document ASN1_get_object(3)

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 @@
+.\" $OpenBSD: ASN1_get_object.3,v 1.1 2021/07/11 15:30:21 schwarze Exp $
+.\"
+.\" Copyright (c) 2021 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
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: July 11 2021 $
+.Dt ASN1_GET_OBJECT 3
+.Os
+.Sh NAME
+.Nm ASN1_get_object
+.Nd parse identifier and length octets
+.Sh SYNOPSIS
+.In openssl/asn1.h
+.Ft int
+.Fo ASN1_get_object
+.Fa "const unsigned char **ber_in"
+.Fa "long *plength"
+.Fa "int *ptag"
+.Fa "int *pclass"
+.Fa "long omax"
+.Fc
+.Sh DESCRIPTION
+.Fn ASN1_get_object
+parses the identifier and length octets of a BER-encoded value.
+On function entry,
+.Pf * Fa ber_in
+is expected to point to the first identifier octet.
+If the identifier and length octets turn out to be valid,
+the function advances
+.Pf * Fa ber_in
+to the first content octet before returning.
+.Pp
+If the identifier octets are valid,
+.Fn ASN1_get_object
+stores the tag number in
+.Pf * Fa ptag
+and the class of the tag in
+.Pf * Fa pclass .
+The class is either
+.Dv V_ASN1_UNIVERSAL
+or
+.Dv V_ASN1_APPLICATION
+or
+.Dv V_ASN1_CONTEXT_SPECIFIC
+or
+.Dv V_ASN1_PRIVATE .
+.Pp
+If the length octets are valid, too,
+.Fn ASN1_get_object
+stores the number encoded in the length octets in
+.Pf * Fa plength .
+If the length octet indicates the indefinite form,
+.Pf * Fa plength
+is set to 0.
+.Pp
+.Fn ASN1_get_object
+inspects at most
+.Fa omax
+bytes.
+If parsing of the length octets remains incomplete after inspecting
+that number of bytes, parsing fails with
+.Dv ASN1_R_HEADER_TOO_LONG .
+.Sh RETURN VALUES
+Bits set in the return value of
+.Fn ASN1_get_object
+have the following meanings:
+.Bl -tag -width Ds
+.It 0x80
+An error occurred.
+One of the
+.Sx ERRORS
+described below has been set.
+.It 0x20 = Dv V_ASN1_CONSTRUCTED
+The encoding is constructed rather than primitive,
+and the identifier and length octets are valid.
+.It 0x01
+The length octet indicates the indefinite form.
+This bit can only occur if
+.Dv V_ASN1_CONSTRUCTED
+is also set.
+.El
+.Pp
+Consequently, the following combinations can occur:
+.Bl -tag -width Ds
+.It 0x00
+A valid primitive encoding.
+.It 0x20
+A valid constructed encoding, definite form.
+.It 0x21
+A valid constructed encoding, indefinite form.
+.It 0x80
+Either a primitive encoding with a valid tag and definite length,
+but the content octets won't fit into
+.Fa omax ,
+or parsing failed.
+Use
+.Xr ERR_GET_REASON 3
+to distinguish the two cases.
+.It 0xa0
+A constructed encoding with a valid tag and definite length,
+but the content octets won't fit into
+.Fa omax .
+.El
+.Pp
+The bit combinations 0x01, 0x81, and 0xa1 cannot occur as return values.
+.Sh ERRORS
+If the bit 0x80 is set in the return value,
+diagnostics can be retrieved with
+.Xr ERR_get_error 3 ,
+.Xr ERR_GET_REASON 3 ,
+and
+.Xr ERR_reason_error_string 3 :
+.Bl -tag -width Ds
+.It Dv ASN1_R_HEADER_TOO_LONG Qq "header too long"
+Inspecting
+.Fa omax
+bytes was insufficient to finish parsing,
+the tag number encoded in the identifier octets exceeds
+.Dv INT_MAX ,
+the number encoded in the length octets exceeds
+.Dv LONG_MAX ,
+or using the indefinite form for the length octets is attempted
+even though the encoding is primitive.
+.Pp
+In this case, the return value is exactly 0x80; no other bits are set.
+.Pp
+If the problem occurred while parsing the identifier octets,
+.Pf * Fa ptag
+and
+.Pf * Fa pclass
+remain unchanged.
+If the problem occurred while parsing the length octets,
+.Pf * Fa ptag
+and
+.Pf * Fa pclass
+are set according to the identifier octets.
+In both cases,
+.Pf * Fa ber_in
+and
+.Pf * Fa plength
+remain unchanged.
+.Pp
+The wording of the error message is confusing.
+On the one hand, the header might be just fine,
+and the root cause of the problem could be that the chosen
+.Fa omax
+argument was too small.
+On the other hand, outright BER syntax errors are also reported as
+.Dv ASN1_R_HEADER_TOO_LONG .
+.It Dv ASN1_R_TOO_LONG Qq "too long"
+The identifier and length octets are valid,
+but the content octets won't fit into
+.Fa omax .
+The following have been set as appropriate and can safely be inspected:
+.Pf * pclass ,
+.Pf * ptag ,
+.Pf * plength ,
+and the bits
+.Dv V_ASN1_CONSTRUCTED
+and 0x01 in the return value.
+The parse pointer
+.Pf * ber_in
+has been advanced to the first content octet.
+.Pp
+Again, the error message may occasionally sound confusing.
+The length of the content may be reasonable, and the root cause of
+the problem could be that the chosen
+.Fa omax
+argument was too small.
+.El
+.Sh SEE ALSO
+.Xr ASN1_item_d2i 3 ,
+.Xr ASN1_item_new 3 
+.Sh STANDARDS
+ITU-T Recommendation X.690, also known as ISO/IEC 8825-1:
+Information technology - ASN.1 encoding rules:
+Specification of Basic Encoding Rules (BER), Canonical Encoding
+Rules (CER) and Distinguished Encoding Rules (DER):
+.Bl -dash -offset 2n -width 1n -compact
+.It
+Section 8.1.2: Identifier octets
+.It
+Section 8.1.3: Length octets
+.El
+.Sh HISTORY
+.Fn ASN1_get_object
+first appeared in SSLeay 0.5.1 and has been available since
+.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 @@
-.\"     $OpenBSD: ASN1_item_d2i.3,v 1.9 2021/03/12 05:18:00 jsg Exp $
+.\"     $OpenBSD: ASN1_item_d2i.3,v 1.10 2021/07/11 15:30:21 schwarze Exp $
 .\"     OpenSSL doc/man3/d2i_X509.pod b97fdb57 Nov 11 09:33:09 2016 +0100
 .\"
 .\" This file is a derived work.
