95.1.3. pepsi-httpd

Pepsi’s web server: well-known endpoints, list pages, portal and console

Section du manuel:

1

95.1.3.1.1. Nom

pepsi-httpd - serveur HTTP/HTTPS pour MTA-STS, le Web Key Directory, l’autoconfiguration du courrier, le module complémentaire Outlook, les pages des listes de diffusion, le portail de lien sécurisé, l’API et la console d’administration, et les métriques.

95.1.3.1.2. Synopsis

pepsi-httpd [GLOBAL-OPTIONS] serve

pepsi-httpd [GLOBAL-OPTIONS] prune

95.1.3.1.3. Description

pepsi-httpd est le serveur HTTP/HTTPS de Pepsi. Il lie un ou plusieurs écouteurs et achemine chaque requête à travers une table de dispatch générique, en mettant en correspondance par méthode HTTP et forme d’URL : le chemin d’une route est une liste de segments, chacun étant un littéral, une capture nommée d’un segment, ou une capture de tout le reste. Les routes sont essayées dans l’ordre d’enregistrement et la première dont la méthode et le chemin correspondent l’emporte. D’autres points de terminaison s’ajoutent comme de simples entrées de table.

Chaque section [pepsi-httpd-listener-<name>] lie une socket — SERVE = tcp (BIND_TO/PORT, port 443 par défaut), unix (UNIXPATH) ou systemd (activation par socket) — avec MODE = plain ou tls. Un écouteur TLS sélectionne son certificat par connexion d’après le nom d’hôte SNI du client : chaque section [pepsi-httpd-cert-<name>] liste un ou plusieurs noms d’hôte SNI avec une paire TLS_CERT/TLS_KEY, et le TLS_CERT/TLS_KEY propre à l’écouteur (le cas échéant) est servi aux connexions qui ne présentent aucun SNI. Un nom SNI qu’aucune section ne liste ne reçoit le certificat de l’écouteur que si ce certificat est valide pour ce nom (ses noms alternatifs de sujet, jokers compris) ; pour tout autre nom, la poignée de main échoue, de sorte que le serveur ne répond jamais à un nom d’hôte pour lequel il n’a pas été configuré avec un certificat destiné à un autre.

Chaque réponse envoyée sur un écouteur TLS porte Strict-Transport-Security: max-age=31536000 (RFC 6797), de sorte qu’un navigateur qui a une fois joint le serveur en HTTPS refuse pendant un an une connexion HTTP simple rétrogradée vers cet hôte. Elle ne nomme ni includeSubDomains ni preload : la politique couvre les noms auxquels répond ce serveur, non d’autres hôtes sous le même domaine. Un écouteur en clair ou sur socket UNIX ne l’envoie jamais (la RFC 6797 l’interdit en HTTP simple) ; derrière un proxy inverse, c’est donc au serveur frontal de définir la politique. Les réponses en texte brut (le 404 d’un chemin inconnu, le 405, les corps d’erreur et d’état courts) portent X-Content-Type-Options: nosniff et Content-Security-Policy: default-src 'none'; frame-ancestors 'none', comme les réponses JSON et HTML.

Lorsqu’un autre serveur web possède déjà les ports 80/443, pepsi-setup(1) configure à la place un déploiement en reverse-proxy. L’écouteur reste activé par socket (SERVE = systemd) mais en HTTP en clair (MODE = plain) ; le basculement se fait plutôt dans l’unité pepsi-httpd.socket : pepsi-setup dépose un drop-in de redéfinition (/etc/systemd/system/pepsi-httpd.socket.d/10-reverse-proxy.conf) qui réinitialise le ListenStream=443 livré et le relie à une socket UNIX à /run/pepsi/httpd.sock (mode 0660, appartenant au groupe propre du serveur frontal — www-data là où ce groupe existe, sinon nginx/apache/httpd), de sorte que systemd passe le fd de cette socket à pepsi-httpd exactement comme il le ferait pour la socket du port 443. Le serveur frontal termine le TLS et lui transfère les requêtes mta-sts.<domain> ; dans ce mode, pepsi-httpd ne détient aucun certificat propre. Supprimer le drop-in et exécuter systemctl daemon-reload rétablit la liaison directe :443, qui exige aussi de rétablir MODE = tls et les certificats ; pepsi-setup run --no-reverse-proxy fait tout cela. Sur un hôte sans systemd, l’écouteur lie lui-même cette socket (SERVE = unix, UNIXPATH, UNIXPATH_MODE = 660, UNIXPATH_GROUP le groupe du serveur frontal). Voir pepsi-setup(1) et --no-reverse-proxy.

95.1.3.1.4. Points de terminaison

GET /.well-known/mta-sts.txt

Renvoie la politique MTA-STS (RFC 8461), construite à partir des options MTA_STS_* de [pepsi] et du HOSTNAME de [pepsi-ingress] (le mx). La politique n’est servie que lorsque le Host de la requête est mta-sts.<domain> pour un domaine de ACCEPTED_DOMAINS ; tout autre hôte (ou MTA_STS_MODE = none) donne 404. La servir ici évite d’héberger le fichier de politique à la main ; pepsi-setup(1) imprime l’enregistrement TXT _mta-sts à publier dans le DNS.

GET /mail/config-v1.1.xml

GET /.well-known/autoconfig/mail/config-v1.1.xml

Renvoie le document d”autoconfiguration de compte de courrier (draft-ietf-mailmaint-autoconfig) : le XML qu’un client de messagerie récupère, ne connaissant que l’adresse de l’utilisateur, pour découvrir quels serveurs employer, sur quels ports, sous quelle sécurité de transport et avec quelle authentification.

Ce sont les deux premiers échelons de la chaîne de repli que définit le brouillon, et le Host choisit entre eux : le premier est servi lorsque le Host de la requête est autoconfig.<domain> (l’échelon obligatoire, et celui que les clients essaient en premier), le second lorsque c’est <domain> lui-même. Dans les deux cas, DOMAIN doit figurer dans ACCEPTED_DOMAINS ; tout autre hôte donne 404. Le paramètre facultatif ?emailaddress= du brouillon est accepté et ignoré — le document nomme %EMAILADDRESS%, l’espace réservé que le client substitue, de sorte qu’aucun texte contrôlé par la requête n’est jamais interpolé dans la réponse.

La réponse est text/xml; charset=utf-8, cachable une heure, et — comme l’exige le brouillon — publique : elle ne porte aucune authentification, car un client doit la lire avant de pouvoir savoir comment s’authentifier.

Le document est construit depuis [pepsi-autoconfig], et le point de terminaison répond 404 tant que cette section ne nomme pas au moins un serveur entrant (IMAP_HOST ou POP3_HOST). Le serveur sortant est dérivé du [pepsi-ingress-listener-*] marqué SUBMISSION = yes, sauf si SMTP_HOST le redéfinit ; un serveur dérivé n’est jamais en clair, car l’ingress refuse un écouteur de soumission TCP en clair. Un IMAP_SOCKET, POP3_SOCKET ou SMTP_SOCKET explicite valant plain n’est publié que lorsque la même section indique aussi ALLOW_PLAIN_AUTOCONFIG = yes : sans cette reconnaissance, pepsi-httpd refuse de démarrer, et validate de pepsi-setup(1) refuse la configuration, chacun avec un message nommant l’option, le serveur et son port, de sorte qu’un plain glissé là par erreur ne puisse jamais atteindre un client. Pepsi ne peut pas distinguer un réseau fermé, où un serveur de boîtes aux lettres en clair peut être exactement ce qui est voulu, d’une faute de frappe ; la reconnaissance est la façon dont l’opérateur le lui dit. Un serveur en clair reconnu est publié comme demandé, avec un avertissement journalisé au démarrage pour chacun : chaque client qui se configure à partir du document enverra alors son mot de passe et son courrier non chiffrés. La publication exige un enregistrement DNS autoconfig.<domain> et un certificat qui le couvre ; voir pepsi.conf(5).

GET /.well-known/openpgpkey/hu/HASH

GET /.well-known/openpgpkey/policy

GET /.well-known/openpgpkey/DOMAIN/hu/HASH

GET /.well-known/openpgpkey/DOMAIN/policy

Le Web Key Directory (draft-koch-openpgp-webkey-service), dans sa forme directe (servie sous le domaine lui-même) comme dans sa forme avancée (servie sous openpgpkey.<domain>, avec le domaine répété dans le chemin). HASH est le SHA-1 en z-base-32 de la partie locale mise en minuscules, stockée et indexée à côté du domaine, de sorte qu’une requête coûte une consultation indexée.

Une clé n’est renvoyée que pour un domaine figurant dans ACCEPTED_DOMAINS et seulement depuis une identité published, active et OpenPGP. La réponse est la clé publique transférable binaire — non blindée — avec Content-Type: application/octet-stream et Access-Control-Allow-Origin: * comme l’exige la spécification. Un condensat inconnu donne 404 avec un corps vide. La clé est servie sans certifications de tiers (seules les propres signatures de son détenteur, et la révocation d’un révocateur désigné, sont conservées), y compris lorsque l’identité stockée a été importée en en portant.

