1.\" $OpenBSD: ASN1_put_object.3,v 1.5 2022/01/12 17:54:51 tb Exp $ 2.\" 3.\" Copyright (c) 2019, 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: January 12 2022 $ 18.Dt ASN1_PUT_OBJECT 3 19.Os 20.Sh NAME 21.Nm ASN1_put_object , 22.Nm ASN1_put_eoc , 23.Nm ASN1_object_size 24.Nd start and end the BER encoding of an arbitrary ASN.1 data element 25.Sh SYNOPSIS 26.In openssl/asn1.h 27.Ft void 28.Fo ASN1_put_object 29.Fa "unsigned char **ber_out" 30.Fa "int constructed" 31.Fa "int content_length" 32.Fa "int tag" 33.Fa "int class" 34.Fc 35.Ft int 36.Fo ASN1_put_eoc 37.Fa "unsigned char **ber_out" 38.Fc 39.Ft int 40.Fo ASN1_object_size 41.Fa "int constructed" 42.Fa "int content_length" 43.Fa "int tag" 44.Fc 45.Sh DESCRIPTION 46.Fn ASN1_put_object 47begins writing the BER encoding of an arbitrary ASN.1 data element 48to the buffer 49.Pf * ber_out 50by writing the identifier and the length bytes. 51Making sure that there is sufficient space in the buffer 52is the responsibility of the caller. 53This function does not write any content bytes 54nor any end-of-content bytes. 55.Pp 56The tag 57.Fa class 58can be 59.Dv V_ASN1_UNIVERSAL , 60.Dv V_ASN1_APPLICATION , 61.Dv V_ASN1_CONTEXT_SPECIFIC , 62or 63.Dv V_ASN1_PRIVATE 64and is written to the two most significant bits of the first byte written. 65.Pp 66The 67.Fa constructed 68argument can have the following values: 69.Bl -tag -width 1n -offset 2n -compact 70.It 0 71Start a primitive value by setting the third most significant bit 72of the first byte written to 0. 73Always use the definite form. 74.It 1 75Start a constructed value by setting the third most significant bit 76of the first byte written to 1, and use the definite form. 77.It 2 78Start a constructed value and use the indefinite form, 79.El 80.Pp 81If the 82.Fa tag 83is less than 84.Dv V_ASN1_PRIMITIVE_TAG Pq = 0x1f , 85it is written to the five least significant bits 86of the only identifier byte written. 87Otherwise, these five bits are all set to 1, and the 88.Fa tag 89is encoded in one or more following identifier bytes as needed. 90.Pp 91After completing the identifier byte(s), 92when using the definite form, the given 93.Fa content_length 94is encoded in one or more bytes as needed, 95using the long form if and only if the 96.Fa content_length 97is greater than 127. 98When using the indefinite form, 99the special byte 0x80 is written instead and the 100.Fa content_length 101argument is ignored. 102.Pp 103At the end, 104.Pf * Fa ber_out 105is set to the byte following the last byte written. 106The calling code can then start writing content bytes. 107.Pp 108If the indefinite form was selected, 109the calling code is also responsible for calling 110.Fn ASN1_put_eoc 111which writes an end-of-content marker to 112.Pf * Fa ber_out , 113consisting of two NUL bytes, and advances 114.Pf * Fa ber_out 115by two bytes. 116.Pp 117.Fn ASN1_object_size 118calculates the total length in bytes of the BER encoding 119of an ASN.1 data element with the given 120.Fa tag 121and the number of content bytes given by 122.Fa content_length . 123The 124.Fa constructed 125argument has the same meaning as for 126.Fn ASN1_put_object . 127The return value includes the identifier, length, and content bytes. 128If 129.Fa constructed 130is 2, it also includes the end-of-content bytes. 131For the definite form, only the short form is supported if the 132.Fa content_length 133is less than 128. 134.Sh RETURN VALUES 135.Fn ASN1_put_eoc 136returns the number of bytes written, which is always 2. 137.Pp 138.Fn ASN1_object_size 139returns the total number of bytes in the encoding of the data element. 140.Sh SEE ALSO 141.Xr ASN1_item_i2d 3 , 142.Xr ASN1_TYPE_get 3 , 143.Xr i2d_ASN1_NULL 3 , 144.Xr i2d_ASN1_OBJECT 3 , 145.Xr i2d_ASN1_OCTET_STRING 3 , 146.Xr i2d_ASN1_SEQUENCE_ANY 3 147.Sh STANDARDS 148ITU-T Recommendation X.690, also known as ISO/IEC 8825-1: 149Information technology - ASN.1 encoding rules: 150Specification of Basic Encoding Rules (BER), Canonical Encoding 151Rules (CER) and Distinguished Encoding Rules (DER), 152section 8.1: General rules for encoding 153.Sh HISTORY 154.Fn ASN1_put_object 155and 156.Fn ASN1_object_size 157first appeared in SSLeay 0.5.1 and have been available since 158.Ox 2.4 . 159.Pp 160.Fn ASN1_put_eoc 161first appeared in OpenSSL 0.9.8 and has been available since 162.Ox 4.5 . 163.Sh CAVEATS 164None of these functions do any sanity checking. 165When called in inconsistent ways, invalid content may result in 166.Pf * Fa ber_out , 167for example 168.Bl -dash -compact 169.It 170a 171.Fa tag 172number less than 173.Dv V_ASN1_PRIMITIVE_TAG 174with a 175.Fa class 176other than 177.Dv V_ASN1_UNIVERSAL 178.It 179a 180.Fa tag 181number equal to 182.Dv V_ASN1_EOC Pq 0x00 183or 184.Dv V_ASN1_PRIMITIVE_TAG Pq 0x1f 185.It 186a 187.Vt BOOLEAN , 188.Vt INTEGER , 189.Vt NULL 190etc. with the 191.Fa constructed 192bit set 193.It 194a 195.Vt SEQUENCE 196or 197.Vt SET 198etc. without the 199.Fa constructed 200bit set 201.It 202a 203.Fa content_length 204that makes no sense for the given 205.Fa tag 206.It 207a 208.Fa content_length 209that disagrees with the following data 210.It 211a 212.Vt BOOLEAN , 213.Vt INTEGER , 214.Vt NULL 215etc. in indefinite form 216.It 217an end-of-content marker even though no indefinite form was started 218.It 219\&... 220.El 221.Pp 222If the calling code wants to find out how many bytes were written, 223it needs to save a copy of the pointer 224.Pf * Fa ber_out 225before calling 226.Fn ASN1_put_object . 227