In objects.h rev. 1.14 and 1.15 (Jan 2022), tb@ provided

OBJ_get0_data(3) and OBJ_length(3).  Document them.
Feedback and OK tb@.

diff --git a/lib/libcrypto/man/d2i_ASN1_OBJECT.3 b/lib/libcrypto/man/d2i_ASN1_OBJECT.3
index a555490..cf75016 100644 (file)
--- a/lib/libcrypto/man/d2i_ASN1_OBJECT.3
+++ b/lib/libcrypto/man/d2i_ASN1_OBJECT.3
@@ -1,6 +1,6 @@
-.\" $OpenBSD: d2i_ASN1_OBJECT.3,v 1.13 2022/09/12 14:33:47 tb Exp $
+.\" $OpenBSD: d2i_ASN1_OBJECT.3,v 1.14 2023/08/09 17:27:26 schwarze Exp $
 .\"
-.\" Copyright (c) 2017, 2022 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2017, 2022, 2023 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -14,12 +14,14 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: September 12 2022 $
+.Dd $Mdocdate: August 9 2023 $
 .Dt D2I_ASN1_OBJECT 3
 .Os
 .Sh NAME
 .Nm d2i_ASN1_OBJECT ,
-.Nm i2d_ASN1_OBJECT
+.Nm i2d_ASN1_OBJECT ,
+.Nm OBJ_get0_data ,
+.Nm OBJ_length
 .Nd decode and encode ASN.1 object identifiers
 .Sh SYNOPSIS
 .In openssl/asn1.h
@@ -34,6 +36,11 @@
 .Fa "const ASN1_OBJECT *val_in"
 .Fa "unsigned char **der_out"
 .Fc
+.In openssl/objects.h
+.Ft const unsigned char *
+.Fn OBJ_get0_data "const ASN1_OBJECT *val_in"
+.Ft size_t
+.Fn OBJ_length "const ASN1_OBJECT *val_in"
 .Sh DESCRIPTION
 These functions decode and encode ASN.1 object identifiers.
 For details about the semantics, examples, caveats, and bugs, see
@@ -60,6 +67,16 @@ and the data contained in them are always marked as dynamically
 allocated, so when they are no longer needed,
 .Xr ASN1_OBJECT_free 3
 can be called on them.
+.Pp
+.Fn i2d_ASN1_OBJECT
+encodes the object identifier pointed to by
+.Fa val_in
+into DER format.
+.Fn OBJ_get0_data
+and
+.Fn OBJ_length
+only deal with the content octets of that DER encoding,
+without taking the identifier and length octets into account.
 .Sh RETURN VALUES
 .Fn d2i_ASN1_OBJECT
 returns a pointer to the new
@@ -71,12 +88,38 @@ With other implementations, it might return a pointer to the reused
 .Vt ASN1_OBJECT .
 .Pp
 .Fn i2d_ASN1_OBJECT
-returns the number of bytes successfully encoded
+returns the number of octets successfully encoded
 or a value <= 0 if an error occurs.
+.Pp
+.Fn OBJ_get0_data
+returns an internal pointer to the first content octet of the DER
+encoding of
+.Fa val_in .
+The other content octets follow the returned pointer contiguously.
+.Fn OBJ_length
+returns the number of content octets contained in the DER encoding of
+.Fa val_in .
+This number is always smaller than the total length of the encoding
+returned by
+.Xr ASN1_object_size 3 .
+.Pp
+If
+.Fa val_in
+is a
+.Dv NULL
+pointer or points to an empty object, for example one freshly created with
+.Xr ASN1_OBJECT_new 3 ,
+.Fn OBJ_get0_data
+returns
+.Dv NULL
+and
+.Fn OBJ_length
+returns zero.
 .Sh SEE ALSO
 .Xr a2d_ASN1_OBJECT 3 ,
 .Xr ASN1_item_d2i 3 ,
 .Xr ASN1_OBJECT_new 3 ,
+.Xr ASN1_put_object 3 ,
 .Xr OBJ_nid2obj 3
 .Sh STANDARDS
 ITU-T Recommendation X.690, also known as ISO/IEC 8825-1:
@@ -90,6 +133,12 @@ and
 .Fn i2d_ASN1_OBJECT
 first appeared in SSLeay 0.5.1 and have been available since
 .Ox 2.4 .
+.Pp
+.Fn OBJ_get0_data
+and
+.Fn OBJ_length
+first appeared in OpenSSL 1.1.0 and have been available since
+.Ox 7.1 .
 .Sh CAVEATS
 .Fn d2i_ASN1_OBJECT
 never sets the long and short names of the object, not even if the
@@ -102,3 +151,14 @@ on the returned object, and then
 and
 .Xr OBJ_nid2ln 3
 on the result.
+.Pp
+Calling
+.Fn OBJ_get0_data
+and then accessing memory in front of the returned pointer
+results in undefined behaviour.
+In particular, it is not possible to find the identifier or
+length octets in that way; use
+.Xr ASN1_put_object 3
+or
+.Fn i2d_ASN1_OBJECT
+instead.