Les clés que porte une réponse suivent la face publique de l’adresse (voir pepsi-keys(1)). Dès que l’utilisateur a enregistré une clé MUA, chaque clé MUA active de l’adresse est servie, les plus récentes d’abord et au plus huit – le même ensemble, le même ordre et le même plafond que ceux pour lesquels scellent pepsi-stage-encrypt(1) et pepsi-stage-reencrypt(1), de sorte qu’un correspondant qui a récupéré la clé dans l’annuaire et un expéditeur local s’accordent sur les clés avec lesquelles un message doit s’ouvrir, et que le jeton de sauvegarde d’un utilisateur ouvre le courrier de l’un comme de l’autre. La clé MTA n’est jamais servie à côté d’une clé MUA. Sans clé MUA, les clés MTA actives sont servies, au plus trois, afin que pendant un renouvellement la nouvelle clé et celle vers laquelle les correspondants chiffrent encore puissent toutes deux être trouvées. Les certificats sont concaténés, comme le permet la spécification ; un client qui ne prend que le premier reçoit la clé la plus récente.

Le fichier policy est un 200 au corps de longueur nulle. Il ne porte aucun indicateur, mais il doit exister : GnuPG interprète son absence comme « ce domaine n’exploite aucun Web Key Directory » et abandonne avant de demander une clé.

Le paramètre ?l=<local-part> est lu et ignoré. L’honorer transformerait le point de terminaison en une consultation par adresse fournie par l’appelant plutôt que par un condensat que l’appelant devait déjà connaître.

Le point de terminaison ne sert que les identités publiées propres à ce déploiement (crypto_identity). Il ne sert jamais une clé de correspondant mise en cache (peer_key) : ce matériel n’a jamais été vérifié par nous et n’est pas à nous pour être publié sous notre propre nom. Il n’existe aucune option pour changer cela.

Une clé stockée dont la moitié publique n’est pas la clé que nomme son empreinte consignée est retenue (404 lorsqu’elle était la seule) et journalisée au niveau error : l’empreinte est ce à quoi est liée la moitié privée enveloppée, de sorte qu’une telle ligne a été écrite par autre chose que la gestion des clés de Pepsi.

Il n’y a délibérément ici aucune limitation de débit ni aucune mise en forme uniforme des 404. Un Web Key Directory est par construction un oracle public, le condensat ne couvre que la partie locale (il répond donc à des devinettes plutôt qu’il n’énumère), et les adresses figurent à l’extérieur de chaque message que le domaine envoie. Voir pepsi-keys(1) et le chapitre de gestion des clés du manuel.

Pour la forme avancée, openpgpkey.<domain> doit se résoudre vers cet hôte et le certificat servi doit couvrir ce nom ; c’est un nom SNI sur le même écouteur HTTPS, non un second écouteur. pepsi-setup(1) l’ajoute à la demande certbot et signale tout nom qui ne se résout pas.

GET /.well-known/pepsi-dkim-retired/DOMAIN/SELECTOR.pem

A retired DKIM private key, published. With [pepsi-dkim] PUBLISH_RETIRED_KEYS the signing daemon pepsi-dkim(1) does not delete a key that it retires but writes it to PUBLIC_DIR/retired/DOMAIN/SELECTOR.pem; once anybody can make a signature with the key, an old signature proves nothing about who made it. This endpoint serves those files on every listener, as application/x-pem-file with Access-Control-Allow-Origin: *. It answers 404 when the option is off, for a name that the daemon could not have written (lower-case domain names and selectors only, so no path climbs out of the directory), and for a file that is missing, a symbolic link, not a regular file or larger than 64 KiB.

GET /addin/manifest.xml

GET /addin/taskpane.html

GET /addin/readpane.html

GET /addin/pepsi-crypto.js

GET /addin/icon-<size>.png

Le module complémentaire Outlook : un manifeste, deux volets de tâches d’une page, le script qu’ils partagent avec l’extension Thunderbird et les icônes (16, 32, 64, 80 et 128 pixels). Le volet de composition (taskpane.html) permet à un utilisateur d’un système de courrier situé derrière cette passerelle de demander qu’un message soit signé ou chiffré : il pose X-Pepsi-Sign / X-Pepsi-Encrypt sur le message en cours de composition, et pepsi-stage-encrypt(1) les lit et les retire avant que le message n’aille sur le fil. Le volet de lecture (readpane.html) montre les champs X-Pepsi-Crypto et X-Pepsi-Warning d’un message, tels que pepsi-stage-decrypt(1) et pepsi-ingress(1) les ont écrits, dans le volet de tâches d’Outlook plutôt que dans la zone du message ; il lit les en-têtes à l’intérieur d’Outlook et n’envoie rien à ce serveur. Chaque ressource est compilée dans le binaire depuis contrib/addin/.

Chacune de ces routes donne 404 à moins que [pepsi-httpd] ADDIN ne soit défini. Le script et les icônes sont servis tels quels (Cache-Control: max-age=86400). Dans le manifeste et les deux pages, deux espaces réservés sont substitués à chaque requête : l’origine publique https:// de cette passerelle, et un identifiant de manifeste dérivé de cette origine. L’origine provient de ADDIN_URL, sinon du Host de la requête. Son schéma est toujours https, car Outlook refuse de charger les ressources d’un module complémentaire en HTTP simple, et une origine http:// configurée est refusée au démarrage, sauf si son hôte est en boucle locale, ce qui est autorisé pour les essais locaux. L’identifiant est stable pour un déploiement et distinct entre déploiements, de sorte que deux passerelles chargées latéralement dans une même organisation Exchange n’entrent pas en collision. Un Host contenant autre chose que ce qu’un nom d’hôte et un port peuvent contenir est refusé par 400 plutôt qu’échappé.

La distribution se fait par chargement latéral : l’administrateur Exchange pointe « Applications intégrées » vers l’URL du manifeste. Voir les chapitres « Microsoft Exchange comme passerelle » et « Extensions des clients de messagerie » du manuel.

GET /metrics

Statistiques du pipeline au format d’exposition texte Prometheus. Les jauges en direct (pepsi_stage_active_messages, pepsi_pause_backlog) sont lues directement depuis la file ; les compteurs (pepsi_stage_timeouts_total, pepsi_stage_crashes_total, pepsi_stage_messages_total, pepsi_stage_duration_seconds_total et les globaux pepsi_stages_executed_total / pepsi_messages_processed_total) proviennent des tables de statistiques que pepsi-dispatch(1) met à jour. pepsi_quarantine_held_messages (par étape) compte les messages que retient une étape de quarantaine, et pepsi_greylist_decisions_24h (par issue et par motif) les décisions du greylisting des dernières 24 heures, à partir des compteurs horaires de pepsi-greylist(1) ; c’est une jauge, puisque les anciens compteurs sont élagués.

Le point de terminaison est d’administration : les profondeurs de file, les comptes de plantages et de timeouts par étape, les totaux cumulés et chaque nom d’étape choisi par l’opérateur décrivent ensemble la quantité de courrier que porte ce déploiement et la façon dont son pipeline est construit. Il n’est donc servi que sur un écouteur marqué ADMIN = yes, autorisé à porter effectivement la surface d’administration. Partout ailleurs, il répond par un simple 404, la réponse qu’obtient tout chemin inconnu. Contrairement à /api/v1, il ne demande aucun identifiant, car un collecteur Prometheus n’en a aucun à présenter : l’indicateur d’écouteur est tout le contrôle d’accès, ne marquez donc qu’un écouteur que seul le système de supervision peut atteindre.

Pointez le collecteur vers l’écouteur d’administration, ou ajoutez ADMIN = yes à l’écouteur qu’il interroge déjà (un écouteur en clair doit être sur la boucle locale ou une socket UNIX — voir La surface d’administration ci-dessous). Lier pepsi-httpd lui-même à une adresse privée n’est pas une solution de rechange : le même processus doit répondre à mta-sts.<domain> (RFC 8461) et à openpgpkey.<domain> depuis l’internet public, et il n’existe pas de liaison d’écouteur par route. La première collecte refusée parce que son écouteur n’est pas marqué est journalisée avec le nom de l’écouteur.

POST /resume

Libère un message en pause dans le pipeline : la ligne correspondante passe de paused à pending et le dispatcher est notifié afin que l’étape responsable s’exécute à nouveau. C’est la cible du webhook de paiement pepsi-resume de GNU Taler (voir pepsi-setup(1) et [pepsi-payments]), appelé lorsqu’un bon de commande est payé.

