|
|
# datekeys-go
|
|
|
|
|
|
Implementación de referencia en Go de la **DateKeys Protocol Specification
|
|
|
v0.9** ([`spec/`](spec/DateKeys_Protocol_Specification_v0.9.md)).
|
|
|
[English version](README.md).
|
|
|
|
|
|
DateKeys cifra datos de forma que solo puedan abrirse a partir de un instante
|
|
|
elegido. La condición temporal procede del beacon de aleatoriedad **Quicknet**
|
|
|
de drand: los datos se sellan con cifrado timelock hacia una ronda futura, y la
|
|
|
firma BLS de esa ronda, que drand publica cuando llega, es la llave. Todo lo que
|
|
|
se puede verificar localmente se verifica localmente; relays, cachés y APIs son
|
|
|
transportes no confiables.
|
|
|
|
|
|
> **Estado: v0.x, pre-estándar.** La especificación es un borrador y la API
|
|
|
> puede cambiar antes de v1.0.0. El código aún no ha pasado una revisión
|
|
|
> criptográfica externa (spec §75). No lo uses para secretos de alto valor.
|
|
|
|
|
|
## Qué implementa
|
|
|
|
|
|
| Objeto | Spec | Paquete |
|
|
|
|---|---|---|
|
|
|
| DateKey: fecha → ronda, cadena canónica `dk1_…` | §14–§19 | [`datekey`](datekey) |
|
|
|
| Provider Profile, perfil Quicknet pinneado, `profile_hash` | §10–§13 | [`profile`](profile) |
|
|
|
| Fuentes de releases, verificación BLS local, relays drand | §45–§52 | [`provider`](provider), [`provider/drand`](provider/drand) |
|
|
|
| DateKeyCap `.dkc`: `time_only` y `time_and_key` | §20–§39, §61–§63 | [`capsule`](capsule) |
|
|
|
| DateKeys Access Key `.dkk` | §40–§44 | [`accesskey`](accesskey) |
|
|
|
| Extensiones | §54 | [`extension`](extension) |
|
|
|
| CBOR determinista | §58 | [`codec`](codec) |
|
|
|
| Errores normativos | §69 | [`errors.go`](errors.go) |
|
|
|
| CLI | — | [`cmd/datekeys`](cmd/datekeys) |
|
|
|
|
|
|
Aquí no se implementa criptografía. El cifrado es [age](https://age-encryption.org)
|
|
|
(`filippo.io/age`); el timelock es [tlock](https://github.com/drand/tlock)
|
|
|
(solo su núcleo exportado); la verificación BLS es la de drand. Este módulo
|
|
|
aporta framing, CBOR, bindings, reglas de verificación y flujo, y aplica las
|
|
|
reglas de stanzas del protocolo dentro de las identities de age, para que un
|
|
|
fichero nunca se acepte solo porque age haya podido desenvolver una clave.
|
|
|
|
|
|
No implementa, a propósito: el servidor y la cola de la Release API, el
|
|
|
almacenamiento y la entrega, extensiones concretas ni el cliente TypeScript
|
|
|
(plan §2).
|
|
|
|
|
|
## Versiones
|
|
|
|
|
|
Hay tres números de versión, cada uno con su significado:
|
|
|
|
|
|
| Versión | Dónde | Cambia cuando |
|
|
|
|---|---|---|
|
|
|
| Formato | Dentro de los objetos: el formato de la cápsula, el `VERSION` del prelude de DKC1, 2 al escribir y 1 o 2 al leer, que es también la versión de schema de CONTROL_CBOR; y 1 en la trama de DKK1 y en el schema de los demás objetos | Cambia el formato. Un lector rechaza una versión que no conoce (spec §22, §70) |
|
|
|
| Especificación | `datekeys.SpecVersion`, hoy `0.9`, y el tag `spec-v0.9` | Cambia el texto normativo. §76 del spec recoge cada cambio con su caso |
|
|
|
| Módulo | Los tags de este módulo Go, `vX.Y.Z`, y `datekeys.Version()` | Cambia la API o el comportamiento. Versionado semántico, sin promesa de estabilidad antes de v1.0.0 |
|
|
|
|
|
|
`datekeys version` imprime la versión del módulo, la del spec y la del toolchain de Go. Un binario compilado en un checkout muestra la pseudo-versión de su commit, por ejemplo `v0.0.0-20260928105528-9ac9cd952f04`.
|
|
|
|
|
|
Cada release dice qué cubre, aquí y en el [CHANGELOG](CHANGELOG.md). El código de `main`, aún sin publicar, cubre:
|
|
|
- la especificación 0.9: escribe el formato 2 de cápsula y lee los formatos 1 y 2;
|
|
|
- el perfil Quicknet pinneado, y cualquier perfil de los tres schemes de drand que soporta tlock;
|
|
|
- cifrado, inspección y apertura, y la CLI;
|
|
|
- todos los vectores y fixtures compartidos de [`testdata/`](testdata).
|
|
|
|
|
|
El primer tag, v0.1.0, llegará cuando `go get` funcione desde una máquina limpia.
|
|
|
|
|
|
## Una cápsula, en un dibujo
|
|
|
|
|
|
```text
|
|
|
.dkc = PRELUDE (16 B) || PUBLIC_HEADER (CBOR) || SEALED_CONTROL (age) || PAYLOAD_AGE (age, hasta EOF)
|
|
|
|
|
|
time_only: SEALED_CONTROL = age(tlock ronda R → CONTROL_CBOR)
|
|
|
time_and_key: SEALED_CONTROL = age(tlock ronda R → age(16 stanzas X25519 → CONTROL_CBOR))
|
|
|
CONTROL_CBOR = { header_binding = SHA-256(PRELUDE || PUBLIC_HEADER), I_PAYLOAD, extensiones, L, regla de relleno }
|
|
|
PAYLOAD_AGE = age(X25519 R_PAYLOAD → tus datos || ceros hasta P = regla(L)), en streaming
|
|
|
```
|
|
|
|
|
|
Es el formato 2, el que escribe `encrypt` (spec §22). Sus 16 stanzas llevan de
|
|
|
1 a 16 credenciales y un señuelo en cada hueco libre, en orden aleatorio, y su
|
|
|
payload se rellena hasta P: hasta la fecha nadie sabe cuántas credenciales hay
|
|
|
ni la longitud exacta L (spec §29.1, §39, §55.2). El formato 1, el de la
|
|
|
v0.8.2, lleva un stanza por credencial y no rellena; los lectores lo siguen
|
|
|
abriendo.
|
|
|
|
|
|
## CLI
|
|
|
|
|
|
```bash
|
|
|
go install g.activething.com/go/DateKeys/cmd/datekeys@latest
|
|
|
```
|
|
|
|
|
|
El módulo se sirve desde el Gitea del proyecto, cuyo certificado Go no
|
|
|
reconoce por defecto. Define `GOPRIVATE=g.activething.com` para que el proxy y
|
|
|
la base de datos de sumas de Go no intervengan, e instala el certificado del
|
|
|
servidor o, en una red de confianza, define `GOINSECURE=g.activething.com`.
|
|
|
|
|
|
```bash
|
|
|
datekeys datekey resolve -at 2030-01-01T00:00:00Z
|
|
|
datekeys encrypt -at 2030-01-01T00:00:00Z -in carta.txt -out carta.dkc
|
|
|
datekeys encrypt -at 2030-01-01T00:00:00Z -policy time_and_key -dkk carta.dkk -in carta.txt -out carta.dkc
|
|
|
datekeys encrypt -at 2030-01-01T00:00:00Z -padding bloque256 -in carta.txt -out carta.dkc
|
|
|
datekeys inspect -in carta.dkc
|
|
|
datekeys decrypt -in carta.dkc -out carta.txt -dkk carta.dkk
|
|
|
datekeys profile hash
|
|
|
datekeys version
|
|
|
```
|
|
|
|
|
|
`encrypt` nunca usa la red. Rellena el contenido con la regla reforzado, o con
|
|
|
bloque256 si se pide (spec §29.1). `inspect` ejecuta solo las comprobaciones
|
|
|
previas al desbloqueo (spec §63, pasos 1 a 8): nunca pide un release ni usa
|
|
|
secretos.
|
|
|
`decrypt` obtiene el release de relays públicos de drand, lo verifica
|
|
|
localmente y publica el plaintext solo cuando age lo ha autenticado entero.
|
|
|
Nunca se sobrescriben ficheros de salida.
|
|
|
|
|
|
## Librería
|
|
|
|
|
|
```go
|
|
|
reg, err := profile.Default() // perfil Quicknet pinneado, comprobado contra su profile_hash
|
|
|
|
|
|
// Cifrar: sin red, la ronda se resuelve localmente. El formato 2 sella la
|
|
|
// longitud del contenido antes que el contenido: src entrega exactamente
|
|
|
// Length bytes.
|
|
|
res, err := capsule.Encrypt(dst, src, capsule.EncryptOptions{
|
|
|
Profile: profile.Quicknet(),
|
|
|
UnlockAt: time.Date(2030, 1, 1, 0, 0, 0, 0, time.UTC),
|
|
|
Policy: capsule.TimeAndKey,
|
|
|
NewPortableKey: true, // res.PortableKey es la .dkk; se codifica con accesskey.Encode
|
|
|
Length: size,
|
|
|
Now: time.Now,
|
|
|
})
|
|
|
|
|
|
// Inspeccionar: pasos 1 a 8, sin red ni secretos.
|
|
|
in, err := capsule.Inspect(f, capsule.InspectOptions{Registry: reg})
|
|
|
|
|
|
// Abrir: pasos 1 a 18; el release se verifica localmente.
|
|
|
opened, err := capsule.Open(ctx, tmp, f, capsule.OpenOptions{
|
|
|
Registry: reg,
|
|
|
Source: drand.New(),
|
|
|
AccessKey: key, // o Identities: []age.Identity{...}
|
|
|
Now: time.Now,
|
|
|
})
|
|
|
if errors.Is(err, datekeys.ErrReleaseUnavailable) { /* todavía no */ }
|
|
|
```
|
|
|
|
|
|
`Open` escribe el contenido en streaming, nunca el relleno; si falla, descarta
|
|
|
lo escrito y no lo presentes como válido (spec §56). `opened.Format` es el
|
|
|
formato de la cápsula: el formato 1 no oculta el número de credenciales ni la
|
|
|
longitud exacta del contenido, así que muéstralo (spec §70). Todo fallo del protocolo envuelve uno de los 17 errores normativos del
|
|
|
§69, así que `errors.Is` y `datekeys.Code(err)` lo identifican.
|
|
|
|
|
|
## Propiedades de seguridad y límites
|
|
|
|
|
|
- **Confidencialidad temporal** bajo el supuesto de umbral de drand. El
|
|
|
timelock de Quicknet **no es post-cuántico**: los ciphertexts guardados
|
|
|
durante años quedan expuestos a *harvest now, decrypt later* (spec §7.7, §53).
|
|
|
- **Sin confianza en servidores**: el perfil va pinneado en el binario, la ronda
|
|
|
se calcula localmente, los releases se verifican con BLS localmente y una
|
|
|
firma válida de otra ronda se rechaza (spec §13, §17, §51).
|
|
|
- **Integridad**: framing, cabecera, control y payload están autenticados
|
|
|
frente a quien no conoce las file keys: un cambio de un tercero hace fallar
|
|
|
la apertura (fixtures y corpus de mutaciones). Publicada la ronda,
|
|
|
cualquiera puede calcular la file key temporal, y cualquiera puede sellar
|
|
|
un control nuevo para una cabecera pública; quién puede escribir cada parte
|
|
|
y desde qué paso queda vinculada es el modelo de confianza de spec §27 y
|
|
|
§55.1.
|
|
|
- **Privacidad de metadatos** (formato 2): hasta la fecha quedan ocultos la
|
|
|
longitud exacta del contenido y el número de credenciales; no la fecha, la
|
|
|
política de acceso, `capsule_id`, las extensiones de la cabecera ni el
|
|
|
tamaño con relleno P (spec §55.2).
|
|
|
- **Sin autoría**: `time_only` da coherencia interna, no prueba de quién creó
|
|
|
la cápsula, ni antes ni después de madurar; `time_and_key` añade una barrera
|
|
|
de acceso, no una firma (spec §36.1).
|
|
|
- **Recuperar años después** exige el release histórico: de un relay drand que
|
|
|
aún lo sirva o de cualquier caché, verificado de nuevo localmente (spec §50).
|
|
|
|
|
|
Ver [SECURITY.md](SECURITY.md).
|
|
|
|
|
|
## Conformidad y tests
|
|
|
|
|
|
```bash
|
|
|
go test ./... # unitarios, vectores golden, fixtures, mutaciones
|
|
|
go test -race -cover ./...
|
|
|
go test -fuzz=FuzzInspect ./capsule # un objetivo de fuzzing cada vez
|
|
|
go test -tags interop ./capsule # las CLI oficiales age y tle abren nuestros ficheros
|
|
|
go test -tags integration ./capsule ./provider/drand # Quicknet en vivo
|
|
|
```
|
|
|
|
|
|
- `testdata/vectors`: vectores de `profile_hash`, fecha→ronda y `dk1_` (spec
|
|
|
§65, §66), vectores del perfil CBOR y de cada schema, vectores del relleno
|
|
|
(spec §29.1), el corpus de mutaciones exportado y un corpus diferencial de
|
|
|
las comprobaciones previas al desbloqueo; formatos en
|
|
|
[`testdata/README.md`](testdata/README.md).
|
|
|
- `testdata/fixtures`: fixtures oficiales `.dkc`/`.dkk` sobre rondas ya
|
|
|
publicadas, con la firma BLS embebida y todos los valores intermedios (spec
|
|
|
§67, §68); se descifran sin red. Siete son de formato 2; los cinco de formato
|
|
|
1, de la v0.8.2, se conservan por compatibilidad. Cada `.dkc` tiene
|
|
|
congelada su salida de `datekeys inspect -json`.
|
|
|
- `internal/testkit.Mutations`: las mutaciones del §64, las 33 de sus dos
|
|
|
primeras listas en cada formato y las 22 de la tercera, y 37 más, cada una
|
|
|
con su error y su paso exactos, comprobando además que los fallos previos al
|
|
|
desbloqueo nunca provocan una petición de release; exportadas a
|
|
|
`testdata/vectors/mutations.json`.
|
|
|
- [`docs/traceability.md`](docs/traceability.md): sección del spec → código → test.
|
|
|
- [`spec/datekeys.cddl`](spec/datekeys.cddl): schemas CBOR.
|
|
|
|
|
|
## Licencia
|
|
|
|
|
|
Código: Apache-2.0 ([LICENSE](LICENSE)). Especificación: CC-BY-4.0
|
|
|
([spec/README.md](spec/README.md)). `codec/bech32` se copia de age bajo su
|
|
|
propia licencia. "DateKeys" es un nombre reservado: ver [TRADEMARKS.md](TRADEMARKS.md).
|
