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

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

<h1>PKCS7_encrypt(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="#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_encrypt - create a PKCS#7 envelopedData structure

</P>
<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
<PRE> #include &lt;openssl/pkcs7.h&gt;
</PRE>
<PRE> PKCS7 *PKCS7_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, int flags);
</PRE>
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
<CODE>PKCS7_encrypt()</CODE> creates and returns a PKCS#7 envelopedData
structure. <STRONG>certs</STRONG>
is a list of recipient certificates. <STRONG>in</STRONG> is the content to be encrypted.
<STRONG>cipher</STRONG> is the symmetric cipher to use. <STRONG>flags</STRONG> is an optional set of flags.

</P>
<P>
<HR>
<H1><A NAME="NOTES">NOTES</A></H1>
<P>
Only RSA keys are supported in PKCS#7 and envelopedData so the recipient
certificates supplied to this function must all contain RSA public keys,
though they do not have to be signed using the RSA algorithm.

</P>
<P>
<CODE>EVP_des_ede3_cbc()</CODE> (triple DES) is the algorithm of choice for
S/MIME use because most clients will support it.

</P>
<P>
Some old ``export grade'' clients may only support weak encryption using 40
or 64 bit RC2. These can be used by passing <CODE>EVP_rc2_40_cbc()</CODE>
and <CODE>EVP_rc2_64_cbc()</CODE> respectively.

</P>
<P>
The algorithm passed in the <STRONG>cipher</STRONG> parameter must support ASN1 encoding of its parameters. 

</P>
<P>
Many browsers implement a ``sign and encrypt'' option which is simply an
S/MIME envelopedData containing an S/MIME signed message. This can be
readily produced by storing the S/MIME signed message in a memory BIO and
passing it to <CODE>PKCS7_encrypt().</CODE>

</P>
<P>
The following flags can be passed in the <STRONG>flags</STRONG> parameter.

</P>
<P>
If the <STRONG>PKCS7_TEXT</STRONG> flag is set MIME headers for type <STRONG>text/plain</STRONG> are prepended to the data.

</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. If <STRONG>PKCS7_BINARY</STRONG> is set then
<STRONG>PKCS7_TEXT</STRONG> is ignored.

</P>
<P>
If the <STRONG>PKCS7_STREAM</STRONG> flag is set a partial <STRONG>PKCS7</STRONG> structure is output suitable for streaming I/O: no data is read from the
BIO <STRONG>in</STRONG>.

</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>
<HR>
<H1><A NAME="RETURN_VALUES">RETURN VALUES</A></H1>
<P>
<CODE>PKCS7_encrypt()</CODE> returns either a 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_decrypt.html#">PKCS7_decrypt(3)</A>



</P>
<P>
<HR>
<H1><A NAME="HISTORY">HISTORY</A></H1>
<P>
<CODE>PKCS7_decrypt()</CODE> was added to OpenSSL 0.9.5 The <STRONG>PKCS7_STREAM</STRONG> flag was first supported in OpenSSL 1.0.0.

</P>
:}