new manual page X509_REQ_print_ex(3),

also documenting X509_REQ_print(3) and X509_REQ_print_fp(3)

4 files changed, 184 insertions, 6 deletions

diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index 20ab72da7f6..43d7c5bc56d 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.206 2021/10/28 13:13:03 tb Exp $
+# $OpenBSD: Makefile,v 1.207 2021/10/29 09:42:07 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -306,6 +306,7 @@ MAN=	\
 	X509_REQ_add1_attr.3 \
 	X509_REQ_add_extensions.3 \
 	X509_REQ_new.3 \
+	X509_REQ_print_ex.3 \
 	X509_REVOKED_new.3 \
 	X509_SIG_get0.3 \
 	X509_SIG_new.3 \
diff --git a/lib/libcrypto/man/X509_REQ_new.3 b/lib/libcrypto/man/X509_REQ_new.3
index be408b5edfc..0a5828d5d4a 100644
--- a/lib/libcrypto/man/X509_REQ_new.3
+++ b/lib/libcrypto/man/X509_REQ_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_REQ_new.3,v 1.10 2021/10/28 13:23:19 schwarze Exp $
+.\" $OpenBSD: X509_REQ_new.3,v 1.11 2021/10/29 09:42:07 schwarze Exp $
 .\"
 .\" Copyright (c) 2016, 2021 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: October 28 2021 $
+.Dd $Mdocdate: October 29 2021 $
 .Dt X509_REQ_NEW 3
 .Os
 .Sh NAME
@@ -126,6 +126,7 @@ if an error occurs.
 .Xr X509_REQ_get_pubkey 3 ,
 .Xr X509_REQ_get_subject_name 3 ,
 .Xr X509_REQ_get_version 3 ,
+.Xr X509_REQ_print_ex 3 ,
 .Xr X509_REQ_sign 3
 .Sh STANDARDS
 RFC 2986: PKCS #10: Certification Request Syntax Specification
