ASN1_INTEGER_GET(3)

📦 version 4.1.0, in opensuse-leap 16.0

💖 NAME 💖

Okay bestie, welcome to the ASN1_INTEGER_GET(3) page — it's from the Library Functions Manual, and it's lowkey the whole ASN.1 INTEGER/ENUMERATED utility squad. The full lineup is ASN1_INTEGER_get_uint64, ASN1_INTEGER_get_int64, ASN1_INTEGER_get, ASN1_INTEGER_set_uint64, ASN1_INTEGER_set_int64, ASN1_INTEGER_set, ASN1_INTEGER_cmp, ASN1_INTEGER_dup, BN_to_ASN1_INTEGER, ASN1_INTEGER_to_BN, ASN1_ENUMERATED_get_int64, ASN1_ENUMERATED_get, ASN1_ENUMERATED_set_int64, ASN1_ENUMERATED_set, BN_to_ASN1_ENUMERATED, and ASN1_ENUMERATED_to_BN — and they're all about ASN.1 INTEGER and ENUMERATED utilities. Periodt. 💅

✨ SYNOPSIS ✨

#include <openssl/asn1.h>

int
ASN1_INTEGER_get_uint64(uint64_t *out_val, const ASN1_INTEGER *a);

int
ASN1_INTEGER_get_int64(int64_t *out_val, const ASN1_INTEGER *a);

long
ASN1_INTEGER_get(const ASN1_INTEGER *a);

int
ASN1_INTEGER_set_uint64(ASN1_INTEGER *a, uint64_t v);

int
ASN1_INTEGER_set_int64(ASN1_INTEGER *a, int64_t v);

int
ASN1_INTEGER_set(ASN1_INTEGER *a, long v);

int
ASN1_INTEGER_cmp(const ASN1_INTEGER *a1, const ASN1_INTEGER *a2);

ASN1_INTEGER *
ASN1_INTEGER_dup(const ASN1_INTEGER *a);

ASN1_INTEGER *
BN_to_ASN1_INTEGER(const BIGNUM *bn, ASN1_INTEGER *ai);

BIGNUM *
ASN1_INTEGER_to_BN(const ASN1_INTEGER *ai, BIGNUM *bn);

int
ASN1_ENUMERATED_get_int64(int64_t *out_val, const ASN1_ENUMERATED *a);

long
ASN1_ENUMERATED_get(const ASN1_ENUMERATED *a);

int
ASN1_ENUMERATED_set_int64(ASN1_ENUMERATED *a, int64_t v);

int
ASN1_ENUMERATED_set(ASN1_ENUMERATED *a, long v);

ASN1_ENUMERATED *
BN_to_ASN1_ENUMERATED(const BIGNUM *bn, ASN1_ENUMERATED *ai);

BIGNUM *
ASN1_ENUMERATED_to_BN(const ASN1_ENUMERATED *ai, BIGNUM *bn);

🌸 DESCRIPTION 🌸

These functions convert to and from ASN1_INTEGER and ASN1_ENUMERATED objects. It's giving "glow-up between C types and ASN.1 types," and honestly? Iconic.

  • ASN1_INTEGER_get_uint64() and ASN1_INTEGER_get_int64() store the value of a in *out_val if successful. Slay. ✨
  • The deprecated function ASN1_INTEGER_get() converts a to the long type. Bestie, it's giving "legacy energy" — tread carefully.
  • ASN1_INTEGER_set_uint64(), ASN1_INTEGER_set_int64(), and ASN1_INTEGER_set() set the type of a to V_ASN1_INTEGER or V_ASN1_NEG_INTEGER depending on the sign of v, and set the value of a to v.
  • ASN1_INTEGER_cmp() compares the signed integer numbers represented by a1 and a2. It's a whole vibe check between two integers.
  • ASN1_INTEGER_dup() does exactly the same as ASN1_STRING_dup(3) without providing any type safety, except that it fails if the ASN1_STRING_length(3) of a is 0. Not me pointing out that "no type safety" detail — it's literally right there. 😭
  • BN_to_ASN1_INTEGER() converts bn to an ASN1_INTEGER. If ai is NULL, a new ASN1_INTEGER object is returned. Otherwise, the existing object ai is used instead.
  • ASN1_INTEGER_to_BN() converts ai into a BIGNUM. If bn is NULL, a new BIGNUM object is returned. Otherwise, the existing object bn is used instead.
  • ASN1_ENUMERATED_get_int64(), ASN1_ENUMERATED_get(), ASN1_ENUMERATED_set_int64(), ASN1_ENUMERATED_set(), BN_to_ASN1_ENUMERATED(), and ASN1_ENUMERATED_to_BN() behave like their ASN1_INTEGER counterparts except that they operate on an ASN1_ENUMERATED object. Same energy, different wrapper. 🦋

