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