1.\" $OpenBSD: CMS_get0_RecipientInfos.3,v 1.7 2019/11/02 15:39:46 schwarze Exp $
2.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100
3.\"
4.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
5.\" Copyright (c) 2008, 2013 The OpenSSL Project.  All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\"
11.\" 1. Redistributions of source code must retain the above copyright
12.\"    notice, this list of conditions and the following disclaimer.
13.\"
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in
16.\"    the documentation and/or other materials provided with the
17.\"    distribution.
18.\"
19.\" 3. All advertising materials mentioning features or use of this
20.\"    software must display the following acknowledgment:
21.\"    "This product includes software developed by the OpenSSL Project
22.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
23.\"
24.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
25.\"    endorse or promote products derived from this software without
26.\"    prior written permission. For written permission, please contact
27.\"    openssl-core@openssl.org.
28.\"
29.\" 5. Products derived from this software may not be called "OpenSSL"
30.\"    nor may "OpenSSL" appear in their names without prior written
31.\"    permission of the OpenSSL Project.
32.\"
33.\" 6. Redistributions of any form whatsoever must retain the following
34.\"    acknowledgment:
35.\"    "This product includes software developed by the OpenSSL Project
36.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
37.\"
38.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
39.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
40.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
41.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
42.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
43.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
44.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
45.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
47.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49.\" OF THE POSSIBILITY OF SUCH DAMAGE.
50.\"
51.Dd $Mdocdate: November 2 2019 $
52.Dt CMS_GET0_RECIPIENTINFOS 3
53.Os
54.Sh NAME
55.Nm CMS_get0_RecipientInfos ,
56.Nm CMS_RecipientInfo_type ,
57.Nm CMS_RecipientInfo_ktri_get0_signer_id ,
58.Nm CMS_RecipientInfo_ktri_cert_cmp ,
59.Nm CMS_RecipientInfo_set0_pkey ,
60.Nm CMS_RecipientInfo_kekri_get0_id ,
61.Nm CMS_RecipientInfo_kekri_id_cmp ,
62.Nm CMS_RecipientInfo_set0_key ,
63.Nm CMS_RecipientInfo_decrypt ,
64.Nm CMS_RecipientInfo_encrypt
65.Nd CMS EnvelopedData RecipientInfo routines
66.Sh SYNOPSIS
67.In openssl/cms.h
68.Ft STACK_OF(CMS_RecipientInfo) *
69.Fo CMS_get0_RecipientInfos
70.Fa "CMS_ContentInfo *cms"
71.Fc
72.Ft int
73.Fo CMS_RecipientInfo_type
74.Fa "CMS_RecipientInfo *ri"
75.Fc
76.Ft int
77.Fo CMS_RecipientInfo_ktri_get0_signer_id
78.Fa "CMS_RecipientInfo *ri"
79.Fa "ASN1_OCTET_STRING **keyid"
80.Fa "X509_NAME **issuer"
81.Fa "ASN1_INTEGER **sno"
82.Fc
83.Ft int
84.Fo CMS_RecipientInfo_ktri_cert_cmp
85.Fa "CMS_RecipientInfo *ri"
86.Fa "X509 *certificate"
87.Fc
88.Ft int
89.Fo CMS_RecipientInfo_set0_pkey
90.Fa "CMS_RecipientInfo *ri"
91.Fa "EVP_PKEY *pkey"
92.Fc
93.Ft int
94.Fo CMS_RecipientInfo_kekri_get0_id
95.Fa "CMS_RecipientInfo *ri"
96.Fa "X509_ALGOR **palg"
97.Fa "ASN1_OCTET_STRING **pid"
98.Fa "ASN1_GENERALIZEDTIME **pdate"
99.Fa "ASN1_OBJECT **potherid"
100.Fa "ASN1_TYPE **pothertype"
101.Fc
102.Ft int
103.Fo CMS_RecipientInfo_kekri_id_cmp
104.Fa "CMS_RecipientInfo *ri"
105.Fa "const unsigned char *id"
106.Fa "size_t idlen"
107.Fc
108.Ft int
109.Fo CMS_RecipientInfo_set0_key
110.Fa "CMS_RecipientInfo *ri"
111.Fa "unsigned char *key"
112.Fa "size_t keylen"
113.Fc
114.Ft int
115.Fo CMS_RecipientInfo_decrypt
116.Fa "CMS_ContentInfo *cms"
117.Fa "CMS_RecipientInfo *ri"
118.Fc
119.Ft int
120.Fo CMS_RecipientInfo_encrypt
121.Fa "CMS_ContentInfo *cms"
122.Fa "CMS_RecipientInfo *ri"
123.Fc
124.Sh DESCRIPTION
125.Fn CMS_get0_RecipientInfos
126returns all the
127.Vt RecipientInfo
128structures associated with the
129.Vt EnvelopedData
130structure
131.Fa cms .
132.Pp
133.Fn CMS_RecipientInfo_type
134returns the type of
135.Fa ri :
136.Bl -column CMS_RECIPINFO_TRANS for -compact
137.It Dv CMS_RECIPINFO_TRANS Ta for Ta Vt KeyTransRecipientInfo ,
138.It Dv CMS_RECIPINFO_AGREE Ta for Ta Vt KeyAgreeRecipientInfo ,
139.It Dv CMS_RECIPINFO_KEK   Ta for Ta Vt KEKRecipientInfo ,
140.It Dv CMS_RECIPINFO_PASS  Ta for Ta Vt PasswordRecipientinfo , No or
141.It Dv CMS_RECIPINFO_OTHER Ta for Ta Vt OtherRecipientInfo .
142.El
143.Pp
144.Fn CMS_RecipientInfo_ktri_get0_signer_id
145retrieves the certificate
146.Vt RecipientIdentifier
147associated with the
148.Vt KeyTransRecipientInfo
149structure
150.Fa ri .
151Either the
152.Vt SubjectKeyIdentifier
153will be set in
154.Fa keyid
155or both issuer name and serial number in
156.Fa issuer
157and
158.Fa sno .
159.Pp
160.Fn CMS_RecipientInfo_ktri_cert_cmp
161compares the
162.Fa certificate
163against the
164.Vt KeyTransRecipientInfo
165structure
166.Fa ri .
167.Pp
168.Fn CMS_RecipientInfo_set0_pkey
169associates the private key
170.Fa pkey
171with the
172.Vt KeyTransRecipientInfo
173structure
174.Fa ri .
175.Pp
176.Fn CMS_RecipientInfo_kekri_get0_id
177retrieves the key information from the
178.Vt KEKRecipientInfo
179structure
180.Fa ri .
181Fields are copied out as follows:
182.Bl -column keyEncryptionAlgorithm to -compact
183.It Fa keyEncryptionAlgorithm Ta to Ta Pf * Fa palg ,
184.It Fa keyIdentifier          Ta to Ta Pf * Fa pid ,
185.It Fa date                   Ta to Ta Pf * Fa pdate Pq optional ,
186.It Fa other.keyAttrId        Ta to Ta Pf * Fa potherid Pq optional ,
187.It Fa other.keyAttr          Ta to Ta Pf * Fa pothertype Pq optional .
188.El
189Where a field is optional and absent,
190.Dv NULL
191is written to the corresponding parameter.
192Parameters the application is not interested in can be set to
193.Dv NULL .
194.Pp
195.Fn CMS_RecipientInfo_kekri_id_cmp
196compares the identifier in the
197.Fa id
198and
199.Fa idlen
200parameters against the
201.Fa keyIdentifier
202field of the
203.Vt KEKRecipientInfo
204structure
205.Fa ri .
206.Pp
207.Fn CMS_RecipientInfo_set0_key
208associates the symmetric
209.Fa key
210of length
211.Fa keylen
212with the
213.Vt KEKRecipientInfo
214structure
215.Fa ri .
216.Pp
217.Fn CMS_RecipientInfo_decrypt
218attempts to decrypt the
219.Vt RecipientInfo
220structure
221.Fa ri
222in
223.Fa cms .
224A key must have been associated with
225.Fa ri
226first.
227.Pp
228.Fn CMS_RecipientInfo_encrypt
229attempts to encrypt the
230.Vt RecipientInfo
231structure
232.Fa ri
233in
234.Fa cms .
235A key must have been associated with
236.Fa ri
237first and the content encryption key must be available,
238for example by a previous call to
239.Fn CMS_RecipientInfo_decrypt .
240.Pp
241The main purpose of these functions is to enable an application to
242lookup recipient keys using any appropriate technique when the simpler
243method of
244.Xr CMS_decrypt 3
245is not appropriate.
246.Pp
247In typical usage, an application retrieves all
248.Vt CMS_RecipientInfo
249structures using
250.Fn CMS_get0_RecipientInfos
251and checks the type of each using
252.Fn CMS_RecipientInfo_type .
253Depending on the type, the
254.Vt CMS_RecipientInfo
255structure can be ignored or its key identifier data retrieved using
256an appropriate function.
257If the corresponding secret or private key can be obtained by any
258appropriate means it can then be associated with the structure and
259.Fn CMS_RecipientInfo_decrypt
260called.
261If successful,
262.Xr CMS_decrypt 3
263can be called with a
264.Dv NULL
265key to decrypt the enveloped content.
266.Pp
267The function
268.Fn CMS_RecipientInfo_encrypt
269can be used to add a new recipient to an existing enveloped data
270structure.
271Typically an application will first decrypt an appropriate
272.Vt CMS_RecipientInfo
273structure to make the content encrypt key available.
274It will then add a new recipient using a function such as
275.Xr CMS_add1_recipient_cert 3
276and finally encrypt the content encryption key using
277.Fn CMS_RecipientInfo_encrypt .
278.Sh RETURN VALUES
279.Fn CMS_get0_RecipientInfos
280returns an internal pointer to all the
281.Vt CMS_RecipientInfo
282structures, or
283.Dv NULL
284if an error occurs.
285.Pp
286.Fn CMS_RecipientInfo_type
287returns an integer constant.
288.Pp
289.Fn CMS_RecipientInfo_ktri_get0_signer_id ,
290.Fn CMS_RecipientInfo_set0_pkey ,
291.Fn CMS_RecipientInfo_kekri_get0_id ,
292.Fn CMS_RecipientInfo_set0_key ,
293.Fn CMS_RecipientInfo_decrypt ,
294and
295.Fn CMS_RecipientInfo_encrypt
296return 1 for success or 0 if an error occurs.
297.Pp
298.Fn CMS_RecipientInfo_ktri_cert_cmp
299and
300.Fn CMS_RecipientInfo_kekri_id_cmp
301return 0 when
302.Fa ri
303matches or non-zero otherwise.
304.Pp
305Any error can be obtained from
306.Xr ERR_get_error 3 .
307.Sh SEE ALSO
308.Xr CMS_ContentInfo_new 3 ,
309.Xr CMS_decrypt 3
310.Sh STANDARDS
311RFC 5652 Cryptographic Message Syntax (CMS):
312.Bl -dash -compact -offset indent
313.It
314section 6.1: EnvelopedData Type
315.It
316section 6.2: RecipientInfo Type
317.It
318section 6.2.1: KeyTransRecipientInfo Type
319.It
320section 6.2.3: KEKRecipientInfo Type
321.El
322.Sh HISTORY
323These functions first appeared in OpenSSL 0.9.8h,
324except that
325.Fn CMS_RecipientInfo_encrypt
326first appeared in OpenSSL 1.0.2.
327They have been available since
328.Ox 6.7 .
329