Skip to content
← Todas las publicaciones
· Delta1 Labs Audit LogKeyright

Crea un registro de auditoría de licencias a prueba de manipulaciones con encadenamiento de hash

Una guía paso a paso para convertir el registro de auditoría de licencias de Keyright en un log encadenado por hash y a prueba de manipulaciones: cómo cada entrada sella a la anterior, cómo leer y verificar la cadena mediante la API de administración y la CLI, cómo anclar el hash de cabecera para que una eliminación no pueda ocultarse, y el C# que necesitas para demostrar el rastro en CI.

Un registro de auditoría vale tanto como su garantía más débil, y para un sistema de licenciamiento esa garantía suele ser ninguna. La mayoría de los servicios de emisión escriben una fila por operación —clave emitida, asiento reclamado, licencia revocada— y confían en que nadie con acceso reescriba jamás la historia. Pero el rastro de auditoría es precisamente el registro que alguien quiere editar: un revendedor que sobreemitió, un infiltrado que reactivó en silencio una clave revocada, una disputa donde la pregunta es qué hizo realmente el servidor, y cuándo. Si cualquiera puede eliminar o retrodatar una fila sin dejar rastro, el log no prueba nada.

Esta es una guía para cerrar esa brecha. Tomaremos el rastro de auditoría de Keyright y lo haremos a prueba de manipulaciones encadenando cada entrada al hash criptográfico de la anterior. El resultado es un log donde cambiar, reordenar o eliminar cualquier entrada histórica rompe todas las entradas posteriores, y donde puedes demostrar a un tercero que el registro está intacto —sin confiar en el almacenamiento, en el operador ni en el host.

Qué te aporta el encadenamiento de hash

A prueba de manipulaciones no significa a prueba de borrado; el almacenamiento siempre se puede borrar. La propiedad alcanzable es la evidencia de manipulación: cualquier modificación es detectable. El encadenamiento de hash la consigue con una sola regla. Cada entrada de auditoría lleva el hash del hash de la entrada anterior. Como un resumen SHA-256 depende de cada bit de su entrada, el hash de la entrada N se compromete transitivamente con toda la historia previa. Cambia un byte en la entrada 5 y el hash de la entrada 5 cambia, lo que invalida el prevHash almacenado de la entrada 6, lo que cambia el hash de la entrada 6, y así hasta la cabecera. Una sola pasada de verificación sobre la cadena detecta una manipulación en cualquier punto.

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

Paso 1 — Habilita la cadena de auditoría

En tu instancia de Keyright, el rastro de auditoría se escribe para cada operación que cambia de estado por defecto, pero el encadenamiento es opcional para que las implantaciones existentes no se vean obligadas a rehashear su historia al actualizar. Actívalo en keyright.config.json:

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

El genesisLabel se incorpora al hash de la primera entrada, de modo que dos implantaciones distintas que registren operaciones idénticas sigan produciendo cadenas diferentes: liga la cadena a esta instancia. En el siguiente arranque, Keyright sella una entrada génesis (seq: 0) cuyo prevHash son 32 bytes cero, y cada operación posterior se extiende a partir de ahí. Community Edition incluye el escritor encadenado; lo que añaden los planes de pago es el checkpointing firmado, que se trata en el Paso 4.

Paso 2 — Lee la cadena mediante la API de administración

Las entradas se exponen a través de la API de administración en orden de secuencia. Avanza con el cursor after para no tener que extraer nunca el rastro completo de golpe:

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..." }
}

Dos decisiones deliberadas hacen que esto sea seguro de compartir. La entrada lleva solo un payloadHash, no el payload en sí: el detalle completo de la operación (correo del licenciatario, huella de la máquina) permanece tras la frontera de administración, de modo que el registro verificable nunca filtra datos personales. Y la respuesta devuelve la head actual, que es el único valor que necesitas para detectar un ataque de truncamiento: si desaparecen entradas del final, la cabecera que recuerdas dejará de coincidir.

Paso 3 — Verifica la cadena tú mismo

