src/lib/libcrypto/man/SMIME_write_ASN1.3

.\" $OpenBSD: SMIME_write_ASN1.3,v 1.2 2023/05/01 07:28:11 tb Exp $
.\"
.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: May 1 2023 $
.Dt SMIME_WRITE_ASN1 3
.Os
.Sh NAME
.Nm SMIME_write_ASN1
.Nd generate an S/MIME message
.Sh SYNOPSIS
.In openssl/asn1.h
.Ft int
.Fo SMIME_write_ASN1
.Fa "BIO *out_bio"
.Fa "ASN1_VALUE *val_in"
.Fa "BIO *in_bio"
.Fa "int flags"
.Fa "int ctype_nid"
.Fa "int econt_nid"
.Fa "STACK_OF(X509_ALGOR) *micalg"
.Fa "const ASN1_ITEM *it"
.Fc
.Sh DESCRIPTION
.Fn SMIME_write_ASN1
generates an S/MIME message on
.Fa out_bio
by writing MIME 1.0 headers
followed by a BER- and base64-encoded serialization of
.Fa val_in ,
which can be of the type
.Vt CMS_ContentInfo
or
.Vt PKCS7
and has to match the
.Fa it
argument.
.Pp
The
.Fa flags
can be the logical OR of zero or more of the following bits:
.Bl -tag -width Ds
.It Dv PKCS7_REUSE_DIGEST
Skip the calls to
.Xr PKCS7_dataInit 3
and
.Xr PKCS7_dataFinal 3 .
This flag has no effect unless
.Dv SMIME_DETACHED
is also set.
It is normally used if
.Fa out_bio
is already set up to calculate and finalize the digest when written through.
.It Dv SMIME_BINARY
If specified, this flag is passed through to
.Xr SMIME_crlf_copy 3 .
.It Dv SMIME_CRLFEOL
End MIME header lines with pairs of carriage return and newline characters.
By default, no carriage return characters are written
and header lines are ended with newline characters only.
.It Dv SMIME_DETACHED
Use cleartext signing.
Generate a
.Qq multipart/signed
S/MIME message using the
.Fa micalg
argument and ignoring the
.Fa ctype_nid
and
.Fa econt_nid
arguments.
The content is read from
.Fa in_bio .
If
.Fa in_bio
is a
.Dv NULL
pointer, this flag is ignored.
.Pp
If this flag is ignored or not specified,
the smime-type is chosen according to
.Fa ctype_nid
instead:
.Bl -tag -width Ds
.It Dv NID_pkcs7_enveloped
.Qq enveloped-data
.It Dv NID_pkcs7_signed
.Qq signed-receipt
if
.Fa econt_nid
is
.Dv NID_id_smime_ct_receipt
.br
.Qq signed-data
if
.Fa micalg
is not empty
.br
.Qq certs-only
if
.Fa micalg
is empty
.It Dv NID_id_smime_ct_compressedData
.Qq compressed-data
.El
.It Dv SMIME_OLDMIME
In Content-Type headers, use
.Qq application/x-pkcs7-mime
or
.Qq application/x-pkcs7-signature .
By default,
.Qq application/pkcs7-mime
or
.Qq application/pkcs7-signature
are used instead.
.It Dv SMIME_STREAM
Perform streaming by reading the content from
.Fa in_bio .
This only works if
.Dv SMIME_DETACHED
is not specified.
.It SMIME_TEXT
Prepend the line
.Qq Content-Type: text/plain
to the content.
This only makes sense if
.Dv SMIME_DETACHED
is also set.
It is ignored if the flag
.Dv SMIME_BINARY
is also set.
.El
.Sh RETURN VALUES
.Fn SMIME_write_ASN1
is intended to return 1 on success or 0 on failure.
.Sh SEE ALSO
.Xr ASN1_item_i2d_bio 3 ,
.Xr BIO_f_base64 3 ,
.Xr BIO_new 3 ,
.Xr SMIME_crlf_copy 3 ,
.Xr SMIME_write_CMS 3 ,
.Xr SMIME_write_PKCS7 3 ,
.Xr X509_ALGOR_new 3
.Sh HISTORY
.Fn SMIME_write_ASN1
first appeared in OpenSSL 1.0.0 and has been available since
.Ox 4.9 .
.Sh BUGS
.Fn SMIME_write_ASN1
ignores most errors and is likely to return 1
even after producing corrupt or incomplete output.