1=pod
2
3=head1 NAME
4
5CMS_add1_recipient, CMS_add1_recipient_cert, CMS_add0_recipient_key - add recipients to a CMS enveloped data structure
6
7=head1 SYNOPSIS
8
9 #include <openssl/cms.h>
10
11 CMS_RecipientInfo *CMS_add1_recipient(CMS_ContentInfo *cms, X509 *recip,
12                                       EVP_PKEY *originatorPrivKey,
13                                       X509 *originator, unsigned int flags);
14
15 CMS_RecipientInfo *CMS_add1_recipient_cert(CMS_ContentInfo *cms,
16                                            X509 *recip, unsigned int flags);
17
18 CMS_RecipientInfo *CMS_add0_recipient_key(CMS_ContentInfo *cms, int nid,
19                                           unsigned char *key, size_t keylen,
20                                           unsigned char *id, size_t idlen,
21                                           ASN1_GENERALIZEDTIME *date,
22                                           ASN1_OBJECT *otherTypeId,
23                                           ASN1_TYPE *otherType);
24
25=head1 DESCRIPTION
26
27CMS_add1_recipient() adds recipient B<recip> and provides the originator pkey
28B<originatorPrivKey> and originator certificate B<originator> to CMS_ContentInfo.
29The originator-related fields are relevant only in case when the keyAgreement
30method of providing of the shared key is in use.
31
32CMS_add1_recipient_cert() adds recipient B<recip> to CMS_ContentInfo enveloped
33data structure B<cms> as a KeyTransRecipientInfo structure.
34
35CMS_add0_recipient_key() adds symmetric key B<key> of length B<keylen> using
36wrapping algorithm B<nid>, identifier B<id> of length B<idlen> and optional
37values B<date>, B<otherTypeId> and B<otherType> to CMS_ContentInfo enveloped
38data structure B<cms> as a KEKRecipientInfo structure.
39
40The CMS_ContentInfo structure should be obtained from an initial call to
41CMS_encrypt() with the flag B<CMS_PARTIAL> set.
42
43=head1 NOTES
44
45The main purpose of this function is to provide finer control over a CMS
46enveloped data structure where the simpler CMS_encrypt() function defaults are
47not appropriate. For example if one or more KEKRecipientInfo structures
48need to be added. New attributes can also be added using the returned
49CMS_RecipientInfo structure and the CMS attribute utility functions.
50
51OpenSSL will by default identify recipient certificates using issuer name
52and serial number. If B<CMS_USE_KEYID> is set it will use the subject key
53identifier value instead. An error occurs if all recipient certificates do not
54have a subject key identifier extension.
55
56Currently only AES based key wrapping algorithms are supported for B<nid>,
57specifically: NID_id_aes128_wrap, NID_id_aes192_wrap and NID_id_aes256_wrap.
58If B<nid> is set to B<NID_undef> then an AES wrap algorithm will be used
59consistent with B<keylen>.
60
61=head1 RETURN VALUES
62
63CMS_add1_recipient_cert() and CMS_add0_recipient_key() return an internal
64pointer to the CMS_RecipientInfo structure just added or NULL if an error
65occurs.
66
67=head1 SEE ALSO
68
69L<ERR_get_error(3)>, L<CMS_decrypt(3)>,
70L<CMS_final(3)>,
71
72=head1 HISTORY
73
74B<CMS_add1_recipient_cert> and B<CMS_add0_recipient_key> were added in
75OpenSSL 3.0.
76
77=head1 COPYRIGHT
78
79Copyright 2008-2021 The OpenSSL Project Authors. All Rights Reserved.
80
81Licensed under the Apache License 2.0 (the "License").  You may not use
82this file except in compliance with the License.  You can obtain a copy
83in the file LICENSE in the source distribution or at
84L<https://www.openssl.org/source/license.html>.
85
86=cut
87