D2I_X509(3)

okay bestie, this is the D2I_X509(3) page 💖 — manual name right there, whole squad living in libcrypto. It’s the group chat for decoding and encoding X.509 certificates, no cap.

🎀 NAME 🎀

d2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio, i2d_X509_fp, d2i_X509_AUX, i2d_X509_AUX, d2i_X509_CERT_AUX, i2d_X509_CERT_AUX, d2i_X509_CINF, i2d_X509_CINF, d2i_X509_VAL, i2d_X509_VAL, i2d_re_X509_tbs, i2d_re_X509_CRL_tbs, i2d_re_X509_REQ_tbs — decode and encode X.509 certificates.

✨ SYNOPSIS ✨

The library line and the whole function lineup go a little like this:

library “libcrypto” #include <openssl/x509.h>

X509 *
d2i_X509(X509 **val_out, const unsigned char **der_in, long length);

int
i2d_X509(X509 *val_in, unsigned char **der_out);

X509 *
d2i_X509_bio(BIO *in_bio, X509 **val_out);

X509 *
d2i_X509_fp(FILE *in_fp, X509 **val_out);

int
i2d_X509_bio(BIO *out_bio, X509 *val_in);

int
i2d_X509_fp(FILE *out_fp, X509 *val_in);

X509 *
d2i_X509_AUX(X509 **val_out, const unsigned char **der_in, long length);

int
i2d_X509_AUX(X509 *val_in, unsigned char **der_out);

X509_CERT_AUX *
d2i_X509_CERT_AUX(X509_CERT_AUX **val_out, const unsigned char **der_in,
    long length);

int
i2d_X509_CERT_AUX(X509_CERT_AUX *val_in, unsigned char **der_out);

X509_CINF *
d2i_X509_CINF(X509_CINF **val_out, const unsigned char **der_in,
    long length);

int
i2d_X509_CINF(X509_CINF *val_in, unsigned char **der_out);

X509_VAL *
d2i_X509_VAL(X509_VAL **val_out, const unsigned char **der_in,
    long length);

int
i2d_X509_VAL(X509_VAL *val_in, unsigned char **der_out);

int
i2d_re_X509_tbs(X509 *x, unsigned char **out);

int
i2d_re_X509_CRL_tbs(X509_CRL *crl, unsigned char **pp);

int
i2d_re_X509_REQ_tbs(X509_REQ *req, unsigned char **pp);

💅 DESCRIPTION 💅

These functions decode and encode X.509 certificates and some of their substructures. For details about the semantics, examples, caveats, and bugs, see ASN1_item_d2i(3).

• d2i_X509() and i2d_X509() — decode and encode an ASN.1 Certificate structure defined in RFC 5280 section 4.1.
• d2i_X509_bio(), d2i_X509_fp(), i2d_X509_bio(), and i2d_X509_fp() — similar, except they decode or encode using a BIO or FILE pointer.
• d2i_X509_AUX() — similar to d2i_X509(), but the input is expected to consist of an X.509 certificate followed by auxiliary trust information. This is used by the PEM routines to read TRUSTED CERTIFICATE objects. Warning: this function should not be called on untrusted input.
• i2d_X509_AUX() — similar to i2d_X509(), but the encoded output contains both the certificate and any auxiliary trust information. This is used by the PEM routines to write TRUSTED CERTIFICATE objects. Note that this is a non-standard OpenSSL-specific data format.
• d2i_X509_CERT_AUX() and i2d_X509_CERT_AUX() — decode and encode optional non-standard auxiliary data appended to a certificate, for example friendly alias names and trust data.
• d2i_X509_CINF() and i2d_X509_CINF() — decode and encode an ASN.1 TBSCertificate structure defined in RFC 5280 section 4.1.
• d2i_X509_VAL() and i2d_X509_VAL() — decode and encode an ASN.1 Validity structure defined in RFC 5280 section 4.1.
• i2d_re_X509_tbs() — similar to i2d_X509(), except it encodes only the TBSCertificate portion of the certificate. i2d_re_X509_CRL_tbs() and i2d_re_X509_REQ_tbs() are analogous for CRL and certificate request, respectively. The "re" in i2d_re_X509_tbs() stands for "re-encode", and ensures that a fresh encoding is generated in case the object has been modified after creation.

The encoding of the TBSCertificate portion of a certificate is cached in the X509 structure internally to improve encoding performance and to ensure certificate signatures are verified correctly in some certificates with broken (non-DER) encodings.

If, after modification, the X509 object is re-signed with X509_sign(3), the encoding is automatically renewed. Otherwise, the encoding of the TBSCertificate portion of the X509 can be manually renewed by calling i2d_re_X509_tbs().

🌸 RETURN VALUES 🌸

• d2i_X509(), d2i_X509_bio(), d2i_X509_fp(), and d2i_X509_AUX() — return a valid X509 structure or NULL if an error occurs.
• d2i_X509_CERT_AUX(), d2i_X509_CINF(), and d2i_X509_VAL() — return an X509_CERT_AUX, X509_CINF, or X509_VAL object, respectively, or NULL if an error occurs.
• i2d_X509(), i2d_X509_AUX(), i2d_X509_CERT_AUX(), i2d_X509_CINF(), and i2d_X509_VAL() — return the number of bytes successfully encoded or a negative value if an error occurs.
• i2d_X509_bio() and i2d_X509_fp() — return 1 for success or 0 if an error occurs.
• i2d_re_X509_tbs(), i2d_re_X509_CRL_tbs(), and i2d_re_X509_REQ_tbs() — return the number of bytes successfully encoded or 0 if an error occurs.

For all functions, the error code can be obtained by ERR_get_error(3).

🦋 SEE ALSO 🦋

ASN1_item_d2i(3), X509_CINF_new(3), X509_new(3) — go read the linked docs, bestie, they’re part of the lore.

🌈 STANDARDS 🌈

RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile

👑 HISTORY 👑

d2i_X509(), i2d_X509(), d2i_X509_fp(), i2d_X509_fp(), d2i_X509_CINF(), i2d_X509_CINF(), d2i_X509_VAL(), and i2d_X509_VAL() first appeared in SSLeay 0.5.1. d2i_X509_bio() and i2d_X509_bio() first appeared in SSLeay 0.6.0. These functions have been available since OpenBSD 2.4.

d2i_X509_AUX(), i2d_X509_AUX(), d2i_X509_CERT_AUX(), and i2d_X509_CERT_AUX() first appeared in OpenSSL 0.9.5 and have been available since OpenBSD 2.7.

i2d_re_X509_tbs(), i2d_re_X509_CRL_tbs(), and i2d_re_X509_REQ_tbs() first appeared in OpenSSL 1.1.0 and have been available since OpenBSD 7.1.

Debian • June 8, 2025 • D2I_X509(3) — that’s the footer source/version + date + manual name sign-off, and honestly? iconic. bye bestie 💅✨