| blob | a246bbb93bbe2653a253e23bd9eb1cab351a0e6d |
1 .\" $OpenBSD: ASN1_STRING_print_ex.3,v 1.12 2018/03/22 17:11:04 schwarze Exp $
2 .\" full merge up to: OpenSSL bb9ad09e Jun 6 00:43:05 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.
6 .\" Copyright (c) 2002, 2004, 2007, 2013, 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 22 2018 $
54 .Dt ASN1_STRING_PRINT_EX 3
55 .Os
56 .Sh NAME
57 .Nm ASN1_STRING_print_ex ,
58 .Nm ASN1_STRING_print_ex_fp ,
59 .Nm ASN1_STRING_print ,
60 .Nm ASN1_tag2str
61 .Nd ASN1_STRING output routines
62 .Sh SYNOPSIS
63 .In openssl/asn1.h
64 .Ft int
65 .Fo ASN1_STRING_print_ex
66 .Fa "BIO *out"
67 .Fa "ASN1_STRING *str"
68 .Fa "unsigned long flags"
69 .Fc
70 .Ft int
71 .Fo ASN1_STRING_print_ex_fp
72 .Fa "FILE *fp"
73 .Fa "ASN1_STRING *str"
74 .Fa "unsigned long flags"
75 .Fc
76 .Ft int
77 .Fo ASN1_STRING_print
78 .Fa "BIO *out"
79 .Fa "ASN1_STRING *str"
80 .Fc
81 .Ft const char *
82 .Fo ASN1_tag2str
83 .Fa "int tag"
84 .Fc
85 .Sh DESCRIPTION
86 These functions output an
87 .Vt ASN1_STRING
88 structure.
89 .Vt ASN1_STRING
90 is used to
91 represent all the ASN.1 string types.
92 .Pp
93 .Fn ASN1_STRING_print_ex
94 outputs
95 .Fa str
96 to
97 .Fa out ,
98 the format being determined by the options
99 .Fa flags .
100 .Fn ASN1_STRING_print_ex_fp
101 is identical except it outputs to
102 .Fa fp
103 instead.
104 .Pp
105 .Fn ASN1_STRING_print
106 prints
107 .Fa str
108 to
109 .Fa out
110 but using a different format to
111 .Fn ASN1_STRING_print_ex .
112 It replaces unprintable characters (other than CR, LF) with
113 .Sq \&. .
114 .Pp
115 .Fn ASN1_tag2str
116 returns a human-readable name of the specified ASN.1
117 .Fa tag .
118 .Pp
119 .Fn ASN1_STRING_print
120 is a deprecated function which should be avoided; use
121 .Fn ASN1_STRING_print_ex
122 instead.
123 .Pp
124 Although there are a large number of options,
125 .Dv ASN1_STRFLGS_RFC2253
126 is often suitable, or on UTF-8 terminals
127 .Dv ASN1_STRFLGS_RFC2253
128 and
129 .Pf ~ Dv ASN1_STRFLGS_ESC_MSB .
130 .Pp
131 The complete set of supported options for
132 .Fa flags
133 is listed below.
134 .Pp
135 Various characters can be escaped.
136 If
137 .Dv ASN1_STRFLGS_ESC_2253
138 is set, the characters determined by RFC 2253 are escaped.
139 If
140 .Dv ASN1_STRFLGS_ESC_CTRL
141 is set, control characters are escaped.
142 If
143 .Dv ASN1_STRFLGS_ESC_MSB
144 is set, characters with the MSB set are escaped: this option should
145 .Em not
146 be used if the terminal correctly interprets UTF-8 sequences.
147 .Pp
148 Escaping takes several forms.
149 If the character being escaped is a 16-bit character then the form "\eUXXXX"
150 is used using exactly four characters for the hex representation.
151 If it is 32 bits then "\eWXXXXXXXX" is used using eight characters
152 of its hex representation.
153 These forms will only be used if UTF-8 conversion is not set (see below).
154 .Pp
155 Printable characters are normally escaped using the backslash
156 .Pq Sq \e
157 character.
158 If
159 .Dv ASN1_STRFLGS_ESC_QUOTE
160 is set, then the whole string is instead surrounded by double quote
161 characters: this is arguably more readable than the backslash notation.
162 Other characters use the "\eXX" using exactly two characters of the hex
163 representation.
164 .Pp
165 If
166 .Dv ASN1_STRFLGS_UTF8_CONVERT
167 is set, then characters are converted to UTF-8 format first.
168 If the terminal supports the display of UTF-8 sequences then this
169 option will correctly display multi-byte characters.
170 .Pp
171 If
172 .Dv ASN1_STRFLGS_IGNORE_TYPE
173 is set, then the string type is not interpreted at all:
174 everything is assumed to be one byte per character.
175 This is primarily for debugging purposes and can result
176 in confusing output in multi-character strings.
177 .Pp
178 If
179 .Dv ASN1_STRFLGS_SHOW_TYPE
180 is set, then the string type itself is printed before its value
181 (for example "BMPSTRING"), using
182 .Fn ASN1_tag2str .
183 .Pp
184 Instead of being interpreted the contents of a string can be "dumped":
185 this just outputs the value of the string using the form #XXXX
186 using hex format for each octet.
187 .Pp
188 If
189 .Dv ASN1_STRFLGS_DUMP_ALL
190 is set, then any type is dumped.
191 .Pp
192 Normally non-character string types (such as OCTET STRING)
193 are assumed to be one byte per character; if
194 .Dv ASN1_STRFLGS_DUMP_UNKNOWN
195 is set, then they will be dumped instead.
196 .Pp
197 When a type is dumped normally just the content octets are printed; if
198 .Dv ASN1_STRFLGS_DUMP_DER
199 is set, then the complete encoding is dumped
200 instead (including tag and length octets).
201 .Pp
202 .Dv ASN1_STRFLGS_RFC2253
203 includes all the flags required by RFC 2253.
204 It is equivalent to
205 .Dv ASN1_STRFLGS_ESC_2253 |
206 .Dv ASN1_STRFLGS_ESC_CTRL |
207 .Dv ASN1_STRFLGS_ESC_MSB |
208 .Dv ASN1_STRFLGS_UTF8_CONVERT |
209 .Dv ASN1_STRFLGS_DUMP_UNKNOWN |
210 .Dv ASN1_STRFLGS_DUMP_DER .
211 .Sh RETURN VALUES
212 .Fn ASN1_STRING_print_ex
213 and
214 .Fn ASN1_STRING_print_ex_fp
215 return the number of characters written or \-1 if an error occurred.
216 .Pp
217 .Fn ASN1_STRING_print
218 returns 1 on success or 0 on error.
219 .Pp
220 .Fn ASN1_tag2str
221 returns a static string.
222 .Sh SEE ALSO
223 .Xr X509_NAME_print_ex 3
224 .Sh HISTORY
225 .Fn ASN1_STRING_print
226 appeared in SSLeay 0.8.1b or earlier and has been available since
227 .Ox 2.4 .
228 .Pp
229 .Fn ASN1_tag2str
230 first appeared in OpenSSL 0.9.5 and has been available since
231 .Ox 2.7 .
232 .Pp
233 .Fn ASN1_STRING_print_ex
234 and
235 .Fn ASN1_STRING_print_ex_fp
236 first appeared in OpenSSL 0.9.6 and have been available since
237 .Ox 2.9 .