Signatures et confiance

Un document qu’un agent suit tient davantage de l’artefact de déploiement que de la page de wiki ; il reçoit donc le même traitement : qui l’a écrit, a-t-il changé, et est-il toujours approuvé.

Ce qui est signé

La publication produit une attestation d’auteur (author attestation) : une signature portant sur les octets tels qu’ils ont été rédigés, qui nomme le document, la version, l’empreinte (digest) et le plafond de capacités dont l’éditeur se porte garant. Une lecture qui résout le document — ses bases, ses inclusions et ses paramètres — peut aussi porter une attestation de livraison (delivery attestation), pour un seul lecteur : une signature portant sur le texte tel qu’il a été envoyé et sur le manifeste de la résolution (l’empreinte du document, chaque dépendance avec laquelle il a été résolu, et l’empreinte du résultat résolu), dans laquelle est incluse la signature de l’auteur. Un consommateur vérifie la livraison, en extrait la signature de l’auteur, et la vérifie elle aussi.

Clés

Les clés publiques d’une organisation se trouvent à instruction://pub/<owner>/keys.json, et les consommateurs les découvrent à partir de la lecture elle-même. Chaque clé est dans l’un de trois états : active (active), retired (retirée) ou revoked (révoquée).

ÉtatSignification
activesigne les nouvelles versions
retiredne signe plus ; les versions passées restent vérifiables
revokedles versions signées avec elle comptent comme non signées ; les consommateurs qui exigent des signatures gardent la version qu’ils avaient

Effectuez la rotation avec instruction keys rotate --org acme. Ne révoquez qu’en cas de compromission : c’est un acte délibéré, et il est irréversible.

Signer avec votre propre clé

La moitié privée ne quitte jamais votre machine ; le registre ne voit jamais que le JWK public.

Shell
instruction keygen --out acme-key.json --kid laptop
instruction keys add acme-key.json --org acme --label "Alice's laptop"
instruction publish <id> --sign-with acme-key.json --message "signed by hand"

Vérifier en tant que consommateur

Shell
instruction watch instruction://acme/runbook@stable \
  --require-signature --publisher https://instruction.md/pub/acme

Épingler l’éditeur est la moitié qui compte. Sans cela, vous vérifiez que quelqu’un a signé le document ; avec cela, vous vérifiez que c’est bien l’éditeur que vous attendiez. Un éditeur non épinglé est un refus, pas un niveau de confiance plus faible.

Retirer une version

instruction revoke <id> <version> retire une version publiée. Les références (refs) doivent d’abord ne plus pointer sur elle. Elle reste lisible lorsqu’on l’épingle, si bien qu’un audit peut encore voir ce qui s’est passé, et elle est marquée, si bien que les consommateurs gardent la version qu’ils avaient plutôt que de l’appliquer.

Ce qu’une signature ne promet pas

Que le document est sûr. Une signature établit la provenance, pas un jugement : elle prouve qui a publié ces octets, et ne dit rien sur le fait que les suivre soit une bonne idée. Les contrôles qui comptent pour cela sont du côté du consommateur : les plafonds de capacités, la relecture avant qu’une référence ne bouge, et une personne qui décide ce qu’un agent est autorisé à suivre.