summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
authorschwarze <>2021-07-11 15:30:21 +0000
committerschwarze <>2021-07-11 15:30:21 +0000
commit8382da87d2675e27bf4e94fb49c63feb542df36f (patch)
tree71c3974ebc92e1a242c68787df60809242ae4235 /src
parentc54835c3a81aadeb800379d608c618fcc193a794 (diff)
downloadopenbsd-8382da87d2675e27bf4e94fb49c63feb542df36f.tar.gz
openbsd-8382da87d2675e27bf4e94fb49c63feb542df36f.tar.bz2
openbsd-8382da87d2675e27bf4e94fb49c63feb542df36f.zip
document ASN1_get_object(3)
Diffstat (limited to 'src')
-rw-r--r--src/lib/libcrypto/man/ASN1_get_object.3199
-rw-r--r--src/lib/libcrypto/man/ASN1_item_d2i.35
-rw-r--r--src/lib/libcrypto/man/ASN1_item_new.35
-rw-r--r--src/lib/libcrypto/man/Makefile3
4 files changed, 207 insertions, 5 deletions
diff --git a/src/lib/libcrypto/man/ASN1_get_object.3 b/src/lib/libcrypto/man/ASN1_get_object.3
new file mode 100644
index 0000000000..a6dc288a06
--- /dev/null
+++ b/src/lib/libcrypto/man/ASN1_get_object.3
@@ -0,0 +1,199 @@
1.\" $OpenBSD: ASN1_get_object.3,v 1.1 2021/07/11 15:30:21 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: July 11 2021 $
18.Dt ASN1_GET_OBJECT 3
19.Os
20.Sh NAME
21.Nm ASN1_get_object
22.Nd parse identifier and length octets
23.Sh SYNOPSIS
24.In openssl/asn1.h
25.Ft int
26.Fo ASN1_get_object
27.Fa "const unsigned char **ber_in"
28.Fa "long *plength"
29.Fa "int *ptag"
30.Fa "int *pclass"
31.Fa "long omax"
32.Fc
33.Sh DESCRIPTION
34.Fn ASN1_get_object
35parses the identifier and length octets of a BER-encoded value.
36On function entry,
37.Pf * Fa ber_in
38is expected to point to the first identifier octet.
39If the identifier and length octets turn out to be valid,
40the function advances
41.Pf * Fa ber_in
42to the first content octet before returning.
43.Pp
44If the identifier octets are valid,
45.Fn ASN1_get_object
46stores the tag number in
47.Pf * Fa ptag
48and the class of the tag in
49.Pf * Fa pclass .
50The class is either
51.Dv V_ASN1_UNIVERSAL
52or
53.Dv V_ASN1_APPLICATION
54or
55.Dv V_ASN1_CONTEXT_SPECIFIC
56or
57.Dv V_ASN1_PRIVATE .
58.Pp
59If the length octets are valid, too,
60.Fn ASN1_get_object
61stores the number encoded in the length octets in
62.Pf * Fa plength .
63If the length octet indicates the indefinite form,
64.Pf * Fa plength
65is set to 0.
66.Pp
67.Fn ASN1_get_object
68inspects at most
69.Fa omax
70bytes.
71If parsing of the length octets remains incomplete after inspecting
72that number of bytes, parsing fails with
73.Dv ASN1_R_HEADER_TOO_LONG .
74.Sh RETURN VALUES
75Bits set in the return value of
76.Fn ASN1_get_object
77have the following meanings:
78.Bl -tag -width Ds
79.It 0x80
80An error occurred.
81One of the
82.Sx ERRORS
83described below has been set.
84.It 0x20 = Dv V_ASN1_CONSTRUCTED
85The encoding is constructed rather than primitive,
86and the identifier and length octets are valid.
87.It 0x01
88The length octet indicates the indefinite form.
89This bit can only occur if
90.Dv V_ASN1_CONSTRUCTED
91is also set.
92.El
93.Pp
94Consequently, the following combinations can occur:
95.Bl -tag -width Ds
96.It 0x00
97A valid primitive encoding.
98.It 0x20
99A valid constructed encoding, definite form.
100.It 0x21
101A valid constructed encoding, indefinite form.
102.It 0x80
103Either a primitive encoding with a valid tag and definite length,
104but the content octets won't fit into
105.Fa omax ,
106or parsing failed.
107Use
108.Xr ERR_GET_REASON 3
109to distinguish the two cases.
110.It 0xa0
111A constructed encoding with a valid tag and definite length,
112but the content octets won't fit into
113.Fa omax .
114.El
115.Pp
116The bit combinations 0x01, 0x81, and 0xa1 cannot occur as return values.
117.Sh ERRORS
118If the bit 0x80 is set in the return value,
119diagnostics can be retrieved with
120.Xr ERR_get_error 3 ,
121.Xr ERR_GET_REASON 3 ,
122and
123.Xr ERR_reason_error_string 3 :
124.Bl -tag -width Ds
125.It Dv ASN1_R_HEADER_TOO_LONG Qq "header too long"
126Inspecting
127.Fa omax
128bytes was insufficient to finish parsing,
129the tag number encoded in the identifier octets exceeds
130.Dv INT_MAX ,
131the number encoded in the length octets exceeds
132.Dv LONG_MAX ,
133or using the indefinite form for the length octets is attempted
134even though the encoding is primitive.
135.Pp
136In this case, the return value is exactly 0x80; no other bits are set.
137.Pp
138If the problem occurred while parsing the identifier octets,
139.Pf * Fa ptag
140and
141.Pf * Fa pclass
142remain unchanged.
143If the problem occurred while parsing the length octets,
144.Pf * Fa ptag
145and
146.Pf * Fa pclass
147are set according to the identifier octets.
148In both cases,
149.Pf * Fa ber_in
150and
151.Pf * Fa plength
152remain unchanged.
153.Pp
154The wording of the error message is confusing.
155On the one hand, the header might be just fine,
156and the root cause of the problem could be that the chosen
157.Fa omax
158argument was too small.
159On the other hand, outright BER syntax errors are also reported as
160.Dv ASN1_R_HEADER_TOO_LONG .
161.It Dv ASN1_R_TOO_LONG Qq "too long"
162The identifier and length octets are valid,
163but the content octets won't fit into
164.Fa omax .
165The following have been set as appropriate and can safely be inspected:
166.Pf * pclass ,
167.Pf * ptag ,
168.Pf * plength ,
169and the bits
170.Dv V_ASN1_CONSTRUCTED
171and 0x01 in the return value.
172The parse pointer
173.Pf * ber_in
174has been advanced to the first content octet.
175.Pp
176Again, the error message may occasionally sound confusing.
177The length of the content may be reasonable, and the root cause of
178the problem could be that the chosen
179.Fa omax
180argument was too small.
181.El
182.Sh SEE ALSO
183.Xr ASN1_item_d2i 3 ,
184.Xr ASN1_item_new 3
185.Sh STANDARDS
186ITU-T Recommendation X.690, also known as ISO/IEC 8825-1:
187Information technology - ASN.1 encoding rules:
188Specification of Basic Encoding Rules (BER), Canonical Encoding
189Rules (CER) and Distinguished Encoding Rules (DER):
190.Bl -dash -offset 2n -width 1n -compact
191.It
192Section 8.1.2: Identifier octets
193.It
194Section 8.1.3: Length octets
195.El
196.Sh HISTORY
197.Fn ASN1_get_object
198first appeared in SSLeay 0.5.1 and has been available since
199.Ox 2.4 .
diff --git a/src/lib/libcrypto/man/ASN1_item_d2i.3 b/src/lib/libcrypto/man/ASN1_item_d2i.3
index 429bbd8c59..140ea6f1ba 100644
--- a/src/lib/libcrypto/man/ASN1_item_d2i.3
+++ b/src/lib/libcrypto/man/ASN1_item_d2i.3
@@ -1,4 +1,4 @@
1.\" $OpenBSD: ASN1_item_d2i.3,v 1.9 2021/03/12 05:18:00 jsg Exp $ 1.\" $OpenBSD: ASN1_item_d2i.3,v 1.10 2021/07/11 15:30:21 schwarze Exp $
2.\" OpenSSL doc/man3/d2i_X509.pod b97fdb57 Nov 11 09:33:09 2016 +0100 2.\" OpenSSL doc/man3/d2i_X509.pod b97fdb57 Nov 11 09:33:09 2016 +0100
3.\" 3.\"
4.\" This file is a derived work. 4.\" This file is a derived work.
@@ -65,7 +65,7 @@
65.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 65.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
66.\" OF THE POSSIBILITY OF SUCH DAMAGE. 66.\" OF THE POSSIBILITY OF SUCH DAMAGE.
67.\" 67.\"
68.Dd $Mdocdate: March 12 2021 $ 68.Dd $Mdocdate: July 11 2021 $
69.Dt ASN1_ITEM_D2I 3 69.Dt ASN1_ITEM_D2I 3
70.Os 70.Os
71.Sh NAME 71.Sh NAME
@@ -361,6 +361,7 @@ if (d2i_X509(&x, &p, len) == NULL)
361 /* error */ 361 /* error */
362.Ed 362.Ed
363.Sh SEE ALSO 363.Sh SEE ALSO
364.Xr ASN1_get_object 3 ,
364.Xr ASN1_item_new 3 , 365.Xr ASN1_item_new 3 ,
365.Xr ASN1_TYPE_new 3 366.Xr ASN1_TYPE_new 3
366.Sh HISTORY 367.Sh HISTORY
diff --git a/src/lib/libcrypto/man/ASN1_item_new.3 b/src/lib/libcrypto/man/ASN1_item_new.3
index d45be112f1..a5bf8aa58f 100644
--- a/src/lib/libcrypto/man/ASN1_item_new.3
+++ b/src/lib/libcrypto/man/ASN1_item_new.3
@@ -1,4 +1,4 @@
1.\" $OpenBSD: ASN1_item_new.3,v 1.5 2019/06/14 13:59:32 schwarze Exp $ 1.\" $OpenBSD: ASN1_item_new.3,v 1.6 2021/07/11 15:30:21 schwarze Exp $
2.\" 2.\"
3.\" Copyright (c) 2016, 2018 Ingo Schwarze <schwarze@openbsd.org> 3.\" Copyright (c) 2016, 2018 Ingo Schwarze <schwarze@openbsd.org>
4.\" 4.\"
@@ -14,7 +14,7 @@
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\" 16.\"
17.Dd $Mdocdate: June 14 2019 $ 17.Dd $Mdocdate: July 11 2021 $
18.Dt ASN1_ITEM_NEW 3 18.Dt ASN1_ITEM_NEW 3
19.Os 19.Os
20.Sh NAME 20.Sh NAME
@@ -105,6 +105,7 @@ object if successful; otherwise
105is returned and an error code can be retrieved with 105is returned and an error code can be retrieved with
106.Xr ERR_get_error 3 . 106.Xr ERR_get_error 3 .
107.Sh SEE ALSO 107.Sh SEE ALSO
108.Xr ASN1_get_object 3 ,
108.Xr ASN1_item_d2i 3 , 109.Xr ASN1_item_d2i 3 ,
109.Xr ASN1_TYPE_new 3 , 110.Xr ASN1_TYPE_new 3 ,
110.Xr d2i_ASN1_NULL 3 , 111.Xr d2i_ASN1_NULL 3 ,
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 46a7d3beb2..be22431dc1 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
1# $OpenBSD: Makefile,v 1.176 2021/07/10 15:56:18 schwarze Exp $ 1# $OpenBSD: Makefile,v 1.177 2021/07/11 15:30:21 schwarze Exp $
2 2
3.include <bsd.own.mk> 3.include <bsd.own.mk>
4 4
@@ -14,6 +14,7 @@ MAN= \
14 ASN1_TIME_set.3 \ 14 ASN1_TIME_set.3 \
15 ASN1_TYPE_get.3 \ 15 ASN1_TYPE_get.3 \
16 ASN1_generate_nconf.3 \ 16 ASN1_generate_nconf.3 \
17 ASN1_get_object.3 \
17 ASN1_item_d2i.3 \ 18 ASN1_item_d2i.3 \
18 ASN1_item_new.3 \ 19 ASN1_item_new.3 \
19 ASN1_put_object.3 \ 20 ASN1_put_object.3 \