1CMS_GET0_RECIPIENTINFOS(3ossl) OpenSSL CMS_GET0_RECIPIENTINFOS(3ossl)
2
6 CMS_get0_RecipientInfos, CMS_RecipientInfo_type,
7 CMS_RecipientInfo_ktri_get0_signer_id, CMS_RecipientInfo_ktri_cert_cmp,
8 CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id,
9 CMS_RecipientInfo_kari_set0_pkey_and_peer,
10 CMS_RecipientInfo_kari_set0_pkey, CMS_RecipientInfo_kekri_id_cmp,
11 CMS_RecipientInfo_set0_key, CMS_RecipientInfo_decrypt,
12 CMS_RecipientInfo_encrypt - CMS envelopedData RecipientInfo routines
13
15 #include <openssl/cms.h>
16 STACK_OF(CMS_RecipientInfo) *CMS_get0_RecipientInfos(CMS_ContentInfo *cms);
18 int CMS_RecipientInfo_type(CMS_RecipientInfo *ri);
19 int CMS_RecipientInfo_ktri_get0_signer_id(CMS_RecipientInfo *ri,
21 ASN1_OCTET_STRING **keyid,
22 X509_NAME **issuer,
23 ASN1_INTEGER **sno);
24 int CMS_RecipientInfo_ktri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert);
25 int CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pkey);
26 int CMS_RecipientInfo_kari_set0_pkey_and_peer(CMS_RecipientInfo *ri,
27 EVP_PKEY *pk, X509 *peer);
28 int CMS_RecipientInfo_kari_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pk);
29 int CMS_RecipientInfo_kekri_get0_id(CMS_RecipientInfo *ri, X509_ALGOR **palg,
30 ASN1_OCTET_STRING **pid,
31 ASN1_GENERALIZEDTIME **pdate,
32 ASN1_OBJECT **potherid,
33 ASN1_TYPE **pothertype);
34 int CMS_RecipientInfo_kekri_id_cmp(CMS_RecipientInfo *ri,
35 const unsigned char *id, size_t idlen);
36 int CMS_RecipientInfo_set0_key(CMS_RecipientInfo *ri,
37 unsigned char *key, size_t keylen);
38 int CMS_RecipientInfo_decrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
40 int CMS_RecipientInfo_encrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
41
43 The function CMS_get0_RecipientInfos() returns all the
44 CMS_RecipientInfo structures associated with a CMS EnvelopedData
45 structure.
46 CMS_RecipientInfo_type() returns the type of CMS_RecipientInfo
48 structure ri. It will currently return CMS_RECIPINFO_TRANS,
49 CMS_RECIPINFO_AGREE, CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, or
50 CMS_RECIPINFO_OTHER.
51 CMS_RecipientInfo_ktri_get0_signer_id() retrieves the certificate
53 recipient identifier associated with a specific CMS_RecipientInfo
54 structure ri, which must be of type CMS_RECIPINFO_TRANS. Either the
55 keyidentifier will be set in keyid or both issuer name and serial
56 number in issuer and sno.
57 CMS_RecipientInfo_ktri_cert_cmp() compares the certificate cert against
59 the CMS_RecipientInfo structure ri, which must be of type
60 CMS_RECIPINFO_TRANS. It returns zero if the comparison is successful
61 and non zero if not.
62 CMS_RecipientInfo_set0_pkey() associates the private key pkey with the
64 CMS_RecipientInfo structure ri, which must be of type
65 CMS_RECIPINFO_TRANS.
66 CMS_RecipientInfo_kari_set0_pkey_and_peer() associates the private key
68 pkey and peer certificate peer with the CMS_RecipientInfo structure ri,
69 which must be of type CMS_RECIPINFO_AGREE.
70 CMS_RecipientInfo_kari_set0_pkey() associates the private key pkey with
72 the CMS_RecipientInfo structure ri, which must be of type
73 CMS_RECIPINFO_AGREE.
74 CMS_RecipientInfo_kekri_get0_id() retrieves the key information from
76 the CMS_RecipientInfo structure ri which must be of type
77 CMS_RECIPINFO_KEK. Any of the remaining parameters can be NULL if the
78 application is not interested in the value of a field. Where a field is
79 optional and absent NULL will be written to the corresponding
80 parameter. The keyEncryptionAlgorithm field is written to palg, the
81 keyIdentifier field is written to pid, the date field if present is
82 written to pdate, if the other field is present the components
83 keyAttrId and keyAttr are written to parameters potherid and
84 pothertype.
85 CMS_RecipientInfo_kekri_id_cmp() compares the ID in the id and idlen
87 parameters against the keyIdentifier CMS_RecipientInfo structure ri,
88 which must be of type CMS_RECIPINFO_KEK. It returns zero if the
89 comparison is successful and non zero if not.
90 CMS_RecipientInfo_set0_key() associates the symmetric key key of length
92 keylen with the CMS_RecipientInfo structure ri, which must be of type
93 CMS_RECIPINFO_KEK.
94 CMS_RecipientInfo_decrypt() attempts to decrypt CMS_RecipientInfo
96 structure ri in structure cms. A key must have been associated with the
97 structure first.
98 CMS_RecipientInfo_encrypt() attempts to encrypt CMS_RecipientInfo
100 structure ri in structure cms. A key must have been associated with the
101 structure first and the content encryption key must be available: for
102 example by a previous call to CMS_RecipientInfo_decrypt().
103
105 The main purpose of these functions is to enable an application to
106 lookup recipient keys using any appropriate technique when the simpler
107 method of CMS_decrypt() is not appropriate.
108 In typical usage and application will retrieve all CMS_RecipientInfo
110 structures using CMS_get0_RecipientInfos() and check the type of each
111 using CMS_RecipientInfo_type(). Depending on the type the
112 CMS_RecipientInfo structure can be ignored or its key identifier data
113 retrieved using an appropriate function. Then if the corresponding
114 secret or private key can be obtained by any appropriate means it can
115 then associated with the structure and CMS_RecipientInfo_decrypt()
116 called. If successful CMS_decrypt() can be called with a NULL key to
117 decrypt the enveloped content.
118 The CMS_RecipientInfo_encrypt() can be used to add a new recipient to
120 an existing enveloped data structure. Typically an application will
121 first decrypt an appropriate CMS_RecipientInfo structure to make the
122 content encrypt key available, it will then add a new recipient using a
123 function such as CMS_add1_recipient_cert() and finally encrypt the
124 content encryption key using CMS_RecipientInfo_encrypt().
125
127 CMS_get0_RecipientInfos() returns all CMS_RecipientInfo structures, or
128 NULL if an error occurs.
129 CMS_RecipientInfo_ktri_get0_signer_id(), CMS_RecipientInfo_set0_pkey(),
131 CMS_RecipientInfo_kekri_get0_id(), CMS_RecipientInfo_set0_key() and
132 CMS_RecipientInfo_decrypt() return 1 for success or 0 if an error
133 occurs. CMS_RecipientInfo_encrypt() return 1 for success or 0 if an
134 error occurs.
135 CMS_RecipientInfo_ktri_cert_cmp() and CMS_RecipientInfo_kekri_cmp()
137 return 0 for a successful comparison and non zero otherwise.
138 Any error can be obtained from ERR_get_error(3).
140
142 ERR_get_error(3), CMS_decrypt(3)
143
145 CMS_RecipientInfo_kari_set0_pkey_and_peer and
146 CMS_RecipientInfo_kari_set0_pkey were added in OpenSSL 3.0.
147
149 Copyright 2008-2021 The OpenSSL Project Authors. All Rights Reserved.
150 Licensed under the Apache License 2.0 (the "License"). You may not use
152 this file except in compliance with the License. You can obtain a copy
153 in the file LICENSE in the source distribution or at
154 <https://www.openssl.org/source/license.html>.
1553.1.1 2023-08-31 CMS_GET0_RECIPIENTINFOS(3ossl)