crypto/external/bsd/openssl/lib/libcrypto/man/CMS_decrypt.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 "CMS_decrypt 3"
 137 .TH CMS_decrypt 3 "2008-04-11" "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 \& CMS_decrypt \- decrypt content from a CMS envelopedData structure
 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 \& int CMS_decrypt(CMS_ContentInfo *cms, EVP_PKEY *pkey, X509 *cert, BIO *dcont, BIO *out, unsigned int flags);
 154 .Ve
 155 .SH "DESCRIPTION"
 156 .IX Header "DESCRIPTION"
 157 \&\fICMS_decrypt()\fR extracts and decrypts the content from a \s-1CMS\s0 EnvelopedData
 158 structure. \fBpkey\fR is the private key of the recipient, \fBcert\fR is the
 159 recipient's certificate, \fBout\fR is a \s-1BIO\s0 to write the content to and
 160 \&\fBflags\fR is an optional set of flags.
 161 .PP
 162 The \fBdcont\fR parameter is used in the rare case where the encrypted content
 163 is detached. It will normally be set to \s-1NULL\s0.
 164 .SH "NOTES"
 165 .IX Header "NOTES"
 166 \&\fIOpenSSL_add_all_algorithms()\fR (or equivalent) should be called before using this
 167 function or errors about unknown algorithms will occur.
 168 .PP
 169 Although the recipients certificate is not needed to decrypt the data it is
 170 needed to locate the appropriate (of possible several) recipients in the \s-1CMS\s0
 171 structure. If \fBcert\fR is set to \s-1NULL\s0 all possible recipients are tried.
 172 .PP
 173 It is possible to determine the correct recipient key by other means (for
 174 example looking them up in a database) and setting them in the \s-1CMS\s0 structure
 175 in advance using the \s-1CMS\s0 utility functions such as \fICMS_set1_pkey()\fR. In this
 176 case both \fBcert\fR and \fBpkey\fR should be set to \s-1NULL\s0.
 177 .PP
 178 To process KEKRecipientInfo types \fICMS_set1_key()\fR or \fICMS_RecipientInfo_set0_key()\fR
 179 and \fICMS_ReceipientInfo_decrypt()\fR should be called before \fICMS_decrypt()\fR and
 180 \&\fBcert\fR and \fBpkey\fR set to \s-1NULL\s0.
 181 .PP
 182 The following flags can be passed in the \fBflags\fR parameter.
 183 .PP
 184 If the \fB\s-1CMS_TEXT\s0\fR flag is set \s-1MIME\s0 headers for type \fBtext/plain\fR are deleted
 185 from the content. If the content is not of type \fBtext/plain\fR then an error is
 186 returned.
 187 .SH "RETURN VALUES"
 188 .IX Header "RETURN VALUES"
 189 \&\fICMS_decrypt()\fR returns either 1 for success or 0 for failure.
 190 The error can be obtained from \fIERR_get_error\fR\|(3)
 191 .SH "BUGS"
 192 .IX Header "BUGS"
 193 The lack of single pass processing and the need to hold all data in memory as
 194 mentioned in \fICMS_verify()\fR also applies to \fICMS_decrypt()\fR.
 195 .SH "SEE ALSO"
 196 .IX Header "SEE ALSO"
 197 \&\fIERR_get_error\fR\|(3), \fICMS_encrypt\fR\|(3)
 198 .SH "HISTORY"
 199 .IX Header "HISTORY"
 200 \&\fICMS_decrypt()\fR was added to OpenSSL 0.9.8