29. Testsuite

Pepsi liefert unter tests/ eine End-to-End-Testsuite, die eine Live-Installation über SMTP ausübt und das beobachtbare Verhalten der gesamten Pipeline prüft, statt einer einzelnen Funktion isoliert. Sie ist bewusst eine Black-Box-Suite: Nachrichten werden mit dem gewöhnlichen mail-Befehl oder per rohem SMTP gesendet, und die Prüfungen lesen die Postfächer der Empfänger und die Tabelle pepsi.workqueue.

Diese Suite ergänzt die Unit-Tests im Baum (cargo test --workspace) und ersetzt sie nicht. Die Unit-Tests decken die reine Logik (SRS, MIME-Herabstufung, DSN-Konstruktion, Sprachbewertung, DNS-Klassifizierung, …) ohne Netzwerk ab.

Zwei Dinge liegen dazwischen und werden von Integrationstests abgedeckt, die weder ein Netzwerk noch eine Datenbank benötigen. Die Migrations-Suiten (pepsi-setup/tests/import_*.rs und tests/cli_import.rs) lassen jeden MTA-Importer gegen einen Fixture-/etc-Baum laufen und führen dann das echte pepsi-setup-Binärprogramm Ende zu Ende aus, bis hin zu einem --wizard --import, das eine Konfiguration erzeugen muss, die Pepsis eigene Validierung besteht; siehe das Kapitel zum Erweitern für deren Aufbau. Die Dispatcher-Lebenszyklus-Suite (pepsi-test-stages) benötigt ein PostgreSQL und wird von make check ausgeführt.

Jede Crate bindet ihre Integrationstests in ein Test-Binary ein (tests/main.rs deklariert jede andere Datei unter tests/ als Modul): stages für pepsi-test-stages, crypto, setup, common, httpd und keydisc für die gleichnamigen Crates und workspace für die Dateien im obersten tests/. Ein Binary pro Datei kostete jeweils einen Link von mehreren Sekunden und bis zu 500 MB Plattenplatz. Um die Tests einer Datei auszuführen, filtern Sie nach ihrem Modulnamen, z. B. cargo test -p pepsi-test-stages keystore:: oder cargo test -p pepsi-crypto --test crypto sweep::. Die beiden Telemetrietests von pepsi-common (telemetry_off, telemetry_short_lived) bleiben eigene Binaries, weil jeder die prozessweite Telemetrie-Senke installiert.

29.1. make check: die Schranke ohne entfernte Konten

make check ist der Einstiegspunkt für alles, was keine echten Mail-Konten braucht. Der Reihe nach führt es aus:

  1. make check-telemetry-socket, make check-systemd-units, make check-version und make check-extensions — tests/check-telemetry-socket.sh, tests/check-systemd-units.sh, tests/check-version.sh und tests/check-extensions.sh. Das sind Konsistenzprüfungen über die systemd-Units, die Debian-Paketierung, die Version, die jedes Manifest und debian/changelog tragen, und die beiden Mail-Client-Erweiterungen im Abgleich mit den Header-Feldern, die das Gateway ausgibt; sie benötigen keine Installation und überspringen nie.

  2. cargo test --workspace --exclude pepsi-test-stages --locked — jeden datenbankfreien Test im Baum. (Ein blankes cargo test --workspace würde pepsi-test-stages einschließen und daher eine Datenbank benötigen; bevorzugen Sie make check, das jene Suite an eine Bedingung knüpft, statt an ihr zu scheitern.)

  3. tests/check-lifecycle.sh — die Dispatcher-Lebenszyklus-Suite, nach bestem Bemühen.

  4. tests/maildir-writer-suid.sh, tests/dot-forward-suid.sh und tests/whitelist-suid.sh — die Verträge der setuid-/setgid-Helper, nach bestem Bemühen.

  5. tests/interop-auth.sh — eine DKIM/ARC-Prüfung über Implementierungen hinweg, nach bestem Bemühen. Pepsis eigene Round-Trip-Tests signieren und verifizieren mit derselben mail-auth-Bibliothek und können daher keine Transformation erkennen, die darin durchgängig falsch ist; dieses Skript bewertet von Pepsi signierte Nachrichten (alle vier c=-Kombinationen, dazu eine manipulierte Kopie, die abgelehnt werden muss, dazu ein ARC-Siegel) mit zwei unabhängigen Implementierungen, ganz ohne DNS. dkimpy erhält die öffentlichen Schlüssel über seine dnsfunc (tests/interop-verify.py) und bewertet DKIM und die ARC-Kette; OpenDKIM liest sie im -t-Testmodus des opendkim-Filters aus einer TestPublicKeys-Datei und bewertet DKIM (es hat keinen ARC-Verifizierer; opendkim-testmsg ist nicht verwendbar, weil es nur gegen Live-DNS verifiziert). Jede DKIM-Signature wird bewertet, die RSA- und die Ed25519-Signatur — dkimpy braucht für Letztere PyNaCl. Jeder Verifizierer überspringt (SKIP) seine eigenen Prüfungen, wenn er fehlt, und das Skript überspringt als Ganzes, wenn beide fehlen. Unter Debian: apt install python3-dkim python3-nacl opendkim (der Filter liegt in /usr/sbin; setzen Sie OPENDKIM, wenn er anderswo liegt, und deaktivieren Sie den opendkim-Dienst, den das Paket aktiviert — der Test spricht nie mit ihm).

  6. cargo deny check — Advisories, Verbote, Lizenzen und Quellen. Dieses ist nicht nach bestem Bemühen: Es wird nur übersprungen, wenn cargo-deny wirklich nicht installiert ist, und ein echter Befund lässt das Ziel fehlschlagen. Lesen Sie deny.toml, bevor Sie der Schranke trauen: Seine ignore-Liste ist nicht leer.

  7. cargo vet --locked — der Audit-Nachweis der Abhängigkeiten, supply-chain/: Jede Version einer Drittanbieter-Crate in Cargo.lock muss durch ein Audit (das des Projekts oder eines der importierten öffentlichen Sets, die in imports.lock festgeschrieben sind) oder durch eine Ausnahme abgedeckt sein, sodass eine ohne festgehaltene Entscheidung hinzugefügte oder aktualisierte Crate hier scheitert. --locked lädt nie etwas herunter, die Prüfung läuft also offline. Übersprungen nur, wenn cargo-vet nicht installiert ist (cargo install --locked cargo-vet); ein echter Befund lässt das Ziel scheitern. Was bei einem Fehlschlag zu tun ist, steht in Die Lieferkette.

  8. make docs-linkcheck — jeder interne Querverweis des Handbuchs muss sich in jeder Sprache auflösen (ein Sphinx-dummy-Build mit Warnungen als Fehlern). Wird nur übersprungen, wenn sphinx-build nicht installiert ist.

Die Thunderbird-S/MIME-Interoperabilitätsschranke gehört zu den Workspace-Tests: Sie läuft überall, wo Thunderbird installiert ist, startet ein echtes (kopfloses, von Marionette gesteuertes) Thunderbird und kostet etwa fünfzehn Sekunden. make interop-thunderbird führt sie allein aus. Ihr Befund, dass Thunderbird AuthEnvelopedData nicht lesen kann, ist der Grund, warum Pepsi einen S/MIME-Fähigkeitsdatensatz je Gegenstelle führt und nicht authentifiziertes AES-CBC nur an einen Korrespondenten sendet, der als unfähig verzeichnet ist, AEAD zu lesen (siehe Der S/MIME-Fähigkeitsdatensatz pro Gegenstelle und EFAIL: Formbarkeits-Gadgets in CBC/CFB exfiltrieren entschlüsselte Mail).

29.1.1. Wann ein Test überspringen darf

Ein Test wird nur aus drei Gründen übersprungen: Seine Berechtigungen reichen wirklich nicht aus, eine Abhängigkeit ist wirklich nicht verfügbar, oder es ist die falsche Plattform. Alles andere ist ein Fehlschlag. Ein Werkzeug, das installiert ist und dann die Arbeit verweigert, ist ein Fehlschlag, ebenso eine Vorrichtung, die sich nicht aufbauen lässt: Ein gpg, das einen Schlüssel nicht importiert, hat den Test scheitern lassen, und nur ein nicht installiertes gpg überspringt ihn.

Die Rust-Tests melden ein Überspringen mit pepsi_common::skip_test! oder pepsi_common::require_tool! (pepsi-common/src/test_skip.rs). Die Zeile SKIP <test>: <reason> geht direkt auf die Standardfehlerausgabe, an der Ausgabeerfassung des Test-Harness vorbei, sodass schon ein einfaches cargo test sie neben den SKIP-Zeilen der Shell-Suiten und von make check zeigt.

Ist PEPSI_TEST_NO_SKIP=1 in der Umgebung gesetzt, ist jedes Überspringen ein Fehlschlag: in den Rust-Tests, in tests/check-lifecycle.sh, tests/interop-auth.sh und den drei *-suid.sh-Suiten sowie in den Schranken von make check. Die einzige Ausnahme ist die Zeile „not running as root“ der Suiten, weil make check sie absichtlich unprivilegiert ausführt. Setzen Sie die Variable, wenn alle Abhängigkeiten installiert sind und Sie wissen wollen, dass nichts ausgelassen wurde:

$ PEPSI_TEST_NO_SKIP=1 PEPSI_X509_LIMBO=$PWD/limbo.json cargo test --workspace

Dies sind die Fälle, in denen noch übersprungen werden darf, und was jeweils fehlt:

Grund

Was fehlt

Tests

Abhängigkeit

gpg, openssl, thunderbird, pg_dump oder named(8) ist nicht installiert

die Interoperabilitätstests und jeder Test, der ein Zertifikat erzeugt

Abhängigkeit

PEPSI_X509_LIMBO nennt kein Korpus

limbo::x509_limbo

Abhängigkeit

kein öffentlicher DNS-Resolver antwortet

outside::test::failures_are_seen_live, dessen Logik failures_are_seen auch gegen einen Stub testet

Abhängigkeit

der Host hat keine IPv6-Loopback-Adresse

der letzte Fall von doh_reaches_a_resolver_named_by_its_address

Abhängigkeit

kein PostgreSQL oder keines über TCP

db_credentials, tests/check-lifecycle.sh, tests/whitelist-suid.sh

Abhängigkeit

ein Verifizierer oder ein Werkzeug wie useradd ist nicht installiert; kein cargo und kein Binärprogramm; kein Dateisystem beachtet das setuid-Bit

