document X509V3_EXT_print(3)

5 files changed, 167 insertions, 8 deletions

diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index f910d81c22f..0216f12ab65 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.178 2021/07/11 19:03:45 schwarze Exp $
+# $OpenBSD: Makefile,v 1.179 2021/07/12 11:47:01 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -324,6 +324,7 @@ MAN=	\
 	X509_sign.3 \
 	X509_signature_dump.3 \
 	X509_verify_cert.3 \
+	X509V3_EXT_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
new file mode 100644
index 00000000000..d9063e48817
--- /dev/null
+++ b/lib/libcrypto/man/X509V3_EXT_print.3
@@ -0,0 +1,155 @@
+.\" $OpenBSD: X509V3_EXT_print.3,v 1.1 2021/07/12 11:47:01 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_EXT_PRINT 3
+.Os
+.Sh NAME
+.Nm X509V3_EXT_print
+.Nd pretty-print an X.509 extension
+.Sh SYNOPSIS
+.In openssl/x509v3.h
+.Ft int
+.Fo X509V3_EXT_print
+.Fa "BIO *bio"
+.Fa "X509_EXTENSION *ext"
+.Fa "unsigned long flags"
+.Fa "int indent"
+.Fc
+.Sh DESCRIPTION
+.Fn X509V3_EXT_print
+decodes
+.Fa ext
+and prints the data contained in it to
+.Fa bio
+in a human-readable format with a left margin of
+.Fa indent
+space characters.
+The details of both the decoding and the printing depend on the type of
+.Fa ext .
+.Pp
+For most extension types, the decoding is done in the same way
+as it would be done by the appropriate public API function, for example:
+.Pp
+.Bl -tag -width NID_authority_key_identifier -compact
+.It Sy extension type
+.Sy decoding function
+.It Dv NID_subject_key_identifier
+.Xr d2i_ASN1_OCTET_STRING 3
+.It Dv NID_key_usage
+.Xr d2i_ASN1_BIT_STRING 3
+.It Dv NID_crl_number
+.Xr d2i_ASN1_INTEGER 3
+.It Dv NID_crl_reason
+.Xr d2i_ASN1_ENUMERATED 3
+.It Dv NID_invalidity_date
+.Xr d2i_ASN1_GENERALIZEDTIME 3
+.It Dv NID_subject_alt_name
+.Xr d2i_GENERAL_NAMES 3
+.It Dv NID_hold_instruction_code
+.Xr d2i_ASN1_OBJECT 3
+.It Dv NID_id_pkix_OCSP_noCheck
+.Xr d2i_ASN1_NULL 3
+.It Dv NID_authority_key_identifier
+.Xr d2i_AUTHORITY_KEYID 3
+.It Dv NID_certificate_policies
+.Xr d2i_CERTIFICATEPOLICIES 3
+.It Dv NID_id_pkix_OCSP_CrlID
+.Xr d2i_OCSP_CRLID 3
+.It Dv NID_id_pkix_OCSP_Nonce
+non-public function built into the library
+.El
+.Pp
+For some types, the printing is performed
+by a dedicated non-public function built into the library.
+For some other types, the printing function is a public API function,
+but none of these printing functions are documented yet.
+.Pp
+If
+.Fa ext
+is of an unknown extension type or if decoding fails
+while using the decoding function for the relevant type,
+the action taken depends on the
+.Fa flags
+argument:
+.Bl -bullet
+.It
+If the bit
+.Dv X509V3_EXT_PARSE_UNKNOWN
+is set,
+.Xr ASN1_parse_dump 3
+is called on the BER-encoded data of the extension, passing \-1 for the
+.Fa dump
+argument.
+Thus, some information about the encoding of the extension gets printed
+and some about its decoded content, falling back to
+.Xr BIO_dump_indent 3
+for the decoded content unless a dedicated printing method is known
+for the respective data type(s).
+Note that even if an extension type is unknown, the data type used
+by the unknown extension, or, if that data type is constructed, of
+the values contained in it, may still be known, which may allow
+printing the content of even an unknown extension in a structured
+or partially structured form.
+.It
+If the bit
+.Dv X509V3_EXT_DUMP_UNKNOWN
+is set,
+.Xr BIO_dump_indent 3
+is called on the BER-encoded data of the extension without decoding
+it first, which is usually less readable than the above but poses
+a smaller risk of omitting or misrepresenting parts of the information.
+.It
+If the bit
+.Dv X509V3_EXT_ERROR_UNKNOWN
+is set, only the fixed string
+.Qq "<Not Supported>"
+is printed for an unknown type or only the fixed string
+.Qq "<Parse Error>"
+if the parsing functions fails,
+but printing is considered as successful anyway.
+.It
+If more than one of these three bits is set, or if a bit in
+.Dv X509V3_EXT_UNKNOWN_MASK
+is set that is not listed above, nothing is printed, but printing
+is considered as successful anyway.
+.It
+If none of the bits in
+.Dv X509V3_EXT_UNKNOWN_MASK
+are set, nothing is printed and printing is considered as failed.
+.El
+.Sh RETURN VALUES
+.Fn X509V3_EXT_print
+returns 0 if failure was both detected and considered relevant.
+Otherwise, 1 is returned, and in general the user cannot tell whether
+failure simply went undetected, whether the function detected failure
+but regarded it as irrelevant, or whether printing did indeed
+succeed.
+.Sh SEE ALSO
+.Xr BIO_new 3 ,
+.Xr X509_EXTENSION_new 3 ,
+.Xr X509_get0_extensions 3 ,
+.Xr X509_get_ext 3
+.Sh HISTORY
+.Fn X509V3_EXT_print
+first appeared in OpenSSL 0.9.2 and has been available since
+.Ox 2.6 .
+.Sh BUGS
+.Fn X509V3_EXT_print
+lacks error handling throughout.
+When a write operation fails, it will usually ignore the fact that
+information was omitted from the output and report success to the
+caller anyway.
diff --git a/lib/libcrypto/man/X509V3_get_d2i.3 b/lib/libcrypto/man/X509V3_get_d2i.3
index 13f1eda35da..8a4f4dfb06e 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.17 2019/08/22 15:15:35 schwarze Exp $
+.\" $OpenBSD: X509V3_get_d2i.3,v 1.18 2021/07/12 11:47:01 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
 .\"
