1=pod
2
3=head1 NAME
4
5 CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_signer_id,CMS_RecipientInfo_ktri_cert_cmp, CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, CMS_RecipientInfo_decrypt - CMS envelopedData RecipientInfo routines
6
7=head1 SYNOPSIS
8
9 #include <openssl/cms.h>
10
11 STACK_OF(CMS_RecipientInfo) *CMS_get0_RecipientInfos(CMS_ContentInfo *cms);
12 int CMS_RecipientInfo_type(CMS_RecipientInfo *ri);
13
14 int CMS_RecipientInfo_ktri_get0_signer_id(CMS_RecipientInfo *ri, ASN1_OCTET_STRING **keyid, X509_NAME **issuer, ASN1_INTEGER **sno);
15 int CMS_RecipientInfo_ktri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert);
16 int CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pkey);
17
18 int CMS_RecipientInfo_kekri_get0_id(CMS_RecipientInfo *ri, X509_ALGOR **palg, ASN1_OCTET_STRING **pid, ASN1_GENERALIZEDTIME **pdate, ASN1_OBJECT **potherid, ASN1_TYPE **pothertype);
19 int CMS_RecipientInfo_kekri_id_cmp(CMS_RecipientInfo *ri, const unsigned char *id, size_t idlen);
20 int CMS_RecipientInfo_set0_key(CMS_RecipientInfo *ri, unsigned char *key, size_t keylen);
21
22 int CMS_RecipientInfo_decrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
23
24=head1 DESCRIPTION
25
26The function CMS_get0_RecipientInfos() returns all the CMS_RecipientInfo
27structures associated with a CMS EnvelopedData structure.
28
29CMS_RecipientInfo_type() returns the type of CMS_RecipientInfo structure B<ri>.
30It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE,
31CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, or CMS_RECIPINFO_OTHER.
32
33CMS_RecipientInfo_ktri_get0_signer_id() retrieves the certificate recipient
34identifier associated with a specific CMS_RecipientInfo structure B<ri>, which
35must be of type CMS_RECIPINFO_TRANS. Either the keyidentifier will be set in
36B<keyid> or B<both> issuer name and serial number in B<issuer> and B<sno>.
37
38CMS_RecipientInfo_ktri_cert_cmp() compares the certificate B<cert> against the
39CMS_RecipientInfo structure B<ri>, which must be of type CMS_RECIPINFO_TRANS.
40It returns zero if the comparison is successful and non zero if not.
41
42CMS_RecipientInfo_set0_pkey() associates the private key B<pkey> with
43the CMS_RecipientInfo structure B<ri>, which must be of type
44CMS_RECIPINFO_TRANS.
45
46CMS_RecipientInfo_kekri_get0_id() retrieves the key information from the
47CMS_RecipientInfo structure B<ri> which must be of type CMS_RECIPINFO_KEK.  Any
48of the remaining parameters can be NULL if the application is not interested in
49the value of a field. Where a field is optional and absent NULL will be written
50to the corresponding parameter. The keyEncryptionAlgorithm field is written to
51B<palg>, the B<keyIdentifier> field is written to B<pid>, the B<date> field if
52present is written to B<pdate>, if the B<other> field is present the components
53B<keyAttrId> and B<keyAttr> are written to parameters B<potherid> and
54B<pothertype>.
55
56CMS_RecipientInfo_kekri_id_cmp() compares the ID in the B<id> and B<idlen>
57parameters against the B<keyIdentifier> CMS_RecipientInfo structure B<ri>,
58which must be of type CMS_RECIPINFO_KEK.  It returns zero if the comparison is
59successful and non zero if not.
60
61CMS_RecipientInfo_set0_key() associates the symmetric key B<key> of length
62B<keylen> with the CMS_RecipientInfo structure B<ri>, which must be of type
63CMS_RECIPINFO_KEK.
64
65CMS_RecipientInfo_decrypt() attempts to decrypt CMS_RecipientInfo structure
66B<ri> in structure B<cms>. A key must have been associated with the structure
67first.
68
69=head1 NOTES
70
71The main purpose of these functions is to enable an application to lookup
72recipient keys using any appropriate technique when the simpler method
73of CMS_decrypt() is not appropriate.
74
75In typical usage and application will retrieve all CMS_RecipientInfo structures
76using CMS_get0_RecipientInfos() and check the type of each using
77CMS_RecpientInfo_type(). Depending on the type the CMS_RecipientInfo structure
78can be ignored or its key identifier data retrieved using an appropriate
79function. Then if the corresponding secret or private key can be obtained by
80any appropriate means it can then associated with the structure and
81CMS_RecpientInfo_decrypt() called. If successful CMS_decrypt() can be called
82with a NULL key to decrypt the enveloped content.
83
84=head1 RETURN VALUES
85
86CMS_get0_RecipientInfos() returns all CMS_RecipientInfo structures, or NULL if
87an error occurs.
88
89CMS_RecipientInfo_ktri_get0_signer_id(), CMS_RecipientInfo_set0_pkey(),
90CMS_RecipientInfo_kekri_get0_id(), CMS_RecipientInfo_set0_key() and
91CMS_RecipientInfo_decrypt() return 1 for success or 0 if an error occurs.
92
93CMS_RecipientInfo_ktri_cert_cmp() and CMS_RecipientInfo_kekri_cmp() return 0
94for a successful comparison and non zero otherwise.
95
96Any error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>.
97
98=head1 SEE ALSO
99
100L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_decrypt(3)|CMS_decrypt(3)>
101
102=head1 HISTORY
103
104These functions were first was added to OpenSSL 0.9.8
105
106=cut
107