new manual page SMIME_read_ASN1(3)

using parts of the text from SMIME_read_CMS(3) and SMIME_read_PKCS7(3)

4 files changed, 134 insertions, 8 deletions

diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 131b8eea1d..98f2cb6b80 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.226 2021/12/13 18:55:22 schwarze Exp $
+# $OpenBSD: Makefile,v 1.227 2021/12/14 14:30:50 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -280,6 +280,7 @@ MAN=	\
         RSA_size.3 \
         SHA1.3 \
         SMIME_crlf_copy.3 \
+        SMIME_read_ASN1.3 \
         SMIME_read_CMS.3 \
         SMIME_read_PKCS7.3 \
         SMIME_write_ASN1.3 \
diff --git a/src/lib/libcrypto/man/SMIME_read_ASN1.3 b/src/lib/libcrypto/man/SMIME_read_ASN1.3
new file mode 100644
index 0000000000..2a04ccb0d2
--- /dev/null
+++ b/src/lib/libcrypto/man/SMIME_read_ASN1.3
@@ -0,0 +1,123 @@
+.\" $OpenBSD: SMIME_read_ASN1.3,v 1.1 2021/12/14 14:30:50 schwarze Exp $
+.\" full merge up to:
+.\" OpenSSL SMIME_read_PKCS7.pod 83cf7abf May 29 13:07:08 2018 +0100
+.\" OpenSSL SMIME_read_CMS.pod b97fdb57 Nov 11 09:33:09 2016 +0100
+.\"
+.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
+.\" Copyright (c) 2002, 2006, 2008 The OpenSSL Project.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\"
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in
+.\"    the documentation and/or other materials provided with the
+.\"    distribution.
+.\"
+.\" 3. All advertising materials mentioning features or use of this
+.\"    software must display the following acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
+.\"
+.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
+.\"    endorse or promote products derived from this software without
+.\"    prior written permission. For written permission, please contact
+.\"    openssl-core@openssl.org.
+.\"
+.\" 5. Products derived from this software may not be called "OpenSSL"
+.\"    nor may "OpenSSL" appear in their names without prior written
+.\"    permission of the OpenSSL Project.
+.\"
+.\" 6. Redistributions of any form whatsoever must retain the following
+.\"    acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
+.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
+.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+.\" OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd $Mdocdate: December 14 2021 $
+.Dt SMIME_READ_ASN1 3
+.Os
+.Sh NAME
+.Nm SMIME_read_ASN1
+.Nd generic S/MIME message parser
+.Sh SYNOPSIS
+.In openssl/asn1.h
+.Ft ASN1_VALUE *
+.Fo SMIME_read_ASN1
+.Fa "BIO *in_bio"
+.Fa "BIO **out_bio"
+.Fa "const ASN1_ITEM *it"
+.Fc
+.Sh DESCRIPTION
+.Fn SMIME_read_ASN1
+reads a message in S/MIME format from
+.Fa in_bio .
+.Pp
+If the message uses cleartext signing, the content is saved in a memory
+.Vt BIO
+which is written to
+.Pf * Fa out_bio .
+Otherwise,
+.Pf * Fa out_bio
+is set to
+.Dv NULL .
+.Pp
+To support future functionality, if
+.Fa out_bio
+is not
+.Dv NULL ,
+.Pf * Fa out_bio
+should be initialized to
+.Dv NULL
+before calling
+.Fn SMIME_read_ASN1 .
+.Sh RETURN VALUES
+.Fn SMIME_read_ASN1
+returns a newly allocated object of type
+.Fa it
+or
+.Dv NULL
+if an error occurred.
+The error can be obtained from
+.Xr ERR_get_error 3 .
+.Sh SEE ALSO
+.Xr ASN1_item_d2i_bio 3 ,
+.Xr BIO_f_base64 3 ,
+.Xr BIO_new 3 ,
+.Xr SMIME_read_CMS 3 ,
+.Xr SMIME_read_PKCS7 3
+.Sh HISTORY
+.Fn SMIME_read_ASN1
+first appeared in OpenSSL 0.9.8h and has been available since
+.Ox 4.5 .
+.Sh BUGS
+The MIME parser used by
+.Fn SMIME_read_ASN1
+is somewhat primitive.
+While it will handle most S/MIME messages, more complex compound
+formats may not work.
+.Pp
+The parser assumes that the
+structure is always base64 encoded, and it will not handle the case
+where it is in binary format or uses quoted printable format.
+.Pp
+The use of a memory
+to hold the signed content limits the size of the message which can
+be processed due to memory restraints: a streaming single pass
+option should be available.
diff --git a/src/lib/libcrypto/man/SMIME_read_CMS.3 b/src/lib/libcrypto/man/SMIME_read_CMS.3
index bbfb1e5463..e1b1d07499 100644
--- a/src/lib/libcrypto/man/SMIME_read_CMS.3
+++ b/src/lib/libcrypto/man/SMIME_read_CMS.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: SMIME_read_CMS.3,v 1.6 2019/11/02 15:39:46 schwarze Exp $
+.\" $OpenBSD: SMIME_read_CMS.3,v 1.7 2021/12/14 14:30:50 schwarze Exp $
 .\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -48,12 +48,12 @@
 .\" 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 14 2021 $
 .Dt SMIME_READ_CMS 3
 .Os
 .Sh NAME
 .Nm SMIME_read_CMS
-.Nd parse S/MIME message
+.Nd extract CMS ContentInfo from an S/MIME message
 .Sh SYNOPSIS
 .In openssl/cms.h
 .Ft CMS_ContentInfo *
@@ -108,6 +108,7 @@ The error can be obtained from
 .Xr CMS_get0_type 3 ,
 .Xr CMS_verify 3 ,
 .Xr d2i_CMS_ContentInfo 3 ,
+.Xr SMIME_read_ASN1 3 ,
 .Xr SMIME_write_CMS 3
 .Sh HISTORY
 .Fn SMIME_read_CMS
diff --git a/src/lib/libcrypto/man/SMIME_read_PKCS7.3 b/src/lib/libcrypto/man/SMIME_read_PKCS7.3
index 8ce739a7cb..dbe2765b8b 100644
--- a/src/lib/libcrypto/man/SMIME_read_PKCS7.3
+++ b/src/lib/libcrypto/man/SMIME_read_PKCS7.3
@@ -1,5 +1,5 @@
-.\"     $OpenBSD: SMIME_read_PKCS7.3,v 1.7 2019/06/10 14:58:48 schwarze Exp $
-.\"     OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
+.\" $OpenBSD: SMIME_read_PKCS7.3,v 1.8 2021/12/14 14:30:50 schwarze Exp $
+.\" full merge up to: OpenSSL 83cf7abf May 29 13:07:08 2018 +0100
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
 .\" Copyright (c) 2002, 2006 The OpenSSL Project.  All rights reserved.
@@ -48,12 +48,12 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 10 2019 $
+.Dd $Mdocdate: December 14 2021 $
 .Dt SMIME_READ_PKCS7 3
 .Os
 .Sh NAME
 .Nm SMIME_read_PKCS7
-.Nd parse S/MIME message
+.Nd extract a PKCS#7 object from an S/MIME message
 .Sh SYNOPSIS
 .In openssl/pkcs7.h
 .Ft PKCS7 *
@@ -125,6 +125,7 @@ The error can be obtained from
 .Xr ERR_get_error 3 .
 .Sh SEE ALSO
 .Xr PKCS7_new 3 ,
+.Xr SMIME_read_ASN1 3 ,
 .Xr SMIME_write_PKCS7 3
 .Sh HISTORY
 .Fn SMIME_read_PKCS7