.Dd $Mdocdate: November 11 2015 $
.Dt CMS_ADD0_CERT 3
.Os
.Sh NAME
.Nm CMS_add0_cert ,
.Nm CMS_add1_cert ,
.Nm CMS_get1_certs ,
.Nm CMS_add0_crl ,
.Nm CMS_add1_crl ,
.Nm CMS_get1_crls
.Nd CMS certificate and CRL utility functions
.Sh SYNOPSIS
.In openssl/cms.h
.Ft int
.Fo CMS_add0_cert
.Fa "CMS_ContentInfo *cms"
.Fa "X509 *cert"
.Fc
.Ft int
.Fo CMS_add1_cert
.Fa "CMS_ContentInfo *cms"
.Fa "X509 *cert"
.Fc
.Ft STACK_OF(X509) *
.Fo CMS_get1_certs
.Fa "CMS_ContentInfo *cms"
.Fc
.Ft int
.Fo CMS_add0_crl
.Fa "CMS_ContentInfo *cms"
.Fa "X509_CRL *crl"
.Fc
.Ft int
.Fo CMS_add1_crl
.Fa "CMS_ContentInfo *cms"
.Fa "X509_CRL *crl"
.Fc
.Ft STACK_OF(X509_CRL) *
.Fo CMS_get1_crls
.Fa "CMS_ContentInfo *cms"
.Fc
.Sh DESCRIPTION
.Fn CMS_add0_cert
and
.Fn CMS_add1_cert
add certificate
.Fa cert
to
.Fa cms .
.Fa cms
must be of type signed data or enveloped data.
.Pp
.Fn CMS_get1_certs
returns all certificates in
.Fa cms .
.Pp
.Fn CMS_add0_crl
and
.Fn CMS_add1_crl
add CRL
.Fa crl
to
.Fa cms .
.Fn CMS_get1_crls
returns any CRLs in
.Fa cms .
.Sh NOTES
The
.Vt CMS_ContentInfo
structure
.Fa cms
must be of type signed data or enveloped data or an error will be
returned.
.Pp
For signed data, certificates and CRLs are added to the
.Fa certificates
and
.Fa crls
fields of the SignedData structure.
For enveloped data, they are added to
.Fa OriginatorInfo .
.Pp
As the
.Sq 0
implies,
.Fn CMS_add0_cert
adds
.Fa cert
internally to
.Fa cms
and it must not be freed up after the call, as opposed to
.Fn CMS_add1_cert
where
.Fa cert
must be freed up.
.Pp
The same certificate or CRL must not be added to the same cms structure
more than once.
.Sh RETURN VALUES
.Fn CMS_add0_cert ,
.Fn CMS_add1_cert ,
.Fn CMS_add0_crl ,
and
.Fn CMS_add1_crl
return 1 for success and 0 for failure.
.Pp
.Fn CMS_get1_certs
and
.Fn CMS_get1_crls
return the STACK of certificates or CRLs or
.Dv NULL
if there are none or an error occurs.
The only error which will occur in practice is if the
.Fa cms
type is invalid.
.Sh SEE ALSO
.Xr CMS_encrypt 3 ,
.Xr CMS_sign 3 ,
.Xr ERR_get_error 3
.Sh HISTORY
.Fn CMS_add0_cert ,
.Fn CMS_add1_cert ,
.Fn CMS_get1_certs ,
.Fn CMS_add0_crl
and
.Fn CMS_get1_crls
were all first added to OpenSSL 0.9.8.