@ -1,10 +1,11 @@
; DateKeys Protocol Specification v0.9 (working draft) - CBOR schemas (RFC
; DateKeys Protocol Specification v0.10 (working draft) - CBOR schemas (RFC
; 8610 CDDL).
;
; Normative companion of spec/DateKeys_Protocol_Specification_v0.9 .md. The
; Normative companion of spec/DateKeys_Protocol_Specification_v0.10 .md. The
; reference implementation g.activething.com/go/DateKeys still implements
; v0.8.2, whose schemas are in tag spec-v0.8.2. These schemas include both
; control versions: 1, of capsule format 1 (v0.8.2), and 2, of format 2.
; 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.
;
; Encoding rules that CDDL cannot express (spec section 58, 58.1):
; - Every structure uses the CBOR profile of the protocol (spec section 58):
@ -41,7 +42,8 @@
; implementation that applies them uses the same mapping.
; - The schema version of a control (key 1) is the one spec section 22
; assigns to the format of its capsule, the VERSION of the PRELUDE:
; control-v1 only in format 1, control-v2 only in format 2. A decoder
; control-v1 only in format 1, control-v2 only in format 2 and
; control-v3 only in format 3. A decoder
; picks the rule by the format, and another version is
; ERR_UNSUPPORTED_VERSION, read before the rest of the schema (spec
; section 69.1, layer 2). CDDL cannot express that link.
@ -54,6 +56,15 @@
; version (keys 0 and 1; for a control, the version of its capsule
; format), then this schema, then the fields with codes of their own in
; ascending key order.
; - In format 3, security and head sit inside BODY, the plaintext of
; PAYLOAD_AGE (spec section 29.2), whose 12-byte frame (AREA_LEN,
; SECURITY_LEN, HEAD_LEN) CDDL cannot express. A failure of security
; never has an error code: it only changes the verdicts (spec section
; 29.3, 29.7). In head, path lengths (R1) and the path order (R8) are
; rules of this schema (ERR_NON_CANONICAL_CBOR); the other path rules
; and the text rules are checked with the fields (ERR_HEAD_INVALID,
; spec section 29.4 to 29.6), and the paths sort by their UTF-8 bytes,
; like extension_id.
; Spec section 11 and 12. Spec section 12.1 adds the rules a profile must
; follow to be pinned (ERR_UNKNOWN_PROFILE), among them period at most 2^32-1
@ -91,7 +102,7 @@ public-header = {
; Spec section 31. Sealed inside OUTER_TIME_AGE (time_only) or inside
; INNER_ACCESS_AGE inside OUTER_TIME_AGE (time_and_key).
control = control-v1 / control-v2
control = control-v1 / control-v2 / control-v3
; Capsule format 1 (v0.8.2).
control-v1 = {
@ -115,6 +126,19 @@ control-v2 = {
7 => padding-scheme, ; padding, the code of the padding rule of PAYLOAD_AGE (spec section 29.1)
}
; Capsule format 3 (v0.10). The keys of control-v2; L is the length of BODY
; (spec section 29.2). 103 bytes without extensions.
control-v3 = {
0 => "datekeys-control",
1 => 3,
2 => bstr .size 32, ; header_binding
3 => bstr .size 32, ; payload_identity, raw X25519 identity I_PAYLOAD
? 4 => extensions, ; critical_extensions
? 5 => extensions, ; noncritical_extensions
6 => payload-length, ; payload_length, L, the length of BODY
7 => padding-scheme, ; padding, the code of the padding rule of PAYLOAD_AGE
}
; Fixed width, so that the length of CONTROL_CBOR, visible in
; SEALED_CONTROL_LEN, never depends on L (spec section 55.2). Value at most
; max-payload-length (see the rules above). L = 0 is 48 0000000000000000.
@ -126,6 +150,51 @@ padding-scheme = &(bloque256: 1, reforzado: 2)
; max-safe-uint under both padding rules (spec section 29.1).
max-payload-length = 8936830510563328
; Spec section 29.3. SECURITY_CBOR of format 3, inside the area of BODY.
; Version 1 in every later version of the spec that keeps format 3. Keys 2
; and 3 hold separately encoded CBOR, author-signature and seal, with the
; CBOR profile; a failure of their content only changes its own verdict.
; This version defines no alg and no seal_type: alg 1 (Ed25519) and
; seal_type 1 (DateKeys), 2 (RFC 3161) and 3 (OpenTimestamps) are reserved,
; and a writer of this version writes security empty (22 bytes).
security = {
0 => "datekeys-security",
1 => 1,
? 2 => bstr .size (1..65536), ; author-signature, encoded on its own
? 3 => bstr .size (1..65536), ; seal, encoded on its own
}
author-signature = {
0 => 1..4294967295, ; alg
1 => bstr, ; public key
2 => bstr, ; signature
}
seal = {
0 => 1..4294967295, ; seal_type
1 => bstr, ; token
}
; Spec section 29.4. HEAD_CBOR of format 3, at most 16 MiB. Always version 1
; in format 3: a new version needs a new format (spec section 22). These
; limits are normative and fixed with the format.
head = {
0 => "datekeys-head",
1 => 1,
2 => bstr .size 32, ; salt, fresh from a CSPRNG
? 3 => tstr .size (1..16384), ; comment (spec section 29.6)
? 4 => tstr .size (1..256), ; declared_author (spec section 29.6)
? 5 => [1*65535 file], ; strictly ascending UTF-8 bytes of path
? 6 => extensions, ; critical_extensions
? 7 => extensions, ; noncritical_extensions
}
file = {
0 => tstr .size (1..1024), ; path (spec section 29.5)
1 => 0..max-payload-length, ; size
2 => 0..max-payload-length, ; start
3 => 0..max-payload-length, ; end, exclusive
4 => bstr .size 32, ; SHA-256 of the file
? 5 => 0..253402300799, ; mtime, UTC seconds, informative
}
; Spec section 41. BODY_CBOR of a .dkk, after the 12-byte DKK1 prelude.
access-key-body = {
0 => "datekeys-access-key",
