1.\" $OpenBSD: ASN1_get_object.3,v 1.2 2021/07/11 19:03:45 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.Xr ASN1_parse_dump 3 186.Sh STANDARDS 187ITU-T Recommendation X.690, also known as ISO/IEC 8825-1: 188Information technology - ASN.1 encoding rules: 189Specification of Basic Encoding Rules (BER), Canonical Encoding 190Rules (CER) and Distinguished Encoding Rules (DER): 191.Bl -dash -offset 2n -width 1n -compact 192.It 193Section 8.1.2: Identifier octets 194.It 195Section 8.1.3: Length octets 196.El 197.Sh HISTORY 198.Fn ASN1_get_object 199first appeared in SSLeay 0.5.1 and has been available since 200.Ox 2.4 . 201