doc/man3/CMS_add1_recipient_cert.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 CMS_add1_recipient_cert, CMS_add0_recipient_key - add recipients to a CMS enveloped data structure
   6
   7 =head1 SYNOPSIS
   8
   9  #include <openssl/cms.h>
  10
  11  CMS_RecipientInfo *CMS_add1_recipient_cert(CMS_ContentInfo *cms,
  12                                             X509 *recip, unsigned int flags);
  13
  14  CMS_RecipientInfo *CMS_add0_recipient_key(CMS_ContentInfo *cms, int nid,
  15                                            unsigned char *key, size_t keylen,
  16                                            unsigned char *id, size_t idlen,
  17                                            ASN1_GENERALIZEDTIME *date,
  18                                            ASN1_OBJECT *otherTypeId,
  19                                            ASN1_TYPE *otherType);
  20
  21 =head1 DESCRIPTION
  22
  23 CMS_add1_recipient_cert() adds recipient B<recip> to CMS_ContentInfo enveloped
  24 data structure B<cms> as a KeyTransRecipientInfo structure.
  25
  26 CMS_add0_recipient_key() adds symmetric key B<key> of length B<keylen> using
  27 wrapping algorithm B<nid>, identifier B<id> of length B<idlen> and optional
  28 values B<date>, B<otherTypeId> and B<otherType> to CMS_ContentInfo enveloped
  29 data structure B<cms> as a KEKRecipientInfo structure.
  30
  31 The CMS_ContentInfo structure should be obtained from an initial call to
  32 CMS_encrypt() with the flag B<CMS_PARTIAL> set.
  33
  34 =head1 NOTES
  35
  36 The main purpose of this function is to provide finer control over a CMS
  37 enveloped data structure where the simpler CMS_encrypt() function defaults are
  38 not appropriate. For example if one or more KEKRecipientInfo structures
  39 need to be added. New attributes can also be added using the returned
  40 CMS_RecipientInfo structure and the CMS attribute utility functions.
  41
  42 OpenSSL will by default identify recipient certificates using issuer name
  43 and serial number. If B<CMS_USE_KEYID> is set it will use the subject key
  44 identifier value instead. An error occurs if all recipient certificates do not
  45 have a subject key identifier extension.
  46
  47 Currently only AES based key wrapping algorithms are supported for B<nid>,
  48 specifically: NID_id_aes128_wrap, NID_id_aes192_wrap and NID_id_aes256_wrap.
  49 If B<nid> is set to B<NID_undef> then an AES wrap algorithm will be used
  50 consistent with B<keylen>.
  51
  52 =head1 RETURN VALUES
  53
  54 CMS_add1_recipient_cert() and CMS_add0_recipient_key() return an internal
  55 pointer to the CMS_RecipientInfo structure just added or NULL if an error
  56 occurs.
  57
  58 =head1 SEE ALSO
  59
  60 L<ERR_get_error(3)>, L<CMS_decrypt(3)>,
  61 L<CMS_final(3)>,
  62
  63 =head1 COPYRIGHT
  64
  65 Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
  66
  67 Licensed under the Apache License 2.0 (the "License").  You may not use
  68 this file except in compliance with the License.  You can obtain a copy
  69 in the file LICENSE in the source distribution or at
  70 L<https://www.openssl.org/source/license.html>.
  71
  72 =cut