1.\" $OpenBSD: X509_print_ex.3,v 1.4 2021/10/29 09:42:07 schwarze Exp $ 2.\" 3.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: October 29 2021 $ 18.Dt X509_PRINT_EX 3 19.Os 20.Sh NAME 21.Nm X509_print_ex , 22.Nm X509_CERT_AUX_print , 23.Nm X509_print_ex_fp , 24.Nm X509_print , 25.Nm X509_print_fp 26.Nd pretty-print an X.509 certificate 27.Sh SYNOPSIS 28.In openssl/x509.h 29.Ft int 30.Fo X509_print_ex 31.Fa "BIO *bio" 32.Fa "X509 *x" 33.Fa "unsigned long nameflags" 34.Fa "unsigned long skipflags" 35.Fc 36.Ft int 37.Fo X509_CERT_AUX_print 38.Fa "BIO *bio" 39.Fa "X509_CERT_AUX *aux" 40.Fa "int indent" 41.Fc 42.Ft int 43.Fo X509_print_ex_fp 44.Fa "FILE *fp" 45.Fa "X509 *x" 46.Fa "unsigned long nameflags" 47.Fa "unsigned long skipflags" 48.Fc 49.Ft int 50.Fo X509_print 51.Fa "BIO *bio" 52.Fa "X509 *x" 53.Fc 54.Ft int 55.Fo X509_print_fp 56.Fa "FILE *fp" 57.Fa "X509 *x" 58.Fc 59.Sh DESCRIPTION 60.Fn X509_print_ex 61prints information contained in 62.Fa x 63to 64.Fa bio 65in human-readable form. 66Printing is aborted as soon as any operation fails, with the exception 67that failures while attempting to decode or print the public key, 68the X.509 version 3 extensions, or non-standard auxiliary data are 69not considered as errors. 70.Pp 71By default, the following blocks of information are printed 72in the following order. 73Each block can be skipped by setting the corresponding bit in 74.Fa skipflags , 75provided in parentheses after each block description. 76.Bl -bullet 77.It 78A pair of lines reading 79.Qq Certificate:\& 80and 81.Qq Data:\& 82containing no information. 83.Pq Dv X509_FLAG_NO_HEADER 84.It 85The certificate version number as defined by the standard, 86followed in parentheses by the value contained in the version field 87in hexadecimal notation. 88See 89.Xr X509_get_version 3 90for details. 91.Pq Dv X509_FLAG_NO_VERSION 92.It 93The serial number of the certificate as returned by 94.Xr X509_get_serialNumber 3 . 95If it is not \-1 and converting it to 96.Vt long 97succeeds, it is printed in both decimal and hexadecimal format. 98If it is \-1, too wide to fit in 99.Vt long , 100or conversion fails, it is printed byte-by-byte in hexadecimal notation. 101.Pq Dv X509_FLAG_NO_SERIAL 102.It 103The name of the signature algorithm is printed with 104.Xr X509_signature_print 3 . 105.Pq Dv X509_FLAG_NO_SIGNAME 106.It 107The issuer name returned by 108.Xr X509_get_issuer_name 3 109is printed with 110.Xr X509_NAME_print_ex 3 . 111.Pq Dv X509_FLAG_NO_ISSUER 112.It 113The validity period from 114.Xr X509_get_notBefore 3 115to 116.Xr X509_get_notAfter 3 117is printed using 118.Xr ASN1_TIME_print 3 . 119.Pq Dv X509_FLAG_NO_VALIDITY 120.It 121The subject name returned from 122.Xr X509_get_subject_name 3 123is printed with 124.Xr X509_NAME_print_ex 3 . 125.Pq Dv X509_FLAG_NO_SUBJECT 126.It 127The public key algorithm is printed with 128.Xr i2a_ASN1_OBJECT 3 , 129and the public key returned from 130.Xr X509_get_pubkey 3 131with 132.Xr EVP_PKEY_print_public 3 . 133.Pq Dv X509_FLAG_NO_PUBKEY 134.It 135All X.509 extensions contained in the certificate are printed with 136.Xr X509V3_extensions_print 3 . 137.Pq Dv X509_FLAG_NO_EXTENSIONS 138.It 139The signature is printed with 140.Xr X509_signature_print 3 . 141.Pq Dv X509_FLAG_NO_SIGDUMP 142.It 143Non-standard auxiliary data associated with the certificate is printed 144using the function 145.Fn X509_CERT_AUX_print 146documented below. 147.Pq Dv X509_FLAG_NO_AUX 148.El 149.Pp 150The 151.Fa nameflags 152argument modifies the format for printing X.501 153.Vt Name 154objects contained in 155.Fa x . 156It is passed through to 157.Xr X509_NAME_print_ex 3 . 158If 159.Fa nameflags 160is 161.Dv X509_FLAG_COMPAT , 162the 163.Fa indent 164argument of 165.Xr X509_NAME_print_ex 3 166is set to 16 spaces and the traditional SSLeay format generated by 167.Xr X509_NAME_print 3 168is used. 169Otherwise, if the only bit set in 170.Dv XN_FLAG_SEP_MASK 171is 172.Dv XN_FLAG_SEP_MULTILINE , 173.Fa indent 174is set to 12 spaces. 175Otherwise, 176.Fa indent 177is set to zero. 178.Pp 179.Fn X509_CERT_AUX_print 180prints information contained in 181.Fa aux 182to 183.Fa bio 184in human-readable form with a left margin of 185.Fa indent 186spaces. 187If 188.Fa aux 189is 190.Dv NULL , 191it prints nothing. 192.Pp 193Information is printed in the following order: 194.Bl -bullet 195.It 196Purposes the certificate is intended to be used for as set with 197.Xr X509_add1_trust_object 3 , 198each printed with 199.Xr OBJ_obj2txt 3 . 200.It 201Purposes the certificate is explicitly 202.Em not 203intended to be used for as set with 204.Xr X509_add1_reject_object 3 , 205again each printed with 206.Xr OBJ_obj2txt 3 . 207.It 208If 209.Fa aux 210contains data set with 211.Xr X509_alias_set1 3 , 212the raw bytes are printed in unencoded form. 213.It 214If 215.Fa aux 216contains data set with 217.Xr X509_keyid_set1 3 , 218the bytes are printed in hexadecimal notation with colons in between. 219.El 220.Pp 221.Fn X509_print_ex_fp 222is similar to 223.Fn X509_print_ex 224except that it prints to 225.Fa fp . 226.Pp 227.Fn X509_print 228and 229.Fn X509_print_fp 230are wrapper functions setting the 231.Fa nameflags 232to 233.Dv XN_FLAG_COMPAT 234and the 235.Fa skipflags 236to 237.Dv X509_FLAG_COMPAT . 238.Sh RETURN VALUES 239.Fn X509_print_ex , 240.Fn X509_print_ex_fp , 241.Fn X509_print , 242and 243.Fn X509_print_fp 244return 1 if all requested information was successfully printed, 245even if failures occurred while attempting to decode or print the 246public key or X.509 version 3 extensions, or 0 if any other operation 247failed. 248.Pp 249.Fn X509_CERT_AUX_print 250always returns 1 and silently ignores write errors. 251.Sh SEE ALSO 252.Xr BIO_new 3 , 253.Xr X509_CERT_AUX_new 3 , 254.Xr X509_CRL_print 3 , 255.Xr X509_new 3 , 256.Xr X509_REQ_print_ex 3 257.Sh HISTORY 258.Fn X509_print 259first appeared in SSLeay 0.5.1 and was changed to print to a 260.Vt BIO 261in SSLeay 0.6.0. 262.Fn X509_print_fp 263first appeared in SSLeay 0.6.0. 264Both functions have been available since 265.Ox 2.4 . 266.Pp 267.Fn X509_CERT_AUX_print 268first appeared in OpenSSL 0.9.5 and has been available since 269.Ox 2.7 . 270.Pp 271.Fn X509_print_ex 272and 273.Fn X509_print_ex_fp 274first appeared in OpenSSL 0.9.7 and have been available since 275.Ox 3.2 . 276.Sh BUGS 277If arbitrary data was stored into 278.Fa x 279using 280.Xr X509_alias_set1 3 , 281these functions may print binary data and even NUL bytes. 282