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