ASN1_TYPE_GET(3)

📦 version 4.1.0, in opensuse-leap 16.0

💅 ASN1_TYPE_GET(3) 💅

okay so bestie, this one's from the Library Functions Manual and it's all about ASN.1 objects that can literally be any type. it's giving "choose your own adventure" but for data encoding. let's get into it 🦋

✨ NAME ✨

ASN1_TYPE_new, ASN1_TYPE_free, ASN1_TYPE_get, ASN1_TYPE_set, ASN1_TYPE_set1, ASN1_TYPE_set_octetstring, ASN1_TYPE_get_octetstring, ASN1_TYPE_set_int_octetstring, ASN1_TYPE_get_int_octetstring, ASN1_TYPE_cmp — ASN.1 objects of arbitrary type 🎀

like, arbitrary. the main character energy of data types fr fr.

🌸 SYNOPSIS 🌸

#include <openssl/asn1.h>

ASN1_TYPE *
ASN1_TYPE_new(void);

void
ASN1_TYPE_free(ASN1_TYPE *a);

int
ASN1_TYPE_get(const ASN1_TYPE *a);

void
ASN1_TYPE_set(ASN1_TYPE *a, int type, void *value);

int
ASN1_TYPE_set1(ASN1_TYPE *a, int type, const void *value);

int
ASN1_TYPE_set_octetstring(ASN1_TYPE *a, const unsigned char *data,
    int len);

int
ASN1_TYPE_get_octetstring(const ASN1_TYPE *a, unsigned char *buffer,
    int buflen);

int
ASN1_TYPE_set_int_octetstring(ASN1_TYPE *a, long num,
    const unsigned char *data, int len);

int
ASN1_TYPE_get_int_octetstring(const ASN1_TYPE *a, ,,
    long *num,unsigned char *buffer, ,, int buflen);

int
ASN1_TYPE_cmp(const ASN1_TYPE *a, const ASN1_TYPE *b);
yes the ,, in ASN1_TYPE_get_int_octetstring is actually there in the real page. we don't fix it, we respect it. slay 💀

🦋 DESCRIPTION 🦋

so the ASN1_TYPE data type and the V_ASN1_ANY type identifier constant together represent the ASN.1 ANY type. an ASN1_TYPE object can store an ASN.1 value of arbitrary type — including constructed types like a SEQUENCE. and it remembers internally which type it's currently holding. it's giving "I contain multitudes" 💖

ASN1_TYPE_new() allocates and initializes an empty ASN1_TYPE object of type V_ASN1_UNDEF.

ASN1_TYPE_free() frees a, including the value stored in it if there is one. if a is a NULL pointer, nothing happens — no action, no drama, no tears.

ASN1_TYPE_get() returns the type currently held by a, represented by one of the V_ASN1_* constants defined in <openssl/asn1.h>.

ASN1_TYPE_set() frees the value contained in a (if any), then sets the value and type now held in a. heads up though — this function uses the pointer value internally, so you must NOT free it up after the call. like, it's not a copy, it's a situationship. keep that pointer alive 🙈

ASN1_TYPE_set1() sets the type held by a to type and its value to a copy of value. if copying succeeds, the previous value contained in a is freed. if copying fails, a stays unchanged. respectful. no half-finished updates. icon behavior ✨

the type and meaning of the value argument of ASN1_TYPE_set() and ASN1_TYPE_set1() is determined by the type argument:

  • if type is V_ASN1_NULL, value is ignored entirely (not even looked at, rude but valid)
  • if type is V_ASN1_BOOLEAN, then the boolean is set to TRUE if value is not NULL
  • if type is V_ASN1_OBJECT, then value is an ASN1_OBJECT structure
  • otherwise type is an ASN1_STRING structure

and about that last case: if type corresponds to a primitive type or a string type, then the contents of the ASN1_STRING contain the content octets of the type. if type corresponds to a constructed type or a tagged type (V_ASN1_SEQUENCE, V_ASN1_SET, or V_ASN1_OTHER), then the ASN1_STRING contains the entire ASN.1 encoding verbatim, including tag and length octets. like, the whole thing. no editing. 💅

ASN1_TYPE_set_octetstring() allocates a new ASN1_OCTET_STRING object, copies len bytes of data into it using ASN1_STRING_set(3), and replaces the value of a with it by calling ASN1_TYPE_set() with a type of V_ASN1_OCTET_STRING. three-step glow-up 🧚

ASN1_TYPE_get_octetstring() copies the contents of the ASN1_OCTET_STRING object contained in a into the caller-provided buffer — but not more than buflen bytes. truncation is possible, we'll get to it.