@@ -65,7 +65,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: March 12 2021 $
+.Dd $Mdocdate: July 11 2021 $
 .Dt ASN1_ITEM_D2I 3
 .Os
 .Sh NAME
@@ -361,6 +361,7 @@ if (d2i_X509(&x, &p, len) == NULL)
         /* error */
 .Ed
 .Sh SEE ALSO
+.Xr ASN1_get_object 3 ,
 .Xr ASN1_item_new 3 ,
 .Xr ASN1_TYPE_new 3
 .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 @@
-.\"     $OpenBSD: ASN1_item_new.3,v 1.5 2019/06/14 13:59:32 schwarze Exp $
+.\"     $OpenBSD: ASN1_item_new.3,v 1.6 2021/07/11 15:30:21 schwarze Exp $
 .\"
 .\" Copyright (c) 2016, 2018 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: June 14 2019 $
+.Dd $Mdocdate: July 11 2021 $
 .Dt ASN1_ITEM_NEW 3
 .Os
 .Sh NAME
@@ -105,6 +105,7 @@ object if successful; otherwise
 is returned and an error code can be retrieved with
 .Xr ERR_get_error 3 .
 .Sh SEE ALSO
+.Xr ASN1_get_object 3 ,
 .Xr ASN1_item_d2i 3 ,
 .Xr ASN1_TYPE_new 3 ,
 .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 @@
-# $OpenBSD: Makefile,v 1.176 2021/07/10 15:56:18 schwarze Exp $
+# $OpenBSD: Makefile,v 1.177 2021/07/11 15:30:21 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -14,6 +14,7 @@ MAN=	\
         ASN1_TIME_set.3 \
         ASN1_TYPE_get.3 \
         ASN1_generate_nconf.3 \
+        ASN1_get_object.3 \
         ASN1_item_d2i.3 \
         ASN1_item_new.3 \
         ASN1_put_object.3 \