tests/interop-auth.sh, die *-suid.sh-Suiten

Berechtigung

die Suite läuft nicht als root

die *-suid.sh-Suiten

Berechtigung

der Host gewährt keinen User- und Netzwerk-Namensraum

die Namensraum-Tests von mail_loss_audit

Berechtigung

die Testrolle darf weder CREATE ROLE noch SET ROLE ausführen, oder eine Pepsi-Rolle des Clusters ist ein Superuser

die Grant-Tests (siehe unten) und das gesamte tests/check-lifecycle.sh, wenn die Peer-Rolle ein solcher Superuser ist

Berechtigung

der Test läuft als root, unter einer uid außerhalb des regulären Bereichs von /etc/login.defs oder unter einer uid ohne passwd-Eintrag: Pepsi verzeichnet kein solches Login

lmtp_lifecycle, dot_forward_lifecycle, ingress_smtp, login_assignment, pep_lifecycle

Plattform

es gibt kein Linux-/proc

preflight::tests::preflight_live

Kein Test ist mit #[ignore] markiert. Die Tests mit live im Namen prüfen, was auf jedem Host gilt, und geben den Rest aus, sodass sie mit --nocapture auch dazu dienen, eine Installation anzusehen. batch_bench ist ein gewöhnlicher Test in kleiner Größe; BENCH_N und BENCH_REPS geben ihm die Größe eines Benchmarks.

29.1.2. Kontinuierliche Integration

Mehrere der obigen Schritte überspringen, wenn ein Werkzeug oder eine Datenbank fehlt. Das ist auf dem Rechner eines Entwicklers der richtige Standard und für einen automatisierten Lauf genau falsch, wo ein übersprungenes, grün gemeldetes Gate wie ein bestandenes aussieht. contrib/ci/ enthält Jobs in dem Layout, das der CI-Worker von GNU Taler ausführt (dasselbe, das vendor/taler-rust/contrib/ci/ verwendet): contrib/ci/ci.sh <job> baut das Image aus contrib/ci/Containerfile mit podman und führt darin contrib/ci/jobs/<job>/job.sh mit eingehängtem Quellbaum aus; contrib/ci/run-all-jobs.sh führt jeden Job der Reihe nach aus. Die Jobs sind:

1-gates

Die Gates zur Übersetzungszeit: RUSTFLAGS="-D warnings" cargo build, cargo clippy … -D warnings und cargo fmt --check.

2-check

make check mit jedem Best-Effort-Gate scharf geschaltet. Das Image enthält dkimpy, PyNaCl, OpenDKIM, gpg, OpenSSL, named von BIND, Thunderbird, das Korpus x509-limbo, cargo-deny, cargo-vet und Sphinx. Der Job startet PostgreSQL, setzt PEPSI_TEST_NO_SKIP=1 (siehe Wann ein Test überspringen darf) und schlägt fehl, wenn irgendeine Zeile des Protokolls ein SKIP meldet. make check läuft als unprivilegierter Benutzer auf einer privaten Kopie des Baums, so wie ein Entwickler es ausführt; sonst würde das pepsi-setup run der Lifecycle-Suite zu paketierten Systemkonten wechseln, die der Container nicht hat. Die drei setuid/setgid-Suiten, die root benötigen, werden danach erneut als root ausgeführt; ihr Überspringen mit „not running as root“ im ersten Durchlauf ist das einzige akzeptierte Überspringen. CI_ALLOWED_SKIPS (ein erweiterter regulärer Ausdruck) benennt jedes weitere absichtlich akzeptierte Überspringen.

3-docs

make docs-all: jede Sprache des Handbuchs einschließlich ihres PDFs, also der Build, der an einem nicht deklarierten Unicode-Zeichen scheitert.

4-upgrade

Der Schema-Upgrade-Test, tests/check-upgrade.sh, gegen das vorherige Release-Tag (ohne Wirkung, solange es keines gibt): Er baut pepsi-setup und pepsi-status dieses Releases, installiert dessen Schema und lädt dessen eingefrorene Fixture (tests/upgrade/), führt mit diesem Baum das Upgrade samt Sicherung durch und prüft, dass jede Zeile erhalten bleibt, die Sicherung sich wiederherstellen lässt, der Dispatcher dieses Baums die alte Warteschlange abarbeitet und das alte Release das aktualisierte Schema mit Exit-Status 78 ablehnt. Das Skript läuft auch außerhalb der CI, wenn man ihm die Programme und das SQL-Verzeichnis eines vorherigen Releases gibt.

5-reproducible

Die Prüfung auf reproduzierbare Builds: zwei Klone des getesteten Commits an verschiedenen Pfaden und mit verschiedenen Crate-Cache-Verzeichnissen, jeweils make build und make dist, und der Job schlägt bei jedem Byte fehl, das sich zwischen den beiden Sätzen von Release-Binaries oder den beiden Tarball-Archiven unterscheidet (Reproduzierbare Builds). Er testet HEAD, nicht den Arbeitsbaum, da ein Release ein Commit ist und make dist einen sauberen Checkout verlangt. Das Skript läuft auch außerhalb von podman: CI_REPO nennt den zu klonenden Checkout (Standard /workdir) und CI_WORK das Arbeitsverzeichnis.

6-crypto-openssl

Das OpenPGP-Krypto-Backend, das ein Paketierer ersetzen darf: jedes Programm mit --features crypto-openssl statt Nettle gebaut und die pepsi-crypto-Suite darauf ausgeführt. OpenSSL 3.5 ist das Backend mit den Post-Quanten-Komposit-Algorithmen aus RFC 9980, daher signiert und verschlüsselt die Suite dort zusätzlich eine Nachricht mit ML-DSA-65+Ed25519- und ML-KEM-768+X25519-Schlüsseln über Pepsis eigenen Code (pepsi-crypto/tests/postquantum.rs); unter Nettle prüft dieselbe Datei, dass das Backend weiterhin keinen davon anbietet.

Die Rust-Toolchain im Image ist festgenagelt, statt stable zu folgen, sodass ein neuer clippy-Lint einen unbeteiligten Commit nicht rot färben kann: rust-toolchain.toml nennt die Version, ci.sh übergibt sie an den Image-Build, und check-version hält den eigenen Standardwert des Containerfile gleich; heben Sie sie dort bewusst an. Die Jobs bauen nach target-ci/, damit sie das target/ eines Entwicklers nicht ungültig machen. Führen Sie einen Job lokal von der Wurzel des Baums aus, mit initialisiertem vendor/taler-rust-Submodul, z. B. contrib/ci/ci.sh 2-check.

29.1.3. Die Lebenszyklus-Suite und ihre Datenbank

pepsi-test-stages startet das echte pepsi-dispatch-Binärprogramm gegen ein echtes PostgreSQL und prüft die Zustände der pepsi.workqueue-Datensätze, benötigt also einen erreichbaren Server. Es hat zwei Datenbankmodi, gewählt durch PEPSI_TEST_DATABASE:

nicht gesetzt — der Standardfall und der Entwicklungsablauf

Jeder Test legt seine eigene Wegwerf-Datenbank mit CREATE an und entfernt sie mit DROP, sodass die Suite parallel läuft. Das tut ein blankes cargo test -p pepsi-test-stages; die verbindende Rolle muss CREATE DATABASE / DROP DATABASE ausführen können.

gesetzt (z. B. pepsicheck)

Alle Tests teilen sich diese eine bereits vorhandene Datenbank — nie angelegt, nie gelöscht, ihr Inhalt bleibt erhalten — und setzen beim Aufbau allein pepsi.workqueue zurück. Die Suite muss dann mit --test-threads=1 laufen.

tests/check-lifecycle.sh ist der zweite Modus, automatisiert: Es sucht nach einer pepsicheck-Datenbank (und legt sie an, wenn sie fehlt), setzt das Schema mit pepsi-setup run --reset zurück und führt die Suite seriell dagegen aus, wobei die Datenbank stehen bleibt. Vor dem Zurücksetzen führt es ein blankes run aus, damit eine frisch angelegte Datenbank das _v-Schema hat, aus dem der Lösch-Schritt löscht. Funktionieren weder die Suche noch das Anlegen, überspringt es: Exit 0, was weder ein Bestehen noch ein Fehlschlag ist.

Vier Umgebungsvariablen justieren das alles:

PEPSI_TEST_DATABASE

Wählt den geteilten Modus und benennt die Datenbank. Nicht gesetzt bedeutet Wegwerf-Modus.

PEPSI_TEST_PGHOST

Das Socket-Verzeichnis für die lokale, peer-authentifizierte Verbindung. Standardwert /var/run/postgresql.

PEPSI_TEST_PGUSER

Die Login-/Peer-Rolle, als die verbunden wird. Standardwert $USER.

PEPSI_TEST_DISPATCH_LOG

Auf 1 setzen, um die eigenen Logs des gestarteten Dispatchers zu sehen, die die Suite standardmäßig stummschaltet.

(tests/check-lifecycle.sh liest zusätzlich PEPSI_CHECK_DB, um die von ihm verwaltete geteilte Datenbank umzubenennen, Standardwert pepsicheck.)

Ein einzelner Test oder ein einzelnes Modul ist cargo test -p <crate> <name::filter>, z. B. cargo test -p pepsi-common srs::.

29.1.3.1. Die Tests der Privilegiengrenzen

Acht Testdateien prüfen die Datenbankrechte aus Die Privilegientrennung und Ein Angreifer, der die Datenbank hat gegen einen echten Server — service_role_grants, secure_link_grants, admin_grants, whitelist_grants, setup_task sowie die Rechtefälle in keystore, keydisc_lifecycle und crl_cache. Jede führt das produktive provision_roles aus und wechselt dann per SET ROLEs in jedes Konto, um PostgreSQL zu fragen, was es tun darf. Diese Rechte verhindern, dass die Datenbank ein einziger Speicher ist, den jeder Prozess lesen kann (siehe Mail-Appliances speichern Geheimnisse für alle lesbar oder ungeschützt).

Sie werden übersprungen, wenn irgendeine geprüfte Rolle ein Superuser ist, weil ein Superuser jedes Recht umgeht und sich über die Grenze nichts lernen lässt. Die geprüften Rollen haben feste Namen und gelten für den ganzen Cluster, daher kann ein Test sich nicht selbst zu einem pepsi ohne Superuser-Recht machen. In CI ist keine von ihnen ein Superuser, daher laufen die Tests dort. Auf einem Entwicklungsrechner ist das Überspringen der Normalfall: Das Konto, das die Tests ausführt, ist pepsi, das zugleich die eigene Rolle der Pipeline und meist auch der Superuser des Clusters ist. Um sie auszuführen, lassen Sie die Suite laufen, während pepsi vorübergehend kein Superuser ist, aber in die anderen Rollen wechseln kann — eingerichtet aus einer zweiten Superuser-Sitzung —, und stellen Sie es danach wieder her:

