bedb4432419143dd0a48575ce651e4578daef17b
[dragonfly.git] / 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-06-11" "1.0.1n" "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.