D2I_SSL_SESSION(3)

✨ bestie's guide to d2i_SSL_SESSION + i2d_SSL_SESSION — the D2I_SSL_SESSION(3) page ✨

okay so this is the D2I_SSL_SESSION(3) manual page, and we are going to make it make sense. no cap. 💖

---

🌸 NAME 🌸

d2i_SSL_SESSION, i2d_SSL_SESSION — convert an SSL_SESSION object from/to ASN1 representation.

---

🦋 SYNOPSIS 🦋

the synopsis is giving exactly this, bestie:

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

SSL_SESSION *
d2i_SSL_SESSION(SSL_SESSION **a, const unsigned char **pp, long length);

int
i2d_SSL_SESSION(SSL_SESSION *in, unsigned char **pp);

---

💅 DESCRIPTION 💅

so d2i_SSL_SESSION() takes the external ASN1 representation of an SSL/TLS session — literally binary data sitting at pp with length length — and transforms it into an SSL_SESSION object. iconic behavior. ✨

then i2d_SSL_SESSION() does the reverse glow-up: it transforms the SSL_SESSION object in into the ASN1 representation and stores it into the memory location pointed to by pp. it returns the length of the resulting ASN1 representation. and if pp is the NULL pointer, it only calculates and returns the length. periodt.

the SSL_SESSION object is built from several malloc(3)-ed parts, so it literally cannot be moved, copied, or stored directly. if you want to store session data on disk or into a database, it has to be transformed into a binary ASN1 representation first. that's the whole vibe.

when you use d2i_SSL_SESSION(), the SSL_SESSION object is automatically allocated. the reference count is 1, so you must explicitly remove the session using SSL_SESSION_free(3) — unless the SSL_SESSION object is completely taken over, when being called inside the get_session_cb(), see SSL_CTX_sess_set_get_cb(3).

SSL_SESSION objects keep internal link information about the session cache list when being inserted into one SSL_CTX object's session cache. so one SSL_SESSION object, regardless of its reference count, must therefore only be used with one SSL_CTX object — and the SSL objects created from this SSL_CTX object. no sharing, bestie. that's the rule. 🫶

when using i2d_SSL_SESSION(), the memory location pointed to by pp must be large enough to hold the binary representation of the session. there is no known limit on the size of the created ASN1 representation, so call i2d_SSL_SESSION() first with pp=NULL to obtain the encoded size — then allocate the required amount of memory and call i2d_SSL_SESSION() again. note that this will advance the value contained in *pp, so it is necessary to save a copy of the original allocation. like, the pointer moves, so keep the original one safe. absolutely do not lose the original allocation. 😭

for example:

char    *p, *pp;
int      elen, len;

elen = i2d_SSL_SESSION(sess, NULL);
p = pp = malloc(elen);
if (p != NULL) {
        len = i2d_SSL_SESSION(sess, &pp);
        assert(elen == len);
        assert(p + len == pp);
}

---

🔥 RETURN VALUES 🔥

d2i_SSL_SESSION() returns a pointer to the newly allocated SSL_SESSION object. in case of failure, a NULL pointer is returned and the error message can be retrieved from the error stack. 💀

i2d_SSL_SESSION() returns the size of the ASN1 representation in bytes. when the session is not valid, 0 is returned and no operation is performed. yes, zero. nothing happens. the function is like "not today." 🙈

---

👑 SEE ALSO 👑

• d2i_X509(3)
• ssl(3)
• SSL_CTX_sess_set_get_cb(3)
• SSL_SESSION_free(3)

---

🌈 HISTORY 🌈

d2i_SSL_SESSION() and i2d_SSL_SESSION() first appeared in SSLeay 0.5.2 and have been available since OpenBSD 2.4. vintage but still slaying. ⭐

---

and that's the page, bestie 🎀 — this Debian-flavored manual page is dated June 8, 2025, and its manual tag is D2I_SSL_SESSION(3). mwah 💋✨