La requête doit porter Authorization: Bearer <token> correspondant au RESUME_AUTHORIZATION_TOKEN configuré (comparé en temps constant), et un corps JSON {"message_id": "<token>"} nommant le jeton externe du message (l”order_id du marchand). Réponses : 200 lorsque le message existe (un message en pause a été repris, ou il n’était déjà pas en pause — l’appel est idempotent), 404 lorsque le jeton est inconnu, 401 en cas d’autorisation échouée, 400 sur un corps malformé, 413 sur un corps de plus de 4 Kio. Le point de terminaison est désactivé (404) lorsque RESUME_AUTHORIZATION_TOKEN n’est pas configuré.

Un message que retient pepsi-stage-quarantine(1) est laissé tel quel (avec une réponse 200) : le webhook signale un paiement, et seul un opérateur libère le courrier en quarantaine (pepsi-queue(1) quarantine release).

/api/v1/…

L’API d’administration — la file, le résumé de santé, la configuration, le magasin de clés, le journal d’audit. Servie uniquement sur un écouteur marqué ADMIN = yes, et seulement à un principal authentifié. Voir La surface d’administration ci-dessous et le chapitre « L’API d’administration » du manuel pour la référence des points de terminaison, la table des portées et la forme des erreurs.

/ui, /ui/…

La console d’administration : un frontal de navigateur rendu côté serveur la file, le magasin de clés, la configuration et les journaux. Servie sur les mêmes écouteurs ADMIN = yes que /api/v1, sous la même authentification, les mêmes vérifications de portée et le même journal d’audit — elle est cliente de l’API et ne lui ajoute aucune capacité. Les pages sont

/ui (tableau de bord), /ui/login, /ui/login/second-factor, /ui/logout, /ui/security, /ui/security/register, /ui/security/ID/{rename,remove} (clés de sécurité, ci-dessous), /ui/enrol, /ui/enrol/TOKEN (connexion par e-mail, ci-dessous), /ui/queue, /ui/queue/ID, /ui/queue/ID/{requeue,bounce,cancel}, /ui/quarantine, /ui/quarantine/TOKEN, /ui/quarantine/TOKEN/{release,delete} (courrier retenu, ci-dessous), /ui/greylist, /ui/greylist/rules, /ui/greylist/rules/ID/delete, /ui/deferred, /ui/deferred/allow (greylisting, ci-dessous), /ui/identities, /ui/identities/ID, /ui/identities/ID/{publish,unpublish,vks,primary,revoke,delete,csr,certificate}, /ui/identities/request/{generate,register}, /ui/peers, /ui/peers/{import,discover}, /ui/peers/ID/{delete,recheck}, /ui/ca-trust, /ui/ca-trust/add, /ui/ca-trust/ID/{delete,scope}, /ui/config, /ui/config/SECTION, /ui/logs, /ui/logs/{mail,tls,dmarc,dns}, /ui/domains, /ui/domains/check, /ui/dkim, /ui/dkim/rotate, /ui/mpki, /ui/mpki/domains, /ui/mpki/domains/DOMAIN (GET et POST), /ui/mpki/users, /ui/mpki/users/ADDRESS/{approve,rename,select,opt-out,delete}, /ui/mpki/orders, /ui/mpki/notices, /ui/mpki/notices/read (certificats gérés, ci-dessous), /ui/secure, /ui/secure/TOKEN, /ui/secure/TOKEN/ACTION, /ui/setup, /ui/setup/STEP (GET et POST), /ui/setup/tasks (GET et POST), /ui/setup/tasks/ID, l’unique feuille de style /ui/static/console.css et l’unique script /ui/static/webauthn.js (chargé seulement par les pages des clés de sécurité).

Attente d’une tâche de configuration. GET /api/v1/setup/tasks/ID accepte ?wait=SECONDS (60 au plus, combinable avec ?since=SEQ) et répond dès que la tâche est terminée ou a une ligne de progression postérieure à SEQ, ou lorsque le temps est écoulé ; la page de tâche de la console attend de la même façon jusqu’à 20 secondes par rechargement. Ni l’une ni l’autre n’interroge la base de données en boucle : le serveur maintient une connexion LISTEN sur les canaux setup_task_done et setup_task_progress, que les écritures de l’applicateur notifient avec l’identifiant de la tâche, et réveille les requêtes qui attendent cette tâche. La connexion est distincte du pool de requêtes et se reconnecte d’elle-même avec un délai croissant ; tant qu’elle est coupée, une attente rend la main aussitôt plutôt que de rester bloquée, et la page de la console se replie sur un rechargement toutes les cinq secondes.

L’interrupteur de télémétrie. La question SHARE_TELEMETRY de l’interview ne peut recevoir la réponse oui que lorsque pepsi-telemetry-client(1) est en cours d’exécution (en sommeil tant que la télémétrie est désactivée) et que [pepsi] SYSTEM_ID est configuré, car ce serveur ne génère jamais d’identifiant et un oui sans démon pour y donner suite ne ferait rien. Il apprend l’un et l’autre de la ligne de vivacité du démon dans pepsi.telemetry_client, qu’il peut lire mais non écrire, et qui porte un booléen pour l’identifiant, jamais sa valeur. Sinon, la case à cocher est rendue désactivée avec des indications (démarrer l’unité ; ajouter un SYSTEM_ID), GET /api/v1/setup/questions marque la question "disabled": true avec un disabled_reason, et un oui passant par PUT /api/v1/setup/answers ou par une tâche write-config est refusé avec 409 telemetry_client_not_ready. GET /api/v1/setup/telemetry rapporte le même état (sharing, can_enable, reason, client). La désactivation de la télémétrie n’est jamais refusée. Le write-config de l’applicateur notifie le démon après avoir écrit le fichier, dans un sens comme dans l’autre.

Une liste d’autorisation de chemins en reverse-proxy doit inclure aussi les familles /ui/setup* et /ui/secure* : la première est tout le questionnaire de configuration initiale du navigateur, la seconde les pages d’administration du lien sécurisé.

La console ne livre aucun JavaScript hormis l’unique script statique des pages des clés de sécurité, et ne charge rien depuis un autre hôte ; chaque action est un formulaire, chaque action destructrice est confirmée, et chaque formulaire modifiant porte le jeton CSRF de la session en champ caché (une requête modifiante dont l”Origin nomme un autre hôte est refusée d’emblée). Elle n’exerce aucun contrôle de service — il n’y a délibérément aucun bouton de redémarrage, d’arrêt ou de sauvegarde. Voir le chapitre « La console d’administration » du manuel.

/3.0/…, /3.1/…

L’API REST de GNU Mailman 3 – version amont 3.3.10, réimplémentée pour que les logiciels écrits pour GNU Mailman 3 (mailmanclient, Postorius, HyperKitty) fonctionnent sans modification avec Pepsi. Servie uniquement sur un écouteur marqué LIST_API = yes, sous la même règle de liaison que ADMIN (clair sur boucle locale, socket UNIX, ou TLS), et authentifiée par HTTP Basic contre l’unique paire [pepsi-list] API_USER/API_PASS. Ce n’est pas /api/v1 : public différent, enveloppe de collection différente, forme d’erreur différente, aucune portée. Voir le chapitre « L’API REST de GNU Mailman 3 » du manuel.

LIST_API_TESTING = yes arme en outre GET /3.1/reserved/reset, qui vide toutes les tables de listes et d’archives. Il existe pour les suites de tests de compatibilité et ne doit pas être posé sur un déploiement portant du courrier réel.

GET /favicon.ico

GET /favicon-VERSION.svg

Le badge Pepsi comme icône du navigateur, servi sur chaque écouteur quels que soient ses drapeaux : une icône ne dit rien du déploiement. La console, sa page de connexion et les pages des listes de diffusion font référence au SVG, dont le nom porte le début de son SHA-256 ; comme une nouvelle icône est une nouvelle URL, il est envoyé avec Cache-Control: public, max-age=31536000, immutable. /favicon.ico (16, 32 et 48 px) est ce qu’un navigateur va chercher de lui-même pour une page qui ne référence aucune icône ; son URL ne peut pas changer, il peut donc être mis en cache une semaine. Les deux portent un ETag et répondent 304 à un If-None-Match correspondant. Les fichiers sont compilés dans le binaire.

/lists, /lists/…, /archives/list/…, /robots.txt

L”interface web publique des listes de diffusion : l’index des listes, la page d’information d’une liste, les formulaires d’abonnement et de désabonnement, les pages de confirmation, la cible de désabonnement en un clic de la RFC 8058 (qui répond 400 à un POST dont le corps n’est pas List-Unsubscribe=One-Click), les archives (aux formes d’URL de HyperKitty, pour que les liens Archived-At: d’un déploiement migré continuent de fonctionner) et leur recherche. Servie uniquement sur un écouteur marqué LISTS = yes, à quiconque, sans identifiant.

C’est le seul drapeau dont le conseil de déploiement est l’inverse des deux autres. ADMIN est pour l’exploitant et LIST_API porte un mot de passe partagé : tous deux refusent d’être servis là où leurs identifiants traverseraient un réseau en clair ; cette surface existe pour être atteinte depuis l’internet ouvert, cette restriction ne lui est donc délibérément pas appliquée. Un écouteur LISTS en clair est le choix de l’exploitant et reçoit une ligne de journal plutôt qu’un refus – mais un formulaire d’abonnement porte l’adresse de quelqu’un : placez-le sur un écouteur TLS.

