1.\" $OpenBSD: ASN1_put_object.3,v 1.1 2019/08/26 11:41:31 schwarze Exp $ 2.\" 3.\" Copyright (c) 2019 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: August 26 2019 $ 18.Dt ASN1_PUT_OBJECT 3 19.Os 20.Sh NAME 21.Nm ASN1_put_object , 22.Nm ASN1_put_eoc 23.Nd start and end the BER encoding of an arbitrary ASN.1 data element 24.Sh SYNOPSIS 25.In openssl/asn1.h 26.Ft void 27.Fo ASN1_put_object 28.Fa "unsigned char **ber_out" 29.Fa "int constructed" 30.Fa "int length" 31.Fa "int tag" 32.Fa "int class" 33.Fc 34.Ft int 35.Fo ASN1_put_eoc 36.Fa "unsigned char **ber_out" 37.Fc 38.Sh DESCRIPTION 39.Fn ASN1_put_object 40begins writing the BER encoding of an arbitrary ASN.1 data element 41to the buffer 42.Pf * ber_out 43by writing the identifier and the length bytes. 44Making sure that there is sufficient space in the buffer 45is the responsibility of the caller. 46This function does not write any content bytes 47nor any end-of-content bytes. 48.Pp 49The tag 50.Fa class 51can be 52.Dv V_ASN1_UNIVERSAL , 53.Dv V_ASN1_APPLICATION , 54.Dv V_ASN1_CONTEXT_SPECIFIC , 55or 56.Dv V_ASN1_PRIVATE 57and is written to the two most significant bits of the first byte written. 58.Pp 59The 60.Fa constructed 61argument can have the following values: 62.Bl -tag -width 1n -offset 2n -compact 63.It 0 64Start a primitive value by setting the third most significant bit 65of the first byte written to 0. 66Always use the definite form. 67.It 1 68Start a constructed value by setting the third most significant bit 69of the first byte written to 1, and use the definite form. 70.It 2 71Start a constructed value and use the indefinite form, 72.El 73.Pp 74If the 75.Fa tag 76is less than 0x1f, it is written to the five least significant bits 77of the only identifier byte written. 78Otherwise, these five bits are all set to 1, and the 79.Fa tag 80is encoded in one or more following identifier bytes as needed. 81.Pp 82After completing the identifier byte(s), 83when using the definite form, the given 84.Fa length 85is encoded in one or more bytes as needed. 86Otherwise, the special byte 0x80 is written instead and the 87.Ar length 88argument is ignored. 89.Pp 90At the end, 91.Pf * Fa ber_out 92is set to the byte following the last byte written. 93The calling code can then start writing content bytes. 94.Pp 95If the indefinite form was selected, 96the calling code is also responsible for calling 97.Fn ASN1_put_eoc 98which writes an end-of-content marker to 99.Pf * Fa ber_out , 100consisting of two NUL bytes, and advances 101.Pf * Fa ber_out 102by two bytes. 103.Sh RETURN VALUES 104.Fn ASN1_put_eoc 105returns the number of bytes written, which is always 2. 106.Sh SEE ALSO 107.Xr ASN1_item_i2d 3 , 108.Xr ASN1_TYPE_get 3 , 109.Xr i2d_ASN1_NULL 3 , 110.Xr i2d_ASN1_OBJECT 3 , 111.Xr i2d_ASN1_OCTET_STRING 3 , 112.Xr i2d_ASN1_SEQUENCE_ANY 3 113.Sh HISTORY 114.Fn ASN1_put_object 115first appeared in SSLeay 0.5.1 and has been available since 116.Ox 2.4 . 117.Pp 118.Fn ASN1_put_eoc 119first appeared in OpenSSL 0.9.8 and has been available since 120.Ox 4.5 . 121.Sh CAVEATS 122Neither 123.Fn ASN1_put_object 124nor 125.Fn ASN1_put_eoc 126do any sanity checking. 127When called in inconsistent ways, invalid content may result in 128.Pf * Fa ber_out , 129for example 130.Bl -dash -compact 131.It 132a 133.Fa tag 134number less than 0x1f with a non-universal 135.Fa class 136.It 137a 138.Fa tag 139number equal to 0x00 or 0x1f 140.It 141a 142.Vt BOOLEAN , 143.Vt INTEGER , 144.Vt NULL 145etc. with the 146.Fa constructed 147bit set 148.It 149a 150.Vt SEQUENCE 151or 152.Vt SET 153etc. without the 154.Fa constructed 155bit set 156.It 157a 158.Fa length 159that makes no sense for the given 160.Fa tag 161.It 162a 163.Fa length 164that disagrees with the following data 165.It 166a 167.Vt BOOLEAN , 168.Vt INTEGER , 169.Vt NULL 170etc. in indefinite form 171.It 172an end-of-content marker even though no indefinite form was started 173.It 174\&... 175.El 176.Pp 177If the calling code wants to find out how many bytes were written, 178it needs to save a copy of the pointer 179.Pf * Fa ber_out 180before calling 181.Fn ASN1_put_object . 182