| 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)>, L<CMS_sign(3)>,
|
|---|
| 60 | L<CMS_encrypt(3)>
|
|---|
| 61 |
|
|---|
| 62 | =head1 HISTORY
|
|---|
| 63 |
|
|---|
| 64 | The BIO_new_CMS() function was added in OpenSSL 1.0.0.
|
|---|
| 65 |
|
|---|
| 66 | =head1 COPYRIGHT
|
|---|
| 67 |
|
|---|
| 68 | Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 69 |
|
|---|
| 70 | Licensed under the OpenSSL license (the "License"). You may not use
|
|---|
| 71 | this file except in compliance with the License. You can obtain a copy
|
|---|
| 72 | in the file LICENSE in the source distribution or at
|
|---|
| 73 | L<https://www.openssl.org/source/license.html>.
|
|---|
| 74 |
|
|---|
| 75 | =cut
|
|---|