ASN1_TYPE_set_int_octetstring() frees the value contained in a (if any), sets its type to V_ASN1_SEQUENCE, and sets its value to a two-element ASN.1 sequence consisting of:

  1. an ASN.1 INTEGER object with the value num
  2. an ASN.1 OCTET STRING object containing a copy of the len bytes pointed to by data

a little duo. a package deal. 🫶

ASN1_TYPE_get_int_octetstring() copies the integer value from the first element of the ASN.1 sequence a into *num — unless num is a NULL pointer — and copies the octet string value from the second element into the caller-provided buffer — but not more than buflen bytes — unless buffer is a NULL pointer. pick and choose what you want back, we don't judge.

ASN1_TYPE_cmp() checks that a and b hold the same type, the same value, and are encoded in the same way. all three. no shortcuts.

⚠️ and this is the important part: if the types agree and the values have the same meaning but are encoded differently, they are considered different. example time — a boolean value is represented using a single content octet. under BER, any non-zero octet represents the TRUE value, but ASN1_TYPE_cmp() will only report a match if the content octet is the same. so 0x01 vs 0xFF? both "true" in spirit, but ASN1_TYPE_cmp() says nope. 💀

if either or both of the arguments passed to ASN1_TYPE_cmp() is NULL, the result is a mismatch. technically, if both arguments are NULL, the two types could be absent OPTIONAL fields and so should match — but passing NULL values could also indicate a programming error (for example an unparsable type which returns NULL) for types which do not match. so applications should handle the case of two absent values separately. don't make NULL do double duty, it's not built for it 😭

⭐ RETURN VALUES ⭐

ASN1_TYPE_new() returns the new ASN1_TYPE object, or NULL if an error occurs.

ASN1_TYPE_get() returns the type currently held by a, or 0 if an error occurs. that 0 case can happen if a doesn't contain a value even though its type is not V_ASN1_NULL — and like, it will always happen for empty objects newly constructed with ASN1_TYPE_new(). brand new and already returning zero, relatable honestly 🙈

ASN1_TYPE_set1(), ASN1_TYPE_set_octetstring(), and ASN1_TYPE_set_int_octetstring() return 1 on success or 0 on failure.

ASN1_TYPE_get_octetstring() returns the number of data bytes contained in the ASN1_OCTET_STRING object contained in a, or -1 if a is not of the type V_ASN1_OCTET_STRING or doesn't contain any object. and if the return value is greater than the buflen argument, the content was truncated when copied to the buffer — so check that number, bestie, don't just assume you got everything 🎀

ASN1_TYPE_get_int_octetstring() returns the number of data bytes contained in the ASN1_OCTET_STRING object that is the second element of the ASN.1 sequence a, or -1 if a is not of the type V_ASN1_SEQUENCE or if decoding fails. same truncation warning: if the return value is greater than the buflen argument, the content was truncated when copied to the buffer.

ASN1_TYPE_cmp() returns 0 for a match or non-zero for a mismatch. classic zero-means-success behavior, extremely Unix of it 💜

🌈 SEE ALSO 🌈

ASN1_generate_nconf(3), ASN1_get_object(3), ASN1_item_free(3), ASN1_OBJECT_new(3), ASN1_parse_dump(3), ASN1_put_object(3), ASN1_STRING_dup(3), ASN1_STRING_new(3), crypto(3), d2i_ASN1_NULL(3), d2i_ASN1_SEQUENCE_ANY(3), d2i_ASN1_TYPE(3), OBJ_dup(3)

the whole friend group. go say hi 👑✨

🎀 HISTORY 🎀

ASN1_TYPE_new() and ASN1_TYPE_free() first appeared in SSLeay 0.5.1. ASN1_TYPE_get() and ASN1_TYPE_set() showed up in SSLeay 0.8.0. and ASN1_TYPE_set_octetstring(), ASN1_TYPE_get_octetstring(), ASN1_TYPE_set_int_octetstring(), and ASN1_TYPE_get_int_octetstring() landed in SSLeay 0.9.0. these functions have been available since OpenBSD 2.4 — literal elders of the ecosystem, respect them 💐

ASN1_TYPE_set1() first appeared in OpenSSL 0.9.8h and has been available since OpenBSD 4.5.

ASN1_TYPE_cmp() first appeared in OpenSSL 0.9.8zd, 1.0.0p, and 1.0.1k, and has been available since OpenBSD 4.9. three versions at once, overachiever behavior ⭐

okay that's the whole page!! this one came from Debian, dated October 9, 2023 — so go forth, compare your ASN.1 objects byte-for-byte, and remember: same meaning ≠ same encoding, bestie 💖🦋✨

📦 where this page comes from