1.\" $OpenBSD: d2i_ASN1_OBJECT.3,v 1.13 2022/09/12 14:33:47 tb Exp $ 2.\" 3.\" Copyright (c) 2017, 2022 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: September 12 2022 $ 18.Dt D2I_ASN1_OBJECT 3 19.Os 20.Sh NAME 21.Nm d2i_ASN1_OBJECT , 22.Nm i2d_ASN1_OBJECT 23.Nd decode and encode ASN.1 object identifiers 24.Sh SYNOPSIS 25.In openssl/asn1.h 26.Ft ASN1_OBJECT * 27.Fo d2i_ASN1_OBJECT 28.Fa "ASN1_OBJECT **val_out" 29.Fa "unsigned char **der_in" 30.Fa "long length" 31.Fc 32.Ft int 33.Fo i2d_ASN1_OBJECT 34.Fa "const ASN1_OBJECT *val_in" 35.Fa "unsigned char **der_out" 36.Fc 37.Sh DESCRIPTION 38These functions decode and encode ASN.1 object identifiers. 39For details about the semantics, examples, caveats, and bugs, see 40.Xr ASN1_item_d2i 3 . 41.Pp 42The LibreSSL implementation of 43.Fn d2i_ASN1_OBJECT 44always calls 45.Xr ASN1_OBJECT_free 3 46if an existing object is passed in via 47.Fa val_out 48and it always creates a new object from scratch. 49Other implementations may attempt to reuse an existing object, 50which is fragile and prone to bugs. 51Consequently, always passing 52.Dv NULL 53for the 54.Fa val_out 55argument is recommended. 56.Pp 57The objects returned from 58.Fn d2i_ASN1_OBJECT 59and the data contained in them are always marked as dynamically 60allocated, so when they are no longer needed, 61.Xr ASN1_OBJECT_free 3 62can be called on them. 63.Sh RETURN VALUES 64.Fn d2i_ASN1_OBJECT 65returns a pointer to the new 66.Vt ASN1_OBJECT 67object or 68.Dv NULL 69if an error occurs. 70With other implementations, it might return a pointer to the reused 71.Vt ASN1_OBJECT . 72.Pp 73.Fn i2d_ASN1_OBJECT 74returns the number of bytes successfully encoded 75or a value <= 0 if an error occurs. 76.Sh SEE ALSO 77.Xr a2d_ASN1_OBJECT 3 , 78.Xr ASN1_item_d2i 3 , 79.Xr ASN1_OBJECT_new 3 , 80.Xr OBJ_nid2obj 3 81.Sh STANDARDS 82ITU-T Recommendation X.690, also known as ISO/IEC 8825-1: 83Information technology - ASN.1 encoding rules: 84Specification of Basic Encoding Rules (BER), Canonical Encoding 85Rules (CER) and Distinguished Encoding Rules (DER), 86section 8.19: Encoding of an object identifier value 87.Sh HISTORY 88.Fn d2i_ASN1_OBJECT 89and 90.Fn i2d_ASN1_OBJECT 91first appeared in SSLeay 0.5.1 and have been available since 92.Ox 2.4 . 93.Sh CAVEATS 94.Fn d2i_ASN1_OBJECT 95never sets the long and short names of the object, not even if the 96object identifier matches one that is built into the library. 97To find the names of an object identifier parsed from DER or BER 98input, call 99.Xr OBJ_obj2nid 3 100on the returned object, and then 101.Xr OBJ_nid2sn 3 102and 103.Xr OBJ_nid2ln 3 104on the result. 105