Ces pages ne livrent aucun JavaScript (hormis les deux pages des clés de sécurité, comme dans la console), et leur Content-Security-Policy n’a par conséquent aucun script-src. /robots.txt autorise les archives et interdit la recherche, la seule route qui exécute une requête plein texte par appel ; la recherche est en outre limitée en débit sur son propre budget, car le serveur doit tout de même survivre à un robot qui ignore le fichier.

Les deux budgets s’expriment en requêtes par minute et par adresse source (un client IPv6 par /64), lues dans la section [pepsi-list] :

WEB_RATE_LIMIT

(entier, facultatif) Toutes les routes de cette interface et du niveau membre ci-dessous. Valeur par défaut 600.

WEB_SEARCH_RATE_LIMIT

(entier, facultatif) La route de recherche, en plus de la limite ci-dessus. Valeur par défaut 30.

Une valeur inférieure à 1 est relevée à 1 : aucune des deux ne peut être désactivée. Derrière un proxy inverse, chaque requête arrive par la socket UNIX sans adresse de client, de sorte que tous les clients partagent un même budget ; relevez-y les limites et laissez le proxy limiter par client.

Le même drapeau sert aussi le palier des membres — /lists/register, /lists/verify/<token>, /lists/sign-in, /lists/sign-in/second-factor, /lists/sign-out, /lists/reset, /lists/me et /lists/me/security (avec /lists/static/webauthn.js) — ainsi que la console du propriétaire et du modérateur à /lists/<list-id>/admin.... Ni l’un ni l’autre n’est un second drapeau : un système de comptes que personne ne peut atteindre n’est pas un choix de déploiement que quiconque ferait.

Ces pages emploient pepsi.list_session et les cookies pepsi_list_session/pepsi_list_csrf, qui ne sont pas les pepsi_session/pepsi_csrf de la console de l’exploitant et n’y accordent rien – ni l’inverse. L’autorité sur une liste est une interrogation de la liste des membres et non un drapeau de compte : un enregistrement list_member avec role = owner ou moderator pour cette liste, plus list_user.is_server_owner comme seule autorité globale du palier. Un appelant qui ne l’a pas obtient la page « introuvable » ordinaire, car sur une surface publique un refus qui se distingue a révélé que la chose existe. Voir la section « Deux systèmes de comptes » du manuel.

95.1.3.1.5. La surface d’administration

Un écouteur portant ADMIN = yes sert en outre /api/v1, la console /ui et /metrics. Sur tout autre écouteur, ces routes répondent un simple 404, octet pour octet celui qu’obtient tout chemin inconnu, de sorte que publier l’écouteur public ne publie pas l’administration et qu’un écouteur public ne peut pas être sondé pour savoir si l’administration est activée sur ce déploiement.

/api/v1 et /ui authentifient et autorisent en outre chaque requête, comme ci-dessous. /metrics non : un collecteur n’a aucun identifiant à présenter, l’indicateur d’écouteur est donc tout ce qui se dresse devant lui.

pepsi-httpd refuse de les servir sur un écouteur marqué qui les transporterait en clair hors de cet hôte : le TCP en clair n’est accepté que sur une adresse de boucle locale, tandis que les écouteurs TLS et les sockets UNIX conviennent toujours. Un écouteur activé par socket (SERVE = systemd) ne convient jamais sans TLS, quoi que lie son unité — y compris un ListenStream= sur la boucle locale ou sur un chemin UNIX — car l’adresse du descripteur hérité n’est pas visible d’ici, et la traiter comme autorisée laisserait passer le cas le plus strict par la vérification la plus lâche. Puisque le déploiement livré est activé par socket, l’administration a besoin d’un écouteur à elle (une socket UNIX, ou une socket TLS). Un écouteur qui échoue au test journalise un avertissement au démarrage et ne sert que les points de terminaison publics ; pepsi-setup(1) signale la même chose au moment de la configuration.

Trois mécanismes d’authentification se résolvent en un seul modèle d’identité, essayés dans cet ordre — un identifiant explicitement présenté l’emporte toujours, de sorte qu’un jeton délibérément étroit n’est jamais silencieusement élargi :

  1. Authorization: Bearer pepsi_<id>.<secret> — une ligne de pepsi.api_token. Seul le condensat de la moitié secrète est stocké.

  2. Un cookie de session issu de POST /api/v1/auth/login — ou du propre formulaire POST /ui/login de la console, qui crée la même session — avec un jeton CSRF exigé sur chaque requête modifiante. Les sessions ont par défaut un délai d’inactivité de 30 minutes et une durée de vie absolue de 12 heures ([pepsi-admin] SESSION_IDLE et SESSION_LIFETIME). Les tentatives de connexion sont limitées par minute par compte et par adresse source (LOGIN_RATE_LIMIT) et les tentatives échouées par compte et par jour (LOGIN_DAILY_LIMIT, 100 par défaut, après quoi les connexions par mot de passe du compte sont refusées jusqu’à ce que l’allocation se reconstitue). Un compte doté d’un second facteur TOTP (pepsi-keys otp enroll --console LOGIN) a aussi besoin du code courant ("otp" dans la requête, le champ de code du formulaire) ; ce serveur ne peut pas lire le secret et demande à pepsi-setup apply une tâche confirm-login une fois le mot de passe vérifié, de sorte qu’un tel compte ne peut pas se connecter par mot de passe tant que l’applicateur n’est pas installé. Un code manquant ou erroné est le même échec qu’un mauvais mot de passe. Un compte doté d’une clé de sécurité WebAuthn (voir ci-dessous) reçoit, une fois le mot de passe correct, une seconde étape au lieu d’une session : la console affiche la page de la clé de sécurité, et l’API répond 401 second_factor_required avec un défi à usage unique, complété à POST /api/v1/auth/login/second-factor (ou au POST /ui/login/second-factor de la console) par une assertion — ou, là où le compte a aussi TOTP et où REQUIRE_WEBAUTHN ne couvre pas les comptes de la console, par son code.

  3. SO_PEERCRED sur un écouteur à socket UNIX : root, ou un membre de [pepsi-admin] ADMIN_GROUP, est administrateur sans aucun identifiant. C’est ce qui fait fonctionner l’amorçage au premier démarrage et ce sur quoi s’appuie la configuration livrée.

PAM n’est délibérément pas pris en charge : cela placerait un chemin d’authentification privilégié et la sémantique des comptes système à l’intérieur de la couche web du serveur de courrier.

Connexion par e-mail. Un utilisateur final obtient un principal own:<address> en prouvant qu’il contrôle la boîte aux lettres. Avec [pepsi-admin] ENROL_STAGE défini, quatre routes publiques de la console existent (sinon elles répondent 404) : GET/POST /ui/enrol prend une adresse et, lorsque ce serveur la sert (une identité non révoquée du magasin de clés, ou un compte local d’une étape Maildir ou .forward), lui envoie un lien à usage unique, injecté à ENROL_STAGE depuis l’expéditeur nul avec le modèle enrol-link.<lang>.body ; la réponse est la même pour toute adresse et est envoyée avant que la recherche ne soit faite. GET /ui/enrol/<token> affiche un formulaire de confirmation et ne change rien ; POST /ui/enrol/<token> vérifie le second facteur TOTP de l’adresse, consomme le lien et ouvre une session de navigateur (pepsi.own_session) détenant exactement own:<address>, avec les cookies, les durées de vie et la protection CSRF d’une session par mot de passe. Le second facteur est vérifié par pepsi-setup apply, jamais ici : la confirmation met en file une tâche confirm-enrolment portant le code (vide lorsqu’aucun n’a été saisi) sous la propre portée de l’adresse et n’ouvre la session que lorsqu’elle se termine done ; une adresse sans second facteur passe. L’inscription a donc besoin de l’applicateur et de CONFIG_DB, et sans eux le formulaire d’adresse répond qu’il est indisponible. Seul le SHA-256 du jeton du lien est stocké (pepsi.own_enrolment) ; un lien fonctionne une fois, pendant ENROL_LIFETIME, accepte cinq soumissions, et est remplacé par le suivant envoyé à l’adresse. Les pages qu’atteint alors un utilisateur final sont en lecture seule, hormis les opérations sur les clés ci-dessous ; les paramètres se changent toujours par e-mail (pepsi-stage-edit-settings(1)). Les options de [pepsi-admin] :

ENROL_STAGE

L’étape à laquelle le courrier du lien est injecté, normalement celle par laquelle le courrier local est remis, ou une étape NOTICE_SIGNER placée devant elle, qui signe le courrier du lien (il est marqué state.notice, type enrol ; voir pepsi-stage-encrypt(1)). Non défini (par défaut), l’inscription est désactivée. pepsi-setup(1) refuse un nom qui n’est pas une étape configurée.

