datekeys-doc/revision_externa/README.md

# DateKeys: request for an external cryptographic review

*Draft package, 6 October 2026; brought up to specification v0.15 and then to v0.16 on 7 October 2026. Prepared for the author before it is sent; see `NOTA_PARA_EL_AUTOR.md` for what is still to be decided.*

## What DateKeys is

DateKeys encrypts data so that it can only be opened after a chosen instant. It is timelock encryption built from existing pieces:

- **drand Quicknet** is the time source. A capsule is sealed with tlock (identity-based encryption over BLS12-381) to a future Quicknet round. When drand publishes the BLS signature of that round, the signature is the decryption key for that round (spec §12, §35, §63 steps 10–11).
- **age v1** (C2SP) is the file encryption. A capsule is three standard age files: an outer one sealed with tlock, an optional inner one sealed to X25519 recipients, and the payload sealed to a fresh X25519 identity carried in the sealed control (spec §28 to §34).

The protocol defines three objects:

- **DateKey**: a public descriptor of the time condition, a provider profile and a round, written as a canonical `dk1_…` string (spec §14 to §19).
- **DateKeyCap, `.dkc`**: the capsule (spec §20 to §39).
- **DateKeys Access Key, `.dkk`**: a portable credential, a raw X25519 identity, for the `time_and_key` policy (spec §38, §40 to §44.1).

Format 3, the only one a writer produces, holds several files with their paths, an encrypted head, payload padding, 16 fixed recipient slots with decoys, and an optional author signature (Ed25519, or CMS/CAdES with X.509 certificates) and RFC 3161 time seal, all encrypted until the date.

The guiding principle is: never trust the server for a property the client can verify cryptographically (spec §3). The profile is pinned, the round is computed locally and the release is verified locally.

Version 0.15 adds long-term recovery, without changing the `.dkc` or `.dkk` formats: a **release object**, the public BLS signature of one round as a small CBOR record (spec §47.1); a distinction between a release fetched from a network source and a **release in hand**, which the local clock no longer vetoes (spec §49, §63 step 9.c); recovery from **release archives and cache services** that keep the releases of all rounds, with an informative archive format and no promise of hosting (spec §50); and an informative **annex to open a capsule without DateKeys software** (spec §79), which the reference proves on fixtures with code that imports nothing from DateKeys, tlock or drand.

Version 0.16 answers a review of v0.15 by Astra, an AI system, and changes no format: a valid RFC 3161 seal proves that it came before the opening date only when its token carries `accuracy`, and otherwise gives its reason (spec §29.7, §29.11); the annex also derives a key of words, with a recipe without tables for the letters of the DateKeys lists and `UnicodeData.txt` of Unicode 18.0.0 for any other text, and allows a full last age chunk (§79.5, §79.7); a signature with certificates keeps the chains without their roots and the OCSP responses that fit, and the writer says what it leaves out (§29.10, §62.1 rules 21 and 22); and drand's JSON, accepted as caller input, is read strictly: no repeated names, exact names once escapes are decoded, an integer round (§47.1).

## What we ask

We ask for a cryptographic review of the protocol as specified, with the reference implementation as an aid. In particular:

1. Whether the construction meets the security goals of spec §4 under the threat model of spec §7, with the limits that spec §5 and §36.1 state.
2. Whether the bindings and commitments are sufficient and correctly placed (header binding, control and payload binding, the author-signature commitments, the seal subject).
3. Whether the byte-level description of the root of trust (spec §12.2, §63 steps 10 and 11 and the paragraphs after the flow) is complete and correct, so that an implementer needs no other source.
4. Whether the parsing surfaces (CBOR profile, age headers, the CMS/X.509/RFC 3161 reader of §29.10–§29.11, locator addresses) are specified tightly enough to avoid divergence and attack.
5. Whether the long-term recovery design of v0.15 is sound: the release object and its check at step 10, accepting a release in hand without comparing it with the clock (§63 step 9.c), archives and cache services as the recovery path (§50), and the annex of §79.
6. Whether the changes of v0.16 are right: a seal without `accuracy` giving no proof of anteriority, the strict reading of drand's JSON, the key of words in the annex, and what a signature with certificates keeps.

The ranked questions are in `scope_and_questions.md`, in two levels of scope: level 1, the protocol with the Go reference as evidence, and level 2, the parsers of the CMS/X.509/RFC 3161 reader and of the locator, which may be commissioned separately. Known open problems are listed there too, so that you do not spend time rediscovering them.

The normative text is the Spanish specification. Any English text, this package or a translation of parts of the specification, is informative: the author checks each finding against the Spanish text before it is accepted.

### Deliverable we expect

