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