ENROL_URL

L’origine https:// vers laquelle pointe le lien (schéma, hôte et port facultatif, rien après) : là où les utilisateurs atteignent un écouteur ADMIN = yes, directement ou par le proxy inverse TLS. Obligatoire avec ENROL_STAGE. Elle n’est jamais dérivée du Host de la requête, qu’un demandeur pourrait choisir.

ENROL_FROM

From: du courrier du lien. Par défaut postmaster@ le propre domaine de l’adresse.

ENROL_LIFETIME

Durée de validité d’un lien. Par défaut 30 m.

ENROL_MAIL_PER_HOUR

Liens envoyés à une même adresse par heure. Par défaut 3.

ENROL_RATE_LIMIT

Demandes et confirmations d’inscription par adresse cliente et par heure, en plus de RATE_LIMIT. Par défaut 20.

Clés de sécurité (WebAuthn). Les comptes de la console, les utilisateurs finaux qui se connectent par e-mail et les membres des listes de diffusion peuvent enregistrer des identifiants WebAuthn comme second facteur à côté de TOTP ; n’importe quelle clé, ou un code TOTP là où il en existe un et où il est autorisé, le satisfait. Ce n’est jamais un remplacement du mot de passe. Le vérificateur est propre à Pepsi (pepsi_common::webauthn) : format d’attestation none seulement, clés ES256 et Ed25519, l’origine exacte et l’empreinte de l’identifiant RP vérifiées, présence de l’utilisateur exigée, et un compteur de signatures qui doit croître. L’origine de la console est [pepsi-admin] CONSOLE_URL (par défaut ENROL_URL), celle des pages de membre celle de [pepsi-list] BASE_URL ; sans elle, aucune clé n’y est proposée. Les défis sont de 32 octets aléatoires, stockés sous forme de leur SHA-256 dans pepsi.webauthn_challenge, fonctionnent une fois, pendant cinq minutes, et sont liés à la connexion en attente, au lien d’inscription ou à la session qui les a demandés ; les identifiants (pepsi.webauthn_credential, clés publiques seulement) sont recherchés par propriétaire et par identifiant. Une session connectée gère ses clés à /ui/security (membres : /lists/me/security) : l’enregistrement redemande le mot de passe, et ajouter une clé supplémentaire ou en retirer une exige aussi une assertion par l’une des clés du compte (ou son code TOTP), car une session seule n’ajoute jamais de facteur à un propriétaire qui en a un. Sous [pepsi-httpd] REQUIRE_WEBAUTHN, la dernière clé ne peut pas être retirée, et un compte qui n’en a pas en enregistre une à sa connexion suivante. Les pages de cérémonie sont les seules qui chargent du script : un fichier statique, webauthn.js, servi à /ui/static/webauthn.js et /lists/static/webauthn.js et autorisé par le Content-Security-Policy de ces pages par son SHA-256 et son URL exacte ; toute autre page garde une politique sans script-src. Un opérateur retire une clé perdue avec DELETE /api/v1/accounts/{id}/webauthn, DELETE /api/v1/webauthn/{address} ou DELETE /api/v1/webauthn/members/{address}. Événements d’audit : auth.webauthn.register, .rename, .remove, .refused et .reset ; une étape de connexion refusée est auth.login.second-factor-refused comme un code TOTP refusé.

CONSOLE_URL ([pepsi-admin])

L’origine https:// à laquelle les clés de sécurité sont liées. Par défaut ENROL_URL.

REQUIRE_WEBAUTHN ([pepsi-httpd])

no (par défaut), all, ou l’un quelconque de admins, users, members.

L’autorisation se fait par portée, déclarée par point de terminaison (config:read, config:write, keys:read, keys:write, peers:write, queue:read, queue:write, logs:read, setup:write, secure:read, secure:write, plus own:<address> pour un principal confiné à une seule adresse). GET /api/v1/openapi.json est engendré depuis la table de routes propre au serveur et constitue la liste faisant foi pour un build donné.

secure:read et secure:write sont séparées parce que révoquer un message à lien sécurisé en détruit l’unique copie ; une suppression irréversible n’a pas sa place derrière une capacité nommée « read ».

La génération ou la révocation de matériel de clé ne se fait jamais ici : le matériel privé appartient au seul rôle de base pepsi-crypto. Générer une clé gérée par le serveur (POST /api/v1/identities), enregistrer la propre clé publique d’un utilisateur (POST /api/v1/identities/client) et révoquer une identité (PATCH /api/v1/identities/{id} avec {"status": "revoked"} et un revocation_reason facultatif, ce qui détruit la moitié privée d’une clé de signature seule) sont au lieu de cela demandés, sous forme de lignes generate-identity, register-client-key et revoke-identity dans pepsi.setup_task que pepsi-setup apply revalide et exécute en tant que pepsi-crypto (voir ci-dessous). Un PATCH de révocation est donc asynchrone : il ne porte que status et répond avec la tâche mise en file ; l’identité se lit revoked une fois que l’applicateur a tourné. L’enregistrement n’implique aucun matériel privé, mais une clé enregistrée comme celle de l’utilisateur devient sa face publique et vérifie des signatures en son nom : un tiers web compromis ne doit donc pas pouvoir en implanter une. L’aller-retour du certificat S/MIME suit le même chemin : POST /api/v1/identities/{id}/csr ({"display_name": ...}, facultatif, le CN du sujet ; le nom alternatif du sujet est toujours la propre adresse de l’identité) met en file une tâche identity-csr dont le résultat porte la requête PKCS#10 sous csr_pem, et POST /api/v1/identities/{id}/certificate ({"certificate": "<PEM, or DER as base64>"}, au plus 64 Kio) met en file une tâche identity-certificate qui installe le certificat émis une fois que l’applicateur a vérifié qu’il porte sur la propre clé de l’identité et nomme son adresse. La requête est signée avec la clé privée et l’installation la ré-enveloppe, de sorte que ni l’une ni l’autre n’est faite par ce serveur. Les deux sont ouvertes au propre principal own:<address> de l’adresse et répondent 400 pour une identité OpenPGP ou pour la propre clé (MUA) d’un utilisateur.

Tout ce qui est du matériel public se fait ici, comme le fait pepsi-keys(1) : POST /api/v1/ca-trust ({"certificate": "<PEM or base64 DER>", "label": ..., "permitted_domains": [...]}) ajoute une ancre de confiance, en refusant tout ce qui n’est pas un certificat d’AC (basicConstraints CA:TRUE), audité comme key.ca.add au niveau warning ; PUT /api/v1/ca-trust/{id}/scope ({"permitted_domains": [...] | null}) définit ou lève les domaines de courrier pour lesquels on lui fait confiance, audité comme key.ca.scope au niveau warning ; POST /api/v1/peers/{id}/recheck efface l’échéance de rafraîchissement de la clé en cache d’un correspondant et lance un key_request forcé pour son adresse, auquel répond un service pepsi-keydisc (rien n’est récupéré dans la requête) ; POST /api/v1/peers et POST /api/v1/peers/discover importent une clé et mettent en file une recherche. Les formulaires de la console appellent les mêmes fonctions que ces gestionnaires.

Certificats gérés. /api/v1/mpki/domains, /api/v1/mpki/users, /api/v1/mpki/orders et /api/v1/mpki/notices (avec .../notices/read), ainsi que les pages /ui/mpki de la console, montrent et modifient la PKI gérée de pepsi-keys(1) mpki : les réglages par domaine, les utilisateurs et les noms que portent leurs certificats, les commandes et les avis destinés aux administrateurs. La lecture exige keys:read, chaque modification keys:write ; un principal confiné à une adresse est refusé. L’en-tête des pages montre une cloche avec le nombre d’avis non lus à chaque principal qui a keys:read et n’est pas confiné à une adresse. Ce serveur ne parle jamais à l’AC, ne peut pas lire l’identifiant d’AC et ne peut pas écrire de commande : commander, renouveler et révoquer sont l’affaire de pepsi-keys mpki run. Les modifications sont auditées sous mpki.domain.set, mpki.user.add, mpki.user.set, mpki.user.delete et mpki.notice.read.

Greylisting. GET /api/v1/greylist (les décisions des dernières ?hours=, à partir des compteurs de pepsi-greylist(1)), /api/v1/greylist/triplets (?state=, ?domain=, ?ip=, ?rcpt=), /api/v1/greylist/rules (GET, POST) et /api/v1/greylist/rules/ID (DELETE), ainsi que /ui/greylist de la console, montrent les décisions du démon et modifient ses règles. La lecture exige logs:read, une règle config:write ; les règles sont écrites par les fonctions SECURITY DEFINER greylist_rule_add et greylist_rule_remove avec origin = console et auditées sous greylist.rule.added et greylist.rule.removed. Un principal confiné à une adresse ne lit que les triplets de cette adresse (/ui/deferred), et POST /api/v1/greylist/allow-sender (/ui/deferred/allow) met un expéditeur sur sa propre liste blanche, la première de l’espace de noms propre à l’utilisateur que consulte pour lui le contournement de liste blanche du démon, par la fonction SECURITY DEFINER whitelist_add_user_sender, qui refuse une liste blanche partagée ; audité sous whitelist.sender.added. Ce serveur peut lire les tables du greylisting mais pas les écrire, et ne peut par ailleurs ni lire ni écrire whitelist.

