.Dd $Mdocdate: September 9 2015 $
.Dt BIO_NEW_CMS 3
.Os
.Sh NAME
.Nm BIO_new_CMS
.Nd CMS streaming filter BIO
.Sh SYNOPSIS
.In openssl/cms.h
.Ft BIO *
.Fo BIO_new_CMS
.Fa "BIO *out"
.Fa "CMS_ContentInfo *cms"
.Fc
.Sh DESCRIPTION
.Fn BIO_new_CMS
returns a streaming filter BIO chain based on
.Fa cms .
The output of the filter is written to
.Fa out .
Any data written to the chain is automatically translated
to a BER format CMS structure of the appropriate type.
.Sh RETURN VALUES
.Fn BIO_new_CMS
returns a BIO chain when successful or
.Dv NULL
if an error occurred.
The error can be obtained from
.Xr ERR_get_error 3 .
.Sh NOTES
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
.Xr BIO_flush 3
must be called to finalise the structure.
.Pp
The
.Dv CMS_STREAM
flag must be included in the corresponding
.Fa flags
parameter of the
.Fa cms
creation function.
.Pp
If an application wishes to write additional data to
.Fa out ,
BIOs should be removed from the chain using
.Xr BIO_pop 3
and freed with
.Xr BIO_free 3
until
.Fa out
is reached.
If no additional data needs to be written,
.Xr BIO_free_all 3
can be called to free up the whole chain.
.Pp
Any content written through the filter is used verbatim:
no canonical translation is performed.
.Pp
It is possible to chain multiple BIOs to, for example,
create a triple wrapped signed, enveloped, signed structure.
In this case it is the application's responsibility
to set the inner content type of any outer
.Vt CMS_ContentInfo
structures.
.Pp
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
.Xr BIO_f_buffer 3
buffering BIO will prevent this.
.Sh SEE ALSO
.Xr CMS_encrypt 3 ,
.Xr CMS_sign 3 ,
.Xr ERR_get_error 3
.Sh HISTORY
.Fn BIO_new_CMS
was added to OpenSSL 1.0.0.
.Sh BUGS
There is currently no corresponding inverse BIO
which can decode a CMS structure on the fly.