Significant revision of cask. Remove expiry. Reorder data. Eliminate CASK kind. (#43)

This significant revision of CASK contains the following changes:

- Sensitive data key moved from its current location. As a result of
this move, we restore reserved padding bits for sensitive component
sizes of 16, 32 and 64 bytes. A 48-byte sensitive component aligns
cleanly along a 3-byte boundary and has no padding.
- The timestamp is moved to follow the CASK signature. Minutes data is
retained.
- The expiry is dropped from the core format. This data would be helpful
to responders to encode, as by reading the key it would be possible to
understand whether the key, as originally allocated was valid in some
exposure timeframe. A key CASK principle is for the core format to
publish data that is useful for static consumption and not tempting to
evaluate at runtime. And so we drop the expiry as too tempting for
runtime evaluation.
- The CASK key kind is eliminated. Various classes of key, primary key,
derived, HMAC can be specified in the provider-specific key kind
component.
- We now encode the optional data size, as a count of 3-byte optional
segments. By encoding this length as well as the sensitive component
length in characters at a fixed location relative to the CASK signature
`QJJQ` we enable high-performance detections that start with locating
the CASK signature in test/data streams.
- The correlating id is dropped to 15 bytes in length. In general, a
16-byte value (128 bits) is preferred in scenarios for a strong
guarantee of uniqueness. In practice, 120 bits is sufficient.

The BNF is renamed to `CaskSecrets.md` to reflect that there's no longer
a specific CASK key kind in play. The churn in the BNF was sufficient
that rather than renaming first so that we could diff, I simply created
a clean copy of the new BNF. But in case anyone finds it helpful to see
the explicit diffs from previous, I've left an edited version of the old
BNF behind to examine. This will be deleted, obviously, once everything
is reviewed/refined/accepted.

This change resolved #35, #36 and #37.

---------

Co-authored-by: Nick Guerrera <[email protected]>

Author: michaelcfanning

.editorconfig

@@ -1,7 +1,7 @@
 root = true
+charset = utf-8
 
 [*]
-charset = utf-8
 indent_style = space
 indent_size = 2
 insert_final_newline = true

docs/CaskSecret.md

@@ -0,0 +1,92 @@
+# CASK Secrets
+## Standard Backus-Naur Form (BNF)
+```
+<key> ::= <sensitive-data>      ; A sequence of security-sensitive bytes.
+          <cask-signature>      ; A fixed signature (`QJJQ`) that enables high-performance textual identification.
+          <timestamp>           ; The year, month, day, hour, and minute of secret allocation.
+          <sensitive-data-size> ; A count of 16-byte segments encoded as sensitive data ('B' = 1 x 16 bytes = 128 bits, etc).
+          <optional-data-size>  ; A count of 3-byte optional data segments, 'A' = 0 = 0 bytes, 'B' = 1 = 3 bytes, etc.
+          <provider-kind>       ; A provider-defined key kind.
+          [<optional-fields>]   ; Optional fields comprising provider-defined data.
+          <provider-signature>  ; A fixed signature identifying the secret provider.
+          <correlating-id>      ; A 20-byte non-sensitive correlating identifier for the secret (see below).
+
+<sensitive-data> ::= <128-bits-padded> | <256-bits-padded>                  ; The sensitive data is a secret generated for a security purpose,
+                   | <384-bits> | <512-bits-padded>                         ; such as random data generated by a cryptographically secure random
+                                                                            ; number generator (RNG), a Hash Message Authentication Code (HMAC),
+                                                                            ; an output of a Key Derivation Function (KDF), etc. CASK specifies
+                                                                            ; a storage location and component size for this data but does not
+                                                                            ; specify a particular cryptographic algorithm or method for
+                                                                            ; generating it. The size of this component must conform to the
+                                                                            ; encoded <sensitive-data-size> value.
+<128-bits-padded>  ::= 21 * <base64url> <base64-four-zeros-suffix> 'AA'     ; The total sensitive data comprises 128 bits encoded as 21
+                                                                            ; characters x 6 bits (126 bits) and 1 character providing
+                                                                            ; 2 bits of sensitive data padded with 0000b. The final
+                                                                            ; characters `AA` comprise 12 bits of additional padding
+                                                                            ; that brings the component to a 3-byte boundary.
+<256-bits-padded>  ::= 42 * <base64url> <base64-two-zeros-suffix> 'A'       ; The total sensitive data comprises 256 bits encoded as 42
+                                                                            ; characters comprising 6 bits of sensitive data = 252 bits and
+                                                                            ; The final characters `A` comprises 6 bits of additional
+                                                                            ; padding that brings the component to a 3-byte boundary.
+<384-bits>  ::= 64 * <base64url>                                            ; The total sensitive data comprises 384 bits encoded as 64
+                                                                            ; 6-bit characters. No reserved padding is required, as
+                                                                            ; 384 bits (48 bytes) aligns to a 3-byte boundary.
+<512-bits-padded>  ::= 85 * <base64url> <base64-four-zeros-suffix> 'AA'     ; The total sensitive data comprises 512 bits encoded as 85
+                                                                            ; characters x 6 bits (510 bits) and 1 character providing
+                                                                            ; 2 bits of sensitive data padded with 0000b. The final 
+                                                                            ; characters `AA` comprise 12 bits of additional padding
+                                                                            ; that brings the component to a 3-byte boundary.
+<base64url> ::= 'A'..'Z' | 'a'..'z' | '0'..'9' | '-' | '_'                  ; Base64 URL-safe printable characters. The '=' padding character is excluded.
+<base64-two-zeros-suffix> ::= 'A' | 'E' | 'I' | 'M' | 'Q' | 'U' | 'Y' | 'c' 
+                            | 'g' | 'k' | 'o' | 's' | 'w' | '0' | '4' | '8' ; Base64 printable characters with two trailing zero bits.
+<base64-four-zeros-suffix> ::= 'A' | 'Q' | 'g' | 'w'                        ; Base64 printable characters with four trailing zero bits.
+<cask-signature> ::= 'QJJQ'                                                 ; Fixed signature identifying the CASK key.
+<timestamp> ::= <year> <month> <day> <hour> <minute>                        ; Time-of-allocation timestamp components.
+<year> ::= <base64url>                                                      ; Allocation year, 'A' (2025) to '_' (2088).
+<month> ::= 'A'..'L'                                                        ; Allocation month, 'A' (January) to 'L' (December).
+<day> ::= 'A'..'Z' | 'a'..'e'                                               ; 'A' = day 1, 'B' = day 2, ... 'e' = day 31
+<hour> ::= 'A'..'X'                                                         ; Represents hours 0-23. 'A' = hour 0 (midnight), ... 'X' = hour 23.
+<minute> ::= 'A'..'7'                                                       ; Represents minutes 0-59.
+<sensitive-data-size> ::= 'A'                                               ; 'A' indicates a 128-bit sensitive data component, 'B' 256-bit, etc.
+<optional-data-size> ::= 'A'                                                ; 'A' = zero 3-byte optional bytes, 'B' = one optional 3-byte segment, etc.
+<provider-kind> ::= <base64url>                                             ; Provider-defined key kind.
+<provider-signature> ::= 4 * <base64url>                                    ; Provider identifier (24 bits).
+<optional-fields> ::= { <optional-field> }                                  ; Zero or more 4-character (24-bit) sequences of optional data.
+<optional-field> ::= 4 * <base64url>                                        ; Each optional field is 4 characters (24 bits). This keeps data
+                                                                            ; cleanly aligned along 3-byte/4-encoded character boundaries,
+                                                                            ; facilitating readability of encoded form as well as byte-wise use.
+<correlating-id> ::= 20 * <base64url>                                       ; 120 bits of unique, non-sensitive data generated by a cryptographically
+                                                                            ; secure RNG. This data is not sensitive and is designed to correlate 
+                                                                            ; metadata for generated secrets with reports of exposure and other data.
+                                                                            ; As a non-security-sensitive component, this data MUST NOT be used
+                                                                            ; to drive security-sensitive operations.
+```
+
+## Byte-wise Rendering Example for 256-bit Key (no optional data)
+|Byte Range|Decimal|Hex|Binary|Description|
+|-|-|-|-|-|
+|decodedKey[..31]|0...255|0x0...0xFF|00000000b...11111111b|256 bits of sensitive data produced by a cryptographically secure RNG, an HMAC, etc.|
+|decodedKey[32]|0|0x00|00000000b| 8 bits of reserved padding.
+|decodedKey[33..36]| 37, 4, 9  |0x40, 0x92, 0x50| 00100000b, 10010010b, 01010000b | Decoded 'QJJQ' signature.
+|decodedKey[36..39]||||Timestamp data encoded in 4 six-bit segments for YMDH.
+|decodedKey[39..42]||||Timestamp minutes, sensitive data size, optional-data-size, and provider kind data encoded in 4 six-bit segments.
+|decodedKey[42..45]|0...255|0x0...0xFF|00000000b...11111111b| Provider signature, e.g. , '0x4c', '0x44', '0x93' (base64-encoded as 'TEST')
+|decodedKey[45..60]||||16 byte non-sensitive, unique correlating id.
+
+## URL-Safe Base64-Encoded Rendering Example for 256-bit Key (no optional data)
+|String Range|Text Value|Description|
+|-|-|-|
+|encodedKey[..42] | 'A'...'_' | 252 bits of randomized data generated by cryptographically secure RNG
+|encodedKey[42] | <base64-two-zeros-suffix> | 4 bits of randomized data followed by 2 zero bits. See the <base64-two-zeros-suffix> definition for legal values.
+|encodedKey[43] | 'A' | The 6-bit encoded sensitive component size.
+|encodedKey[44..48]|'QJJQ'| Fixed CASK signature.
+|encodedKey[48]|'A'...'_'|Represents the year of allocation time, 'A' (2025) to '_' (2088)|
+|encodedKey[49|'A'...'L'|Represents the month of allocation time, 'A' (January) to 'L' (December)|
+|encodedKey[50]|'A'...'Z'\|'a'..'e'|Represents the day of allocation time, 'A' (0) to 'e' (31)|
+|encodedKey[51]|'A'...'X'|Represents the hour of allocation time, 'A' (hour 0 or midnight) to 'X' (hour 23).
+|encodedKey[52]|'A'...'7'| Represents the minute of allocation time.
+|encodedKey[53]|'A'...'D'| Sensitive component key size, 'A' (128-bit), 'B' (256-bit), 'C' (384-bit) or 'D' (512-bit).
+|encodedKey[54]|'A'...'?'| Count of optional 3-byte data segments, 'A' == 0 bytes, 'B' == 3 bytes, capped at ?? (maximum permissible would be 189 bytes, 63 * 3)
+|encodedKey[55]|'A'...'_'| Provider-defined key kind.
+|encodedKey[55..75]|'A'...'_'| Correlating id.
+```

docs/GenerateKeyPseudoCode.md

@@ -4,54 +4,52 @@
 
 ## Inputs:
 - Provider signature: string
-- Provider key kind: string
-- Key expiry expressed in five minutes increments: integer
+- Provider key kind: char
 - Provider data: string
+- Secret data size: int
 
 ## Outputs:
 - Generated key: string
 
 ## Computation
 1. Validate input. Return an error if any of the following are NOT true:
     - Provider signature is exactly 4 characters long.
-    - Provider signature consists entirely of characters that are valid in base64url encoding.
-    - Provider key kind is a single, printable (i.e., non-padding) base64url character.
-    - Expiry in five minutes increments is a non-negative integer less than 262,144.
-    - Provider data (if non-empty) has a length that is a multiple of 4 characters and no more than 32 characters.
+    - Provider signature consists entirely of printable (non-padding) characters that are valid in base64url encoding.
+    - Provider key kind is a single, printable base64url character.
+    - Provider data (if non-empty) has a length that is a multiple of 4 characters and no more than 12 characters.
     - Provider data (if non-empty) consists entirely of base64url printable characters.
+    - Secret data size is between 1 (a single 16-byte segment of sensitive data = 128 bits) and 4 (four 16-byte segments = 512 bits).
 1. Let N = the length of the base64url-decoded provider data.
     - Number of characters in provider data divided by 4, times 3.
+1. Compute the sensitive data size in bytes:
+    - Multiply the secret data size by 16 to generate a secret size in bytes.
+    - If the secret size in bytes is not a multiple of 3, round this value up, i.e., (secret size in bytes + 3 - 1) / 3 * 3.
+    - The final padded sensitive data size will be one of 18, 33, 48, or 66 bytes.
 1. Allocate storage for the generated key:
-    - 32 bytes for entropy.
-    - 1 byte for sensitive-data size.
+    - 18, 33, 48, or 66 bytes bytes for the sensitive data component.
     - 3 bytes for CASK signature.
+    - 6 bytes for the timestamp, sensitive and optional size designations, and provider key kind.
+    - N bytes for provider data. (Guaranteed to be a multiple of 3 by input validation.)
     - 3 bytes for provider signature.
-    - 1 byte for provider key kind
-    - 1 byte for CASK key kind.
-    - 16 bytes for the non-sensitive correlating id.
-    - 3 bytes for year, month, day and hour of the allocation timestamp.
-    - 3 bytes for minutes of the allocation timestamp and the 18-bit expiry.
-1.  - N bytes for provider data. (Guaranteed to be a multiple of 3 by input validation.)
-
-1. Generate 256 bits of cryptographically secure random data. Store the result at the beginning of the generated key.
-1. Write sensitive data size to next byte, e.g., 0 to indicate 256-bits.
+    - 15 bytes for the non-sensitive correlating id.
+1. Generate cryptographically secure random bytes as specified by the secret size computation. Store the result at the beginning of the generated key.
+1. Clear the padding bytes, if any, that follow the secret and which bring alignment to a 3-byte boundary.
 1. Write CASK signature [0x40, 0x92, 0x50] ("QJJQ", base64-decoded) to the next 3 bytes.
-1. Base64url-decode provider signature and store the result in the next 3 bytes.
-1. Write 0x00 to the next byte to indicate a CASK primary key kind.
-1. Left-shift the provider key kind by 2 bits and store the result in the next byte.
-1. Left-shift the CASK key key kind by 4 bits and store the result in the next byte.
-1. Generate 128 bits of cryptographically secure random data and store the result in the next 16 bytes.
-1. Let T = current date and time in UTC.
+1. Retrieve the current date and time in UTC and store the result in T.
 1. Encode T in 4 characters, YMDH:
-    - Y = base64url-encoding of (Year - 2025).
-    - M = base64url-encoding of zero-based month.
-    - D = base64url-encoding of zero-based hour.
-    - H = base64url-encoding of zero-based day.
+    - Y = base64url-encoding of T.Year - 2025.
+    - M = base64url-encoding of T.Month as a zero-based value, 0 - 11.
+    - D = base64url-encoding of T.Day as a zero-based value, i.e., 0 - 30.
+    - H = base64url-encoding of T.Hour as zero-based value, i.e., 0 - 23.
 1. Base64url-decode YMDH and store the result in the next 3 bytes.
-1. Base64url-encode T minutes M in a single character
-1. Encode the last 3 bytes of the big-endian representation of the 18-bit expiry.
-1. Base64url-decode M and the 3-character expiry and store the result in the next 3 bytes.
-1. Base64url-decode provider data and store the result in the next N bytes.
+1. Encode the timestamp minutes, data sizes and provider key kind in 4 characters, MSOK:
+    - M = base64url-encoding of T.Minutes as a zero-based value, i.e., 0 - 59.
+    - S = base64url-encoding of secret data size, one of 1 (128 bits), 2 (256), 3 (384), or 4 (512).
+    - O = base64url-encoding of optional data size, a count of 3-byte segments, one of 0 - 4.
+    - K = provider key kind, i.e., the exact base64url printable char specified by the caller.
+1. Base64url-decode MSOK and store the result in the next 3 bytes.
+1. Base64url-decode provider signature and store the result in the next 3 bytes.
+1. Generate 120 bits of cryptographically secure random data and store the result in the next 15 bytes.
 
 ## References
 - Base64url: https://datatracker.ietf.org/doc/html/rfc4648#section-5