NAME
d2i_ASN1_OBJECT,
i2d_ASN1_OBJECT,
OBJ_get0_data, OBJ_length
— decode and encode ASN.1 object
identifiers
SYNOPSIS
#include
<openssl/asn1.h>
ASN1_OBJECT *
d2i_ASN1_OBJECT(ASN1_OBJECT
**val_out, unsigned char **der_in,
long length);
int
i2d_ASN1_OBJECT(const ASN1_OBJECT
*val_in, unsigned char **der_out);
#include
<openssl/objects.h>
const unsigned char *
OBJ_get0_data(const
ASN1_OBJECT *val_in);
size_t
OBJ_length(const
ASN1_OBJECT *val_in);
DESCRIPTION
These functions decode and encode ASN.1 object identifiers. For details about the semantics, examples, caveats, and bugs, see ASN1_item_d2i(3).
The LibreSSL implementation of
d2i_ASN1_OBJECT()
always calls
ASN1_OBJECT_free(3) if an existing object is passed in via
val_out and it always creates a new object from
scratch. Other implementations may attempt to reuse an existing object,
which is fragile and prone to bugs. Consequently, always passing
NULL for the val_out argument
is recommended.
The objects returned from
d2i_ASN1_OBJECT()
and the data contained in them are always marked as dynamically allocated,
so when they are no longer needed,
ASN1_OBJECT_free(3) can be called on them.
i2d_ASN1_OBJECT()
encodes the object identifier pointed to by val_in
into DER format.
OBJ_get0_data()
and
OBJ_length()
only deal with the content octets of that DER encoding, without taking the
identifier and length octets into account.
RETURN VALUES
d2i_ASN1_OBJECT() returns a pointer to the
new ASN1_OBJECT object or NULL
if an error occurs. With other implementations, it might return a pointer to
the reused ASN1_OBJECT.
i2d_ASN1_OBJECT() returns the number of
octets successfully encoded or a value <= 0 if an error occurs.
OBJ_get0_data() returns an internal
pointer to the first content octet of the DER encoding of
val_in. The other content octets follow the returned
pointer contiguously. OBJ_length() returns the
number of content octets contained in the DER encoding of
val_in. This number is always smaller than the total
length of the encoding returned by
ASN1_object_size(3).
If val_in is a NULL
pointer or points to an empty object, for example one freshly created with
ASN1_OBJECT_new(3), OBJ_get0_data() returns
NULL and OBJ_length()
returns zero.
SEE ALSO
a2d_ASN1_OBJECT(3), ASN1_item_d2i(3), ASN1_OBJECT_new(3), ASN1_put_object(3), OBJ_nid2obj(3)
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), section 8.19: Encoding of an object identifier value
HISTORY
d2i_ASN1_OBJECT() and
i2d_ASN1_OBJECT() first appeared in SSLeay 0.5.1 and
have been available since OpenBSD 2.4.
OBJ_get0_data() and
OBJ_length() first appeared in OpenSSL 1.1.0 and
have been available since OpenBSD 7.1.
CAVEATS
d2i_ASN1_OBJECT() never sets the long and
short names of the object, not even if the object identifier matches one
that is built into the library. To find the names of an object identifier
parsed from DER or BER input, call
OBJ_obj2nid(3) on the returned object, and then
OBJ_nid2sn(3) and
OBJ_nid2ln(3) on the result.
Calling OBJ_get0_data() and then accessing
memory in front of the returned pointer results in undefined behaviour. In
particular, it is not possible to find the identifier or length octets in
that way; use
ASN1_put_object(3) or i2d_ASN1_OBJECT()
instead.