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

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

<h1>PKCS7_sign(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="#NOTES">NOTES</A>
	<LI><A HREF="#BUGS">BUGS</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 - create a PKCS#7 signedData structure

</P>
<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
<PRE> #include &lt;openssl/pkcs7.h&gt;
</PRE>
<PRE> PKCS7 *PKCS7_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, int flags);
</PRE>
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
<CODE>PKCS7_sign()</CODE> creates and returns a PKCS#7 signedData
structure. <STRONG>signcert</STRONG> is the certificate to sign with, <STRONG>pkey</STRONG> is the corresponsding private key.
<STRONG>certs</STRONG> is an optional additional set of certificates to include in the PKCS#7
structure (for example any intermediate CAs in the chain). 

</P>
<P>
The data to be signed is read from BIO <STRONG>data</STRONG>.

</P>
<P>
<STRONG>flags</STRONG> is an optional set of flags.

</P>
<P>
<HR>
<H1><A NAME="NOTES">NOTES</A></H1>
<P>
Any of the following flags (ored together) can be passed in the <STRONG>flags</STRONG>
parameter.

</P>
<P>
Many S/MIME clients expect the signed content to include valid MIME
headers. If the <STRONG>PKCS7_TEXT</STRONG> flag is set MIME headers for type <STRONG>text/plain</STRONG> are prepended to the data.

</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 data being signed is included in the PKCS7 structure, unless
<STRONG>PKCS7_DETACHED</STRONG> is set in which case it is omitted. This is used for PKCS7 detached
signatures which are used in S/MIME plaintext signed messages for example.

</P>
<P>
Normally the supplied content is translated into MIME canonical format (as
required by the S/MIME specifications) if <STRONG>PKCS7_BINARY</STRONG> is set no translation occurs. This option should be used if the supplied
data is in binary format otherwise the translation will corrupt it.

</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>
If the flags <STRONG>PKCS7_STREAM</STRONG> is set then the returned <STRONG>PKCS7</STRONG> structure is just initialized ready to perform the signing operation. The
signing is however
<STRONG>not</STRONG> performed and the data to be signed is not read from the <STRONG>data</STRONG>
parameter. Signing is deferred until after the data has been written. In
this way data can be signed in a single pass.

</P>
<P>
If the <STRONG>PKCS7_PARTIAL</STRONG> flag is set a partial <STRONG>PKCS7</STRONG> structure is output to which additional signers and capabilities can be
added before finalization.

</P>
<P>
<HR>
<H1><A NAME="NOTES">NOTES</A></H1>
<P>
If the flag <STRONG>PKCS7_STREAM</STRONG> is set the returned <STRONG>PKCS7</STRONG> structure is <STRONG>not</STRONG>
complete and outputting its contents via a function that does not properly
finalize the <STRONG>PKCS7</STRONG> structure will give unpredictable results.

</P>
<P>
Several functions including <CODE>SMIME_write_PKCS7(),</CODE>
<CODE>i2d_PKCS7_bio_stream(),</CODE>
<CODE>PEM_write_bio_PKCS7_stream()</CODE> finalize the structure.
Alternatively finalization can be performed by obtaining the streaming ASN1 <STRONG>BIO</STRONG> directly using <CODE>BIO_new_PKCS7().</CODE>

</P>
<P>
If a signer is specified it will use the default digest for the signing
algorithm. This is <STRONG>SHA1</STRONG> for both RSA and DSA keys.

</P>
<P>
In OpenSSL 1.0.0 the <STRONG>certs</STRONG>, <STRONG>signcert</STRONG> and <STRONG>pkey</STRONG> parameters can all be
<STRONG>NULL</STRONG> if the <STRONG>PKCS7_PARTIAL</STRONG> flag is set. One or more signers can be added using the function <STRONG>PKCS7_sign_add_signer()</STRONG>. <STRONG>PKCS7_final()</STRONG> must also be called to finalize the structure if streaming is not enabled.
Alternative signing digests can also be specified using this method.

</P>
<P>
In OpenSSL 1.0.0 if <STRONG>signcert</STRONG> and <STRONG>pkey</STRONG> are NULL then a certificates only PKCS#7 structure is output.

</P>
<P>
In versions of OpenSSL before 1.0.0 the <STRONG>signcert</STRONG> and <STRONG>pkey</STRONG> parameters must
<STRONG>NOT</STRONG> be NULL.

</P>
<P>
<HR>
<H1><A NAME="BUGS">BUGS</A></H1>
<P>
Some advanced attributes such as counter signatures are not supported.

</P>
<P>
<HR>
<H1><A NAME="RETURN_VALUES">RETURN VALUES</A></H1>
<P>
<CODE>PKCS7_sign()</CODE> returns either a valid PKCS7 structure or NULL if
an error occurred. The error can be obtained from
<CODE>ERR_get_error(3).</CODE>

</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_verify.html#">PKCS7_verify(3)</A>



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

</P>
<P>
The <STRONG>PKCS7_PARTIAL</STRONG> flag was added in OpenSSL 1.0.0

</P>
<P>
The <STRONG>PKCS7_STREAM</STRONG> flag was added in OpenSSL 1.0.0

</P>
:}