summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/ASN1_parse_dump.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/ASN1_parse_dump.3')
-rw-r--r--src/lib/libcrypto/man/ASN1_parse_dump.3216
1 files changed, 0 insertions, 216 deletions
diff --git a/src/lib/libcrypto/man/ASN1_parse_dump.3 b/src/lib/libcrypto/man/ASN1_parse_dump.3
deleted file mode 100644
index 50761f38aa..0000000000
--- a/src/lib/libcrypto/man/ASN1_parse_dump.3
+++ /dev/null
@@ -1,216 +0,0 @@
1.\" $OpenBSD: ASN1_parse_dump.3,v 1.3 2021/12/09 18:52:09 schwarze Exp $
2.\"
3.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: December 9 2021 $
18.Dt ASN1_PARSE_DUMP 3
19.Os
20.Sh NAME
21.Nm ASN1_parse_dump ,
22.Nm ASN1_parse
23.Nd parse BER and print information about it
24.Sh SYNOPSIS
25.In openssl/asn1.h
26.Ft int
27.Fo ASN1_parse_dump
28.Fa "BIO *bio"
29.Fa "const unsigned char *ber_in"
30.Fa "long length"
31.Fa "int indent"
32.Fa "int dump"
33.Fc
34.Ft int
35.Fo ASN1_parse
36.Fa "BIO *bio"
37.Fa "const unsigned char *ber_in"
38.Fa "long length"
39.Fa "int indent"
40.Fc
41.Sh DESCRIPTION
42.Fn ASN1_parse_dump
43parses BER-encoded values and prints information about them to
44.Fa bio .
45On function entry,
46.Pf * Fa ber_in
47is expected to point to the first identifier octet of an encoded value.
48At most
49.Fa length
50bytes are inspected.
51.Pp
52For each value successfully parsed, the following information is printed:
53.Bl -enum
54.It
55The index of its first identifier octet relative to
56.Fa ber_in
57as a decimal number followed by a colon.
58For the first value parsed and printed, this is
59.Qq 0:\& .
60.It
61The nesting depth as a decimal integer.
62For the first value parsed and printed, this is
63.Qq d=0 .
64.It
65The header length in bytes, including the identifier octets and the
66length octets, as a decimal integer.
67For example, for a boolean value, this is
68.Qq hl=2
69because the encoding of a boolean value contains
70one identifier octet (0x01) and one length octet (also 0x01,
71because one content octet follows after the header).
72.It
73If the value is encoded using the definite form for the length octets,
74the number encoded in the length octets as a decimal integer.
75This is the number of content octets that follow.
76For example, for a boolean value, this is
77.Qq l=1 .
78If the value is encoded using a length octet indicating the indefinite form,
79.Qq l=inf
80is printed instead.
81.It
82If the value is primitive,
83.Qq prim:\&
84is printed;
85if it is constructed,
86.Qq cons:\& .
87.It
88The next field depends on the class of the tag:
89.Bl -tag -width Ds
90.It Dv V_ASN1_PRIVATE
91.Qq priv
92followed by the decimal tag number in square brackets
93.It Dv V_ASN1_CONTEXT_SPECIFIC
94.Qq cont
95followed by the decimal tag number in square brackets
96.It Dv V_ASN1_APPLICATION
97.Qq appl
98followed by the decimal tag number in square brackets
99.It V_ASN1_UNIVERSAL
100If the tag number is 30 or less, the return value from
101.Xr ASN1_tag2str 3
102is printed; otherwise,
103.Qq <ASN1
104followed by the decimal tag number and a closing angle bracket.
105.El
106.El
107.Pp
108For constructed values, the contained values are recursively printed.
109.Pp
110Primitive values are processed as follows:
111.Bl -tag -width Ds
112.It Dv V_ASN1_BOOLEAN
113Its integer value is printed as a decimal number.
114.It Dv V_ASN1_INTEGER
115Decoded with
116.Xr d2i_ASN1_INTEGER 3 ,
117printed as a hexadecimal number with an even number of digits.
118.It Dv V_ASN1_ENUMERATED
119Decoded with
120.Xr d2i_ASN1_ENUMERATED 3 ,
121printed as a hexadecimal number with an even number of digits.
122.It Dv V_ASN1_OBJECT
123Decoded with
124.Xr d2i_ASN1_OBJECT 3 ,
125printed with
126.Xr i2a_ASN1_OBJECT 3 .
127.It Dv V_ASN1_OCTET_STRING
128Decoded with
129.Xr d2i_ASN1_OCTET_STRING 3 .
130If the data consists only of printable ASCII characters, line feeds,
131carriage returns and horizontal tabs, it is printed as an ASCII string.
132.Pp
133Otherwise, the
134.Fa dump
135argument decides the format.
136If it is zero, a raw hex dump is emitted, consisting of two hexadecimal
137digits for every data byte.
138If
139.Fa dump
140is non-zero,
141.Xr BIO_dump_indent 3
142is used.
143Unless
144.Fa dump
145is \-1, the data is truncated after
146.Fa dump
147bytes.
148.It Dv V_ASN1_PRINTABLESTRING
149Printed as an ASCII string.
150The same applies to
151.Dv V_ASN1_IA5STRING ,
152.Dv V_ASN1_T61STRING ,
153.Dv V_ASN1_NUMERICSTRING ,
154.Dv V_ASN1_VISIBLESTRING ,
155.Dv V_ASN1_UTF8STRING ,
156.Dv V_ASN1_UTCTIME ,
157and
158.Dv V_ASN1_GENERALIZEDTIME .
159.It Other tags
160If the
161.Fa dump
162argument is 0, their data is silently ignored.
163If
164.Fa dump
165is non-zero,
166.Xr BIO_dump_indent 3
167is used.
168Unless
169.Fa dump
170is \-1, the data is truncated after
171.Fa dump
172bytes.
173.El
174.Pp
175.Fn ASN1_parse
176is identical to
177.Fn ASN1_parse_dump
178with 0 passed as the
179.Fa dump
180argument.
181.Sh RETURN VALUES
182These functions return 1 for success or 0 for failure.
183.Pp
184In particular, they print an error message to
185.Fa bio ,
186abort parsing and printing, and return 0
187when parsing or decoding fails, when a recursive call fails,
188when encountering a value extending beyond
189.Fa length ,
190or when encountering a nesting level in excess of 128.
191They also abort parsing and printing and return 0
192when any printing operation fails.
193.Sh SEE ALSO
194.Xr ASN1_get_object 3 ,
195.Xr ASN1_item_d2i 3 ,
196.Xr ASN1_item_new 3 ,
197.Xr ASN1_STRING_print 3 ,
198.Xr ASN1_TYPE_new 3
199.Sh STANDARDS
200ITU-T Recommendation X.690, also known as ISO/IEC 8825-1:
201Information technology - ASN.1 encoding rules:
202Specification of Basic Encoding Rules (BER), Canonical Encoding
203Rules (CER) and Distinguished Encoding Rules (DER),
204section 8.1: General rules for encoding
205.Sh HISTORY
206.Fn ASN1_parse
207first appeared in SSLeay 0.5.1 and has been available since
208.Ox 2.4 .
209.Pp
210.Fn ASN1_parse_dump
211first appeared in OpenSSL 0.9.6 and has been available since
212.Ox 2.9 .
213.Sh BUGS
214The content of values tagged as
215.Dv V_ASN1_BMPSTRING
216is silently ignored and none of it is printed.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-12-23 15:15:40 +0000