From 22f184c2e7ce2d76efd8ab406678d76942d6a227 Mon Sep 17 00:00:00 2001 From: dev Date: Tue, 6 Oct 2026 22:26:23 +0200 Subject: [PATCH] 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 --- README.es.md | 4 ++-- README.md | 4 ++-- SECURITY.md | 5 +++-- docs/traceability.md | 4 ++-- spec/datekeys.cddl | 13 ++++++------- 5 files changed, 15 insertions(+), 15 deletions(-) diff --git a/README.es.md b/README.es.md index 4dab305..d1be5f8 100644 --- a/README.es.md +++ b/README.es.md @@ -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 diff --git a/README.md b/README.md index 07cbeae..f50464c 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/SECURITY.md b/SECURITY.md index c934e7a..7883c24 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -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`). diff --git a/docs/traceability.md b/docs/traceability.md index 217f68b..1860866 100644 --- a/docs/traceability.md +++ b/docs/traceability.md @@ -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/*` | diff --git a/spec/datekeys.cddl b/spec/datekeys.cddl index ccb1db9..e217b56 100644 --- a/spec/datekeys.cddl +++ b/spec/datekeys.cddl @@ -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):