summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/X509_NAME_print_ex.3
diff options
context:
space:
mode:
authorcvs2svn <admin@example.com>2025-04-14 17:32:06 +0000
committercvs2svn <admin@example.com>2025-04-14 17:32:06 +0000
commitb1ddde874c215cc8891531ed92876f091b7eb83e (patch)
treeedb6da6af7e865d488dc1a29309f1e1ec226e603 /src/lib/libcrypto/man/X509_NAME_print_ex.3
parentf0a36529837a161734c802ae4c42e84e42347be2 (diff)
downloadopenbsd-tb_20250414.tar.gz
openbsd-tb_20250414.tar.bz2
openbsd-tb_20250414.zip
This commit was manufactured by cvs2git to create tag 'tb_20250414'.tb_20250414
Diffstat (limited to 'src/lib/libcrypto/man/X509_NAME_print_ex.3')
-rw-r--r--src/lib/libcrypto/man/X509_NAME_print_ex.3260
1 files changed, 0 insertions, 260 deletions
diff --git a/src/lib/libcrypto/man/X509_NAME_print_ex.3 b/src/lib/libcrypto/man/X509_NAME_print_ex.3
deleted file mode 100644
index fc06a717cc..0000000000
--- a/src/lib/libcrypto/man/X509_NAME_print_ex.3
+++ /dev/null
@@ -1,260 +0,0 @@
1.\" $OpenBSD: X509_NAME_print_ex.3,v 1.17 2025/03/09 16:45:31 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: March 9 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.Nd X509_NAME printing routines
61.Sh SYNOPSIS
62.In openssl/x509.h
63.Ft int
64.Fo X509_NAME_print_ex
65.Fa "BIO *out"
66.Fa "const X509_NAME *nm"
67.Fa "int indent"
68.Fa "unsigned long flags"
69.Fc
70.Ft int
71.Fo X509_NAME_print_ex_fp
72.Fa "FILE *fp"
73.Fa "const X509_NAME *nm"
74.Fa "int indent"
75.Fa "unsigned long flags"
76.Fc
77.Ft char *
78.Fo X509_NAME_oneline
79.Fa "const X509_NAME *a"
80.Fa "char *buf"
81.Fa "int size"
82.Fc
83.Sh DESCRIPTION
84.Fn X509_NAME_print_ex
85prints a human readable version of
86.Fa nm
87to
88.Vt BIO
89.Fa out .
90Each line (for multiline formats) is indented by
91.Fa indent
92spaces.
93The output format can be extensively customised by use of the
94.Fa flags
95parameter.
96.Pp
97.Fn X509_NAME_print_ex_fp
98is identical to
99.Fn X509_NAME_print_ex
100except the output is written to the
101.Vt FILE
102pointer
103.Fa fp .
104.Pp
105.Fn X509_NAME_oneline
106prints an ASCII version of
107.Fa a
108to
109.Fa buf .
110If
111.Fa buf
112is
113.Dv NULL ,
114then a buffer is dynamically allocated and returned, and
115.Fa size
116is ignored.
117Otherwise, at most
118.Fa size
119bytes will be written, including the ending NUL, and
120.Fa buf
121is returned.
122.Pp
123.Fn X509_NAME_oneline
124is a legacy function which produces a non-standard output form.
125It doesn't handle multi-character fields and has various quirks
126and inconsistencies.
127Its use is strongly discouraged in new applications.
128.Pp
129Although there are a large number of possible flags, for most purposes
130.Dv XN_FLAG_ONELINE ,
131.Dv XN_FLAG_MULTILINE ,
132or
133.Dv XN_FLAG_RFC2253
134will suffice.
135As noted on the
136.Xr ASN1_STRING_print_ex 3
137manual page, for UTF-8 terminals the
138.Dv ASN1_STRFLGS_ESC_MSB
139should be unset: so for example
140.Dv XN_FLAG_ONELINE No & Pf ~ Dv ASN1_STRFLGS_ESC_MSB
141would be used.
142.Pp
143The complete set of the flags supported by
144.Dv X509_NAME_print_ex
145is listed below.
146.Pp
147Several options can be OR'ed together.
148.Pp
149The options
150.Dv XN_FLAG_SEP_COMMA_PLUS ,
151.Dv XN_FLAG_SEP_CPLUS_SPC ,
152.Dv XN_FLAG_SEP_SPLUS_SPC ,
153and
154.Dv XN_FLAG_SEP_MULTILINE
155determine the field separators to use.
156Two distinct separators are used between distinct
157.Vt RelativeDistinguishedName
158components and separate values in the same RDN for a multi-valued RDN.
159Multi-valued RDNs are currently very rare so the second separator
160will hardly ever be used.
161.Pp
162.Dv XN_FLAG_SEP_COMMA_PLUS
163uses comma and plus as separators.
164.Dv XN_FLAG_SEP_CPLUS_SPC
165uses comma and plus with spaces:
166this is more readable that plain comma and plus.
167.Dv XN_FLAG_SEP_SPLUS_SPC
168uses spaced semicolon and plus.
169.Dv XN_FLAG_SEP_MULTILINE
170uses spaced newline and plus respectively.
171.Dv XN_FLAG_SEP_MASK
172contains the bits used to represent these four options.
173.Pp
174If
175.Dv XN_FLAG_DN_REV
176is set, the whole DN is printed in reversed order.
177.Pp
178The fields
179.Dv XN_FLAG_FN_SN ,
180.Dv XN_FLAG_FN_LN ,
181.Dv XN_FLAG_FN_OID ,
182and
183.Dv XN_FLAG_FN_NONE
184determine how a field name is displayed.
185It will use the short name (e.g. CN), the long name (e.g. commonName),
186always use OID numerical form (normally OIDs are only used if the
187field name is not recognised) and no field name, respectively.
188.Dv XN_FLAG_FN_MASK
189contains the bits used to represent these four options.
190.Pp
191If
192.Dv XN_FLAG_SPC_EQ
193is set, then spaces will be placed around the
194.Ql =
195character separating field names and values.
196.Pp
197If
198.Dv XN_FLAG_DUMP_UNKNOWN_FIELDS
199is set, then the encoding of unknown fields is printed instead of the
200values.
201.Pp
202If
203.Dv XN_FLAG_FN_ALIGN
204is set, then field names are padded to 20 characters:
205this is only of use for multiline format.
206.Pp
207Additionally, all the options supported by
208.Xr ASN1_STRING_print_ex 3
209can be used to control how each field value is displayed.
210.Pp
211In addition a number of options can be set for commonly used formats.
212.Pp
213.Dv XN_FLAG_RFC2253
214sets options which produce an output compatible with RFC 2253.
215It is equivalent to
216.Dv ASN1_STRFLGS_RFC2253 | XN_FLAG_SEP_COMMA_PLUS | XN_FLAG_DN_REV |
217.Dv XN_FLAG_FN_SN | XN_FLAG_DUMP_UNKNOWN_FIELDS .
218.Pp
219.Dv XN_FLAG_ONELINE
220is a more readable one line format which is the same as:
221.Dv ASN1_STRFLGS_RFC2253 | ASN1_STRFLGS_ESC_QUOTE | XN_FLAG_SEP_CPLUS_SPC |
222.Dv XN_FLAG_SPC_EQ | XN_FLAG_FN_SN .
223.Pp
224.Dv XN_FLAG_MULTILINE
225is a multiline format which is the same as:
226.Dv ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB | XN_FLAG_SEP_MULTILINE |
227.Dv XN_FLAG_SPC_EQ | XN_FLAG_FN_LN | XN_FLAG_FN_ALIGN .
228.Pp
229.Dv XN_FLAG_COMPAT
230uses the traditional non-standard SSLeay format.
231.Sh RETURN VALUES
232.Fn X509_NAME_print_ex
233and
234.Fn X509_NAME_print_ex_fp
235return 1 on success or 0 on error if
236.Dv XN_FLAG_COMPAT
237is set in
238.Fa flags .
239Otherwise, they return the number of printed bytes including the
240indentation or \-1 on error.
241.Pp
242.Fn X509_NAME_oneline
243returns a valid string on success or
244.Dv NULL
245on error.
246.Sh SEE ALSO
247.Xr ASN1_STRING_print_ex 3 ,
248.Xr d2i_X509_NAME 3 ,
249.Xr X509_NAME_get_index_by_NID 3 ,
250.Xr X509_NAME_new 3
251.Sh HISTORY
252.Fn X509_NAME_oneline
253first appeared in SSLeay 0.5.1 and has been available since
254.Ox 2.4 .
255.Pp
256.Fn X509_NAME_print_ex
257and
258.Fn X509_NAME_print_ex_fp
259first appeared in OpenSSL 0.9.6 and have been available since
260.Ox 2.9 .