Skip to content
← Tous les articles
· Delta1 Labs Audit LogKeyright

Construire un journal d'audit de licences inviolable par chaînage de hachage

Un guide pas à pas pour transformer la piste d'audit des licences de Keyright en un journal chaîné par hachage et inviolable : comment chaque entrée scelle la précédente, comment lire et vérifier la chaîne via l'API d'administration et la CLI, comment ancrer le hachage de tête pour qu'une suppression ne puisse se cacher, et le C# dont vous avez besoin pour prouver la piste en CI.

Un journal d’audit ne vaut que par sa garantie la plus faible, et pour un système de licences cette garantie n’est généralement aucune. La plupart des services d’émission écrivent une ligne par opération —clé émise, siège réclamé, licence révoquée— et comptent sur le fait que personne, parmi ceux qui y ont accès, ne réécrive jamais l’histoire. Mais la piste d’audit est précisément l’enregistrement que quelqu’un veut modifier : un revendeur qui a surémis, un initié qui a discrètement réactivé une clé révoquée, un litige où la question est ce que le serveur a réellement fait, et quand. Si une partie peut supprimer ou antidater une ligne sans laisser de trace, le journal ne prouve rien.

Voici un guide pour combler cet écart. Nous allons prendre la piste d’audit de Keyright et la rendre inviolable en chaînant chaque entrée au hachage cryptographique de la précédente. Le résultat est un journal où modifier, réordonner ou supprimer n’importe quelle entrée historique casse toutes les entrées suivantes, et où vous pouvez prouver à un tiers que l’enregistrement est intact — sans faire confiance au stockage, à l’opérateur ou à l’hôte.

Ce que le chaînage de hachage vous apporte

Inviolable n’est pas le bon mot ; le stockage peut toujours être effacé. La propriété atteignable est la preuve de falsification : toute modification est détectable. Le chaînage de hachage l’obtient avec une seule règle. Chaque entrée d’audit porte le hachage du hachage de l’entrée précédente. Comme un condensé SHA-256 dépend de chaque bit de son entrée, le hachage de l’entrée N s’engage transitivement sur toute l’histoire qui la précède. Inversez un octet dans l’entrée 5 et le hachage de l’entrée 5 change, ce qui invalide le prevHash stocké de l’entrée 6, ce qui change le hachage de l’entrée 6, et ainsi de suite jusqu’à la tête. Une seule passe de vérification sur la chaîne attrape une falsification où qu’elle soit.

entry 41 prevHash: a7f3… action: key.issued subject: KR-9QX… hash: 3c1b… entry 42 prevHash: 3c1b… action: seat.claimed subject: host-7e2 hash: 8e04… entry 43 prevHash: 8e04… action: license.revoked subject: KR-9QX… hash: d55a… each entry's hash becomes the next entry's prevHash — the chain seals the past

Étape 1 — Activer la chaîne d’audit

Dans votre instance Keyright, la piste d’audit est écrite pour chaque opération qui change l’état par défaut, mais le chaînage est optionnel afin que les déploiements existants ne soient pas contraints de re-hacher leur historique lors d’une mise à jour. Activez-le dans keyright.config.json :

{
  "audit": {
    "chain": {
      "enabled": true,
      "hashAlgorithm": "SHA-256",
      "genesisLabel": "acme-prod-2026"
    }
  }
}

Le genesisLabel est intégré au hachage de la toute première entrée, de sorte que deux déploiements distincts qui enregistreraient des opérations identiques produisent tout de même des chaînes différentes : il lie la chaîne à cette instance. Au démarrage suivant, Keyright scelle une entrée genèse (seq: 0) dont le prevHash est constitué de 32 octets nuls, et chaque opération ultérieure s’étend à partir de là. Community Edition inclut l’écrivain chaîné ; ce que les formules payantes ajoutent, c’est le checkpointing signé, traité à l’étape 4.

Étape 2 — Lire la chaîne via l’API d’administration

Les entrées sont exposées via l’API d’administration dans l’ordre de séquence. Avancez avec le curseur after pour ne jamais avoir à extraire toute la piste d’un coup :

