164 lines
3.8 KiB
Groff
164 lines
3.8 KiB
Groff
.\" $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.
|