Update files for OpenSSL-1.0.0f import.
[dragonfly.git] / secure / lib / libcrypto / man / BIO_new_CMS.3
CommitLineData
e3261593 1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.19)
01185282
PA
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"
e3261593 127.TH BIO_new_CMS 3 "2012-01-04" "1.0.0f" "OpenSSL"
01185282
PA
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
146of the filter is written to \fBout\fR. Any data written to the chain is
147automatically translated to a \s-1BER\s0 format \s-1CMS\s0 structure of the appropriate type.
148.SH "NOTES"
149.IX Header "NOTES"
150The chain returned by this function behaves like a standard filter \s-1BIO\s0. It
151supports non blocking I/O. Content is processed and streamed on the fly and not
152all held in memory at once: so it is possible to encode very large structures.
153After all content has been written through the chain \fIBIO_flush()\fR must be called
154to finalise the structure.
155.PP
156The \fB\s-1CMS_STREAM\s0\fR flag must be included in the corresponding \fBflags\fR
157parameter of the \fBcms\fR creation function.
158.PP
159If an application wishes to write additional data to \fBout\fR BIOs should be
160removed from the chain using \fIBIO_pop()\fR and freed with \fIBIO_free()\fR until \fBout\fR
161is reached. If no additional data needs to be written \fIBIO_free_all()\fR can be
162called to free up the whole chain.
163.PP
164Any content written through the filter is used verbatim: no canonical
165translation is performed.
166.PP
167It is possible to chain multiple BIOs to, for example, create a triple wrapped
168signed, enveloped, signed structure. In this case it is the applications
169responsibility to set the inner content type of any outer CMS_ContentInfo
170structures.
171.PP
172Large numbers of small writes through the chain should be avoided as this will
173produce an output consisting of lots of \s-1OCTET\s0 \s-1STRING\s0 structures. Prepending
174a \fIBIO_f_buffer()\fR buffering \s-1BIO\s0 will prevent this.
175.SH "BUGS"
176.IX Header "BUGS"
177There is currently no corresponding inverse \s-1BIO:\s0 i.e. one which can decode
178a \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
182occurred. 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