Courrier retenu. GET /api/v1/quarantine, GET /api/v1/quarantine/TOKEN et POST /api/v1/quarantine/TOKEN/{release,delete}, ainsi que les pages /ui/quarantine de la console, listent, libèrent et suppriment les messages que retient une étape pepsi-stage-quarantine(1), avec les fonctions et les natures d’événement d’audit (queue.quarantine-release, queue.quarantine-delete) de pepsi-queue quarantine. La lecture exige queue:read, l’action queue:write. La libération ne passe pas par workqueue_resume, qui refuse le courrier retenu. Jamais les en-têtes ni le corps d’un message.

Libre-service sur ses propres clés. Un principal confiné à une adresse (own:<address>) peut atteindre, pour cette seule adresse, les trois écritures de clé du libre-service à la manière de pEp : POST /api/v1/identities ({"address": ..., "vks": true|false}, vks facultatif et valant par défaut [pepsi-keys] VKS_PUBLISH), POST /api/v1/identities/client ({"address": ..., "key": "<armoured OpenPGP public key>"}, 64 Kio au plus) et PATCH /api/v1/identities/{id} (dont le champ vks_wanted, lorsqu’il vaut true, enregistre une demande de téléversement vers le serveur de clés pour une identité OpenPGP active et la publie via WKD ; la tâche de réessai pepsi-keys identity publish --retry effectue le téléversement ; et dont status: revoked demande une révocation). Chaque gestionnaire revérifie l’adresse ; l’identité d’une autre adresse répond 404. Chacun d’eux met en file une tâche pour un tel principal, y compris un PATCH qui modifie is_primary, published ou vks_wanted (set-identity-flags, réponse 202) : le second facteur de l’adresse appuie chaque modification, et seul l’applicateur peut le vérifier ; le champ otp est donc transmis. Les routes POST et le PATCH répondent avec la tâche mise en file ({"task": ..., "kind": ..., "applier_notified": ...}), non avec la clé, et le principal qui l’a demandée peut suivre cette tâche : GET /api/v1/setup/tasks/ID répond à tout principal pour une tâche qu’il a lui-même mise en file (404 pour celle de quelqu’un d’autre, comme pour une tâche inexistante ; la propriété est le requester_key de la tâche – le sélecteur du jeton, le numéro de ligne du compte ou le login du pair, aucun d’eux n’étant jamais réutilisé –, non le nom d’affichage requested_by), et GET /api/v1/setup/tasks ne liste que ces tâches-là à un principal dépourvu de setup:write. Les formulaires de clé de la console répondent avec la page de la tâche, /ui/setup/tasks/ID, aux mêmes conditions. DELETE /api/v1/identities/{id} reste réservé à l’opérateur (keys:write) : un utilisateur retire une clé, il n’efface pas sa ligne. La console offre la même chose via les formulaires Générer une clé gérée par le serveur et Enregistrer ma propre clé de la page des identités et les actions Téléverser vers le serveur de clés et Révoquer de la page d’une identité.

L’applicateur admet ces trois types de tâches avec sa propre barrière d’autorisation : le principal demandeur doit avoir détenu keys:write, ou own:<address> pour exactement l’adresse nommée dans les paramètres de la tâche (setup:write seul ne suffit pas). Il exige ensuite que l’adresse soit dans un domaine de [pepsi-ingress] ACCEPTED_DOMAINS et, pour un enregistrement, un unique certificat OpenPGP dont les User IDs nomment l’adresse ; pour une révocation, l’identité doit appartenir à cette adresse. Sans l’applicateur, les trois répondent 503 setup_applier_unavailable, comme tout autre chemin de l’applicateur ; la mise en file exige aussi la connexion [pepsi-admin] CONFIG_DB (503 setup_write_unavailable sinon).

Le second facteur. Chacun des trois corps de requête (et les formulaires de la console) accepte un "otp": "123456" facultatif, le code de second facteur actuel du propriétaire de l’adresse (voir pepsi-keys(1), otp). Ce serveur ne peut pas le vérifier, car il ne détient aucun droit sur pepsi.otp_key. Il se contente de transmettre le code dans les paramètres de la tâche, et l’applicateur le vérifie avant d’agir, pour une tâche admise au seul titre de own:<address> ; un code absent, erroné, rejoué ou verrouillé fait échouer la tâche avec le motif. Un principal détenant keys:write n’est pas sollicité. DELETE /api/v1/otp/ADDRESS (keys:write, jamais accessible sous own:) met en file une tâche reset-otp qui supprime le second facteur de l’adresse, ce qui est la façon de déverrouiller un second facteur verrouillé. Les changements d’indicateurs synchrones de PATCH /api/v1/identities/{id} (is_primary, published, vks_wanted) sont effectués ici et ne sont donc pas soumis au second facteur.

Il y a deux opérations que ce serveur refuse délibérément : écrire la surcouche de configuration (503 à moins que [pepsi-admin] CONFIG_DB ne nomme une connexion s’authentifiant comme le rôle pepsi-config, ce que le serveur vérifie au démarrage), et toute requête de configuration privilégiée lorsque le paquet de l’applicateur n’est pas installé (503, voir L’applicateur privilégié, et s’en passer ci-dessous).

La politique de rétention du journal d’audit et, lorsqu’il est activé, du journal de courrier est appliquée par la commande prune de ce binaire, non par le serveur : chaque compte de traitement du courrier peut ajouter à ces tables sans pouvoir en effacer, et le rôle pepsi-httpd est le seul rôle de service qui y détient DELETE (l’unique autre détenteur est le rôle pepsi-config de l’opérateur). Le pepsi-log-prune.timer livré l’exécute quotidiennement sous ce compte, de sorte que la rétention s’applique que le serveur web tourne ou non, et qu’un écouteur serve ou non la surface d’administration.

Note

Un seul binaire sert la surface publique et la surface d’administration. Un bogue dans le processus serveur partagé est donc un bogue dans les deux. C’est l’opérateur qui configure l’isolation : liez l’écouteur d’administration à une socket UNIX ou à la boucle locale.

GET /secure/TOKEN

La page d’entrée du portail de repli par lien sécurisé. Sans session, elle demande le PIN ; avec un cookie de session valide, elle rend le message. Répond 404 lorsque le jeton est inconnu (ou que le portail n’est pas configuré), 410 lorsque le message a expiré, et 429 tant que le jeton est verrouillé. Voir le chapitre sur le lien sécurisé du manuel et pepsi-stage-secure-link(1).

POST /secure/TOKEN

Vérifie le PIN. En cas de succès, elle pose le cookie de session et redirige (303) vers la page ci-dessus ; sur un mauvais PIN, elle réaffiche le formulaire avec 401, et sur la tentative qui épuise MAX_ATTEMPTS, elle répond 429 et verrouille le jeton pour une durée qui double à chaque nouveau verrouillage. Chaque tentative est imputée sur MAX_ATTEMPTS avant que son PIN ne soit testé, atomiquement avec la vérification du verrouillage, de sorte que des soumissions concurrentes ne peuvent pas tester plus de PIN que le budget ne le permet ; un PIN correct annule l’imputation. Une soumission sans PIN reçoit également 401, mais n’est pas comptée dans MAX_ATTEMPTS : ce n’est pas une devinette, et un client qui resoumet le formulaire vide dépenserait sinon les tentatives d’un destinataire légitime à sa place. Le PIN est soumis dans le corps de la requête et n’apparaît jamais dans une URL.

GET /secure/TOKEN/part/N

Télécharge la pièce jointe N du message. Autorisé par la session, jamais par le PIN. Toujours servi en Content-Type: application/octet-stream avec Content-Disposition: attachment et une Content-Security-Policy de bac à sable, quel que soit le type de média que le message prétendait — une partie text/html rendue en ligne depuis l’origine propre du portail est précisément ce que la conception refuse.

POST /secure/TOKEN/reply

Compose une réponse, en multipart/form-data (un champ text et des files facultatifs). Autorisé par la session. Le destinataire et l’expéditeur d’enveloppe de la réponse sont pris dans la ligne stockée et ne sont pas des entrées ; le corps est toujours en text/plain ; les téléversements sont plafonnés par MAX_REPLY_SIZE / MAX_REPLY_FILES pendant que le corps s’écoule ; et le message injecté ne porte délibérément pas state.local_origin, de sorte qu’il ne puisse hériter des privilèges de soumission. Répond 404 lorsque REPLY_STAGE n’est pas défini (répondre relève d’un consentement explicite, par déploiement).