GET /v1/admin/audit?after=40&limit=3 HTTP/1.1
Host: licensing.internal.acme.example
Authorization: Bearer <admin-token>
{
  "entries": [
    {
      "seq": 41,
      "ts": "2026-11-16T09:12:04.118Z",
      "actor": "svc:fulfillment",
      "action": "key.issued",
      "subject": "KR-9QX2-7F3M-...",
      "payloadHash": "sha256:1f0a9c...",
      "prevHash": "sha256:a7f3e2...",
      "entryHash": "sha256:3c1b88..."
    }
  ],
  "head": { "seq": 43, "entryHash": "sha256:d55a10..." }
}

Deux choix délibérés rendent cela sûr à faire circuler. L’entrée ne porte qu’un payloadHash, pas le payload lui-même : le détail complet de l’opération (courriel du licencié, empreinte de la machine) reste derrière la frontière d’administration, de sorte que l’enregistrement vérifiable ne divulgue jamais de données personnelles. Et la réponse renvoie la head courante, qui est la seule valeur dont vous avez besoin pour détecter une attaque par troncature : si des entrées disparaissent de la fin, la tête dont vous vous souvenez ne correspondra plus.

Étape 3 — Vérifier la chaîne vous-même

Ne faites pas confiance au serveur pour vous dire que la chaîne est valide ; recalculez-la. La seule subtilité est que le hachage doit être pris sur un encodage d’octets canonique —les mêmes octets que le serveur a hachés— de sorte que l’ordre et le formatage des champs soient figés, et non laissés au caprice d’un sérialiseur JSON. Keyright canonise chaque entrée en champs UTF-8 préfixés par leur longueur dans un ordre figé, puis hache prevHash ‖ canonicalBytes.

using System.Security.Cryptography;
using System.Text;

static byte[] Canonicalize(AuditEntry e)
{
    // Frozen field order. Each field is length-prefixed so that
    // ("ab","c") and ("a","bc") can never collide.
    using var ms = new MemoryStream();
    void Field(string s)
    {
        var b = Encoding.UTF8.GetBytes(s);
        Span<byte> len = stackalloc byte[4];
        BinaryPrimitives.WriteUInt32BigEndian(len, (uint)b.Length);
        ms.Write(len);
        ms.Write(b);
    }
    Field(e.Seq.ToString(CultureInfo.InvariantCulture));
    Field(e.Ts.ToString("O", CultureInfo.InvariantCulture)); // round-trip ISO-8601
    Field(e.Actor);
    Field(e.Action);
    Field(e.Subject);
    Field(e.PayloadHash);
    return ms.ToArray();
}

static byte[] ComputeHash(byte[] prevHash, AuditEntry e)
{
    using var sha = SHA256.Create();
    sha.TransformBlock(prevHash, 0, prevHash.Length, null, 0);
    var body = Canonicalize(e);
    sha.TransformFinalBlock(body, 0, body.Length);
    return sha.Hash!;
}

// Walk the chain. Returns the seq of the first broken entry, or null if intact.
static long? FindBreak(IReadOnlyList<AuditEntry> entries, byte[] genesisPrev)
{
    var prev = genesisPrev; // 32 zero bytes, or the hash of your last checkpoint
    foreach (var e in entries) // must be contiguous and ascending by seq
    {
        var expected = ComputeHash(prev, e);
        if (!CryptographicOperations.FixedTimeEquals(expected, Convert.FromHexString(e.EntryHash)))
            return e.Seq;
        prev = expected;
    }
    return null;
}

FindBreak est tout le modèle de sécurité en vingt lignes. Partez d’un prevHash auquel vous faites déjà confiance —le bloc nul de genèse la première fois, ou le hachage de votre dernier checkpoint vérifié lors des exécutions suivantes— et recalculez le hachage de chaque entrée à partir de la précédente. La première entrée dont l’entryHash stocké ne correspond pas est le point de falsification, ou le point où une ligne a été supprimée et où la séquence ne colle plus. Remarquez les champs préfixés par leur longueur : sans eux, un attaquant pourrait brasser des octets entre actor et action et laisser la concaténation inchangée.

