|
|
# datekeys-go
|
|
|
|
|
|
Implementación de referencia en Go de la **DateKeys Protocol Specification
|
|
|
v0.8.2** ([`spec/`](spec/DateKeys_Protocol_Specification_v0.8.2.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: la versión de framing de DKC1 y DKK1 y la versión de schema de la clave 1, hoy todas 1 | Cambia el formato. Un lector rechaza una versión que no conoce (spec §70) |
|
|
|
| Especificación | `datekeys.SpecVersion`, hoy `0.8.2`, y el tag `spec-v0.8.2` | 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.8.2, con versiones de formato 1;
|
|
|
- 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(recipients X25519 → CONTROL_CBOR))
|
|
|
CONTROL_CBOR = { header_binding = SHA-256(PRELUDE || PUBLIC_HEADER), I_PAYLOAD, extensiones }
|
|
|
PAYLOAD_AGE = age(X25519 R_PAYLOAD → tus datos), en streaming
|
|
|
```
|
|
|
|
|
|
## 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 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. `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.
|
|
|
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
|
|
|
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 plaintext en streaming; si falla, descarta lo escrito (spec
|
|
|
§56). 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.
|
|
|
- **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, 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. Cada `.dkc` tiene congelada su salida de
|
|
|
`datekeys inspect -json`.
|
|
|
- `internal/testkit.Mutations`: las 33 mutaciones del §64 y 32 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).
|