Chaque réponse du portail porte, par route plutôt que par hôte, Content-Security-Policy: default-src 'none' (avec un nonce par réponse pour l’unique feuille de style en ligne et aucune source de script), Referrer-Policy: no-referrer, X-Content-Type-Options: nosniff, X-Frame-Options: DENY et Cache-Control: no-store. Le cookie de session est limité à Path=/secure/, HttpOnly, Secure et SameSite=Strict, de sorte que partager une origine avec les points de terminaison ci-dessus est sûr par construction et non par discipline de déploiement.

95.1.3.1.6. L’applicateur privilégié, et s’en passer

pepsi-httpd n’effectue jamais de changement privilégié. Il consigne une ligne d’intention dans pepsi.setup_task et se connecte à une socket de sonnette ; l’activation par socket de systemd transforme cette connexion en un pepsi-setup apply root de courte durée, qui valide la ligne et fait le travail. Le modèle de confiance complet est dans pepsi-setup(1), Le modèle de confiance de l’applicateur.

Cela rend la capacité retirable, et Debian l’empaquette séparément :

pepsi

Le serveur de courrier proprement dit : les binaires — y compris pepsi-setup lui-même —, le schéma, les modèles et toutes les autres unités (mis à part pepsi-stage-detect-language et pepsi-telemetry, empaquetés séparément). Un déploiement administré depuis un terminal n’a besoin de rien d’autre.

pepsi-httpd-admin

pepsi-setup-apply.socket et pepsi-setup-apply.service, et rien d’autre. C’est ce qui transforme une requête HTTP en un changement sous /etc/pepsi. pepsi le Recommends, de sorte qu’une installation par défaut l’a ; apt remove pepsi-httpd-admin réussit sans toucher à pepsi.

Avec ce paquet retiré, rien ne vide pepsi.setup_task. La boucle est rompue au mécanisme, non au bouton : une insertion dans cette table devient inerte, quoi qu’il advienne de la couche web. (Une installation depuis les sources obtient le même levier avec make install INSTALL_ADMIN_UNITS=no.)

Inerte, et cela le reste : remettre le paquet n’agit pas sur ce qui s’est accumulé pendant son absence. Son postinst exécute pepsi-setup apply --clear, qui supprime chaque ligne en file sans en exécuter une seule, de sorte qu’armer l’applicateur ne soit jamais aussi l’événement qui exécute une demande dont personne ne se souvient. Voir pepsi-setup(1).

95.1.3.1.6.1. Ce que fait alors la console

En lecture seule, et elle le dit. Chaque réglage sur lequel porte le questionnaire de configuration initiale est toujours affiché, avec sa réponse en attente ou sa valeur par défaut ; chaque contrôle qui en modifierait un est désactivé, sous une bannière nommant le paquet manquant. Les pages ne sont pas masquées : un opérateur qui a délibérément retiré l’applicateur doit encore pouvoir voir ce que le déploiement est configuré pour faire.

L’API refuse les mutations correspondantes avec un statut et un code qui leur sont propres plutôt qu’un échec générique

HTTP/1.1 503 Service Unavailable
{"code": "setup_applier_unavailable",
 "hint":  "the administrative package 'pepsi-httpd-admin' is not installed …",
 "detail": {"package": "pepsi-httpd-admin", "unit": "pepsi-setup-apply.socket"}}

Cela s’applique à POST /api/v1/setup/tasks, /setup/preflight, /setup/dns-check, /setup/certificates, PUT /api/v1/setup/answers, POST /api/v1/identities, POST /api/v1/identities/client, à un PATCH /api/v1/identities/{id} de révocation et à DELETE /api/v1/otp/{address}, ainsi qu’aux propres envois de formulaires de la console — POST /ui/setup/{step}, /ui/setup/tasks, /ui/identities/request/{generate,register}, /ui/identities/{id}/revoke, /ui/dkim/rotate (le « renouveler maintenant » de la page DKIM, une tâche dkim-rotate) et /ui/domains/check, qui est le bouton « vérifier maintenant » de la page des domaines. Chacun d’eux atteint la file par une unique fonction de mise en file qui demande d’abord, de sorte que le refus soit une seule décision plutôt qu’une par surface ; le contrôle désactivé sur la page est une présentation par-dessus cette vérification, non un substitut. La mise en attente des réponses est délibérément incluse : le seul but d’une réponse brouillon est d’être appliquée, et un assistant qui en accumule six étapes sur un hôte où rien ne peut les appliquer est une inaction silencieuse. DELETE /api/v1/setup/answers ne passe pas par cette barrière — écarter des brouillons ne peut causer aucun changement privilégié, et une console en lecture seule doit encore pouvoir vider un questionnaire à moitié terminé.

Notez le code distinct. setup_write_unavailable (pas de connexion CONFIG_DB) et setup_applier_unavailable appellent des remèdes différents, et l’applicateur est signalé en premier lorsque les deux s’appliquent : configurer un rôle de base n’aurait pas aidé.

Ce qui n’est pas affecté, c’est /api/v1/config et les pages de configuration de la console. Celles-ci écrivent pepsi.config_override, la surcouche en base que chaque composant lit à l’exécution — non un fichier de /etc. Leur seule barrière est [pepsi-admin] CONFIG_DB, car l’applicateur n’a rien à y voir et étendre la règle de lecture seule pour les couvrir retirerait une capacité dont la scission du paquet ne traitait pas. Les deux couches sont décrites sous Superposition de la configuration dans le manuel.

95.1.3.1.6.2. Comment il le détecte

En regardant deux fichiers, qui à eux deux répondent installé et armé :

  1. pepsi-setup-apply.socket existe comme fichier d’unité dans un répertoire que systemd parcourt (/etc/systemd/system, /run/systemd/system, /usr/local/lib/systemd/system, /usr/lib/systemd/system, /lib/systemd/system) ; et

  2. [pepsi-admin] APPLY_SOCKET existe, est une socket, et est accessible en écriture à ce compte — se connecter à une socket UNIX exige la permission d’écriture.

Deux stat et un access, sans privilège — ce qui compte, car le serveur est déjà descendu vers le compte non privilégié pepsi-httpd et ne peut rien demander à dpkg ni à systemd. Il ne se connecte délibérément pas : se connecter est la sonnette, et démarrerait un processus root à chaque rendu de page.

Aucun des deux tests n’est redondant. Sans le premier, un nœud de socket périmé se lit comme une sonnette vivante — et les nœuds périmés arrivent : le RemoveOnStop= de systemd vaut « off » par défaut (l’unité livrée le règle ; une unité éditée à la main peut ne pas le faire), et un paquet dont les fichiers sont supprimés plutôt qu’arrêtés laisse purement et simplement le nœud derrière lui. C’est exactement le cas pour lequel cette fonctionnalité existe, et s’y tromper échouerait de façon ouverte. Sans le second, un paquet fraîchement installé dont la socket n’a jamais été activée se lirait comme prêt, et chaque tâche resterait pending à jamais.

La vérification échoue de façon fermée. Un chemin qui ne peut pas être examiné, un chemin qui n’est pas une socket, une erreur de permission — chaque incertitude se lit comme « indisponible » et la console passe en lecture seule. L’échec récupérable est de se voir dire d’installer quelque chose qui est déjà installé ; l’irrécupérable est de croire qu’un changement a été fait.

Deux conséquences :

  • Un site qui vide la file autrement n’a pas de sonnette (ou pas de fichier d’unité) et se lit comme indisponible : pepsi-setup apply --once depuis cron, une unité écrite à la main, un hôte sans systemd, ou des fichiers d’unité quelque part où systemd ne cherche pas. [pepsi-admin] APPLIER = yes outrepasse la sonde. C’est une promesse que fait l’opérateur ; rien ici ne peut la vérifier.

  • L’inverse : la socket peut être présente alors que l’unité de service est masquée ou cassée, auquel cas une tâche est mise en file et reste pending. La page des tâches montre ce statut plutôt que de prétendre autre chose. Les deux unités sont livrées dans un seul paquet : c’est donc un état fabriqué à la main plutôt qu’un résultat d’empaquetage.

[pepsi-admin] APPLIER = no rend la console en lecture seule par la seule configuration, pour un déploiement qui ne peut pas modifier son jeu de paquets.

95.1.3.1.7. Configuration

Les éléments suivants sont documentés dans pepsi.conf(5) : les options de la section [pepsi-httpd] (MAX_CONNECTIONS, MAX_CONNECTIONS_PER_IP, DB_POOL_SIZE, la paire ADDIN / ADDIN_URL qui active le module complémentaire Outlook, REQUIRE_WEBAUTHN, et le RESUME_AUTHORIZATION_TOKEN facultatif qui protège POST /resume), les sections de socket et de certificat SNI [pepsi-httpd-listener-<name>] et [pepsi-httpd-cert-<name>] (y compris les drapeaux d’écouteur ADMIN, LIST_API, LIST_API_TESTING et LISTS), la section [pepsi-admin] qui configure l’API d’administration, la section [pepsi-list] qui contient l’identifiant API_USER/API_PASS de l’API Mailman et API_RATE_LIMIT ainsi que les WEB_RATE_LIMIT/WEB_SEARCH_RATE_LIMIT de l’interface web, la section [pepsi-autoconfig] à partir de laquelle le document d’autoconfiguration est bâti, et la section [pepsi-secure-link] qui active le portail.

