From 80a0aabaf5c68fc096c4e1cafc26b0d54aab9862 Mon Sep 17 00:00:00 2001 From: schwarze Date: Mon, 12 Jul 2021 14:54:00 +0000 Subject: [PATCH] document X509V3_extensions_print(3) --- lib/libcrypto/man/Makefile | 3 +- lib/libcrypto/man/X509V3_EXT_print.3 | 5 +- lib/libcrypto/man/X509V3_extensions_print.3 | 100 ++++++++++++++++++ lib/libcrypto/man/X509V3_get_d2i.3 | 5 +- lib/libcrypto/man/X509_EXTENSION_set_object.3 | 3 +- lib/libcrypto/man/X509v3_get_ext_by_NID.3 | 3 +- 6 files changed, 112 insertions(+), 7 deletions(-) create mode 100644 lib/libcrypto/man/X509V3_extensions_print.3 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 @@ -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 .\" @@ -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 +.\" +.\" 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 . @@ -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 -- 2.20.1