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