diff options
| -rw-r--r-- | lib/libcrypto/man/Makefile | 3 | ||||
| -rw-r--r-- | lib/libcrypto/man/X509V3_EXT_print.3 | 155 | ||||
| -rw-r--r-- | lib/libcrypto/man/X509V3_get_d2i.3 | 7 | ||||
| -rw-r--r-- | lib/libcrypto/man/X509_EXTENSION_set_object.3 | 5 | ||||
| -rw-r--r-- | lib/libcrypto/man/X509v3_get_ext_by_NID.3 | 5 |
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 |