From 81d81082d1e65c494112369086f3a05486c56679 Mon Sep 17 00:00:00 2001 From: schwarze Date: Wed, 9 Aug 2023 17:27:26 +0000 Subject: [PATCH] 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@. --- lib/libcrypto/man/d2i_ASN1_OBJECT.3 | 70 ++++++++++++++++++++++++++--- 1 file changed, 65 insertions(+), 5 deletions(-) diff --git a/lib/libcrypto/man/d2i_ASN1_OBJECT.3 b/lib/libcrypto/man/d2i_ASN1_OBJECT.3 index a555490f659..cf750162e59 100644 --- 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 +.\" Copyright (c) 2017, 2022, 2023 Ingo Schwarze .\" .\" 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. -- 2.20.1