$ psql -U some_superuser -c "ALTER ROLE pepsi NOSUPERUSER CREATEDB CREATEROLE" \
    -c 'GRANT "pepsi-ingress", "pepsi-httpd", "pepsi-telemetry", "pepsi-whitelist",
              "pepsi-crypto", "pepsi-keydisc", "pepsi-config"
        TO pepsi WITH INHERIT FALSE, SET TRUE'
$ cargo test -p pepsi-test-stages service_role_grants:: -- --nocapture
$ psql -U some_superuser \
    -c 'REVOKE "pepsi-ingress", "pepsi-httpd", "pepsi-telemetry", "pepsi-whitelist",
               "pepsi-crypto", "pepsi-keydisc", "pepsi-config" FROM pepsi' \
    -c "ALTER ROLE pepsi SUPERUSER"

INHERIT FALSE ist wichtig: Damit kann pepsi jede Rolle annehmen, ohne ihre Privilegien zu erwerben, sodass die Prüfungen an pepsi selbst aussagekräftig bleiben.

Die End-to-End-Tests der Verwaltungs-API (admin_api) enthalten einen weiteren rollenabhängigen Fall: Der erfolgreiche CONFIG_DB-Schreibvorgang verbindet sich mit options[role]=pepsi-config. Der Test legt die Rolle an, wenn er darf, und wird übersprungen, wenn die Testrolle danach nicht SET ROLE "pepsi-config" ausführen kann. Dasselbe Recht wie oben lässt ihn laufen. Keiner der Ablauftests dort wartet, bis ein Zeitfenster verstrichen ist (Leerlauf- und absoluter Ablauf von Sitzungen, expires_at und disabled von Tokens, der pepsi-httpd prune-Job): Jeder datiert den Zeitstempel zurück, den die Datenbank mit now() vergleicht, und die durchsetzende Abfrage kann das nicht vom Verstreichen der Zeit unterscheiden.

29.2. Auch die Dokumentations-Builds sind Prüfungen

make docs führt sie alle für die Quellsprache aus und ist das eine Dokumentationsziel in der allgemeinen Qualitätsschranke. Es ist ein Alias für make docs-en; make docs-de und make docs-fr bauen dieselben Artefakte aus den übersetzten Katalogen, und make docs-all baut jede Sprache. Vier getrennte Builds stecken darin, und dass einer durchläuft, sagt wenig über die anderen:

make docs-html-en

Sphinx-HTML. Fängt kaputte Querverweise, unbekannte Rollen und fehlerhafte Tabellen ab.

make man

