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 duHOSTNAMEde[pepsi-ingress](lemx). La politique n’est servie que lorsque leHostde la requête estmta-sts.<domain>pour un domaine deACCEPTED_DOMAINS; tout autre hôte (ouMTA_STS_MODE = none) donne404. 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
Hostchoisit entre eux : le premier est servi lorsque leHostde la requête estautoconfig.<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 dansACCEPTED_DOMAINS; tout autre hôte donne404. 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épond404tant que cette section ne nomme pas au moins un serveur entrant (IMAP_HOSTouPOP3_HOST). Le serveur sortant est dérivé du[pepsi-ingress-listener-*]marquéSUBMISSION = yes, sauf siSMTP_HOSTle redéfinit ; un serveur dérivé n’est jamais en clair, car l’ingress refuse un écouteur de soumission TCP en clair. UnIMAP_SOCKET,POP3_SOCKETouSMTP_SOCKETexplicite valantplainn’est publié que lorsque la même section indique aussiALLOW_PLAIN_AUTOCONFIG = yes: sans cette reconnaissance, pepsi-httpd refuse de démarrer, etvalidatede pepsi-setup(1) refuse la configuration, chacun avec un message nommant l’option, le serveur et son port, de sorte qu’unplainglissé 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 DNSautoconfig.<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_DOMAINSet seulement depuis une identitépublished,activeet OpenPGP. La réponse est la clé publique transférable binaire — non blindée — avecContent-Type: application/octet-streametAccess-Control-Allow-Origin: *comme l’exige la spécification. Un condensat inconnu donne404avec 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
policyest un200au 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 (
404lorsqu’elle était la seule) et journalisée au niveauerror: 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_KEYSthe signing daemon pepsi-dkim(1) does not delete a key that it retires but writes it toPUBLIC_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, asapplication/x-pem-filewithAccess-Control-Allow-Origin: *. It answers404when 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 poseX-Pepsi-Sign/X-Pepsi-Encryptsur 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 champsX-Pepsi-CryptoetX-Pepsi-Warningd’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 depuiscontrib/addin/.Chacune de ces routes donne
404à moins que[pepsi-httpd] ADDINne 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 publiquehttps://de cette passerelle, et un identifiant de manifeste dérivé de cette origine. L’origine provient deADDIN_URL, sinon duHostde la requête. Son schéma est toujourshttps, car Outlook refuse de charger les ressources d’un module complémentaire en HTTP simple, et une originehttp://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. UnHostcontenant autre chose que ce qu’un nom d’hôte et un port peuvent contenir est refusé par400plutô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_totalet les globauxpepsi_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, etpepsi_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 simple404, 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àpendinget le dispatcher est notifié afin que l’étape responsable s’exécute à nouveau. C’est la cible du webhook de paiementpepsi-resumede 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 auRESUME_AUTHORIZATION_TOKENconfiguré (comparé en temps constant), et un corps JSON{"message_id": "<token>"}nommant le jeton externe du message (l”order_iddu marchand). Réponses :200lorsque le message existe (un message en pause a été repris, ou il n’était déjà pas en pause — l’appel est idempotent),404lorsque le jeton est inconnu,401en cas d’autorisation échouée,400sur un corps malformé,413sur un corps de plus de 4 Kio. Le point de terminaison est désactivé (404) lorsqueRESUME_AUTHORIZATION_TOKENn’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 = yesque/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.csset 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 connexionLISTENsur les canauxsetup_task_doneetsetup_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_TELEMETRYde 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_IDest 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 danspepsi.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 unSYSTEM_ID),GET /api/v1/setup/questionsmarque la question"disabled": trueavec undisabled_reason, et un oui passant parPUT /api/v1/setup/answersou par une tâchewrite-configest refusé avec409 telemetry_client_not_ready.GET /api/v1/setup/telemetryrapporte le même état (sharing,can_enable,reason,client). La désactivation de la télémétrie n’est jamais refusée. Lewrite-configde 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”
Originnomme 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 queADMIN(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 = yesarme en outreGET /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 unETaget répondent304à unIf-None-Matchcorrespondant. 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à unPOSTdont le corps n’est pasList-Unsubscribe=One-Click), les archives (aux formes d’URL de HyperKitty, pour que les liensArchived-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.
ADMINest pour l’exploitant etLIST_APIporte 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 écouteurLISTSen 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.txtautorise 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 à
1est 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/meet/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_sessionet les cookiespepsi_list_session/pepsi_list_csrf, qui ne sont pas lespepsi_session/pepsi_csrfde 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 enregistrementlist_memberavecrole = owneroumoderatorpour cette liste, pluslist_user.is_server_ownercomme 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 :
Authorization: Bearer pepsi_<id>.<secret>— une ligne depepsi.api_token. Seul le condensat de la moitié secrète est stocké.Un cookie de session issu de
POST /api/v1/auth/login— ou du propre formulairePOST /ui/loginde 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_IDLEetSESSION_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âcheconfirm-loginune 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épond401 second_factor_requiredavec un défi à usage unique, complété àPOST /api/v1/auth/login/second-factor(ou auPOST /ui/login/second-factorde la console) par une assertion — ou, là où le compte a aussi TOTP et oùREQUIRE_WEBAUTHNne couvre pas les comptes de la console, par son code.SO_PEERCREDsur 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_STAGEL’étape à laquelle le courrier du lien est injecté, normalement celle par laquelle le courrier local est remis, ou une étape
NOTICE_SIGNERplacée devant elle, qui signe le courrier du lien (il est marquéstate.notice, typeenrol; 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_URLL’origine
https://vers laquelle pointe le lien (schéma, hôte et port facultatif, rien après) : là où les utilisateurs atteignent un écouteurADMIN = yes, directement ou par le proxy inverse TLS. Obligatoire avecENROL_STAGE. Elle n’est jamais dérivée duHostde la requête, qu’un demandeur pourrait choisir.ENROL_FROMFrom:du courrier du lien. Par défautpostmaster@le propre domaine de l’adresse.ENROL_LIFETIMEDurée de validité d’un lien. Par défaut
30 m.ENROL_MAIL_PER_HOURLiens envoyés à une même adresse par heure. Par défaut
3.ENROL_RATE_LIMITDemandes et confirmations d’inscription par adresse cliente et par heure, en plus de
RATE_LIMIT. Par défaut20.
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éfautENROL_URL.REQUIRE_WEBAUTHN([pepsi-httpd])no(par défaut),all, ou l’un quelconque deadmins,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
404lorsque le jeton est inconnu (ou que le portail n’est pas configuré),410lorsque le message a expiré, et429tant 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 avec401, et sur la tentative qui épuiseMAX_ATTEMPTS, elle répond429et verrouille le jeton pour une durée qui double à chaque nouveau verrouillage. Chaque tentative est imputée surMAX_ATTEMPTSavant 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 également401, mais n’est pas comptée dansMAX_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-streamavecContent-Disposition: attachmentet uneContent-Security-Policyde bac à sable, quel que soit le type de média que le message prétendait — une partietext/htmlrendue 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 champtextet desfilesfacultatifs). 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 entext/plain; les téléversements sont plafonnés parMAX_REPLY_SIZE/MAX_REPLY_FILESpendant que le corps s’écoule ; et le message injecté ne porte délibérément passtate.local_origin, de sorte qu’il ne puisse hériter des privilèges de soumission. Répond404lorsqueREPLY_STAGEn’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: DENYetCache-Control: no-store. Le cookie de session est limité àPath=/secure/,HttpOnly,SecureetSameSite=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 :
pepsiLe 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-languageetpepsi-telemetry, empaquetés séparément). Un déploiement administré depuis un terminal n’a besoin de rien d’autre.pepsi-httpd-adminpepsi-setup-apply.socketetpepsi-setup-apply.service, et rien d’autre. C’est ce qui transforme une requête HTTP en un changement sous/etc/pepsi.pepsile Recommends, de sorte qu’une installation par défaut l’a ;apt remove pepsi-httpd-adminré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é :
pepsi-setup-apply.socketexiste 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[pepsi-admin] APPLY_SOCKETexiste, 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 --oncedepuis 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 = yesoutrepasse 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 runaprè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, oulaunchctl kickstart -ksous 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_CONNECTIONSconnexions à la fois (256 par défaut), et au plusMAX_CONNECTIONS_PER_IP(32 par défaut) depuis une même adresse IPv4 ou un même/64IPv6 ; 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 queMAIL_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 comptepepsi-httpd, dont le rôle de base de données détient le droitDELETE.pepsi-log-prune.timerl’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, sinoninfo).- -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 stopmet 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.