X509_LOOKUP_HASH_DIR(3SSL)

📦
version 4.0.3 · 14 versions
, in ubuntu stonking

💖 X509_LOOKUP_HASH_DIR — the OpenSSL cert-lookup glow-up (3SSL) 💖

okay bestie, sit down, hydrate, because we're talking about default OpenSSL certificate lookup methods and honestly? it's giving ✨ infrastructure ✨. this whole page lives in section 3SSL of the OpenSSL manual, and it's about how OpenSSL finds your certs and CRLs. let's get into it. 🎀

🌸 NAME 🌸

X509_LOOKUP_hash_dir, X509_LOOKUP_file, X509_LOOKUP_store, X509_load_cert_file_ex, X509_load_cert_file, X509_load_crl_file, X509_load_cert_crl_file_ex, X509_load_cert_crl_file — the default OpenSSL certificate lookup methods, aka the girlies who go find your certs for you. 🫶

✨ SYNOPSIS ✨

#include <openssl/x509_vfy.h>

X509_LOOKUP_METHOD *X509_LOOKUP_hash_dir(void);
X509_LOOKUP_METHOD *X509_LOOKUP_file(void);
X509_LOOKUP_METHOD *X509_LOOKUP_store(void);

int X509_load_cert_file_ex(X509_LOOKUP *ctx, const char *file, int type,
                           OSSL_LIB_CTX *libctx, const char *propq);
int X509_load_cert_file(X509_LOOKUP *ctx, const char *file, int type);
int X509_load_crl_file(X509_LOOKUP *ctx, const char *file, int type);
int X509_load_cert_crl_file_ex(X509_LOOKUP *ctx, const char *file, int type,
                               OSSL_LIB_CTX *libctx, const char *propq);
int X509_load_cert_crl_file(X509_LOOKUP *ctx, const char *file, int type);

look at that prototype lineup. iconic behavior, no notes. 💅

🦋 DESCRIPTION 🦋

so X509_LOOKUP_hash_dir, X509_LOOKUP_file, and X509_LOOKUP_store are certificate and CRL lookup methods that you use with X509_STORE, and they're provided by the OpenSSL library itself. built-in. free. slay. 🌈

and here's the thing — most of y'all will literally never need to create instances of these methods by hand. they get created automatically for you by X509_STORE_load_locations(3) or SSL_CTX_load_verify_locations(3). the library handles it. you just vibe. 😌

under the hood, the loading of certificates and CRLs is implemented through these three functions: X509_load_cert_crl_file, X509_load_cert_file, and X509_load_crl_file. they all take a parameter called type, and type can be one of these constants: FILETYPE_PEM, FILETYPE_ASN1, or FILETYPE_DEFAULT. what do they do? they load certs and/or CRLs from the file you specified straight into the in-memory cache of the X509_STORE object that your ctx parameter is associated with. 🫶

X509_load_cert_file and X509_load_crl_file can both handle PEM and DER formats, and which one you get depends on the value of type. here's the tea though: DER format cannot contain more than one certificate or CRL object — meanwhile PEM can hold several concatenated PEM objects, it's greedy like that. so that's why X509_load_cert_crl_file with FILETYPE_ASN1 is equivalent to X509_load_cert_file. 💀

now, the constant FILETYPE_DEFAULT paired with a NULL filename? that makes these functions load the default certificate store file (see X509_STORE_set_default_paths(3)). easy.

these functions return the number of objects loaded from the file, or 0 if something went wrong. 📉

and fun fact: both methods support adding several certificate locations into one X509_STORE. we love a method that shares. 🤝

this page also documents the certificate store formats these methods use, plus the caching policy. so keep reading bestie, we're not done. ⬇️

🍓 File Method 🍓

the X509_LOOKUP_file method loads all the certificates or CRLs present in a file into memory at the exact moment the file is added as a lookup source. no take-backs, no do-overs, it's all going in. 💖

the file format is ASCII text containing concatenated PEM certificates and CRLs. simple as that. 🎀

use this method when your app works with a small set of CAs. if your CA list is huge, this is not the method for you, bestie.

🧚 Hashed Directory Method 🧚

X509_LOOKUP_hash_dir is the more advanced method. instead of grabbing everything upfront, it loads certificates and CRLs on demand, then caches them in memory once they're loaded. ✨ as of OpenSSL 1.0.0, it also checks for newer CRLs on every single lookup, so newer CRLs get picked up as soon as they appear in the directory. obsessed with the diligence honestly. 👑

the directory should contain one certificate or CRL per file, in PEM format, and the filenames must follow this pattern:

  • hash.N for a certificate
  • hash.rN for a CRL

the hash is the value returned by the X509_NAME_hash_ex(3) function, applied to the subject name for certificates, or the issuer name for CRLs. you can also grab the hash via the -hash option of the openssl-x509(1) or openssl-crl(1) commands. iykyk. 💅

the .N or .rN suffix is a sequence number that starts at zero and increments consecutively for each certificate or CRL sharing the same hash value. and listen — gaps in the sequence numbers are not supported. it's assumed there are no more objects with that same hash beyond the first missing number in the sequence. so don't be leaving holes in your numbering, bestie. 🙈

what's the point of sequence numbers, you ask? they let the directory hold multiple certificates with the same subject name hash value. for example, you can have several certificates with the same subject in the store, or several CRLs with the same issuer (say, with different validity periods). it's giving flexibility. 🌸

when it's checking for new CRLs after one CRL for a given hash value is already loaded, the hash_dir lookup method checks only for certificates with a sequence number greater than that of the already cached CRL. efficient. focused. main character energy. ⭐

⚠️ heads up: 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. don't skip this step, it will Not go well. 😭

also, OpenSSL ships a openssl-rehash(1) utility which creates symlinks with hashed names for all files with a .pem suffix in a given directory. so you don't have to do it by hand. the tool ate. 🔥

💜 OSSL_STORE Method 💜

X509_LOOKUP_store is a method that lets you access any store of certificates and CRLs through any loader supported by ossl_store(7). it does this with the help of URIs — and those URIs can be direct references to certificates or CRLs, but they can also point at catalogues of those objects (which behave like directories). cute, right? 🎀

FYI: since OpenSSL 4.0, X509_LOOKUP_store ignores anything in its input besides certificates and CRLs. it's very selective. it's got boundaries. we respect it. 💅

this method overlaps with the "File Method" and the "Hashed Directory Method" because of the 'file:' scheme loader. it does no caching of its own, but it can use a caching ossl_store(7) loader — so whether you get caching at all depends entirely on the loader's capability. no cap. 🦋

🌟 RETURN VALUES 🌟

X509_LOOKUP_hash_dir(), X509_LOOKUP_file(), and X509_LOOKUP_store() always return a valid X509_LOOKUP_METHOD structure. always. they never flake on you. 🫶

X509_load_cert_file(), X509_load_crl_file(), and X509_load_cert_crl_file() return the number of loaded objects, or 0 on error. 📊

💀 SEE ALSO 💀

go read them. expand your mind. 🌈

👑 HISTORY 👑

the functions X509_load_cert_file_ex(), X509_load_cert_crl_file_ex(), and X509_LOOKUP_store() were added in OpenSSL 3.0. the new girls on the block. 💅

Copyright 2015-2021 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 whole page, bestie!! 🎀 that was OpenSSL version 4.0.3, dated 2026-09-29, from the X509_LOOKUP_HASH_DIR(3SSL) manual. go forth and hash your directories correctly. slay, periodt, and rehash responsibly. 💖✨🦋🌸

📦 where this page comes from