doc/man3/CMS_compress.pod

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