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