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

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

<h1>PKCS7_sign_add_signer(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>
<P>
PKCS7_sign_add_signer - add a signer PKCS7 signed data structure.

</P>
<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
<PRE> #include &lt;openssl/pkcs7.h&gt;
</PRE>
<PRE> PKCS7_SIGNER_INFO *PKCS7_sign_add_signer(PKCS7 *p7, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, int flags);
</PRE>
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
<CODE>PKCS7_sign_add_signer()</CODE> adds a signer with certificate <STRONG>signcert</STRONG> and private key <STRONG>pkey</STRONG> using message digest <STRONG>md</STRONG> to a PKCS7 signed data structure
<STRONG>p7</STRONG>.

</P>
<P>
The PKCS7 structure should be obtained from an initial call to
<CODE>PKCS7_sign()</CODE> with the flag <STRONG>PKCS7_PARTIAL</STRONG> set or in the case or re-signing a valid PKCS7 signed data structure.

</P>
<P>
If the <STRONG>md</STRONG> parameter is <STRONG>NULL</STRONG> then the default digest for the public key algorithm will be used.

</P>
<P>
Unless the <STRONG>PKCS7_REUSE_DIGEST</STRONG> flag is set the returned PKCS7 structure is not complete and must be
finalized either by streaming (if applicable) or a call to
<CODE>PKCS7_final().</CODE>

</P>
<P>
<HR>
<H1><A NAME="NOTES">NOTES</A></H1>
<P>
The main purpose of this function is to provide finer control over a PKCS#7
signed data structure where the simpler <CODE>PKCS7_sign()</CODE> function
defaults are not appropriate. For example if multiple signers or non
default digest algorithms are needed.

</P>
<P>
Any of the following flags (ored together) can be passed in the <STRONG>flags</STRONG>
parameter.

</P>
<P>
If <STRONG>PKCS7_REUSE_DIGEST</STRONG> is set then an attempt is made to copy the content digest value from the
PKCS7 struture: to add a signer to an existing structure. An error occurs
if a matching digest value cannot be found to copy. The returned PKCS7
structure will be valid and finalized when this flag is set.

</P>
<P>
If <STRONG>PKCS7_PARTIAL</STRONG> is set in addition to <STRONG>PKCS7_REUSE_DIGEST</STRONG> then the 
<STRONG>PKCS7_SIGNER_INO</STRONG> structure will not be finalized so additional attributes can be added. In
this case an explicit call to <CODE>PKCS7_SIGNER_INFO_sign()</CODE> is
needed to finalize it.

</P>
<P>
If <STRONG>PKCS7_NOCERTS</STRONG> is set the signer's certificate will not be included in the PKCS7
structure, the signer's certificate must still be supplied in the
<STRONG>signcert</STRONG> parameter though. This can reduce the size of the signature if the signers
certificate can be obtained by other means: for example a previously signed
message.

</P>
<P>
The signedData structure includes several PKCS#7 autenticatedAttributes
including the signing time, the PKCS#7 content type and the supported list
of ciphers in an SMIMECapabilities attribute. If <STRONG>PKCS7_NOATTR</STRONG> is set then no authenticatedAttributes will be used. If <STRONG>PKCS7_NOSMIMECAP</STRONG> is set then just the SMIMECapabilities are omitted.

</P>
<P>
If present the SMIMECapabilities attribute indicates support for the
following algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit
RC2. If any of these algorithms is disabled then it will not be included.

</P>
<P>
<CODE>PKCS7_sign_add_signers()</CODE> returns an internal pointer to the
PKCS7_SIGNER_INFO structure just added, this can be used to set additional
attributes before it is finalized.

</P>
<P>
<HR>
<H1><A NAME="RETURN_VALUES">RETURN VALUES</A></H1>
<P>
<CODE>PKCS7_sign_add_signers()</CODE> returns an internal pointer to the
PKCS7_SIGNER_INFO structure just added or NULL if an error occurs.

</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/PKCS7_sign.html#">PKCS7_sign(3)</A>,
<EM>PKCS7_final(3)</EM>,

</P>
<P>
<HR>
<H1><A NAME="HISTORY">HISTORY</A></H1>
<P>
<CODE>PPKCS7_sign_add_signer()</CODE> was added to OpenSSL 1.0.0

</P>
:}