.Dd $Mdocdate: November 11 2015 $
.Dt CMS_COMPRESS 3
.Os
.Sh NAME
.Nm CMS_compress
.Nd create a CMS CompressedData structure
.Sh SYNOPSIS
.In openssl/cms.h
.Ft CMS_ContentInfo *
.Fo CMS_compress
.Fa "BIO *in"
.Fa "int comp_nid"
.Fa "unsigned int flags"
.Fc
.Sh DESCRIPTION
.Fn CMS_compress
creates and returns a CMS CompressedData structure.
.Fa comp_nid
is the compression algorithm to use or
.Dv NID_undef
to use the default algorithm (zlib compression).
.Fa in
is the content to be compressed.
.Fa flags
is an optional set of flags.
.Sh NOTES
The only currently supported compression algorithm is zlib using the NID
.Dv NID_zlib_compression .
.Pp
If zlib support is not compiled into OpenSSL then
.Fn CMS_compress
will return an error.
.Pp
If the
.Dv CMS_TEXT
flag is set, MIME headers for type
.Sy text/plain
are prepended to the data.
.Pp
Normally the supplied content is translated into MIME canonical format
(as required by the S/MIME specifications); if
.Dv CMS_BINARY
is set, no translation occurs.
This option should be used if the supplied data is in binary format;
otherwise the translation will corrupt it.
If
.Dv CMS_BINARY
is set then
.Dv CMS_TEXT
is ignored.
.Pp
If the
.Dv CMS_STREAM
flag is set a partial
.Vt CMS_ContentInfo
structure is returned suitable for streaming I/O: no data is read from
the
.Vt BIO
.Fa in .
.Pp
The compressed data is included in the
.Vt CMS_ContentInfo
structure, unless
.Dv CMS_DETACHED
is set, in which case it is omitted.
This is rarely used in practice and is not supported by
.Xr SMIME_write_CMS 3 .
.Sh NOTES
If the flag
.Dv CMS_STREAM
is set, the returned
.Vt CMS_ContentInfo
structure is
.Em not
complete and outputting its contents via a function that does not
properly finalize the
.Vt CMS_ContentInfo
structure will give unpredictable results.
.Pp
Several functions including
.Xr SMIME_write_CMS 3 ,
.Xr i2d_CMS_bio_stream 3 ,
.Xr PEM_write_bio_CMS_stream 3
finalize the structure.
Alternatively finalization can be performed by obtaining the streaming
ASN1
.Vt BIO
directly using
.Xr BIO_new_CMS 3 .
.Pp
Additional compression parameters such as the zlib compression level
cannot currently be set.
.Sh RETURN VALUES
.Fn CMS_compress
returns either a
.Vt CMS_ContentInfo
structure or
.Dv NULL
if an error occurred.
The error can be obtained from
.Xr ERR_get_error 3 .
.Sh SEE ALSO
.Xr CMS_uncompress 3 ,
.Xr ERR_get_error 3
.Sh HISTORY
.Fn CMS_compress
was added to OpenSSL 0.9.8.
The
.Dv CMS_STREAM
flag was first supported in OpenSSL 1.0.0.