@@ -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: August 22 2019 $
+.Dd $Mdocdate: July 12 2021 $
 .Dt X509V3_GET_D2I 3
 .Os
 .Sh NAME
@@ -416,7 +416,8 @@ if no extensions are present.
 .Xr X509_get_subject_name 3 ,
 .Xr X509_get_version 3 ,
 .Xr X509_new 3 ,
-.Xr X509_REVOKED_new 3
+.Xr X509_REVOKED_new 3 ,
+.Xr X509V3_EXT_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 95bbebfa25f..36b48f61ace 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.10 2019/06/06 01:06:59 schwarze Exp $
+.\"	$OpenBSD: X509_EXTENSION_set_object.3,v 1.11 2021/07/12 11:47:01 schwarze Exp $
 .\"	OpenSSL bb9ad09e Jun 6 00:43:05 2016 -0400
 .\"
 .\" This file is a derived work.
@@ -65,7 +65,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 6 2019 $
+.Dd $Mdocdate: July 12 2021 $
 .Dt X509_EXTENSION_SET_OBJECT 3
 .Os
 .Sh NAME
@@ -287,6 +287,7 @@ pointer.
 .Xr X509_check_ca 3 ,
 .Xr X509_check_host 3 ,
 .Xr X509_check_issued 3 ,
+.Xr X509V3_EXT_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 97d54911f56..0267e185d1c 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.11 2019/06/06 01:06:59 schwarze Exp $
+.\" $OpenBSD: X509v3_get_ext_by_NID.3,v 1.12 2021/07/12 11:47:01 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>.
@@ -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: June 6 2019 $
+.Dd $Mdocdate: July 12 2021 $
 .Dt X509V3_GET_EXT_BY_NID 3
 .Os
 .Sh NAME
@@ -392,6 +392,7 @@ returns 1 on success or 0 on error.
 .Xr X509_EXTENSION_new 3 ,
 .Xr X509_new 3 ,
 .Xr X509_REVOKED_new 3 ,
+.Xr X509V3_EXT_print 3 ,
 .Xr X509V3_get_d2i 3
 .Sh HISTORY
 These functions first appeared in SSLeay 0.8.0