#use wml::openssl-macros area=docs page=BIO_new_CMS

<title>Documents, BIO_new_CMS(3)</title>

<h1>BIO_new_CMS(3)</h1>

#use wml::imp::generic

{:
## What's this? [[s|(<STRONG>[^<].+?)</A>(</STRONG><DD>)|$1$2|sg]]
[[s|<P>\s+<P>|<P>|sg]]
[[s|<P>\s+</|</|sg]]
[[s|<DD>\s*<DT>|<DD>&nbsp;<DT>|sg]]
[[s|<DD>\s*</DL>|<DD>&nbsp;</DL>|sg]]
[[s|\[|&#91;|sg]]
[[s|\]|&#93;|sg]]

<!-- INDEX BEGIN -->

<UL>

	<LI><A HREF="#NAME">NAME</A>
	<LI><A HREF="#SYNOPSIS">SYNOPSIS</A>
	<LI><A HREF="#DESCRIPTION">DESCRIPTION</A>
	<LI><A HREF="#NOTES">NOTES</A>
	<LI><A HREF="#BUGS">BUGS</A>
	<LI><A HREF="#RETURN_VALUES">RETURN VALUES</A>
	<LI><A HREF="#SEE_ALSO">SEE ALSO</A>
	<LI><A HREF="#HISTORY">HISTORY</A>
</UL>
<!-- INDEX END -->

<HR>
<P>
<HR>
<H1><A NAME="NAME">NAME</A></H1>
<PRE> BIO_new_CMS - CMS streaming filter BIO
</PRE>
<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
<PRE> #include &lt;openssl/cms.h&gt;
</PRE>
<PRE> BIO *BIO_new_CMS(BIO *out, CMS_ContentInfo *cms);
</PRE>
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
<CODE>BIO_new_CMS()</CODE> returns a streaming filter BIO chain based on <STRONG>cms</STRONG>. The output of the filter is written to <STRONG>out</STRONG>. Any data written to the chain is automatically translated to a BER format
CMS structure of the appropriate type.

</P>
<P>
<HR>
<H1><A NAME="NOTES">NOTES</A></H1>
<P>
The chain returned by this function behaves like a standard filter BIO. It
supports non blocking I/O. Content is processed and streamed on the fly and
not all held in memory at once: so it is possible to encode very large
structures. After all content has been written through the chain
<CODE>BIO_flush()</CODE> must be called to finalise the structure.

</P>
<P>
The <STRONG>CMS_STREAM</STRONG> flag must be included in the corresponding <STRONG>flags</STRONG>
parameter of the <STRONG>cms</STRONG> creation function.

</P>
<P>
If an application wishes to write additional data to <STRONG>out</STRONG> BIOs should be removed from the chain using <CODE>BIO_pop()</CODE> and
freed with <CODE>BIO_free()</CODE> until <STRONG>out</STRONG>
is reached. If no additional data needs to be written
<CODE>BIO_free_all()</CODE> can be called to free up the whole chain.

</P>
<P>
Any content written through the filter is used verbatim: no canonical
translation is performed.

</P>
<P>
It is possible to chain multiple BIOs to, for example, create a triple
wrapped signed, enveloped, signed structure. In this case it is the
applications responsibility to set the inner content type of any outer
CMS_ContentInfo structures.

</P>
<P>
Large numbers of small writes through the chain should be avoided as this
will produce an output consisting of lots of OCTET STRING structures.
Prepending a <CODE>BIO_f_buffer()</CODE> buffering BIO will prevent this.

</P>
<P>
<HR>
<H1><A NAME="BUGS">BUGS</A></H1>
<P>
There is currently no corresponding inverse BIO: i.e. one which can decode
a CMS structure on the fly.

</P>
<P>
<HR>
<H1><A NAME="RETURN_VALUES">RETURN VALUES</A></H1>
<P>
<CODE>BIO_new_CMS()</CODE> returns a BIO chain when successful or NULL if
an error occurred. The error can be obtained from
<CODE>ERR_get_error(3).</CODE>

</P>
<P>
<HR>
<H1><A NAME="SEE_ALSO">SEE ALSO</A></H1>
<P>
<A HREF="../crypto/ERR_get_error.html#">ERR_get_error(3)</A>, <A HREF="../crypto/CMS_sign.html#">CMS_sign(3)</A>,
<A HREF="../crypto/CMS_encrypt.html#">CMS_encrypt(3)</A>



</P>
<P>
<HR>
<H1><A NAME="HISTORY">HISTORY</A></H1>
<P>
<CODE>BIO_new_CMS()</CODE> was added to OpenSSL 1.0.0

</P>
:}