165 lines
8.3 KiB
HTML
Executable File
165 lines
8.3 KiB
HTML
Executable File
<?xml version="1.0" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>CMS_get0_RecipientInfos</title>
|
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
|
<link rev="made" href="mailto:root@localhost" />
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
|
|
<!-- INDEX BEGIN -->
|
|
<div name="index">
|
|
<p><a name="__index__"></a></p>
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<li><a href="#notes">NOTES</a></li>
|
|
<li><a href="#return_values">RETURN VALUES</a></li>
|
|
<li><a href="#see_also">SEE ALSO</a></li>
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
</ul>
|
|
|
|
<hr name="index" />
|
|
</div>
|
|
<!-- INDEX END -->
|
|
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>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_RecipientInfo_encrypt
|
|
- CMS envelopedData RecipientInfo routines</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
#include <openssl/cms.h></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);
|
|
int CMS_RecipientInfo_encrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>The function CMS_get0_RecipientInfos() 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>CMS_RecipientInfo_ktri_get0_signer_id() 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>CMS_RecipientInfo_set0_pkey() 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>CMS_RecipientInfo_kekri_get0_id() 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>CMS_RecipientInfo_set0_key() 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><code>CMS_RecipientInfo_encrypt()</code> attempts to encrypt CMS_RecipientInfo structure
|
|
<strong>ri</strong> in structure <strong>cms</strong>. A key must have been associated with the structure
|
|
first and the content encryption key must be available: for example by a
|
|
previous call to <code>CMS_RecipientInfo_decrypt()</code>.</p>
|
|
<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 CMS_get0_RecipientInfos() and check the type of each using
|
|
<code>CMS_RecipientInfo_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_RecipientInfo_decrypt()</code> called. If successful <code>CMS_decrypt()</code> can be called
|
|
with a NULL key to decrypt the enveloped content.</p>
|
|
<p>The <code>CMS_RecipientInfo_encrypt()</code> can be used to add a new recipient to an
|
|
existing enveloped data structure. Typically an application will first decrypt
|
|
an appropriate CMS_RecipientInfo structure to make the content encrypt key
|
|
available, it will then add a new recipient using a function such as
|
|
CMS_add1_recipient_cert() and finally encrypt the content encryption key
|
|
using <code>CMS_RecipientInfo_encrypt()</code>.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="return_values">RETURN VALUES</a></h1>
|
|
<p>CMS_get0_RecipientInfos() returns all CMS_RecipientInfo structures, or NULL if
|
|
an error occurs.</p>
|
|
<p>CMS_RecipientInfo_ktri_get0_signer_id(), CMS_RecipientInfo_set0_pkey(),
|
|
CMS_RecipientInfo_kekri_get0_id(), CMS_RecipientInfo_set0_key() and
|
|
<code>CMS_RecipientInfo_decrypt()</code> return 1 for success or 0 if an error occurs.
|
|
<code>CMS_RecipientInfo_encrypt()</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 <em>ERR_get_error(3)</em>.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
|
<p><em>ERR_get_error(3)</em>, <em>CMS_decrypt(3)</em></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.</p>
|
|
<p>Licensed under the Apache License 2.0 (the "License"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file LICENSE in the source distribution or at
|
|
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
|
|
|
</body>
|
|
|
|
</html>
|