.. This file is part of PEPSI. Copyright (C) 2026 GNUnet e.V. PEPSI is free software; you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version. PEPSI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. .. _dependencies: ============ Dependencies ============ Pepsi is built from its own crates and from several hundred packages written by others. Every one of them runs with the privilege of the programs that link it (:ref:`tm-adv-supply`), so each is a decision. This chapter records those decisions. It says why each direct dependency is there, what it brings with it, how much of it someone has audited, and how much machine code it adds to the release. The tables are generated from data kept in the source tree (``docs/dependencies/``): ``measure.py`` measures every package in ``Cargo.lock``, ``clusters.toml`` classifies them and gives the reason for each direct dependency, and ``make dependency-index`` writes the tables. A test fails when ``Cargo.lock`` names a package that the data does not, so a dependency change cannot bypass this chapter. .. _dependencies-method: How the figures are made ======================== **The sets.** Every package in ``Cargo.lock`` belongs to exactly one set, the narrowest that contains it: * *linked*: compiled into the release binaries that ``make build`` produces (on Linux, with the default Nettle backend); * *build*: runs only while building them, as a build script or procedural macro, or as a dependency of one; * *tests*: built only for the test suite; * *optional*: built only with a non-default feature (the OpenSSL backend, LDAP key discovery); * *other OS*: built only for a platform other than Linux; * *lock only*: recorded in ``Cargo.lock`` but never compiled. Cargo records an optional dependency as soon as an enabled feature names it in a weak form, even when nothing enables it (``deny.toml`` lists which feature names which). **Audited.** A package counts as audited when ``cargo vet`` finds a full audit of its version: one of the project's own, or one from the imported public sets (:ref:`sec-supply-chain`). Everything else counts as unaudited. That includes an exempted version, a version only partially covered (an audited delta from an exempted base), and the vendored copies of ``mail-auth``, ``hickory-net`` and the ``taler-rust`` crates, which are reviewed in the tree but carry no ``cargo vet`` audit. A figure *a/u* gives audited/unaudited packages. **Pulls in.** For a direct dependency, the packages reachable from it in the release build, the dependency itself included and build-time packages included. These sets overlap: tokio is in the set of every dependency that runs on it. **Only via it.** The packages that would leave the release build if this one direct dependency went, because nothing else reaches them. Most transitive packages are reached through several direct dependencies, so this figure is much smaller than *pulls in*, and often empty. The last row of each table, *all of the above*, removes all the cluster's direct dependencies at once. **Machine code.** The release binaries are built with line tables and symbols kept (the code is that of ``make build``). Every function symbol is attributed to the package whose source file holds the function, and its size counts for that package. A package's figure is the largest it reaches in any one binary, so code linked into several binaries counts once. *Own KiB* is the direct dependency itself; *Removable KiB* is everything in *only via it*. The figure measures code and nothing else. Data does not count: the language models, the Unicode tables and the compiled-in certificate roots are not machine code, and neither are comments or tests. Three caveats: * The release is optimised with link-time optimisation across all crates. Library code inlined into Pepsi's functions counts for Pepsi, so a dependency's figure is a lower bound of the code it causes. Generic code counts for the crate that defines it, wherever it is instantiated. A dash means that no function of the package survives as its own. * C and assembly linked statically count for the crate that builds them: AWS-LC for ``aws-lc-sys``. Libraries linked dynamically from the system (Nettle, GMP, Kerberos, the C library) do not count. Their code is the distribution's. * Build-time packages have no figure: their code runs on the build host and is not shipped. **Bundles.** Each cluster's second table lists every package in the cluster. A *bundle* printed as one row is a stack Pepsi takes as a whole: a protocol implementation and the crates it is built from, a family published together, or one detector's language models. Leaving out one member is not a choice Pepsi has. Packages where a choice exists are listed one per row. .. _dependencies-overview: Overview ======== .. include:: ../dependencies/generated/summary.rst Three observations follow from the tables: * **Pepsi's own code is the largest part of the binaries.** Third-party packages contribute about a third of the machine code, and the largest of them are the ones that do the heaviest work: AWS-LC (TLS and every public-key operation), Sequoia (OpenPGP), rustls, the ASN.1 codec, HTTP/2, tokio and the PostgreSQL driver. * **Package counts and code size are different measures.** lingua and its 75 language models are the largest group of packages but add little code; the size of ``pepsi-stage-detect-language`` is model data. AWS-LC, by contrast, is two packages and the most machine code of any dependency. * **Few direct dependencies can be removed alone.** taler-common (through its database layer) and mail-auth (through its DNS resolver) each reach the async runtime, the PostgreSQL driver, the DNS and TLS stacks and the HTTP types. Dropping one of Pepsi's own uses of those crates therefore removes nothing. The large *only via it* sets belong to lingua, Sequoia, async-imap and taler-common's own extras. .. _dependencies-audits: The audit landscape =================== ``cargo vet`` audits are supply-chain reviews. An auditor of an imported set read the crate's code, or the diff from an audited version, and certifies that it is fit to deploy: it does not do what it should not. They are not security assessments, and they do not look for subtle bugs. Most of the audited packages are small and widely used (the ``futures`` and ``serde`` families, Unicode helpers, the RustCrypto traits); most of the large protocol implementations are exempted. A handful of packages have had a published security audit or formal verification. None of them covers the version Pepsi builds exactly: .. list-table:: :header-rows: 1 :widths: 22 26 52 * - Packages - Assessment - Relation to the version Pepsi builds * - rustls, rustls-webpki - Cure53 for the CNCF, 2020: four findings, all informational or low - rustls 0.16 and the webpki of that time; Pepsi builds rustls 0.23 and the rustls-webpki fork * - aes-gcm - NCC Group for MobileCoin, 2020: no significant findings - the RustCrypto AEADs before 0.10; focused on timing side channels * - hickory-proto, hickory-resolver - X41 D-Sec for OSTIF, 2024: two medium and two low findings, fixed - two minor versions before the one Pepsi builds * - AWS-LC - formal verification of functional correctness (SAW, Coq, HOL Light, Fiat-Crypto) - a subset of algorithms, key sizes and processors; RSA, the X.509 parsing and the Rust layer are outside it. Pepsi builds the non-FIPS ``aws-lc-sys``, so the FIPS 140-3 validation does not apply * - libbz2-rs-sys - Radically Open Security for NLnet, 2025: one logic bug, fixed - a version before the one Pepsi builds * - OpenSSL (optional backend) - Trail of Bits for OSTIF, 2023: four medium, six low findings - the C library, not the Rust bindings; only in a build with ``crypto-openssl`` No published audit was found for Sequoia, Nettle, tokio, hyper, h2, sqlx, mail-parser, mail-auth, regex, the RustCrypto formats (``der``, ``x509-cert``, ``cms``) or the compression crates. **The residual risk** is stated in :ref:`tm-adv-supply`. An exemption is an honest "unread", and the exempted packages include parsers of hostile input (mail-parser, the DNS and HTTP stacks, the ASN.1 codec). An exemption names a version, so an update is still a recorded decision; the code that is in the lock file now is trusted as downloaded. .. _dependencies-clusters: The clusters ============ .. _dependencies-async: Async runtime and concurrency ----------------------------- Every server, stage worker and network client of Pepsi runs on tokio, and so do the libraries it builds on: sqlx, hyper, hickory and taler-common's database layer. There is no choice of runtime, and none of these packages can leave while any of those libraries stays. ``futures-util`` provides the stream combinators with which the IMAP and key-discovery code consume responses; the ``futures`` facade, which only re-exports it, is not a direct dependency. .. include:: ../dependencies/generated/async.rst .. _dependencies-tls: TLS and certificate verification -------------------------------- All TLS in Pepsi is rustls, a memory-safe implementation, on the AWS-LC cryptographic provider: SMTP in both directions, HTTPS, LMTP, milter, DNS over TLS and HTTPS, and PostgreSQL. No program links OpenSSL for TLS. Every TLS client trusts the system root store (``rustls-native-certs``, which honours ``SSL_CERT_FILE`` and ``SSL_CERT_DIR``). ``rustls-webpki`` is also used directly, to validate client certificates against a configured CA on the submission listeners. ``rustls-platform-verifier`` comes with hickory's HTTPS transport, and ``webpki-roots`` is compiled into sqlx but unused, because Pepsi turns on the system store there too. .. include:: ../dependencies/generated/tls.rst .. _dependencies-awslc: AWS-LC ------ AWS-LC is the one C cryptographic library in the release build, and the largest single contributor of third-party machine code. It is rustls's provider, and Pepsi uses it directly for every public-key operation: RSA, ECDSA and ECDH on P-256 and P-384, and Ed25519 (DKIM and ARC signing, S/MIME, WebAuthn), as well as SHA-1 and HMAC-SHA-1 where a protocol still needs them (TOTP, OCSP, WKD hashes, SCRAM-SHA-1). Keeping these on one library means one implementation to trust, with constant-time code and formal verification for part of it, instead of one per protocol. Building it needs CMake and a C compiler (:ref:`dependencies-build`). .. include:: ../dependencies/generated/awslc.rst .. _dependencies-http: HTTP ---- ``pepsi-httpd`` and ``pepsi-telemetry`` use hyper only to parse HTTP/1.1 requests and write responses. The router, the TLS layer and the socket handling are Pepsi's own. Every HTTP request Pepsi makes goes through hyper's HTTP/1.1 client, in ``pepsi_common::http_client``: one connection per request over Pepsi's rustls configuration, a deadline over the whole request, a size cap enforced while the body arrives, and a redirect policy chosen by each caller. The callers are the MTA-STS policy fetch, the Taler merchant backend, OAuth token refresh, telemetry, mailing-list templates, the Mailman importer, the ``pepsi-setup`` probes, and key discovery, which vets and dials the addresses itself and hands hyper the connection. Pepsi's own DNS client exists because hickory's resolver never asks for the DNSSEC AD bit and does not report it for negative answers; its DNS-over-HTTPS queries go through hickory's DoH client, which brings in ``h2``. Pepsi uses ``h2`` and ``http`` directly only for a test server. hyper, hyper-util and http-body-util come only with Pepsi's own HTTP code; ``http`` comes with hickory too, and ``url`` with sqlx, taler-common and hickory. .. include:: ../dependencies/generated/http.rst .. _dependencies-dns: DNS, IDNA and network addresses ------------------------------- hickory answers every DNS query: MX, TLSA, the TXT records of SPF, DKIM, DMARC and MTA-STS, and the RFC 2136 updates that publish records such as rotated DKIM keys. ``hickory-net`` is vendored with four fixes. A UDP reply that does not decode is skipped instead of failing the lookup. The DNS-over-HTTPS client compares media types without regard to case or parameters, and writes the resolver's port into a request when it is not 443 (both as RFC 9110 asks) and an IPv6 address in brackets (as RFC 3986 asks). Hickory's own DNSSEC validation is not enabled. Pepsi trusts the AD bit of a validating resolver it reaches over loopback or an authenticated channel. The ``__dnssec`` feature stays on for TSIG-signed updates, because an own TSIG implementation would be cryptography written for one purpose. ``idna`` uses ``idna_adapter`` on its default ICU4X stream. Pinning the adapter to the older unicode-rs stream would remove about twenty packages, but ICU4X follows new Unicode versions sooner, and IDNA conversion should accept the domains the current Unicode version allows. .. include:: ../dependencies/generated/dns.rst .. _dependencies-database: PostgreSQL ---------- sqlx is the driver and connection pool of every program with a database, and taler-common's configuration and schema code is built on it. Only the PostgreSQL driver is compiled. The MySQL and SQLite drivers are lock-only entries, recorded because sqlx's ``json`` and ``uuid`` features name them. ``sqlx-core`` is a direct dependency only for the feature that makes PostgreSQL over TLS trust the system root store. ``uuid`` is there because the mailing-list model keys users and members by UUID, as GNU Mailman's REST API expects. .. include:: ../dependencies/generated/database.rst .. _dependencies-taler: GNU Taler --------- taler-common, from the ``taler-rust`` submodule, gives Pepsi the configuration file format, the command-line conventions, the logging set-up and the database helpers of GNU Taler, so the two projects are configured and operated the same way. It brings the ``serde_with`` and ``compact_str`` families its configuration types use. .. include:: ../dependencies/generated/taler.rst .. _dependencies-mail: Mail formats and protocols -------------------------- mail-auth verifies and produces DKIM signatures and ARC sets and evaluates SPF and DMARC. It is vendored with one added constructor (``vendor/PEPSI-VENDORING.md``). Its unconditional dependency on ``similar`` stays: gating it would be one more local change to the vendored copy for a single package. mail-parser decodes untrusted MIME (charsets, transfer encodings, HTML to text) wherever Pepsi needs a message's content rather than its structure. async-imap is the IMAP client of ``pepsi-whitelist import --imap``. An own IMAP client would parse untrusted server responses, which Pepsi does not write for itself when a maintained parser exists. .. include:: ../dependencies/generated/mail.rst .. _dependencies-openpgp: OpenPGP ------- Sequoia implements OpenPGP. Its cryptography comes from a backend chosen at build time: Nettle (the default, a system library linked dynamically) or OpenSSL (``crypto-openssl``, the only backend that decrypts ML-KEM keys, and only with OpenSSL 3.5 or later). Its compression feature is mandatory in practice, because gpg compresses by default, with ZIP, ZLIB or BZip2 at the sender's choice. Most of this cluster's packages are build-time only: the LALRPOP parser generator for Sequoia's grammar, and bindgen for the Nettle bindings. .. include:: ../dependencies/generated/openpgp.rst .. _dependencies-x509: ASN.1, X.509 and CMS -------------------- The RustCrypto format crates decode and encode certificates, CRLs, OCSP responses, PKCS#8 keys and the CMS structures of S/MIME. ``cms`` supplies only type definitions. Pepsi builds and opens CMS messages itself, because AuthEnvelopedData, its default for encryption, is not among the crate's types. ``ldap3`` and its X.509 parser are built only with the optional LDAP key discovery. .. include:: ../dependencies/generated/x509.rst .. _dependencies-crypto: Cryptographic primitives ------------------------ The RustCrypto primitives cover what AWS-LC does not do for Pepsi. That is the symmetric side of S/MIME (AES-CBC, AES key wrap, AES-GCM, and 3DES to decrypt legacy messages), the at-rest wrapping of private keys, the HMACs of SRS, VERP and secure-link, the SASL mechanisms towards a smarthost (CRAM-MD5, SCRAM, and the MD4-based NT hash of NTLM) and Argon2 password hashing. Every RSA operation is AWS-LC's; the ``num-bigint-dig`` big integers run the weak-modulus and batch-GCD screens and one check of WebAuthn's Ed25519 keys, all on public values. Two generations of the hash and MAC traits are present. The format crates and the RustCrypto ciphers pin the older one, and the newer one serves Pepsi's own HMAC and SASL code, so both stay until those crates move. .. include:: ../dependencies/generated/crypto.rst .. _dependencies-text: Text, Unicode and language detection ------------------------------------ lingua detects the language of a message for ``pepsi-stage-detect-language``. All 75 language models are compiled in, because ``LANGUAGES`` may name any of them and language detection is not a sensitive exposure. They make it the cluster with the most packages and a large binary, but little code. ``regex`` matches the patterns of the mailing-list rules against message content. It never backtracks, so a pattern that a list owner pasted in cannot become a denial of service. The rest of the tree matches its patterns in PostgreSQL or with globs. .. include:: ../dependencies/generated/text.rst .. _dependencies-formats: Data formats, encodings and compression --------------------------------------- serde and serde_json carry the per-message JSON state, the admin API and the telemetry reports. ``data-encoding`` is Pepsi's one crate for base64, base32 and hex. The two ``base64`` versions come with sqlx, Sequoia, async-imap and taler-common. Compression is pure Rust: ``miniz_oxide`` behind ``flate2``, shared with Sequoia and mail-auth. The ``toml`` reader serves only ``pepsi-setup``'s importer for Stalwart configurations, and ``lzma-rs`` only unpacks the compromised-keys list. .. include:: ../dependencies/generated/formats.rst .. _dependencies-web: Web console ----------- The console's pages are askama templates, compiled into the binary and type-checked against the structures they render, and escaped by default. Mail bodies use Pepsi's own Mustache implementation instead, because operators edit them per language as installed files. .. include:: ../dependencies/generated/web.rst .. _dependencies-cli: Command line, logging and errors -------------------------------- clap parses every program's command line, and tracing with tracing-subscriber writes the logs, as text or JSON lines. Both are also taler-common's. rustyline gives the ``pepsi-setup`` interview line editing on a terminal. anyhow and thiserror carry errors. .. include:: ../dependencies/generated/cli.rst .. _dependencies-time: Time and dates -------------- jiff handles timestamps, time zones and calendar arithmetic. ``time``, used by hickory and mail-auth, and ``chrono``, used by async-imap, duplicate it. Pepsi cannot remove either while those libraries depend on it. .. include:: ../dependencies/generated/time.rst .. _dependencies-system: Operating system ---------------- ``nix`` provides the system calls that the set-id helpers and servers need: privilege changes, user and group lookup, quotas, terminal modes, ``splice`` and ``fsync``. ``listenfd`` takes the sockets systemd passes on socket activation, which ingress and httpd rely on. ``libgssapi`` binds the system's Kerberos library for GSSAPI authentication towards a smarthost. .. include:: ../dependencies/generated/system.rst .. _dependencies-utility: Data structures and small utilities ----------------------------------- Hash tables, ordered maps and small vectors used throughout the graph. Pepsi names none of them directly. Several crates appear in more than one version because the libraries that use them require different ones. .. include:: ../dependencies/generated/utility.rst .. _dependencies-build: Build-time tooling ------------------ None of this is shipped, but all of it runs on the build host with the builder's rights, so it is part of the supply chain. The procedural-macro toolchain (``syn``, ``quote``, ``proc-macro2``) runs inside the compiler for every derive. The C build tooling compiles AWS-LC (CMake and the ``cc`` crate) and generates the bindings to Nettle and Kerberos (bindgen with libclang). .. include:: ../dependencies/generated/build.rst .. _dependencies-platform: Other platforms and lock-file entries ------------------------------------- Platform shims for Windows, macOS, Android and WebAssembly are never compiled for Linux, and the lock-only packages are never compiled at all. Both are still checked by ``cargo deny`` and recorded by ``cargo vet``. .. include:: ../dependencies/generated/platform.rst