ASN1_ITEM_D2I_BIO(3ossl)

📦
version 15.1 · 2 versions
, in freebsd 15.1

💅 ASN1_ITEM_D2I_BIO — decode and encode DER-encoded ASN.1 structures (OpenSSL, section 3ossl)

okay so bestie, gather round 🫶 this is the <openssl/asn1.h> page for turning DER-encoded ASN.1 bytes into real live structures and back again. It's giving glow-up for buffers. ✨

🌸 NAME

ASN1_item_d2i_ex, ASN1_item_d2i, ASN1_item_d2i_bio_ex, ASN1_item_d2i_bio, ASN1_item_d2i_fp_ex, ASN1_item_d2i_fp, ASN1_item_i2d_mem_bio, ASN1_item_pack, ASN1_item_unpack_ex, ASN1_item_unpack — decode and encode DER-encoded ASN.1 structures. That's the whole squad 💜

✨ SYNOPSIS

#include <openssl/asn1.h>

ASN1_VALUE *ASN1_item_d2i_ex(ASN1_VALUE **pval, const unsigned char **in,
                             long len, const ASN1_ITEM *it,
                             OSSL_LIB_CTX *libctx, const char *propq);
ASN1_VALUE *ASN1_item_d2i(ASN1_VALUE **pval, const unsigned char **in,
                          long len, const ASN1_ITEM *it);

void *ASN1_item_d2i_bio_ex(const ASN1_ITEM *it, BIO *in, void *x,
                           OSSL_LIB_CTX *libctx, const char *propq);
void *ASN1_item_d2i_bio(const ASN1_ITEM *it, BIO *in, void *x);

void *ASN1_item_d2i_fp_ex(const ASN1_ITEM *it, FILE *in, void *x,
                          OSSL_LIB_CTX *libctx, const char *propq);
void *ASN1_item_d2i_fp(const ASN1_ITEM *it, FILE *in, void *x);

BIO *ASN1_item_i2d_mem_bio(const ASN1_ITEM *it, const ASN1_VALUE *val);

ASN1_STRING *ASN1_item_pack(void *obj, const ASN1_ITEM *it, ASN1_STRING **oct);

void *ASN1_item_unpack(const ASN1_STRING *oct, const ASN1_ITEM *it);

void *ASN1_item_unpack_ex(const ASN1_STRING *oct, const ASN1_ITEM *it,
                         OSSL_LIB_CTX *libctx, const char *propq);

Not me dropping the entire signature list unprompted 😭 but like, you need all of them, so.

🦋 DESCRIPTION

💖 the core decoder: ASN1_item_d2i_ex()

ASN1_item_d2i_ex() decodes the contents of the data stored in *in of length len, which must be a DER-encoded ASN.1 structure, using the ASN.1 template it. It places the result in *pval unless pval is NULL. If *pval is non-NULL on entry then the ASN1_VALUE present there will be reused. Otherwise a new ASN1_VALUE will be allocated. 🔥

If any algorithm fetches are required during the process, they'll use the OSSL_LIB_CTX provided in the libctx parameter and the property query string in propq. See "ALGORITHM FETCHING" in crypto(7) for more info about algorithm fetching — iykyk, go read it.

On exit *in will be updated to point to the next byte in the buffer after the decoded structure. The way it just walks forward, main character energy honestly 👑

🎀 ASN1_item_d2i()

Same as ASN1_item_d2i_ex() except the default OSSL_LIB_CTX is used (i.e. NULL) and with a NULL property query string. The no-frills version, and honestly? slay.

💅 ASN1_item_d2i_bio_ex()

Decodes the contents of its input BIO in, which must be a DER-encoded ASN.1 structure, using the ASN.1 template it, and places the result in *pval unless pval is NULL. If in is NULL it returns NULL, else a pointer to the parsed structure. 🫶

If any algorithm fetches are required during the process, they will use the OSSL_LIB_CTX provided in the libctx parameter and the property query string in propq. Again: see "ALGORITHM FETCHING" in crypto(7).

🌈 ASN1_item_d2i_bio()

Same as ASN1_item_d2i_bio_ex() except the default OSSL_LIB_CTX is used (i.e. NULL) and with a NULL property query string.

🍓 ASN1_item_d2i_fp_ex()

Same as ASN1_item_d2i_bio_ex() except that a FILE pointer is provided instead of a BIO. old school, still iconic.

🧚 ASN1_item_d2i_fp()

Same as ASN1_item_d2i_fp_ex() except the default OSSL_LIB_CTX is used (i.e. NULL) and with a NULL property query string.

⭐ ASN1_item_i2d_mem_bio()

Encodes the given ASN.1 value val using the ASN.1 template it and returns the result in a memory BIO. cute, contained, self-sufficient 💜

🌸 ASN1_item_pack()

Encodes the given ASN.1 value in obj using the ASN.1 template it and returns an ASN1_STRING object. If the passed in *oct is not NULL then this is used to store the returned result, otherwise a new ASN1_STRING object is created. If oct is not NULL and *oct is NULL then the returned return is also set into *oct.

🚨 okay important caveat, no cap: if there is an error, the optional passed in ASN1_STRING will not be freed, but the previous value may be cleared when ASN1_STRING_set0(*oct, NULL, 0) is called internally. Read that twice, bestie.

🔥 ASN1_item_unpack()

Uses ASN1_item_d2i() to decode the DER-encoded ASN1_STRING oct using the ASN.1 template it.

👑 ASN1_item_unpack_ex()

Similar to ASN1_item_unpack(), but uses ASN1_item_d2i_ex() so that the libctx and propq can be used when doing algorithm fetching. the upgraded version, fr fr.

🎀 RETURN VALUES

  • ASN1_item_d2i_bio(), ASN1_item_unpack_ex() and ASN1_item_unpack() return a pointer to an ASN1_VALUE or NULL on error.
  • ASN1_item_i2d_mem_bio() returns a pointer to a memory BIO or NULL on error.
  • ASN1_item_pack() returns a pointer to an ASN1_STRING or NULL on error.

NULL everywhere means error, so like… vibe check your returns, always 🙈

🕰️ HISTORY

  • The functions ASN1_item_d2i_ex(), ASN1_item_d2i_bio_ex(), ASN1_item_d2i_fp_ex() and ASN1_item_i2d_mem_bio() were added in OpenSSL 3.0.
  • The function ASN1_item_unpack_ex() was added in OpenSSL 3.2.

glow-ups with receipts 💅

Copyright 2021-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

and that's the page, bestie 🦋 this was OpenSSL 3.5.6, dated 2026-04-07, filed under ASN1_ITEM_D2I_BIO(3ossl) — go forth and decode responsibly, mwah 💋🎀

📦 where this page comes from