Skip to content

Commit f678715

Browse files
h4x3rotabh4x3rotab
committed
dip-330: self-describing hash
1 parent ee04ffa commit f678715

1 file changed

Lines changed: 117 additions & 0 deletions

File tree

‎DIPs/dip-330.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
dip: 330
3+
title: Self-Describing Hash Format for Attestation ReportData
4+
status: Draft
5+
author: Hang Yin <hangyin@phala.network>
6+
created: 2025-09-13
7+
---
8+
9+
## Abstract
10+
11+
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:
12+
13+
```
14+
<purpose>:<algo>:<base64url-hash>
15+
```
16+
17+
The format is directly designed for remote attestation use cases. Other applications may adopt it, but they are out of scope for this proposal.
18+
19+
## Motivation
20+
21+
Intel DCAP’s remote attestation `reportdata` field provides exactly 64 bytes for application-defined data. Existing hash formats either:
22+
23+
* Overflow the field (e.g. Docker’s `sha256:<hex>` representation),
24+
* Omit algorithm metadata (bare digests), or
25+
* Lack a way to indicate purpose/domain.
26+
27+
To solve this, we propose a representation that:
28+
29+
1. Explicitly encodes the **algorithm** (`sha-256`),
30+
2. Uses **base64url encoding** for compactness,
31+
3. Adds a **purpose prefix** for human readability and domain separation,
32+
4. Always fits within the 64-byte `reportdata` field (for SHA-256).
33+
34+
This enables straightforward claim verification in remote attestation workflows without extra metadata.
35+
36+
## Specification
37+
38+
The format is:
39+
40+
```
41+
<purpose>:<algo>:<base64url-hash>
42+
```
43+
44+
* **purpose**: Short identifier (≤10 characters recommended). Examples: `attest`, `claim`.
45+
* **algo**: Lowercase algorithm identifier with optional dash, e.g. `sha-256`.
46+
* **base64url-hash**: Digest of the preimage, encoded in URL-safe Base64 without padding (`=`).
47+
48+
Separators: two colons (`:`).
49+
50+
### Size Constraints
51+
52+
For SHA-256:
53+
54+
* Digest (base64url, no padding): 43 characters
55+
* Algorithm (`sha-256`): 7 characters
56+
* Purpose: up to 10 characters (recommended)
57+
* Separators: 2 characters
58+
59+
**Total: 62 characters**, under the 64-byte maximum.
60+
61+
Longer digests (e.g. SHA-512, 86 chars in base64url) will not fit. Therefore, **SHA-256 is the normative algorithm** for attestation `reportdata`.
62+
63+
### Example
64+
65+
```
66+
attest:sha-256:7zYbTVHDz2A3sfmGdPZLhv17Qrs5X7s1U6B7YyBR9nM
67+
```
68+
69+
* `attest`: purpose
70+
* `sha-256`: algorithm
71+
* `7zYb...9nM`: base64url digest
72+
73+
## Rationale
74+
75+
* **Purpose prefix** improves readability and domain separation (e.g. differentiating attestation claims vs. config hashes).
76+
* **Algorithm field** avoids ambiguity and enables algorithm agility.
77+
* **Base64url encoding** is compact (43 chars vs. 64 hex chars for SHA-256) and URL-safe.
78+
* **Colon separator** is widely used (e.g. Docker digests, URIs) and compatible with base64 encoding, and algorithm names containing hyphens.
79+
80+
## Implementation Notes
81+
82+
This format can reuse existing parsing and serialization libraries:
83+
84+
* **ni:// (RFC 6920)** already uses `algo;base64url-digest`. Libraries exist in Python (`rfc6920`), Go, Ruby, Perl.
85+
* **SRI strings** (`algo-base64digest`) are supported by the Node.js `ssri` package and browsers.
86+
87+
By simply converting to/from `<algo>:<base64url-hash>`, developers can leverage these mature libraries for digest verification and serialization, minimizing new code.
88+
89+
## Backwards Compatibility
90+
91+
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.
92+
93+
## Security Considerations
94+
95+
* Security strength derives from the algorithm (SHA-256 recommended).
96+
* Purpose is metadata only and not cryptographically bound unless explicitly included in the preimage.
97+
* Implementations must ensure canonical encoding: lowercase algorithm names, no padding, and URL-safe characters only.
98+
99+
## Test Vectors
100+
101+
| Preimage | Purpose | Algorithm | Base64url Digest | Full String |
102+
| --------------------------- | ------- | --------- | --------------------------------------------- | ------------------------------------------------------------ |
103+
| `"hello"` (0x68656c6c6f) | attest | sha-256 | `LPJNul-wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ` | `attest:sha-256:LPJNul-wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ` |
104+
| `"dstack"` (0x64737461636b) | claim | sha-256 | `FPBeUtMvvR54kqX8DSmVNzKiaLvtGPpqna9xvv6l6ws` | `claim:sha-256:FPBeUtMvvR54kqX8DSmVNzKiaLvtGPpqna9xvv6l6ws` |
105+
106+
> All digests shown are base64url-encoded SHA-256 values without padding.
107+
108+
## References
109+
110+
* [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)
111+
* [RFC 6920: Naming Things with Hashes (ni://)](https://www.rfc-editor.org/rfc/rfc6920)
112+
* [W3C Subresource Integrity (SRI)](https://www.w3.org/TR/SRI/)
113+
* [Docker/OCI Image Manifest Specification](https://github.com/opencontainers/image-spec)
114+
115+
## Copyright
116+
117+
Copyright and related rights waived via CC0.

0 commit comments

Comments
 (0)