From 3d955ecadc561a1cd05817d1e07b58a2548ef32a Mon Sep 17 00:00:00 2001 From: schwarze Date: Tue, 14 Dec 2021 14:30:50 +0000 Subject: [PATCH] new manual page SMIME_read_ASN1(3) using parts of the text from SMIME_read_CMS(3) and SMIME_read_PKCS7(3) --- lib/libcrypto/man/Makefile | 3 +- lib/libcrypto/man/SMIME_read_ASN1.3 | 123 +++++++++++++++++++++++++++ lib/libcrypto/man/SMIME_read_CMS.3 | 7 +- lib/libcrypto/man/SMIME_read_PKCS7.3 | 9 +- 4 files changed, 134 insertions(+), 8 deletions(-) create mode 100644 lib/libcrypto/man/SMIME_read_ASN1.3 diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 131b8eea1dd..98f2cb6b803 100644 --- a/lib/libcrypto/man/Makefile +++ b/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 @@ -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/lib/libcrypto/man/SMIME_read_ASN1.3 b/lib/libcrypto/man/SMIME_read_ASN1.3 new file mode 100644 index 00000000000..2a04ccb0d2f --- /dev/null +++ b/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 . +.\" 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/lib/libcrypto/man/SMIME_read_CMS.3 b/lib/libcrypto/man/SMIME_read_CMS.3 index bbfb1e54633..e1b1d074991 100644 --- a/lib/libcrypto/man/SMIME_read_CMS.3 +++ b/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 . @@ -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/lib/libcrypto/man/SMIME_read_PKCS7.3 b/lib/libcrypto/man/SMIME_read_PKCS7.3 index 8ce739a7cb6..dbe2765b8b1 100644 --- a/lib/libcrypto/man/SMIME_read_PKCS7.3 +++ b/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 . .\" 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 -- 2.20.1