1.\" $OpenBSD: X509_NAME_print_ex.3,v 1.14 2025/01/08 00:08:02 tb Exp $
2.\" full merge up to: OpenSSL aebb9aac Jul 19 09:27:53 2016 -0400
3.\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800
4.\"
5.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
6.\" Copyright (c) 2002, 2004, 2007, 2016, 2017 The OpenSSL Project.
7.\" All rights reserved.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\"
13.\" 1. Redistributions of source code must retain the above copyright
14.\"    notice, this list of conditions and the following disclaimer.
15.\"
16.\" 2. Redistributions in binary form must reproduce the above copyright
17.\"    notice, this list of conditions and the following disclaimer in
18.\"    the documentation and/or other materials provided with the
19.\"    distribution.
20.\"
21.\" 3. All advertising materials mentioning features or use of this
22.\"    software must display the following acknowledgment:
23.\"    "This product includes software developed by the OpenSSL Project
24.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
25.\"
26.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
27.\"    endorse or promote products derived from this software without
28.\"    prior written permission. For written permission, please contact
29.\"    openssl-core@openssl.org.
30.\"
31.\" 5. Products derived from this software may not be called "OpenSSL"
32.\"    nor may "OpenSSL" appear in their names without prior written
33.\"    permission of the OpenSSL Project.
34.\"
35.\" 6. Redistributions of any form whatsoever must retain the following
36.\"    acknowledgment:
37.\"    "This product includes software developed by the OpenSSL Project
38.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
39.\"
40.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
41.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
42.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
43.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
44.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
45.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
46.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
47.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
48.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
49.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
50.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
51.\" OF THE POSSIBILITY OF SUCH DAMAGE.
52.\"
53.Dd $Mdocdate: January 8 2025 $
54.Dt X509_NAME_PRINT_EX 3
55.Os
56.Sh NAME
57.Nm X509_NAME_print_ex ,
58.Nm X509_NAME_print_ex_fp ,
59.Nm X509_NAME_oneline ,
60.Nm X509_NAME_print
61.Nd X509_NAME printing routines
62.Sh SYNOPSIS
63.In openssl/x509.h
64.Ft int
65.Fo X509_NAME_print_ex
66.Fa "BIO *out"
67.Fa "const X509_NAME *nm"
68.Fa "int indent"
69.Fa "unsigned long flags"
70.Fc
71.Ft int
72.Fo X509_NAME_print_ex_fp
73.Fa "FILE *fp"
74.Fa "const X509_NAME *nm"
75.Fa "int indent"
76.Fa "unsigned long flags"
77.Fc
78.Ft char *
79.Fo X509_NAME_oneline
80.Fa "const X509_NAME *a"
81.Fa "char *buf"
82.Fa "int size"
83.Fc
84.Ft int
85.Fo X509_NAME_print
86.Fa "BIO *bp"
87.Fa "const X509_NAME *name"
88.Fa "int obase"
89.Fc
90.Sh DESCRIPTION
91.Fn X509_NAME_print_ex
92prints a human readable version of
93.Fa nm
94to
95.Vt BIO
96.Fa out .
97Each line (for multiline formats) is indented by
98.Fa indent
99spaces.
100The output format can be extensively customised by use of the
101.Fa flags
102parameter.
103.Pp
104.Fn X509_NAME_print_ex_fp
105is identical to
106.Fn X509_NAME_print_ex
107except the output is written to the
108.Vt FILE
109pointer
110.Fa fp .
111.Pp
112.Fn X509_NAME_oneline
113prints an ASCII version of
114.Fa a
115to
116.Fa buf .
117If
118.Fa buf
119is
120.Dv NULL ,
121then a buffer is dynamically allocated and returned, and
122.Fa size
123is ignored.
124Otherwise, at most
125.Fa size
126bytes will be written, including the ending NUL, and
127.Fa buf
128is returned.
129.Pp
130.Fn X509_NAME_print
131prints out
132.Fa name
133to
134.Fa bp .
135The
136.Fa obase
137argument is intended to indent the output,
138it is however ignored.
139.Pp
140The functions
141.Fn X509_NAME_oneline
142and
143.Fn X509_NAME_print
144are legacy functions which produce a non-standard output form.
145They don't handle multi-character fields and have various quirks
146and inconsistencies.
147Their use is strongly discouraged in new applications.
148.Pp
149Although there are a large number of possible flags, for most purposes
150.Dv XN_FLAG_ONELINE ,
151.Dv XN_FLAG_MULTILINE ,
152or
153.Dv XN_FLAG_RFC2253
154will suffice.
155As noted on the
156.Xr ASN1_STRING_print_ex 3
157manual page, for UTF-8 terminals the
158.Dv ASN1_STRFLGS_ESC_MSB
159should be unset: so for example
160.Dv XN_FLAG_ONELINE No & Pf ~ Dv ASN1_STRFLGS_ESC_MSB
161would be used.
162.Pp
163The complete set of the flags supported by
164.Dv X509_NAME_print_ex
165is listed below.
166.Pp
167Several options can be OR'ed together.
168.Pp
169The options
170.Dv XN_FLAG_SEP_COMMA_PLUS ,
171.Dv XN_FLAG_SEP_CPLUS_SPC ,
172.Dv XN_FLAG_SEP_SPLUS_SPC ,
173and
174.Dv XN_FLAG_SEP_MULTILINE
175determine the field separators to use.
176Two distinct separators are used between distinct
177.Vt RelativeDistinguishedName
178components and separate values in the same RDN for a multi-valued RDN.
179Multi-valued RDNs are currently very rare so the second separator
180will hardly ever be used.
181.Pp
182.Dv XN_FLAG_SEP_COMMA_PLUS
183uses comma and plus as separators.
184.Dv XN_FLAG_SEP_CPLUS_SPC
185uses comma and plus with spaces:
186this is more readable that plain comma and plus.
187.Dv XN_FLAG_SEP_SPLUS_SPC
188uses spaced semicolon and plus.
189.Dv XN_FLAG_SEP_MULTILINE
190uses spaced newline and plus respectively.
191.Dv XN_FLAG_SEP_MASK
192contains the bits used to represent these four options.
193.Pp
194If
195.Dv XN_FLAG_DN_REV
196is set, the whole DN is printed in reversed order.
197.Pp
198The fields
199.Dv XN_FLAG_FN_SN ,
200.Dv XN_FLAG_FN_LN ,
201.Dv XN_FLAG_FN_OID ,
202and
203.Dv XN_FLAG_FN_NONE
204determine how a field name is displayed.
205It will use the short name (e.g. CN), the long name (e.g. commonName),
206always use OID numerical form (normally OIDs are only used if the
207field name is not recognised) and no field name, respectively.
208.Dv XN_FLAG_FN_MASK
209contains the bits used to represent these four options.
210.Pp
211If
212.Dv XN_FLAG_SPC_EQ
213is set, then spaces will be placed around the
214.Ql =
215character separating field names and values.
216.Pp
217If
218.Dv XN_FLAG_DUMP_UNKNOWN_FIELDS
219is set, then the encoding of unknown fields is printed instead of the
220values.
221.Pp
222If
223.Dv XN_FLAG_FN_ALIGN
224is set, then field names are padded to 20 characters:
225this is only of use for multiline format.
226.Pp
227Additionally, all the options supported by
228.Xr ASN1_STRING_print_ex 3
229can be used to control how each field value is displayed.
230.Pp
231In addition a number of options can be set for commonly used formats.
232.Pp
233.Dv XN_FLAG_RFC2253
234sets options which produce an output compatible with RFC 2253.
235It is equivalent to
236.Dv ASN1_STRFLGS_RFC2253 | XN_FLAG_SEP_COMMA_PLUS | XN_FLAG_DN_REV |
237.Dv XN_FLAG_FN_SN | XN_FLAG_DUMP_UNKNOWN_FIELDS .
238.Pp
239.Dv XN_FLAG_ONELINE
240is a more readable one line format which is the same as:
241.Dv ASN1_STRFLGS_RFC2253 | ASN1_STRFLGS_ESC_QUOTE | XN_FLAG_SEP_CPLUS_SPC |
242.Dv XN_FLAG_SPC_EQ | XN_FLAG_FN_SN .
243.Pp
244.Dv XN_FLAG_MULTILINE
245is a multiline format which is the same as:
246.Dv ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB | XN_FLAG_SEP_MULTILINE |
247.Dv XN_FLAG_SPC_EQ | XN_FLAG_FN_LN | XN_FLAG_FN_ALIGN .
248.Pp
249.Dv XN_FLAG_COMPAT
250uses a format identical to
251.Fn X509_NAME_print :
252in fact it calls
253.Fn X509_NAME_print
254internally.
255.Sh RETURN VALUES
256.Fn X509_NAME_print_ex
257and
258.Fn X509_NAME_print_ex_fp
259return 1 on success or 0 on error if
260.Dv XN_FLAG_COMPAT
261is set in
262.Fa flags .
263Otherwise, they return the number of printed bytes including the
264indentation or \-1 on error.
265.Pp
266.Fn X509_NAME_oneline
267returns a valid string on success or
268.Dv NULL
269on error.
270.Pp
271.Fn X509_NAME_print
272returns 1 on success or 0 on error.
273.Sh SEE ALSO
274.Xr ASN1_STRING_print_ex 3 ,
275.Xr d2i_X509_NAME 3 ,
276.Xr X509_NAME_get_index_by_NID 3 ,
277.Xr X509_NAME_new 3
278.Sh HISTORY
279.Fn X509_NAME_oneline
280and
281.Fn X509_NAME_print
282first appeared in SSLeay 0.5.1 and have been available since
283.Ox 2.4 .
284.Pp
285.Fn X509_NAME_print_ex
286and
287.Fn X509_NAME_print_ex_fp
288first appeared in OpenSSL 0.9.6 and have been available since
289.Ox 2.9 .
290