Update files for OpenSSL-1.0.0f import.
[dragonfly.git] / secure / lib / libcrypto / man / BIO_new_CMS.3
1 .\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.19)
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 'br\}
42 .\"
43 .\" Escape single quotes in literal strings from groff's Unicode transform.
44 .ie \n(.g .ds Aq \(aq
45 .el       .ds Aq '
46 .\"
47 .\" If the F register is turned on, we'll generate index entries on stderr for
48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
50 .\" output yourself in some meaningful fashion.
51 .ie \nF \{\
52 .    de IX
53 .    tm Index:\\$1\t\\n%\t"\\$2"
54 ..
55 .    nr % 0
56 .    rr F
57 .\}
58 .el \{\
59 .    de IX
60 ..
61 .\}
62 .\"
63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
65 .    \" fudge factors for nroff and troff
66 .if n \{\
67 .    ds #H 0
68 .    ds #V .8m
69 .    ds #F .3m
70 .    ds #[ \f1
71 .    ds #] \fP
72 .\}
73 .if t \{\
74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75 .    ds #V .6m
76 .    ds #F 0
77 .    ds #[ \&
78 .    ds #] \&
79 .\}
80 .    \" simple accents for nroff and troff
81 .if n \{\
82 .    ds ' \&
83 .    ds ` \&
84 .    ds ^ \&
85 .    ds , \&
86 .    ds ~ ~
87 .    ds /
88 .\}
89 .if t \{\
90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
96 .\}
97 .    \" troff and (daisy-wheel) nroff accents
98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105 .ds ae a\h'-(\w'a'u*4/10)'e
106 .ds Ae A\h'-(\w'A'u*4/10)'E
107 .    \" corrections for vroff
108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
110 .    \" for low resolution devices (crt and lpr)
111 .if \n(.H>23 .if \n(.V>19 \
112 \{\
113 .    ds : e
114 .    ds 8 ss
115 .    ds o a
116 .    ds d- d\h'-1'\(ga
117 .    ds D- D\h'-1'\(hy
118 .    ds th \o'bp'
119 .    ds Th \o'LP'
120 .    ds ae ae
121 .    ds Ae AE
122 .\}
123 .rm #[ #] #H #V #F C
124 .\" ========================================================================
125 .\"
126 .IX Title "BIO_new_CMS 3"
127 .TH BIO_new_CMS 3 "2012-01-04" "1.0.0f" "OpenSSL"
128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
129 .\" way too many mistakes in technical documents.
130 .if n .ad l
131 .nh
132 .SH "NAME"
133 .Vb 1
134 \& BIO_new_CMS \- CMS streaming filter BIO
135 .Ve
136 .SH "SYNOPSIS"
137 .IX Header "SYNOPSIS"
138 .Vb 1
139 \& #include <openssl/cms.h>
140 \&
141 \& BIO *BIO_new_CMS(BIO *out, CMS_ContentInfo *cms);
142 .Ve
143 .SH "DESCRIPTION"
144 .IX Header "DESCRIPTION"
145 \&\fIBIO_new_CMS()\fR returns a streaming filter \s-1BIO\s0 chain based on \fBcms\fR. The output
146 of the filter is written to \fBout\fR. Any data written to the chain is
147 automatically translated to a \s-1BER\s0 format \s-1CMS\s0 structure of the appropriate type.
148 .SH "NOTES"
149 .IX Header "NOTES"
150 The chain returned by this function behaves like a standard filter \s-1BIO\s0. It
151 supports non blocking I/O. Content is processed and streamed on the fly and not
152 all held in memory at once: so it is possible to encode very large structures.
153 After all content has been written through the chain \fIBIO_flush()\fR must be called
154 to finalise the structure.
155 .PP
156 The \fB\s-1CMS_STREAM\s0\fR flag must be included in the corresponding \fBflags\fR
157 parameter of the \fBcms\fR creation function.
158 .PP
159 If an application wishes to write additional data to \fBout\fR BIOs should be
160 removed from the chain using \fIBIO_pop()\fR and freed with \fIBIO_free()\fR until \fBout\fR
161 is reached. If no additional data needs to be written \fIBIO_free_all()\fR can be
162 called to free up the whole chain.
163 .PP
164 Any content written through the filter is used verbatim: no canonical
165 translation is performed.
166 .PP
167 It is possible to chain multiple BIOs to, for example, create a triple wrapped
168 signed, enveloped, signed structure. In this case it is the applications
169 responsibility to set the inner content type of any outer CMS_ContentInfo
170 structures.
171 .PP
172 Large numbers of small writes through the chain should be avoided as this will
173 produce an output consisting of lots of \s-1OCTET\s0 \s-1STRING\s0 structures. Prepending
174 a \fIBIO_f_buffer()\fR buffering \s-1BIO\s0 will prevent this.
175 .SH "BUGS"
176 .IX Header "BUGS"
177 There is currently no corresponding inverse \s-1BIO:\s0 i.e. one which can decode
178 a \s-1CMS\s0 structure on the fly.
179 .SH "RETURN VALUES"
180 .IX Header "RETURN VALUES"
181 \&\fIBIO_new_CMS()\fR returns a \s-1BIO\s0 chain when successful or \s-1NULL\s0 if an error
182 occurred. The error can be obtained from \fIERR_get_error\fR\|(3).
183 .SH "SEE ALSO"
184 .IX Header "SEE ALSO"
185 \&\fIERR_get_error\fR\|(3), \fICMS_sign\fR\|(3),
186 \&\fICMS_encrypt\fR\|(3)
187 .SH "HISTORY"
188 .IX Header "HISTORY"
189 \&\fIBIO_new_CMS()\fR was added to OpenSSL 1.0.0