OLD | NEW |
(Empty) | |
| 1 =pod |
| 2 |
| 3 =head1 NAME |
| 4 |
| 5 BIO_new_CMS - CMS streaming filter BIO |
| 6 |
| 7 =head1 SYNOPSIS |
| 8 |
| 9 #include <openssl/cms.h> |
| 10 |
| 11 BIO *BIO_new_CMS(BIO *out, CMS_ContentInfo *cms); |
| 12 |
| 13 =head1 DESCRIPTION |
| 14 |
| 15 BIO_new_CMS() returns a streaming filter BIO chain based on B<cms>. The output |
| 16 of the filter is written to B<out>. Any data written to the chain is |
| 17 automatically translated to a BER format CMS structure of the appropriate type. |
| 18 |
| 19 =head1 NOTES |
| 20 |
| 21 The chain returned by this function behaves like a standard filter BIO. It |
| 22 supports non blocking I/O. Content is processed and streamed on the fly and not |
| 23 all held in memory at once: so it is possible to encode very large structures. |
| 24 After all content has been written through the chain BIO_flush() must be called |
| 25 to finalise the structure. |
| 26 |
| 27 The B<CMS_STREAM> flag must be included in the corresponding B<flags> |
| 28 parameter of the B<cms> creation function. |
| 29 |
| 30 If an application wishes to write additional data to B<out> BIOs should be |
| 31 removed from the chain using BIO_pop() and freed with BIO_free() until B<out> |
| 32 is reached. If no additional data needs to be written BIO_free_all() can be |
| 33 called to free up the whole chain. |
| 34 |
| 35 Any content written through the filter is used verbatim: no canonical |
| 36 translation is performed. |
| 37 |
| 38 It is possible to chain multiple BIOs to, for example, create a triple wrapped |
| 39 signed, enveloped, signed structure. In this case it is the applications |
| 40 responsibility to set the inner content type of any outer CMS_ContentInfo |
| 41 structures. |
| 42 |
| 43 Large numbers of small writes through the chain should be avoided as this will |
| 44 produce an output consisting of lots of OCTET STRING structures. Prepending |
| 45 a BIO_f_buffer() buffering BIO will prevent this. |
| 46 |
| 47 =head1 BUGS |
| 48 |
| 49 There is currently no corresponding inverse BIO: i.e. one which can decode |
| 50 a CMS structure on the fly. |
| 51 |
| 52 =head1 RETURN VALUES |
| 53 |
| 54 BIO_new_CMS() returns a BIO chain when successful or NULL if an error |
| 55 occurred. The error can be obtained from ERR_get_error(3). |
| 56 |
| 57 =head1 SEE ALSO |
| 58 |
| 59 L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, |
| 60 L<CMS_encrypt(3)|CMS_encrypt(3)> |
| 61 |
| 62 =head1 HISTORY |
| 63 |
| 64 BIO_new_CMS() was added to OpenSSL 1.0.0 |
| 65 |
| 66 =cut |
OLD | NEW |