|
|
# datekeys-go
|
|
|
|
|
|
Reference implementation in Go of the **DateKeys Protocol Specification
|
|
|
v0.9** ([`spec/`](spec/DateKeys_Protocol_Specification_v0.9.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).
|
|
|
|
|
|
## Versions
|
|
|
|
|
|
Three version numbers, each with its own meaning:
|
|
|
|
|
|
| Version | Where | Changes when |
|
|
|
|---|---|---|
|
|
|
| Format | Inside the objects: the capsule format, the `VERSION` of the DKC1 prelude, 2 when written and 1 or 2 when read, which is also the schema version of CONTROL_CBOR; and 1 for the framing of DKK1 and the schema of the other objects | The format changes. A reader rejects a version it does not know (spec §22, §70) |
|
|
|
| Specification | `datekeys.SpecVersion`, today `0.9`, and the tag `spec-v0.9` | The normative text changes. Spec §76 records each change with its case |
|
|
|
| Module | The tags of this Go module, `vX.Y.Z`, and `datekeys.Version()` | The API or the behaviour changes. Semantic versioning, with no stability promise before v1.0.0 |
|
|
|
|
|
|
`datekeys version` prints the module version, the specification and the Go toolchain. A binary built in a checkout shows the pseudo-version of its commit, for example `v0.0.0-20260928105528-9ac9cd952f04`.
|
|
|
|
|
|
Each release states what it covers, here and in the [CHANGELOG](CHANGELOG.md). The code on `main`, not yet released, covers:
|
|
|
- specification 0.9: it writes capsule format 2 and reads formats 1 and 2;
|
|
|
- the pinned Quicknet profile, and any profile on the three drand schemes that tlock supports;
|
|
|
- encryption, inspection and opening, and the CLI;
|
|
|
- every shared vector and fixture of [`testdata/`](testdata).
|
|
|
|
|
|
The first tag, v0.1.0, comes once `go get` works from a clean machine.
|
|
|
|
|
|
## 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(16 X25519 stanzas → CONTROL_CBOR))
|
|
|
CONTROL_CBOR = { header_binding = SHA-256(PRELUDE || PUBLIC_HEADER), I_PAYLOAD, extensions, L, padding rule }
|
|
|
PAYLOAD_AGE = age(X25519 R_PAYLOAD → your data || zeros up to P = rule(L)), streamed
|
|
|
```
|
|
|
|
|
|
This is format 2, the one `encrypt` writes (spec §22). Its 16 stanzas hold
|
|
|
from 1 to 16 credentials and a dummy in each slot left, in a random order, and
|
|
|
its payload is padded to P, so that until the unlock date nobody learns the
|
|
|
number of credentials or the exact length L (spec §29.1, §39, §55.2). Format
|
|
|
1, that of v0.8.2, has one stanza per credential and no padding; readers
|
|
|
still open it.
|
|
|
|
|
|
## CLI
|
|
|
|
|
|
```bash
|
|
|
go install g.activething.com/go/DateKeys/cmd/datekeys@latest
|
|
|
```
|
|
|
|
|
|
The module is served by the project's own Gitea, whose certificate Go does not
|
|
|
trust by default. Set `GOPRIVATE=g.activething.com` so that the Go proxy and
|
|
|
checksum database are bypassed for it, and either install the server's
|
|
|
certificate or, on a trusted network, set `GOINSECURE=g.activething.com`.
|
|
|
|
|
|
```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 encrypt -at 2030-01-01T00:00:00Z -padding bloque256 -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
|
|
|
datekeys version
|
|
|
```
|
|
|
|
|
|
`encrypt` never touches the network. It pads the content with the rule
|
|
|
reforzado, or bloque256 if asked (spec §29.1). `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. Format 2 seals the
|
|
|
// content length before the content: src must deliver exactly 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 is the .dkk; encode it with accesskey.Encode
|
|
|
Length: size,
|
|
|
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 content and never the padding; on error, discard what was
|
|
|
written and never present it as valid (spec §56). `opened.Format` is the
|
|
|
format of the capsule: format 1 hides neither the number of credentials nor
|
|
|
the exact length of the content, so show it (spec §70).
|
|
|
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 authenticated
|
|
|
against whoever does not know the file keys: a third party's change makes
|
|
|
opening fail (fixtures and the mutation corpus). Once the round is
|
|
|
published anyone can compute the time file key, and anyone can seal a new
|
|
|
control for a public header; who can write each part, and from which step
|
|
|
it is bound, is the trust model of spec §27 and §55.1.
|
|
|
- **Metadata privacy** (format 2): until the date, the exact length of the
|
|
|
content and the number of credentials stay hidden; the date, the access
|
|
|
policy, `capsule_id`, the header extensions and the padded size P do not
|
|
|
(spec §55.2).
|
|
|
- **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),
|
|
|
CBOR profile and schema vectors, padding vectors (spec §29.1), the exported
|
|
|
mutation corpus and a differential corpus of the pre-unlock checks; formats in
|
|
|
[`testdata/README.md`](testdata/README.md).
|
|
|
- `testdata/fixtures`: official `.dkc`/`.dkk` fixtures over published rounds,
|
|
|
with the BLS signature embedded and every intermediate value (spec §67, §68);
|
|
|
they decrypt offline. Seven are of format 2; the five of format 1, from
|
|
|
v0.8.2, are kept for compatibility. Each `.dkc` has its frozen
|
|
|
`datekeys inspect -json` output.
|
|
|
- `internal/testkit.Mutations`: the mutations of spec §64, the 33 of its first
|
|
|
two lists in each format and the 22 of its third list, and 37 more, each
|
|
|
with its exact error and step, and a check that pre-unlock failures never
|
|
|
cause a release request; exported to `testdata/vectors/mutations.json`.
|
|
|
- [`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).
|
