Documentation at v0.14: one drand scheme, 19 errors, the CDDL header

The traceability table, the READMEs, SECURITY.md and the header comment
of datekeys.cddl still described earlier versions: three drand schemes,
18 normative errors, a CDDL of v0.11 and signed releases that do not exist
yet. No normative text and no schema changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
v0.14
dev 1 day ago
parent 39b2033e3c
commit 22f184c2e7

@ -69,7 +69,7 @@ Hay tres números de versión, cada uno con su significado:
Cada release dice qué cubre, aquí y en el [CHANGELOG](CHANGELOG.md). El código de esta rama, aún sin publicar, cubre:
- la especificación 0.14: escribe el formato 3 de cápsula y lee los formatos 1, 2 y 3;
- el perfil Quicknet pinneado, y cualquier perfil de los tres schemes de drand que soporta tlock;
- el perfil Quicknet pinneado, y cualquier perfil del scheme `bls-unchained-g1-rfc9380`, el único que admite la v0.14 del spec;
- cifrado, inspección y apertura, firmas de autor y sellos, la nota pública, la llave de palabras y el localizador, y la CLI;
- todos los vectores y fixtures compartidos de [`testdata/`](testdata).
@ -225,7 +225,7 @@ publicar los ficheros. `Open` sin `Sink` se detiene justo tras el paso 2 con
los formatos 1 y 2 siguen escribiendo su contenido en streaming en `dst`,
nunca el relleno. `opened.Format` es el formato de la cápsula: el formato 1 no
oculta el número de credenciales ni la longitud exacta del contenido, así que
muéstralo (spec §70). Todo fallo del protocolo envuelve uno de los 18 errores
muéstralo (spec §70). Todo fallo del protocolo envuelve uno de los 19 errores
normativos del §69, así que `errors.Is` y `datekeys.Code(err)` lo identifican.
## Propiedades de seguridad y límites

