Debian Codegraph @

upstream/debian-unstable/man3/CMS_get0_RecipientInfos.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "CMS_GET0_RECIPIENTINFOS 3SSL"
58 .TH CMS_GET0_RECIPIENTINFOS 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 CMS_get0_RecipientInfos, CMS_RecipientInfo_type,
65 CMS_RecipientInfo_ktri_get0_signer_id, CMS_RecipientInfo_ktri_cert_cmp,
66 CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id,
67 CMS_RecipientInfo_kari_set0_pkey_and_peer,
68 CMS_RecipientInfo_kari_set0_pkey, CMS_RecipientInfo_kari_get0_ctx,
69 CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key,
70 CMS_RecipientInfo_kemri_cert_cmp, CMS_RecipientInfo_kemri_set0_pkey,
71 CMS_RecipientInfo_kemri_get0_ctx, CMS_RecipientInfo_kemri_get0_kdf_alg,
72 CMS_RecipientInfo_kemri_set_ukm, CMS_RecipientInfo_decrypt,
73 CMS_RecipientInfo_encrypt
74 \&\- CMS envelopedData RecipientInfo routines
75 .SH SYNOPSIS
76 .IX Header "SYNOPSIS"
77 .Vb 1
78 \& #include <openssl/cms.h>
79 \&
80 \& STACK_OF(CMS_RecipientInfo) *CMS_get0_RecipientInfos(CMS_ContentInfo *cms);
81 \& int CMS_RecipientInfo_type(CMS_RecipientInfo *ri);
82 \&
83 \& int CMS_RecipientInfo_ktri_get0_signer_id(CMS_RecipientInfo *ri,
84 \& ASN1_OCTET_STRING **keyid,
85 \& X509_NAME **issuer,
86 \& ASN1_INTEGER **sno);
87 \& int CMS_RecipientInfo_ktri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert);
88 \& int CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pkey);
89 \& int CMS_RecipientInfo_kari_set0_pkey_and_peer(CMS_RecipientInfo *ri,
90 \& EVP_PKEY *pk, X509 *peer);
91 \& int CMS_RecipientInfo_kari_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pk);
92 \& EVP_CIPHER_CTX *CMS_RecipientInfo_kari_get0_ctx(CMS_RecipientInfo *ri);
93 \& int CMS_RecipientInfo_kekri_get0_id(CMS_RecipientInfo *ri, X509_ALGOR **palg,
94 \& ASN1_OCTET_STRING **pid,
95 \& ASN1_GENERALIZEDTIME **pdate,
96 \& ASN1_OBJECT **potherid,
97 \& ASN1_TYPE **pothertype);
98 \& int CMS_RecipientInfo_kekri_id_cmp(CMS_RecipientInfo *ri,
99 \& const unsigned char *id, size_t idlen);
100 \& int CMS_RecipientInfo_set0_key(CMS_RecipientInfo *ri,
101 \& unsigned char *key, size_t keylen);
102 \& int CMS_RecipientInfo_kemri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert);
103 \& int CMS_RecipientInfo_kemri_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pk);
104 \& EVP_CIPHER_CTX *CMS_RecipientInfo_kemri_get0_ctx(CMS_RecipientInfo *ri);
105 \& X509_ALGOR *CMS_RecipientInfo_kemri_get0_kdf_alg(CMS_RecipientInfo *ri);
106 \& int CMS_RecipientInfo_kemri_set_ukm(CMS_RecipientInfo *ri,
107 \& const unsigned char *ukm,
108 \& int ukmLength);
109 \&
110 \& int CMS_RecipientInfo_decrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
111 \& int CMS_RecipientInfo_encrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
112 .Ve
113 .SH DESCRIPTION
114 .IX Header "DESCRIPTION"
115 The function \fBCMS_get0_RecipientInfos()\fR returns all the CMS_RecipientInfo
116 structures associated with a CMS EnvelopedData structure.
117 .PP
118 \&\fBCMS_RecipientInfo_type()\fR returns the type of CMS_RecipientInfo structure \fBri\fR.
119 It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE,
120 CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, CMS_RECIPINFO_KEM, or
121 CMS_RECIPINFO_OTHER.
122 .PP
123 \&\fBCMS_RecipientInfo_ktri_get0_signer_id()\fR retrieves the certificate recipient
124 identifier associated with a specific CMS_RecipientInfo structure \fBri\fR, which
125 must be of type CMS_RECIPINFO_TRANS. Either the keyidentifier will be set in
126 \&\fBkeyid\fR or \fBboth\fR issuer name and serial number in \fBissuer\fR and \fBsno\fR.
127 .PP
128 \&\fBCMS_RecipientInfo_ktri_cert_cmp()\fR compares the certificate \fBcert\fR against the
129 CMS_RecipientInfo structure \fBri\fR, which must be of type CMS_RECIPINFO_TRANS.
130 It returns zero if the comparison is successful and non zero if not.
131 .PP
132 \&\fBCMS_RecipientInfo_set0_pkey()\fR associates the private key \fBpkey\fR with
133 the CMS_RecipientInfo structure \fBri\fR, which must be of type
134 CMS_RECIPINFO_TRANS.
135 .PP
136 \&\fBCMS_RecipientInfo_kari_set0_pkey_and_peer()\fR associates the private key \fBpkey\fR
137 and peer certificate \fBpeer\fR with the CMS_RecipientInfo structure \fBri\fR, which
138 must be of type CMS_RECIPINFO_AGREE.
139 .PP
140 \&\fBCMS_RecipientInfo_kari_set0_pkey()\fR associates the private key \fBpkey\fR with the
141 CMS_RecipientInfo structure \fBri\fR, which must be of type CMS_RECIPINFO_AGREE.
142 .PP
143 \&\fBCMS_RecipientInfo_kari_get0_ctx()\fR returns the EVP_CIPHER_CTX for the key
144 encryption key, allowing the caller to specify the key wrap cipher. The
145 CMS_RecipientInfo structure \fBri\fR must be of type CMS_RECIPINFO_AGREE.
146 .PP
147 \&\fBCMS_RecipientInfo_kekri_get0_id()\fR retrieves the key information from the
148 CMS_RecipientInfo structure \fBri\fR which must be of type CMS_RECIPINFO_KEK. Any
149 of the remaining parameters can be NULL if the application is not interested in
150 the value of a field. Where a field is optional and absent NULL will be written
151 to the corresponding parameter. The keyEncryptionAlgorithm field is written to
152 \&\fBpalg\fR, the \fBkeyIdentifier\fR field is written to \fBpid\fR, the \fBdate\fR field if
153 present is written to \fBpdate\fR, if the \fBother\fR field is present the components
154 \&\fBkeyAttrId\fR and \fBkeyAttr\fR are written to parameters \fBpotherid\fR and
155 \&\fBpothertype\fR.
156 .PP
157 \&\fBCMS_RecipientInfo_kekri_id_cmp()\fR compares the ID in the \fBid\fR and \fBidlen\fR
158 parameters against the \fBkeyIdentifier\fR CMS_RecipientInfo structure \fBri\fR,
159 which must be of type CMS_RECIPINFO_KEK. It returns zero if the comparison is
160 successful and non zero if not.
161 .PP
162 \&\fBCMS_RecipientInfo_set0_key()\fR associates the symmetric key \fBkey\fR of length
163 \&\fBkeylen\fR with the CMS_RecipientInfo structure \fBri\fR, which must be of type
164 CMS_RECIPINFO_KEK.
165 .PP
166 \&\fBCMS_RecipientInfo_kemri_cert_cmp()\fR compares the certificate \fBcert\fR against the
167 CMS_RecipientInfo structure \fBri\fR, which must be of type CMS_RECIPINFO_KEM.
168 It returns zero if the comparison is successful and non zero if not.
169 .PP
170 \&\fBCMS_RecipientInfo_kemri_set0_pkey()\fR associates the private key \fBpkey\fR with the
171 CMS_RecipientInfo structure \fBri\fR, which must be of type CMS_RECIPINFO_KEM.
172 .PP
173 \&\fBCMS_RecipientInfo_kemri_get0_ctx()\fR returns the EVP_CIPHER_CTX for the key
174 encryption key, allowing the caller to specify the key wrap cipher. The
175 CMS_RecipientInfo structure \fBri\fR must be of type CMS_RECIPINFO_KEM.
176 .PP
177 \&\fBCMS_RecipientInfo_kemri_get0_kdf_alg()\fR returns the X509_ALGOR for the
178 RecipientInfo's KDF, allowing the caller to specify the KDF algorithm. The
179 CMS_RecipientInfo structure \fBri\fR must be of type CMS_RECIPINFO_KEM. If the
180 caller doesn't specify a KDF algorithm, \fBHKDF\-SHA256\fR will be used.
181 .PP
182 \&\fBCMS_RecipientInfo_kemri_set_ukm()\fR sets the RecipientInfo's optional user
183 keying material (UKM). The UKM is encoded, along with other information, into
184 the \fBOSSL_KDF_PARAM_INFO\fR parameter of the RecipientInfo's KDF. The
185 CMS_RecipientInfo structure \fBri\fR must be of type CMS_RECIPINFO_KEM.
186 .PP
187 \&\fBCMS_RecipientInfo_decrypt()\fR attempts to decrypt CMS_RecipientInfo structure
188 \&\fBri\fR in structure \fBcms\fR. A key must have been associated with the structure
189 first.
190 .PP
191 \&\fBCMS_RecipientInfo_encrypt()\fR attempts to encrypt CMS_RecipientInfo structure
192 \&\fBri\fR in structure \fBcms\fR. A key must have been associated with the structure
193 first and the content encryption key must be available: for example by a
194 previous call to \fBCMS_RecipientInfo_decrypt()\fR.
195 .SH NOTES
196 .IX Header "NOTES"
197 The main purpose of these functions is to enable an application to lookup
198 recipient keys using any appropriate technique when the simpler method
199 of \fBCMS_decrypt()\fR is not appropriate.
200 .PP
201 In typical usage and application will retrieve all CMS_RecipientInfo structures
202 using \fBCMS_get0_RecipientInfos()\fR and check the type of each using
203 \&\fBCMS_RecipientInfo_type()\fR. Depending on the type the CMS_RecipientInfo structure
204 can be ignored or its key identifier data retrieved using an appropriate
205 function. Then if the corresponding secret or private key can be obtained by
206 any appropriate means it can then associated with the structure and
207 \&\fBCMS_RecipientInfo_decrypt()\fR called. If successful \fBCMS_decrypt()\fR can be called
208 with a NULL key to decrypt the enveloped content.
209 .PP
210 The \fBCMS_RecipientInfo_encrypt()\fR can be used to add a new recipient to an
211 existing enveloped data structure. Typically an application will first decrypt
212 an appropriate CMS_RecipientInfo structure to make the content encrypt key
213 available, it will then add a new recipient using a function such as
214 \&\fBCMS_add1_recipient_cert()\fR and finally encrypt the content encryption key
215 using \fBCMS_RecipientInfo_encrypt()\fR.
216 .SH "RETURN VALUES"
217 .IX Header "RETURN VALUES"
218 \&\fBCMS_get0_RecipientInfos()\fR returns all CMS_RecipientInfo structures, or NULL if
219 an error occurs.
220 .PP
221 \&\fBCMS_RecipientInfo_ktri_get0_signer_id()\fR, \fBCMS_RecipientInfo_set0_pkey()\fR,
222 \&\fBCMS_RecipientInfo_kekri_get0_id()\fR, \fBCMS_RecipientInfo_set0_key()\fR,
223 \&\fBCMS_RecipientInfo_kemri_set0_pkey()\fR, \fBCMS_RecipientInfo_kemri_set_ukm()\fR,
224 \&\fBCMS_RecipientInfo_decrypt()\fR and \fBCMS_RecipientInfo_encrypt()\fR return 1 for
225 success or 0 if an error occurs.
226 .PP
227 \&\fBCMS_RecipientInfo_ktri_cert_cmp()\fR, \fBCMS_RecipientInfo_kemri_cert_cmp()\fR and
228 \&\fBCMS_RecipientInfo_kekri_cmp()\fR return 0 for a successful comparison and non zero
229 otherwise.
230 .PP
231 \&\fBCMS_RecipientInfo_kemri_get0_ctx()\fR and CMS_RecipientInfo_kari_get0_ctx return
232 the RecipientInfo's EVP_CIPHER_CTX or NULL if an error occurred.
233 .PP
234 \&\fBCMS_RecipientInfo_kemri_get0_kdf_alg()\fR returns the RecipientInfo's KDF's
235 X509_ALGOR or NULL if an error occurred.
236 .PP
237 Any error can be obtained from \fBERR_get_error\fR\|(3).
238 .SH "SEE ALSO"
239 .IX Header "SEE ALSO"
240 \&\fBERR_get_error\fR\|(3), \fBCMS_decrypt\fR\|(3)
241 .SH HISTORY
242 .IX Header "HISTORY"
243 \&\fBCMS_RecipientInfo_kari_set0_pkey_and_peer\fR and \fBCMS_RecipientInfo_kari_set0_pkey\fR
244 were added in OpenSSL 3.0.
245 .PP
246 \&\fBCMS_RecipientInfo_kemri_cert_cmp\fR, \fBCMS_RecipientInfo_kemri_set0_pkey\fR,
247 \&\fBCMS_RecipientInfo_kemri_get0_ctx\fR, \fBCMS_RecipientInfo_kemri_get0_kdf_alg\fR
248 and \fBCMS_RecipientInfo_kemri_set_ukm\fR were added in OpenSSL 3.6.
249 .SH COPYRIGHT
250 .IX Header "COPYRIGHT"
251 Copyright 2008\-2025 The OpenSSL Project Authors. All Rights Reserved.
252 .PP
253 Licensed under the Apache License 2.0 (the "License"). You may not use
254 this file except in compliance with the License. You can obtain a copy
255 in the file LICENSE in the source distribution or at
256 <https://www.openssl.org/source/license.html>.