05 · Custodia de claves y firma#

En una frase, para cualquiera: una clave de firma es como la llave de una caja fuerte: si alguien la copia, ya no sirve de nada cambiar la cerradura de golpe. Este caso hace que la llave entre en una habitación sin ventanas, firme allí dentro, y que no haya ningún camino por donde sacarla.

Estado real: 🟡 building · Carpeta: cases/05-smart-contracts/ · Puerto: 8805

Por qué se realiza este caso#

Casi todos los secretos se pueden rotar barato: cambias la contraseña y sigues. Una clave de firma no. Con ella se han emitido documentos, transacciones o paquetes que otros ya aceptaron como auténticos. Si se filtra, no solo hay que cambiarla: hay que revisar todo lo firmado desde que se filtró, y decidir qué sigue valiendo.

Lo que basta para perderla:

La idea que enseña, y que ningún otro caso enseña#

El secreto entra solo si tres cosas coinciden: el manifiesto de la carga declara que lo necesita, la política autoriza inyectarlo, y el entorno cumple lo que la política exige. Si falla cualquiera de las tres, no se ejecuta: falla cerrada y dice qué faltó.

Y dentro, no hay por dónde sacarla:

• La red es none. No hay socket que abrir.
• La comunicación es por socket Unix, no por puerto: no se alcanza desde

fuera del equipo.

• La clave no aparece en el entorno, ni en los argumentos —que se ven en ps—,

ni en los registros.

• Hay una prueba de exfiltración: un proceso que intenta sacarla y falla, y

ese fallo se comprueba en cada commit.

Casos de uso reales#

• Firmar artefactos de una construcción para que quien los instale pueda

verificarlos.

• Firmar transacciones sin que el servicio que las prepara vea la clave.
• Emitir certificados o credenciales verificables.
• Sellar registros de auditoría para que una alteración posterior se note.
• Firmar la propia evidencia de este proyecto — que es exactamente lo que hace

el formato de evidencia.

Cómo funciona#

flowchart LR
  A["📄 Algo que firmar"] --> S["🧭 Servicio :8805"]
  S -- "socket Unix" --> J
  subgraph J["🔒 Jaula · red none · sin entorno"]
    K["🔑 Clave, inyectada solo si<br/>manifiesto + política + entorno coinciden"]
    F["✍️ Firma Ed25519"]
    K --> F
  end
  J --> R["🧾 Firma + acta"]
  J -. "intento de salida" .-> X["🚫 No hay red que usar"]

La comprobación de tres llaves#

flowchart TB
  A["Petición de firma"] --> B{"¿El manifiesto declara<br/>que necesita el secreto?"}
  B -- no --> N["🚫 No se ejecuta"]
  B -- sí --> C{"¿La política autoriza<br/>inyectar ese secreto?"}
  C -- no --> N
  C -- sí --> D{"¿El entorno cumple lo<br/>que la política exige?"}
  D -- no --> N
  D -- sí --> E["🔑 Se inyecta y se firma dentro"]
  N --> M["📣 Se explica qué faltó"]

Ese «no se ejecuta» es deliberado. La alternativa —ejecutar con menos controles de los pedidos— es la que produce sistemas que parecen seguros.

Esquemas#

Entrada — POST /api/sign#

{ "payload": { "to": "cuenta-b", "amount": 1250, "currency": "CLP" } }

Salida#

{
  "signature": "base64…",
  "algorithm": "ed25519",
  "publicKey": "base64…",
  "keyFingerprint": "sha256:…",
  "signedAt": "2026-08-07T03:00:00Z",
  "controls": { "network": "none", "transport": "unix-socket", "environment": "cleared" }
}

La clave privada no aparece en ningún campo de ninguna respuesta. Lo que sale es la firma, la clave pública y una huella para poder identificar qué clave se usó sin revelarla.

Comprobaciones auxiliares#

Software necesario#

Instalación#

sudo apt install bubblewrap util-linux python3
cargo build --release
cargo run -p sandboxctl -- doctor

La clave de demostración se genera sola la primera vez, en

de versiones y debe seguir estándolo.**

Cómo se ejecuta#

cargo run -p sandboxctl -- service up smart-contracts

Y la verificación de que la evidencia firmada se sostiene:

cargo run -p sandboxctl -- evidence verify

Procesos que se crean#

sandboxctl service up smart-contracts
  │
  ├─ systemd --user scope
  │   └─ bwrap                   ← red none, entorno vacío, sin dispositivos
  │       └─ python3 app.py      ← firma, escuchando en socket Unix
  │
  └─ sandboxctl service forward  ← puente TCP :8805 ↔ socket Unix

Que el transporte sea un socket Unix no es un detalle de implementación: es el control. Un socket Unix vive en el sistema de ficheros, no en la red, así que no se alcanza desde otra máquina ni aunque el equipo esté expuesto.

Tiempo de carga#

Estado real y qué falta#

Construido: la firma Ed25519 dentro de la jaula, la red none, el transporte por socket Unix, la clave con permisos restringidos fuera del repositorio, y la firma de la evidencia del propio proyecto, encadenada y verificable con

Falta, y empieza por dividirlo en dos: este caso mezcla hoy dos ideas distintas. La custodia y la firma se quedan aquí, como

instrucciones, sin reloj, resultados reproducibles— es otra idea y se va al caso 07.

Falta también: límites de monto por firma, política de autorizaciones, rotación y revocación de claves.

Si algo falla#

Los fallos que afectan a cualquier caso —no se puede crear el sandbox, no hay cgroups, un puerto ocupado, procesos huérfanos, la compilación en Windows— están resueltos uno a uno en Cuando algo falla.

Ver también: Catálogo completo · Formato de evidencia · Estado del proyecto