]>
Commit | Line | Data |
---|---|---|
847e551f DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
c952780c RS |
5 | CMS_get0_RecipientInfos, CMS_RecipientInfo_type, |
6 | CMS_RecipientInfo_ktri_get0_signer_id, CMS_RecipientInfo_ktri_cert_cmp, | |
7 | CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, | |
8 | CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, | |
9 | CMS_RecipientInfo_decrypt, CMS_RecipientInfo_encrypt | |
10 | - CMS envelopedData RecipientInfo routines | |
847e551f DSH |
11 | |
12 | =head1 SYNOPSIS | |
13 | ||
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 | ||
e9b77246 BB |
19 | int CMS_RecipientInfo_ktri_get0_signer_id(CMS_RecipientInfo *ri, |
20 | ASN1_OCTET_STRING **keyid, | |
21 | X509_NAME **issuer, | |
22 | ASN1_INTEGER **sno); | |
847e551f DSH |
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 | ||
e9b77246 BB |
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); | |
847e551f DSH |
35 | |
36 | int CMS_RecipientInfo_decrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri); | |
e1f1d28f | 37 | int CMS_RecipientInfo_encrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri); |
847e551f DSH |
38 | |
39 | =head1 DESCRIPTION | |
40 | ||
41 | The function CMS_get0_RecipientInfos() returns all the CMS_RecipientInfo | |
38d3a738 | 42 | structures associated with a CMS EnvelopedData structure. |
847e551f DSH |
43 | |
44 | CMS_RecipientInfo_type() returns the type of CMS_RecipientInfo structure B<ri>. | |
45 | It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE, | |
46 | CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, or CMS_RECIPINFO_OTHER. | |
47 | ||
48 | CMS_RecipientInfo_ktri_get0_signer_id() retrieves the certificate recipient | |
49 | identifier associated with a specific CMS_RecipientInfo structure B<ri>, which | |
50 | must be of type CMS_RECIPINFO_TRANS. Either the keyidentifier will be set in | |
1bc74519 | 51 | B<keyid> or B<both> issuer name and serial number in B<issuer> and B<sno>. |
847e551f | 52 | |
c420fab5 | 53 | CMS_RecipientInfo_ktri_cert_cmp() compares the certificate B<cert> against the |
847e551f DSH |
54 | CMS_RecipientInfo structure B<ri>, which must be of type CMS_RECIPINFO_TRANS. |
55 | It returns zero if the comparison is successful and non zero if not. | |
56 | ||
57 | CMS_RecipientInfo_set0_pkey() associates the private key B<pkey> with | |
58 | the CMS_RecipientInfo structure B<ri>, which must be of type | |
59 | CMS_RECIPINFO_TRANS. | |
60 | ||
61 | CMS_RecipientInfo_kekri_get0_id() retrieves the key information from the | |
62 | CMS_RecipientInfo structure B<ri> which must be of type CMS_RECIPINFO_KEK. Any | |
63 | of the remaining parameters can be NULL if the application is not interested in | |
64 | the value of a field. Where a field is optional and absent NULL will be written | |
65 | to the corresponding parameter. The keyEncryptionAlgorithm field is written to | |
66 | B<palg>, the B<keyIdentifier> field is written to B<pid>, the B<date> field if | |
67 | present is written to B<pdate>, if the B<other> field is present the components | |
68 | B<keyAttrId> and B<keyAttr> are written to parameters B<potherid> and | |
69 | B<pothertype>. | |
70 | ||
71 | CMS_RecipientInfo_kekri_id_cmp() compares the ID in the B<id> and B<idlen> | |
72 | parameters against the B<keyIdentifier> CMS_RecipientInfo structure B<ri>, | |
73 | which must be of type CMS_RECIPINFO_KEK. It returns zero if the comparison is | |
74 | successful and non zero if not. | |
75 | ||
76 | CMS_RecipientInfo_set0_key() associates the symmetric key B<key> of length | |
77 | B<keylen> with the CMS_RecipientInfo structure B<ri>, which must be of type | |
78 | CMS_RECIPINFO_KEK. | |
79 | ||
80 | CMS_RecipientInfo_decrypt() attempts to decrypt CMS_RecipientInfo structure | |
81 | B<ri> in structure B<cms>. A key must have been associated with the structure | |
82 | first. | |
83 | ||
e1f1d28f DSH |
84 | CMS_RecipientInfo_encrypt() attempts to encrypt CMS_RecipientInfo structure |
85 | B<ri> in structure B<cms>. A key must have been associated with the structure | |
86 | first and the content encryption key must be available: for example by a | |
87 | previous call to CMS_RecipientInfo_decrypt(). | |
88 | ||
847e551f DSH |
89 | =head1 NOTES |
90 | ||
91 | The main purpose of these functions is to enable an application to lookup | |
92 | recipient keys using any appropriate technique when the simpler method | |
93 | of CMS_decrypt() is not appropriate. | |
94 | ||
95 | In typical usage and application will retrieve all CMS_RecipientInfo structures | |
96 | using CMS_get0_RecipientInfos() and check the type of each using | |
df578aa0 | 97 | CMS_RecipientInfo_type(). Depending on the type the CMS_RecipientInfo structure |
847e551f | 98 | can be ignored or its key identifier data retrieved using an appropriate |
38d3a738 | 99 | function. Then if the corresponding secret or private key can be obtained by |
847e551f | 100 | any appropriate means it can then associated with the structure and |
df578aa0 | 101 | CMS_RecipientInfo_decrypt() called. If successful CMS_decrypt() can be called |
847e551f DSH |
102 | with a NULL key to decrypt the enveloped content. |
103 | ||
e1f1d28f DSH |
104 | The CMS_RecipientInfo_encrypt() can be used to add a new recipient to an |
105 | existing enveloped data structure. Typically an application will first decrypt | |
106 | an appropriate CMS_RecipientInfo structure to make the content encrypt key | |
107 | available, it will then add a new recipient using a function such as | |
108 | CMS_add1_recipient_cert() and finally encrypt the content encryption key | |
109 | using CMS_RecipientInfo_encrypt(). | |
110 | ||
847e551f DSH |
111 | =head1 RETURN VALUES |
112 | ||
113 | CMS_get0_RecipientInfos() returns all CMS_RecipientInfo structures, or NULL if | |
114 | an error occurs. | |
115 | ||
116 | CMS_RecipientInfo_ktri_get0_signer_id(), CMS_RecipientInfo_set0_pkey(), | |
117 | CMS_RecipientInfo_kekri_get0_id(), CMS_RecipientInfo_set0_key() and | |
118 | CMS_RecipientInfo_decrypt() return 1 for success or 0 if an error occurs. | |
e1f1d28f | 119 | CMS_RecipientInfo_encrypt() return 1 for success or 0 if an error occurs. |
847e551f DSH |
120 | |
121 | CMS_RecipientInfo_ktri_cert_cmp() and CMS_RecipientInfo_kekri_cmp() return 0 | |
c420fab5 | 122 | for a successful comparison and non zero otherwise. |
847e551f | 123 | |
9b86974e | 124 | Any error can be obtained from L<ERR_get_error(3)>. |
847e551f DSH |
125 | |
126 | =head1 SEE ALSO | |
127 | ||
9b86974e | 128 | L<ERR_get_error(3)>, L<CMS_decrypt(3)> |
847e551f | 129 | |
e2f92610 RS |
130 | =head1 COPYRIGHT |
131 | ||
132 | Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. | |
133 | ||
134 | Licensed under the OpenSSL license (the "License"). You may not use | |
135 | this file except in compliance with the License. You can obtain a copy | |
136 | in the file LICENSE in the source distribution or at | |
137 | L<https://www.openssl.org/source/license.html>. | |
138 | ||
139 | =cut |