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