.Dd $Mdocdate: November 11 2015 $
.Dt CMS_GET0_SIGNERINFOS 3
.Os
.Sh NAME
.Nm CMS_get0_SignerInfos ,
.Nm CMS_SignerInfo_get0_signer_id ,
.Nm CMS_SignerInfo_cert_cmp ,
.Nm CMS_set1_signer_certs
.Nd CMS signedData signer functions
.Sh SYNOPSIS
.In openssl/cms.h
.Ft STACK_OF(CMS_SignerInfo) *
.Fo CMS_get0_SignerInfos
.Fa "CMS_ContentInfo *cms"
.Fc
.Ft int
.Fo CMS_SignerInfo_get0_signer_id
.Fa "CMS_SignerInfo *si"
.Fa "ASN1_OCTET_STRING **keyid"
.Fa "X509_NAME **issuer"
.Fa "ASN1_INTEGER **sno"
.Fc
.Ft int
.Fo CMS_SignerInfo_cert_cmp
.Fa "CMS_SignerInfo *si"
.Fa "X509 *cert"
.Fc
.Ft void
.Fo CMS_SignerInfo_set1_signer_cert
.Fa "CMS_SignerInfo *si"
.Fa "X509 *signer"
.Fc
.Sh DESCRIPTION
The function
.Fn CMS_get0_SignerInfos
returns all the
.Vt CMS_SignerInfo
structures associated with a CMS signedData structure.
.Pp
.Fn CMS_SignerInfo_get0_signer_id
retrieves the certificate signer identifier associated with a specific
.Vt CMS_SignerInfo
structure
.Fa si .
Either the keyidentifier will be set in
.Fa keyid
or
.Em both
issuer name and serial number in
.Fa issuer
and
.Fa sno .
.Pp
.Fn CMS_SignerInfo_cert_cmp
compares the certificate
.Fa cert
against the signer identifier
.Fa si .
It returns zero if the comparison is successful and non zero if not.
.Pp
.Fn CMS_SignerInfo_set1_signer_cert
sets the signers certificate of
.Fa si
to
.Fa signer .
.Sh NOTES
The main purpose of these functions is to enable an application to
lookup signers certificates using any appropriate technique when the
simpler method of
.Xr CMS_verify 3
is not appropriate.
.Pp
In typical usage and application will retrieve all
.Vt CMS_SignerInfo
structures using
.Fn CMS_get0_SignerInfo
and retrieve the identifier information using CMS.
It will then obtain the signer certificate by some unspecified means
(or return and error if it cannot be found) and set it using
.Fn CMS_SignerInfo_set1_signer_cert .
.Pp
Once all signer certificates have been set,
.Xr CMS_verify 3
can be used.
.Pp
Although
.Fn CMS_get0_SignerInfos
can return
.Dv NULL
if an error occur
.Em or
if there are no signers, this is not a problem in practice because the
only error which can occur is if the
.Fa cms
structure is not of type signedData due to application error.
.Sh RETURN VALUES
.Fn CMS_get0_SignerInfos
returns all
.Vt CMS_SignerInfo
structures, or
.Dv NULL
if there are no signers or an error occurs.
.Pp
.Fn CMS_SignerInfo_get0_signer_id
returns 1 for success and 0 for failure.
.Pp
.Fn CMS_SignerInfo_cert_cmp
returns 0 for a successful comparison and non zero otherwise.
.Pp
.Fn CMS_SignerInfo_set1_signer_cert
does not return a value.
.Pp
Any error can be obtained from
.Xr ERR_get_error 3 .
.Sh SEE ALSO
.Xr CMS_verify 3 ,
.Xr ERR_get_error 3
.Sh HISTORY
These functions were first was added to OpenSSL 0.9.8.