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

   1 .\"     $NetBSD: SMIME_read_CMS.3,v 1.14 2015/06/12 17:01:14 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 "SMIME_read_CMS 3"
 138 .TH SMIME_read_CMS 3 "2009-07-19" "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 .Vb 1
 145 \& SMIME_read_CMS \- parse S/MIME message.
 146 .Ve
 147 .SH "LIBRARY"
 148 libcrypto, -lcrypto
 149 .SH "SYNOPSIS"
 150 .IX Header "SYNOPSIS"
 151 .Vb 1
 152 \& #include <openssl/cms.h>
 153 \&
 154 \& CMS_ContentInfo *SMIME_read_CMS(BIO *in, BIO **bcont);
 155 .Ve
 156 .SH "DESCRIPTION"
 157 .IX Header "DESCRIPTION"
 158 \&\fISMIME_read_CMS()\fR parses a message in S/MIME format.
 159 .PP
 160 \&\fBin\fR is a \s-1BIO\s0 to read the message from.
 161 .PP
 162 If cleartext signing is used then the content is saved in a memory bio which is
 163 written to \fB*bcont\fR, otherwise \fB*bcont\fR is set to \s-1NULL.\s0
 164 .PP
 165 The parsed CMS_ContentInfo structure is returned or \s-1NULL\s0 if an
 166 error occurred.
 167 .SH "NOTES"
 168 .IX Header "NOTES"
 169 If \fB*bcont\fR is not \s-1NULL\s0 then the message is clear text signed. \fB*bcont\fR can
 170 then be passed to \fICMS_verify()\fR with the \fB\s-1CMS_DETACHED\s0\fR flag set.
 171 .PP
 172 Otherwise the type of the returned structure can be determined
 173 using \fICMS_get0_type()\fR.
 174 .PP
 175 To support future functionality if \fBbcont\fR is not \s-1NULL \s0\fB*bcont\fR should be
 176 initialized to \s-1NULL.\s0 For example:
 177 .PP
 178 .Vb 2
 179 \& BIO *cont = NULL;
 180 \& CMS_ContentInfo *cms;
 181 \&
 182 \& cms = SMIME_read_CMS(in, &cont);
 183 .Ve
 184 .SH "BUGS"
 185 .IX Header "BUGS"
 186 The \s-1MIME\s0 parser used by \fISMIME_read_CMS()\fR is somewhat primitive.  While it will
 187 handle most S/MIME messages more complex compound formats may not work.
 188 .PP
 189 The parser assumes that the CMS_ContentInfo structure is always base64 encoded
 190 and will not handle the case where it is in binary format or uses quoted
 191 printable format.
 192 .PP
 193 The use of a memory \s-1BIO\s0 to hold the signed content limits the size of message
 194 which can be processed due to memory restraints: a streaming single pass option
 195 should be available.
 196 .SH "RETURN VALUES"
 197 .IX Header "RETURN VALUES"
 198 \&\fISMIME_read_CMS()\fR returns a valid \fBCMS_ContentInfo\fR structure or \fB\s-1NULL\s0\fR
 199 if an error occurred. The error can be obtained from \fIERR_get_error\fR\|(3).
 200 .SH "SEE ALSO"
 201 .IX Header "SEE ALSO"
 202 \&\fIERR_get_error\fR\|(3), \fICMS_type\fR\|(3)
 203 \&\fISMIME_read_CMS\fR\|(3), \fICMS_sign\fR\|(3),
 204 \&\fICMS_verify\fR\|(3), \fICMS_encrypt\fR\|(3)
 205 \&\fICMS_decrypt\fR\|(3)
 206 .SH "HISTORY"
 207 .IX Header "HISTORY"
 208 \&\fISMIME_read_CMS()\fR was added to OpenSSL 0.9.8