FETCH-CRL(8)

💖 FETCH-CRL 💖 — the fetch-crl page from section 8 (System Manager's Manual)

okay bestie, sit down, hydrate, because this is the page about fetch-crl — yes the manual is literally called FETCH-CRL(8), it lives in the System Manager's Manual, and it's about retrieving certificate revocation lists 🎀

---

✨ NAME ✨

fetch-crl — retrieve certificate revocation lists 💅

---

✨ SYNOPSIS ✨

fetch-crl [-c config] [-v[v..]]  [-q] [-h] [--inet6glue] [-l infopath]
[-o outputpath] [-s statepath] [-a agingtolerance] [-T httptimeout]
[-r randomwait] [-p parallelism] [--formats openssl|pem|der|nss] ..
[--define key=value] ..  [--cfgdir dirname]

---

✨ DESCRIPTION ✨

so the fetch-crl utility goes and gets certificate revocation lists (CRLs, iykyk) for a whole set of installed trust anchors, working off crl_url files or IGTF-style info files. then it installs them so they can be used with OpenSSL, NSS, or third-party tools. iconic behaviour honestly 🦋

it works based on a list of trust anchors, and for each one, one or more CRLs should be installed into a CRL store. and for each of those CRLs, you can specify one or more URLs to grab that specific CRL from. there are several supported formats for CRL stores:

• openssl — has a directory in which hash.i files are stored, one CRL per file, and all CRLs for the trust anchors whose subject distinguished name hashes to hash are read and evaluated for each certificate issued by the CAs whose subject name hash matches hash

⚠️ lowkey important: OpenSSL in version 1 changed its subject name hashing algorithm, so for one trust anchor, two hashes could be used depending on which specific OpenSSL version you've got. if OpenSSL version 1 or higher is used by fetch-crl and the default mode is used, each CRL is written out twice, once for each possible hash value. this mode is controlled by the opensslmode = { dual | single } configuration option in the configuration file. not me having to write everything twice 💀

• pem — writes out the CRL in PEM (RFC 1421) format ✨
• der — writes out the CRL in binary under distinguished encoding rules 🔥
• nss — will use the crlutil from the Mozilla NSS tools to add or replace a CRL in the NSS cert8.db database 👑

each CRL can be retrieved from one of several URLs. these URLs are listed by default in the trust anchor meta-data: the .info file or the .crl_url file, as shipped with the trust anchor. in the crl_url file, there's one URL per line; in the .info file, the crl_url attribute is a semi-colon separated list of URLs. these URLs are then tried in order to retrieve a fresh CRL. once data has been successfully retrieved, that data is used as the CRL if it passes verification, signature checking and expiration checks. Http, https, ftp and file URLs are supported. 🫶

🚨 bestie, pay attention to this one: if data for a CRL has been downloaded but this data fails any of the subsequent checks (signature validation, freshness), the CRL data is discarded and NO further URLs are tried for this CRL! that's the whole mood. no second chances.

URLs can be pre-pended or post-pended to the default list via the configuration file. this is how you prefer a local mirror repository over any URLs shipped by the trust anchor provider, without needing to modify the trust anchor metadata. by post-pending a URL, you can add a 'last-resort' download location in case the CA-provided URLs can't be used. the pre- and post-pended URLs are subject to token expansion of the tokens @ALIAS@, @ANCHORNAME@, and @R@, where R is the sequence number of the CRL on a per-trust anchor basis. 💫

retrieved CRLs may be PEM (RFC1421) or DER encoded. they are automatically converted as needed by fetch-crl, using the OpenSSL command-line tool. 🧚

retrieving a CRL without having an accompanying CA root certificate in an OpenSSL-accessible form (like @ALIAS@.0 or @ANCHORNAME@.@R@) will result in verification failures. the CA lookup directory and patterns can be configured via the configuration file. 😭

---

🌸 TOKEN EXPANSION 🌸

in paths and name templates, tokens get expanded so a single pattern can be used for all trust anchors. the nametemplate_*, catemplate, prepend_url, and postpend_url configuration settings are subject to token expansion. ✨

the following tokens are recognised:

• @ALIAS@ — the alias name of the trust anchor as defined in the info file. if there's no info file and the meta-data is retrieved from crl_url files, then the alias is set to the basename (excluding the .crl_url suffix) of the filename of the trust anchor. 💅
• @ANCHORNAME@ — the file name of the trust anchor, without any .info or .url_crl suffix.
• @R@ — the CRL sequence number, counting from 0. note that most trust anchors only have a single CRL, with sequence number "0". 🎀

---

✨ OPTIONS ✨

• -h, --help — show help text. the classic. 🫶
• -l, --infodir metadata-directory — the script will search this directory for files with the suffix '.info' or '.crl_url'. Note: the CRL files to download must be in either PEM or DER format.
• -o, --out outputDirectory — directory where to put the downloaded and processed CRLs. the directory you use as the argument for this option is typically /etc/grid-security/certificates. default: infodir (the meta-data directory). 💖
• -a, --agingtolerance hours — the maximum age of the locally downloaded CRL before download failures trigger actual error messages. this error message suppression mechanism only works if the CRL has been downloaded at least once and either the crl_url files are named after the hash of the CRL issuer name, or a state directory is used to preserve state across invocations. default: 24 hour aging tolerance. ⏰
• -q, --quiet — quiet mode (do not print information messages). silent but deadly 🤫
• -r, --randomwait s — wait up to s seconds before starting the retrieval process(es). keeping it spontaneous ✨
• -p, --parallelism n — do the retrieval for several trust anchors in parallel, with up to n processes doing retrievals. at most n downloads will be active at any one time. multiple CRLs for the same trust anchor are still downloaded sequentially. main character energy but make it multithreaded 🔥
• --inet6glue — load the Net::INET6Glue module to enable IPv6 support in LWP. 🌈
• --define key=value — add definitions to the configuration at runtime. the key=value pair is appended to the main section of the configuration, unless a colon is used in the key: then the part before the colon is the config file section name, and the part after it is the key inside that section. to merely set a valueless option, set it to the null-string "". 💅

---

💜 CONFIGURATION 💜

see http://wiki.nikhef.nl/grid/FetchCRL3 or the included example file for a description of the configuration options. the default location of the configuration file is /etc/fetch-crl.conf. supplementary configuration is read from all files located in /etc/fetch-crl.d/, or the directory designated by the cfgdir directive, whose collated contents are added to the existing configuration data. 🗂️✨

---

🦋 NOTES 🦋

defaults can be set in the fetch-crl system configuration file /etc/fetch-crl.conf. that's the vibe, that's the home base 🏡

---

⭐ SEE ALSO ⭐

openssl(1), http://wiki.nikhef.nl/grid/FetchCRL3 — go read those too, bestie 📚

---

😭 DIAGNOSTICS 😭

exit status is normally 0; if an error occurs, exit status is 1 and diagnostics will be written to standard error. so if you see a 1, something's up 💀

---

👑 LICENSE 👑

licensed under the Apache License, Version 2.0 (the "License"); 🌈

http://www.apache.org/licenses/LICENSE-2.0

---

💀 BUGS 💀

although fetch-crl3 will install multiple CRLs in the CRL stores (called '.r0', '.r1', or labelled appropriately in an NSS store), if the number of CRLs decreases, the left-overs are not automatically removed. so if the number of CRLs for a particular CA goes down from n to n-1, the file '.rn' must be removed manually. yes girl, with your own two hands 🙈

---

and that's the whole page, fr fr — brought to you by the Trust Anchor Utilities, local build, dated however this thing is dated, and forever filed under FETCH-CRL(8). slay, go fetch those revocation lists 💖✨🎀