From f67871524cf25e87274fbdc4e207404cecbb2e6e Mon Sep 17 00:00:00 2001 From: Hang Yin Date: Sat, 13 Sep 2025 07:26:32 +0000 Subject: [PATCH 1/3] dip-330: self-describing hash --- DIPs/dip-330.md | 117 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 DIPs/dip-330.md diff --git a/DIPs/dip-330.md b/DIPs/dip-330.md new file mode 100644 index 00000000..9895a6b4 --- /dev/null +++ b/DIPs/dip-330.md @@ -0,0 +1,117 @@ +--- +dip: 330 +title: Self-Describing Hash Format for Attestation ReportData +status: Draft +author: Hang Yin +created: 2025-09-13 +--- + +## Abstract + +This DIP specifies a compact, self-describing hash string format that fits within the strict 64-byte limit of Intel DCAP’s `reportdata` field. The format includes a purpose prefix and algorithm identifier to improve readability, domain separation, and verifiability: + +``` +:: +``` + +The format is directly designed for remote attestation use cases. Other applications may adopt it, but they are out of scope for this proposal. + +## Motivation + +Intel DCAP’s remote attestation `reportdata` field provides exactly 64 bytes for application-defined data. Existing hash formats either: + +* Overflow the field (e.g. Docker’s `sha256:` representation), +* Omit algorithm metadata (bare digests), or +* Lack a way to indicate purpose/domain. + +To solve this, we propose a representation that: + +1. Explicitly encodes the **algorithm** (`sha-256`), +2. Uses **base64url encoding** for compactness, +3. Adds a **purpose prefix** for human readability and domain separation, +4. Always fits within the 64-byte `reportdata` field (for SHA-256). + +This enables straightforward claim verification in remote attestation workflows without extra metadata. + +## Specification + +The format is: + +``` +:: +``` + +* **purpose**: Short identifier (≤10 characters recommended). Examples: `attest`, `claim`. +* **algo**: Lowercase algorithm identifier with optional dash, e.g. `sha-256`. +* **base64url-hash**: Digest of the preimage, encoded in URL-safe Base64 without padding (`=`). + +Separators: two colons (`:`). + +### Size Constraints + +For SHA-256: + +* Digest (base64url, no padding): 43 characters +* Algorithm (`sha-256`): 7 characters +* Purpose: up to 10 characters (recommended) +* Separators: 2 characters + +**Total: 62 characters**, under the 64-byte maximum. + +Longer digests (e.g. SHA-512, 86 chars in base64url) will not fit. Therefore, **SHA-256 is the normative algorithm** for attestation `reportdata`. + +### Example + +``` +attest:sha-256:7zYbTVHDz2A3sfmGdPZLhv17Qrs5X7s1U6B7YyBR9nM +``` + +* `attest`: purpose +* `sha-256`: algorithm +* `7zYb...9nM`: base64url digest + +## Rationale + +* **Purpose prefix** improves readability and domain separation (e.g. differentiating attestation claims vs. config hashes). +* **Algorithm field** avoids ambiguity and enables algorithm agility. +* **Base64url encoding** is compact (43 chars vs. 64 hex chars for SHA-256) and URL-safe. +* **Colon separator** is widely used (e.g. Docker digests, URIs) and compatible with base64 encoding, and algorithm names containing hyphens. + +## Implementation Notes + +This format can reuse existing parsing and serialization libraries: + +* **ni:// (RFC 6920)** already uses `algo;base64url-digest`. Libraries exist in Python (`rfc6920`), Go, Ruby, Perl. +* **SRI strings** (`algo-base64digest`) are supported by the Node.js `ssri` package and browsers. + +By simply converting to/from `:`, developers can leverage these mature libraries for digest verification and serialization, minimizing new code. + +## Backwards Compatibility + +This is a new format, scoped for Intel DCAP remote attestation. No existing systems are broken. Other contexts may adopt it later, but that is not addressed in this DIP. + +## Security Considerations + +* Security strength derives from the algorithm (SHA-256 recommended). +* Purpose is metadata only and not cryptographically bound unless explicitly included in the preimage. +* Implementations must ensure canonical encoding: lowercase algorithm names, no padding, and URL-safe characters only. + +## Test Vectors + +| Preimage | Purpose | Algorithm | Base64url Digest | Full String | +| --------------------------- | ------- | --------- | --------------------------------------------- | ------------------------------------------------------------ | +| `"hello"` (0x68656c6c6f) | attest | sha-256 | `LPJNul-wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ` | `attest:sha-256:LPJNul-wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ` | +| `"dstack"` (0x64737461636b) | claim | sha-256 | `FPBeUtMvvR54kqX8DSmVNzKiaLvtGPpqna9xvv6l6ws` | `claim:sha-256:FPBeUtMvvR54kqX8DSmVNzKiaLvtGPpqna9xvv6l6ws` | + +> All digests shown are base64url-encoded SHA-256 values without padding. + +## References + +* [Intel SGX DCAP Attestation Architecture](https://www.intel.com/content/www/us/en/developer/articles/technical/intel-software-guard-extensions-data-center-attestation-primitives.html) +* [RFC 6920: Naming Things with Hashes (ni://)](https://www.rfc-editor.org/rfc/rfc6920) +* [W3C Subresource Integrity (SRI)](https://www.w3.org/TR/SRI/) +* [Docker/OCI Image Manifest Specification](https://github.com/opencontainers/image-spec) + +## Copyright + +Copyright and related rights waived via CC0. From 703384837052c654e4c0f542a0e54ce0c53664e8 Mon Sep 17 00:00:00 2001 From: Kevin Wang Date: Thu, 9 Oct 2025 02:58:03 +0000 Subject: [PATCH 2/3] Refactor dip-1 according to comments in issue #330 --- DIPs/dip-1.md | 114 ++++++++++++++++++++++++++++++++++++++++++++++ DIPs/dip-330.md | 117 ------------------------------------------------ 2 files changed, 114 insertions(+), 117 deletions(-) create mode 100644 DIPs/dip-1.md delete mode 100644 DIPs/dip-330.md diff --git a/DIPs/dip-1.md b/DIPs/dip-1.md new file mode 100644 index 00000000..f365b891 --- /dev/null +++ b/DIPs/dip-1.md @@ -0,0 +1,114 @@ +--- +dip: 1 +title: Self-Describing Identifiers for Attestation ReportData +status: Draft +author: Hang Yin +created: 2025-09-13 +--- + +## Abstract + +This DIP defines `dip1`, a compact self-describing identifier that fits within the 64-byte Intel DCAP `reportdata` field. A fixed scope prefix (`dip1`) is followed by an algorithm label and either a digest or inline payload. The canonical form for hashed payloads is: + +``` +dip1:: +``` + +The actual payload, which encodes purpose/content-type metadata, is transmitted or embedded separately. An inline variant allows very small payloads to fit entirely inside the identifier. + +## Motivation + +Attestation workflows need a short, unambiguous identifier for application-defined data that can be carried inside `reportdata`. Without such structure, a verifier that receives a TDX quote can only check the quote envelope itself; it has no portable way to interpret what the embedded `reportdata` is supposed to prove. + +By reserving the `dip1` prefix and standardising how algorithms and payload descriptors appear in the identifier, we make `reportdata` self-describing without exceeding the 64-byte budget. A verification platform can inspect the `dip1` string to learn which hash algorithm was used and what content type the payload represents, then route the quote to specialised validation plugins whenever they are available. + +## Specification + +The general grammar is: + +``` +dip1:: +``` + +* `dip1`: Literal ASCII prefix reserving the namespace for this format. +* ``: Lowercase token indicating how to interpret ``. +* ``: Algorithm-dependent ASCII payload. + +### Hashed payloads + +For cryptographic digests: + +``` +dip1:sha256: +``` + +* `` is the URL-safe Base64 (unpadded) encoding of a SHA-256 digest (43 characters). +* The digest is computed over a canonical payload byte string supplied alongside the attestation evidence. The payload SHOULD begin with its own content-type prefix, e.g. `ratls-pubkey:`. +* Other algorithms MAY be supported in the future, but **SHA-256 is normative** for interoperability. + +### Inline payloads + +Short payloads can be embedded directly using the reserved `inline` algorithm: + +``` +dip1:inline:: +``` + +* ``: Short token (≤8 characters recommended) describing the payload, e.g. `ra-pk`. +* ``: URL-safe Base64 (unpadded) encoding of the raw payload bytes. +* Inline payloads MUST keep the entire identifier within 64 bytes. + +For maximal brevity, the `inline` algorithm MAY be omitted. The double-colon form is an alias for the inline variant: + +``` +dip1::: +``` + +### Size considerations + +For the SHA-256 variant: + +* Prefix + separators: `dip1:` (5 chars) + second colon (1 char) +* Algorithm token: `sha256` (6 chars) +* Digest: 43 chars + +Total: 55 characters, fitting comfortably within the 64-byte requirement. + +For inline payloads, the combined length of `` and `` MUST keep the string within 64 characters. + +## Rationale + +* Fixed namespace (`dip1`) prevents collisions with other project-defined encodings. +* Algorithm tag enables future extensions without ambiguity. +* Separating purpose metadata into the payload simplifies domain separation and allows richer payload structures. +* Base64url encoding maximises information density while remaining safe for textual channels. + +## Implementation Notes + +* Existing digest libraries can be reused by serialising payloads as `:` before prefixing with `dip1:`. +* Canonical payload serialisation (e.g. `content-type:value`) should be specified by higher-level protocols. +* Inline payloads are best suited for small tokens such as capability flags or truncated keys. + +## Security Considerations + +* Security strength is determined by the chosen algorithm (SHA-256 recommended). +* Payload canonicalisation must be consistent to avoid digest mismatches. +* Inline payloads are not hashed; consumers must validate them according to application policy. + +## Test Vectors + +| Case | Identifier | Payload (when hashed) | +| ------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | +| SHA-256 of payload | `dip1:sha256:HmdI7tOxX-IxZngR8Aok9miZ4A5DzUj-HW-VUZ1Et0E` | `ratls-pubkey:ee218f44a5f0a9c3233f9cc09f0cd41518f376478127feb989d5cf1292c56a01` | +| Inline ra-pk sample | `dip1:inline:ra-pk:LPJNul-wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ` | _Embedded in identifier_ | +| Inline alias (short form) | `dip1::ra-pk:LPJNul-wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ` | _Embedded in identifier_ | + +## References + +* [Intel SGX DCAP Attestation Architecture](https://www.intel.com/content/www/us/en/developer/articles/technical/intel-software-guard-extensions-data-center-attestation-primitives.html) +* [RFC 6920: Naming Things with Hashes (ni://)](https://www.rfc-editor.org/rfc/rfc6920) +* [W3C Subresource Integrity (SRI)](https://www.w3.org/TR/SRI/) + +## Copyright + +Copyright and related rights waived via CC0. diff --git a/DIPs/dip-330.md b/DIPs/dip-330.md deleted file mode 100644 index 9895a6b4..00000000 --- a/DIPs/dip-330.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -dip: 330 -title: Self-Describing Hash Format for Attestation ReportData -status: Draft -author: Hang Yin -created: 2025-09-13 ---- - -## Abstract - -This DIP specifies a compact, self-describing hash string format that fits within the strict 64-byte limit of Intel DCAP’s `reportdata` field. The format includes a purpose prefix and algorithm identifier to improve readability, domain separation, and verifiability: - -``` -:: -``` - -The format is directly designed for remote attestation use cases. Other applications may adopt it, but they are out of scope for this proposal. - -## Motivation - -Intel DCAP’s remote attestation `reportdata` field provides exactly 64 bytes for application-defined data. Existing hash formats either: - -* Overflow the field (e.g. Docker’s `sha256:` representation), -* Omit algorithm metadata (bare digests), or -* Lack a way to indicate purpose/domain. - -To solve this, we propose a representation that: - -1. Explicitly encodes the **algorithm** (`sha-256`), -2. Uses **base64url encoding** for compactness, -3. Adds a **purpose prefix** for human readability and domain separation, -4. Always fits within the 64-byte `reportdata` field (for SHA-256). - -This enables straightforward claim verification in remote attestation workflows without extra metadata. - -## Specification - -The format is: - -``` -:: -``` - -* **purpose**: Short identifier (≤10 characters recommended). Examples: `attest`, `claim`. -* **algo**: Lowercase algorithm identifier with optional dash, e.g. `sha-256`. -* **base64url-hash**: Digest of the preimage, encoded in URL-safe Base64 without padding (`=`). - -Separators: two colons (`:`). - -### Size Constraints - -For SHA-256: - -* Digest (base64url, no padding): 43 characters -* Algorithm (`sha-256`): 7 characters -* Purpose: up to 10 characters (recommended) -* Separators: 2 characters - -**Total: 62 characters**, under the 64-byte maximum. - -Longer digests (e.g. SHA-512, 86 chars in base64url) will not fit. Therefore, **SHA-256 is the normative algorithm** for attestation `reportdata`. - -### Example - -``` -attest:sha-256:7zYbTVHDz2A3sfmGdPZLhv17Qrs5X7s1U6B7YyBR9nM -``` - -* `attest`: purpose -* `sha-256`: algorithm -* `7zYb...9nM`: base64url digest - -## Rationale - -* **Purpose prefix** improves readability and domain separation (e.g. differentiating attestation claims vs. config hashes). -* **Algorithm field** avoids ambiguity and enables algorithm agility. -* **Base64url encoding** is compact (43 chars vs. 64 hex chars for SHA-256) and URL-safe. -* **Colon separator** is widely used (e.g. Docker digests, URIs) and compatible with base64 encoding, and algorithm names containing hyphens. - -## Implementation Notes - -This format can reuse existing parsing and serialization libraries: - -* **ni:// (RFC 6920)** already uses `algo;base64url-digest`. Libraries exist in Python (`rfc6920`), Go, Ruby, Perl. -* **SRI strings** (`algo-base64digest`) are supported by the Node.js `ssri` package and browsers. - -By simply converting to/from `:`, developers can leverage these mature libraries for digest verification and serialization, minimizing new code. - -## Backwards Compatibility - -This is a new format, scoped for Intel DCAP remote attestation. No existing systems are broken. Other contexts may adopt it later, but that is not addressed in this DIP. - -## Security Considerations - -* Security strength derives from the algorithm (SHA-256 recommended). -* Purpose is metadata only and not cryptographically bound unless explicitly included in the preimage. -* Implementations must ensure canonical encoding: lowercase algorithm names, no padding, and URL-safe characters only. - -## Test Vectors - -| Preimage | Purpose | Algorithm | Base64url Digest | Full String | -| --------------------------- | ------- | --------- | --------------------------------------------- | ------------------------------------------------------------ | -| `"hello"` (0x68656c6c6f) | attest | sha-256 | `LPJNul-wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ` | `attest:sha-256:LPJNul-wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ` | -| `"dstack"` (0x64737461636b) | claim | sha-256 | `FPBeUtMvvR54kqX8DSmVNzKiaLvtGPpqna9xvv6l6ws` | `claim:sha-256:FPBeUtMvvR54kqX8DSmVNzKiaLvtGPpqna9xvv6l6ws` | - -> All digests shown are base64url-encoded SHA-256 values without padding. - -## References - -* [Intel SGX DCAP Attestation Architecture](https://www.intel.com/content/www/us/en/developer/articles/technical/intel-software-guard-extensions-data-center-attestation-primitives.html) -* [RFC 6920: Naming Things with Hashes (ni://)](https://www.rfc-editor.org/rfc/rfc6920) -* [W3C Subresource Integrity (SRI)](https://www.w3.org/TR/SRI/) -* [Docker/OCI Image Manifest Specification](https://github.com/opencontainers/image-spec) - -## Copyright - -Copyright and related rights waived via CC0. From c44cee77269ec68bfc505fed5bdaf19bdd84b7b2 Mon Sep 17 00:00:00 2001 From: Kevin Wang Date: Thu, 9 Oct 2025 03:09:40 +0000 Subject: [PATCH 3/3] chore: Table header --- DIPs/dip-1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DIPs/dip-1.md b/DIPs/dip-1.md index f365b891..c5980410 100644 --- a/DIPs/dip-1.md +++ b/DIPs/dip-1.md @@ -97,7 +97,7 @@ For inline payloads, the combined length of `` and `` M ## Test Vectors -| Case | Identifier | Payload (when hashed) | +| Case | Report data | Outband payload | | ------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | SHA-256 of payload | `dip1:sha256:HmdI7tOxX-IxZngR8Aok9miZ4A5DzUj-HW-VUZ1Et0E` | `ratls-pubkey:ee218f44a5f0a9c3233f9cc09f0cd41518f376478127feb989d5cf1292c56a01` | | Inline ra-pk sample | `dip1:inline:ra-pk:LPJNul-wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ` | _Embedded in identifier_ |