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

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