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