1.\" $OpenBSD: SMIME_write_ASN1.3,v 1.2 2023/05/01 07:28:11 tb Exp $ 2.\" 3.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: May 1 2023 $ 18.Dt SMIME_WRITE_ASN1 3 19.Os 20.Sh NAME 21.Nm SMIME_write_ASN1 22.Nd generate an S/MIME message 23.Sh SYNOPSIS 24.In openssl/asn1.h 25.Ft int 26.Fo SMIME_write_ASN1 27.Fa "BIO *out_bio" 28.Fa "ASN1_VALUE *val_in" 29.Fa "BIO *in_bio" 30.Fa "int flags" 31.Fa "int ctype_nid" 32.Fa "int econt_nid" 33.Fa "STACK_OF(X509_ALGOR) *micalg" 34.Fa "const ASN1_ITEM *it" 35.Fc 36.Sh DESCRIPTION 37.Fn SMIME_write_ASN1 38generates an S/MIME message on 39.Fa out_bio 40by writing MIME 1.0 headers 41followed by a BER- and base64-encoded serialization of 42.Fa val_in , 43which can be of the type 44.Vt CMS_ContentInfo 45or 46.Vt PKCS7 47and has to match the 48.Fa it 49argument. 50.Pp 51The 52.Fa flags 53can be the logical OR of zero or more of the following bits: 54.Bl -tag -width Ds 55.It Dv PKCS7_REUSE_DIGEST 56Skip the calls to 57.Xr PKCS7_dataInit 3 58and 59.Xr PKCS7_dataFinal 3 . 60This flag has no effect unless 61.Dv SMIME_DETACHED 62is also set. 63It is normally used if 64.Fa out_bio 65is already set up to calculate and finalize the digest when written through. 66.It Dv SMIME_BINARY 67If specified, this flag is passed through to 68.Xr SMIME_crlf_copy 3 . 69.It Dv SMIME_CRLFEOL 70End MIME header lines with pairs of carriage return and newline characters. 71By default, no carriage return characters are written 72and header lines are ended with newline characters only. 73.It Dv SMIME_DETACHED 74Use cleartext signing. 75Generate a 76.Qq multipart/signed 77S/MIME message using the 78.Fa micalg 79argument and ignoring the 80.Fa ctype_nid 81and 82.Fa econt_nid 83arguments. 84The content is read from 85.Fa in_bio . 86If 87.Fa in_bio 88is a 89.Dv NULL 90pointer, this flag is ignored. 91.Pp 92If this flag is ignored or not specified, 93the smime-type is chosen according to 94.Fa ctype_nid 95instead: 96.Bl -tag -width Ds 97.It Dv NID_pkcs7_enveloped 98.Qq enveloped-data 99.It Dv NID_pkcs7_signed 100.Qq signed-receipt 101if 102.Fa econt_nid 103is 104.Dv NID_id_smime_ct_receipt 105.br 106.Qq signed-data 107if 108.Fa micalg 109is not empty 110.br 111.Qq certs-only 112if 113.Fa micalg 114is empty 115.It Dv NID_id_smime_ct_compressedData 116.Qq compressed-data 117.El 118.It Dv SMIME_OLDMIME 119In Content-Type headers, use 120.Qq application/x-pkcs7-mime 121or 122.Qq application/x-pkcs7-signature . 123By default, 124.Qq application/pkcs7-mime 125or 126.Qq application/pkcs7-signature 127are used instead. 128.It Dv SMIME_STREAM 129Perform streaming by reading the content from 130.Fa in_bio . 131This only works if 132.Dv SMIME_DETACHED 133is not specified. 134.It SMIME_TEXT 135Prepend the line 136.Qq Content-Type: text/plain 137to the content. 138This only makes sense if 139.Dv SMIME_DETACHED 140is also set. 141It is ignored if the flag 142.Dv SMIME_BINARY 143is also set. 144.El 145.Sh RETURN VALUES 146.Fn SMIME_write_ASN1 147is intended to return 1 on success or 0 on failure. 148.Sh SEE ALSO 149.Xr ASN1_item_i2d_bio 3 , 150.Xr BIO_f_base64 3 , 151.Xr BIO_new 3 , 152.Xr SMIME_crlf_copy 3 , 153.Xr SMIME_write_CMS 3 , 154.Xr SMIME_write_PKCS7 3 , 155.Xr X509_ALGOR_new 3 156.Sh HISTORY 157.Fn SMIME_write_ASN1 158first appeared in OpenSSL 1.0.0 and has been available since 159.Ox 4.9 . 160.Sh BUGS 161.Fn SMIME_write_ASN1 162ignores most errors and is likely to return 1 163even after producing corrupt or incomplete output. 164