ssl_crl_cache_api(3)

💖 ssl_crl_cache_api(3) — Erlang Module Definition ✨

okay bestie, welcome to ssl_crl_cache_api — it's a page from the Erlang manual (section 3, the module-definition girlies 🎀), and it's literally all about hooking your own CRL cache into Erlang's ssl application. let's get into it 💅

---

🌸 NAME 🌸

ssl_crl_cache_api — the API for a TLS CRL (Certificate Revocation List) cache. yes, CRL. Certificate. Revocation. List. we love an acronym 👑

---

✨ DESCRIPTION ✨

okay so here's the vibe: when TLS does its certificate path validation according to RFC 5280, it should also be doing CRL validation checks. that's just what RFC 5280 says, no cap. but for those CRL checks to even happen, the application needs access to CRLs.

now, a database of CRLs? you can set that up in like a million different ways. so this module provides the behavior of the API you need to integrate an arbitrary CRL cache with the erlang ssl application. and plot twist — the application itself uses this module too, to provide a simple default implementation of a CRL cache. iconic behavior honestly 🫶

---

🦋 DATA TYPES 🦋

• crl_cache_ref() :: any() — a reference to the CRL cache. that's it, that's the type 💖
• dist_point() :: #'DistributionPoint'{} — for the description, go look at X509 certificates records. i'm not rewriting the record for you bestie, it's right there 📜
• logger_info() — {logger:level(), Report :: #{description => string(), reason => term()}, logger:metadata()}. this is the info that ssl applications use with Logger(3) ✨

---

💜 CALLBACKS 💜

fresh_crl(DistPoint, CRL)

so fun fresh_crl/2 is gonna be used as the input option update_crl to public_key:pkix_crls_validate/3. that's the whole deal.

and since OTP 22.2 it's possible to return logger info here too — the TLS connection will use it to produce log events. cute, right? 🎀

lookup(DistPoint, CacheRef)

backwards compatibility moment 💀 — this one got replaced by lookup/3.

lookup(Distpoint, Issuer, CacheRef)

okay so this one looks up the CRLs that belong to the distribution point Distributionpoint. and here's the thing — this function gets to choose whether it only looks in the cache or follows distribution point links, depending on how the cache is administrated. your cache, your rules 💅

the Issuer argument holds the issuer name of the certificate that's being checked. normally the returned CRL should be issued by this issuer — except if the cRLIssuer field of DistributionPoint has a value, in which case you should use that value instead. read that part twice, bestie, it matters.

in an earlier version of this API, the lookup function took just two arguments and skipped Issuer. for compatibility that's still supported: if there's no lookup/3 function in the callback module, lookup/2 gets called instead. legacy support staying booked and busy 🫶

and yep — since OTP 22.2 you can return logger info here too, and the TLS connection will use it to produce log events. ⭐

select(IssuerOrDPLocations, CacheRef)

this one selects the CRLs in the cache that are issued by Issuer — unless that value is a list of so called general names (peep X509 certificates records for that), originating from #'DistributionPoint'.cRLissuer, representing different mechanisms to obtain the CRLs. in that case? the cache callback needs to use the appropriate entry to retrieve the CRLs, or return an empty list if it doesn't exist. no CRLs, no problem, return [] 🙈

and yes, same as the others — since OTP 22.2, logger info can be returned here too, and the TLS connection will use it to produce log events. 🌈

---

and that's the whole page, bestie, you ate it 🍓

this little love letter to CRLs comes to you from Ericsson AB, it's from ssl 11.7.5, and it lives at ssl_crl_cache_api(3). go forth and cache your revocation lists responsibly 👑💖✨