datekeys-doc/revision_externa/README.md

# DateKeys: request for an external cryptographic review

*Draft package, 6 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.

## 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.

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.14.md`, tag `spec-v0.14`, commit `39b2033e3ccf54a91bda8d7e3ced39b26dbfa58c`, approved 6 October 2026 |
| Its SHA-256 | `390922135931dd61a263ed90259c7a978b5d92944405e641e94cc194f84fb459` (recorded in `spec/README.md`; checked on 6 October 2026) |
| CBOR schemas | `datekeys-go/spec/datekeys.cddl`: SHA-256 `35c6e5fb74d65907bcb436242079bcc99cfb81a654a1174f2cac68576bf24a51` at the tag, and `9607d1c7ebd2c09df3969a2749a588cf39bc24fe49a05a5f308b798a3ca621fa` at `22f184c`, which changes only its header comment |
| Shared test data | `datekeys-go/testdata/` at the same tag: 136 files, documented in `testdata/README.md` |
| Reference implementation (Go) | `datekeys-go` at `spec-v0.14` / `39b2033`; its documentation (README, SECURITY.md, `docs/traceability.md`, the header comment of `spec/datekeys.cddl`) brought up to v0.14 at `22f184c`, the head of branch `v0.14`. That commit changes no specification text, no schema rule and no code: in `datekeys.cddl` only its header comment, so its SHA-256 differs from the tag's (row above) |
| TypeScript implementation | `datekeys-ts` 0.2.0, tag `v0.2.0`, commit `8cf0685fb016ae05afcd5b96387b4b884f3ad972` (see the note below) |
| Dart implementation | `datekeys-dart`, branch `v0.14`, commit `013b0695228bae6a4a61e244e679d38f2b8b93fd` |

Note on TypeScript: `datekeys-ts` 0.2.0 implements specification **0.13** (its `testdata/` is at tag `spec-v0.13`). Spec 0.14 changes no format and no verdict of a Quicknet capsule (spec §70). The v0.14 support of TypeScript (the `tlock_steps.json` test and the one-scheme rule) is in commit `4e23f88`, on a development branch, without a tag. The author decides which one is frozen.

## 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.14.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).

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`.