- A written report, in English, with each finding: the spec section, a severity (for example critical, high, medium, low, informational), a description, and a reproducible case or argument where possible.
- A separate list of points where the text is ambiguous or insufficient to implement, even if not a vulnerability.
- Answers, even short, to the ranked questions of `scope_and_questions.md`.
- The reviewer's name, scope and date, so that spec §76 can record the review as external (today §75 item 10 is open).

Scope, budget and timeline are to be agreed with the author.

## What is frozen for the review

| Item | Identifier |
|---|---|
| Specification | `datekeys-go/spec/DateKeys_Protocol_Specification_v0.16.md`, tag `spec-v0.16`, commit `b6ff17a5fa5f119aa8125356437a09c657b15d0b`, approved 7 October 2026 |
| Its SHA-256 | `807d4fe85ac09ad6f97abc75ab3e2156bb2f3fb0dc589777f4420627fad545e1` (recorded in `spec/README.md`; checked on 7 October 2026) |
| CBOR schemas | `datekeys-go/spec/datekeys.cddl` at the same commit: SHA-256 `ba3ceb24203ef49f55d5da021b7e940ae6780ef83fccb10aa3d305e4dcfac3a3` (v0.15 adds the rule `release`; v0.16 changes only the header comment) |
| Shared test data | `datekeys-go/testdata/` at the same tag: 150 files, documented in `testdata/README.md` |
| Reference implementation (Go) | `datekeys-go` at `spec-v0.16` / `b6ff17a`, which is also the head of branch `v0.16` and of `main`. Its documentation (README, SECURITY.md, `docs/traceability.md`, the header comment of `spec/datekeys.cddl`) is at v0.16 in the same commit: one frozen commit for Go |
| TypeScript implementation | `datekeys-ts` 0.5.0, tag `v0.5.0`, commit `2c305cf` |
| Dart implementation | `datekeys-dart`, branch `v0.16`, commit `b53afdc` (no tag) |

Note on TypeScript and Dart: `datekeys-ts` 0.5.0 and `datekeys-dart` at `b53afdc` implement specification 0.16, with their `testdata/` at tag `spec-v0.16` (`b6ff17a`), so they run against the same frozen vectors as the reference. The previous TypeScript version, 0.4.0, implemented 0.15.

## How this package is organised

| File | Content |
|---|---|
| `README.md` | This cover letter |
| `design_overview.md` | A self-contained English description of the cryptographic design, with spec sections |
| `threat_model.md` | Security goals, non-goals and the threat model (spec §4, §5, §7, §36.1, §55) |
| `scope_and_questions.md` | In scope, out of scope, the ranked questions, and the known open problems |
| `artifacts.md` | Repositories, commits, how to build and run the gates, the test vectors, dependencies and the traceability table |
| `precedence_and_language.md` | A proposal for the author: which language is normative, and precedence between the text, the CDDL, the test vectors and the implementation |
| `NOTA_PARA_EL_AUTOR.md` | A short note in Spanish for the author: what is still missing before sending |

The normative text is the Spanish specification. The English files here are informative summaries; where they disagree with the specification, the specification wins. Section numbers (§) refer to `DateKeys_Protocol_Specification_v0.16.md`.

## Prior reviews: all by AI systems

No human has reviewed DateKeys so far. Every review to date was done by AI systems:

- Claude (Anthropic), in the working sessions that wrote the specification and the implementations, including the completeness reviews of 29 September 2026 (`docs/REVISION_completitud_protocolo.md`, against v0.8.2) and 6 October 2026 (`docs/REVISION_completitud_v0.13.md`, against v0.13).
- Fable and Astra, also AI systems (confirmed by the author on 6 October 2026), for the design of format 3 (v0.10) and of the signature and the seal (v0.11).
- The long-term recovery of v0.15 (6 and 7 October 2026) was designed and drafted in the same Claude working sessions (`docs/diseno_recuperacion.md`, `docs/spec_v0.15/decisiones.md`) and approved by the author; it has had no review outside those AI-assisted sessions.
- Astra reviewed v0.15 on 7 October 2026, with five findings; v0.16 is the answer, drafted and implemented in the Claude working sessions (`docs/spec_v0.16/decisiones.md`) and approved by the author the same day. The §76 block of v0.16 calls it «la revisión de Astra»: an AI review too.

Some passages of spec §76 describe these reviews with words that suggest otherwise:

- the corrections of v0.8.2 are attributed to «la revisión formal e independiente», counted as an external review;
- the v0.10 block says the design passed «una revisión de seguridad externa»;
- «segunda implementación independiente» refers to the TypeScript implementation, which was written with the Go code in view; the Dart implementation was written the same way.

They should be read as internal, AI-assisted reviews. `precedence_and_language.md` proposes the wording change for the next version.

Three implementations agree on the shared vectors. That shows the code is consistent; it does not show that the text alone is enough to implement the protocol (completeness review of v0.13, point 2.4).

## Contact

The specification author. The security contact of the reference implementation is in `datekeys-go/SECURITY.md`.