🎀 RETURN VALUES 🎀

  • ASN1_INTEGER_get_uint64() returns 1 in case of success or 0 if a is not of the type V_ASN1_INTEGER or greater than UINT64_MAX.
  • ASN1_INTEGER_get_int64() returns 1 in case of success or 0 if a is not of the type V_ASN1_INTEGER or V_ASN1_NEG_INTEGER, less than INT64_MIN, or greater than INT64_MAX.
  • ASN1_INTEGER_get() and ASN1_ENUMERATED_get() return the converted value, 0 if a is NULL, or -1 on error, which is ambiguous because -1 is a legitimate value for an ASN1_INTEGER. Yes, that's the messy part. 🙈
  • ASN1_INTEGER_set_uint64(), ASN1_INTEGER_set_int64(), ASN1_INTEGER_set(), ASN1_ENUMERATED_set_int64(), and ASN1_ENUMERATED_set() return 1 for success or 0 for failure. They only fail if a memory allocation error occurs.
  • ASN1_INTEGER_cmp() returns a value greater than, equal to, or less than 0 if the signed integer number represented by a1 is greater than, equal to, or less than the signed integer number represented by a2, respectively.
  • ASN1_INTEGER_dup() returns a pointer to a newly allocated ASN1_STRING structure or NULL if a is a NULL pointer, if the length of a is 0, or if memory allocation fails.
  • BN_to_ASN1_INTEGER() and BN_to_ASN1_ENUMERATED() return an ASN1_INTEGER or ASN1_ENUMERATED object, respectively, or NULL if an error occurs. They only fail due to memory allocation errors.
  • ASN1_INTEGER_to_BN() and ASN1_ENUMERATED_to_BN() return a BIGNUM object or NULL if an error occurs. They can fail if the passed type is incorrect (due to a programming error) or due to memory allocation failures.

🫶 SEE ALSO 🫶

🌈 HISTORY 🌈

  • ASN1_INTEGER_set() first appeared in SSLeay 0.5.1.
  • ASN1_INTEGER_get(), BN_to_ASN1_INTEGER(), and ASN1_INTEGER_to_BN() first appeared in SSLeay 0.6.0.
  • ASN1_INTEGER_cmp() and ASN1_INTEGER_dup() first appeared in SSLeay 0.6.5.
  • These functions have been available since OpenBSD 2.3.
  • ASN1_ENUMERATED_get(), ASN1_ENUMERATED_set(), BN_to_ASN1_ENUMERATED(), and ASN1_ENUMERATED_to_BN() first appeared in OpenSSL 0.9.2b and have been available since OpenBSD 2.6.
  • ASN1_INTEGER_get_uint64(), ASN1_INTEGER_get_int64(), ASN1_INTEGER_set_uint64(), ASN1_INTEGER_set_int64(), ASN1_ENUMERATED_get_int64(), and ASN1_ENUMERATED_set_int64() first appeared in OpenSSL 1.1.0 and have been available since OpenBSD 7.2.

⭐ CAVEATS ⭐

In general an ASN1_INTEGER or ASN1_ENUMERATED type can contain an integer of almost arbitrary size and so cannot always be represented by a C long type. The ambiguous return values of ASN1_INTEGER_get() and ASN1_ENUMERATED_get() imply that these functions should be avoided if possible.

Like, no cap — big ASN.1 integers can absolutely humble a plain long, and those ambiguous return values are not the moment. Avoid if you can, bestie. 💀

💜 BUGS 💜

ASN1_INTEGER_cmp(), ASN1_INTEGER_dup(), and ASN1_INTEGER_to_BN() do not check whether their arguments are really of the type V_ASN1_INTEGER or V_ASN1_NEG_INTEGER. They may report success even if their arguments are of a wrong type. Consequently, even in case of success, the return value of ASN1_INTEGER_dup() is not guaranteed to be of the type V_ASN1_INTEGER or V_ASN1_NEG_INTEGER either.

Similarly, ASN1_ENUMERATED_to_BN() does not check whether its argument is really of the type V_ASN1_ENUMERATED or V_ASN1_NEG_ENUMERATED and may report success even if the argument is of a wrong type.

💖 That's the whole page, bestie — Debian build, dated May 22, 2023. Now go forth and slay those ASN.1 conversions. 🎀✨

📦 where this page comes from