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