Debian Codegraph @

upstream/debian-unstable/man3/X509_NAME_print_ex.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "X509_NAME_PRINT_EX 3SSL"
58 .TH X509_NAME_PRINT_EX 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 X509_NAME_print_ex, X509_NAME_print_ex_fp, X509_NAME_print,
65 X509_NAME_oneline \- X509_NAME printing routines
66 .SH SYNOPSIS
67 .IX Header "SYNOPSIS"
68 .Vb 1
69 \& #include <openssl/x509.h>
70 \&
71 \& int X509_NAME_print_ex(BIO *out, const X509_NAME *nm,
72 \& int indent, unsigned long flags);
73 \& int X509_NAME_print_ex_fp(FILE *fp, const X509_NAME *nm,
74 \& int indent, unsigned long flags);
75 \& char *X509_NAME_oneline(const X509_NAME *a, char *buf, int size);
76 \& int X509_NAME_print(BIO *bp, const X509_NAME *name, int obase);
77 .Ve
78 .SH DESCRIPTION
79 .IX Header "DESCRIPTION"
80 \&\fBX509_NAME_print_ex()\fR prints a human readable version of \fInm\fR to BIO \fIout\fR.
81 Each line (for multiline formats) is indented by \fIindent\fR spaces. The
82 output format can be extensively customised by use of the \fIflags\fR parameter.
83 .PP
84 \&\fBX509_NAME_print_ex_fp()\fR is identical to \fBX509_NAME_print_ex()\fR
85 except the output is written to FILE pointer \fIfp\fR.
86 .PP
87 \&\fBX509_NAME_oneline()\fR prints an ASCII version of \fIa\fR to \fIbuf\fR.
88 This supports multi-valued RDNs and escapes \fB/\fR and \fB+\fR characters in values.
89 If \fIbuf\fR is \fBNULL\fR then a buffer is dynamically allocated and returned, and
90 \&\fIsize\fR is ignored.
91 Otherwise, at most \fIsize\fR bytes will be written, including the ending '\e0',
92 and \fIbuf\fR is returned.
93 .PP
94 \&\fBX509_NAME_print()\fR prints out \fIname\fR to \fIbp\fR on a single line.
95 The \fIobase\fR parameter is ignored and retained only for API compatibility.
96 .SH NOTES
97 .IX Header "NOTES"
98 The functions \fBX509_NAME_oneline()\fR and \fBX509_NAME_print()\fR
99 produce a non standard output form, they don't handle multi-character fields and
100 have various quirks and inconsistencies.
101 Their use is strongly discouraged in new applications and they could
102 be deprecated in a future release.
103 .PP
104 Although there are a large number of possible flags for most purposes
105 \&\fBXN_FLAG_ONELINE\fR, \fBXN_FLAG_MULTILINE\fR or \fBXN_FLAG_RFC2253\fR will suffice.
106 As noted on the \fBASN1_STRING_print_ex\fR\|(3) manual page
107 for UTF8 terminals the \fBASN1_STRFLGS_ESC_MSB\fR should be unset: so for example
108 \&\fBXN_FLAG_ONELINE & ~ASN1_STRFLGS_ESC_MSB\fR would be used.
109 .PP
110 The complete set of the flags supported by \fBX509_NAME_print_ex()\fR is listed below.
111 .PP
112 Several options can be ored together.
113 .PP
114 The options \fBXN_FLAG_SEP_COMMA_PLUS\fR, \fBXN_FLAG_SEP_CPLUS_SPC\fR,
115 \&\fBXN_FLAG_SEP_SPLUS_SPC\fR and \fBXN_FLAG_SEP_MULTILINE\fR
116 determine the field separators to use.
117 Two distinct separators are used between distinct RelativeDistinguishedName
118 components and separate values in the same RDN for a multi-valued RDN.
119 Multi-valued RDNs are currently very rare
120 so the second separator will hardly ever be used.
121 .PP
122 \&\fBXN_FLAG_SEP_COMMA_PLUS\fR uses comma and plus as separators.
123 \&\fBXN_FLAG_SEP_CPLUS_SPC\fR uses comma and plus with spaces:
124 this is more readable that plain comma and plus.
125 \&\fBXN_FLAG_SEP_SPLUS_SPC\fR uses spaced semicolon and plus.
126 \&\fBXN_FLAG_SEP_MULTILINE\fR uses spaced newline and plus respectively.
127 .PP
128 If \fBXN_FLAG_DN_REV\fR is set the whole DN is printed in reversed order.
129 .PP
130 The fields \fBXN_FLAG_FN_SN\fR, \fBXN_FLAG_FN_LN\fR, \fBXN_FLAG_FN_OID\fR,
131 \&\fBXN_FLAG_FN_NONE\fR determine how a field name is displayed. It will
132 use the short name (e.g. CN) the long name (e.g. commonName) always
133 use OID numerical form (normally OIDs are only used if the field name is not
134 recognised) and no field name respectively.
135 .PP
136 If \fBXN_FLAG_SPC_EQ\fR is set then spaces will be placed around the '=' character
137 separating field names and values.
138 .PP
139 If \fBXN_FLAG_DUMP_UNKNOWN_FIELDS\fR is set then the encoding of unknown fields is
140 printed instead of the values.
141 .PP
142 If \fBXN_FLAG_FN_ALIGN\fR is set then field names are padded to 20 characters: this
143 is only of use for multiline format.
144 .PP
145 Additionally all the options supported by \fBASN1_STRING_print_ex()\fR can be used to
146 control how each field value is displayed.
147 .PP
148 In addition a number options can be set for commonly used formats.
149 .PP
150 \&\fBXN_FLAG_RFC2253\fR sets options which produce an output compatible with RFC2253.
151 It is equivalent to:
152 \f(CW\*(C`ASN1_STRFLGS_RFC2253 | XN_FLAG_SEP_COMMA_PLUS | XN_FLAG_DN_REV
153 | XN_FLAG_FN_SN | XN_FLAG_DUMP_UNKNOWN_FIELDS\*(C'\fR
154 .PP
155 \&\fBXN_FLAG_ONELINE\fR is a more readable one line format which is the same as:
156 \f(CW\*(C`ASN1_STRFLGS_RFC2253 | ASN1_STRFLGS_ESC_QUOTE | XN_FLAG_SEP_CPLUS_SPC
157 | XN_FLAG_SPC_EQ | XN_FLAG_FN_SN\*(C'\fR
158 .PP
159 \&\fBXN_FLAG_MULTILINE\fR is a multiline format which is the same as:
160 \f(CW\*(C`ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB | XN_FLAG_SEP_MULTILINE
161 | XN_FLAG_SPC_EQ | XN_FLAG_FN_LN | XN_FLAG_FN_ALIGN\*(C'\fR
162 .PP
163 \&\fBXN_FLAG_COMPAT\fR uses a format identical to \fBX509_NAME_print()\fR:
164 in fact it calls \fBX509_NAME_print()\fR internally.
165 .SH "RETURN VALUES"
166 .IX Header "RETURN VALUES"
167 \&\fBX509_NAME_oneline()\fR returns a valid string on success or NULL on error.
168 .PP
169 \&\fBX509_NAME_print()\fR returns 1 on success or 0 on error.
170 .PP
171 \&\fBX509_NAME_print_ex()\fR and \fBX509_NAME_print_ex_fp()\fR return 1 on success or 0 on
172 error if the \fBXN_FLAG_COMPAT\fR is set, which is the same as \fBX509_NAME_print()\fR.
173 Otherwise, it returns \-1 on error or other values on success.
174 .SH "SEE ALSO"
175 .IX Header "SEE ALSO"
176 \&\fBASN1_STRING_print_ex\fR\|(3)
177 .SH COPYRIGHT
178 .IX Header "COPYRIGHT"
179 Copyright 2002\-2026 The OpenSSL Project Authors. All Rights Reserved.
180 .PP
181 Licensed under the Apache License 2.0 (the "License"). You may not use
182 this file except in compliance with the License. You can obtain a copy
183 in the file LICENSE in the source distribution or at
184 <https://www.openssl.org/source/license.html>.