document X509V3_extensions_print(3)

6 files changed, 112 insertions, 7 deletions

diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index 0216f12ab65..231e39aa27b 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.179 2021/07/12 11:47:01 schwarze Exp $
+# $OpenBSD: Makefile,v 1.180 2021/07/12 14:54:00 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -325,6 +325,7 @@ MAN=	\
 	X509_signature_dump.3 \
 	X509_verify_cert.3 \
 	X509V3_EXT_print.3 \
+	X509V3_extensions_print.3 \
 	X509v3_get_ext_by_NID.3 \
 	crypto.3 \
 	d2i_ASN1_NULL.3 \
diff --git a/lib/libcrypto/man/X509V3_EXT_print.3 b/lib/libcrypto/man/X509V3_EXT_print.3
index d9063e48817..0c695842b72 100644
--- a/lib/libcrypto/man/X509V3_EXT_print.3
+++ b/lib/libcrypto/man/X509V3_EXT_print.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509V3_EXT_print.3,v 1.1 2021/07/12 11:47:01 schwarze Exp $
+.\" $OpenBSD: X509V3_EXT_print.3,v 1.2 2021/07/12 14:54:00 schwarze Exp $
 .\"
 .\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -142,7 +142,8 @@ succeed.
 .Xr BIO_new 3 ,
 .Xr X509_EXTENSION_new 3 ,
 .Xr X509_get0_extensions 3 ,
-.Xr X509_get_ext 3
+.Xr X509_get_ext 3 ,
+.Xr X509V3_extensions_print 3
 .Sh HISTORY
 .Fn X509V3_EXT_print
 first appeared in OpenSSL 0.9.2 and has been available since
diff --git a/lib/libcrypto/man/X509V3_extensions_print.3 b/lib/libcrypto/man/X509V3_extensions_print.3
new file mode 100644
index 00000000000..ad5b02a8262
--- /dev/null
+++ b/lib/libcrypto/man/X509V3_extensions_print.3
@@ -0,0 +1,100 @@
+.\" $OpenBSD: X509V3_extensions_print.3,v 1.1 2021/07/12 14:54:00 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: July 12 2021 $
+.Dt X509V3_EXTENSIONS_PRINT 3
+.Os
+.Sh NAME
+.Nm X509V3_extensions_print
+.Nd pretty-print an array of X.509 extensions
+.Sh SYNOPSIS
+.In openssl/x509v3.h
+.Ft int
+.Fo X509V3_extensions_print
+.Fa "BIO *bio"
+.Fa "char *title"
+.Fa "const STACK_OF(X509_EXTENSION) *sk"
+.Fa "unsigned long flags"
+.Fa "int indent"
+.Fc
+.Sh DESCRIPTION
+For each member of the variable sized array
+.Fa sk ,
+.Fn X509V3_extensions_print
+prints the following information to
+.Fa bio
+in the following order:
+.Bl -bullet
+.It
+The extension type as printed by
+.Xr i2a_ASN1_OBJECT 3 .
+.It
+If the extension is critical, the fixed string
+.Qq "critical" .
+.It
+A human-readable representation of the data contained in the extension
+as printed by
+.Xr X509V3_EXT_print 3 ,
+passing through the
+.Fa flags .
+If that function indicates failure,
+the BER-encoded data of the extension is dumped with
+.Xr ASN1_STRING_print 3
+without decoding it first.
+In both cases, an
+.Fa indent
+incremented by 4 space characaters is used.
+.El
+.Pp
+If
+.Fa sk
+is a
+.Dv NULL
+pointer or empty,
+.Fn X509V3_extensions_print
+prints nothing and indicates success.
+.Pp
+Unless
+.Fa title
+is
+.Dv NULL ,
+it is printed on its own output line before the rest of the output, and
+.Fa indent
+is increased by 4 space characters.
+This additional global indentation is cumulative
+to the one applied to individual extensions mentioned above.
+.Sh RETURN VALUES
+.Fn X509V3_extensions_print
+is intended to return 1 on success or 0 if an error occurs.
+.Sh SEE ALSO
+.Xr BIO_new 3 ,
+.Xr STACK_OF 3 ,
+.Xr X509_EXTENSION_get_critical 3 ,
+.Xr X509_get0_extensions 3 ,
+.Xr X509_get_ext 3 ,
+.Xr X509V3_EXT_print 3
+.Sh HISTORY
+.Fn X509V3_extensions_print
+first appeared in OpenSSL 0.9.7 and has been available since
+.Ox 3.2 .
+.Sh BUGS
+Many parsing and printing errors are silently ignored,
+and the function may return indicating success even though
+.Fa sk
+contains invalid data.
+Even if all the data is valid, success may be indicated  even when the
+information printed is incomplete for various reasons, for example
+due to memory allocation failures or I/O errors.
diff --git a/lib/libcrypto/man/X509V3_get_d2i.3 b/lib/libcrypto/man/X509V3_get_d2i.3
index 8a4f4dfb06e..4e1a003365b 100644
--- a/lib/libcrypto/man/X509V3_get_d2i.3
+++ b/lib/libcrypto/man/X509V3_get_d2i.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509V3_get_d2i.3,v 1.18 2021/07/12 11:47:01 schwarze Exp $
+.\" $OpenBSD: X509V3_get_d2i.3,v 1.19 2021/07/12 14:54:00 schwarze Exp $
 .\" full merge up to: OpenSSL ff7fbfd5 Nov 2 11:52:01 2015 +0000
 .\" selective merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