No confíes en que el servidor te diga que la cadena es válida; recómputala. La única sutileza es que el hash debe tomarse sobre una codificación de bytes canónica —los mismos bytes que hasheó el servidor— de modo que el orden y el formato de los campos estén fijados, no al capricho de un serializador JSON. Keyright canoniza cada entrada como campos UTF-8 con prefijo de longitud en un orden fijo, y luego hashea 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 es todo el modelo de seguridad en veinte líneas. Parte de un prevHash en el que ya confías —el bloque cero de génesis la primera vez, o el hash de tu último checkpoint verificado en ejecuciones posteriores— y recómputa el hash de cada entrada a partir de la anterior. La primera entrada cuyo entryHash almacenado no coincida es el punto de manipulación, o el punto donde se eliminó una fila y la secuencia ya no cuadra. Fíjate en los campos con prefijo de longitud: sin ellos, un atacante podría barajar bytes entre actor y action y dejar la concatenación sin cambios.

Paso 4 — Ancla la cabecera para que la eliminación no pueda ocultarse

El encadenamiento de hash detecta ediciones y reordenamientos, pero no el truncamiento de aspecto honesto en el que alguien corta la cola y nadie tiene copia de lo que había allí. La solución es publicar periódicamente el hash de cabecera en un lugar que el operador no pueda reescribir en silencio: un checkpoint. Keyright puede emitir uno de forma programada:

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

Un checkpoint firmado es un registro diminuto —{ seq, entryHash, ts } firmado con tu clave de emisión— que reenvías fuera del sistema: a un almacén separado de solo adición, a un buzón de cumplimiento, a la bandeja de entrada de una contraparte. Una vez que una contraparte posee un checkpoint que dice «a las 10:00 la cabecera estaba en seq 4.210 con hash d55a…», ninguna eliminación posterior puede llevar el rastro por debajo de 4.210 sin contradecir una firma que ya tiene. La cadena prueba la consistencia interna; el checkpoint fija la cadena a un punto en el tiempo de reloj que un externo presenció.

Paso 5 — Verifica en CI, no solo a mano

Convierte la verificación en un paso de build para que una cadena rota falle a gritos en lugar de esperar a una disputa. La CLI extrae el rango, lo recómputa y sale con código distinto de cero en la primera discrepancia:

$ 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

Un rastro manipulado produce lo contrario, nombrando la primera entrada que falla para que sepas exactamente dónde se tocó la historia:

$ 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)

Qué rompe legítimamente una cadena

Una cadena rota no siempre es un ataque, y tratar cada rotura como una brecha enseñará a tu equipo a ignorar la alerta. Vale la pena conocer tres causas benignas. Una migración de esquema que añade un campo a la codificación canónica cambiará cada hash posterior, y por eso inicias un segmento de cadena nuevo en el límite de la migración y haces checkpoint de la cabecera antigua, en lugar de rehashear la historia sobre la marcha. Una restauración desde copia de seguridad que pierde las entradas escritas tras la instantánea es un hueco real, pero esperado; el checkpoint te dice con precisión cuántas entradas te faltan. Y un reloj que salta hacia atrás puede hacer que las marcas de tiempo no sean monótonas sin romper el hash en absoluto: la cadena se compromete con el orden en que escribiste las entradas, no con el tiempo honesto, que es exactamente por lo que la confianza en el reloj de pared vive en el checkpoint firmado y no en el campo ts.

Resumen

El encadenamiento convierte un rastro de auditoría de licencias de un conjunto de filas editables en un registro que se defiende solo. Habilita la cadena en la configuración, lee las entradas y la cabecera mediante la API de administración, recómputa la cadena con un recorrido de veinte líneas sobre una codificación canónica, y ancla la cabecera con checkpoints firmados para que el truncamiento no pueda ocultarse. La recompensa es un rastro que puedes entregar a un auditor, a un socio o a un tribunal y demostrar, desde primeros principios, que no se ha reescrito desde el último momento en que alguien lo presenció.

Prueba Nebula.NET

Endurece tu código .NET en minutos — empieza con la edición gratuita.