diff options
Diffstat (limited to 'lib/libcrypto/man/SMIME_write_ASN1.3')
| -rw-r--r-- | lib/libcrypto/man/SMIME_write_ASN1.3 | 166 |
1 files changed, 166 insertions, 0 deletions
diff --git a/lib/libcrypto/man/SMIME_write_ASN1.3 b/lib/libcrypto/man/SMIME_write_ASN1.3 new file mode 100644 index 00000000000..971cd226dd6 --- /dev/null +++ b/lib/libcrypto/man/SMIME_write_ASN1.3 @@ -0,0 +1,166 @@ +.\" $OpenBSD: SMIME_write_ASN1.3,v 1.1 2021/12/13 17:24:39 schwarze 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: December 13 2021 $ +.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 passing this flag through to +.Xr i2d_ASN1_bio_stream 3 +and 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 i2d_ASN1_bio_stream 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. |