24. L’API d’administration¶
pepsi-httpd sert sous /api/v1 une API HTTP qui couvre tout ce que font les outils en ligne de commande de l’opérateur : la file d’attente, le résumé de santé, la configuration, le magasin de clés et les journaux. La console de navigateur et un script sans surveillance sont clients de la même surface documentée.
Avertissement
L’API n’est pas encore stable. Le chemin porte v1 afin que le mécanisme de versionnement existe et que les clients soient écrits en conséquence, mais tant que la version de Pepsi commence par 0., une version peut encore changer la forme d’une demande ou d’une réponse ; de tels changements sont listés dans NEWS. Contrairement à la base de données, que chaque version fait avancer par migration (voir Mise à niveau), un client peut devoir être adapté. Figer le contrat avant que la console, son premier vrai client, ne l’ait exercé graverait des décisions prises à l’aveugle.
24.1. Où elle est servie¶
Uniquement sur un écouteur marqué ADMIN = yes. Sur tout autre écouteur, les routes /api/v1 répondent un simple 404 identique octet pour octet à ce que reçoit n’importe quel chemin inconnu. Publier l’écouteur HTTPS public ne publie donc pas l’administration, et un écouteur public ne peut même pas être sondé pour savoir si l’administration est activée sur ce déploiement.
La configuration livrée marque exactement un écouteur, une socket UNIX :
[pepsi-httpd-listener-admin]
SERVE = unix
UNIXPATH = /run/pepsi/admin.sock
UNIXPATH_MODE = 660
UNIXPATH_GROUP = pepsi-admin
MODE = plain
ADMIN = yes
pepsi-httpd refuse de servir les routes d’administration sur un écouteur marqué qui les emporterait en clair hors de cet hôte : le TCP en clair n’est accepté que sur une adresse de boucle locale, le TLS et les sockets UNIX toujours. Un écouteur activé par socket (SERVE = systemd) n’est admis qu’avec TLS, car l’adresse du descripteur hérité n’est pas visible du serveur. Un écouteur marqué qui échoue au test journalise un avertissement au démarrage et ne sert que les points de terminaison publics ; pepsi-setup rapporte la même chose lorsqu’il valide la configuration, de sorte que l’erreur soit attrapée avant d’avoir de l’importance.
Note
Un seul binaire sert les deux publics. Il n’y a pas de démon d’administration distinct, donc une seule chose à construire, empaqueter, superviser et tenir synchronisée. En contrepartie, un bogue dans le processus serveur partagé est un bogue dans les deux surfaces. L’isolation est donc à la charge de l’opérateur. Liez l’écouteur d’administration à une socket UNIX ou au loopback, et placez un proxy inverse devant lui s’il doit être joignable d’ailleurs.
Note
Ce que l’on croit d’un serveur frontal. Dans cette topologie, ce processus ne termine aucun TLS et ne voit aucune adresse cliente : il lit donc deux en-têtes posés par le serveur frontal. X-Forwarded-Proto décide si le cookie de session part avec l’attribut Secure (et sous son nom __Host-), et l’élément le plus à droite de X-Forwarded-For est ce sur quoi s’indexent les limitations de débit et ce que le portail à lien sécurisé note comme pair d’une tentative d’accès. Les deux ne sont lus que sur une connexion qui ne peut pas venir de l’extérieur de cet hôte (une socket UNIX, ou un pair TCP en loopback), de sorte qu’un client parlant directement à un écouteur public ne puisse jamais affirmer ni l’un ni l’autre. Les sites de proxy qu’écrit pepsi-setup posent les deux. Sans eux, un déploiement derrière un proxy a des cookies sans attribut Secure et un unique seau de limitation de débit partagé par l’internet entier.
24.2. Authentification¶
Il y a trois mécanismes et un seul modèle d’identité. Un identifiant explicitement présenté l’emporte toujours : l’en-tête Authorization est essayé en premier, puis le cookie de session, et SO_PEERCRED seulement lorsque ni l’un ni l’autre n’est présent. Cet ordre importe : si peercred l’emportait, un administrateur présentant délibérément un jeton à portée étroite sur la socket locale retrouverait silencieusement toute l’autorité.
24.2.1. Administrateurs locaux (SO_PEERCRED)¶
Un processus qui se connecte sur un écouteur à socket UNIX est identifié par les identifiants que le noyau a enregistrés à l’appel connect(2), et que le pair ne peut pas falsifier. root, ou un membre de [pepsi-admin] ADMIN_GROUP (pepsi-admin par défaut), est un administrateur sans identifiant à configurer, stocker ou perdre :
# curl --unix-socket /run/pepsi/admin.sock http://localhost/api/v1/status
C’est ainsi que fonctionne l’amorçage initial sur un système qui n’a encore aucun compte, et c’est pourquoi la socket peut être en mode 0660 avec un groupe sans danger : l’identité vient du noyau, non du mode du fichier.
24.2.2. Jetons porteurs¶
Pour l’automatisation. Un jeton est frappé via l’API et affiché exactement une fois :
# curl --unix-socket /run/pepsi/admin.sock -X POST \
-H 'Content-Type: application/json' \
-d '{"label":"monitoring","scopes":["queue:read","logs:read"]}' \
http://localhost/api/v1/tokens
La forme présentée est pepsi_<id>.<secret>. Seul le SHA-256 de la moitié secrète est stocké, de sorte qu’un jeton ne puisse être réaffiché ni récupéré depuis une sauvegarde de base ; la moitié identifiante est un sélecteur public qui indexe la table, ce qui permet à la comparaison d’être une vérification à temps constant sur une seule ligne plutôt qu’un parcours. La moitié secrète est aléatoire, non dérivée de quoi que ce soit de devinable : elle n’a donc besoin ni de sel ni de hachage lent (voir Devinette hors ligne de hachages de mots de passe faibles, de phrases de passe de clés et de clés dérivées).
Présentez-le sous la forme Authorization: Bearer pepsi_<id>.<secret>. C’est le schéma Bearer de la RFC 6750, porté dans le champ Authorization que définit la RFC 9110 §11.6.2. Les noms de schéma ne distinguent pas la casse (RFC 7235 §2.1), de sorte que bearer et BEARER soient également acceptés. Les jetons peuvent porter une expiration (expires_in_days) et sont révoqués en les supprimant.
Le jeton n’est pas un jeton d’accès OAuth 2.0 (RFC 6749) et il n’y a pas de serveur d’autorisation : c’est un identifiant frappé localement qui se trouve employer la même forme sur le fil. Pepsi parle bel et bien OAuth 2.0 ailleurs, vers un smarthost (voir pepsi-helper-token-refresh), et il ne faut pas confondre les deux.
24.2.3. Mots de passe et sessions¶
Pour un navigateur. Les comptes vivent dans pepsi.admin_account avec des condensats de mot de passe Argon2id (RFC 9106) salés, pour empêcher les devinettes précalculées et rapides hors ligne (voir Devinette hors ligne de hachages de mots de passe faibles, de phrases de passe de clés et de clés dérivées et Devinette hors ligne de hachages de mots de passe faibles, de phrases de passe de clés et de clés dérivées). POST /api/v1/auth/login échange un nom et un mot de passe contre un cookie de session (RFC 6265) plus un jeton CSRF ; pour un compte doté d’un second facteur, la requête porte aussi le code courant à six chiffres sous "otp". Chaque requête mutante venue d’une session doit répéter ce jeton dans l’en-tête X-Pepsi-Csrf. Un jeton porteur et un pair local n’ont besoin d’aucun jeton CSRF : ni l’un ni l’autre n’est jamais envoyé par un navigateur pour le compte de quelqu’un d’autre.
Un compte doté d’une clé de sécurité WebAuthn (Clés de sécurité) se connecte en deux temps. Une fois le mot de passe correct, POST /api/v1/auth/login répond 401 avec le code second_factor_required et, dans detail, un challenge à usage unique (base64url, valable cinq minutes), totp (si un code TOTP peut répondre à la place), register (vrai là où REQUIRE_WEBAUTHN couvre le compte et où celui-ci n’a pas encore de clé, de sorte que l’étape est un enregistrement) et webauthn : mode (get ou create), rp_id, credential_ids, algorithms, user_id et user_name — ce qu’un script remet à navigator.credentials. POST /api/v1/auth/login/second-factor prend ensuite {"challenge": …} avec une assertion (credential_id, client_data_json, authenticator_data, signature), un enregistrement (client_data_json, attestation_object, label facultatif) ou otp, chaque champ binaire étant en base64url sans remplissage, et répond comme une connexion terminée. Un mauvais mot de passe reçoit toujours l’uniforme invalid_credentials ; la seconde étape indique forcément à quiconque connaît le mot de passe qu’il était correct.
Le cookie porte HttpOnly, SameSite=Strict et le préfixe de nom __Host-. Ce préfixe est le plus fort des trois : le navigateur refuse le cookie sauf s’il a été posé en HTTPS sans attribut Domain et avec Path=/, de sorte qu’un hôte frère du même domaine enregistrable ne puisse pas planter un cookie de session pour celui-ci. Les jetons de session ne voyagent jamais dans une URL (voir XSS réfléchie et stockée ou injection HTML dans les portails et les courriers d’administration).
Le préfixe et Secure sont une seule décision, et elle suit le schéma du client plutôt que celui de ce processus : un écouteur qui termine lui-même le TLS, ou un écouteur en clair derrière un serveur frontal qui affirme X-Forwarded-Proto: https comme décrit ci-dessus. Sur le chemin d’amorçage local en clair (un écouteur loopback ou UNIX sans serveur frontal), un navigateur refuserait purement et simplement un cookie Secure : aucun des deux n’est donc employé et le cookie s’appelle pepsi_session. Les deux graphies sont acceptées à l’entrée, de sorte qu’ajouter ou retirer un serveur frontal TLS ne déconnecte pas tous les administrateurs.
Ces exigences sont aussi la raison pour laquelle le portail à lien sécurisé, qui partage une origine, ne peut pas employer le même préfixe : __Host- impose Path=/, ce qui enverrait le cookie de session du portail à /metrics, à /resume et au Web Key Directory également. Il conserve son cantonnement par chemin, emploie __Secure- à la place, et rachète ce que le préfixe lui aurait donné en scellant la valeur du cookie sous le poivre du serveur — voir Le portail de repli par lien sécurisé.
Les sessions sont des lignes, non de la mémoire de processus : un redémarrage ne déconnecte donc personne et deux processus serveur s’accordent sur qui est connecté. Elles expirent de deux façons :
un délai d’inactivité (
SESSION_IDLE, 30 minutes par défaut) repoussé à chaque requête, etune durée de vie dure (
SESSION_LIFETIME, 12 heures par défaut) qui n’est jamais prolongée.
Il n’y a pas de « se souvenir de moi ». Cette console peut révoquer une clé, lire qui correspond avec qui et réécrire le pipeline ; un onglet de navigateur oublié ne devrait plus détenir ce pouvoir demain, et un portable volé ne devrait pas être une session d’administration permanente. La politique est abordable parce que les gens qui administrent un déploiement le plus souvent, les opérateurs locaux, ne tapent jamais de mot de passe.
Note
PAM n’est pas pris en charge. Il placerait un chemin d’authentification privilégié et la sémantique des comptes système à l’intérieur de la couche web d’un serveur de courrier, et ferait dépendre la sécurité de l’API d’une configuration d’hôte que Pepsi ne contrôle pas. Un administrateur local n’en a pas besoin ; un administrateur distant reçoit un compte en base de données avec une liste de portées explicite.
24.4. Conventions¶
JSON uniquement. Les requêtes et les réponses sont en
application/json.Une seule forme d’erreur, à chaque échec
{"code": "scope_required", "hint": "this endpoint requires the 'queue:write' scope", "detail": {"scope": "queue:write"}}
codeest un jeton stable sur lequel brancher ;hintest de la prose pour un humain et peut changer ;detailporte des informations supplémentaires structurées lorsqu’il y en a.Des échecs d’authentification uniformes. Un mauvais mot de passe, un compte inconnu et un compte désactivé produisent tous le même
invalid_credentials, et un compte inconnu paie tout de même une vérification de mot de passe : ni le message ni le temps de réponse n’énumèrent donc les comptes.Les défaillances internes ne portent jamais de cause. L’erreur complète va dans le journal du processus ; le client reçoit
internal_error.Les listages répondent
{"items": [...], "total": N, "limit": L, "offset": O}, et toutes entendent la même chose par là. Voir Pagination.Horodatages ISO-8601, avec un décalage.
Pas de barre oblique finale.
24.5. Pagination¶
Treize points de terminaison répondent par l’enveloppe de listage, et les treize se comportent tous à l’identique :
Point d’accès |
Filtres qui s’appliquent aussi à |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
— |
|
|
|
|
|
|
|
— |
|
— |
|
— |
|
— (restreint aux propres tâches de l’appelant sans |
limit vaut par défaut [pepsi-admin] PAGE_LIMIT (100) et est borné à 1–1000 ; offset est borné à une valeur non négative ; une valeur qui n’est pas un nombre donne un 400. L’enveloppe renvoie la fenêtre appliquée, de sorte qu’une requête à limit=100000 revienne en disant "limit": 1000. Les deux entrent dans le SQL, et total est un COUNT(*) sur la même clause WHERE que la page, jamais la longueur d”items, et jamais la taille d’une fenêtre surdimensionnée. Chaque listage trie en dernier ressort sur quelque chose d’unique (son identifiant de ligne), de sorte qu’un OFFSET ne puisse ni sauter une ligne ni en montrer une deux fois.
GET /api/v1/mail-log ajoute un membre à l’enveloppe, mode, parce qu’une page vide ne signifie pas la même chose selon que [pepsi] MAIL_LOG enregistre quoi que ce soit ou non. GET /api/v1/quarantine ajoute stages, les étapes qui exécutent pepsi-stage-quarantine(1), pour la même raison : s’il n’y en a aucune, rien ne peut être retenu.
24.5.1. total et la page sont deux requêtes¶
Le compte s’exécute d’abord, puis la page, et rien ne maintient d’instantané entre les deux. Une transaction en lecture seule par listage les rendrait exactement cohérents, au prix d’immobiliser une connexion de base de données mutualisée dans une couche web pour une garantie dont aucun client n’a besoin. Donc, face à une table écrite en parallèle :
les lignes supprimées entre-temps font de
totalune surestimation. La file est vidée en continu, c’est donc là le cas normal, non une curiosité. L’effet visible est une dernière page qui revient vide.les lignes insérées entre-temps en font une sous-estimation.
Paginez jusqu’à ce qu”items soit plus court que limit ; traitez total comme un bon nombre à montrer à un opérateur, non comme une borne de boucle à croire à la ligne près.
Le compte est un véritable COUNT(*), non une estimation, sur chacune de ces tables. C’est abordable en raison de ce qu’elles sont. pepsi.workqueue est l”arriéré vivant : la ligne d’un message remis est supprimée par l’étape qui l’a remis, de sorte que la table contient le courrier encore en vol plutôt qu’un historique de tout ce qui a jamais été envoyé. Le magasin de clés, les comptes et les jetons sont des objets à l’échelle du déploiement. event_log et mail_log sont les deux qui grandissent avec le trafic ; toutes deux sont bornées par les balayages de rétention décrits sous Le journal d’audit et Le journal de courrier (désactivé par défaut).
24.5.2. Pas cette forme¶
GET /api/v1/status prend un limit (combien de messages bloqués le rapport liste) mais pas d”offset, et répond le rapport de pepsi-status plutôt qu’un listage. GET /api/v1/tls-sessions répond {"days": D, "items": [...]}, borné par le paramètre days (1–365, valeur par défaut venue de pepsi-status) ; il renvoie la fenêtre qu’il a appliquée, comme l’enveloppe de listage renvoie limit/offset. GET /api/v1/dns-cache répond un simple {"items": [...]}, borné seulement par la taille du cache d’échecs DNS. Les listages de la PKI gérée répondent {"items": [...]} (domaines, utilisateurs) ou {"items": [...], "limit": L} (commandes, et avis avec "unread": N à côté) ; limit vaut par défaut PAGE_LIMIT et au plus 1000, et il n’y a pas d”offset. GET /api/v1/dmarc-reports répond {"days": D, "domains": [...], "items": [...]} : days (1–365, par défaut [pepsi-dmarc-reports] WINDOW_DAYS) est la fenêtre, domains un résumé par domaine de politique avec son verdict (aligned, unaligned ou no-reports, d’après les seuls rapports authentifiés), et items les sources, les non alignées d’abord, au plus limit.
24.6. Points de terminaison¶
La liste faisant autorité pour une compilation donnée est GET /api/v1/openapi.json, engendré depuis la table de routes propre au serveur, y compris les paramètres limit et offset, qu’il déclare exactement sur les points de terminaison listés sous Pagination. La colonne Notes ci-dessous donne les autres paramètres de chaque listage ; tout listage prend en outre ?limit= et ?offset=.
Méthode |
Chemin |
Portée |
Notes |
|---|---|---|---|
|
|
— |
Renvoie un cookie de session et un jeton CSRF. |
|
|
— |
La seconde étape d’une connexion qui a répondu |
|
|
— |
Les propres clés de sécurité de la session appelante (jamais leurs clés publiques). En enregistrer une ou en supprimer une exige un navigateur et se fait sur la page Clés de sécurité de la console. |
|
|
— |
Idempotent. |
|
|
— |
La première chose à vérifier quand quelque chose répond |
|
|
|
Les condensats de mot de passe ne sont jamais renvoyés. |
|
|
|
Supprimer un compte met fin à ses sessions. |
|
|
|
Les clés de sécurité d’un compte ; |
|
|
|
Le secret est dans la réponse au |
|
|
|
Révocation. |
|
|
|
Identique à |
|
|
|
|
|
|
|
Enveloppe, étape, statut et |
|
|
|
De nouveau en attente à son étape courante. |
|
|
|
Corps |
|
|
|
Supprime le message. |
|
|
|
Le journal d’audit. |
|
|
|
|
|
|
|
|
|
|
|
Adresses MX actuellement en échec. |
|
|
|
|
|
|
|
|
|
|
|
Les triplets expéditeur, destinataire et client, les plus récents d’abord. |
|
|
|
Les règles qui n’ont pas expiré ; en ajouter ou en renouveler une. |
|
|
|
Retirer une règle. |
|
|
|
Mettre un expéditeur sur la liste blanche propre à une adresse (pas une règle). |
|
|
|
Les messages aux étapes de quarantaine. Voir Quarantaine. |
|
|
|
Un message retenu : enveloppe et enregistrement de quarantaine, jamais son contenu. |
|
|
|
Faire suivre un message retenu vers son |
|
|
|
Supprimer un message à une étape de quarantaine sans le remettre. |
|
|
|
|
|
|
|
Une section. |
|
|
|
Validé avant d’être stocké. Voir ci-dessous. |
|
|
|
Essai à blanc ; répond |
|
|
|
|
|
|
|
|
|
|
|
La moitié publique, en base64. |
|
|
|
Met en file une tâche |
|
|
|
Met en file une tâche |
|
|
|
Met en file une tâche |
|
|
|
Met en file une tâche |
|
|
|
Met en file une tâche |
|
|
|
Supprime toutes les clés de sécurité de l’utilisateur final qui se connecte sous cette adresse (jamais à la demande d’un principal |
|
|
|
Supprime toutes les clés de sécurité du compte de membre de liste qui se connecte sous cette adresse vérifiée. |
|
|
|
|
|
|
|
Importer à la main la clé d’un correspondant. Voir ci-dessous. |
|
|
|
Met en file une consultation de découverte ; il ne récupère rien. Voir ci-dessous. |
|
|
|
Oublier une clé en cache. |
|
|
|
Fait expirer une clé en cache et met en file une nouvelle recherche pour son adresse. Voir plus bas. |
|
|
|
|
|
|
|
L’état public du démon de signature DKIM. La rotation se fait par une tâche de configuration |
|
|
|
Les ancres de confiance S/MIME. |
|
|
|
Ajoute une ancre de confiance : |
|
|
|
Change quelles signatures entrantes se valident. |
|
|
|
Définit ou lève la portée de l’ancre : |
|
|
|
Les domaines de la PKI gérée et leurs réglages. Voir PKI gérée. |
|
|
|
Les réglages d’un domaine. |
|
|
|
Crée ou modifie les réglages d’un domaine. Décide de ce que l’AC facture à l’organisation. |
|
|
|
|
|
|
|
Ajoute un utilisateur sous un nom dont l’appelant se porte garant. |
|
|
|
Corrige ou approuve le nom d’un utilisateur, le sélectionne ou l’exclut. |
|
|
|
Supprime un utilisateur ; ses certificats sont révoqués. |
|
|
|
|
|
|
|
|
|
|
|
Marque des avis comme lus, pour chaque administrateur. |
|
|
|
Messages à lien sécurisé en attente, métadonnées seulement. |
|
|
|
Un message avec son historique d’accès. Jamais son contenu. |
|
|
|
Révoquer ; ceci détruit l’unique copie du message. |
|
|
|
Les enregistrements à publier et le dernier verdict en service. Voir ci-dessous. |
|
|
|
Le questionnaire de configuration initiale sous forme de données. |
|
|
|
Indique si l’activation de la télémétrie de fonctionnalités pourrait prendre effet et, sinon, ce qu’il faut faire sur le serveur. Voir plus bas. |
|
|
|
Les réponses en attente ; identifiants masqués. |
|
|
|
Fusionner des réponses dans le jeu en attente (brouillon). |
|
|
|
Abandonner le questionnaire en attente. |
|
|
|
Tâches de configuration privilégiées, les plus récentes d’abord ; sans |
|
|
|
Demander à l’applicateur l’une de ses actions issues d’un ensemble fermé. |
|
|
|
Une tâche, avec |
|
|
|
Vérifier l’environnement (ports, DNSSEC du résolveur). |
|
|
|
Comparer le DNS en service à ce que la configuration publierait. |
|
|
|
Obtenir les certificats dont la configuration a besoin. |
|
|
— |
Engendré depuis la table de routes. |
Les points de terminaison de supervision appellent les fonctions propres de pepsi-status et de pepsi-queue et sérialisent les mêmes structures, de sorte que pepsi-status --json et GET /api/v1/status soient les mêmes octets par construction. Les points de terminaison de configuration réemploient le parcours de provenance de pepsi-config et sa validation.
24.7. Ce que ce serveur ne peut pas faire¶
24.7.1. Engendrer ou révoquer du matériel de clé – il le demande à l’applicateur¶
Le matériel de clé privée vit dans crypto_identity.private_wrapped, que pepsi-setup accorde au rôle pepsi-crypto seul (le propriétaire du schéma mis à part) et révoque à tout compte de service, pepsi-httpd compris : une couche web capable de frapper des clés de signature les frappe pour quiconque la compromet.
POST /api/v1/identities n’engendre donc rien. Il met en file une tâche generate-identity ({"address": ..., "vks": true|false} ; vks est facultatif et vaut par défaut [pepsi-keys] VKS_PUBLISH) et répond avec la tâche ({"task": ..., "kind": "generate-identity", "applier_notified": ...}). L’applicateur root la revalide et engendre une clé OpenPGP en tant que rôle pepsi-crypto. La génération sur demande est toujours permise, même à côté de la propre clé de l’utilisateur.
POST /api/v1/identities/client met en file une tâche register-client-key de la même façon ({"address": ..., "key": ...}, la clé étant une clé publique OpenPGP en armure d’au plus 64 Kio). Elle passe par l’applicateur bien qu’aucun matériel privé ne soit en jeu, car le MTA fait confiance à une clé enregistrée comme étant celle de l’utilisateur : elle devient la face publique de l’adresse, et les signatures faites avec elle se vérifient comme étant celles de l’utilisateur. Une couche web compromise ne doit donc pas pouvoir en planter une. L’applicateur exige un certificat OpenPGP dont les User IDs nomment l’adresse, et n’enregistre pas une empreinte que l’adresse possède déjà, retirée ou non. Cela limite l’enregistrement de la clé de quelqu’un d’autre comme la sienne ; la vérification lit les User IDs sans exiger leurs auto-signatures, elle ne l’exclut donc pas (voir Clés et certificats importés ou considérés comme de confiance sans vérification).
PATCH /api/v1/identities/{id} avec {"status": "revoked"} (et un "revocation_reason" facultatif, une ligne d’au plus 1024 octets) est asynchrone pour la même raison : révoquer une clé de signature seule détruit sa moitié privée, et cet UPDATE nomme private_wrapped, ce que pepsi-httpd n’a pas le droit de faire. Il met en file une tâche revoke-identity ({"address": ..., "identity_id": ..., "reason": ...}) et répond avec la tâche, non avec la ligne modifiée : {"identity_id": ..., "task": ..., "kind": "revoke-identity", "applier_notified": ...}. Le status de l’identité se lit revoked une fois que l’applicateur s’est exécuté. GET /api/v1/setup/tasks/{task} montre la tâche elle-même, à setup:write comme au principal qui l’a demandée. Le result de la tâche nomme l’empreinte, dit si l’identité a été révoquée par cette tâche ou l’était déjà, et dit ce qui a été publié : un certificat de révocation signé par la clé tant que sa moitié privée existait encore (revocation_certificate), servi par le Web Key Directory (wkd_serves_revocation) et à envoyer au serveur de clés sur lequel la clé avait été téléversée (key_server_upload_due), avec les mêmes phrases dans published. L’applicateur vérifie que l’identité appartient à l’adresse de la tâche puis applique la même règle que pepsi-keys identity revoke : la moitié privée d’une clé de signature seule est détruite, celle d’une clé de chiffrement est conservée afin que le courrier déjà chiffré pour elle reste lisible. Comme la réponse est une tâche, un PATCH de révocation porte status seul ; combiné à is_primary, published ou vks_wanted, il est refusé avec 400, de même qu’un revocation_reason sans status.
Les changements de drapeaux d’un propriétaire sont eux aussi demandés. Sous own:<address> (sans keys:write), un PATCH qui pose is_primary, published ou vks_wanted ne change rien par lui-même : il met en file une tâche set-identity-flags ({"address": ..., "identity_id": ..., "published": ..., "otp": ...}, avec les drapeaux nommés) et répond 202 Accepted avec {"identity_id": ..., "task": ..., "kind": "set-identity-flags", "applier_notified": ...}. Quelle clé est donnée aux correspondants et si elle est publiée sont des changements des clés du propriétaire comme les autres ; ils exigent donc le second facteur du propriétaire, que seul l’applicateur peut vérifier ; l’applicateur vérifie aussi que l’identité appartient à l’adresse de la tâche et enregistre key.identity.update. Un opérateur détenant keys:write pose les drapeaux directement et reçoit 200 avec les champs modifiés.
Pour les quatre, la barrière d’autorisation de l’applicateur est keys:write, ou own:<address> pour exactement l’adresse des paramètres de la tâche (setup:write seul ne suffit pas, puisque gérer la clé d’un utilisateur n’est pas configurer le serveur), et l’adresse doit appartenir à un domaine de [pepsi-ingress] ACCEPTED_DOMAINS. Une tâche peut se terminer done, failed (l’applicateur a essayé et n’a pas pu, la raison dans error) ou refused (l’applicateur n’a pas du tout accepté la ligne), et le principal qui l’a demandée peut lire laquelle : une demande de révocation pour une clé compromise se suit avec GET /api/v1/setup/tasks/{task}?wait=60 jusqu’à ce que status soit l’un des trois, comme le décrit Suivre une tâche. Sans pepsi-httpd-admin, les quatre répondent 503 setup_applier_unavailable, comme tout chemin passant par l’applicateur, et sans connexion [pepsi-admin] CONFIG_DB, 503 setup_write_unavailable (voir Configuration en ligne : seul le rôle pepsi-config peut mettre en file). Produire une CSR et installer un certificat émis (tâches identity-csr et identity-certificate) se demandent, se contrôlent et reçoivent une réponse de la même manière.
Le second facteur du propriétaire. Une adresse dont le propriétaire a enrôlé un second facteur (Gestion des clés, « Un second facteur pour les modifications de clés ») exige son code courant pour chacune de ces tâches lorsqu’elle est demandée sous own:<address> : ajoutez "otp": "123456" au corps (les formulaires de la console ont un champ pour cela). pepsi-httpd ne peut pas vérifier le code (pepsi.otp_key est accordée à pepsi-crypto seul), il est donc transporté dans les paramètres de la tâche et l’applicateur le vérifie avant d’agir ; un code manquant, erroné, rejoué ou verrouillé fait échouer la tâche avec la raison dans error. Une tâche demandée avec keys:write n’est pas soumise au contrôle du second facteur : l’opérateur peut de toute façon réinitialiser le second facteur. DELETE /api/v1/otp/{address} (keys:write uniquement, jamais own:) met en file une tâche reset-otp qui supprime le second facteur de l’adresse, la déverrouillant ; son propriétaire s’enrôle alors de nouveau. Les changements de drapeaux d’un propriétaire sont soumis au même contrôle du second facteur, car sous own:<address> ce sont aussi des tâches (voir Contournement de l’authentification dans les interfaces web des passerelles, des listes et des portails).
24.7.2. Écrire la configuration, sauf si vous le demandez¶
Écrire pepsi.config_override appartient au rôle de base de données pepsi-config, que pepsi-setup accorde et révoque explicitement à chaque compte de service : un composant qui traite du courrier ne doit pas pouvoir réécrire le pipeline dans lequel il s’exécute. pepsi-httpd est un tel compte, et l’authentification par pair se fonde sur l’uid effectif : sa propre connexion ne peut donc pas être ce rôle. config:write n’en est pas moins une portée puissante : la surcouche recâble le pipeline (quelles étapes s’exécutent, dans quel ordre, avec quelles options), même si elle ne peut jamais nommer un exécutable (voir plus bas et Injection de commandes et XXE dans les interfaces de gestion des passerelles de messagerie).
PUT et DELETE sur /api/v1/config répondent donc 503 config_write_unavailable tant que [pepsi-admin] CONFIG_DB ne nomme pas une connexion qui s’authentifie comme pepsi-config. En pratique, c’est un mot de passe dans un fragment secrets.d lisible par pepsi-httpd seul, ou une correspondance pg_ident. Le serveur vérifie avec SELECT current_user au démarrage et refuse toute autre chose.
PUT prend {"value": "...", "scope": "..."}, où scope vaut global (par défaut), domain:<domain> ou address:<address> ; DELETE prend la même chose sous forme de ?scope=, et GET lit la configuration effective telle que vue depuis cette portée. Les deux écritures répondent avec un objet reload indiquant comment le changement prend effet (hot, restart avec l’unité à redémarrer, ou ini-only).
Les sections qui ne sont lues que depuis le fichier de configuration ([pepsi], [pepsi-postgres], [paths], [pepsi-admin], [pepsi-httpd], [pepsi-crypto], [pepsi-srs], [pepsi-origin], [pepsi-secure-link], [pepsi-wizard], et chaque section [pepsi-httpd-listener-*], [pepsi-httpd-cert-*] et [pepsi-ingress-listener-*]) sont refusées avec 403 forbidden quoi qu’il arrive. De même pour toute option porteuse d’identifiants dans n’importe quelle autre section, c’est-à-dire une option dont le nom comporte, parmi les mots que séparent ses tirets bas, PASS, PASSWORD, PASSPHRASE, SECRET, TOKEN, CREDENTIAL(S), CLIENT_ID, PEPPER ou SYSTEM_ID (API_PASS, KEY_WRAP_SECRET, mais pas SECRETARY). C’est la même règle qui masque une telle option dans GET, et elle couvre aussi le fichier d’où un identifiant est lu et le point de terminaison auquel il est envoyé ; les secrets ne sont jamais stockés dans la base de données. De même pour une option nommant un exécutable (HELPER, SCAN_HELPER, MAILBOX_HELPER, PIN_COMMAND), et pour le PROGRAM d’une étape à moins qu’il ne soit une simple commande pepsi-stage-*. Une portée domain: ou address: n’est acceptée que pour les sections [stage-*], les seules sections lues par correspondant ; toute autre section y est également refusée avec 403. POST /api/v1/config/validate rapporte les mêmes refus sous forme de "valid": false. Le lecteur de la surcouche applique la même règle, de sorte qu’une ligne parvenue dans la table par un autre chemin est ignorée avec un avertissement.
24.7.3. Faire quoi que ce soit de privilégié¶
La configuration initiale écrit /etc/pepsi/pepsi.conf, remet chaque fragment secrets.d au seul compte qui le lit, exécute certbot, crée des rôles de base de données et engendre du matériel de clé, le tout en root. pepsi-httpd abandonne ses privilèges avant d’accepter une connexion et ne doit jamais pouvoir les regagner.
Les points de terminaison de configuration initiale n’agissent donc pas. Ils écrivent une ligne d”intention dans pepsi.setup_task, et un programme root distinct, pepsi-setup apply, la vide. On atteint root par une table de base de données, jamais par une socket parlant un protocole. Nous procédons ainsi pour qu’une faille de la couche web ne puisse pas devenir une exécution de commandes en root (voir Injection de commandes et XXE dans les interfaces de gestion des passerelles de messagerie et Des appliances de messagerie stockent des secrets lisibles par tous ou non protégés). pepsi-setup(1), « Le modèle de confiance de l’applicateur », décrit le modèle de confiance complet : la liste fermée de tâches, les deux barrières d’admission, ce qui est délibérément absent, et ce que la conception ne peut pas promettre. C’est une lecture obligatoire avant de déployer la configuration par navigateur.
24.7.4. L’aller-retour du certificat S/MIME – lui aussi demandé à l’applicateur¶
Une identité S/MIME que Pepsi a générée porte un certificat auto-signé ; une AC en émet un de remplacement à partir d’une demande PKCS#10 sur la même clé (l’aller-retour manuel que documente pepsi-keys(1)). Les deux moitiés touchent la clé privée : la demande est signée avec elle, et l’installation d’un certificat la ré-enveloppe, car le blob enveloppé est lié à l’empreinte du certificat. Les deux sont donc des tâches :
POST /api/v1/identities/{id}/csrmet en fileidentity-csr({"display_name": ...}, facultatif, d’au plus 128 octets : leCNdu sujet). Le nom alternatif du sujet est toujours l’adresse propre de l’identité et n’est pas un paramètre, si bien qu’une tâche ne peut pas demander à une AC de certifier une autre boîte aux lettres sur cette clé. L’applicateur signe la demande en tant quepepsi-cryptoet l’enregistre dans le résultat de la tâche souscsr_pem; le principal qui l’a demandée la lit dansGET /api/v1/setup/tasks/{id}(ou sur la page de la tâche dans la console, qui affiche le PEM seul).POST /api/v1/identities/{id}/certificatemet en fileidentity-certificate({"certificate": ...}: du PEM, dont un paquet ne fournit que le premier certificat, ou du DER en base64, d’au plus 64 Kio). L’applicateur refuse un certificat qui n’est pas sur la clé de l’identité (vérifié par rapport à la clé privée ouverte), qui ne nomme pas l’adresse dans sonrfc822Name, qui est un certificat d’AC, auquel manqueemailProtectionou l’usage de clé dont l’objet de l’identité a besoin, ou qui a expiré. Il remplace ensuite la moitié publique, l’empreinte (SHA-256 du nouveau DER, que voient WKD et les correspondants) et l’expiration, ré-enveloppe la clé privée sous la nouvelle empreinte, et enregistrekey.identity.certificate. Installer le certificat déjà en place ne change rien (already_installed).
Les deux sont ouverts au propre principal own:<address> de l’adresse, avec le champ otp et la règle de second facteur des autres tâches de clés, et répondent 400 pour une identité OpenPGP ou pour la propre clé (MUA) d’un utilisateur, qui n’a pas de moitié privée ici. Sans le paquet de l’applicateur, ils répondent 503 comme tout autre chemin passant par l’applicateur.
24.8. Clés de correspondants¶
POST /api/v1/peers stocke à la main la clé publique d’un correspondant ; c’est le frère de pepsi-keys peer import. (La page correspondant de la console de navigateur propose les mêmes formulaires d’import et de recherche et un bouton Revérifier par ligne ; chacun appelle la propre fonction du gestionnaire, si bien que la console ne peut pas accepter ce que l’API refuse.) Le corps nomme l”address, le protocol (openpgp ou smime), le material (en base64, ou du texte blindé/PEM verbatim) et un pin facultatif.
Deux refus importent :
Un matériel qui n’est pas une clé donne un
422 invalid_value. L’entrée OpenPGP passe par l’analyseur durci qu’emploient les méthodes de découverte, qui ne parcourt que le niveau supérieur et rejette un flux portant un paquet compressé ou chiffré : une clé publique transférable n’en contient jamais, et une bombe de compression jointe à un trousseau n’est pas une clé qui vaille la peine d’être détenue.Une clé qui nomme une adresse différente donne un
422 invalid_valuenommant à qui la clé appartient réellement. Classer la clé d’un correspondant sous l’adresse d’un autre égare silencieusement chaque message futur qui lui est destiné. Une clé qui ne nomme aucune adresse est stockée, car le silence ne peut rien contredire, et la réponse le dit dans son champbinding(matched/no-identity).
La ligne est stockée avec source = api, que la règle de conflit classe à côté d’une clé saisie à la main : elle déloge une clé découverte et ne déloge pas une clé épinglée. Une entrée *@domain est refusée ici ; le schéma n’en admet une que pour source = manual, de sorte qu’élargir tout un domaine reste une décision prise à un terminal.
GET /api/v1/peers liste chaque ligne en cache, y compris une ligne révoquée : sa validity se lit revoked et, lorsque pepsi-keydisc l’a retirée d’après la liste de révocation de son émetteur, revoked_at et revoked_reason disent quand et quelle liste. Une telle ligne est affichée, non utilisée : aucune étape ne la reçoit.
POST /api/v1/peers/discover met en file une consultation et rend la main aussitôt. Il ne récupère rien : la découverte parle HTTPS, LDAP et DNS à des hôtes que choisit le domaine du correspondant, et le faire à l’intérieur d’un gestionnaire de demande laisserait un inconnu maintenir ouverte la connexion de ce serveur. C’est pour la même raison que les étapes de chiffrement et de déchiffrement garent un message au lieu de consulter une clé elles-mêmes. Le point de terminaison écrit la même ligne pepsi.key_request qu’écrit une étape lorsqu’elle gare un message, par la même fonction SQL, et un service pepsi-keydisc fait le travail. La réponse apparaît dans GET /api/v1/peers lorsque l’un d’eux l’a stockée. {"force": true} redemande une adresse dont l’entrée négative fraîche du cache dit qu’il n’y a pas de clé. Il répond 501 no_discovery_method lorsque [pepsi-keydiscovery] SOURCES est vide, puisqu’aucun service ne répondrait jamais, et 403 pour une adresse qu’excluent ALLOW_DOMAINS/DENY_DOMAINS.
POST /api/v1/peers/{id}/recheck est la revérification à la demande d’une clé en cache, équivalente à pepsi-keys peer refresh --expire ID suivi d’une recherche forcée. Il efface le refresh_after de la ligne (si bien que le prochain message vers l’adresse récupère à nouveau la clé quoi qu’il arrive par ailleurs) et lève une key_request forcée pour l’adresse par la même fonction, en renvoyant l’issue de la demande, cache_expired: true et les méthodes interrogées. Rien n’est récupéré dans la requête, pour la raison ci-dessus ; une clé plus récente ou révoquée que trouve le service remplace la ligne selon la règle de conflit ordinaire, et une ligne épinglée n’est jamais déplacée. Une ligne *@domain saisie à la main répond 400 : la découverte n’en recherche jamais. Audité sous key.peer.recheck.
24.9. Ancres de confiance¶
POST /api/v1/ca-trust ajoute une ancre de confiance S/MIME. C’est le frère de pepsi-keys ca add, et il passe par le même analyseur, si bien que les deux surfaces acceptent et refusent les mêmes certificats. Le corps porte le certificate (PEM verbatim, ou DER en base64) et un label facultatif d’une ligne d’au plus 128 octets. Seul un certificat d’AC (basicConstraints CA:TRUE) est accepté : une feuille ne pourrait ancrer aucune chaîne, et en stocker une produirait un ensemble d’ancres qui ne valide silencieusement rien ; un certificat présentant un défaut structurel ou une extension critique non reconnue est refusé comme le vérificateur le refuserait. L’appel est idempotent sur le SHA-256 du certificat : en ajouter un déjà présent met à jour son libellé et répond inserted: false. Ajouter une ancre change les signatures entrantes qui se valident ; c’est donc audité sous key.ca.add au niveau warning, comme DELETE /api/v1/ca-trust/{id}. Uniquement du matériel public : le gestionnaire le stocke donc lui-même ; un principal confiné à une adresse est refusé.
La portée d’une ancre est l’ensemble des domaines de messagerie pour lesquels on lui fait confiance, chacun couvrant ses sous-domaines. Elle est donnée sous forme de permitted_domains lors de l’ajout de l’ancre (appliquée à une nouvelle ancre uniquement) et changée avec PUT /api/v1/ca-trust/{id}/scope ({"permitted_domains": [...]}, ou null pour la lever), les frères de pepsi-keys ca add --domain et ca scope. Les domaines sont stockés sous forme de A-labels en minuscules triés ; une liste vide, un point initial ou un nom qui n’est pas un domaine pleinement qualifié répond 422 invalid_value, un identifiant inconnu 404. La validation de chemin applique la portée comme une contrainte de nom de l’ancre de confiance, en plus de celles du certificat lui-même (voir Modèle de sécurité). Audité sous key.ca.scope au niveau warning. GET /api/v1/ca-trust renvoie permitted_domains et constrained (si le certificat porte des nameConstraints) pour chaque ancre.
24.10. PKI gérée¶
Les points de terminaison /api/v1/mpki montrent et modifient la PKI gérée, qui commande auprès d’une AC des certificats S/MIME pour les utilisateurs d’un domaine (voir Gestion des clés et pepsi-keys(1)). Ce sont les frères de pepsi-keys mpki domain et mpki user, et les pages de la console (Certificats gérés) appellent les mêmes fonctions. La lecture exige keys:read ; chaque modification exige keys:write, car les réglages et les utilisateurs décident de ce qui est facturé à l’organisation et du nom que porte un certificat. Un principal confiné à une adresse est refusé sur chacun d’eux. Un corps de requête comportant un champ que le point de terminaison ne connaît pas est refusé (400), puisqu’un réglage mal orthographié et ignoré en silence serait tout de même facturé ; une valeur que la bibliothèque refuse (un algorithme de clé qui n’existe pas, une fenêtre de renouvellement de 0 jour, un seul certificat avec une clé à courbe elliptique) répond 422 invalid_value avec sa phrase d’explication.
PATCH /api/v1/mpki/domains/{domain}crée les réglages du domaine, désactivés, ou les modifie. Chaque champ est facultatif et un champ absent garde sa valeur :enabled,api_url,organization_id,product,validity_years,enrolment,header_names,renew_days,certificates,key_algorithm,daily_limitetnotify_address.nullsignifie, pourorganization_id, la seule organisation du compte, et pournotify_address, aucun courrier. La réponse est le domaine tel qu’il est stocké. Audité sousmpki.domain.set.POST /api/v1/mpki/usersprend{"address": ..., "given_name": ..., "surname": ..., "selection": ...}; les deux noms sont obligatoires, puisque l’appelant s’en porte garant, etselection(default,yesouno) est facultatif. Il fait aussi revenir un utilisateur supprimé. Audité sousmpki.user.add.PATCH /api/v1/mpki/users/{address}prendgiven_nameetsurnameensemble (un nouveau nom, qui est alors confirmé),confirm_name: true(le nom tel qu’il est) etselection;"selection": "no"exclut l’utilisateur et révoque ses certificats.DELETEsupprime l’utilisateur et révoque aussi ses certificats. Un utilisateur qui n’existe pas ou a été supprimé donne un404. Audité sousmpki.user.setetmpki.user.delete, au niveauwarninglorsque des certificats sont révoqués.GET /api/v1/mpki/usersliste chaque utilisateur avecwanted(si les réglages lui donnent un certificat),hold_reason(pourquoi une commande pour lui attendrait) et ses cinq commandes (orders) les plus récentes.GET /api/v1/mpki/ordersne renvoie jamais la clé enveloppée d’une commande, quepepsi-httpdne peut pas lire ;has_keyindique si la commande en a une.POST /api/v1/mpki/notices/readprend{"ids": [...]}ou{"all": true}; l’absence des deux donne un422. Il répond{"marked": N}et est audité sousmpki.notice.read.
Rien ici ne parle à l’AC. Passer, libérer, réessayer et annuler des commandes, ainsi que l’identifiant d’AC, relèvent de pepsi-keys mpki : pepsi-httpd n’a aucun droit d’écriture sur mpki_order et ne peut pas lire le fichier d’identifiant.
24.11. Greylisting¶
Les points de terminaison /api/v1/greylist montrent ce que pepsi-greylist(1) a décidé et modifient ses règles. Ce sont les frères de pepsi-greylist stats, list, rules, allow, deny et unrule, et les pages de greylisting de la console (Greylisting) appellent les mêmes fonctions. La lecture exige logs:read, puisque les triplets consignent qui a écrit à qui ; une règle exige config:write, puisqu’elle décide quel courrier est accepté pour chaque utilisateur. Un principal confiné à une adresse ne lit que les triplets de sa propre adresse et ne peut voir ni les compteurs ni les règles.
GET /api/v1/greylistrépond{"configured": ..., "hours": H, "counts": [{"outcome", "reason", "count"}], "totals": {outcome: n}, "never_retried": N}à partir des compteurs horaires du démon (greylist_stats), si bien qu’il ne parcourt jamais les triplets.never_retriedcompte les premières tentatives dont la fenêtre de réessai s’est achevée dans la période sans aucun réessai. Il ne sonde pas la socket du démon, que le compte de ce serveur n’a peut-être pas le droit d’ouvrir ;pepsi-statusle fait.GET /api/v1/greylist/tripletsprend?state=(all,pending,passed,never-retried),?domain=(le domaine de l’identité du client ou celui de l’expéditeur, ou un parent de l’un ou de l’autre),?ip=(une adresse ou un réseau) et?rcpt=, commepepsi-greylist list; unstateou unipmal formé donne un400.POST /api/v1/greylist/rulesprend{"action": "allow"|"deny", "kind": "ip"|"network"|"domain"|"sender"|"rcpt", "value": ..., "note": ..., "expires_in": "90 days"};noteetexpires_insont facultatifs. La règle est écrite pargreylist_rule_add, qui normalise la valeur et refuse une valeur mal formée (422avec sa phrase) ; la même action, la même nature et la même valeur renouvellent une règle. Il répond{"rule_id": N}. La règle consigneorigin = consoleet l’identité de l’appelant.DELETE /api/v1/greylist/rules/{id}en retire une viagreylist_rule_remove. Audité sousgreylist.rule.addedetgreylist.rule.removed, comme en ligne de commande.POST /api/v1/greylist/allow-senderprend{"sender": ..., "address": ...}. Un principalown:ometaddress(ou nomme la sienne) ;config:writenomme n’importe quelle adresse. L’expéditeur va sur la liste blanche propre à l’adresse : la première liste blanche de l’espace de noms propre à l’utilisateur (<login>/…) parmi celles que consulte leWHITELIST_BYPASSdu démon pour ce destinataire. La ligne est celle qu’écritpepsi-whitelist addpour une adresse (un littéral ancré comparé àFrom:, DKIM exigé), de sorte qu’elle ne compte que pour le courrier que le domaine de l’expéditeur authentifie, et l’étape de liste blanche la lit aussi. Lorsqu’aucune liste blanche de ce genre n’existe (le contournement est désactivé, ou chaque liste blanche qu’il consulte est partagée), la réponse est409 conflict: une liste blanche partagée laisserait passer l’expéditeur pour tout le monde, ce qui est le rôle d’une règle. Il répond{"address", "sender", "whitelist", "added"}(addedvaut false lorsque l’expéditeur y figurait déjà) et est audité souswhitelist.sender.added.
pepsi-httpd peut lire les quatre tables du greylisting et rien de plus : une règle ne change que par les deux fonctions SECURITY DEFINER, et une ligne de liste blanche que par whitelist_add_user_sender, qui construit lui-même le motif à partir d’une seule adresse et refuse un nom de liste blanche à un seul segment (partagée). Le serveur ne peut ni faire passer un triplet ni lire la liste blanche de qui que ce soit.
24.12. Quarantaine¶
Les points de terminaison /api/v1/quarantine listent les messages que retient une étape pepsi-stage-quarantine(1), et en libèrent ou en suppriment un par son jeton, au moyen des fonctions qu’utilise pepsi-queue quarantine. La lecture exige queue:read, l’action queue:write. Chaque élément est ce qu’affiche pepsi-queue quarantine show --json (enveloppe, From:, Subject:, ainsi que since, until, by et reason de l’enregistrement de quarantaine), plus held, qui vaut false tant qu’un worker détient le message ou qu’il attend un réessai. Jamais ses en-têtes ni son corps.
POST /api/v1/quarantine/{token}/releaserend un message retenu à son étape de quarantaine enpending, ce qui le fait suivre vers sonRELEASE_STAGE. Il n’utilise pasworkqueue_resume, qui refuse le courrier retenu, si bien que le jeton du webhook de paiement ne peut pas le libérer. Un message qui n’est pas retenu (paused) donne un404.POST /api/v1/quarantine/{token}/deletesupprime le message, sauf si un worker le détient (409), et consigne la suppression dans le journal de courrier facultatif, comme le faitpepsi-queue quarantine delete.
Les deux répondent {"workqueue_id": N, "token": ...} et sont audités sous queue.quarantine-release et queue.quarantine-delete.
24.13. Clés DKIM¶
GET /api/v1/keys/dkim répond avec ce que le démon de signature pepsi-dkim(1) rapporte dans son fichier d’état public ([pepsi-dkim] PUBLIC_DIR/status.json) : {"file": ..., "status": ..., "error": ...}. status est le document lui-même, ou null tant que le démon ne l’a pas écrit, et error dit pourquoi un fichier existant n’a pas pu être lu. Par domaine de signature, le document liste les générations de clés avec leurs sélecteurs, algorithmes, états (next, current, retiring, retired), enregistrements TXT et l’indication que chaque serveur faisant autorité les sert ou non, ainsi que les changements DNS dus et une rotation en attente du DNS. Ce serveur ne détient aucune clé DKIM et n’en lit aucune : le fichier ne contient que du matériel public. Le point de terminaison est en lecture seule. Une rotation se demande par POST /api/v1/setup/tasks de type dkim-rotate ({"domain": ..., "hard": false}, setup:write), que l’applicateur root exécute en lançant pepsi-dkim rotate, puisque le démon n’accepte de requêtes d’administration que de root et de son propre compte.
24.14. Liens sécurisés¶
GET /api/v1/secure-messages liste les messages que le portail à lien sécurisé conserve : de qui et pour qui ils sont, quand ils ont été créés et quand ils expirent, combien de fois le code PIN a été saisi correctement et à tort, si un verrouillage est en vigueur, et combien d’octets sont stockés. GET /api/v1/secure-messages/{token} y ajoute le journal d’accès : l’horodatage, l’adresse du pair et l’issue de chaque tentative. Il n’y a délibérément ni géolocalisation ni agent utilisateur.
Aucun point de terminaison ne renvoie le message. pepsi-httpd est le portail : c’est donc l’unique rôle de base à qui secure_message.ciphertext est accordé. C’est précisément pour cela que rien sur la surface d’exploitation ne le lit. Les requêtes derrière ces points de terminaison nomment chaque colonne sauf celle-là et ne rapportent que length(ciphertext), de sorte que la propriété soit imposée par le SQL plutôt que par un champ que quelqu’un a pensé à omettre. Le lire n’aiderait d’ailleurs pas : la clé est un Argon2id sur un code PIN que le serveur ne voit jamais, salé par ligne et poivré depuis un fichier que seul le portail lit. Un vidage de la base de données seul ne permet donc aucune devinette de PIN ; avec le poivre en plus, c’est la longueur du PIN qui reste (voir Devinette hors ligne de hachages de mots de passe faibles, de phrases de passe de clés et de clés dérivées).
DELETE /api/v1/secure-messages/{token} révoque. Il supprime la ligne, et avec elle l’unique copie du message, puisqu’il n’y a pas de clé de séquestre et que le portail ne garde pas de seconde copie. Il faut donc secure:write plutôt que secure:read. L’expéditeur renvoie le message si c’était une erreur.
24.15. Enregistrements DNS¶
GET /api/v1/dns-records répond avec les enregistrements que ce déploiement devrait publier, le dernier verdict du DNS en service pour chacun (ok / missing / mismatch / lookup-failed), le remède pour chacun qui est erroné, et le texte de zone qu’afficherait pepsi-setup run.
Il sert une réponse stockée plutôt que d’en calculer une. Dériver ce qui devrait être publié suppose de lire la configuration validée et l’état du démon de signature DKIM, et le comparer suppose d’interroger le DNS. Ce travail revient à pepsi-setup, que ce serveur ne peut pas appeler (la dépendance va déjà dans l’autre sens), et une couche web ne devrait pas en lire les entrées. L’applicateur privilégié le calcule donc dans le cadre d’une tâche run-preflight et le réécrit, et ce point de terminaison le rapporte avec l’heure à laquelle il a été calculé, toujours : un verdict sans âge invite à faire confiance à un verdict périmé. POST /api/v1/setup/dns-check en demande un frais, et exige donc setup:write : regarder ce qui a été trouvé est une lecture, mais demander à un processus root d’aller voir ne l’est pas.
Avant qu’une vérification n’ait été exécutée, la réponse est vide et nomme le point de terminaison qui en exécute une, plutôt qu’une liste vide qui se lirait comme « tout va bien ».
24.16. Configuration en ligne¶
C’est le chemin par navigateur à travers pepsi-setup. Il repose sur deux mécanismes :
Les réponses sont mises en attente, non appliquées. PUT /api/v1/setup/answers fusionne dans un jeu de lignes brouillons de pepsi.config_override, que chaque lecteur de configuration écarte structurellement (WHERE NOT draft). Rien ne prend effet pendant que le questionnaire est en cours, de sorte qu’une session expirant à mi-parcours n’ait pas à moitié configuré un serveur de courrier, et reprendre consiste à relire les brouillons. Les identifiants sont ceux que publie GET /api/v1/setup/questions. Ce sont aussi les clés que lit pepsi-setup --answers et que la section [pepsi-wizard] fait circuler dans les deux sens, de sorte qu’un questionnaire puisse être commencé dans un navigateur et achevé à un terminal.
L’interrupteur de télémétrie n’est proposé que là où il peut prendre effet. [pepsi] SHARE_TELEMETRY se trouve dans le fichier de configuration : il se règle donc comme n’importe quelle autre réponse et est écrit par la tâche write-config de l’applicateur, qui envoie ensuite la notification telemetry_changed (dans les deux sens) afin qu’un pepsi-telemetry-client en cours d’exécution relise le fichier. Ce démon peut tourner alors que la télémétrie est désactivée (dormant, il ne soumet rien), et il tient une ligne de vivacité dans pepsi.telemetry_client indiquant s’il tourne et si un SYSTEM_ID est configuré (un booléen ; la console ne voit jamais l’identifiant). La console ne génère jamais d’identifiant, puisque c’est précisément ce que le consentement explicite exclut ; à moins que le démon ne tourne et n’en possède un, oui ne peut donc pas prendre effet : GET /api/v1/setup/questions marque alors la question "disabled": true avec un disabled_reason qui indique à l’opérateur quoi faire sur le serveur (systemctl enable --now pepsi-telemetry-client.service ; ajouter à [pepsi] SYSTEM_ID = suivi de 64 caractères hexadécimaux), la console l’affiche désactivée, et un oui envoyé malgré tout via PUT /api/v1/setup/answers ou une tâche write-config est refusé avec 409 telemetry_client_not_ready. Désactiver, ou conserver une réponse qui vaut déjà oui, n’est jamais refusé. GET /api/v1/setup/telemetry répond avec le tableau complet :
{"question": "SHARE_TELEMETRY", "sharing": false, "can_enable": true,
"reason": null,
"client": {"running": true, "enabled": false, "submitting": false,
"system_id_configured": true, "detail": null,
"version": "0.1.0", "last_seen": "2026-09-27T10:00:00+00"}}
Les actions sont demandées, non effectuées. POST /api/v1/setup/tasks met en file l’une de seize sortes (write-config, write-secret, obtain-certificate, install-schema, provision-roles, generate-keys, dkim-rotate, run-preflight, generate-identity, register-client-key, revoke-identity, set-identity-flags, reset-otp, confirm-enrolment, identity-csr, identity-certificate) avec des paramètres strictement validés. (Une dix-septième, confirm-login, vérifie le second facteur d’une connexion à la console et n’est mise en file que par le chemin de connexion ; ce point de terminaison la refuse.) Les huit dernières agissent sur une adresse. On les atteint normalement par POST /api/v1/identities, /identities/client, un PATCH /api/v1/identities/{id} de révocation ou de pose de drapeaux, DELETE /api/v1/otp/{address}, POST /api/v1/identities/{id}/csr et POST /api/v1/identities/{id}/certificate, et confirm-enrolment par la connexion par courrier de la console (Se connecter par courrier) ; cette sorte ne fait que vérifier le code de second facteur d’un propriétaire et ne change rien. L’applicateur les autorise par keys:write ou, pour toutes sauf reset-otp, par la portée own: propre à l’adresse, et non par setup:write. Il n’y a pas de sorte « commande arbitraire », et il n’y a aucune sorte redémarrage, rechargement ou arrêt : un changement qui exige le redémarrage d’un composant se termine par l’opérateur le redémarrant, ce que la console dit plutôt que de le cacher. L’applicateur refuse toute autre chose, et chaque refus, succès et échec est un enregistrement d’audit.
La mise en file passe par la connexion [pepsi-admin] CONFIG_DB, exactement comme les écritures de configuration et pour la même raison : seul le rôle pepsi-config peut faire un INSERT dans setup_task, et l’applicateur refuse toute ligne dont le written_by dit autre chose. Sans cette connexion, les points de terminaison de configuration initiale répondent 503 setup_write_unavailable ; le compte propre du serveur ne peut que faire un SELECT sur la file, de sorte que la console puisse observer le travail privilégié sans pouvoir le demander.
GET /api/v1/setup/tasks/{id}?since=<seq> renvoie les lignes de progression que l’applicateur a écrites jusque-là, de sorte qu’une exécution de certbot ou une installation de schéma puisse être observée ligne à ligne sans que l’applicateur ne retienne une connexion HTTP ouverte.
24.16.1. Suivre une tâche¶
Une tâche répond {"id", "kind", "status", "requested_by", "requested_at", "result", "error", "log"} ; status vaut pending ou running jusqu’à ce qu’il prenne l’une des valeurs done, failed ou refused, après quoi l’applicateur n’y écrit plus rien. params n’est jamais renvoyé, puisque le paramètre de l’un des types de tâche est un secret d’authentification.
Qui peut la lire. Un principal détenant setup:write lit toutes les tâches. Tout autre principal authentifié lit les tâches qu’il a lui-même mises en file. En pratique, ce sont les tâches generate-identity, register-client-key, revoke-identity, set-identity-flags, identity-csr et identity-certificate qu’il a mises en file par les points de terminaison de clés, les seules tâches qu’il puisse mettre en file. GET /api/v1/setup/tasks est restreint à celles-ci plutôt que refusé, et GET /api/v1/setup/tasks/{id} répond 404 not_found pour une tâche que quelqu’un d’autre a mise en file, exactement comme pour une tâche qui n’existe pas. Ce qu’une telle tâche montre ne regarde que le demandeur : le type, l’adresse et l’identité qu’elle nommait, l’empreinte de la clé, la demande de certificat qu’il a demandée, et la raison de son échec ou de son refus. Les paramètres (une clé publique enregistrée, un motif de révocation, un certificat émis) ne sont pas renvoyés, et les points de terminaison de clés ne livrent de toute façon rien de privé.
« Mise en file par lui-même » est déterminé par une clé enregistrée avec la tâche, requester_key, et non par requested_by. requested_by (token:<label>, session:<login>, peer:<login>) est ce que la tâche affiche et ce que le journal d’audit enregistre, mais c’est un nom, et les noms sont réutilisés : deux jetons peuvent porter la même étiquette, et un compte supprimé puis recréé sous le même login est un nouveau compte. La clé, elle, n’est jamais réutilisée : token:<selector> pour un jeton porteur (la moitié publique <id> de pepsi_<id>.<secret>, unique parmi les jetons), account:<n> pour une session par mot de passe (le numéro de ligne du compte, que PostgreSQL ne distribue jamais deux fois) et peer:<login> pour un pair local, où le compte système lui-même est le principal. Ainsi, un nouveau jeton étiqueté comme un ancien, ou un compte recréé, ne lit aucune des tâches de son prédécesseur. Une tâche mise en file depuis la ligne de commande (pepsi-setup) enregistre une clé vide, à laquelle aucun principal ne correspond.
Attendre au lieu de redemander. ?wait=<seconds> (au plus 60 ; une valeur supérieure est prise pour 60) retient la réponse jusqu’à ce que la tâche soit terminée ou ait une ligne de progression postérieure à since (0 en son absence), ou jusqu’à l’expiration du délai, selon ce qui survient en premier, puis répond exactement comme sans ce paramètre. Un client qui suit une tâche boucle donc sur ?since=<last seq>&wait=60 : chaque réponse porte les lignes qu’il n’a pas encore vues, et un status qui n’est ni pending ni running termine la boucle. Rien n’interroge la base de données entre-temps. Les écritures de l’applicateur déclenchent deux notifications portant l’identifiant de la tâche : setup_task_progress pour chaque ligne de progression, et setup_task_done lorsque la tâche se termine (voir pepsi-setup). pepsi-httpd maintient une seule connexion d’écoute pour elles, qui réveille chaque requête en attente sur cette tâche. Une requête en attente s’abonne avant de lire la ligne, de sorte qu’une tâche qui se termine entre les deux n’est jamais manquée. Lorsque l’écouteur n’est pas connecté (PostgreSQL redémarré, par exemple), wait rend la main immédiatement, sans jamais bloquer ; l’écouteur se reconnecte de lui-même. Un wait qui n’est pas un nombre entier de secondes donne un 400.
La page de tâche de la console fait la même chose pour un navigateur, sans script : tant qu’une tâche est en attente ou en cours, la page se recharge aussitôt en une requête que le serveur retient jusqu’à 20 secondes, jusqu’à ce qu’il y ait quelque chose de nouveau à afficher, de sorte que le résultat apparaît au moment même où l’applicateur l’enregistre. Les formulaires de clés en libre-service (générer, enregistrer, révoquer) répondent avec cette page pour la tâche qu’ils ont mise en file.
24.17. Durcissement¶
Ce qu’un mot de passe d’administrateur volé ou une couche web compromise donnerait à un attaquant est exposé dans Un administrateur délégué et Un composant compromis ; les droits de base de données qui confinent pepsi-httpd figurent dans La séparation des privilèges.
Limitations de débit, par adresse source (
RATE_LIMIT, 120/minute par défaut) et, sur le chemin de connexion, par compte et par adresse source (LOGIN_RATE_LIMIT, 10/minute par défaut), car beaucoup de mots de passe contre un compte et un mot de passe contre beaucoup de comptes sont des attaques différentes ; et un plafond quotidien de connexions échouées par compte, toutes sources confondues (LOGIN_DAILY_LIMIT, 100 par défaut), au-delà duquel les connexions par mot de passe du compte reçoivent429jusqu’à ce que l’allocation se reconstitue. L”« adresse source » est celle du client, prise dansX-Forwarded-Forlorsqu’un serveur frontal local de confiance en affirme une ; un appelant sur socket UNIX sans une telle affirmation n’a pas d’adresse, et tout l’hôte partage une seule clé.Plafonds de corps (
MAX_BODY, 1 Mio par défaut), et un délai de 30 secondes sur chaque corps de requête une fois ses en-têtes arrivés (les en-têtes ont leurs propres 30 secondes, de même qu’une poignée de main TLS), si bien qu’un client qui envoie des octets au compte-gouttes ne peut pas monopoliser un emplacement de connexion.Vérifications de mot de passe bornées. Chaque vérification Argon2id s’exécute hors de l’exécuteur des requêtes, au plus une par CPU à la fois ; une connexion qui ne trouve aucun créneau libre en cinq secondes reçoit
429sans que rien ne soit testé. Un compte inconnu est vérifié contre un hachage factice, si bien que le temps de réponse ne permet pas non plus d’énumérer les comptes.Limites de connexions pour l’ensemble du serveur, dans
[pepsi-httpd]:MAX_CONNECTIONS(256 par défaut) etMAX_CONNECTIONS_PER_IP(32 par défaut, par adresse IPv4 ou/64IPv6 ; les connexions sur socket UNIX d’un proxy inverse ne sont pas comptées). Les valeurs sont récapitulées dans Disponibilité.Comparaison à temps constant de chaque jeton et de chaque condensat CSRF.
Aucun secret n’est jamais renvoyé par
GET /api/v1/config: une valeur qui pourrait en être un est remplacée par"***"avec"secret": true. Le masquage est délibérément généreux : une valeur masquée à tort coûte un coup d’œil dans le fichier, alors qu’une valeur montrée à tort est publiée à quiconque détientconfig:read.Aucun contenu de message n’est atteignable. Les points de terminaison de la file répondent l’enveloppe, l’étape, le statut et le JSON
state, jamaisheadersnibody. Lire du courrier n’est pas une fonction d’administration.Les réponses portent
Cache-Control: no-store,X-Content-Type-Options: nosniffet une politiqueframe-ancestors 'none'.
24.18. Le journal d’audit¶
Chaque changement de configuration, opération de clé, connexion, connexion en échec, modification de compte et de jeton, et action d’administration sur la file est consignée dans pepsi.event_log et lisible par GET /api/v1/events :
event_id at actor kind subject severity detail
actor nomme le principal (peer:root, token:monitoring, session:alice) ou, pour un changement fait à un terminal, le login appelant (cli:alice). Les outils en ligne de commande de l’opérateur écrivent dans le même journal, de sorte qu’il soit complet quelle que soit la surface qui a agi ; un journal qui ne remarquerait que ce qui s’est passé en HTTP inviterait à tirer la mauvaise conclusion d’une absence.
Le journal est en ajout seul pour tout ce qui traite du courrier : pepsi-setup accorde à ces rôles INSERT et SELECT et révoque UPDATE/DELETE, puis vérifie la révocation face au serveur en service. La rétention est bornée par [pepsi-admin] EVENT_RETENTION_DAYS (90 par défaut) et élaguée chaque jour par pepsi-httpd prune, que pepsi-log-prune.timer exécute sous le compte pepsi-httpd, que le serveur web tourne ou non.
Ni une valeur de configuration ni le moindre matériel de clé n’est écrit dans un enregistrement : ce qui a changé est le fait auditable, non ce en quoi cela a changé.
24.19. Le journal de courrier (désactivé par défaut)¶
Avertissement
Activer ``[pepsi] MAIL_LOG`` fait que ce déploiement conserve la trace de qui correspond avec qui. Demandez-vous si vous avez besoin de cette preuve, et si la conserver est licite là où vous opérez, avant de l’activer.
Pepsi supprime la ligne d’un message lorsque le pipeline en a fini avec lui. Il n’y a donc aucun journal de succès par message : un déploiement ordinaire n’accumule pas de trace de la correspondance de ses utilisateurs, et ne peut pas être contraint d’en produire une qu’il n’a pas.
Certains déploiements ont réellement besoin de cette preuve. [pepsi] MAIL_LOG la fournit, comme un acte d’administration aux conséquences énoncées :
offLa valeur par défaut. Rien n’est écrit ;
pepsi.mail_logreste vide.summaryUne ligne au moment où le message quitte le pipeline : l’expéditeur et les destinataires d’enveloppe, la direction (
outboundpour le courrier soumis localement,inboundsinon), l’étape où il s’est arrêté, l’issue, et ce que le pipeline a décidé à son sujet (le verdict d’authentification, la décision spam/payé, tout détail d’échec au saut suivant).fullCe qui précède plus la ligne
Subject:.
Le contenu des messages n’est jamais enregistré, quel que soit le réglage. Les lignes sont lisibles par GET /api/v1/mail-log pour un principal détenant logs:read (ou, pour une adresse, own:<address>), sont en ajout seul pour les comptes traitant du courrier exactement comme le journal d’audit, et sont élaguées après [pepsi-admin] MAIL_LOG_RETENTION_DAYS jours (30 par défaut).
Une ligne est écrite lorsqu’une étape en finit avec un message (completed) et lorsqu’un message échoue définitivement (failed) ; ce sont les deux façons dont il cesse d’avancer. L’écriture voyage sur la même instruction que le terminal qui retire ou fait échouer la ligne, de sorte qu’activer le journal ne coûte aucun aller-retour supplémentaire à la base.
24.20. Amorçage¶
Une installation fraîche n’a aucun compte, et n’en a pas besoin : la socket UNIX plus SO_PEERCRED fonctionne toujours pour un administrateur local. À partir de là,
# curl --unix-socket /run/pepsi/admin.sock -X POST \
-H 'Content-Type: application/json' \
-d '{"login":"alice","password":"…","scopes":["queue:read","queue:write"]}' \
http://localhost/api/v1/accounts
crée le premier compte distant. Un mot de passe de console doit compter au moins douze caractères, ne doit pas figurer sur la liste des mots de passe courants que livre Pepsi (comparaison sans tenir compte de la casse) et ne doit pas contenir le nom du compte ; POST /api/v1/accounts et un PATCH qui pose un mot de passe répondent 400 à tout le reste. Un mot de passe perdu n’est pas un verrouillage : le socket local est toujours là.
Lorsque la socket n’est pas joignable (un opérateur travaillant depuis une autre machine, ou un conteneur sans shell sur l’hôte), pepsi-setup bootstrap, exécuté en root, affiche un jeton porteur qui détient l’ensemble complet des portées d’administrateur, expire dans l’heure, et est accepté exactement une fois : de quoi faire un unique POST /api/v1/accounts.
Il doit détenir cet ensemble plutôt que setup:write seul, car POST /api/v1/accounts refuse d’émettre une portée que l’appelant ne détient pas lui-même. Un jeton limité à setup:write ne pourrait donc créer aucun administrateur, et un compte qu’il aurait créé ne pourrait pas non plus s’élargir ensuite. Ce qui borne cet identifiant, c’est sa durée de vie, son usage unique, et le fait que le prochain pepsi-setup bootstrap le révoque.
Le jeton est à usage unique à cause de l’endroit où il est affiché. Un jeton sur un terminal est dans un tampon de défilement et un jeton dans le journal est lisible par quiconque peut lire le journal, ce qui est d’ordinaire un ensemble de gens plus large que « peut administrer le serveur de courrier ». Il est consommé à la présentation par une mise à jour qu’une seule demande concurrente peut gagner, de sorte qu’un jeton que deux personnes ont lu n’en admette qu’une. Il n’y a pas de compte ni de mot de passe par défaut que l’on oublierait de changer (voir Mots de passe par défaut et secrets applicatifs absents). Seul son condensat est stocké : il ne peut donc pas être récupéré ; relancez la commande, ce qui révoque aussi le précédent.
24.21. La console de navigateur¶
La console d’administration est un client de cette API, monté sous /ui sur les mêmes écouteurs ADMIN = yes, partageant son authentification, ses portées et son journal d’audit. Elle n’ajoute aucune capacité : tout ce qu’elle fait est atteignable ici avec curl. Deux détails du mécanisme de session existent pour elle, et comptent lorsqu’on écrit un autre client :
POST /api/v1/auth/loginrenvoie le jeton CSRF dans le corps de la réponse et le pose comme cookiepepsi_csrf(HttpOnly,SameSite=Strict; nommé__Host-pepsi_csrfchaque fois que le cookie de session porte ce préfixe). Un programme lit le corps ; la console n’a pas d’autre moyen de faire entrer le jeton dans un formulaire, puisque ses pages ne portent aucun script capable d’en lire un dans la page. Aucun des deux emplacements n’est la vérification : la vérification, c’est que le condensat de ce que présente une requête mutante égale celui stocké avec la session.Une requête mutante peut présenter le jeton dans l’en-tête
X-Pepsi-Csrf(ce que fait un programme) ou comme champ de formulaire_csrf(ce que fait un formulaire HTML). Un jeton porteur et un pair de socket UNIX ne se voient demander ni l’un ni l’autre, puisqu’un navigateur ne les envoie jamais pour le compte de quelqu’un d’autre.