From a4c8c587915fba57f45bb1d00aa28ffbd3f8af44 Mon Sep 17 00:00:00 2001 From: schwarze Date: Mon, 13 Dec 2021 17:24:39 +0000 Subject: [PATCH] new manual page SMIME_write_ASN1(3); still vague in various respects, but it's a start --- lib/libcrypto/man/Makefile | 3 +- lib/libcrypto/man/SMIME_write_ASN1.3 | 166 ++++++++++++++++++++++++ lib/libcrypto/man/SMIME_write_CMS.3 | 7 +- lib/libcrypto/man/SMIME_write_PKCS7.3 | 7 +- lib/libcrypto/man/i2d_ASN1_bio_stream.3 | 5 +- 5 files changed, 179 insertions(+), 9 deletions(-) create mode 100644 lib/libcrypto/man/SMIME_write_ASN1.3 diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 2e608bffbb7..88610412cc1 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.224 2021/12/13 13:46:09 schwarze Exp $ +# $OpenBSD: Makefile,v 1.225 2021/12/13 17:24:39 schwarze Exp $ .include @@ -281,6 +281,7 @@ MAN= \ SMIME_crlf_copy.3 \ SMIME_read_CMS.3 \ SMIME_read_PKCS7.3 \ + SMIME_write_ASN1.3 \ SMIME_write_CMS.3 \ SMIME_write_PKCS7.3 \ STACK_OF.3 \ 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 +.\" +.\" 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. diff --git a/lib/libcrypto/man/SMIME_write_CMS.3 b/lib/libcrypto/man/SMIME_write_CMS.3 index 5a4e607a3cd..c2c6b77e537 100644 --- a/lib/libcrypto/man/SMIME_write_CMS.3 +++ b/lib/libcrypto/man/SMIME_write_CMS.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: SMIME_write_CMS.3,v 1.5 2019/11/02 15:39:46 schwarze Exp $ +.\" $OpenBSD: SMIME_write_CMS.3,v 1.6 2021/12/13 17:24:39 schwarze Exp $ .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 .\" .\" This file was written by Dr. Stephen Henson . @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: November 2 2019 $ +.Dd $Mdocdate: December 13 2021 $ .Dt SMIME_WRITE_CMS 3 .Os .Sh NAME @@ -120,7 +120,8 @@ returns 1 for success or 0 for failure. .Xr CMS_encrypt 3 , .Xr CMS_sign 3 , .Xr d2i_CMS_ContentInfo 3 , -.Xr ERR_get_error 3 +.Xr ERR_get_error 3 , +.Xr SMIME_write_ASN1 3 .Sh HISTORY .Fn SMIME_write_CMS first appeared in OpenSSL 0.9.8h diff --git a/lib/libcrypto/man/SMIME_write_PKCS7.3 b/lib/libcrypto/man/SMIME_write_PKCS7.3 index 39d8b5d8598..4257a890184 100644 --- a/lib/libcrypto/man/SMIME_write_PKCS7.3 +++ b/lib/libcrypto/man/SMIME_write_PKCS7.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: SMIME_write_PKCS7.3,v 1.7 2020/06/03 13:41:27 schwarze Exp $ +.\" $OpenBSD: SMIME_write_PKCS7.3,v 1.8 2021/12/13 17:24:39 schwarze Exp $ .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 .\" .\" This file was written by Dr. Stephen Henson . @@ -49,7 +49,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: June 3 2020 $ +.Dd $Mdocdate: December 13 2021 $ .Dt SMIME_WRITE_PKCS7 3 .Os .Sh NAME @@ -136,7 +136,8 @@ otherwise 0 is returned and an error code can be retrieved with .Xr PEM_write_PKCS7 3 , .Xr PKCS7_final 3 , .Xr PKCS7_new 3 , -.Xr SMIME_read_PKCS7 3 +.Xr SMIME_read_PKCS7 3 , +.Xr SMIME_write_ASN1 3 .Sh HISTORY .Fn SMIME_write_PKCS7 first appeared in OpenSSL 0.9.5 and has been available since diff --git a/lib/libcrypto/man/i2d_ASN1_bio_stream.3 b/lib/libcrypto/man/i2d_ASN1_bio_stream.3 index 007d8eefd43..82908bb10fa 100644 --- a/lib/libcrypto/man/i2d_ASN1_bio_stream.3 +++ b/lib/libcrypto/man/i2d_ASN1_bio_stream.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: i2d_ASN1_bio_stream.3,v 1.1 2021/12/13 13:46:09 schwarze Exp $ +.\" $OpenBSD: i2d_ASN1_bio_stream.3,v 1.2 2021/12/13 17:24:39 schwarze Exp $ .\" .\" Copyright (c) 2021 Ingo Schwarze .\" @@ -83,7 +83,8 @@ is intended to return 1 on success or 0 on failure. .Xr BIO_push 3 , .Xr i2d_CMS_bio_stream 3 , .Xr i2d_PKCS7_bio_stream 3 , -.Xr SMIME_crlf_copy 3 +.Xr SMIME_crlf_copy 3 , +.Xr SMIME_write_ASN1 3 .Sh HISTORY .Fn i2d_ASN1_bio_stream first appeared in OpenSSL 1.0.0 and has been available since -- 2.20.1