#use wml::openssl-macros area=docs page=CMS_get0_RecipientInfos

<title>Documents, CMS_get0_RecipientInfos(3)</title>

<h1>CMS_get0_RecipientInfos(3)</h1>

#use wml::imp::generic

{:
## What's this? [[s|(<STRONG>[^<].+?)</A>(</STRONG><DD>)|$1$2|sg]]
[[s|<P>\s+<P>|<P>|sg]]
[[s|<P>\s+</|</|sg]]
[[s|<DD>\s*<DT>|<DD>&nbsp;<DT>|sg]]
[[s|<DD>\s*</DL>|<DD>&nbsp;</DL>|sg]]
[[s|\[|&#91;|sg]]
[[s|\]|&#93;|sg]]

<!-- INDEX BEGIN -->

<UL>

	<LI><A HREF="#NAME">NAME</A>
	<LI><A HREF="#SYNOPSIS">SYNOPSIS</A>
	<LI><A HREF="#DESCRIPTION">DESCRIPTION</A>
	<LI><A HREF="#NOTES">NOTES</A>
	<LI><A HREF="#RETURN_VALUES">RETURN VALUES</A>
	<LI><A HREF="#SEE_ALSO">SEE ALSO</A>
	<LI><A HREF="#HISTORY">HISTORY</A>
</UL>
<!-- INDEX END -->

<HR>
<P>
<HR>
<H1><A NAME="NAME">NAME</A></H1>
<PRE> CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_signer_id,CMS_RecipientInfo_ktri_cert_cmp, CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, CMS_RecipientInfo_decrypt - CMS envelopedData RecipientInfo routines
</PRE>
<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
<PRE> #include &lt;openssl/cms.h&gt;
</PRE>
<PRE> STACK_OF(CMS_RecipientInfo) *CMS_get0_RecipientInfos(CMS_ContentInfo *cms);
 int CMS_RecipientInfo_type(CMS_RecipientInfo *ri);
</PRE>
<PRE> int CMS_RecipientInfo_ktri_get0_signer_id(CMS_RecipientInfo *ri, ASN1_OCTET_STRING **keyid, X509_NAME **issuer, ASN1_INTEGER **sno);
 int CMS_RecipientInfo_ktri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert);
 int CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pkey);
</PRE>
<PRE> int CMS_RecipientInfo_kekri_get0_id(CMS_RecipientInfo *ri, X509_ALGOR **palg, ASN1_OCTET_STRING **pid, ASN1_GENERALIZEDTIME **pdate, ASN1_OBJECT **potherid, ASN1_TYPE **pothertype);
 int CMS_RecipientInfo_kekri_id_cmp(CMS_RecipientInfo *ri, const unsigned char *id, size_t idlen);
 int CMS_RecipientInfo_set0_key(CMS_RecipientInfo *ri, unsigned char *key, size_t keylen);
</PRE>
<PRE> int CMS_RecipientInfo_decrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
</PRE>
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
The function <CODE>CMS_get0_RecipientInfos()</CODE> returns all the
CMS_RecipientInfo structures associated with a CMS EnvelopedData structure.

</P>
<P>
<CODE>CMS_RecipientInfo_type()</CODE> returns the type of CMS_RecipientInfo
structure <STRONG>ri</STRONG>. It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE,
CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, or CMS_RECIPINFO_OTHER.

</P>
<P>
<CODE>CMS_RecipientInfo_ktri_get0_signer_id()</CODE> retrieves the
certificate recipient identifier associated with a specific
CMS_RecipientInfo structure <STRONG>ri</STRONG>, which must be of type CMS_RECIPINFO_TRANS. Either the keyidentifier will
be set in
<STRONG>keyid</STRONG> or <STRONG>both</STRONG> issuer name and serial number in <STRONG>issuer</STRONG> and <STRONG>sno</STRONG>. 

</P>
<P>
<CODE>CMS_RecipientInfo_ktri_cert_cmp()</CODE> compares the certificate <STRONG>cert</STRONG> against the CMS_RecipientInfo structure <STRONG>ri</STRONG>, which must be of type CMS_RECIPINFO_TRANS. It returns zero if the
comparison is successful and non zero if not.

</P>
<P>
<CODE>CMS_RecipientInfo_set0_pkey()</CODE> associates the private key <STRONG>pkey</STRONG> with the CMS_RecipientInfo structure <STRONG>ri</STRONG>, which must be of type CMS_RECIPINFO_TRANS.

</P>
<P>
<CODE>CMS_RecipientInfo_kekri_get0_id()</CODE> retrieves the key
information from the CMS_RecipientInfo structure <STRONG>ri</STRONG> which must be of type CMS_RECIPINFO_KEK. Any of the remaining parameters
can be NULL if the application is not interested in the value of a field.
Where a field is optional and absent NULL will be written to the
corresponding parameter. The keyEncryptionAlgorithm field is written to
<STRONG>palg</STRONG>, the <STRONG>keyIdentifier</STRONG> field is written to <STRONG>pid</STRONG>, the <STRONG>date</STRONG> field if present is written to <STRONG>pdate</STRONG>, if the <STRONG>other</STRONG> field is present the components
<STRONG>keyAttrId</STRONG> and <STRONG>keyAttr</STRONG> are written to parameters <STRONG>potherid</STRONG> and
<STRONG>pothertype</STRONG>.

</P>
<P>
<CODE>CMS_RecipientInfo_kekri_id_cmp()</CODE> compares the ID in the <STRONG>id</STRONG> and <STRONG>idlen</STRONG>
parameters against the <STRONG>keyIdentifier</STRONG> CMS_RecipientInfo structure <STRONG>ri</STRONG>, which must be of type CMS_RECIPINFO_KEK. It returns zero if the
comparison is successful and non zero if not.

</P>
<P>
<CODE>CMS_RecipientInfo_set0_key()</CODE> associates the symmetric key <STRONG>key</STRONG> of length
<STRONG>keylen</STRONG> with the CMS_RecipientInfo structure <STRONG>ri</STRONG>, which must be of type CMS_RECIPINFO_KEK.

</P>
<P>
<CODE>CMS_RecipientInfo_decrypt()</CODE> attempts to decrypt
CMS_RecipientInfo structure
<STRONG>ri</STRONG> in structure <STRONG>cms</STRONG>. A key must have been associated with the structure first.

</P>
<P>
<HR>
<H1><A NAME="NOTES">NOTES</A></H1>
<P>
The main purpose of these functions is to enable an application to lookup
recipient keys using any appropriate technique when the simpler method of
<CODE>CMS_decrypt()</CODE> is not appropriate.

</P>
<P>
In typical usage and application will retrieve all CMS_RecipientInfo
structures using <CODE>CMS_get0_RecipientInfos()</CODE> and check the type
of each using <CODE>CMS_RecpientInfo_type().</CODE> Depending on the type
the CMS_RecipientInfo structure can be ignored or its key identifier data
retrieved using an appropriate function. Then if the corresponding secret
or private key can be obtained by any appropriate means it can then
associated with the structure and <CODE>CMS_RecpientInfo_decrypt()</CODE>
called. If successful <CODE>CMS_decrypt()</CODE> can be called with a NULL
key to decrypt the enveloped content.

</P>
<P>
<HR>
<H1><A NAME="RETURN_VALUES">RETURN VALUES</A></H1>
<P>
<CODE>CMS_get0_RecipientInfos()</CODE> returns all CMS_RecipientInfo
structures, or NULL if an error occurs.

</P>
<P>
<CODE>CMS_RecipientInfo_ktri_get0_signer_id(),</CODE>
<CODE>CMS_RecipientInfo_set0_pkey(),</CODE>
<CODE>CMS_RecipientInfo_kekri_get0_id(),</CODE>
<CODE>CMS_RecipientInfo_set0_key()</CODE> and
<CODE>CMS_RecipientInfo_decrypt()</CODE> return 1 for success or 0 if an
error occurs.

</P>
<P>
<CODE>CMS_RecipientInfo_ktri_cert_cmp()</CODE> and
<CODE>CMS_RecipientInfo_kekri_cmp()</CODE> return 0 for a successful
comparison and non zero otherwise.

</P>
<P>
Any error can be obtained from <A HREF="../crypto/ERR_get_error.html#">ERR_get_error(3)</A>.

</P>
<P>
<HR>
<H1><A NAME="SEE_ALSO">SEE ALSO</A></H1>
<P>
<A HREF="../crypto/ERR_get_error.html#">ERR_get_error(3)</A>, <A HREF="../crypto/CMS_decrypt.html#">CMS_decrypt(3)</A>



</P>
<P>
<HR>
<H1><A NAME="HISTORY">HISTORY</A></H1>
<P>
These functions were first was added to OpenSSL 0.9.8

</P>
:}