From 2d704d09cd1a78115e2d10a4918602191ed0a6fd Mon Sep 17 00:00:00 2001
From: schwarze <>
Date: Sat, 28 Dec 2024 10:19:45 +0000
Subject: Document X509V3_EXT_print_fp(3). Sort the list of decoding functions
 alphabetically by extension type. List the printing functions that are
 already documented.

---
 src/lib/libcrypto/man/X509V3_EXT_print.3 | 95 ++++++++++++++++++++++----------
 1 file changed, 67 insertions(+), 28 deletions(-)

diff --git a/src/lib/libcrypto/man/X509V3_EXT_print.3 b/src/lib/libcrypto/man/X509V3_EXT_print.3
index 0c695842b7..edb97d3a36 100644
--- a/src/lib/libcrypto/man/X509V3_EXT_print.3
+++ b/src/lib/libcrypto/man/X509V3_EXT_print.3
@@ -1,6 +1,6 @@
-.\" $OpenBSD: X509V3_EXT_print.3,v 1.2 2021/07/12 14:54:00 schwarze Exp $
+.\" $OpenBSD: X509V3_EXT_print.3,v 1.3 2024/12/28 10:19:45 schwarze Exp $
 .\"
-.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2021, 2024 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
@@ -14,11 +14,12 @@
 .\" 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 $
+.Dd $Mdocdate: December 28 2024 $
 .Dt X509V3_EXT_PRINT 3
 .Os
 .Sh NAME
-.Nm X509V3_EXT_print
+.Nm X509V3_EXT_print ,
+.Nm X509V3_EXT_print_fp
 .Nd pretty-print an X.509 extension
 .Sh SYNOPSIS
 .In openssl/x509v3.h
@@ -29,13 +30,24 @@
 .Fa "unsigned long flags"
 .Fa "int indent"
 .Fc
+.Ft int
+.Fo X509V3_EXT_print_fp
+.Fa "FILE *file"
+.Fa "X509_EXTENSION *ext"
+.Fa "int flags"
+.Fa "int indent"
+.Fc
 .Sh DESCRIPTION
 .Fn X509V3_EXT_print
-decodes
+and
+.Fn X509V3_EXT_print_fp
+decode
 .Fa ext
-and prints the data contained in it to
+and print the data contained in it to the
 .Fa bio
-in a human-readable format with a left margin of
+or
+.Fa file ,
+respectively, 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
@@ -47,36 +59,63 @@ as it would be done by the appropriate public API function, for example:
 .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_authority_key_identifier
+.Xr d2i_AUTHORITY_KEYID 3
+.It Dv NID_certificate_policies
+.Xr d2i_CERTIFICATEPOLICIES 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_noCheck
+.Xr d2i_ASN1_NULL 3
 .It Dv NID_id_pkix_OCSP_Nonce
 non-public function built into the library
+.It Dv NID_invalidity_date
+.Xr d2i_ASN1_GENERALIZEDTIME 3
+.It Dv NID_key_usage
+.Xr d2i_ASN1_BIT_STRING 3
+.It Dv NID_subject_alt_name
+.Xr d2i_GENERAL_NAMES 3
+.It Dv NID_subject_key_identifier
+.Xr d2i_ASN1_OCTET_STRING 3
 .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.
+for example:
+.Pp
+.Bl -tag -width NID_id_pkix_OCSP_archiveCutoff -compact
+.It Sy extension type
+.Sy printing function
+.It Dv NID_crl_number
+.Xr i2s_ASN1_INTEGER 3
+.It Dv NID_crl_reason
+.Xr i2s_ASN1_ENUMERATED_TABLE 3
+.It Dv NID_delta_crl
+.Xr i2s_ASN1_INTEGER 3
+.It Dv NID_hold_instruction_code
+.Xr i2a_ASN1_OBJECT 3
+.It Dv NID_id_pkix_OCSP_archiveCutoff
+.Xr ASN1_GENERALIZEDTIME_print 3
+.It Dv NID_id_pkix_OCSP_Nonce
+.Xr i2a_ASN1_STRING 3
+.It Dv NID_inhibit_any_policy
+.Xr i2s_ASN1_INTEGER 3
+.It Dv NID_invalidity_date
+.Xr ASN1_GENERALIZEDTIME_print 3
+.It Dv NID_key_usage
+.Xr i2v_ASN1_BIT_STRING 3
+.It Dv NID_subject_key_identifier
+.Xr i2s_ASN1_OCTET_STRING 3
+.El
+.Pp
+Some of the public printing functions are not documented yet.
 .Pp
 If
 .Fa ext
@@ -133,7 +172,9 @@ 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.
+and
+.Fn X509V3_EXT_print_fp
+return 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
@@ -145,12 +186,10 @@ succeed.
 .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
+These functions first appeared in OpenSSL 0.9.2 and have 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
+These functions lack error handling throughout.
+When a write operation fails, they will usually ignore the fact that
 information was omitted from the output and report success to the
 caller anyway.
-- 
cgit v1.2.3-55-g6feb