]>
Commit | Line | Data |
---|---|---|
287df2fe DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
1bc74519 | 5 | BIO_new_CMS - CMS streaming filter BIO |
287df2fe DSH |
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 | |
38d3a738 DSH |
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. | |
287df2fe DSH |
18 | |
19 | =head1 NOTES | |
20 | ||
38d3a738 DSH |
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 | |
287df2fe | 23 | all held in memory at once: so it is possible to encode very large structures. |
38d3a738 | 24 | After all content has been written through the chain BIO_flush() must be called |
287df2fe DSH |
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 | ||
38d3a738 DSH |
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. | |
287df2fe | 34 | |
38d3a738 | 35 | Any content written through the filter is used verbatim: no canonical |
287df2fe DSH |
36 | translation is performed. |
37 | ||
38d3a738 DSH |
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 | |
287df2fe DSH |
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 | ||
9b86974e RS |
59 | L<ERR_get_error(3)>, L<CMS_sign(3)>, |
60 | L<CMS_encrypt(3)> | |
287df2fe DSH |
61 | |
62 | =head1 HISTORY | |
63 | ||
fc5ecadd | 64 | The BIO_new_CMS() function was added in OpenSSL 1.0.0. |
287df2fe | 65 | |
e2f92610 RS |
66 | =head1 COPYRIGHT |
67 | ||
68 | Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. | |
69 | ||
4746f25a | 70 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
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 |