Die Handbuchseiten der Abschnitte 1/5 über docs/rst2man.py. Fängt Titel-Über-/Unterstriche ab, die nicht zur Titellänge passen — ein docutils-Fehler, den der HTML-Build toleriert. Nur in der Quellsprache: Die roff-Seiten werden direkt aus docs/*.rst gerendert und laufen nie durch Sphinx, haben also keinen Übersetzungskatalog.

make info

Das GNU-Info-Handbuch, über den Texinfo-Builder von Sphinx und makeinfo. Nur in der Quellsprache, aus demselben Grund, aus dem install-info ein pepsi.info in einem Info-dir-Index registriert.

make docs-pdf-en, make docs-pdf-de, make docs-pdf-fr

LaTeX, ein PDF pro Sprache, jeweils nach docs/manual/_build/pdf/<lang>/latex/pepsi.pdf geschrieben; make docs-pdf-all baut alle drei (und sonst nichts), make docs-pdf ist das englische. Die deutschen und französischen Builds brauchen die Sprachunterstützung von babel (texlive-lang-german, texlive-lang-french unter Debian). Der am leichtesten vergessene und der am härtesten scheiternde. pdflatex hat für ein beliebiges Unicode-Zeichen keine Glyphe und degradiert nicht, wenn es ihm begegnet: Es bricht mit „Unicode character … not set up for use with LaTeX“ ab und erzeugt überhaupt kein PDF. HTML und man rendern dasselbe Zeichen klaglos, sodass ein neuer Pfeil, ein Rahmenzeichen oder ein griechischer Buchstabe in der Prosa beide besteht und nur diesen Build bricht.

Jedes im Handbuch verwendete Nicht-ASCII-Zeichen muss in latex_elements["preamble"] in docs/manual/conf.py deklariert werden. Der von den ASCII-Art-Pipeline-Diagrammen benutzte Rahmenzeichensatz wird absichtlich auf reines ASCII abgebildet: Diese Diagramme stehen in code-block:: text, sodass die Ersetzung in einer Verbatim-Umgebung expandiert wird, in der kein Mathematikmodus verfügbar ist.

Der zweite Fehlermodus ist eine Tabelle, die nicht auf eine Seite passt. Erst oberhalb einer Zeilenzahlschwelle rendert Sphinx eine list-table in LaTeX‘ longtable, die über Seiten hinweg umbricht und den Kopf wiederholt; darunter wird die Tabelle zu einem tabular, das überhaupt nicht umbrechen kann. Die Heuristik zählt Zeilen, aber was eine Seite überläuft, ist die Höhe, und die beiden gehen bei einer breiten Tabelle mit umbrechenden Zellen weit auseinander: Die 113-zeilige RFC-Übersichtstabelle bricht anstandslos um, während die 17-zeilige, siebenspaltige Vergleichstabelle in Einführung es nicht tut und 397 pt unten über die Seite hinausläuft.

Die Abhilfe besteht darin, es ausdrücklich zu sagen, statt sich auf die Heuristik zu verlassen:

.. list-table::
   :header-rows: 1
   :widths: 20 14 14 14 14 14 14
   :class: longtable

Anders als ein fehlendes Zeichen lässt dies den Build nicht scheitern — es ist eine Overfull \vbox-Warnung und ein PDF mit Inhalt außerhalb der Seite —, durchsuchen Sie die Log-Datei also nach Overfull \vbox und behandeln Sie alles jenseits von ein, zwei Punkt als echten Mangel. Überschüsse unterhalb eines Punktes sind gewöhnliche typografische Rundung.

Ignorieren Sie beim Lesen der Ausgabe die Hyper reference … undefined-Warnungen der ersten Durchläufe — latexmk löst Vorwärtsreferenzen in späteren auf. Der letzte Durchlauf, in docs/manual/_build/pdf/en/latex/pepsi.log, ist derjenige, der sauber sein muss.

Die Übersetzungen werden auf dieselbe Weise geprüft, und die Prüfung ist nicht überflüssig: Derselbe pdflatex-Build scheitert auf dieselbe Weise an einem Zeichen, das ein Übersetzer einführt (ein Guillemet, ein deutsches Anführungszeichen, ein geschütztes Leerzeichen), und kein rein englischer Lauf würde ihm je begegnen. make docs-all ist daher eher eine Freigabeschranke als eine Schranke je Commit; das PDF jeder Sprache landet in docs/manual/_build/pdf/<lang>/latex/pepsi.pdf, und ein deutscher oder französischer Build braucht zusätzlich die installierte babel-Unterstützung dieser Sprache (Debian: texlive-lang-german, texlive-lang-french).

Die Übersetzungen aktuell zu halten besorgt make update-po: Es extrahiert die Nachrichtenvorlagen neu und führt sie in docs/manual/locale/<lang>/LC_MESSAGES zusammen, sodass geänderte Absätze als fuzzy markiert und neue unübersetzt zurückkommen. Nur die .po-Dateien stehen unter Versionskontrolle; Sphinx kompiliert sie zur Build-Zeit.

29.3. Topologie

Die Suite steuert drei echte Mail-Konten auf drei Hosts, beschrieben in einer kleinen INI-Datei, tests/test-accounts.ini. Diese Datei gehört nicht zum Quellbaum: Legen Sie sie aus der Vorlage mit cp tests/test-accounts.ini.sample tests/test-accounts.ini an und ersetzen Sie deren Platzhalter-Konten durch Hosts, die Sie kontrollieren:

Rolle

Konto (ssh-Ziel = E-Mail)

Funktion

ADMIN

root@<mx-host>

Betreibt Pepsi (ingress, dispatch, httpd), PostgreSQL und systemd; außerdem den Smarthost, über den die bediente Domain weiterleitet.

ALICE / BOB

alice@<served> / bob@<served>

Lokale Konten auf der bedienten Domain. Ihr MTA leitet über ADMIN weiter und wird von ihm als vertrauenswürdig eingestuft (MYNETWORKS), sodass ihre Mail lokalen Ursprungs ist (der ausgehende Pfad).

CAROL

test@<other>

Ein Konto auf einem unabhängigen Host. Ihre Mail erreicht ADMINs öffentlichen MX auf Port 25 als fremder MTA — der eingehende Pfad.

DAVE

dave@<mx-host> (optional)

Ein lokaler Unix-Benutzer auf dem ADMIN-Host, der Mail per direkter lokaler Zustellung in sein Maildir empfängt (der Lokale-Zustellung-Pfad; keine Weiterleitung). Anders als die anderen wird er nie direkt per ssh angesprochen — sein Postfach wird als root über die ADMIN-Verbindung gelesen. Nur 07-maildir-test.sh benötigt ihn; 01-deploy.sh richtet die Benutzer dave/dave-broken und die Gruppe pepsi-maildir ein, wenn er gesetzt ist.

Jeder Host wird über passwortloses ssh erreicht; der Harness installiert nichts. ALICE/BOB verwenden eine mbox (/var/mail/<user>); CAROL und DAVE verwenden ein Maildir. Die Postfach-Helper sind formatunabhängig und finden eine Nachricht über ein laufspezifisches Token in beiden Layouts.

Bemerkung

Die beiden anderen Hosts haben eigene Annahmerichtlinien, und die greifen lange vor Pepsi. In der Korrektheits-Suite, die eine Handvoll Nachrichten verschickt, sind sie unsichtbar; in den Benchmarks, die Hunderttausende verschicken, entscheiden sie. Zwei davon besonders:

  • Der MX von CAROL ist die empfangende Seite jedes ausgehenden Tests. Ist er selbst eine Pepsi-Installation, dann sind [pepsi-ingress] CONN_RATE_PER_SECOND und CONN_RATE_BURST dort standardmäßig 1 und 1 — eine neue Verbindung pro Sekunde aus einem bestimmten Quellbereich —, sodass ein Relay, das pro Nachricht eine Verbindung öffnet, mit 421 4.7.0 Too many connections from your address beantwortet wird und zurückstellt. Es geht nichts verloren; gemessen wird aber auch nichts. Erhöhe sie auf diesem Host, bevor du irgendeiner ausgehenden Zahl glaubst.

  • Sind sie erhöht, bleibt die eigene Geschwindigkeit dieses Hosts. Ist der CAROL-Host deutlich kleiner als der getestete MTA, ist jede ausgehende Messung die Zahl dieses Hosts, nicht die von Pepsi; das Kapitel Performance sagt, wie solche Zahlen zu lesen sind.

  • Der MTA von ALICE/BOB ist der Smarthost, an dem der Relay-Schwanz endet, und Postfix‘ message_size_limit liegt standardmäßig bei zehn Millionen Bytes. Deshalb können die größeren Größen des Stage-Durchlaufs den Smarthost-Pfad überhaupt nicht passieren — was der Durchlauf als das eigene 552 des nächsten Hops meldet, anstatt zu raten.

Dieselbe Datei enthält ein Konto, das kein Mailkonto ist, in einem [demobank]-Abschnitt:

[demobank]
URL  = https://bank.demo.taler.net
USER = pepsi-ci
PASS = pepsi-pass

Dies ist ein Bankkonto bei der öffentlichen GNU-Taler-Demo-Bank, deren Währung (KUDOS) Spielgeld ist. 12-wallet-topup-test.sh benötigt es, weil eine manuelle Wallet-Aufladung dem Benutzer nur mitteilt, wohin er Geld überweisen soll — dem Wallet wird nichts gutgeschrieben, bis diese Banküberweisung tatsächlich stattfindet. Der Harness spielt daher die Bank des Benutzers: Er meldet sich an und führt genau die Überweisung aus, um die die per E-Mail versandten Anweisungen bitten; nur so kann der Test prüfen, dass die Abhebung wirklich abgeschlossen wird, und nicht bloß, dass Anweisungen verschickt wurden. Registrieren Sie ein Konto unter https://bank.demo.taler.net/ (ein neues beginnt mit KUDOS:100 und darf bis KUDOS:500 ins Soll gehen — etwa 120 Durchläufe dieses Falls); DEMOBANK_USER, DEMOBANK_PASS und DEMOBANK_URL in der Umgebung haben Vorrang vor der Datei. Kein anderes Skript verwendet es, und fehlt der Abschnitt, wird nur diese eine Gutschriftprüfung übersprungen, als fehlende Abhängigkeit.

Kein Skript nennt einen eigenen Host: Jeder Host, jeder Dienst und jede Einstellung pro Host kommt aus dieser Datei, und tests/test_layout.rs schlägt fehl, wenn ein Skript einen anderen Host nennt oder eine Einstellung liest, die das Muster nicht aufführt. Drei weitere Abschnitte vervollständigen sie:

[taler]
MERCHANT_URL   = https://backend.demo.taler.net/instances/sandbox
MERCHANT_TOKEN = secret-token:sandbox
EXCHANGE_URL   = https://exchange.demo.taler.net/

[deployment]
BEHIND_FRONT = 127.0.0.1:9443

[lmtp-interop]
BINDIR = /usr/local/bin
SQLDIR = /usr/local/share/pepsi/sql

[taler] ist erforderlich und nennt die Händlerinstanz und die Exchange, hier die öffentlichen Demo-Dienste. [deployment] und [lmtp-interop] sind optional und bei den Skripten beschrieben, die sie lesen.

29.4. Die Skripte

tests/lib.sh

Gemeinsame Bibliothek, die von jedem nummerierten Skript gesourct wird. Sie parst die Konten-INI und stellt bereit: die von der gemeinsamen Vorprüfung verwendeten ssh-/Abhängigkeits-/Datenbank-/Dienst-Proben, die Ergebniszähler und die farbige ok/no-Ausgabe, die drei Skip-Helper (siehe Wann ein Fall überspringen darf), die SQL- und Reset-Helper des ADMIN-Hosts, die Postfach-Sende-/Empfangs-Helper, die Taler-Wallet-Helper, die RFC-3464-DSN-Prüfung und — für die erweiterten Skripte — send_smtp (einen Roh-SMTP-Sender, der die ESMTP- und DSN-Parameter setzen kann, die der mail-Befehl nicht kann) und hop_caps (eine EHLO-Fähigkeitsprobe). Sie ist für sich allein nicht ausführbar.

01-deploy.sh

Richtet eine vollständige Pepsi-Installation auf dem ADMIN-Host aus einem sauberen Checkout ein: Dienstbenutzer, PostgreSQL-Rolle/-Datenbank, die Konfigurationsdatei (einschließlich der vollständigen Stage-Pipeline), pepsi-setup (TLS, Schema, DKIM-Schlüssel, DNS-Einträge), den Demo-Zahlungs-Händler und die systemd-Units. Es verifiziert nur die erforderlichen Werkzeuge und bricht mit einer genauen Liste ab, falls welche fehlen — es installiert nie OS-Abhängigkeiten.

02-pipeline-test.sh

Die zentrale Happy-Path-Suite (T1–T6): die Pay-to-Send-Anti-Spam-Stage (unbezahlt → Bounce, bezahlt → zugestellt, zentral aus dem Taler-Wallet des Runners bezahlt), der Sprachfilter (auf die schwarze Liste gesetztes Französisch → Bounce), der ausgehende Signier-/Relay-Pfad (DKIM + ARC beim Empfänger verifiziert), das Lernen der weißen Liste mit SRS-Umschlag-Umschreibung und ein zweiter lokaler Benutzer.

03-dsn-test.sh

RFC-3461-DSN-Erweiterungen und Bounce-Varianten, mit send_smtp: NOTIFY=NEVER unterdrückt die DSN (D1); ENVID/ORCPT werden zurückgespiegelt (D2); RET=HDRS gibt nur Header zurück (D3); NOTIFY=SUCCESS mit ORIGINATE_SUCCESS_DSN liefert eine positive DSN (D4); ein NXDOMAIN-Empfänger routet zum Standard-Bounce (D5); ein unerreichbares Relay erzeugt eine DELAY-DSN (D6); und ein Null-Absender-Bounce an eine SRS0=…-Adresse wird von Ingress zurück zum ursprünglichen Absender rückwärtsdekodiert (D7).

04-settings-test.sh

Die Überschreibungsschicht pro Adresse: ein pepsi-settings-Datensatz ändert das Ergebnis eines Empfängers, aber nicht das eines anderen (S1); ein Konto bearbeitet seine eigenen Überschreibungen per E-Mail und wird bestätigt (S2); eine Bearbeitung an einem Nicht-EDITABLE_STAGES-Abschnitt wird abgelehnt und speichert nichts (S3); und ein DATA mit divergierenden Überschreibungen pro Empfänger wird in separate Datensätze der Warteschlange aufgeteilt (S4).

05-mime-test.sh

8BITMIME-/SMTPUTF8-Behandlung: ein 8-Bit-Nachrichtentext und ein UTF-8-Subject überstehen das Relay unversehrt, wenn der Zustell-Hop die Erweiterung anbietet, werden herabgestuft (Quoted-Printable/Base64, RFC 2047), wenn er es nicht tut, und eine Nicht-ASCII-Empfängeradresse, die der Hop nicht darstellen kann, schlägt dauerhaft fehl. Das Skript probt zuerst das EHLO des Hops und nimmt den passenden Zweig.

06-cli-test.sh

Die Betreiber-CLIs, direkt über ssh ausgeführt: pepsi-config (get/dump/pathsub), pepsi-whitelist (add/list/remove und die dkim/signature-Flags), pepsi-settings (set/get/list/unset/remove), pepsi-tlsrpt (report --dry-run / prune) und der pepsi-httpd-/metrics-Endpunkt.

07-maildir-test.sh

Direkte (lokale Maildir-)Zustellung über die pepsi-stage-relay-to-maildir-Stage, die den setuid-root pepsi-helper-maildir-writer antreibt. Eine Nachricht an den lokalen DAVE-Benutzer landet in dessen Maildir mit den vorangestellten Return-Path/Delivered-To/Received-Headern (L1); eine einzelne Nachricht an einen lokalen und einen entfernten Empfänger wird aufgeteilt, wobei dave lokal zugestellt und alice weitergeleitet wird (L2); und eine Nachricht an ein absichtlich nicht zustellbares Konto (dave-broken, kein nutzbares Home) gibt nach MAX_LIFETIME auf und gibt eine Failure-DSN an den Absender zurück (L3). Weil [stage-local] nach den eingehenden Filtern sitzt (… → anti-spam → local → srs), wird der Absender zuerst auf die weiße Liste gesetzt, um die Pay-to-Send-Schranke zu passieren. Das gesamte Skript scheitert, wenn die Installation keine [stage-local] hat oder die Zielbenutzer fehlen.

11-lmtp-test.sh

Lokale LMTP-Zustellung (pepsi-stage-relay-to-lmtp) gegen ein echtes Dovecot auf dem ADMIN-Host, sodass das Sieve-Skript des Empfängers läuft, während der MDA die Mail ablegt: Eine Nachricht, deren Subject den Sieve-Auslöser trägt, wird per fileinto :create in einen Pepsi-Ordner abgelegt (S1, was beweist, dass Sieve lief, und nicht bloß, dass LMTP zugestellt hat), und eine Nachricht an einen unbekannten Benutzer wird von Dovecot je Empfänger abgelehnt und weiter an NEXT_STAGE geroutet — die Stage baut nie selbst eine DSN (S2). Das Skript installiert und konfiguriert Dovecot selbst, idempotent, und verdrahtet einen Wegwerf-Abschnitt [stage-lmtp] in pepsi.conf; es treibt den worker der Stage direkt an, statt LMTP in die laufende Pipeline zu setzen, sodass es kein anderes Skript stört. Es wird nur übersprungen, wenn sich Dovecot nicht installieren lässt; ein fehlendes Stage-Binärprogramm ist ein Fehlschlag.

12-wallet-topup-test.sh

Die By-E-Mail-Wallet-Self-Service-Hälfte von pepsi-stage-auto-pay (der [stage-wallet]-Abschnitt): Ein lokales Konto füllt sein eigenes benutzerspezifisches GNU-Taler-Wallet auf, indem es pepsi-wallet@<served-domain> einen Subject:-Befehl sendet. Alle drei Methoden werden End-to-End gegen den Demo-Exchange (KUDOS) ausgeübt, mit dem finanzierten lokalen taler-wallet-cli als echtem Gegenüber: withdraw (manuelle Bank-Überweisungsanweisungen, die Überweisung wird anschließend tatsächlich vom [demobank]-Konto aus ausgeführt), pull (eine taler://pay-pull/-URI, die der Harness begleicht) und push (der Harness pusht; der Benutzer akzeptiert die taler://pay-push/-URI). Jeder Fall prüft, dass die Steuernachricht verbraucht wird und das Wallet-Guthaben wächst.

13-auto-pay-test.sh

Die forderungszahlende Hälfte: pepsi-stage-auto-pay begleicht eine zurückkehrende Pay-to-Send-Forderung aus dem eigenen Wallet des Absenders. Die Forderung wird echt erzeugt: Ein lokaler Benutzer sendet an einen mit Bezahlschranke versehenen lokalen Empfänger (DAVE), und die ausgehende Nachricht wird über das Internet weitergeleitet (mit einem echten Pepsi-Origin-Stempel) und läuft in den eingehenden MX dieses Hosts zurück, wo pepsi-stage-anti-spam sie zurückhält und dem Absender eine echte Forderung mailt. Diese Forderung wird durch den Auto-Pay-worker wiedergespielt. Die beiden Fälle verwenden separate Absender (also separate benutzerspezifische Wallets/Bestellungen): BOB``s Wallet bleibt leer, sodass Auto-Pay die Forderung weiterleitet und nichts berechnet (A1); ``ALICE``s Wallet wird **im Voraus vorfinanziert** (sodass die langsame Abhebung außerhalb des kurzen 30-Sekunden-Zahlungsfensters der Bezahlschranke liegt), sodass Auto-Pay die Forderung darin begleicht — die Bestellung kippt auf bezahlt, das Wallet wird belastet, und die zurückgehaltene Nachricht wird freigegeben und an ``DAVE zugestellt (A2).

14-multi-recipient-test.sh

Empfänger-Fan-out — der Fehlerfall, in dem eine an mehrere Personen adressierte Nachricht nur einen Teil von ihnen erreicht. Beide Fälle prüfen die positive Zustellung an jeden vorgesehenen Empfänger. T1 sendet einen Umschlag an zwei entfernte Empfänger und verlangt, dass beide ankommen — ein Relay, das rcpt_to.first() nimmt und dann den Datensatz beendet, gibt nichts weiter. T2 deckt das ~/.forward-Fan-out ab: ein Umschlag, der an einen lokalen Benutzer mit Weiterleitung (DAVE) und an einen zweiten einfachen Empfänger adressiert ist, wobei die weitergeleitete Kopie und der Durchleitungsempfänger jeweils genau einmal ankommen müssen — eine Stage, die den Datenbank-Datensatz serverseitig reduziert, ohne die Nachricht im Speicher zu ändern, lässt einen fusionierten Nachfolger mit der veralteten Empfängerliste arbeiten. T2 benötigt das DAVE-Konto und die ~/.forward-Stage, die 01-deploy.sh einrichtet.

15-debian-deploy-test.sh

Das paketierte Artefakt und der Assistent — der echte Installationsweg des Betreibers, während 01-deploy.sh aus einem Checkout baut und die Konfiguration von Hand schreibt. Es baut das .deb lokal, installiert es auf dem ADMIN-Host (sodass das postinst die Konten, Rollen und dpkg-statoverride-Bits anlegt) und führt dann pepsi-setup --wizard --answers für eine Reihe von Szenarien aus, jeweils gefolgt von pepsi-setup run und echter Probe-Mail durch die Pipeline, die der Assistent erzeugt hat. Es schreibt den installierten Host neu, tut also nichts außer seinen Plan auszugeben, solange PEPSI_DEPLOY_CONFIRM=yes nicht gesetzt ist.

16-whitelist-import-test.sh

Das setuid-pepsi-whitelist und sein Postfach-Importer, gegen die laufende Installation — alles an diesem Programm, was es erst gibt, wenn es installiert ist. Es prüft die Installation selbst (Modus 4755 mit Eigentümer pepsi-whitelist, den Scan-Helper ohne Privilegien-Bits, die auf die Tabelle beschränkte Datenbankrolle, die Hoster-Liste); die Namensraum-Regel, indem es zwei Wegwerf-Konten anlegt und bestätigt, dass eines <login>/… und sonst nichts verwenden darf, dass list die geteilte weiße Liste des Betreibers nicht offenlegt und dass -c abgelehnt wird; den Import selbst, der genau die Empfänger der Mail ergeben muss, die dieser Benutzer gesendet hat, und empfangene Mail ignorieren muss; die Wildcard-Entscheidung, bei der eine stark frequentierte Domain zu einem einzigen *@domain-Datensatz zusammenfällt, während gmail.com mit ebenso vielen Korrespondenten das nicht tut; die Privilegienabgabe, indem ein Helper untergeschoben wird, der seine eigenen Zugangsdaten meldet, und geprüft wird, dass die uid des Aufrufers in allen drei ID-Slots auftaucht; --user, das den eigenen Namensraum eines anderen Kontos befüllt; und schließlich, dass pepsi-stage-check-whitelist den benutzerspezifischen Namen konsultiert, zu dem sein {localpart}-Platzhalter expandiert. Jede dieser Prüfungen scheitert, wenn der Installation die Funktion fehlt.

17-crypto-test.sh

Ende-zu-Ende-Kryptographie: die Teile von pepsi-stage-encrypt, pepsi-stage-decrypt und pepsi-keys, die es erst gibt, wenn die Binärprogramme setuid installiert sind und der Schlüsselspeicher einen Schlüsselverschlüsselungsschlüssel hält. Es prüft die Installation und die Verwahrungsgrenze (4750 pepsi-crypto:pepsi; die Rolle pepsi kann crypto_identity.private_wrapped nicht lesen), die Identitätserzeugung für beide Protokolle und die Interoperabilität statt bloßer Selbstkonsistenz: Pepsis Chiffrat wird von einem unveränderten gpg gelesen, und das Chiffrat von gpg wird von Pepsi gelesen. Es deckt außerdem die fail-open-Urteile für eingehende Mail ab, den gefälschten X-Pepsi-Crypto-Header und dass ENCRYPT = required einen Bounce erzeugt, statt je Klartext zu senden.

18-wkd-test.sh

Das Spiegelbild von 17: wie andere unsere Schlüssel finden. pepsi-httpd bedient das Web Key Directory für jede akzeptierte Domain aus dem Schlüsselspeicher und beachtet dabei das published-Flag jeder Identität — die Richtliniendatei, den direkten und den fortgeschrittenen Pfad, dass sich die zurückgegebenen Bytes in ein unverändertes gpg importieren lassen, dass gpg --locate-external-key sie über echtes DNS und TLS findet und dass eine unveröffentlichte Identität und eine Domain, die wir nicht bedienen, beide 404 ergeben.

19-secure-link-test.sh

Das ferne Ende von [stage-encrypt] ON_NO_KEY = secure-link: Der Klartext wird von der Leitung genommen, dem Empfänger wird ein Link und dem Absender eine PIN gemailt. Es deckt das Routing ab, die PIN, die an den Absender geht, das Offenlegungsverhalten des Portals, die Sperre nach MAX_ATTEMPTS, das erfolgreiche Lesen, die Lesebestätigung und dass die Datenbank allein Chiffrat und keine PIN hält.

20-admin-api-test.sh

Die administrative API über den UNIX-Socket-Listener mit ADMIN = yes, den 01-deploy.sh konfiguriert: dass alle drei Mechanismen authentifizieren (SO_PEERCRED, ein Bearer-Token, eine Passwort-Sitzung), dass ein Token auf seine Geltungsbereiche beschränkt ist und ein fehlender Geltungsbereich ein 403 ergibt, dass jeder nur lesende Endpunkt JSON antwortet und dass GET /api/v1/config kein Geheimnis offenlegt.

21-online-setup-test.sh

Dass die zwei Front-Ends eines Setup-Interviews — das Terminal-pepsi-setup --wizard und das im Browser unter /api/v1/setup — nicht auseinanderdriften: dieselben Fragen, Bezeichner, Arten, dieselbe Reihenfolge, dieselben Standardwerte und Bedingungen; Antworten, die unverändert hin und zurück gehen; dieselben Werte, die von beiden abgelehnt werden; und dieselben Antworten, die zu derselben Konfiguration gerendert werden. Der letzte Fall schreibt die installierte Konfiguration neu (und stellt sie danach wieder her) und ist an PEPSI_DEPLOY_CONFIRM=yes gebunden; die nur lesenden laufen immer.

22-list-api-test.sh

Das Kompatibilitätstor der Mailinglisten und das eine Skript hier, das nicht unseres ist. Es führt die eigene Suite von mailmanclient 3.3.5 (344 Doctest-Anweisungen in using.rst und 36 Testfunktionen) und die mailman_api_tests von Postorius 1.3.13 (30 Dateien, 248 Funktionen) gegen den installierten Server aus, wobei nur die Vorrichtung ausgetauscht ist, die GNU Mailman Core startet — diese zwei Ersatzstücke liegen in contrib/compat/, versioniert neben den Festschreibungen. Davor prüft es die Dinge, deren Scheitern sonst als 250 rote Python-Tracebacks erscheinen würde: dass die API auf dem Loopback-Listener mit LIST_API = yes antwortet und ohne die Zugangsdaten verweigert, dass dieselben Pfade auf dem öffentlichen Listener ein Byte-für-Byte gleiches 404 sind, dass der nur für Tests gedachte Reset-Haken funktioniert, und ein Rauchtest des Ressourcenbaums samt der 400-gegen-404-Asymmetrie auf /config und der Aufteilung dezimal gegen hexadezimal bei member_id zwischen /3.0/ und /3.1/. Eine Suite, die nicht installiert werden kann, lässt den Lauf scheitern, weil ein stillschweigend übersprungenes Tor die andere Art ist, auf die dieser Test lügen kann; nur ein nicht antwortendes PyPI ist ein erklärtes Überspringen. Eine Suite besteht mit N passed und beliebig vielen xfailed: Jeder erwartete Fehlschlag ist ein erklärter Unterschied zu GNU Mailman, von der Vorrichtung als strikt markiert, sodass einer, der zu bestehen beginnt, das Tor scheitern lässt; ein Überspringen, ein Fehler oder ein unerwartetes Bestehen lässt es scheitern. contrib/compat/run-local.sh führt dieselben beiden Suiten gegen einen Build-Baum ohne Installation aus (siehe Die REST-API von GNU Mailman 3).

24-list-post-test.sh … 27-list-archive-test.sh

Die vier Hälften des Mailinglisten-Subsystems über echte Post: eine Listennachricht, die jedes Mitglied mit seiner eigenen Ein-Klick-Abmelde-URI erreicht; -join, -leave und -confirm, die die Abonnementabläufe antreiben; ein Bounce, der einem Mitglied zugeordnet, bewertet und in eine Warnung und dann eine Entfernung verwandelt wird; und das Archiv, das aufnimmt, threadet, durchsucht und löscht, was gesendet wurde.

Skript 24 trägt außerdem die Sammelnachrichtenphase: Nachrichten wachsen an, eine Ausgabe geht in jedem Format an die Mitglieder, die dieses Format verlangt haben, Band und Nummer sind das, was die Regel sagt, und ein Mitglied, das an diesem Morgen die Sammelnachrichten abgeschaltet hat, erhält dennoch die letzte Ausgabe. Es ist eine Phase dieses Skripts und kein neues, weil die Installationssuite schon lang ist.

28-list-web-test.sh

Die öffentlichen Mailinglistenseiten über HTTP: dass jede Route auf einem Listener ohne LISTS = yes ein Byte-für-Byte gleiches 404 ist; dass eine beworbene Liste im Verzeichnis steht und eine nicht beworbene nicht und weiterhin über ihre URL erreichbar ist; dass das Anmeldeformular genau ein anstehendes Token ausgibt, von sich aus niemanden anmeldet, ein gültiges Token wiederverwendet statt ein zweites auszugeben und für eine bekannte und eine unbekannte Adresse gleich antwortet; dass ein Bestätigungs-GET nichts abschließt und nur das POST es tut; dass eine Nachricht unter ihrer HyperKitty-URL und über die Suche zu finden ist, mit ihrem Text maskiert und nicht gerendert; dass ein privates Archiv ein 404 und kein 403 ist; und dass das Ein-Klick-Ziel nach RFC 8058 das Mitglied mit einem einzigen POST entfernt, selbst wenn unsubscription_policy moderate ist, idempotent ist und bei einem manipulierten Token niemanden entfernt.

Die letzte Phase behandelt die Mitgliederebene und die Verwalteroberfläche: ein Konto registrieren und genau ein Bestätigungstoken zugesandt bekommen (eine zweite Registrierung verwendet es wieder statt ein zweites auszugeben), bestätigen und ein Passwort setzen, von der Kommandozeile zum Verwalter gemacht werden, sich anmelden, und dann der Test, auf den es am meisten ankommt – ein Verwalter ändert eine Einstellung im Browser und die REST-API liest denselben Wert zurück, und das ist es, was belegt, dass die zwei Oberflächen einen Datensatz schreiben. Es prüft außerdem, dass ein Fremder, der die Konsole anfordert, dieselbe Antwort erhält wie für eine nicht vorhandene Liste, und dass eine Einstellungssendung ohne CSRF-Token abgewiesen wird.

Neben den nummerierten Skripten deckt tests/whitelist-suid.sh denselben setuid-Vertrag ohne SSH oder eine Installation ab: Als root auf einem beliebigen Host mit lokalem PostgreSQL ausgeführt, legt es eine Wegwerf-Datenbank an, installiert das Binärprogramm setuid in ein suid-beachtendes Verzeichnis und führt dieselben Namensraum-/Privilegienabgabe-Prüfungen aus. make check führt es (und die anderen *-suid.sh-Skripte) nach bestem Bemühen aus — sie überspringen, statt fehlzuschlagen, wenn sie kein root, keine Datenbank oder kein suid-fähiges Dateisystem bekommen können. Als root ist eine Vorrichtung, die sich nicht aufbauen lässt, ein Fehlschlag.

29-list-import-test.sh

Das Migrationswerkzeug. Eine echte config.pck in Protokoll 0 wird importiert, und die Umwandlungen, die keine Kopien sind, werden über die Datenbank geprüft und nicht über den Rückgabewert des Konverters – der Zusammenfall von archive_policy, die DMARC-Vorrangregel, die neunzig Tage Karenzzeit, das abschließende Leerzeichen des subject_prefix, das DisableMime-Bit, das ein Klartext-Sammelnachrichtenmitglied erzeugt, und ein wegen Bounces abgeschaltetes Mitglied, das abgeschaltet ankommt. Der Import endet mit einem Fehlerstatus, weil die Testdaten absichtlich eine Sperre tragen, die niemand übersetzen kann, und ein zweiter Lauf ändert nichts und sagt das.

Die mittlere Phase ist die wertvollste: pepsi-archive export, gefolgt von import in eine zweite Liste, mit Vergleich der Nachrichtenzahl, jeder Message-ID und der Threadzahl. Das prüft die beiden Hälften gegeneinander und nicht gegen unsere Erwartungen, und ein erneuter Import fügt nichts hinzu – die Wiederaufnahme hängt am Inhalt und nicht an einem Zeitstempel.

Die letzte Phase ist die Umstellungssendung: das Histogramm je Domain, ein ratenbegrenzter Lauf und ein zweiter Lauf, der überspringt, was der erste eingeladen hat.

Was es nicht tut, ist ein echtes upstream Mailman 3 aufzusetzen, um über REST zu importieren; das braucht eine Mailman-Installation auf dem Zielrechner. Die Lücke ist im Skript benannt und nicht dem Entdecken überlassen.

30-secretary-test.sh

Confirm-to-Send (pepsi-stage-secretary). Die Installation, die 01-deploy.sh aufbaut, hat keine Secretary in ihrer eingehenden Kette, daher fügt das Skript für seine eigene Laufzeit eine nach check-whitelist ein und stellt die Konfiguration beim Beenden wieder her. Es prüft, dass ein unbekannter Absender zurückgehalten wird und eine Challenge mit Null-Absender erhält (X1); dass eine automatische Antwort auf die Challenge nichts freigibt und niemanden auf die Whitelist setzt (X2); dass eine echte Antwort die zurückgehaltene Nachricht zustellt und den Absender auf die Whitelist setzt (X3), dessen nächste Nachricht dann ohne zweite Challenge durchgeht (X4); dass eine gebouncte Challenge die zurückgehaltene Mail sofort in den Timeout-Pfad schickt (X5); und dass ohne Antwort die zurückgehaltene Mail nach HOLD_TIME gebounct wird, wobei eine verspätete Antwort auf das abgelaufene Cookie nichts bewirkt (X6).

31-lmtp-interop-test.sh

Führt den echten Dispatcher und pepsi-stage-relay-to-lmtp auf dem ADMIN-Host gegen elf LMTP-Server in Containern aus (Dovecot, Cyrus, Stalwart, Apache James, maddy, Citadel, WildDuck, Mailman, aiosmtpd, go-smtp und smtp-sink von Postfix), in einer eigenen Datenbank und Konfiguration, sodass die Live-Instanz unberührt bleibt. Jeder Server erhält einen Basislauf und, über tests/lmtp-fault-proxy.py, verspätete, geteilte, fehlerhafte und abgeschnittene Antworten, ein Einfrieren über das Ende von DATA hinweg und kill -9 mit Neustart, sowohl nach der ersten Antwort als auch zwischen dem Ende von DATA und den Antworten. Was Pepsi meldet, wird damit verglichen, was jedes Postfach enthält, und eine große Nachricht wird Byte für Byte verglichen, sowohl so, wie sie über die Leitung ging, als auch so, wie der Server sie gespeichert hat. Der IMAP-Server von Citadel setzt drei Leerzeilen vor jeden Text, und der von Stalwart lässt das letzte Zeilenende weg; der Vergleich lässt genau das zu. Stalwart antwortet 250, sobald eine Nachricht in seiner Warteschlange liegt, und hat daher nach einem Neustart bis zu eine Minute Zeit, abzulegen, was es bestätigt hat, bevor der Test diese Mail als verloren wertet.

Zwei Server werden wegen ihrer Eigenart anders beurteilt. smtp-sink verwirft Mail und nimmt jede Adresse an, daher erwartet der Test, dass Pepsi einen unbekannten Benutzer als zugestellt meldet und niemanden bouncet, und das Journal des Proxys steht für das Postfach. James läuft auf seinem Image im Arbeitsspeicher, das beim Beenden Mail und Konten vergisst: Der Test legt die Konten neu an, während der Proxy Verbindungen verweigert, und zählt anhand des Journals, was James vor dem Neustart bestätigt hat. Ein langsames Sieve-Programm neben einem vollen Postfach, kill -9 während dieses Programms und MAX_RUNTIME unter DATA_TIMEOUT laufen nur auf Dovecot, weil sie eine von sich aus langsame Zustellung brauchen.

Das Skript wird nur übersprungen, wenn es den ADMIN-Host nicht erreicht oder dort ein Werkzeug fehlt; ein Server, der nicht startet, ist ein Fehlschlag. BINDIR und SQLDIR in [lmtp-interop] wählen einen anderen Build aus, und PEPSI_BINDIR und PEPSI_SQLDIR überschreiben sie für einen Lauf. LMTP_SERVERS und LMTP_ONLY schränken einen Lauf ein.

29.5. Ausführen

# One-time: deploy this checkout onto the MX host (over SSH):
tests/01-deploy.sh tests/test-accounts.ini

# Then, repeatedly, from the test runner:
tests/02-pipeline-test.sh tests/test-accounts.ini
tests/03-dsn-test.sh      tests/test-accounts.ini
tests/04-settings-test.sh tests/test-accounts.ini
tests/05-mime-test.sh     tests/test-accounts.ini
tests/06-cli-test.sh      tests/test-accounts.ini
tests/07-maildir-test.sh  tests/test-accounts.ini   # delivers to the DAVE account
tests/11-lmtp-test.sh     tests/test-accounts.ini   # deploys Dovecot on the MX host
tests/31-lmtp-interop-test.sh tests/test-accounts.ini   # containers on the MX host
tests/12-wallet-topup-test.sh tests/test-accounts.ini   # needs taler-wallet-cli on the MX host
tests/13-auto-pay-test.sh     tests/test-accounts.ini   # needs DAVE + taler-wallet-cli
tests/14-multi-recipient-test.sh tests/test-accounts.ini   # T2 needs DAVE + a ~/.forward stage
tests/16-whitelist-import-test.sh tests/test-accounts.ini   # needs root on the MX host
tests/17-crypto-test.sh   tests/test-accounts.ini   # needs the setuid crypto stages + gpg
tests/18-wkd-test.sh      tests/test-accounts.ini   # needs pepsi-httpd + gpg
tests/19-secure-link-test.sh  tests/test-accounts.ini
tests/20-admin-api-test.sh    tests/test-accounts.ini   # needs the ADMIN = yes listener
tests/22-list-api-test.sh     tests/test-accounts.ini   # needs the LIST_API = yes listener + PyPI
tests/24-list-post-test.sh    tests/test-accounts.ini
tests/25-list-command-test.sh tests/test-accounts.ini
tests/26-list-bounce-test.sh  tests/test-accounts.ini   # needs the DAVE account for the owner notices
tests/27-list-archive-test.sh tests/test-accounts.ini
tests/28-list-web-test.sh     tests/test-accounts.ini   # needs the LISTS = yes listener
tests/29-list-import-test.sh  tests/test-accounts.ini   # the importers and the cutover
tests/30-secretary-test.sh    tests/test-accounts.ini   # splices in a secretary stage

# These two rewrite the deployed host. Without the confirmation 15 only plans
# and 21 leaves out O5, and each reports what did not run as a permission skip:
PEPSI_DEPLOY_CONFIRM=yes tests/15-debian-deploy-test.sh tests/test-accounts.ini
PEPSI_DEPLOY_CONFIRM=yes tests/21-online-setup-test.sh  tests/test-accounts.ini

make integrationtests ACCOUNTS=tests/test-accounts.ini führt den ganzen Satz aus: Das INTEGRATION_SH des Ziels ist tests/[0-9][0-9]-*.sh abzüglich der tests/[0-9][0-9]-*-bench.sh-Skripte (BENCH_SH, die ihr eigenes Ziel make benchmarks haben — siehe Benchmark-Suite), sodass ein Skript aufgenommen wird, weil es existiert, und nicht, weil es irgendwo aufgeführt ist; das gilt auch für jedes Skript, das dieses Kapitel nicht erwähnt. Ein fehlgeschlagenes 01-deploy.sh beendet den Lauf, weil nichts danach etwas aussagen würde; nach jedem anderen fehlgeschlagenen Skript laufen die übrigen weiter, und das Ziel scheitert am Ende. Es endet mit einer Liste der fehlgeschlagenen Skripte und jedes übersprungenen Falls mit seinem Grund. Es hängt von interop-thunderbird ab, sodass die S/MIME-Interoperabilitätsschranke zuerst läuft. ACCOUNTS hat den Standardwert tests/test-accounts.ini.

Läuft auf einem Host der Webserver, der Port 443 auch für andere Websites belegt, setzen Sie BEHIND_FRONT = HOST:PORT in [deployment], das 01-deploy.sh und 15-debian-deploy-test.sh lesen. Der öffentliche HTTPS-Listener verwendet dann diese Adresse, und der Webserver bleibt unverändert in Betrieb. 28-list-web-test.sh spricht den Listener direkt an, weil ein solcher Server vielleicht nur einige Pfade von Pepsi weiterleitet.

Das Ziel setzt PEPSI_DEPLOY_CONFIRM=yes, die einzige Zustimmung der Suite, weil schon das erste Skript den ADMIN-Host umschreibt: Jeder Fall läuft. make integrationtests PEPSI_DEPLOY_CONFIRM=no lässt die beiden zerstörerischen Fälle aus.

Jedes Skript verwaltet sich selbst: Es führt eine Vorprüfung durch (ssh-Erreichbarkeit mit dem echten Fehler bei Misserfolg, erforderliche entfernte Werkzeuge, eine Datenbankprobe und der Zustand der drei Dienste mit dem Journal-Auszug jedes ausgefallenen), stellt eine kurze PAYMENT_DEADLINE und ein zügiges POLL_INTERVAL für schnellen Durchlauf sicher und setzt die weiße Liste/Warteschlange/Einstellungen zurück, von denen es abhängt. Eine fehlende Annahme lässt die Vorprüfung mit einer umsetzbaren Meldung scheitern; eine nicht ankommende Nachricht löst einen Diagnose-Dump aus (die Live-Warteschlange plus das Dispatcher-Journal). Stellgrößen wie PAYMENT_DEADLINE_SECS, DELIVER_TIMEOUT und WITHDRAW_AMOUNT sind Überschreibungen aus der Umgebung. Jedes Skript endet nur dann mit 0, wenn kein Fall fehlschlug. Ein Überspringen lässt ein Skript nicht scheitern, und die letzte Zeile seiner Zusammenfassung führt jedes Überspringen mit seinem Grund auf. Die Zusammenfassung nennt auch jeden Fehlschlag noch einmal. tests/lib.sh hält jedes Ergebnis in einer Datei fest, sodass auch eine Prüfung zählt, die in einer Pipeline oder in $( ) läuft.

29.6. Wann ein Fall überspringen darf

01-deploy.sh richtet alles ein, was die nummerierten Skripte brauchen: jede Stage, Option, jedes Konto und jede Vorrichtung sowie die kleinen Werkzeuge (curl, gpg, dig, das Python-Modul venv) über apt-get. Auf einem Host mit root-Zugriff überspringt ein Skript daher normalerweise nichts. Ein Fall, der nicht laufen kann, sagt warum, und nur drei Gründe zählen. Jeder hat einen eigenen Helper in tests/lib.sh, und die ausgegebene Zeile nennt die Kategorie:

skip_perm

Die Berechtigungen reichen wirklich nicht aus: Das ADMIN-Konto ist nicht root, oder PEPSI_DEPLOY_CONFIRM=yes ist nicht gesetzt für einen Fall, der den eingerichteten Host umschreibt (15 und O5 von 21).

skip_dep

Eine Abhängigkeit ist wirklich nicht verfügbar. Die Fälle der Suite sind:

  • Der Demo-Exchange, die Demo-Bank, das Merchant-Backend oder PyPI antwortet nicht. Ein Wallet-, Zahlungs- oder pip-Schritt, der scheitert, während sein Dienst antwortet, ist ein Fehlschlag. tests/lib.sh trifft diese Entscheidung in no_unless_taler_down und no_unless_merchant_down, 22 in no_unless_pypi_down.

  • der Gutschrift-Teil von withdraw in 12 ohne ein Konto [demobank] (siehe oben).

  • Das taler-wallet-cli des Runners fehlt, ist mit dem Demo-Exchange inkompatibel oder kann dort nichts abheben; taler-wallet-cli ließ sich auf dem ADMIN-Host nicht von deb.taler.net installieren. Alle Zahlungen erfolgen zentral aus dem Wallet des Runners (im Produktivbetrieb würde jeder Absender für seine eigene Nachricht bezahlen).

  • Der DKIM-Selektor ist nicht im DNS veröffentlicht, was der Schritt des DNS-Administrators nach 01-deploy.sh ist: 02 kann dann beim Empfänger kein dkim=pass erwarten.

  • Ein Werkzeug fehlt, und apt-get konnte es nicht installieren (gpg, curl, Dovecot, python3-venv).

  • Im Benchmark 08 ein nächster Hop, der eine Nachrichtengröße ablehnte: die größeren Größen dieses Szenarios. Die Ablehnung selbst wird als Fehlschlag gemeldet.

skip_platform

Dies ist die falsche Plattform für den Test. Kein nummeriertes Skript braucht das heute.

Alles andere ist ein Fehlschlag:

  • Ein Schritt, der von einem früheren fehlgeschlagenen abhängt, meldet not verified als eigenen Fehlschlag, sodass ein ungeprüfter Pfad nie als bestanden erscheint.

  • Eine Stage, Option, ein Konto oder ein Binärprogramm, das 01-deploy.sh bereitstellt, der Host aber nicht hat, bedeutet, dass die Installation defekt ist, nicht, dass der Fall nicht zutrifft.

  • Ein einfaches skip ist ebenfalls ein Fehlschlag, sodass sich ein Überspringen nicht schreiben lässt, ohne einen der drei Gründe zu wählen.

Einige Fälle bringen ihre eigene Vorrichtung mit, damit sie laufen, was auch immer der Host bietet:

  • M3 von 05 braucht einen nächsten Hop ohne SMTPUTF8, und der echte Hop hat es meist. Das Skript startet tests/smtp-fixture-hop.py auf dem Loopback des ADMIN-Hosts, und eine Nachricht mit dem ENVID-Wächterwert des Testrelays erreicht ihn über [pepsi-stage-relay-to-smarthost-mta-nosmtputf8]. M1 und M2 nehmen den Durchleitungs- oder den Downgrade-Zweig, je nachdem, was der echte Hop ankündigt; rfc2231_downgrade_lifecycle von pepsi-test-stages deckt die Downgrades ab, was auch immer dieser Hop bietet, über die echte Smarthost-Stage und einen Mock-Server, der keine der beiden Erweiterungen ankündigt.

  • Die Cutover-Phase von 29 legt drei Konten ohne Passwort in einer reservierten Domain an, sodass immer jemand eine Einladung braucht.

  • 21 schreibt über [pepsi-admin] CONFIG_DB und den privilegierten Applier. Beide sind standardmäßig aus, und 01-deploy.sh schaltet sie ein: Ein Fragment, das nur pepsi-httpd lesen kann, enthält das Passwort von pepsi-config, und pepsi-setup-apply.socket ist die Türglocke des Appliers.

  • 08 richtet Dovecot so ein wie 11 für bench-lmtp. Für bench-milter startet es pepsi-milter-test-server, den 01-deploy.sh baut, es sei denn, BENCH_MILTER_ADDR nennt einen anderen Milter.

DAVE darf in der Konten-Datei fehlen. Die Skripte verwenden dann dave@<ADMIN-Host>, das Konto, das 01-deploy.sh anlegt.

29.7. Die Parser fuzzen

Drei Oberflächen parsen Bytes, die ein Angreifer gewählt hat: der MIME-Durchlauf (pepsi_crypto::classify, der bei jeder eingehenden Nachricht vor jeder Authentifizierung läuft), unser eigener handgeschriebener S/MIME-CMS-Öffner und der OpenPGP-Leser einschließlich seines Pfads für komprimierte Pakete. Daneben stehen der Parser für die eingehende Authentifizierung, die öffentlichen DKIM-Schlüssel, die er aus dem DNS der Absender abruft, die X.509-Pfadvalidierung und die Parser des Mailinglisten-Subsystems für Bounces, Beiträge, mboxes und importierte Mailman-Konfigurationen. Keiner von ihnen darf panicken, abbrechen oder davonlaufen, und diese Zusage wird auf zwei Wegen gehalten. Damit vermeiden wir Parser-Defekte, die feindliche Eingaben in einen Absturz oder Schlimmeres verwandeln können (siehe Speicherfehler in ASN.1-, CMS-, Zertifikats- und OpenPGP-Parsern und Ungültige, abgelaufene oder alte Signaturen als gültig gemeldet).

make fuzz führt jeweils ein libFuzzer-Ziel aus:

make fuzz                                  # FUZZ_TARGET=parse, 300 s
make fuzz FUZZ_TARGET=cms FUZZ_TIME=3600
make fuzz FUZZ_TARGET=pgp FUZZ_TIME=0      # until interrupted

Die zwölf Ziele unter fuzz/fuzz_targets/ sind parse (der Parser für die eingehende Authentifizierung), classify (der MIME-Durchlauf), cms (der CMS-Öffner), pgp (der OpenPGP-Leser), dkimkey (ein DKIM-Schlüsseleintrag und das DER seines p=-Schlüssels, das AWS-LC parst), x509 (Pfadvalidierung, strukturbewusst: siehe unten), bounceparse (die RFC-3464-Extraktion und die heuristischen Bounce-Erkenner), mimebuild (der Parse-Modify-Rebuild-Pfad der Posting-Stage der Mailingliste, der neben der Abwesenheit von Panics auch den Hin-und-Rückweg prüft), pickle21 (der Leser für Mailman-2.1-config.pck, der prüft, dass nie etwas konstruiert wird), mboxsplit (der mbox-Zerleger, den der Archiv-Importer verwendet), dkim_request (eine Anfragezeile an den DKIM-Signierdaemon und die Richtlinienprüfung, die ihre Daten durchlaufen) und webauthn (der WebAuthn-CBOR-Leser und die darauf aufbauenden Registrierungs- und Assertion-Prüfungen). FUZZ_TIME begrenzt einen Lauf in Sekunden (0 heißt: laufen, bis unterbrochen wird), und FUZZ_FLAGS reicht alles Weitere an libFuzzer durch. Die Saat-Korpora liegen in fuzz/corpus/<target>/, das nicht versioniert ist: PEPSI_CRYPTO_WRITE_FUZZ_CORPUS=1 cargo test -p pepsi-crypto --test crypto sweep:: schreibt die Saaten (PEPSI_CRYPTO_WRITE_FUZZ_CORPUS=1 cargo test -p pepsi-common dkim_key_never_panics die von dkimkey), führen Sie es also in einem frischen Checkout einmal vor dem Fuzzing aus; Funde landen in fuzz/artifacts/<target>/.

x509 mutiert keine Bytes. Ein Byte-Mutator macht aus DER selten ein wohlgeformtes Zertifikat, geschweige denn eine Kette, in der eine eingeschränkte CA über einem Blatt steht, das etwas von derselben Form nennt, sodass die Abgleicher hinter nameConstraints nur über feste Pfade erreicht wurden. Dieses Ziel fuzzt stattdessen eine Beschreibung einer Kette (mit der Crate arbitrary): eine Wurzel, eine optionale Zwischen-CA und ein Blatt, echt signiert; erlaubte und ausgeschlossene Teilbäume von rfc822Name (Postfach, Host, .domain), dNSName und directoryName auf der Wurzel und der Zwischen-CA; und Blattnamen jeder Form, einschließlich SmtpUTF8Mailbox nach RFC 9598 und eines DN-emailAddress. Neben der Abwesenheit von Panics prüft es, dass ein Name innerhalb eines ausgeschlossenen Teilbaums nie validiert, beurteilt von einem bewusst einfachen eigenen Orakel.

cargo-fuzz instrumentiert den Rust-Code. Die C-Bibliotheken darunter parsen ebenfalls feindliche Eingaben: AWS-LC jeden DKIM-Schlüssel und jede S/MIME-RSA-Operation, und Nettle (das Backend von sequoia) jeden OpenPGP-Schlüssel und jede OpenPGP-Nachricht. Die Build-Skripte ihrer Crates kompilieren sie, daher baut make fuzz sie ebenfalls mit AddressSanitizer (FUZZ_ASAN_C=yes, der Standard). AWS-LC wird über AWS_LC_SYS_SANITIZER=asan von aws-lc-sys gebaut, mit clang als C-Compiler und fuzz/asan-rustc.sh als RUSTC_WRAPPER (die Proc-Macros binden das instrumentierte AWS-LC ebenfalls ein, daher erhält rustc die ASan-Laufzeit, um sie zu laden). Das braucht clang und cmake; ohne sie wird das Ziel mit einem Hinweis übersprungen (SKIP), und FUZZ_ASAN_C=no fuzzt mit nicht instrumentiertem C-Code. Nettle wird instrumentiert, wenn FUZZ_ASAN_NETTLE=1 gesetzt ist: fuzz/build-nettle-asan.sh lädt das Release der installierten Version herunter, prüft es gegen ein festgeschriebenes SHA-256, baut die statischen Bibliotheken mit -fsanitize=address und ohne Assembler (sodass jede Routine instrumentiertes C ist) und richtet PKG_CONFIG_PATH darauf:

make fuzz FUZZ_TARGET=dkimkey FUZZ_TIME=3600
make fuzz FUZZ_TARGET=pgp FUZZ_ASAN_NETTLE=1

Für eine Kampagne auf vielen Kernen startet fuzz/campaign.sh mehrere Ziele gleichzeitig unter AddressSanitizer, jedes im Fork-Modus von libFuzzer mit seinem eigenen Anteil an den Kernen, und hält pro Ziel ein Korpusverzeichnis, auf dem aufeinanderfolgende Läufe aufbauen:

cd fuzz && for t in parse classify cms pgp dkimkey x509; do
    AWS_LC_SYS_SANITIZER=asan CC=clang CXX=clang++ \
    RUSTC_WRAPPER=$PWD/asan-rustc.sh PKG_CONFIG_PATH=$(./build-nettle-asan.sh) \
    cargo +nightly fuzz build -O --debug-assertions $t; done
fuzz/campaign.sh p1 3600 "parse:24 classify:80 cms:90 pgp:54"

Die erste solche Kampagne — acht Stunden auf 256 Kernen, etwa vier Milliarden Ausführungen — fand keinen Absturz, kein Leck und kein Hängen. Eine kürzere, bei der zusätzlich AWS-LC und Nettle instrumentiert waren (cms, pgp, dkimkey und x509, je fünfzehn Minuten mit drei Workern, etwa 82 Millionen Ausführungen), fand ebenfalls nichts.

fuzz/ ist ein eigener Cargo-Workspace, vom Wurzel-Workspace ausgeschlossen, weil libfuzzer-sys die Nightly-Toolchain und eine Sanitizer-Laufzeit braucht. Die stabilen Qualitätsschranken bauen ihn also nie, und make fuzz ist ein bewusstes, teures Opt-in-Ziel. Ohne cargo-fuzz oder eine Nightly-Toolchain überspringt es mit dem Installationshinweis und endet mit 0, sodass es harmlos ist, es auf einer Maschine mit nur Stable auszuführen.

Die immer aktive Hälfte ist stabil und braucht kein Nightly: pepsi-crypto/tests/sweep.rs ist ein deterministischer Mutationsdurchlauf über dieselben drei Krypto-Oberflächen, Eingabe für Eingabe, und parse_verify_never_panics und dkim_key_never_panics in pepsi-common decken den Authentifizierungsparser und den DKIM-Schlüsselpfad ab. Sie laufen unter einfachem cargo test — also unter make check —, sodass eine Regression, die eine Fuzzing-Sitzung fände, meist schon von der gewöhnlichen Schranke gefangen wird.

29.8. X.509-Pfadvalidierung gegen x509-limbo

Die Konformität des S/MIME-Validierers ist in der gewöhnlichen Suite durch NIST PKITS 4.6 und 4.8–4.13 (pepsi-crypto/tests/pkits.rs) und ein eigenes Korpus zu Namenseinschränkungen festgeschrieben. x509-limbo, die Vektorsuite, an der andere X.509-Implementierungen gemessen werden, braucht eine Datei von vierzig Megabyte, die nicht im Baum liegt. Das CI-Image enthält sie. Anderswo holen Sie das festgeschriebene Release und richten den Test darauf:

curl -LO https://raw.githubusercontent.com/C2SP/x509-limbo/554528a9b0c0d95e071f55de018326f0b65a8364/limbo.json
PEPSI_X509_LIMBO=$PWD/limbo.json cargo test -p pepsi-crypto --test crypto limbo:: -- --nocapture

Ohne PEPSI_X509_LIMBO wird der Test übersprungen. Mit der Variable muss die Datei die festgeschriebene sein (ihr SHA-256 wird geprüft), weil die Liste erwarteter Abweichungen in pepsi-crypto/tests/limbo.rs von dieser Version spricht. Der Test führt die Fälle aus, die sich auf einen S/MIME-Validierer abbilden lassen — den Pfad, Signaturen, Gültigkeit, Basis- und Namenseinschränkungen, die Schlüsselverwendung der CAs, den Richtlinienbaum, CRLs — und lässt weg, was das nicht tut: den erwarteten DNS-Namen oder die IP-Adresse der Gegenstelle bei einem Fall, der scheitern soll (Pepsi bindet einen rfc822Name, nie einen Host), TLS-extendedKeyUsage, ML-DSA, die eigenen Profilregeln der Web-PKI und eine vom Aufrufer gewählte Kettentiefe. Jedes Ergebnis ist das von limbo; eine Abweichung, die nicht auf der kommentierten Abweichungsliste steht, lässt den Test scheitern, ebenso ein gelisteter Fall, der inzwischen übereinstimmt.

29.9. Beschränkungen

Tests dürfen niemals echte Mail an Drittanbieter-MX-Hosts senden: Die Suite verwendet nur die eigenen Domains der Betreiber und reservierte/.invalid-Namen (z. B. leitet der DELAY-Test über einen Empfänger in blackhole.invalid an eine nicht routbare 192.0.2.0/24-TEST-NET-1-Adresse weiter). Die Entwickler-uid kann die privilegierten Ports 25/53 nicht binden, sodass die privilegierten Listener nur auf dem installierten Host ausgeübt werden.