From fd901ea309d90fe66479e8d3172a6c76f2cdd241 Mon Sep 17 00:00:00 2001 From: schwarze Date: Mon, 12 Jul 2021 15:56:54 +0000 Subject: [PATCH] new manual page X509_print_ex(3) --- lib/libcrypto/man/Makefile | 3 +- lib/libcrypto/man/X509_CINF_new.3 | 5 +- lib/libcrypto/man/X509_new.3 | 5 +- lib/libcrypto/man/X509_print_ex.3 | 279 ++++++++++++++++++++++++++++++ 4 files changed, 287 insertions(+), 5 deletions(-) create mode 100644 lib/libcrypto/man/X509_print_ex.3 diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 231e39aa27b..7a1747f2917 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.180 2021/07/12 14:54:00 schwarze Exp $ +# $OpenBSD: Makefile,v 1.181 2021/07/12 15:56:54 schwarze Exp $ .include @@ -321,6 +321,7 @@ MAN= \ X509_get1_email.3 \ X509_keyid_set1.3 \ X509_new.3 \ + X509_print_ex.3 \ X509_sign.3 \ X509_signature_dump.3 \ X509_verify_cert.3 \ diff --git a/lib/libcrypto/man/X509_CINF_new.3 b/lib/libcrypto/man/X509_CINF_new.3 index 94fae2a49d5..9b87aaa77b3 100644 --- a/lib/libcrypto/man/X509_CINF_new.3 +++ b/lib/libcrypto/man/X509_CINF_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509_CINF_new.3,v 1.8 2021/07/09 12:07:27 schwarze Exp $ +.\" $OpenBSD: X509_CINF_new.3,v 1.9 2021/07/12 15:56:54 schwarze Exp $ .\" .\" Copyright (c) 2016 Ingo Schwarze .\" @@ -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 9 2021 $ +.Dd $Mdocdate: July 12 2021 $ .Dt X509_CINF_NEW 3 .Os .Sh NAME @@ -95,6 +95,7 @@ if an error occurs. .Sh SEE ALSO .Xr d2i_X509_CINF 3 , .Xr X509_add1_trust_object 3 , +.Xr X509_CERT_AUX_print 3 , .Xr X509_keyid_set1 3 , .Xr X509_new 3 .Sh STANDARDS diff --git a/lib/libcrypto/man/X509_new.3 b/lib/libcrypto/man/X509_new.3 index ea097bc8662..8a38cf5b72b 100644 --- a/lib/libcrypto/man/X509_new.3 +++ b/lib/libcrypto/man/X509_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509_new.3,v 1.23 2021/07/04 12:56:27 schwarze Exp $ +.\" $OpenBSD: X509_new.3,v 1.24 2021/07/12 15:56:54 schwarze Exp $ .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 .\" .\" This file is a derived work. @@ -66,7 +66,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: July 4 2021 $ +.Dd $Mdocdate: July 12 2021 $ .Dt X509_NEW 3 .Os .Sh NAME @@ -192,6 +192,7 @@ if an error occurs. .Xr X509_get_version 3 , .Xr X509_INFO_new 3 , .Xr X509_NAME_new 3 , +.Xr X509_print_ex 3 , .Xr X509_PUBKEY_new 3 , .Xr X509_REQ_new 3 , .Xr X509_SIG_new 3 , diff --git a/lib/libcrypto/man/X509_print_ex.3 b/lib/libcrypto/man/X509_print_ex.3 new file mode 100644 index 00000000000..19373e07549 --- /dev/null +++ b/lib/libcrypto/man/X509_print_ex.3 @@ -0,0 +1,279 @@ +.\" $OpenBSD: X509_print_ex.3,v 1.1 2021/07/12 15:56:54 schwarze Exp $ +.\" +.\" Copyright (c) 2021 Ingo Schwarze +.\" +.\" 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 X509_PRINT_EX 3 +.Os +.Sh NAME +.Nm X509_print_ex , +.Nm X509_CERT_AUX_print , +.Nm X509_print_ex_fp , +.Nm X509_print , +.Nm X509_print_fp +.Nd pretty-print an X.509 certificate +.Sh SYNOPSIS +.In openssl/x509.h +.Ft int +.Fo X509_print_ex +.Fa "BIO *bio" +.Fa "X509 *x" +.Fa "unsigned long nameflags" +.Fa "unsigned long skipflags" +.Fc +.Ft int +.Fo X509_CERT_AUX_print +.Fa "BIO *bio" +.Fa "X509_CERT_AUX *aux" +.Fa "int indent" +.Fc +.Ft int +.Fo X509_print_ex_fp +.Fa "FILE *fp" +.Fa "X509 *x" +.Fa "unsigned long nameflags" +.Fa "unsigned long skipflags" +.Fc +.Ft int +.Fo X509_print +.Fa "BIO *bio" +.Fa "X509 *x" +.Fc +.Ft int +.Fo X509_print_fp +.Fa "FILE *fp" +.Fa "X509 *x" +.Fc +.Sh DESCRIPTION +.Fn X509_print_ex +prints information contained in +.Fa x +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, +the X.509 version 3 extensions, or non-standard auxiliary data 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:\& +and +.Qq Data:\& +containing no information. +.Pq Dv X509_FLAG_NO_HEADER +.It +The certificate version number as defined by the standard, +followed in parentheses by the value contained in the version field +in hexadecimal notation. +See +.Xr X509_get_version 3 +for details. +.Pq Dv X509_FLAG_NO_VERSION +.It +The serial number of the certificate as returned by +.Xr X509_get_serialNumber 3 . +If it is not \-1 and converting it to +.Vt long +succeeds, it is printed in both decimal and hexadecimal format. +If it is \-1, too wide to fit in +.Vt long , +or conversion fails, it is printed byte-by-byte in hexadecimal notation. +.Pq Dv X509_FLAG_NO_SERIAL +.It +The name of the signature algorithm is printed with +.Xr X509_signature_print 3 . +.Pq Dv X509_FLAG_NO_SIGNAME +.It +The issuer name returned by +.Xr X509_get_issuer_name 3 +is printed with +.Xr X509_NAME_print_ex 3 . +.Pq Dv X509_FLAG_NO_ISSUER +.It +The validity period from +.Xr X509_get_notBefore 3 +to +.Xr X509_get_notAfter 3 +is printed using +.Xr ASN1_TIME_print 3 . +.Pq Dv X509_FLAG_NO_VALIDITY +.It +The subject name returned from +.Xr X509_get_subject_name 3 +is printed with +.Xr X509_NAME_print_ex 3 . +.Pq Dv 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_get_pubkey 3 +with +.Xr EVP_PKEY_print_public 3 . +.Pq Dv X509_FLAG_NO_PUBKEY +.It +All X.509 extensions contained in the certificate are printed with +.Xr X509V3_extensions_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 +.It +Non-standard auxiliary data associated with the certificate is printed +using the function +.Fn X509_CERT_AUX_print +documented below. +.Pq Dv X509_FLAG_NO_AUX +.El +.Pp +The +.Fa nameflags +argument modifies the format for printing X.501 +.Vt Name +objects contained in +.Fa x . +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, +.Fa indent +is set to zero. +.Pp +.Fn X509_CERT_AUX_print +prints information contained in +.Fa aux +to +.Fa bio +in human-readable form with a left margin of +.Fa indent +spaces. +If +.Fa aux +is +.Dv NULL , +it prints nothing. +.Pp +Information is printed in the following order: +.Bl -bullet +.It +Purposes the certificate is intended to be used for as set with +.Xr X509_add1_trust_object 3 , +each printed with +.Xr OBJ_obj2txt 3 . +.It +Purposes the certificate is explicitly +.Em not +intended to be used for as set with +.Xr X509_add1_reject_object 3 , +again each printed with +.Xr OBJ_obj2txt 3 . +.It +If +.Fa aux +contains data set with +.Xr X509_alias_set1 3 , +the raw bytes are printed in unencoded form. +.It +If +.Fa aux +contains data set with +.Xr X509_keyid_set1 3 , +the bytes are printed in hexadecimal notation with colons in between. +.El +.Pp +.Fn X509_print_ex_fp +is similar to +.Fn X509_print_ex +except that it prints to +.Fa fp . +.Pp +.Fn X509_print +and +.Fn X509_print_fp +are wrapper functions setting the +.Fa nameflags +to +.Dv XN_FLAG_COMPAT +and the +.Fa skipflags +to +.Dv X509_FLAG_COMPAT . +.Sh RETURN VALUES +.Fn X509_print_ex , +.Fn X509_print_ex_fp , +.Fn X509_print , +and +.Fn X509_print_fp +return 1 if all requested information was successfully printed, +even if failures occured while attempting to decode or print the +public key or X.509 version 3 extensions, or 0 if any other operation +failed. +.Pp +.Fn X509_CERT_AUX_print +always returns 1 and silently ignores write errors. +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr X509_CERT_AUX_new 3 , +.Xr X509_new 3 +.Sh HISTORY +.Fn X509_print +first appeared in SSLeay 0.5.1 and was changed to print to a +.Vt BIO +in SSLeay 0.6.0. +.Fn X509_print_fp +first appeared in SSLeay 0.6.0. +Both functions have been available since +.Ox 2.4 . +.Pp +.Fn X509_CERT_AUX_print +first appeared in OpenSSL 0.9.5 and has been available since +.Ox 2.7 . +.Pp +.Fn X509_print_ex +and +.Fn X509_print_ex_fp +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Sh BUGS +If arbitrary data was stored into +.Fa x +using +.Xr X509_alias_set1 3 , +these functions may print binary data and even NUL bytes. -- 2.20.1