1=pod
2
3=head1 NAME
4
5CMS_get0_RecipientInfos, CMS_RecipientInfo_type,
6CMS_RecipientInfo_ktri_get0_signer_id, CMS_RecipientInfo_ktri_cert_cmp,
7CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id,
8CMS_RecipientInfo_kari_set0_pkey_and_peer,
9CMS_RecipientInfo_kari_set0_pkey, CMS_RecipientInfo_kari_get0_ctx,
10CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key,
11CMS_RecipientInfo_kemri_cert_cmp, CMS_RecipientInfo_kemri_set0_pkey,
12CMS_RecipientInfo_kemri_get0_ctx, CMS_RecipientInfo_kemri_get0_kdf_alg,
13CMS_RecipientInfo_kemri_set_ukm, CMS_RecipientInfo_decrypt,
14CMS_RecipientInfo_encrypt
15- CMS envelopedData RecipientInfo routines
16
17=head1 SYNOPSIS
18
19 #include <openssl/cms.h>
20
21 STACK_OF(CMS_RecipientInfo) *CMS_get0_RecipientInfos(CMS_ContentInfo *cms);
22 int CMS_RecipientInfo_type(CMS_RecipientInfo *ri);
23
24 int CMS_RecipientInfo_ktri_get0_signer_id(CMS_RecipientInfo *ri,
25                                           ASN1_OCTET_STRING **keyid,
26                                           X509_NAME **issuer,
27                                           ASN1_INTEGER **sno);
28 int CMS_RecipientInfo_ktri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert);
29 int CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pkey);
30 int CMS_RecipientInfo_kari_set0_pkey_and_peer(CMS_RecipientInfo *ri,
31                                               EVP_PKEY *pk, X509 *peer);
32 int CMS_RecipientInfo_kari_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pk);
33 EVP_CIPHER_CTX *CMS_RecipientInfo_kari_get0_ctx(CMS_RecipientInfo *ri);
34 int CMS_RecipientInfo_kekri_get0_id(CMS_RecipientInfo *ri, X509_ALGOR **palg,
35                                     ASN1_OCTET_STRING **pid,
36                                     ASN1_GENERALIZEDTIME **pdate,
37                                     ASN1_OBJECT **potherid,
38                                     ASN1_TYPE **pothertype);
39 int CMS_RecipientInfo_kekri_id_cmp(CMS_RecipientInfo *ri,
40                                    const unsigned char *id, size_t idlen);
41 int CMS_RecipientInfo_set0_key(CMS_RecipientInfo *ri,
42                                unsigned char *key, size_t keylen);
43 int CMS_RecipientInfo_kemri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert);
44 int CMS_RecipientInfo_kemri_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pk);
45 EVP_CIPHER_CTX *CMS_RecipientInfo_kemri_get0_ctx(CMS_RecipientInfo *ri);
46 X509_ALGOR *CMS_RecipientInfo_kemri_get0_kdf_alg(CMS_RecipientInfo *ri);
47 int CMS_RecipientInfo_kemri_set_ukm(CMS_RecipientInfo *ri,
48                                     const unsigned char *ukm,
49                                     int ukmLength);
50
51 int CMS_RecipientInfo_decrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
52 int CMS_RecipientInfo_encrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
53
54=head1 DESCRIPTION
55
56The function CMS_get0_RecipientInfos() returns all the CMS_RecipientInfo
57structures associated with a CMS EnvelopedData structure.
58
59CMS_RecipientInfo_type() returns the type of CMS_RecipientInfo structure B<ri>.
60It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE,
61CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, CMS_RECIPINFO_KEM, or
62CMS_RECIPINFO_OTHER.
63
64CMS_RecipientInfo_ktri_get0_signer_id() retrieves the certificate recipient
65identifier associated with a specific CMS_RecipientInfo structure B<ri>, which
66must be of type CMS_RECIPINFO_TRANS. Either the keyidentifier will be set in
67B<keyid> or B<both> issuer name and serial number in B<issuer> and B<sno>.
68
69CMS_RecipientInfo_ktri_cert_cmp() compares the certificate B<cert> against the
70CMS_RecipientInfo structure B<ri>, which must be of type CMS_RECIPINFO_TRANS.
71It returns zero if the comparison is successful and non zero if not.
72
73CMS_RecipientInfo_set0_pkey() associates the private key B<pkey> with
74the CMS_RecipientInfo structure B<ri>, which must be of type
75CMS_RECIPINFO_TRANS.
76
77CMS_RecipientInfo_kari_set0_pkey_and_peer() associates the private key B<pkey>
78and peer certificate B<peer> with the CMS_RecipientInfo structure B<ri>, which
79must be of type CMS_RECIPINFO_AGREE.
80
81CMS_RecipientInfo_kari_set0_pkey() associates the private key B<pkey> with the
82CMS_RecipientInfo structure B<ri>, which must be of type CMS_RECIPINFO_AGREE.
83
84CMS_RecipientInfo_kari_get0_ctx() returns the EVP_CIPHER_CTX for the key
85encryption key, allowing the caller to specify the key wrap cipher.  The
86CMS_RecipientInfo structure B<ri> must be of type CMS_RECIPINFO_AGREE.
87
88CMS_RecipientInfo_kekri_get0_id() retrieves the key information from the
89CMS_RecipientInfo structure B<ri> which must be of type CMS_RECIPINFO_KEK.  Any
90of the remaining parameters can be NULL if the application is not interested in
91the value of a field. Where a field is optional and absent NULL will be written
92to the corresponding parameter. The keyEncryptionAlgorithm field is written to
93B<palg>, the B<keyIdentifier> field is written to B<pid>, the B<date> field if
94present is written to B<pdate>, if the B<other> field is present the components
95B<keyAttrId> and B<keyAttr> are written to parameters B<potherid> and
96B<pothertype>.
97
98CMS_RecipientInfo_kekri_id_cmp() compares the ID in the B<id> and B<idlen>
99parameters against the B<keyIdentifier> CMS_RecipientInfo structure B<ri>,
100which must be of type CMS_RECIPINFO_KEK.  It returns zero if the comparison is
101successful and non zero if not.
102
103CMS_RecipientInfo_set0_key() associates the symmetric key B<key> of length
104B<keylen> with the CMS_RecipientInfo structure B<ri>, which must be of type
105CMS_RECIPINFO_KEK.
106
107CMS_RecipientInfo_kemri_cert_cmp() compares the certificate B<cert> against the
108CMS_RecipientInfo structure B<ri>, which must be of type CMS_RECIPINFO_KEM.
109It returns zero if the comparison is successful and non zero if not.
110
111CMS_RecipientInfo_kemri_set0_pkey() associates the private key B<pkey> with the
112CMS_RecipientInfo structure B<ri>, which must be of type CMS_RECIPINFO_KEM.
113
114CMS_RecipientInfo_kemri_get0_ctx() returns the EVP_CIPHER_CTX for the key
115encryption key, allowing the caller to specify the key wrap cipher.  The
116CMS_RecipientInfo structure B<ri> must be of type CMS_RECIPINFO_KEM.
117
118CMS_RecipientInfo_kemri_get0_kdf_alg() returns the X509_ALGOR for the
119RecipientInfo's KDF, allowing the caller to specify the KDF algorithm.  The
120CMS_RecipientInfo structure B<ri> must be of type CMS_RECIPINFO_KEM. If the
121caller doesn't specify a KDF algorithm, B<HKDF-SHA256> will be used.
122
123CMS_RecipientInfo_kemri_set_ukm() sets the RecipientInfo's optional user
124keying material (UKM).  The UKM is encoded, along with other information, into
125the B<OSSL_KDF_PARAM_INFO> parameter of the RecipientInfo's KDF. The
126CMS_RecipientInfo structure B<ri> must be of type CMS_RECIPINFO_KEM.
127
128CMS_RecipientInfo_decrypt() attempts to decrypt CMS_RecipientInfo structure
129B<ri> in structure B<cms>. A key must have been associated with the structure
130first.
131
132CMS_RecipientInfo_encrypt() attempts to encrypt CMS_RecipientInfo structure
133B<ri> in structure B<cms>. A key must have been associated with the structure
134first and the content encryption key must be available: for example by a
135previous call to CMS_RecipientInfo_decrypt().
136
137=head1 NOTES
138
139The main purpose of these functions is to enable an application to lookup
140recipient keys using any appropriate technique when the simpler method
141of CMS_decrypt() is not appropriate.
142
143In typical usage and application will retrieve all CMS_RecipientInfo structures
144using CMS_get0_RecipientInfos() and check the type of each using
145CMS_RecipientInfo_type(). Depending on the type the CMS_RecipientInfo structure
146can be ignored or its key identifier data retrieved using an appropriate
147function. Then if the corresponding secret or private key can be obtained by
148any appropriate means it can then associated with the structure and
149CMS_RecipientInfo_decrypt() called. If successful CMS_decrypt() can be called
150with a NULL key to decrypt the enveloped content.
151
152The CMS_RecipientInfo_encrypt() can be used to add a new recipient to an
153existing enveloped data structure. Typically an application will first decrypt
154an appropriate CMS_RecipientInfo structure to make the content encrypt key
155available, it will then add a new recipient using a function such as
156CMS_add1_recipient_cert() and finally encrypt the content encryption key
157using CMS_RecipientInfo_encrypt().
158
159=head1 RETURN VALUES
160
161CMS_get0_RecipientInfos() returns all CMS_RecipientInfo structures, or NULL if
162an error occurs.
163
164CMS_RecipientInfo_ktri_get0_signer_id(), CMS_RecipientInfo_set0_pkey(),
165CMS_RecipientInfo_kekri_get0_id(), CMS_RecipientInfo_set0_key(),
166CMS_RecipientInfo_kemri_set0_pkey(), CMS_RecipientInfo_kemri_set_ukm(),
167CMS_RecipientInfo_decrypt() and CMS_RecipientInfo_encrypt() return 1 for
168success or 0 if an error occurs.
169
170CMS_RecipientInfo_ktri_cert_cmp(), CMS_RecipientInfo_kemri_cert_cmp() and
171CMS_RecipientInfo_kekri_cmp() return 0 for a successful comparison and non zero
172otherwise.
173
174CMS_RecipientInfo_kemri_get0_ctx() and CMS_RecipientInfo_kari_get0_ctx return
175the RecipientInfo's EVP_CIPHER_CTX or NULL if an error occurred.
176
177CMS_RecipientInfo_kemri_get0_kdf_alg() returns the RecipientInfo's KDF's
178X509_ALGOR or NULL if an error occurred.
179
180Any error can be obtained from L<ERR_get_error(3)>.
181
182=head1 SEE ALSO
183
184L<ERR_get_error(3)>, L<CMS_decrypt(3)>
185
186=head1 HISTORY
187
188B<CMS_RecipientInfo_kari_set0_pkey_and_peer> and B<CMS_RecipientInfo_kari_set0_pkey>
189were added in OpenSSL 3.0.
190
191B<CMS_RecipientInfo_kemri_cert_cmp>, B<CMS_RecipientInfo_kemri_set0_pkey>,
192B<CMS_RecipientInfo_kemri_get0_ctx>, B<CMS_RecipientInfo_kemri_get0_kdf_alg>
193and B<CMS_RecipientInfo_kemri_set_ukm> were added in OpenSSL 3.6.
194
195=head1 COPYRIGHT
196
197Copyright 2008-2025 The OpenSSL Project Authors. All Rights Reserved.
198
199Licensed under the Apache License 2.0 (the "License").  You may not use
200this file except in compliance with the License.  You can obtain a copy
201in the file LICENSE in the source distribution or at
202L<https://www.openssl.org/source/license.html>.
203
204=cut
205