X509_LOOKUP_HASH_DIR(3)

💅 X509_LOOKUP_HASH_DIR(3) — certificate lookup methods, bestie edition 🎀

okay so this is a page from the Library Functions Manual and it's literally all about the three certificate lookup methods, and honestly? it's giving "small page, big lore." let's get into it ✨

---

🌸 NAME 🌸

X509_LOOKUP_hash_dir, X509_LOOKUP_file, X509_LOOKUP_mem — certificate lookup methods 🗂️

---

🦋 SYNOPSIS 🦋

so first off, it's the libcrypto library, and you're gonna want this include:

#include <openssl/x509_vfy.h>

then these three icons:

const X509_LOOKUP_METHOD *
X509_LOOKUP_hash_dir(void);

const X509_LOOKUP_METHOD *
X509_LOOKUP_file(void);

const X509_LOOKUP_METHOD *
X509_LOOKUP_mem(void);

---

👑 DESCRIPTION 👑

okay so X509_LOOKUP_hash_dir(), X509_LOOKUP_file(), and X509_LOOKUP_mem() return pointers to static certificate lookup method objects that are built right into the library, and you use them with X509_STORE. that's the whole vibe fr fr 💖

ngl though, if you're just a normal user of the library, you typically do not need to grab pointers to these method objects yourself. they get used automatically by the X509_STORE_load_locations(3) or SSL_CTX_load_verify_locations(3) functions. no cap, they just show up and do the work. ✨

---

🍓 File Method 🍓

the X509_LOOKUP_file() method loads all the certificates or CRLs sitting in a file into memory at the time the file gets added as a lookup source. all of them. immediately. it's not subtle and that's lowkey its whole thing 💅

the file format is ASCII text which contains concatenated PEM certificates and CRLs.

this method should be used by applications which work with a small set of CAs. small set. keep it cute, keep it contained 🎀

---

🧚 Hashed Directory Method 🧚

X509_LOOKUP_hash_dir is the more advanced icon of the group — it loads certificates and CRLs on demand, and caches them in memory once they are loaded. very "i'll get to it when i get to it" energy, but make it efficient. and as of OpenSSL 1.0.0, it also checks for newer CRLs upon each lookup, so that newer CRLs are used as soon as they appear in the directory. obsessed. 🔥

the directory should contain one certificate or CRL per file in PEM format, with a filename of the form hash.N for a certificate, or hash.rN for a CRL. the hash is the value returned by the X509_NAME_hash(3) function applied to the subject name for certificates or issuer name for CRLs. you can also get that hash via the -hash option of the openssl(1) x509 or crl commands. iykyk 🫶

the N suffix is a sequence number that starts at zero and is incremented consecutively for each certificate or CRL with the same hash value. and listen — gaps in the sequence numbers are not supported. ⚠️ it is assumed that there are no more objects with the same hash beyond the first missing number in the sequence. so like, don't leave a hole in your numbering and expect it to be fine, because it will not be fine. 🙈

sequence numbers make it possible for the directory to contain multiple certificates with the same subject name hash value. for example, it is possible to have in the store several certificates with the same subject, or several CRLs with the same issuer (and, for example, a different validity period). iconic behavior honestly 🌈

when checking for new CRLs, once one CRL for a given hash value is loaded, the hash_dir lookup method checks only for certificates with sequence number greater than that of the already cached CRL. 👑

⚠️ heads up bestie: the hash algorithm used for subject name hashing changed in OpenSSL 1.0.0, and all certificate stores have to be rehashed when moving from OpenSSL 0.9.8 to 1.0.0. not me warning you about a migration 💀

---

💜 Memory Method 💜

the X509_LOOKUP_mem() method supports loading PEM-encoded certificates and revocation lists that are already stored in memory, using the function X509_LOOKUP_add_mem(3). this is particularly useful in processes using chroot(2). like, you can't reach the filesystem? no problem, it's already in memory. slay 🧚‍♀️

---

⭐ RETURN VALUES ⭐

these functions always return a pointer to a static object. that's it. that's the return value. consistent king 👑

---

🌈 SEE ALSO 🌈

• SSL_CTX_load_verify_locations(3)
• X509_LOOKUP_new(3)
• X509_STORE_load_locations(3)
• X509_STORE_new(3)

---

🎀 HISTORY 🎀

X509_LOOKUP_hash_dir() and X509_LOOKUP_file() first appeared in SSLeay 0.8.0 and have been available since OpenBSD 2.4. ancient. legendary. elder emoji energy 🫶

X509_LOOKUP_mem() first appeared in OpenBSD 5.7. the baby of the family 💖

---

and that's the page, bestie!! this little beauty came to you from Debian, dated June 8, 2025 — so go forth, hash your directories, and remember: no gaps in your sequence numbers. periodt. 💅✨🌸