Fix L<> content in manpages
[openssl.git] / doc / crypto / CMS_get0_RecipientInfos.pod
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_RecipientInfo_encrypt - 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  int CMS_RecipientInfo_encrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
24
25 =head1 DESCRIPTION
26
27 The function CMS_get0_RecipientInfos() returns all the CMS_RecipientInfo
28 structures associated with a CMS EnvelopedData structure.
29
30 CMS_RecipientInfo_type() returns the type of CMS_RecipientInfo structure B<ri>.
31 It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE,
32 CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, or CMS_RECIPINFO_OTHER.
33
34 CMS_RecipientInfo_ktri_get0_signer_id() retrieves the certificate recipient
35 identifier associated with a specific CMS_RecipientInfo structure B<ri>, which
36 must be of type CMS_RECIPINFO_TRANS. Either the keyidentifier will be set in
37 B<keyid> or B<both> issuer name and serial number in B<issuer> and B<sno>. 
38
39 CMS_RecipientInfo_ktri_cert_cmp() compares the certificate B<cert> against the
40 CMS_RecipientInfo structure B<ri>, which must be of type CMS_RECIPINFO_TRANS.
41 It returns zero if the comparison is successful and non zero if not.
42
43 CMS_RecipientInfo_set0_pkey() associates the private key B<pkey> with
44 the CMS_RecipientInfo structure B<ri>, which must be of type
45 CMS_RECIPINFO_TRANS.
46
47 CMS_RecipientInfo_kekri_get0_id() retrieves the key information from the
48 CMS_RecipientInfo structure B<ri> which must be of type CMS_RECIPINFO_KEK.  Any
49 of the remaining parameters can be NULL if the application is not interested in
50 the value of a field. Where a field is optional and absent NULL will be written
51 to the corresponding parameter. The keyEncryptionAlgorithm field is written to
52 B<palg>, the B<keyIdentifier> field is written to B<pid>, the B<date> field if
53 present is written to B<pdate>, if the B<other> field is present the components
54 B<keyAttrId> and B<keyAttr> are written to parameters B<potherid> and
55 B<pothertype>.
56
57 CMS_RecipientInfo_kekri_id_cmp() compares the ID in the B<id> and B<idlen>
58 parameters against the B<keyIdentifier> CMS_RecipientInfo structure B<ri>,
59 which must be of type CMS_RECIPINFO_KEK.  It returns zero if the comparison is
60 successful and non zero if not.
61
62 CMS_RecipientInfo_set0_key() associates the symmetric key B<key> of length
63 B<keylen> with the CMS_RecipientInfo structure B<ri>, which must be of type
64 CMS_RECIPINFO_KEK.
65
66 CMS_RecipientInfo_decrypt() attempts to decrypt CMS_RecipientInfo structure
67 B<ri> in structure B<cms>. A key must have been associated with the structure
68 first.
69
70 CMS_RecipientInfo_encrypt() attempts to encrypt CMS_RecipientInfo structure
71 B<ri> in structure B<cms>. A key must have been associated with the structure
72 first and the content encryption key must be available: for example by a
73 previous call to CMS_RecipientInfo_decrypt().
74
75 =head1 NOTES
76
77 The main purpose of these functions is to enable an application to lookup
78 recipient keys using any appropriate technique when the simpler method
79 of CMS_decrypt() is not appropriate.
80
81 In typical usage and application will retrieve all CMS_RecipientInfo structures
82 using CMS_get0_RecipientInfos() and check the type of each using
83 CMS_RecpientInfo_type(). Depending on the type the CMS_RecipientInfo structure
84 can be ignored or its key identifier data retrieved using an appropriate
85 function. Then if the corresponding secret or private key can be obtained by
86 any appropriate means it can then associated with the structure and
87 CMS_RecpientInfo_decrypt() called. If successful CMS_decrypt() can be called
88 with a NULL key to decrypt the enveloped content.
89
90 The CMS_RecipientInfo_encrypt() can be used to add a new recipient to an
91 existing enveloped data structure. Typically an application will first decrypt
92 an appropriate CMS_RecipientInfo structure to make the content encrypt key
93 available, it will then add a new recipient using a function such as
94 CMS_add1_recipient_cert() and finally encrypt the content encryption key
95 using CMS_RecipientInfo_encrypt().
96
97 =head1 RETURN VALUES
98
99 CMS_get0_RecipientInfos() returns all CMS_RecipientInfo structures, or NULL if
100 an error occurs.
101
102 CMS_RecipientInfo_ktri_get0_signer_id(), CMS_RecipientInfo_set0_pkey(),
103 CMS_RecipientInfo_kekri_get0_id(), CMS_RecipientInfo_set0_key() and
104 CMS_RecipientInfo_decrypt() return 1 for success or 0 if an error occurs.
105 CMS_RecipientInfo_encrypt() return 1 for success or 0 if an error occurs.
106
107 CMS_RecipientInfo_ktri_cert_cmp() and CMS_RecipientInfo_kekri_cmp() return 0
108 for a successful comparison and non zero otherwise.
109
110 Any error can be obtained from L<ERR_get_error(3)>.
111
112 =head1 SEE ALSO
113
114 L<ERR_get_error(3)>, L<CMS_decrypt(3)>
115
116 =head1 HISTORY
117
118 These functions were first was added to OpenSSL 0.9.8
119
120 =cut