xref: /openssl/doc/man3/CMS_compress.pod (revision 485d3361)
1=pod
2
3=head1 NAME
4
5CMS_compress - create a CMS CompressedData structure
6
7=head1 SYNOPSIS
8
9 #include <openssl/cms.h>
10
11 CMS_ContentInfo *CMS_compress(BIO *in, int comp_nid, unsigned int flags);
12
13=head1 DESCRIPTION
14
15CMS_compress() creates and returns a CMS CompressedData structure. B<comp_nid>
16is the compression algorithm to use or B<NID_undef> to use the default
17algorithm (zlib compression). B<in> is the content to be compressed.
18B<flags> is an optional set of flags.
19
20The only currently supported compression algorithm is zlib using the NID
21NID_zlib_compression.
22
23If zlib support is not compiled into OpenSSL then CMS_compress() will return
24an error.
25
26If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are
27prepended to the data.
28
29Normally the supplied content is translated into MIME canonical format (as
30required by the S/MIME specifications) if B<CMS_BINARY> is set no translation
31occurs. This option should be used if the supplied data is in binary format
32otherwise the translation will corrupt it. If B<CMS_BINARY> is set then
33B<CMS_TEXT> is ignored.
34
35If the B<CMS_STREAM> flag is set a partial B<CMS_ContentInfo> structure is
36returned suitable for streaming I/O: no data is read from the BIO B<in>.
37
38The compressed data is included in the CMS_ContentInfo structure, unless
39B<CMS_DETACHED> is set in which case it is omitted. This is rarely used in
40practice and is not supported by SMIME_write_CMS().
41
42If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is
43B<not> complete and outputting its contents via a function that does not
44properly finalize the B<CMS_ContentInfo> structure will give unpredictable
45results.
46
47Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(),
48PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization
49can be performed by obtaining the streaming ASN1 B<BIO> directly using
50BIO_new_CMS().
51
52Additional compression parameters such as the zlib compression level cannot
53currently be set.
54
55=head1 RETURN VALUES
56
57CMS_compress() returns either a CMS_ContentInfo structure or NULL if an error
58occurred. The error can be obtained from ERR_get_error(3).
59
60=head1 SEE ALSO
61
62L<ERR_get_error(3)>, L<CMS_uncompress(3)>
63
64=head1 HISTORY
65
66The B<CMS_STREAM> flag was added in OpenSSL 1.0.0.
67
68=head1 COPYRIGHT
69
70Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
71
72Licensed under the Apache License 2.0 (the "License").  You may not use
73this file except in compliance with the License.  You can obtain a copy
74in the file LICENSE in the source distribution or at
75L<https://www.openssl.org/source/license.html>.
76
77=cut
78