Skip to content

dip-330: self-describing hash #331

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

dip-330: self-describing hash #331

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 117 additions & 0 deletions DIPs/dip-330.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
---
dip: 330
title: Self-Describing Hash Format for Attestation ReportData
status: Draft
author: Hang Yin <[email protected]>
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:

```
<purpose>:<algo>:<base64url-hash>
```

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:<hex>` 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>:<algo>:<base64url-hash>
```

* **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 `<algo>:<base64url-hash>`, 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.