95.1.3.1.8. Abandon de privilèges

Pour lier les ports privilégiés (80/443), pepsi-httpd est souvent démarré en tant que root. Il ne sert pas en tant que root : une fois chaque écouteur configuré lié (et tout matériel de clé TLS lu), le processus abandonne ses privilèges au profit du compte de service non privilégié pepsi-httpd, abandonnant tous les groupes supplémentaires et basculant vers le gid et l’uid de ce compte avant d’accepter la moindre connexion. Le compte doit donc exister avant que le serveur ne soit démarré en tant que root ; créez-le (par exemple useradd --system --no-create-home --shell /usr/sbin/nologin pepsi-httpd) dans le cadre de l’installation.

Si l’abandon ne peut être complété en s’exécutant en tant que root — le plus souvent parce que le compte pepsi-httpd n’existe pas — le serveur journalise une erreur et quitte sans servir, plutôt que de risquer de s’exécuter en tant que root. Lorsqu’il est démarré par un utilisateur non root, aucun changement de privilège n’est effectué (le serveur s’exécute simplement en tant que l’utilisateur invoquant) ; il ne s’exécutera jamais en tant que root.

95.1.3.1.9. Matériel de clés TLS

Le certificat et la clé privée de chaque écouteur TLS sont lus une seule fois, au démarrage, avant l’abandon de privilèges décrit ci-dessus. Cela concerne ses propres TLS_CERT/TLS_KEY et chaque certificat SNI [pepsi-httpd-cert-*]. L’endroit d’où ils sont lus dépend de la façon dont le serveur a été démarré.

Sous systemd (le déploiement empaqueté). L’unité s’exécute dès le départ sous l’utilisateur non privilégié pepsi-httpd — elle ne détient jamais root — et ne peut donc pas ouvrir /etc/letsencrypt/{live,archive}, réservé à root par certbot. Elle n’en a pas besoin : pepsi-setup(1) écrit un drop-in /etc/systemd/system/pepsi-httpd.service.d/10-tls-credentials.conf comportant une entrée LoadCredential= par fichier. systemd ouvre ces fichiers en tant que root au démarrage de l’unité et transmet au service des copies privées sous $CREDENTIALS_DIRECTORY, un répertoire tmpfs propre à l’unité, lisible par ce seul service et invisible pour toute autre unité. pepsi-httpd y recherche chaque chemin configuré avant de se rabattre sur la lecture du chemin lui-même. La configuration n’en est pas affectée : TLS_CERT/TLS_KEY désignent toujours les fichiers réels, et c’est de ces chemins que sont dérivés les noms de credentials.

Deux conséquences :

  • Relancez pepsi-setup run après avoir ajouté, déplacé ou supprimé un certificat. Le drop-in est régénéré à partir de la configuration et n’énumère délibérément que des fichiers qui existent, car systemd refuse de démarrer une unité dont la source de credential est absente.

  • Un credential est matérialisé au démarrage de l’unité ; un certificat renouvelé n’atteint donc les clients qu’après un redémarrage. Le hook de déploiement certbot installé par pepsi-setup s’en charge (systemctl try-restart, ou launchctl kickstart -k sous macOS).

Démarré directement, sans systemd. Le serveur est démarré en tant que root, lit les fichiers lui-même et n’abandonne ses privilèges qu’ensuite : aucun credential n’intervient et les permissions des fichiers n’ont jamais d’importance.

Un certificat qui ne peut pas être chargé est signalé et ignoré, sans être fatal : les noms d’hôte SNI qu’il aurait servis cessent d’être disponibles en HTTPS, tandis que tous les autres certificats continuent de fonctionner. Seul un écouteur TLS qui ne dispose plus d’aucun certificat utilisable fait sortir le serveur. Un unique fichier illisible ne peut donc entraîner avec lui ni la politique MTA-STS de domaines sans rapport, ni le point de terminaison des métriques.

95.1.3.1.10. Limites de ressources

Le serveur est joignable depuis l’internet ouvert ; chaque ressource qu’un client peut lui faire dépenser est donc bornée :

  • Au plus MAX_CONNECTIONS connexions à la fois (256 par défaut), et au plus MAX_CONNECTIONS_PER_IP (32 par défaut) depuis une même adresse IPv4 ou un même /64 IPv6 ; une connexion au-delà du plafond par adresse est fermée avant de prendre une place. Les pairs sur socket UNIX — un proxy inverse — ne sont pas comptés par adresse.

  • Une poignée de main TLS doit s’achever en 30 secondes, les en-têtes de la requête doivent arriver en 30 secondes, et un corps de requête dans les 30 secondes suivant ses en-têtes ; un client qui cale perd sa connexion plutôt que de garder une place.

  • Chaque vérification de mot de passe (la console, le palier des membres des listes de diffusion, les mots de passe d’utilisateur de l’API Mailman) s’exécute hors de l’exécuteur de requêtes, au plus une vérification Argon2id par CPU à la fois ; une connexion qui ne trouve aucune place libre dans les cinq secondes reçoit une réponse de limitation de débit, sans avoir rien testé. Les comptes inconnus sont vérifiés contre un hachage factice, de sorte que le temps de réponse ne révèle pas quels comptes existent.

  • Les formulaires publics qui font envoyer par le serveur du courrier à une adresse dont personne n’a prouvé le contrôle (abonnement à une liste, inscription d’un membre, réinitialisation de mot de passe) sont limités par adresse cible — deux courriers de ce genre par adresse et par heure — en plus des limites par client ; l’inscription à la console a son propre ENROL_MAIL_PER_HOUR. La réponse est la même dans les deux cas.

Le chapitre « Modèle de sécurité » du manuel décrit ces mécanismes et les droits de base de données qui confinent ce serveur ; le tableau de disponibilité de son chapitre « Modèle de menace » énonce ce qu’ils garantissent.

95.1.3.1.11. Commandes

serve

Exécute le serveur jusqu’à interruption. Nécessite que le schéma ait été installé avec pepsi-setup(1).

prune

Supprime les enregistrements d’audit plus anciens que [pepsi-admin] EVENT_RETENTION_DAYS, les enregistrements du journal de courrier plus anciens que MAIL_LOG_RETENTION_DAYS, les sessions d’administration et d’utilisateurs finaux expirées et les liens d’inscription expirés, puis se termine. Exécuté en root, il descend d’abord au compte pepsi-httpd, dont le rôle de base de données détient le droit DELETE. pepsi-log-prune.timer l’exécute quotidiennement ; sur un système sans systemd, exécutez-le depuis cron.

95.1.3.1.12. Options globales

-c FILE, –config FILE

Lit la configuration depuis FILE au lieu de parcourir les emplacements par défaut.

-L LOGLEVEL, –log LOGLEVEL

Règle la verbosité de journalisation (par défaut [pepsi] LOG, sinon info).

-v, –verbose

Affiche les messages de journal de toutes les sources.

-h, –help ; -V, –version

Affiche un résumé d’utilisation / la version et quitte.

95.1.3.1.13. Signaux

SIGINT

Amorce l’arrêt et quitte proprement.

SIGTERM

Non capturé : la disposition par défaut met fin au processus sur-le-champ, coupant toute requête en vol. Rien n’est perdu de ce fait, puisque la file d’attente est dans PostgreSQL et que ce serveur ne conserve aucun état propre ; c’est ainsi que systemctl stop met fin à l’unité.

95.1.3.1.14. Code de sortie

0

Arrêt propre.

1

Une erreur s’est produite (par exemple un fichier de configuration malformé, un certificat illisible, ou une connexion de base de données échouée). La raison est écrite dans le journal.

2

La ligne de commande elle-même était erronée (une option inconnue, une option globale écrite après la sous-commande, un argument manquant).

78

Le schéma de la base de données est manquant ou provient d’une autre version de Pepsi ; exécutez pepsi-setup schema (voir pepsi-setup(1)).

95.1.3.1.15. Exemples

Servir via HTTPS

pepsi-httpd -c /etc/pepsi/pepsi.conf serve

Récupérer une politique pour test (en résolvant l’hôte SNI vers le serveur)

curl --resolve mta-sts.example.org:443:203.0.113.7 \
     https://mta-sts.example.org/.well-known/mta-sts.txt

Vérifier que la clé d’un utilisateur est publiée, comme le ferait le client d’un correspondant

gpg --locate-external-key alice@example.org

95.1.3.1.16. Voir aussi

pepsi-config(1), pepsi.conf(5), pepsi-dispatch(1), pepsi-keys(1), pepsi-setup(1), pepsi-dkim(1)

95.1.3.1.17. Bogues

Signalez les bogues au gestionnaire de tickets de Pepsi.