1.\" $OpenBSD: SMIME_write_PKCS7.3,v 1.9 2021/12/14 15:46:48 schwarze Exp $ 2.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org> 8.\" 9.\" Permission to use, copy, modify, and distribute this software for any 10.\" purpose with or without fee is hereby granted, provided that the above 11.\" copyright notice and this permission notice appear in all copies. 12.\" 13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 20.\" 21.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>. 22.\" Copyright (c) 2002, 2003, 2006, 2007, 2015 The OpenSSL Project. 23.\" All rights reserved. 24.\" 25.\" Redistribution and use in source and binary forms, with or without 26.\" modification, are permitted provided that the following conditions 27.\" are met: 28.\" 29.\" 1. Redistributions of source code must retain the above copyright 30.\" notice, this list of conditions and the following disclaimer. 31.\" 32.\" 2. Redistributions in binary form must reproduce the above copyright 33.\" notice, this list of conditions and the following disclaimer in 34.\" the documentation and/or other materials provided with the 35.\" distribution. 36.\" 37.\" 3. All advertising materials mentioning features or use of this 38.\" software must display the following acknowledgment: 39.\" "This product includes software developed by the OpenSSL Project 40.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 41.\" 42.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 43.\" endorse or promote products derived from this software without 44.\" prior written permission. For written permission, please contact 45.\" openssl-core@openssl.org. 46.\" 47.\" 5. Products derived from this software may not be called "OpenSSL" 48.\" nor may "OpenSSL" appear in their names without prior written 49.\" permission of the OpenSSL Project. 50.\" 51.\" 6. Redistributions of any form whatsoever must retain the following 52.\" acknowledgment: 53.\" "This product includes software developed by the OpenSSL Project 54.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 55.\" 56.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 57.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 58.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 59.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 60.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 61.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 62.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 63.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 64.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 65.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 66.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 67.\" OF THE POSSIBILITY OF SUCH DAMAGE. 68.\" 69.Dd $Mdocdate: December 14 2021 $ 70.Dt SMIME_WRITE_PKCS7 3 71.Os 72.Sh NAME 73.Nm SMIME_write_PKCS7 74.Nd convert PKCS#7 structure to S/MIME format 75.Sh SYNOPSIS 76.In openssl/pkcs7.h 77.Ft int 78.Fo SMIME_write_PKCS7 79.Fa "BIO *out" 80.Fa "PKCS7 *p7" 81.Fa "BIO *data" 82.Fa "int flags" 83.Fc 84.Sh DESCRIPTION 85.Fn SMIME_write_PKCS7 86adds the appropriate MIME headers to a PKCS#7 structure to produce an 87S/MIME message. 88.Pp 89.Fa out 90is the 91.Vt BIO 92to write the data to. 93.Fa p7 94is the appropriate 95.Vt PKCS7 96structure. 97If streaming is enabled, then the content must be supplied in the 98.Fa data 99argument. 100.Fa flags 101is an optional set of flags. 102.Pp 103The following flags can be passed in the 104.Fa flags 105parameter. 106.Pp 107If 108.Dv PKCS7_DETACHED 109is set, then cleartext signing will be used. 110This option only makes sense for signedData where 111.Dv PKCS7_DETACHED 112is also set when 113.Xr PKCS7_sign 3 114is also called. 115.Pp 116If the 117.Dv PKCS7_TEXT 118flag is set, MIME headers for type 119.Sy text/plain 120are added to the content. 121This only makes sense if 122.Dv PKCS7_DETACHED 123is also set. 124.Pp 125If the 126.Dv PKCS7_STREAM 127flag is set, streaming is performed. 128This flag should only be set if 129.Dv PKCS7_STREAM 130was also set in the previous call to 131.Xr PKCS7_sign 3 132or 133.Xr PKCS7_encrypt 3 . 134.Pp 135The bit 136.Dv SMIME_OLDMIME 137is inverted before passing on the 138.Fa flags 139to 140.Xr SMIME_write_ASN1 3 . 141Consequently, if this bit is set in the 142.Fa flags 143argument, 144.Qq application/pkcs7-mime 145or 146.Qq application/pkcs7-signature 147is used in Content-Type headers. 148Otherwise, 149.Qq application/x-pkcs7-mime 150or 151.Qq application/x-pkcs7-signature 152is used. 153.Pp 154If cleartext signing is being used and 155.Dv PKCS7_STREAM 156is not set, then the data must be read twice: once to compute the 157signature in 158.Xr PKCS7_sign 3 159and once to output the S/MIME message. 160.Pp 161If streaming is performed, the content is output in BER format using 162indefinite length constructed encoding except in the case of signed 163data with detached content where the content is absent and DER 164format is used. 165.Sh RETURN VALUES 166Upon successful completion, 1 is returned; 167otherwise 0 is returned and an error code can be retrieved with 168.Xr ERR_get_error 3 . 169.Sh SEE ALSO 170.Xr i2d_PKCS7_bio_stream 3 , 171.Xr PEM_write_bio_PKCS7_stream 3 , 172.Xr PEM_write_PKCS7 3 , 173.Xr PKCS7_final 3 , 174.Xr PKCS7_new 3 , 175.Xr SMIME_read_PKCS7 3 , 176.Xr SMIME_write_ASN1 3 177.Sh HISTORY 178.Fn SMIME_write_PKCS7 179first appeared in OpenSSL 0.9.5 and has been available since 180.Ox 2.7 . 181.Sh BUGS 182.Fn SMIME_write_PKCS7 183always base64 encodes PKCS#7 structures. 184There should be an option to disable this. 185