|
|
# datekeys-go
|
|
|
|
|
|
Reference implementation in Go of the **DateKeys Protocol Specification
|
|
|
v0.8.1** ([`spec/`](spec/DateKeys_Protocol_Specification_v0.8.1.md)).
|
|
|
[Versión en español](README.es.md).
|
|
|
|
|
|
DateKeys encrypts data so that it can only be opened after a chosen instant.
|
|
|
The time condition comes from the drand **Quicknet** randomness beacon: data is
|
|
|
sealed with timelock encryption to a future round, and the round's BLS
|
|
|
signature, published by drand when the round arrives, is the key. Everything
|
|
|
that can be verified locally is verified locally; relays, caches and APIs are
|
|
|
untrusted transports.
|
|
|
|
|
|
> **Status: v0.x, pre-standard.** The specification is a draft and the API may
|
|
|
> change before v1.0.0. The code has not had an external cryptographic review
|
|
|
> yet (spec §75). Do not rely on it for high-value secrets.
|
|
|
|
|
|
## What it implements
|
|
|
|
|
|
| Object | Spec | Package |
|
|
|
|---|---|---|
|
|
|
| DateKey: date → round, canonical `dk1_…` string | §14–§19 | [`datekey`](datekey) |
|
|
|
| Provider Profile, pinned Quicknet profile, `profile_hash` | §10–§13 | [`profile`](profile) |
|
|
|
| Release sources, local BLS verification, drand relays | §45–§52 | [`provider`](provider), [`provider/drand`](provider/drand) |
|
|
|
| DateKeyCap `.dkc`: `time_only` and `time_and_key` | §20–§39, §61–§63 | [`capsule`](capsule) |
|
|
|
| DateKeys Access Key `.dkk` | §40–§44 | [`accesskey`](accesskey) |
|
|
|
| Extensions | §54 | [`extension`](extension) |
|
|
|
| Deterministic CBOR | §58 | [`codec`](codec) |
|
|
|
| Normative errors | §69 | [`errors.go`](errors.go) |
|
|
|
| CLI | — | [`cmd/datekeys`](cmd/datekeys) |
|
|
|
|
|
|
No cryptography is implemented here. Encryption is [age](https://age-encryption.org)
|
|
|
(`filippo.io/age`); the timelock is [tlock](https://github.com/drand/tlock)
|
|
|
(its exported core only); BLS verification is drand's. This module adds
|
|
|
framing, CBOR, bindings, verification rules and the flow, and it enforces the
|
|
|
stanza rules of the protocol inside the age identities, so that a file is never
|
|
|
accepted just because age could unwrap a key.
|
|
|
|
|
|
Not implemented on purpose: the Release API server and queue, storage and
|
|
|
delivery, concrete extensions, and the TypeScript client (plan §2).
|
|
|
|
|
|
## A capsule, in one picture
|
|
|
|
|
|
```text
|
|
|
.dkc = PRELUDE (16 B) || PUBLIC_HEADER (CBOR) || SEALED_CONTROL (age) || PAYLOAD_AGE (age, to EOF)
|
|
|
|
|
|
time_only: SEALED_CONTROL = age(tlock round R → CONTROL_CBOR)
|
|
|
time_and_key: SEALED_CONTROL = age(tlock round R → age(X25519 recipients → CONTROL_CBOR))
|
|
|
CONTROL_CBOR = { header_binding = SHA-256(PRELUDE || PUBLIC_HEADER), I_PAYLOAD, extensions }
|
|
|
PAYLOAD_AGE = age(X25519 R_PAYLOAD → your data), streamed
|
|
|
```
|
|
|
|
|
|
## CLI
|
|
|
|
|
|
```bash
|
|
|
go install github.com/datekeys/datekeys-go/cmd/datekeys@latest
|
|
|
```
|
|
|
|
|
|
```bash
|
|
|
datekeys datekey resolve -at 2030-01-01T00:00:00Z
|
|
|
datekeys encrypt -at 2030-01-01T00:00:00Z -in letter.txt -out letter.dkc
|
|
|
datekeys encrypt -at 2030-01-01T00:00:00Z -policy time_and_key -dkk letter.dkk -in letter.txt -out letter.dkc
|
|
|
datekeys inspect -in letter.dkc
|
|
|
datekeys decrypt -in letter.dkc -out letter.txt -dkk letter.dkk
|
|
|
datekeys profile hash
|
|
|
```
|
|
|
|
|
|
`encrypt` never touches the network. `inspect` runs only the pre-unlock checks
|
|
|
(spec §63 steps 1–8): it never requests a release and never uses a secret.
|
|
|
`decrypt` fetches the release from public drand relays, verifies it locally
|
|
|
and publishes the plaintext only after age authenticated all of it. Outputs are
|
|
|
never overwritten.
|
|
|
|
|
|
## Library
|
|
|
|
|
|
```go
|
|
|
reg, err := profile.Default() // pinned Quicknet profile, checked against its profile_hash
|
|
|
|
|
|
// Encrypt: no network, the round is resolved locally.
|
|
|
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 is the .dkk; encode it with accesskey.Encode
|
|
|
Now: time.Now,
|
|
|
})
|
|
|
|
|
|
// Inspect: steps 1–8, no network, no secrets.
|
|
|
in, err := capsule.Inspect(f, capsule.InspectOptions{Registry: reg})
|
|
|
|
|
|
// Open: steps 1–18; the release is verified locally.
|
|
|
opened, err := capsule.Open(ctx, tmp, f, capsule.OpenOptions{
|
|
|
Registry: reg,
|
|
|
Source: drand.New(),
|
|
|
AccessKey: key, // or Identities: []age.Identity{...}
|
|
|
Now: time.Now,
|
|
|
})
|
|
|
if errors.Is(err, datekeys.ErrReleaseUnavailable) { /* not yet */ }
|
|
|
```
|
|
|
|
|
|
`Open` streams the plaintext; on error, discard what was written (spec §56).
|
|
|
Every protocol failure wraps one of the 17 normative errors of spec §69, so
|
|
|
`errors.Is` and `datekeys.Code(err)` identify it.
|
|
|
|
|
|
## Security properties and limits
|
|
|
|
|
|
- **Time confidentiality** holds under drand's threshold assumption. The
|
|
|
Quicknet timelock is **not post-quantum**: ciphertexts kept for years are
|
|
|
exposed to harvest-now, decrypt-later (spec §7.7, §53).
|
|
|
- **No trust in servers**: the profile is pinned in the binary, the round is
|
|
|
computed locally, releases are BLS-verified locally, and a valid signature of
|
|
|
another round is rejected (spec §13, §17, §51).
|
|
|
- **Integrity**: framing, header, control and payload are all authenticated;
|
|
|
any change makes opening fail (fixtures and the mutation corpus).
|
|
|
- **No authorship**: `time_only` gives internal coherence, not proof of who
|
|
|
created a capsule, before or after it matures; `time_and_key` adds an access
|
|
|
barrier, not a signature (spec §36.1).
|
|
|
- **Recovery years later** needs the historical release: from a drand relay
|
|
|
that still serves it or from any cache, re-verified locally (spec §50).
|
|
|
|
|
|
See [SECURITY.md](SECURITY.md).
|
|
|
|
|
|
## Conformance and tests
|
|
|
|
|
|
```bash
|
|
|
go test ./... # unit, golden vectors, fixtures, mutation corpus
|
|
|
go test -race -cover ./...
|
|
|
go test -fuzz=FuzzInspect ./capsule # one fuzz target at a time
|
|
|
go test -tags interop ./capsule # official age and tle CLIs open our files
|
|
|
go test -tags integration ./capsule ./provider/drand # live Quicknet
|
|
|
```
|
|
|
|
|
|
- `testdata/vectors`: profile hash, date→round and `dk1_` vectors (spec §65, §66).
|
|
|
- `testdata/fixtures`: official `.dkc`/`.dkk` fixtures over published rounds,
|
|
|
with the BLS signature embedded and every intermediate value (spec §67, §68);
|
|
|
they decrypt offline.
|
|
|
- `capsule/mutation_test.go`: the 20 mutations of spec §64 and 25 more, each
|
|
|
with its exact error and step, and a check that pre-unlock failures never
|
|
|
cause a release request.
|
|
|
- [`docs/traceability.md`](docs/traceability.md): spec section → code → test.
|
|
|
- [`spec/datekeys.cddl`](spec/datekeys.cddl): CBOR schemas.
|
|
|
|
|
|
## License
|
|
|
|
|
|
Code: Apache-2.0 ([LICENSE](LICENSE)). Specification: CC-BY-4.0
|
|
|
([spec/README.md](spec/README.md)). `codec/bech32` is copied from age under its
|
|
|
own license. "DateKeys" is a reserved name: see [TRADEMARKS.md](TRADEMARKS.md).
|
