1*1dcdf01fSchristos=pod 2*1dcdf01fSchristos 3*1dcdf01fSchristos=head1 NAME 4*1dcdf01fSchristos 5*1dcdf01fSchristosX509_NAME_print_ex, X509_NAME_print_ex_fp, X509_NAME_print, 6*1dcdf01fSchristosX509_NAME_oneline - X509_NAME printing routines 7*1dcdf01fSchristos 8*1dcdf01fSchristos=head1 SYNOPSIS 9*1dcdf01fSchristos 10*1dcdf01fSchristos #include <openssl/x509.h> 11*1dcdf01fSchristos 12*1dcdf01fSchristos int X509_NAME_print_ex(BIO *out, const X509_NAME *nm, int indent, unsigned long flags); 13*1dcdf01fSchristos int X509_NAME_print_ex_fp(FILE *fp, const X509_NAME *nm, int indent, unsigned long flags); 14*1dcdf01fSchristos char *X509_NAME_oneline(const X509_NAME *a, char *buf, int size); 15*1dcdf01fSchristos int X509_NAME_print(BIO *bp, const X509_NAME *name, int obase); 16*1dcdf01fSchristos 17*1dcdf01fSchristos=head1 DESCRIPTION 18*1dcdf01fSchristos 19*1dcdf01fSchristosX509_NAME_print_ex() prints a human readable version of B<nm> to BIO B<out>. Each 20*1dcdf01fSchristosline (for multiline formats) is indented by B<indent> spaces. The output format 21*1dcdf01fSchristoscan be extensively customised by use of the B<flags> parameter. 22*1dcdf01fSchristos 23*1dcdf01fSchristosX509_NAME_print_ex_fp() is identical to X509_NAME_print_ex() except the output is 24*1dcdf01fSchristoswritten to FILE pointer B<fp>. 25*1dcdf01fSchristos 26*1dcdf01fSchristosX509_NAME_oneline() prints an ASCII version of B<a> to B<buf>. 27*1dcdf01fSchristosIf B<buf> is B<NULL> then a buffer is dynamically allocated and returned, and 28*1dcdf01fSchristosB<size> is ignored. 29*1dcdf01fSchristosOtherwise, at most B<size> bytes will be written, including the ending '\0', 30*1dcdf01fSchristosand B<buf> is returned. 31*1dcdf01fSchristos 32*1dcdf01fSchristosX509_NAME_print() prints out B<name> to B<bp> indenting each line by B<obase> 33*1dcdf01fSchristoscharacters. Multiple lines are used if the output (including indent) exceeds 34*1dcdf01fSchristos80 characters. 35*1dcdf01fSchristos 36*1dcdf01fSchristos=head1 NOTES 37*1dcdf01fSchristos 38*1dcdf01fSchristosThe functions X509_NAME_oneline() and X509_NAME_print() 39*1dcdf01fSchristosproduce a non standard output form, they don't handle multi character fields and 40*1dcdf01fSchristoshave various quirks and inconsistencies. 41*1dcdf01fSchristosTheir use is strongly discouraged in new applications and they could 42*1dcdf01fSchristosbe deprecated in a future release. 43*1dcdf01fSchristos 44*1dcdf01fSchristosAlthough there are a large number of possible flags for most purposes 45*1dcdf01fSchristosB<XN_FLAG_ONELINE>, B<XN_FLAG_MULTILINE> or B<XN_FLAG_RFC2253> will suffice. 46*1dcdf01fSchristosAs noted on the L<ASN1_STRING_print_ex(3)> manual page 47*1dcdf01fSchristosfor UTF8 terminals the B<ASN1_STRFLGS_ESC_MSB> should be unset: so for example 48*1dcdf01fSchristosB<XN_FLAG_ONELINE & ~ASN1_STRFLGS_ESC_MSB> would be used. 49*1dcdf01fSchristos 50*1dcdf01fSchristosThe complete set of the flags supported by X509_NAME_print_ex() is listed below. 51*1dcdf01fSchristos 52*1dcdf01fSchristosSeveral options can be ored together. 53*1dcdf01fSchristos 54*1dcdf01fSchristosThe options B<XN_FLAG_SEP_COMMA_PLUS>, B<XN_FLAG_SEP_CPLUS_SPC>, 55*1dcdf01fSchristosB<XN_FLAG_SEP_SPLUS_SPC> and B<XN_FLAG_SEP_MULTILINE> determine the field separators 56*1dcdf01fSchristosto use. Two distinct separators are used between distinct RelativeDistinguishedName 57*1dcdf01fSchristoscomponents and separate values in the same RDN for a multi-valued RDN. Multi-valued 58*1dcdf01fSchristosRDNs are currently very rare so the second separator will hardly ever be used. 59*1dcdf01fSchristos 60*1dcdf01fSchristosB<XN_FLAG_SEP_COMMA_PLUS> uses comma and plus as separators. B<XN_FLAG_SEP_CPLUS_SPC> 61*1dcdf01fSchristosuses comma and plus with spaces: this is more readable that plain comma and plus. 62*1dcdf01fSchristosB<XN_FLAG_SEP_SPLUS_SPC> uses spaced semicolon and plus. B<XN_FLAG_SEP_MULTILINE> uses 63*1dcdf01fSchristosspaced newline and plus respectively. 64*1dcdf01fSchristos 65*1dcdf01fSchristosIf B<XN_FLAG_DN_REV> is set the whole DN is printed in reversed order. 66*1dcdf01fSchristos 67*1dcdf01fSchristosThe fields B<XN_FLAG_FN_SN>, B<XN_FLAG_FN_LN>, B<XN_FLAG_FN_OID>, 68*1dcdf01fSchristosB<XN_FLAG_FN_NONE> determine how a field name is displayed. It will 69*1dcdf01fSchristosuse the short name (e.g. CN) the long name (e.g. commonName) always 70*1dcdf01fSchristosuse OID numerical form (normally OIDs are only used if the field name is not 71*1dcdf01fSchristosrecognised) and no field name respectively. 72*1dcdf01fSchristos 73*1dcdf01fSchristosIf B<XN_FLAG_SPC_EQ> is set then spaces will be placed around the '=' character 74*1dcdf01fSchristosseparating field names and values. 75*1dcdf01fSchristos 76*1dcdf01fSchristosIf B<XN_FLAG_DUMP_UNKNOWN_FIELDS> is set then the encoding of unknown fields is 77*1dcdf01fSchristosprinted instead of the values. 78*1dcdf01fSchristos 79*1dcdf01fSchristosIf B<XN_FLAG_FN_ALIGN> is set then field names are padded to 20 characters: this 80*1dcdf01fSchristosis only of use for multiline format. 81*1dcdf01fSchristos 82*1dcdf01fSchristosAdditionally all the options supported by ASN1_STRING_print_ex() can be used to 83*1dcdf01fSchristoscontrol how each field value is displayed. 84*1dcdf01fSchristos 85*1dcdf01fSchristosIn addition a number options can be set for commonly used formats. 86*1dcdf01fSchristos 87*1dcdf01fSchristosB<XN_FLAG_RFC2253> sets options which produce an output compatible with RFC2253 it 88*1dcdf01fSchristosis equivalent to: 89*1dcdf01fSchristos B<ASN1_STRFLGS_RFC2253 | XN_FLAG_SEP_COMMA_PLUS | XN_FLAG_DN_REV | XN_FLAG_FN_SN | XN_FLAG_DUMP_UNKNOWN_FIELDS> 90*1dcdf01fSchristos 91*1dcdf01fSchristos 92*1dcdf01fSchristosB<XN_FLAG_ONELINE> is a more readable one line format which is the same as: 93*1dcdf01fSchristos B<ASN1_STRFLGS_RFC2253 | ASN1_STRFLGS_ESC_QUOTE | XN_FLAG_SEP_CPLUS_SPC | XN_FLAG_SPC_EQ | XN_FLAG_FN_SN> 94*1dcdf01fSchristos 95*1dcdf01fSchristosB<XN_FLAG_MULTILINE> is a multiline format which is the same as: 96*1dcdf01fSchristos B<ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB | XN_FLAG_SEP_MULTILINE | XN_FLAG_SPC_EQ | XN_FLAG_FN_LN | XN_FLAG_FN_ALIGN> 97*1dcdf01fSchristos 98*1dcdf01fSchristosB<XN_FLAG_COMPAT> uses a format identical to X509_NAME_print(): in fact it calls X509_NAME_print() internally. 99*1dcdf01fSchristos 100*1dcdf01fSchristos=head1 RETURN VALUES 101*1dcdf01fSchristos 102*1dcdf01fSchristosX509_NAME_oneline() returns a valid string on success or NULL on error. 103*1dcdf01fSchristos 104*1dcdf01fSchristosX509_NAME_print() returns 1 on success or 0 on error. 105*1dcdf01fSchristos 106*1dcdf01fSchristosX509_NAME_print_ex() and X509_NAME_print_ex_fp() return 1 on success or 0 on error 107*1dcdf01fSchristosif the B<XN_FLAG_COMPAT> is set, which is the same as X509_NAME_print(). Otherwise, 108*1dcdf01fSchristosit returns -1 on error or other values on success. 109*1dcdf01fSchristos 110*1dcdf01fSchristos=head1 SEE ALSO 111*1dcdf01fSchristos 112*1dcdf01fSchristosL<ASN1_STRING_print_ex(3)> 113*1dcdf01fSchristos 114*1dcdf01fSchristos=head1 COPYRIGHT 115*1dcdf01fSchristos 116*1dcdf01fSchristosCopyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved. 117*1dcdf01fSchristos 118*1dcdf01fSchristosLicensed under the OpenSSL license (the "License"). You may not use 119*1dcdf01fSchristosthis file except in compliance with the License. You can obtain a copy 120*1dcdf01fSchristosin the file LICENSE in the source distribution or at 121*1dcdf01fSchristosL<https://www.openssl.org/source/license.html>. 122*1dcdf01fSchristos 123*1dcdf01fSchristos=cut 124