secure/lib/libcrypto/man/CMS_compress.3

   1 .\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.35)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "CMS_compress 3"
 132 .TH CMS_compress 3 "2017-11-02" "1.0.2m" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 CMS_compress \- create a CMS CompressedData structure
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/cms.h>
 143 \&
 144 \& CMS_ContentInfo *CMS_compress(BIO *in, int comp_nid, unsigned int flags);
 145 .Ve
 146 .SH "DESCRIPTION"
 147 .IX Header "DESCRIPTION"
 148 \&\fICMS_compress()\fR creates and returns a \s-1CMS\s0 CompressedData structure. \fBcomp_nid\fR
 149 is the compression algorithm to use or \fBNID_undef\fR to use the default
 150 algorithm (zlib compression). \fBin\fR is the content to be compressed.
 151 \&\fBflags\fR is an optional set of flags.
 152 .SH "NOTES"
 153 .IX Header "NOTES"
 154 The only currently supported compression algorithm is zlib using the \s-1NID\s0
 155 NID_zlib_compression.
 156 .PP
 157 If zlib support is not compiled into OpenSSL then \fICMS_compress()\fR will return
 158 an error.
 159 .PP
 160 If the \fB\s-1CMS_TEXT\s0\fR flag is set \s-1MIME\s0 headers for type \fBtext/plain\fR are
 161 prepended to the data.
 162 .PP
 163 Normally the supplied content is translated into \s-1MIME\s0 canonical format (as
 164 required by the S/MIME specifications) if \fB\s-1CMS_BINARY\s0\fR is set no translation
 165 occurs. This option should be used if the supplied data is in binary format
 166 otherwise the translation will corrupt it. If \fB\s-1CMS_BINARY\s0\fR is set then
 167 \&\fB\s-1CMS_TEXT\s0\fR is ignored.
 168 .PP
 169 If the \fB\s-1CMS_STREAM\s0\fR flag is set a partial \fBCMS_ContentInfo\fR structure is
 170 returned suitable for streaming I/O: no data is read from the \s-1BIO \s0\fBin\fR.
 171 .PP
 172 The compressed data is included in the CMS_ContentInfo structure, unless
 173 \&\fB\s-1CMS_DETACHED\s0\fR is set in which case it is omitted. This is rarely used in
 174 practice and is not supported by \fISMIME_write_CMS()\fR.
 175 .SH "NOTES"
 176 .IX Header "NOTES"
 177 If the flag \fB\s-1CMS_STREAM\s0\fR is set the returned \fBCMS_ContentInfo\fR structure is
 178 \&\fBnot\fR complete and outputting its contents via a function that does not
 179 properly finalize the \fBCMS_ContentInfo\fR structure will give unpredictable
 180 results.
 181 .PP
 182 Several functions including \fISMIME_write_CMS()\fR, \fIi2d_CMS_bio_stream()\fR,
 183 \&\fIPEM_write_bio_CMS_stream()\fR finalize the structure. Alternatively finalization
 184 can be performed by obtaining the streaming \s-1ASN1 \s0\fB\s-1BIO\s0\fR directly using
 185 \&\fIBIO_new_CMS()\fR.
 186 .PP
 187 Additional compression parameters such as the zlib compression level cannot
 188 currently be set.
 189 .SH "RETURN VALUES"
 190 .IX Header "RETURN VALUES"
 191 \&\fICMS_compress()\fR returns either a CMS_ContentInfo structure or \s-1NULL\s0 if an error
 192 occurred. The error can be obtained from \fIERR_get_error\fR\|(3).
 193 .SH "SEE ALSO"
 194 .IX Header "SEE ALSO"
 195 \&\fIERR_get_error\fR\|(3), \fICMS_uncompress\fR\|(3)
 196 .SH "HISTORY"
 197 .IX Header "HISTORY"
 198 \&\fICMS_compress()\fR was added to OpenSSL 0.9.8
 199 The \fB\s-1CMS_STREAM\s0\fR flag was first supported in OpenSSL 1.0.0.