From: schwarze Date: Fri, 29 Oct 2021 09:42:07 +0000 (+0000) Subject: new manual page X509_REQ_print_ex(3), X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=0aed5e83b36d570eb28e8b1d25ade074b6e3e260;p=openbsd new manual page X509_REQ_print_ex(3), also documenting X509_REQ_print(3) and X509_REQ_print_fp(3) --- 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 @@ -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 .\" @@ -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 +.\" +.\" 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 .\" @@ -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