crypto/external/bsd/openssl/lib/libcrypto/man/CMS_compress.3

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