Étape 4 — Ancrer la tête pour qu’une suppression ne puisse se cacher

Le chaînage de hachage attrape les modifications et les réordonnancements, mais pas la troncature d’apparence honnête où quelqu’un coupe la queue et où personne n’a de copie de ce qui s’y trouvait. La parade est de publier périodiquement le hachage de tête quelque part que l’opérateur ne peut réécrire en silence : un checkpoint. Keyright peut en émettre un de façon planifiée :

{
  "audit": {
    "chain": { "enabled": true },
    "checkpoint": { "everyMinutes": 60, "sign": true }
  }
}

Un checkpoint signé est un enregistrement minuscule —{ seq, entryHash, ts } signé avec votre clé d’émission— que vous transférez hors du système : vers un stockage séparé en ajout seul, une boîte aux lettres de conformité, la boîte de réception d’une contrepartie. Une fois qu’une contrepartie détient un checkpoint disant « à 10 h 00 la tête était à seq 4 210 avec le hachage d55a… », aucune suppression ultérieure ne peut faire descendre la piste sous 4 210 sans contredire une signature qu’elle possède déjà. La chaîne prouve la cohérence interne ; le checkpoint fixe la chaîne à un point du temps horloge qu’un extérieur a constaté.

Étape 5 — Vérifier en CI, pas seulement à la main

Faites de la vérification une étape de build pour qu’une chaîne cassée échoue bruyamment au lieu d’attendre un litige. La CLI extrait la plage, la recalcule et sort avec un code non nul à la première divergence :

$ keyright audit verify --from 0 --to head \
    --expect-checkpoint checkpoints/2026-11-16T10-00.json
Verifying 4211 entries from genesis…
  genesis label: acme-prod-2026
  checkpoint seq 4210 hash d55a10…  OK (signature valid)
Chain intact: 4211/4211 entries, head d55a10… at 2026-11-16T10:00:11Z

Une piste falsifiée produit l’inverse, en nommant la première entrée qui échoue pour que vous sachiez exactement où l’histoire a été touchée :

$ keyright audit verify --from 0 --to head
Chain BROKEN at seq 42: stored hash 8e04a1… != computed 0b7cc9…
  entries 0–41 verify; everything from 42 onward is unprovable
error: audit chain verification failed (exit 2)

Ce qui casse légitimement une chaîne

Une chaîne cassée n’est pas toujours une attaque, et traiter chaque rupture comme une brèche apprendra à votre équipe à ignorer l’alerte. Trois causes bénignes méritent d’être connues. Une migration de schéma qui ajoute un champ à l’encodage canonique changera chaque hachage suivant — c’est pourquoi vous démarrez un nouveau segment de chaîne à la frontière de la migration et faites un checkpoint de l’ancienne tête, plutôt que de re-hacher l’historique sur place. Une restauration depuis une sauvegarde qui perd les entrées écrites après l’instantané est un vrai trou, mais attendu ; le checkpoint vous dit précisément combien d’entrées vous manquent. Et une horloge qui revient en arrière peut rendre les horodatages non monotones sans casser le hachage du tout : la chaîne s’engage sur l’ordre dans lequel vous avez écrit les entrées, pas sur le temps honnête, ce qui est exactement pourquoi la confiance dans l’horloge murale vit dans le checkpoint signé et non dans le champ ts.

Résumé

Le chaînage transforme une piste d’audit de licences d’un ensemble de lignes modifiables en un enregistrement qui se défend lui-même. Activez la chaîne dans la configuration, lisez les entrées et la tête via l’API d’administration, recalculez la chaîne avec un parcours de vingt lignes sur un encodage canonique, et ancrez la tête avec des checkpoints signés pour que la troncature ne puisse se cacher. La récompense est une piste que vous pouvez remettre à un auditeur, à un partenaire ou à un tribunal et prouver, à partir de premiers principes, qu’elle n’a pas été réécrite depuis le dernier moment où quelqu’un l’a constatée.

Essayez Nebula.NET

Renforcez votre code .NET en quelques minutes — commencez avec l'édition gratuite.