1.\" $OpenBSD: PKCS7_encrypt.3,v 1.11 2020/06/03 13:41:27 schwarze Exp $ 2.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 3.\" 4.\" This file was written by Dr. Stephen Henson <steve@openssl.org>. 5.\" Copyright (c) 2002, 2006, 2007, 2008, 2009 The OpenSSL Project. 6.\" All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in 17.\" the documentation and/or other materials provided with the 18.\" distribution. 19.\" 20.\" 3. All advertising materials mentioning features or use of this 21.\" software must display the following acknowledgment: 22.\" "This product includes software developed by the OpenSSL Project 23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 24.\" 25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 26.\" endorse or promote products derived from this software without 27.\" prior written permission. For written permission, please contact 28.\" openssl-core@openssl.org. 29.\" 30.\" 5. Products derived from this software may not be called "OpenSSL" 31.\" nor may "OpenSSL" appear in their names without prior written 32.\" permission of the OpenSSL Project. 33.\" 34.\" 6. Redistributions of any form whatsoever must retain the following 35.\" acknowledgment: 36.\" "This product includes software developed by the OpenSSL Project 37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 38.\" 39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 50.\" OF THE POSSIBILITY OF SUCH DAMAGE. 51.\" 52.Dd $Mdocdate: June 3 2020 $ 53.Dt PKCS7_ENCRYPT 3 54.Os 55.Sh NAME 56.Nm PKCS7_encrypt 57.Nd create a PKCS#7 envelopedData structure 58.Sh SYNOPSIS 59.In openssl/pkcs7.h 60.Ft PKCS7 * 61.Fo PKCS7_encrypt 62.Fa "STACK_OF(X509) *certs" 63.Fa "BIO *in" 64.Fa "const EVP_CIPHER *cipher" 65.Fa "int flags" 66.Fc 67.Sh DESCRIPTION 68.Fn PKCS7_encrypt 69creates and returns a PKCS#7 envelopedData structure. 70.Fa certs 71is a list of recipient certificates. 72.Fa in 73is the content to be encrypted. 74.Fa cipher 75is the symmetric cipher to use. 76.Fa flags 77is an optional set of flags. 78.Pp 79Only RSA keys are supported in PKCS#7 and envelopedData so the recipient 80certificates supplied to this function must all contain RSA public keys, 81though they do not have to be signed using the RSA algorithm. 82.Pp 83The algorithm passed in the 84.Fa cipher 85parameter must support ASN.1 encoding of its parameters. 86.Pp 87Many browsers implement a "sign and encrypt" option which is simply an 88S/MIME envelopedData containing an S/MIME signed message. 89This can be readily produced by storing the S/MIME signed message in a 90memory 91.Vt BIO 92and passing it to 93.Fn PKCS7_encrypt . 94.Pp 95The following flags can be passed in the 96.Fa flags 97parameter. 98.Pp 99If the 100.Dv PKCS7_TEXT 101flag is set, MIME headers for type 102.Sy text/plain 103are prepended to the data. 104.Pp 105Normally the supplied content is translated into MIME canonical format 106(as required by the S/MIME specifications). 107If 108.Dv PKCS7_BINARY 109is set, no translation occurs. 110This option should be used if the supplied data is in binary format; 111otherwise, the translation will corrupt it. 112If 113.Dv PKCS7_BINARY 114is set, then 115.Dv PKCS7_TEXT 116is ignored. 117.Pp 118If the 119.Dv PKCS7_STREAM 120flag is set, a partial 121.Vt PKCS7 122structure is output suitable for streaming I/O: no data is read from 123.Fa in . 124.Pp 125If the flag 126.Dv PKCS7_STREAM 127is set, the returned 128.Vt PKCS7 129structure is 130.Sy not 131complete and outputting its contents via a function that does not 132properly finalize the 133.Vt PKCS7 134structure will give unpredictable results. 135.Pp 136Several functions including 137.Xr PKCS7_final 3 , 138.Xr SMIME_write_PKCS7 3 , 139.Xr PEM_write_bio_PKCS7_stream 3 , 140and 141.Xr i2d_PKCS7_bio_stream 3 142finalize the structure. 143Alternatively finalization can be performed by obtaining the streaming 144ASN.1 145.Vt BIO 146directly using 147.Fn BIO_new_PKCS7 . 148.Sh RETURN VALUES 149.Fn PKCS7_encrypt 150returns either a 151.Vt PKCS7 152structure or 153.Dv NULL 154if an error occurred. 155The error can be obtained from 156.Xr ERR_get_error 3 . 157.Sh SEE ALSO 158.Xr PKCS7_decrypt 3 , 159.Xr PKCS7_final 3 , 160.Xr PKCS7_new 3 , 161.Xr PKCS7_sign 3 162.Sh HISTORY 163.Fn PKCS7_encrypt 164first appeared in OpenSSL 0.9.5 and has been available since 165.Ox 2.7 . 166.Pp 167The 168.Dv PKCS7_STREAM 169flag was first supported in OpenSSL 1.0.0. 170