1CMS_GET0_RECIPIENTINFOS(3)          OpenSSL         CMS_GET0_RECIPIENTINFOS(3)
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_kekri_id_cmp, CMS_RecipientInfo_set0_key,
10       CMS_RecipientInfo_decrypt, CMS_RecipientInfo_encrypt - CMS
11       envelopedData RecipientInfo routines
12

SYNOPSIS

14        #include <openssl/cms.h>
15
16        STACK_OF(CMS_RecipientInfo) *CMS_get0_RecipientInfos(CMS_ContentInfo *cms);
17        int CMS_RecipientInfo_type(CMS_RecipientInfo *ri);
18
19        int CMS_RecipientInfo_ktri_get0_signer_id(CMS_RecipientInfo *ri,
20                                                  ASN1_OCTET_STRING **keyid,
21                                                  X509_NAME **issuer,
22                                                  ASN1_INTEGER **sno);
23        int CMS_RecipientInfo_ktri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert);
24        int CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pkey);
25
26        int CMS_RecipientInfo_kekri_get0_id(CMS_RecipientInfo *ri, X509_ALGOR **palg,
27                                            ASN1_OCTET_STRING **pid,
28                                            ASN1_GENERALIZEDTIME **pdate,
29                                            ASN1_OBJECT **potherid,
30                                            ASN1_TYPE **pothertype);
31        int CMS_RecipientInfo_kekri_id_cmp(CMS_RecipientInfo *ri,
32                                           const unsigned char *id, size_t idlen);
33        int CMS_RecipientInfo_set0_key(CMS_RecipientInfo *ri,
34                                       unsigned char *key, size_t keylen);
35
36        int CMS_RecipientInfo_decrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
37        int CMS_RecipientInfo_encrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
38

DESCRIPTION

40       The function CMS_get0_RecipientInfos() returns all the
41       CMS_RecipientInfo structures associated with a CMS EnvelopedData
42       structure.
43
44       CMS_RecipientInfo_type() returns the type of CMS_RecipientInfo
45       structure ri.  It will currently return CMS_RECIPINFO_TRANS,
46       CMS_RECIPINFO_AGREE, CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, or
47       CMS_RECIPINFO_OTHER.
48
49       CMS_RecipientInfo_ktri_get0_signer_id() retrieves the certificate
50       recipient identifier associated with a specific CMS_RecipientInfo
51       structure ri, which must be of type CMS_RECIPINFO_TRANS. Either the
52       keyidentifier will be set in keyid or both issuer name and serial
53       number in issuer and sno.
54
55       CMS_RecipientInfo_ktri_cert_cmp() compares the certificate cert against
56       the CMS_RecipientInfo structure ri, which must be of type
57       CMS_RECIPINFO_TRANS.  It returns zero if the comparison is successful
58       and non zero if not.
59
60       CMS_RecipientInfo_set0_pkey() associates the private key pkey with the
61       CMS_RecipientInfo structure ri, which must be of type
62       CMS_RECIPINFO_TRANS.
63
64       CMS_RecipientInfo_kekri_get0_id() retrieves the key information from
65       the CMS_RecipientInfo structure ri which must be of type
66       CMS_RECIPINFO_KEK.  Any of the remaining parameters can be NULL if the
67       application is not interested in the value of a field. Where a field is
68       optional and absent NULL will be written to the corresponding
69       parameter. The keyEncryptionAlgorithm field is written to palg, the
70       keyIdentifier field is written to pid, the date field if present is
71       written to pdate, if the other field is present the components
72       keyAttrId and keyAttr are written to parameters potherid and
73       pothertype.
74
75       CMS_RecipientInfo_kekri_id_cmp() compares the ID in the id and idlen
76       parameters against the keyIdentifier CMS_RecipientInfo structure ri,
77       which must be of type CMS_RECIPINFO_KEK.  It returns zero if the
78       comparison is successful and non zero if not.
79
80       CMS_RecipientInfo_set0_key() associates the symmetric key key of length
81       keylen with the CMS_RecipientInfo structure ri, which must be of type
82       CMS_RECIPINFO_KEK.
83
84       CMS_RecipientInfo_decrypt() attempts to decrypt CMS_RecipientInfo
85       structure ri in structure cms. A key must have been associated with the
86       structure first.
87
88       CMS_RecipientInfo_encrypt() attempts to encrypt CMS_RecipientInfo
89       structure ri in structure cms. A key must have been associated with the
90       structure first and the content encryption key must be available: for
91       example by a previous call to CMS_RecipientInfo_decrypt().
92

NOTES

94       The main purpose of these functions is to enable an application to
95       lookup recipient keys using any appropriate technique when the simpler
96       method of CMS_decrypt() is not appropriate.
97
98       In typical usage and application will retrieve all CMS_RecipientInfo
99       structures using CMS_get0_RecipientInfos() and check the type of each
100       using CMS_RecipientInfo_type(). Depending on the type the
101       CMS_RecipientInfo structure can be ignored or its key identifier data
102       retrieved using an appropriate function. Then if the corresponding
103       secret or private key can be obtained by any appropriate means it can
104       then associated with the structure and CMS_RecipientInfo_decrypt()
105       called. If successful CMS_decrypt() can be called with a NULL key to
106       decrypt the enveloped content.
107
108       The CMS_RecipientInfo_encrypt() can be used to add a new recipient to
109       an existing enveloped data structure. Typically an application will
110       first decrypt an appropriate CMS_RecipientInfo structure to make the
111       content encrypt key available, it will then add a new recipient using a
112       function such as CMS_add1_recipient_cert() and finally encrypt the
113       content encryption key using CMS_RecipientInfo_encrypt().
114

RETURN VALUES

116       CMS_get0_RecipientInfos() returns all CMS_RecipientInfo structures, or
117       NULL if an error occurs.
118
119       CMS_RecipientInfo_ktri_get0_signer_id(), CMS_RecipientInfo_set0_pkey(),
120       CMS_RecipientInfo_kekri_get0_id(), CMS_RecipientInfo_set0_key() and
121       CMS_RecipientInfo_decrypt() return 1 for success or 0 if an error
122       occurs.  CMS_RecipientInfo_encrypt() return 1 for success or 0 if an
123       error occurs.
124
125       CMS_RecipientInfo_ktri_cert_cmp() and CMS_RecipientInfo_kekri_cmp()
126       return 0 for a successful comparison and non zero otherwise.
127
128       Any error can be obtained from ERR_get_error(3).
129

SEE ALSO

131       ERR_get_error(3), CMS_decrypt(3)
132
134       Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
135
136       Licensed under the OpenSSL license (the "License").  You may not use
137       this file except in compliance with the License.  You can obtain a copy
138       in the file LICENSE in the source distribution or at
139       <https://www.openssl.org/source/license.html>.
140
141
142
1431.1.1q                            2022-07-21        CMS_GET0_RECIPIENTINFOS(3)
Impressum