1.\" $OpenBSD: CMS_add1_recipient_cert.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 is a derived work.
5.\" The changes are covered by the following Copyright and license:
6.\"
7.\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org>
8.\"
9.\" Permission to use, copy, modify, and distribute this software for any
10.\" purpose with or without fee is hereby granted, provided that the above
11.\" copyright notice and this permission notice appear in all copies.
12.\"
13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
20.\"
21.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
22.\" Copyright (c) 2008 The OpenSSL Project.  All rights reserved.
23.\"
24.\" Redistribution and use in source and binary forms, with or without
25.\" modification, are permitted provided that the following conditions
26.\" are met:
27.\"
28.\" 1. Redistributions of source code must retain the above copyright
29.\"    notice, this list of conditions and the following disclaimer.
30.\"
31.\" 2. Redistributions in binary form must reproduce the above copyright
32.\"    notice, this list of conditions and the following disclaimer in
33.\"    the documentation and/or other materials provided with the
34.\"    distribution.
35.\"
36.\" 3. All advertising materials mentioning features or use of this
37.\"    software must display the following acknowledgment:
38.\"    "This product includes software developed by the OpenSSL Project
39.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
40.\"
41.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
42.\"    endorse or promote products derived from this software without
43.\"    prior written permission. For written permission, please contact
44.\"    openssl-core@openssl.org.
45.\"
46.\" 5. Products derived from this software may not be called "OpenSSL"
47.\"    nor may "OpenSSL" appear in their names without prior written
48.\"    permission of the OpenSSL Project.
49.\"
50.\" 6. Redistributions of any form whatsoever must retain the following
51.\"    acknowledgment:
52.\"    "This product includes software developed by the OpenSSL Project
53.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
54.\"
55.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
56.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
57.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
58.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
59.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
60.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
61.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
62.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
63.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
64.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
65.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
66.\" OF THE POSSIBILITY OF SUCH DAMAGE.
67.\"
68.Dd $Mdocdate: November 2 2019 $
69.Dt CMS_ADD1_RECIPIENT_CERT 3
70.Os
71.Sh NAME
72.Nm CMS_add1_recipient_cert ,
73.Nm CMS_add0_recipient_key
74.Nd add recipients to a CMS EnvelopedData structure
75.Sh SYNOPSIS
76.In openssl/cms.h
77.Ft CMS_RecipientInfo *
78.Fo CMS_add1_recipient_cert
79.Fa "CMS_ContentInfo *cms"
80.Fa "X509 *certificate"
81.Fa "unsigned int flags"
82.Fc
83.Ft CMS_RecipientInfo *
84.Fo CMS_add0_recipient_key
85.Fa "CMS_ContentInfo *cms"
86.Fa "int nid"
87.Fa "unsigned char *key"
88.Fa "size_t keylen"
89.Fa "unsigned char *id"
90.Fa "size_t idlen"
91.Fa "ASN1_GENERALIZEDTIME *date"
92.Fa "ASN1_OBJECT *otherTypeId"
93.Fa "ASN1_TYPE *otherType"
94.Fc
95.Sh DESCRIPTION
96These functions add a new
97.Vt RecipientInfo
98structure to the
99.Fa recipientInfos
100field of the
101.Vt EnvelopedData
102structure
103.Fa cms ,
104which should have been obtained from an initial call to
105.Xr CMS_encrypt 3
106with the flag
107.Dv CMS_PARTIAL
108set.
109.Pp
110.Fn CMS_add1_recipient_cert
111adds the recipient
112.Fa certificate
113as a
114.Vt KeyTransRecipientInfo
115structure.
116.Pp
117.Fn CMS_add0_recipient_key
118adds the symmetric
119.Fa key
120of length
121.Fa keylen
122using the wrapping algorithm
123.Fa nid ,
124the identifier
125.Fa id
126of length
127.Fa idlen ,
128and the optional values
129.Fa date ,
130.Fa otherTypeId
131and
132.Fa otherType
133as a
134.Vt KEKRecipientInfo
135structure.
136.Pp
137The main purpose of these functions is to provide finer control over a CMS
138.Vt EnvelopedData
139structure where the simpler
140.Xr CMS_encrypt 3
141function defaults are not appropriate,
142for example if one or more
143.Vt KEKRecipientInfo
144structures need to be added.
145New attributes can also be added using the returned
146.Vt CMS_RecipientInfo
147structure and the CMS attribute utility functions.
148.Pp
149By default, recipient certificates are identified using issuer
150name and serial number.
151If the flag
152.Dv CMS_USE_KEYID
153is set, the subject key identifier value is used instead.
154An error occurs if all recipient certificates do not have a subject key
155identifier extension.
156.Pp
157Currently only AES based key wrapping algorithms are supported for
158.Fa nid ,
159specifically
160.Dv NID_id_aes128_wrap ,
161.Dv NID_id_aes192_wrap ,
162and
163.Dv NID_id_aes256_wrap .
164If
165.Fa nid
166is set to
167.Dv NID_undef ,
168then an AES wrap algorithm will be used consistent with
169.Fa keylen .
170.Sh RETURN VALUES
171.Fn CMS_add1_recipient_cert
172and
173.Fn CMS_add0_recipient_key
174return an internal pointer to the
175.Vt CMS_RecipientInfo
176structure just added or
177.Dv NULL
178if an error occurs.
179.Sh SEE ALSO
180.Xr CMS_ContentInfo_new 3 ,
181.Xr CMS_encrypt 3 ,
182.Xr CMS_final 3 ,
183.Xr ERR_get_error 3
184.Sh STANDARDS
185RFC 5652: Cryptographic Message Syntax
186.Bl -dash -compact -offset indent
187.It
188section 6.1: EnvelopedData Type
189.It
190section 6.2.1: KeyTransRecipientInfo Type
191.It
192section 6.2.3: KEKRecipientInfo Type
193.El
194.Sh HISTORY
195.Fn CMS_add1_recipient_cert
196and
197.Fn CMS_add0_recipient_key
198first appeared in OpenSSL 0.9.8h
199and have been available since
200.Ox 6.7 .
201