secure/lib/libcrypto/man/CMS_compress.3

   1 .\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
   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 turned on, 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 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{
  60 .    if \nF \{
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "CMS_compress 3"
 136 .TH CMS_compress 3 "2015-07-09" "1.0.1p" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 CMS_compress \- create a CMS CompressedData structure
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/cms.h>
 147 \&
 148 \& CMS_ContentInfo *CMS_compress(BIO *in, int comp_nid, unsigned int flags);
 149 .Ve
 150 .SH "DESCRIPTION"
 151 .IX Header "DESCRIPTION"
 152 \&\fICMS_compress()\fR creates and returns a \s-1CMS\s0 CompressedData structure. \fBcomp_nid\fR
 153 is the compression algorithm to use or \fBNID_undef\fR to use the default
 154 algorithm (zlib compression). \fBin\fR is the content to be compressed.
 155 \&\fBflags\fR is an optional set of flags.
 156 .SH "NOTES"
 157 .IX Header "NOTES"
 158 The only currently supported compression algorithm is zlib using the \s-1NID\s0
 159 NID_zlib_compression.
 160 .PP
 161 If zlib support is not compiled into OpenSSL then \fICMS_compress()\fR will return
 162 an error.
 163 .PP
 164 If the \fB\s-1CMS_TEXT\s0\fR flag is set \s-1MIME\s0 headers for type \fBtext/plain\fR are
 165 prepended to the data.
 166 .PP
 167 Normally the supplied content is translated into \s-1MIME\s0 canonical format (as
 168 required by the S/MIME specifications) if \fB\s-1CMS_BINARY\s0\fR is set no translation
 169 occurs. This option should be used if the supplied data is in binary format
 170 otherwise the translation will corrupt it. If \fB\s-1CMS_BINARY\s0\fR is set then
 171 \&\fB\s-1CMS_TEXT\s0\fR is ignored.
 172 .PP
 173 If the \fB\s-1CMS_STREAM\s0\fR flag is set a partial \fBCMS_ContentInfo\fR structure is
 174 returned suitable for streaming I/O: no data is read from the \s-1BIO \s0\fBin\fR.
 175 .PP
 176 The compressed data is included in the CMS_ContentInfo structure, unless
 177 \&\fB\s-1CMS_DETACHED\s0\fR is set in which case it is omitted. This is rarely used in
 178 practice and is not supported by \fISMIME_write_CMS()\fR.
 179 .SH "NOTES"
 180 .IX Header "NOTES"
 181 If the flag \fB\s-1CMS_STREAM\s0\fR is set the returned \fBCMS_ContentInfo\fR structure is
 182 \&\fBnot\fR complete and outputting its contents via a function that does not
 183 properly finalize the \fBCMS_ContentInfo\fR structure will give unpredictable
 184 results.
 185 .PP
 186 Several functions including \fISMIME_write_CMS()\fR, \fIi2d_CMS_bio_stream()\fR,
 187 \&\fIPEM_write_bio_CMS_stream()\fR finalize the structure. Alternatively finalization
 188 can be performed by obtaining the streaming \s-1ASN1 \s0\fB\s-1BIO\s0\fR directly using
 189 \&\fIBIO_new_CMS()\fR.
 190 .PP
 191 Additional compression parameters such as the zlib compression level cannot
 192 currently be set.
 193 .SH "RETURN VALUES"
 194 .IX Header "RETURN VALUES"
 195 \&\fICMS_compress()\fR returns either a CMS_ContentInfo structure or \s-1NULL\s0 if an error
 196 occurred. The error can be obtained from \fIERR_get_error\fR\|(3).
 197 .SH "SEE ALSO"
 198 .IX Header "SEE ALSO"
 199 \&\fIERR_get_error\fR\|(3), \fICMS_uncompress\fR\|(3)
 200 .SH "HISTORY"
 201 .IX Header "HISTORY"
 202 \&\fICMS_compress()\fR was added to OpenSSL 0.9.8
 203 The \fB\s-1CMS_STREAM\s0\fR flag was first supported in OpenSSL 1.0.0.