xref: /openbsd-src/lib/libcrypto/man/X509_NAME_print_ex.3 (revision c1a45aed656e7d5627c30c92421893a76f370ccb) 
1.\" $OpenBSD: X509_NAME_print_ex.3,v 1.12 2021/11/11 15:58:49 schwarze 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: November 11 2021 $
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
135indenting each line by
136.Fa obase
137characters.
138Multiple lines are used if the output (including indent) exceeds 80
139characters.
140.Pp
141The functions
142.Fn X509_NAME_oneline
143and
144.Fn X509_NAME_print
145are legacy functions which produce a non-standard output form.
146They don't handle multi-character fields and have various quirks
147and inconsistencies.
148Their use is strongly discouraged in new applications.
149.Pp
150Although there are a large number of possible flags, for most purposes
151.Dv XN_FLAG_ONELINE ,
152.Dv XN_FLAG_MULTILINE ,
153or
154.Dv XN_FLAG_RFC2253
155will suffice.
156As noted on the
157.Xr ASN1_STRING_print_ex 3
158manual page, for UTF-8 terminals the
159.Dv ASN1_STRFLGS_ESC_MSB
160should be unset: so for example
161.Dv XN_FLAG_ONELINE No & Pf ~ Dv ASN1_STRFLGS_ESC_MSB
162would be used.
163.Pp
164The complete set of the flags supported by
165.Dv X509_NAME_print_ex
166is listed below.
167.Pp
168Several options can be OR'ed together.
169.Pp
170The options
171.Dv XN_FLAG_SEP_COMMA_PLUS ,
172.Dv XN_FLAG_SEP_CPLUS_SPC ,
173.Dv XN_FLAG_SEP_SPLUS_SPC ,
174and
175.Dv XN_FLAG_SEP_MULTILINE
176determine the field separators to use.
177Two distinct separators are used between distinct
178.Vt RelativeDistinguishedName
179components and separate values in the same RDN for a multi-valued RDN.
180Multi-valued RDNs are currently very rare so the second separator
181will hardly ever be used.
182.Pp
183.Dv XN_FLAG_SEP_COMMA_PLUS
184uses comma and plus as separators.
185.Dv XN_FLAG_SEP_CPLUS_SPC
186uses comma and plus with spaces:
187this is more readable that plain comma and plus.
188.Dv XN_FLAG_SEP_SPLUS_SPC
189uses spaced semicolon and plus.
190.Dv XN_FLAG_SEP_MULTILINE
191uses spaced newline and plus respectively.
192.Dv XN_FLAG_SEP_MASK
193contains the bits used to represent these four options.
194.Pp
195If
196.Dv XN_FLAG_DN_REV
197is set, the whole DN is printed in reversed order.
198.Pp
199The fields
200.Dv XN_FLAG_FN_SN ,
201.Dv XN_FLAG_FN_LN ,
202.Dv XN_FLAG_FN_OID ,
203and
204.Dv XN_FLAG_FN_NONE
205determine how a field name is displayed.
206It will use the short name (e.g. CN), the long name (e.g. commonName),
207always use OID numerical form (normally OIDs are only used if the
208field name is not recognised) and no field name, respectively.
209.Dv XN_FLAG_FN_MASK
210contains the bits used to represent these four options.
211.Pp
212If
213.Dv XN_FLAG_SPC_EQ
214is set, then spaces will be placed around the
215.Ql =
216character separating field names and values.
217.Pp
218If
219.Dv XN_FLAG_DUMP_UNKNOWN_FIELDS
220is set, then the encoding of unknown fields is printed instead of the
221values.
222.Pp
223If
224.Dv XN_FLAG_FN_ALIGN
225is set, then field names are padded to 20 characters:
226this is only of use for multiline format.
227.Pp
228Additionally, all the options supported by
229.Xr ASN1_STRING_print_ex 3
230can be used to control how each field value is displayed.
231.Pp
232In addition a number of options can be set for commonly used formats.
233.Pp
234.Dv XN_FLAG_RFC2253
235sets options which produce an output compatible with RFC 2253.
236It is equivalent to
237.Dv ASN1_STRFLGS_RFC2253 | XN_FLAG_SEP_COMMA_PLUS | XN_FLAG_DN_REV |
238.Dv XN_FLAG_FN_SN | XN_FLAG_DUMP_UNKNOWN_FIELDS .
239.Pp
240.Dv XN_FLAG_ONELINE
241is a more readable one line format which is the same as:
242.Dv ASN1_STRFLGS_RFC2253 | ASN1_STRFLGS_ESC_QUOTE | XN_FLAG_SEP_CPLUS_SPC |
243.Dv XN_FLAG_SPC_EQ | XN_FLAG_FN_SN .
244.Pp
245.Dv XN_FLAG_MULTILINE
246is a multiline format which is the same as:
247.Dv ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB | XN_FLAG_SEP_MULTILINE |
248.Dv XN_FLAG_SPC_EQ | XN_FLAG_FN_LN | XN_FLAG_FN_ALIGN .
249.Pp
250.Dv XN_FLAG_COMPAT
251uses a format identical to
252.Fn X509_NAME_print :
253in fact it calls
254.Fn X509_NAME_print
255internally.
256.Sh RETURN VALUES
257.Fn X509_NAME_print_ex
258and
259.Fn X509_NAME_print_ex_fp
260return 1 on success or 0 on error if
261.Dv XN_FLAG_COMPAT
262is set in
263.Fa flags .
264Otherwise, they return the number of printed bytes including the
265indentation or \-1 on error.
266.Pp
267.Fn X509_NAME_oneline
268returns a valid string on success or
269.Dv NULL
270on error.
271.Pp
272.Fn X509_NAME_print
273returns 1 on success or 0 on error.
274.Sh SEE ALSO
275.Xr ASN1_STRING_print_ex 3 ,
276.Xr d2i_X509_NAME 3 ,
277.Xr X509_NAME_get_index_by_NID 3 ,
278.Xr X509_NAME_new 3
279.Sh HISTORY
280.Fn X509_NAME_oneline
281and
282.Fn X509_NAME_print
283first appeared in SSLeay 0.5.1 and have been available since
284.Ox 2.4 .
285.Pp
286.Fn X509_NAME_print_ex
287and
288.Fn X509_NAME_print_ex_fp
289first appeared in OpenSSL 0.9.6 and have been available since
290.Ox 2.9 .
291