| blob | 41d8eec5f32c1b89ea0c5d5f1b97fe061063908f |
1 .\" $NetBSD: CMS_get0_RecipientInfos.3,v 1.14 2015/06/12 17:01:13 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 "CMS_get0_RecipientInfos 3"
138 .TH CMS_get0_RecipientInfos 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 \& CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_signer_id,CMS_RecipientInfo_ktri_cert_cmp, CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, CMS_RecipientInfo_decrypt \- CMS envelopedData RecipientInfo routines
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 \& STACK_OF(CMS_RecipientInfo) *CMS_get0_RecipientInfos(CMS_ContentInfo *cms);
155 \& int CMS_RecipientInfo_type(CMS_RecipientInfo *ri);
156 \&
157 \& int CMS_RecipientInfo_ktri_get0_signer_id(CMS_RecipientInfo *ri, ASN1_OCTET_STRING **keyid, X509_NAME **issuer, ASN1_INTEGER **sno);
158 \& int CMS_RecipientInfo_ktri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert);
159 \& int CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pkey);
160 \&
161 \& int CMS_RecipientInfo_kekri_get0_id(CMS_RecipientInfo *ri, X509_ALGOR **palg, ASN1_OCTET_STRING **pid, ASN1_GENERALIZEDTIME **pdate, ASN1_OBJECT **potherid, ASN1_TYPE **pothertype);
162 \& int CMS_RecipientInfo_kekri_id_cmp(CMS_RecipientInfo *ri, const unsigned char *id, size_t idlen);
163 \& int CMS_RecipientInfo_set0_key(CMS_RecipientInfo *ri, unsigned char *key, size_t keylen);
164 \&
165 \& int CMS_RecipientInfo_decrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
166 .Ve
167 .SH "DESCRIPTION"
168 .IX Header "DESCRIPTION"
169 The function \fICMS_get0_RecipientInfos()\fR returns all the CMS_RecipientInfo
170 structures associated with a \s-1CMS\s0 EnvelopedData structure.
171 .PP
172 \&\fICMS_RecipientInfo_type()\fR returns the type of CMS_RecipientInfo structure \fBri\fR.
173 It will currently return \s-1CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE,
174 CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS,\s0 or \s-1CMS_RECIPINFO_OTHER.\s0
175 .PP
176 \&\fICMS_RecipientInfo_ktri_get0_signer_id()\fR retrieves the certificate recipient
177 identifier associated with a specific CMS_RecipientInfo structure \fBri\fR, which
178 must be of type \s-1CMS_RECIPINFO_TRANS.\s0 Either the keyidentifier will be set in
179 \&\fBkeyid\fR or \fBboth\fR issuer name and serial number in \fBissuer\fR and \fBsno\fR.
180 .PP
181 \&\fICMS_RecipientInfo_ktri_cert_cmp()\fR compares the certificate \fBcert\fR against the
182 CMS_RecipientInfo structure \fBri\fR, which must be of type \s-1CMS_RECIPINFO_TRANS.\s0
183 It returns zero if the comparison is successful and non zero if not.
184 .PP
185 \&\fICMS_RecipientInfo_set0_pkey()\fR associates the private key \fBpkey\fR with
186 the CMS_RecipientInfo structure \fBri\fR, which must be of type
187 \&\s-1CMS_RECIPINFO_TRANS.\s0
188 .PP
189 \&\fICMS_RecipientInfo_kekri_get0_id()\fR retrieves the key information from the
190 CMS_RecipientInfo structure \fBri\fR which must be of type \s-1CMS_RECIPINFO_KEK. \s0 Any
191 of the remaining parameters can be \s-1NULL\s0 if the application is not interested in
192 the value of a field. Where a field is optional and absent \s-1NULL\s0 will be written
193 to the corresponding parameter. The keyEncryptionAlgorithm field is written to
194 \&\fBpalg\fR, the \fBkeyIdentifier\fR field is written to \fBpid\fR, the \fBdate\fR field if
195 present is written to \fBpdate\fR, if the \fBother\fR field is present the components
196 \&\fBkeyAttrId\fR and \fBkeyAttr\fR are written to parameters \fBpotherid\fR and
197 \&\fBpothertype\fR.
198 .PP
199 \&\fICMS_RecipientInfo_kekri_id_cmp()\fR compares the \s-1ID\s0 in the \fBid\fR and \fBidlen\fR
200 parameters against the \fBkeyIdentifier\fR CMS_RecipientInfo structure \fBri\fR,
201 which must be of type \s-1CMS_RECIPINFO_KEK. \s0 It returns zero if the comparison is
202 successful and non zero if not.
203 .PP
204 \&\fICMS_RecipientInfo_set0_key()\fR associates the symmetric key \fBkey\fR of length
205 \&\fBkeylen\fR with the CMS_RecipientInfo structure \fBri\fR, which must be of type
206 \&\s-1CMS_RECIPINFO_KEK.\s0
207 .PP
208 \&\fICMS_RecipientInfo_decrypt()\fR attempts to decrypt CMS_RecipientInfo structure
209 \&\fBri\fR in structure \fBcms\fR. A key must have been associated with the structure
210 first.
211 .SH "NOTES"
212 .IX Header "NOTES"
213 The main purpose of these functions is to enable an application to lookup
214 recipient keys using any appropriate technique when the simpler method
215 of \fICMS_decrypt()\fR is not appropriate.
216 .PP
217 In typical usage and application will retrieve all CMS_RecipientInfo structures
218 using \fICMS_get0_RecipientInfos()\fR and check the type of each using
219 \&\fICMS_RecpientInfo_type()\fR. Depending on the type the CMS_RecipientInfo structure
220 can be ignored or its key identifier data retrieved using an appropriate
221 function. Then if the corresponding secret or private key can be obtained by
222 any appropriate means it can then associated with the structure and
223 \&\fICMS_RecpientInfo_decrypt()\fR called. If successful \fICMS_decrypt()\fR can be called
224 with a \s-1NULL\s0 key to decrypt the enveloped content.
225 .SH "RETURN VALUES"
226 .IX Header "RETURN VALUES"
227 \&\fICMS_get0_RecipientInfos()\fR returns all CMS_RecipientInfo structures, or \s-1NULL\s0 if
228 an error occurs.
229 .PP
230 \&\fICMS_RecipientInfo_ktri_get0_signer_id()\fR, \fICMS_RecipientInfo_set0_pkey()\fR,
231 \&\fICMS_RecipientInfo_kekri_get0_id()\fR, \fICMS_RecipientInfo_set0_key()\fR and
232 \&\fICMS_RecipientInfo_decrypt()\fR return 1 for success or 0 if an error occurs.
233 .PP
234 \&\fICMS_RecipientInfo_ktri_cert_cmp()\fR and \fICMS_RecipientInfo_kekri_cmp()\fR return 0
235 for a successful comparison and non zero otherwise.
236 .PP
237 Any error can be obtained from \fIERR_get_error\fR\|(3).
238 .SH "SEE ALSO"
239 .IX Header "SEE ALSO"
240 \&\fIERR_get_error\fR\|(3), \fICMS_decrypt\fR\|(3)
241 .SH "HISTORY"
242 .IX Header "HISTORY"
243 These functions were first was added to OpenSSL 0.9.8