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