@@ -417,7 +417,8 @@ if no extensions are present.
 .Xr X509_get_version 3 ,
 .Xr X509_new 3 ,
 .Xr X509_REVOKED_new 3 ,
-.Xr X509V3_EXT_print 3
+.Xr X509V3_EXT_print 3 ,
+.Xr X509V3_extensions_print 3
 .Sh HISTORY
 .Fn X509V3_EXT_d2i
 first appeared in OpenSSL 0.9.2b.
diff --git a/lib/libcrypto/man/X509_EXTENSION_set_object.3 b/lib/libcrypto/man/X509_EXTENSION_set_object.3
index 36b48f61ace..ef14f7cca37 100644
--- a/lib/libcrypto/man/X509_EXTENSION_set_object.3
+++ b/lib/libcrypto/man/X509_EXTENSION_set_object.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: X509_EXTENSION_set_object.3,v 1.11 2021/07/12 11:47:01 schwarze Exp $
+.\"	$OpenBSD: X509_EXTENSION_set_object.3,v 1.12 2021/07/12 14:54:00 schwarze Exp $
 .\"	OpenSSL bb9ad09e Jun 6 00:43:05 2016 -0400
 .\"
 .\" This file is a derived work.
@@ -288,6 +288,7 @@ pointer.
 .Xr X509_check_host 3 ,
 .Xr X509_check_issued 3 ,
 .Xr X509V3_EXT_print 3 ,
+.Xr X509V3_extensions_print 3 ,
 .Xr X509V3_get_d2i 3 ,
 .Xr X509v3_get_ext_by_NID 3
 .Sh STANDARDS
diff --git a/lib/libcrypto/man/X509v3_get_ext_by_NID.3 b/lib/libcrypto/man/X509v3_get_ext_by_NID.3
index 0267e185d1c..54e4b583f77 100644
--- a/lib/libcrypto/man/X509v3_get_ext_by_NID.3
+++ b/lib/libcrypto/man/X509v3_get_ext_by_NID.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509v3_get_ext_by_NID.3,v 1.12 2021/07/12 11:47:01 schwarze Exp $
+.\" $OpenBSD: X509v3_get_ext_by_NID.3,v 1.13 2021/07/12 14:54:00 schwarze Exp $
 .\" full merge up to: OpenSSL fd38836b Jun 20 15:25:43 2018 +0100
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -393,6 +393,7 @@ returns 1 on success or 0 on error.
 .Xr X509_new 3 ,
 .Xr X509_REVOKED_new 3 ,
 .Xr X509V3_EXT_print 3 ,
+.Xr X509V3_extensions_print 3 ,
 .Xr X509V3_get_d2i 3
 .Sh HISTORY
 These functions first appeared in SSLeay 0.8.0