1CMS_GET0_RECIPIENTINFOS(3ossl)      OpenSSL     CMS_GET0_RECIPIENTINFOS(3ossl)
2
3
4

NAME

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

SYNOPSIS

15        #include <openssl/cms.h>
16
17        STACK_OF(CMS_RecipientInfo) *CMS_get0_RecipientInfos(CMS_ContentInfo *cms);
18        int CMS_RecipientInfo_type(CMS_RecipientInfo *ri);
19
20        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
39        int CMS_RecipientInfo_decrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
40        int CMS_RecipientInfo_encrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
41

DESCRIPTION

43       The function CMS_get0_RecipientInfos() returns all the
44       CMS_RecipientInfo structures associated with a CMS EnvelopedData
45       structure.
46
47       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
52       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
58       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
63       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
67       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
71       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
75       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
86       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
91       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
95       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
99       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

NOTES

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
109       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
119       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

RETURN VALUES

127       CMS_get0_RecipientInfos() returns all CMS_RecipientInfo structures, or
128       NULL if an error occurs.
129
130       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
136       CMS_RecipientInfo_ktri_cert_cmp() and CMS_RecipientInfo_kekri_cmp()
137       return 0 for a successful comparison and non zero otherwise.
138
139       Any error can be obtained from ERR_get_error(3).
140

SEE ALSO

142       ERR_get_error(3), CMS_decrypt(3)
143

HISTORY

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
151       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>.
155
156
157
1583.0.5                             2022-11-01    CMS_GET0_RECIPIENTINFOS(3ossl)
Impressum