doc/man3/CMS_get0_RecipientInfos.pod

   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