@ -69,7 +69,7 @@ Three version numbers, each with its own meaning:
Each release states what it covers, here and in the [CHANGELOG](CHANGELOG.md). The code of this branch, not yet released, covers:
- specification 0.14: it writes capsule format 3 and reads formats 1, 2 and 3;
- the pinned Quicknet profile, and any profile on the three drand schemes that tlock supports;
- the pinned Quicknet profile, and any profile of the scheme `bls-unchained-g1-rfc9380`, the only one spec v0.14 admits;
- encryption, inspection and opening, author signatures and seals, the public note, the key of words and the locator, and the CLI;
- every shared vector and fixture of [`testdata/`](testdata).
@ -223,7 +223,7 @@ a caller error with no code. Capsules of formats 1 and 2 still stream their
content to `dst`, never the padding. `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 18 normative errors of spec §69, so `errors.Is` and
one of the 19 normative errors of spec §69, so `errors.Is` and
`datekeys.Code(err)` identify it.
## Security properties and limits

@ -103,7 +103,8 @@ All versions are pinned in `go.mod` and verified through `go.sum`. Changes to
## Supply chain
- Reproducible builds: `-trimpath`, `CGO_ENABLED=0`, pinned toolchain in CI.
- Releases publish SHA-256 checksums and a CycloneDX SBOM, and are signed with
cosign using the project's signing key.
- Releases will publish SHA-256 checksums and a CycloneDX SBOM, signed with
cosign using the project's signing key. No release of this module exists
yet: the specification has tags, the module has none.
- The Quicknet root of trust is compiled into the binary and checked against
its pinned `profile_hash` (`4147645109798ecbc9f630c2f709835bb5846fe7911a6bd5c5755e25ade2ada4`).

@ -1,4 +1,4 @@
# Traceability: DateKeys Protocol Specification v0.12 ↔ datekeys-go
# Traceability: DateKeys Protocol Specification v0.14 ↔ datekeys-go
This table maps every normative section of the specification to the code that
implements it and to the tests that exercise it. It is updated in the same
@ -22,7 +22,7 @@ v0.12 and v0.11 number their sections the same, but for §7.10, new in v0.14. A
| 10 | Provider Profile | `profile.Profile`, `Profile.Validate` | `profile.TestValidateRejectsTamperedProfiles` |
| 11 | Canonical profile encoding, `profile_hash`; `period` in 1..2^53−1, `genesis_time` in 0..2^53−1 | `Profile.CanonicalCBOR`, `Profile.Hash`, `profile.Decode` (hand-written `wire` encode and decode: keys 0 to 10, all required, in order; unsigned `genesis_time`, `codec.MaxSafeUint`; `period` limited to 1..86400 s, an implementation limit marked in `spec/datekeys.cddl`, `ERR_NON_CANONICAL_CBOR`) | `profile.TestQuicknetMatchesGoldenVector`, `TestQuicknetCBORLayout`, `TestDecodeRoundTrip`, `TestDecodeStructure`, `TestIntegerRanges`, `FuzzDecode`; `testdata/vectors/profile_quicknet.json`; the `provider_profile` block of `testdata/vectors/cbor.json` (*period of one day, the implementation limit*, *… above the implementation limit*) |
| 12 | Quicknet Provider Profile V1 | `profile.Quicknet`, `profile.Quicknet*` constants | `profile.TestQuicknetMatchesGoldenVector` |
| 12.1 | Provider Profile validation: CDDL, field rules (`ERR_UNKNOWN_PROFILE`: the name alphabets, normative, and their lengths and the `public_key` size, implementation limits; `period` at most 2^32−1, implied by the 86400 s limit; `genesis_time` in 1..253402300798, provider `drand`, the three unchained tlock schemes, a public key that is the canonical encoding of a point of the key group (§12.2) other than the identity), then the chain-hash self-check (`ERR_PROFILE_MISMATCH`), then the pinned `profile_hash`; the same codes on the pin path and the decode path | `profile.Decode`, `Profile.Validate` (rules 1 to 3 for a value), `validateDrand` (drand `chain.Info.Hash`), `profile.NewRegistry` (encode, `Decode`, then the pinned hash) | `profile.TestDecodePrecedence` (with a G1 point outside the subgroup), `TestPinPathMatchesDecode`, `TestChainHashFormula` (the formula computed without drand), `TestPublicKeyEncodingIsCanonical`, `TestValidateRejectsTamperedProfiles`, `TestRegistry`; the `provider_profile` block of `testdata/vectors/cbor.json` |
| 12.1 | Provider Profile validation: CDDL, field rules (`ERR_UNKNOWN_PROFILE`: the name alphabets, normative, and their lengths and the `public_key` size, implementation limits; `period` at most 2^32−1, implied by the 86400 s limit; `genesis_time` in 1..253402300798, provider `drand`, the scheme `bls-unchained-g1-rfc9380` alone since v0.14, a public key that is the canonical encoding of a point of G2 (§12.2) other than the identity), then the chain-hash self-check (`ERR_PROFILE_MISMATCH`), then the pinned `profile_hash`; the same codes on the pin path and the decode path | `profile.Decode`, `Profile.Validate` (rules 1 to 3 for a value), `validateDrand` (drand `chain.Info.Hash`), `profile.NewRegistry` (encode, `Decode`, then the pinned hash) | `profile.TestDecodePrecedence` (with a G1 point outside the subgroup), `TestPinPathMatchesDecode`, `TestChainHashFormula` (the formula computed without drand), `TestPublicKeyEncodingIsCanonical`, `TestValidateRejectsTamperedProfiles`, `TestRegistry`; the `provider_profile` block of `testdata/vectors/cbor.json` |
| 12.2 | Canonical encoding of a BLS12-381 point: compressed, 48 bytes in G1 and 96 in G2 (c1 then c0); compression flag set, infinity flag only for the point at infinity with every other bit zero, sort flag for the lexicographically largest y; coordinates below p; the prime-order subgroup; every other string rejected (x + p, c0 + p, c1 + p, an identity with a payload or the sort flag, no compression flag, uncompressed forms, other lengths) | the decoder of `kilic/bls12-381` through drand's `kyber-bls12381` (`KyberG1` and `KyberG2` `UnmarshalBinary`), which the reference runs for the public key (`profile.validateDrand`), the release signature (drand `Scheme.VerifyBeacon` in `provider.Verify`) and U (`tlock.BytesToCiphertext` in `agewrap.TimeIdentity.Unwrap`); the point at infinity refused explicitly for the public key and U, and for the signature by the BLS verification | `profile.TestDrandPointDecodersAreCanonical` (fails if a dependency update makes the decoders lenient), `TestPublicKeyEncodingIsCanonical`; `provider.TestVerifyRejects`; `agewrap.TestTimeIdentityStrictness`, `TestTimeIdentityRelease`; `internal/testkit.TestPointReencodings`; `capsule.TestPointMutationsChangeOnlyTheEncoding`; the ten point mutations of §64 |
| 13 | Root of trust | `profile.NewRegistry`, `profile.Pin`, `profile.Default`, `QuicknetProfileHash`; chain-hash self-check in `Profile.Validate` (the drand chain-info hash, formula in spec §12.1) | `profile.TestRegistry`, `TestPinPathMatchesDecode`; mutations *unknown profile*, *empty registry*; the `provider_profile` block of `testdata/vectors/cbor.json` |
| 14 | DateKey | `datekey.DateKey` | `datekey/*` |

@ -1,11 +1,10 @@
; DateKeys Protocol Specification v0.11 (working draft) - CBOR schemas (RFC
; 8610 CDDL).
; DateKeys Protocol Specification v0.14 - CBOR schemas (RFC 8610 CDDL).
;
; Normative companion of spec/DateKeys_Protocol_Specification_v0.11.md. The
; reference implementation g.activething.com/go/DateKeys still implements
; v0.9, whose schemas are in tag spec-v0.9. These schemas include the three
; control versions: 1, of capsule format 1 (v0.8.2), 2, of format 2 (v0.9),
; and 3, of format 3, and the security and head objects of format 3.
; Normative companion of spec/DateKeys_Protocol_Specification_v0.14.md, which
; the reference implementation g.activething.com/go/DateKeys implements. The
; schemas have not changed since v0.12. They include the three control
; versions: 1, of capsule format 1 (v0.8.2), 2, of format 2 (v0.9), and 3, of
; format 3, and the security and head objects of format 3.
;
; Encoding rules that CDDL cannot express (spec section 58, 58.1):
; - Every structure uses the CBOR profile of the protocol (spec section 58):

Loading…
Cancel
Save

Powered by TurnKey Linux.