diff --git a/lib/libcrypto/man/X509_REQ_print_ex.3 b/lib/libcrypto/man/X509_REQ_print_ex.3
new file mode 100644
index 00000000000..231b1b7248e
--- /dev/null
+++ b/lib/libcrypto/man/X509_REQ_print_ex.3
@@ -0,0 +1,175 @@
+.\" $OpenBSD: X509_REQ_print_ex.3,v 1.1 2021/10/29 09:42:07 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: October 29 2021 $
+.Dt X509_REQ_PRINT_EX 3
+.Os
+.Sh NAME
+.Nm X509_REQ_print_ex ,
+.Nm X509_REQ_print ,
+.Nm X509_REQ_print_fp
+.Nd pretty-print a PKCS#10 certification request
+.Sh SYNOPSIS
+.Ft int
+.Fo X509_REQ_print_ex
+.Fa "BIO *bio"
+.Fa "X509_REQ *req"
+.Fa "unsigned long nameflags"
+.Fa "unsigned long skipflags"
+.Fc
+.Ft int
+.Fo X509_REQ_print
+.Fa "BIO *bio"
+.Fa "X509_REQ *req"
+.Fc
+.Ft int
+.Fo X509_REQ_print_fp
+.Fa "FILE *fp"
+.Fa "X509_REQ *req"
+.Fc
+.Sh DESCRIPTION
+.Fn X509_REQ_print_ex
+prints information contained in
+.Fa req
+to
+.Fa bio
+in human-readable form.
+Printing is aborted as soon as any operation fails, with the exception
+that failures while attempting to decode or print the public key
+are not considered as errors.
+.Pp
+By default, the following blocks of information
+are printed in the following order.
+Each block can be skipped by setting the corresponding bit in
+.Fa skipflags ,
+provided in parentheses after each block description.
+.Bl -bullet
+.It
+A pair of lines reading
+.Qq Certificate Request:\&
+and
+.Qq Data:\&
+containing no information.
+.Pq Dv X509_FLAG_NO_HEADER
+.It
+The value contained in the version field
+in decimal and hexadecimal notation.
+.Pq Dv X509_FLAG_NO_VERSION
+.It
+The subject name is printed with
+.Xr X509_NAME_print_ex 3 .
+.Pq X509_FLAG_NO_SUBJECT
+.It
+The public key algorithm is printed with
+.Xr i2a_ASN1_OBJECT 3 ,
+and the public key returned from
+.Xr X509_REQ_get_pubkey 3
+with
+.Xr EVP_PKEY_print_public 3 .
+.Pq Dv X509_FLAG_NO_PUBKEY
+.It
+For each X.501 attribute that is not a requested extension according to
+.Xr X509_REQ_extension_nid 3 ,
+the object identifier is printed with
+.Xr i2a_ASN1_OBJECT 3 ,
+and all values of the types
+.Dv V_ASN1_PRINTABLESTRING ,
+.Dv V_ASN1_T61STRING ,
+and
+.Dv V_ASN1_IA5STRING
+are printed with
+.Xr BIO_write 3 .
+.Pq X509_FLAG_NO_ATTRIBUTES
+.It
+The requested extensions are retrieved with
+.Xr X509_REQ_get_extensions 3
+and their types and values are printed with
+.Xr i2a_ASN1_OBJECT 3
+and
+.Xr X509V3_EXT_print 3 ,
+or, if the latter fails, with
+.Xr ASN1_STRING_print 3 .
+.Pq Dv X509_FLAG_NO_EXTENSIONS
+.It
+The signature is printed with
+.Xr X509_signature_print 3 .
+.Pq Dv X509_FLAG_NO_SIGDUMP
+.El
+.Pp
+The
+.Fa nameflags
+argument modifies the format for printing X.501
+.Vt Name
+objects contained in
+.Fa req .
+It is passed through to
+.Xr X509_NAME_print_ex 3 .
+If
+.Fa nameflags
+is
+.Dv X509_FLAG_COMPAT ,
+the
+.Fa indent
+argument of
+.Xr X509_NAME_print_ex 3
+is set to 16 spaces and the traditional SSLeay format generated by
+.Xr X509_NAME_print 3
+is used.
+Otherwise, if the only bit set in
+.Dv XN_FLAG_SEP_MASK
+is
+.Dv XN_FLAG_SEP_MULTILINE ,
+.Fa indent
+is set to 12 spaces.
+Otherwise, indent is set to zero.
+.Pp
+.Fn X509_REQ_print
+is a wrapper function setting the
+.Fa nameflags
+to
+.Dv XN_FLAG_COMPAT
+and the
+.Fa skipflags
+to
+.Dv X509_FLAG_COMPAT .
+.Pp
+.Fn X509_REQ_print_fp
+is similar to
+.Fn X509_REQ_print
+except that it prints to
+.Fa fp .
+.Sh RETURN VALUES
+These functions return 1 if all requested information was successfully
+printed, even if failures occurred while attempting to decode or
+print the public key, or 0 if any operation fails.
+.Sh SEE ALSO
+.Xr BIO_new 3 ,
+.Xr X509_print_ex 3 ,
+.Xr X509_REQ_new 3
+.Sh HISTORY
+.Fn X509_REQ_print
+first appeared in SSLeay 0.4.4 and
+.Fn X509_REQ_print_fp
+in SSLeay 0.6.0.
+These functions have been available since
+.Ox 2.4 .
+.Pp
+.Fn X509_REQ_print_ex
+first appeared in OpenSSL 0.9.7 and has been available since
+.Ox 3.2 .
+.Sh BUGS
+Some printing failures are silently ignored while printing extensions,
+which may result in incomplete data being printed.
diff --git a/lib/libcrypto/man/X509_print_ex.3 b/lib/libcrypto/man/X509_print_ex.3
index 85e82709bb2..1a2e0edbdfa 100644
--- a/lib/libcrypto/man/X509_print_ex.3
+++ b/lib/libcrypto/man/X509_print_ex.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_print_ex.3,v 1.3 2021/07/23 06:02:39 jmc Exp $
+.\" $OpenBSD: X509_print_ex.3,v 1.4 2021/10/29 09:42:07 schwarze Exp $
 .\"
 .\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" 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 23 2021 $
+.Dd $Mdocdate: October 29 2021 $
 .Dt X509_PRINT_EX 3
 .Os
 .Sh NAME
@@ -252,7 +252,8 @@ always returns 1 and silently ignores write errors.
 .Xr BIO_new 3 ,
 .Xr X509_CERT_AUX_new 3 ,
 .Xr X509_CRL_print 3 ,
-.Xr X509_new 3
+.Xr X509_new 3 ,
+.Xr X509_REQ_print_ex 3
 .Sh HISTORY
 .Fn X509_print
 first appeared in SSLeay 0.5.1 and was changed to print to a