--- /dev/null
+.\" $OpenBSD: X509_print_ex.3,v 1.1 2021/07/12 15:56:54 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 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.
projects / openbsd / commitdiff