summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/d2i_ASN1_OBJECT.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/d2i_ASN1_OBJECT.3')
-rw-r--r--src/lib/libcrypto/man/d2i_ASN1_OBJECT.3164
1 files changed, 0 insertions, 164 deletions
diff --git a/src/lib/libcrypto/man/d2i_ASN1_OBJECT.3 b/src/lib/libcrypto/man/d2i_ASN1_OBJECT.3
deleted file mode 100644
index bbb70ad8c6..0000000000
--- a/src/lib/libcrypto/man/d2i_ASN1_OBJECT.3
+++ /dev/null
@@ -1,164 +0,0 @@
1.\" $OpenBSD: d2i_ASN1_OBJECT.3,v 1.15 2025/03/14 21:32:15 tb Exp $
2.\"
3.\" Copyright (c) 2017, 2022, 2023 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: March 14 2025 $
18.Dt D2I_ASN1_OBJECT 3
19.Os
20.Sh NAME
21.Nm d2i_ASN1_OBJECT ,
22.Nm i2d_ASN1_OBJECT ,
23.Nm OBJ_get0_data ,
24.Nm OBJ_length
25.Nd decode and encode ASN.1 object identifiers
26.Sh SYNOPSIS
27.In openssl/asn1.h
28.Ft ASN1_OBJECT *
29.Fo d2i_ASN1_OBJECT
30.Fa "ASN1_OBJECT **val_out"
31.Fa "const unsigned char **der_in"
32.Fa "long length"
33.Fc
34.Ft int
35.Fo i2d_ASN1_OBJECT
36.Fa "const ASN1_OBJECT *val_in"
37.Fa "unsigned char **der_out"
38.Fc
39.In openssl/objects.h
40.Ft const unsigned char *
41.Fn OBJ_get0_data "const ASN1_OBJECT *val_in"
42.Ft size_t
43.Fn OBJ_length "const ASN1_OBJECT *val_in"
44.Sh DESCRIPTION
45These functions decode and encode ASN.1 object identifiers.
46For details about the semantics, examples, caveats, and bugs, see
47.Xr ASN1_item_d2i 3 .
48.Pp
49The LibreSSL implementation of
50.Fn d2i_ASN1_OBJECT
51always calls
52.Xr ASN1_OBJECT_free 3
53if an existing object is passed in via
54.Fa val_out
55and it always creates a new object from scratch.
56Other implementations may attempt to reuse an existing object,
57which is fragile and prone to bugs.
58Consequently, always passing
59.Dv NULL
60for the
61.Fa val_out
62argument is recommended.
63.Pp
64The objects returned from
65.Fn d2i_ASN1_OBJECT
66and the data contained in them are always marked as dynamically
67allocated, so when they are no longer needed,
68.Xr ASN1_OBJECT_free 3
69can be called on them.
70.Pp
71.Fn i2d_ASN1_OBJECT
72encodes the object identifier pointed to by
73.Fa val_in
74into DER format.
75.Fn OBJ_get0_data
76and
77.Fn OBJ_length
78only deal with the content octets of that DER encoding,
79without taking the identifier and length octets into account.
80.Sh RETURN VALUES
81.Fn d2i_ASN1_OBJECT
82returns a pointer to the new
83.Vt ASN1_OBJECT
84object or
85.Dv NULL
86if an error occurs.
87With other implementations, it might return a pointer to the reused
88.Vt ASN1_OBJECT .
89.Pp
90.Fn i2d_ASN1_OBJECT
91returns the number of octets successfully encoded
92or a value <= 0 if an error occurs.
93.Pp
94.Fn OBJ_get0_data
95returns an internal pointer to the first content octet of the DER
96encoding of
97.Fa val_in .
98The other content octets follow the returned pointer contiguously.
99.Fn OBJ_length
100returns the number of content octets contained in the DER encoding of
101.Fa val_in .
102This number is always smaller than the total length of the encoding
103returned by
104.Xr ASN1_object_size 3 .
105.Pp
106If
107.Fa val_in
108is a
109.Dv NULL
110pointer or points to an empty object, for example one freshly created with
111.Xr ASN1_OBJECT_new 3 ,
112.Fn OBJ_get0_data
113returns
114.Dv NULL
115and
116.Fn OBJ_length
117returns zero.
118.Sh SEE ALSO
119.Xr a2d_ASN1_OBJECT 3 ,
120.Xr ASN1_item_d2i 3 ,
121.Xr ASN1_OBJECT_new 3 ,
122.Xr ASN1_put_object 3 ,
123.Xr OBJ_nid2obj 3
124.Sh STANDARDS
125ITU-T Recommendation X.690, also known as ISO/IEC 8825-1:
126Information technology - ASN.1 encoding rules:
127Specification of Basic Encoding Rules (BER), Canonical Encoding
128Rules (CER) and Distinguished Encoding Rules (DER),
129section 8.19: Encoding of an object identifier value
130.Sh HISTORY
131.Fn d2i_ASN1_OBJECT
132and
133.Fn i2d_ASN1_OBJECT
134first appeared in SSLeay 0.5.1 and have been available since
135.Ox 2.4 .
136.Pp
137.Fn OBJ_get0_data
138and
139.Fn OBJ_length
140first appeared in OpenSSL 1.1.0 and have been available since
141.Ox 7.1 .
142.Sh CAVEATS
143.Fn d2i_ASN1_OBJECT
144never sets the long and short names of the object, not even if the
145object identifier matches one that is built into the library.
146To find the names of an object identifier parsed from DER or BER
147input, call
148.Xr OBJ_obj2nid 3
149on the returned object, and then
150.Xr OBJ_nid2sn 3
151and
152.Xr OBJ_nid2ln 3
153on the result.
154.Pp
155Calling
156.Fn OBJ_get0_data
157and then accessing memory in front of the returned pointer
158results in undefined behaviour.
159In particular, it is not possible to find the identifier or
160length octets in that way; use
161.Xr ASN1_put_object 3
162or
163.Fn i2d_ASN1_OBJECT
164instead.