Proof Format Specification

Overview

StampedSafe proofs are self-contained, cryptographically signed attestations that can be verified without any external service. Each proof contains all information needed to verify its authenticity and integrity.

Proofs are designed for long-term verifiability. Old proofs will continue to verify correctly even as the protocol evolves.

Proof Structure

A StampedSafe proof is a JSON object with the following fields:

{
  "id": string,      // 24-character hex identifier
  "payload": {
    "v": string,     // Protocol version ("1.0" or "1.1")
    "alg": string,   // Algorithm identifier ("Ed25519+SHA256")
    "t": number,     // Unix timestamp (milliseconds)
    "tz": string,    // IANA timezone identifier
    "h": string,     // SHA-256 hash of message (hex)
    "m": string,     // Message content (max 280 chars)
    "n": string,     // Random nonce (hex, 16 bytes)
    "pk": string,    // Ed25519 public key (hex)
    "f": {           // Optional file attachment
      "name": string,
      "size": number,
      "hash": string,  // SHA-256 hash (hex)
      "type": string   // MIME type
    },
    "ta": {          // Optional time attestation (v1.1+)
      "ts": number,    // Server timestamp (ms)
      "iso": string,   // ISO 8601 UTC string
      "exp": number,   // Expiration timestamp
      "kid": string,   // Key ID
      "nonce": string, // Anti-replay nonce
      "sig": string,   // Server signature (hex)
      "pk": string     // Server public key (hex)
    }
  },
  "sig": string,     // Ed25519 signature (hex)
  "level": number    // Trust level (1=self, 2=server-time)
}

Field Details

id

A 12-character hexadecimal string derived from the first6 bytes of the SHA-256 hash of the canonicalized payload.

payload.v

Protocol version string. Supported: "1.0" (original), "1.1" (with time attestation)

payload.alg

Algorithm identifier string. Format: "signing_algorithm-hash_algorithm". Current: "Ed25519+SHA256" (Ed25519 signatures with SHA-256 hashing).

payload.t

Unix timestamp in milliseconds. In v1.1, this comes from the server-signed time attestation. In v1.0, it uses the client's local clock.

payload.tz

IANA timezone identifier (e.g., "America/New_York") at time of creation.

payload.h

64-character hexadecimal SHA-256 hash of the message content.

payload.m

The message content being attested. Maximum 280 characters. May be empty string if only attesting a file.

payload.n

32-character hexadecimal random nonce ensuring unique proofs for identical content.

payload.pk

64-character hexadecimal Ed25519 public key generated for this proof.

payload.f

Optional file attachment metadata. Contains name, size, SHA-256 hash, and MIME type. The file content itself is never transmitted.

payload.ta

Optional time attestation (v1.1+). Server-signed timestamp proving when the proof was created. Contains timestamp, server signature, and public key.

sig

128-character hexadecimal Ed25519 signature of the proof ID bytes, created using an ephemeral keypair generated for this proof.

level

Integer verification level. Level 1 = self-attested (device time). Level 2 = server-attested time (verified by StampedSafe time authority).

Cryptographic Algorithms

Hashing: SHA-256

All hashing uses SHA-256 as specified in FIPS 180-4. This includes:

• Message content hashing (payload.h)
• File content hashing (payload.f.hash)
• Proof ID derivation from canonicalized payload

Signing: Ed25519

Digital signatures use Ed25519 as specified in RFC 8032. Each proof generates an ephemeral keypair:

• A new Ed25519 keypair is generated for each proof
• The public key is included in the payload
• The private key signs the proof ID and is then securely wiped
• This ensures proofs are self-verifying without external key management

Canonicalization

Before hashing, the payload is canonicalized to JSON Canonicalization Scheme (JCS, RFC 8785). This ensures identical payloads produce identical hashes regardless of JSON formatting.

Verification Process

To verify a StampedSafe proof:

1. Version Check
   Confirm payload.v equals a supported version number.
2. Algorithm Check
   Confirm payload.alg equals a supported algorithm identifier.
3. Message Hash Verification
   Compute SHA-256(payload.m) and verify it equals payload.h.
4. ID Verification
   Canonicalize the payload using JCS, compute SHA-256, and verify the first6 bytes (as hex) equal the proof ID.
5. Signature Verification
   Using the public key in payload.pk, verify the Ed25519 signature in sig over the full SHA-256 hash of the canonicalized payload.

A proof is valid if and only if all five checks pass. Verification can be performed entirely offline using only the proof JSON.

Versioning Policy

Backward Compatibility

StampedSafe maintains strict backward compatibility. Proofs created with any version will continue to verify correctly with all future versions of the verification software.

Version History

Future Changes

Future versions may add new optional fields or support additional algorithms while maintaining verification of all prior versions.

Test Vectors

The following test vectors can be used to verify conformance of StampedSafe implementations. All implementations MUST pass these tests.

Vector 1: Basic Message Proof

Input message: "Hello, World!"

Message Hash (SHA-256):
dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f

Given payload fields:
- v: "1.0"
- alg: "Ed25519+SHA256"
- t: 1735689600000 (2025-01-01 00:00:00 UTC)
- tz: "UTC"
- m: "Hello, World!"
- h: "dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f"
- n: "0123456789abcdef0123456789abcdef"
- pk: (varies by keypair)

Verification: Hash of message must match h field.

Vector 2: Empty Message with File

Tests file-only proof verification:

Empty message hash:
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

File attachment:
- name: "document.pdf"
- size: 1024
- hash: "abc123..." (SHA-256 of file content)
- type: "application/pdf"

Verification: Empty string hash + valid file metadata.

Vector 3: Signature Verification

Tests Ed25519 signature validation:

Verification steps:
1. Canonicalize payload to JCS format
2. Compute SHA-256 of canonicalized payload
3. First 6 bytes (12 hex chars) = proof ID
4. Verify Ed25519(sig, full_hash, pk) = true

Invalid if:
- Signature doesn't match
- Public key format invalid
- Hash mismatch at any step

Conformance Requirements

• All SHA-256 outputs must be lowercase hex
• All Ed25519 outputs must be lowercase hex
• Timestamps must be integer milliseconds
• JSON canonicalization must follow RFC 8785
• Invalid proofs must return clear error codes

Reference Implementation

The official reference implementation is available at github.com/stampedsafe.

For questions about the specification or implementation, contact dev@stampedsafe.com.