.Dd $Mdocdate: November 11 2015 $
.Dt CMS_ADD1_RECIPIENT_CERT 3
.Os
.Sh NAME
.Nm CMS_add1_recipient_cert ,
.Nm CMS_add0_recipient_key
.Nd add recipients to a CMS enveloped data structure
.Sh SYNOPSIS
.In openssl/cms.h
.Ft CMS_RecipientInfo *
.Fo CMS_add1_recipient_cert
.Fa "CMS_ContentInfo *cms"
.Fa "X509 *recip"
.Fa "unsigned int flags"
.Fc
.Ft CMS_RecipientInfo *
.Fo CMS_add0_recipient_key
.Fa "CMS_ContentInfo *cms"
.Fa "int nid"
.Fa "unsigned char *key"
.Fa "size_t keylen"
.Fa "unsigned char *id"
.Fa "size_t idlen"
.Fa "ASN1_GENERALIZEDTIME *date"
.Fa "ASN1_OBJECT *otherTypeId"
.Fa "ASN1_TYPE *otherType"
.Fc
.Sh DESCRIPTION
.Fn CMS_add1_recipient_cert
adds recipient
.Fa recip
to the
.Vt CMS_ContentInfo
enveloped data structure
.Fa cms
as a KeyTransRecipientInfo structure.
.Pp
.Fn CMS_add0_recipient_key
adds the symmetric key
.Fa key
of length
.Fa keylen
using the wrapping algorithm
.Fa nid ,
identifier
.Fa id
of length
.Fa idlen
and optional values
.Fa date ,
.Fa otherTypeId ,
and
.Fa otherType
to the
.Vt CMS_ContentInfo
enveloped data structure
.Fa cms
as a KEKRecipientInfo structure.
.Pp
The
.Vt CMS_ContentInfo
structure should be obtained from an initial call to
.Xr CMS_encrypt 3
with the flag
.Dv CMS_PARTIAL
set.
.Sh NOTES
The main purpose of this function is to provide finer control over a CMS
enveloped data structure where the simpler
.Xr CMS_encrypt 3
function defaults are not appropriate.
For example if one or more KEKRecipientInfo structures need to be added.
New attributes can also be added using the returned
.Vt CMS_RecipientInfo
structure and the CMS attribute utility functions.
.Pp
OpenSSL will by default identify recipient certificates using issuer
name and serial number.
If
.Dv CMS_USE_KEYID
is set, it will use the subject key identifier value instead.
An error occurs if all recipient certificates do not have a subject key
identifier extension.
.Pp
Currently only AES based key wrapping algorithms are supported for
.Fa nid ,
specifically:
.Dv NID_id_aes128_wrap ,
.Dv NID_id_aes192_wrap ,
and
.Dv NID_id_aes256_wrap .
If
.Fa nid
is set to
.Dv NID_undef ,
then an AES wrap algorithm will be used consistent with
.Fa keylen .
.Sh RETURN VALUES
.Fn CMS_add1_recipient_cert
and
.Fn CMS_add0_recipient_key
return an internal pointer to the
.Vt CMS_RecipientInfo
structure just added or
.Dv NULL
if an error occurs.
.Sh SEE ALSO
.Xr CMS_decrypt 3 ,
.Xr CMS_final 3 ,
.Xr ERR_get_error 3
.Sh HISTORY
.Fn CMS_add1_recipient_cert
and
.Fn CMS_add0_recipient_key
were added to OpenSSL 0.9.8.