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.