Skip to content

ISCC Signature Specification#

This specification defines a simple JSON signature format for ISCC metadata using EdDSA signatures and JSON Canonicalization Scheme (JCS).

Why a Custom Signature Format?#

The ISCC framework requires a signature format that balances simplicity, flexibility, and standards compliance:

  • Simplicity: Unlike complex standards like JSON-LD signatures or JWT, ISCC signatures are straightforward JSON objects that developers can implement without extensive cryptographic libraries
  • Flexibility: The format supports three verification modes (proof-only, self-verifying, identity-bound) allowing use cases from simple integrity checks to full identity verification
  • Minimal Dependencies: Uses only Ed25519 and JCS, avoiding heavyweight dependencies like JSON-LD processors or JWT libraries
  • Identity Agnostic: Works with any identity system (DIDs, CIDs, URLs) without requiring specific identity infrastructure
  • Backward Compatible: The simple structure ensures long-term stability and easy migration paths

Overview#

ISCC Signatures add a signature object to any JSON document, providing cryptographic integrity and optional identity attribution. The signature is computed over the entire JSON object using JCS canonicalization.

Signature Format#

{
  "your": "data",
  "signature": {
    "version": "ISCC-SIG v1.0",
    "controller": "<optional-identity-uri>",
    "keyid": "<optional-key-identifier>",
    "pubkey": "<optional-multibase-public-key>",
    "proof": "<multibase-signature>"
  }
}

Fields#

  • version (required): Must be "ISCC-SIG v1.0"
  • controller (optional): URI identifying the key controller (e.g., DID or CID)
  • keyid (optional): Specific key identifier within the controller document
  • pubkey (optional): Ed25519 public key in multibase format (z-base58-btc with ED01 prefix)
  • proof (required): EdDSA signature in multibase format (z-base58-btc)

Signature Types#

PROOF_ONLY#

Minimal signature containing only version and proof. Requires out-of-band public key for verification.

SELF_VERIFYING#

Includes the public key for standalone verification without external dependencies.

IDENTITY_BOUND#

Includes controller URI and public key for full attribution and identity verification.

AUTO (default)#

Includes all available fields from the signing keypair.

Signing Process#

  1. Ensure input JSON has no existing signature field
  2. Create a copy and add signature object with:
    • version: "ISCC-SIG v1.0"
    • Optional fields based on signature type
  3. Canonicalize the entire object using JCS
  4. Sign the canonical bytes with Ed25519
  5. Encode signature as multibase (z-base58-btc)
  6. Add signature to signature.proof field

Verification Process#

  1. Extract and validate signature object:
    • Check version equals "ISCC-SIG v1.0"
    • Extract proof field
  2. Obtain public key from:
    • signature.pubkey field (if present)
    • External parameter (if provided)
  3. Create copy without signature.proof field
  4. Canonicalize using JCS
  5. Verify EdDSA signature against canonical bytes

Identity Verification (Optional)#

When an identity document is provided:

  1. Check if signature.controller exists
  2. Verify the public key is authorized in the identity document's verificationMethod array
  3. Match verification methods by:
    • Same controller URI AND
    • Same public key value (publicKeyMultibase)
    • If keyid is provided: also match against verification method's id
    • If keyid is absent: the public key itself acts as the identifier

Implementation Requirements#

  • Cryptography: Ed25519 signatures per RFC 8032
  • Canonicalization: JSON Canonicalization Scheme (RFC 8785)
  • Encoding: Multibase z-base58-btc for keys and signatures
  • Public Keys: 34-byte format with 2-byte ED01 prefix + 32-byte key
  • Signatures: 64-byte Ed25519 signatures

ISCC Signature Example#

Keypair Information#

  • Public Key: z6MkpFpVngrAUTSY6PagXa1x27qZqgdmmy3ZNWSBgyFSvBSx
  • Secret Key: z3u2So9EAtuYVuxGog4F2ksFGws8YT7pBPs4xyRbv3NJgrNA
  • Controller: did:web:crypto.iscc.codes:alice

Controlled Identity Document#

Must be published at http://crypto.iscc.codes/alice/did.json:

{
  "id": "did:web:crypto.iscc.codes:alice",
  "verificationMethod": [
    {
      "id": "did:web:crypto.iscc.codes:alice#z6MkpFpVngrAUTSY6PagXa1x27qZqgdmmy3ZNWSBgyFSvBSx",
      "type": "Multikey",
      "controller": "did:web:crypto.iscc.codes:alice",
      "publicKeyMultibase": "z6MkpFpVngrAUTSY6PagXa1x27qZqgdmmy3ZNWSBgyFSvBSx"
    }
  ],
  "authentication": [
    "did:web:crypto.iscc.codes:alice#z6MkpFpVngrAUTSY6PagXa1x27qZqgdmmy3ZNWSBgyFSvBSx"
  ],
  "assertionMethod": [
    "did:web:crypto.iscc.codes:alice#z6MkpFpVngrAUTSY6PagXa1x27qZqgdmmy3ZNWSBgyFSvBSx"
  ],
  "capabilityDelegation": [
    "did:web:crypto.iscc.codes:alice#z6MkpFpVngrAUTSY6PagXa1x27qZqgdmmy3ZNWSBgyFSvBSx"
  ],
  "capabilityInvocation": [
    "did:web:crypto.iscc.codes:alice#z6MkpFpVngrAUTSY6PagXa1x27qZqgdmmy3ZNWSBgyFSvBSx"
  ]
}

Document to be Signed#

{
  "@context": "http://purl.org/iscc/context",
  "@type": "VideoObject",
  "$schema": "http://purl.org/iscc/schema",
  "iscc": "ISCC:KACYPXW445FTYNJ3CYSXHAFJMA2HUWULUNRFE3BLHRSCXYH2M5AEGQY",
  "name": "The Never Ending Story",
  "description": "a 1984 fantasy film co-written and directed by *Wolfgang Petersen*"
}

Example: IDENTITY_BOUND Signature#

Includes controller URI and public key for full attribution.

{
  "@context": "http://purl.org/iscc/context",
  "@type": "VideoObject",
  "$schema": "http://purl.org/iscc/schema",
  "iscc": "ISCC:KACYPXW445FTYNJ3CYSXHAFJMA2HUWULUNRFE3BLHRSCXYH2M5AEGQY",
  "name": "The Never Ending Story",
  "description": "a 1984 fantasy film co-written and directed by *Wolfgang Petersen*",
  "signature": {
    "version": "ISCC-SIG v1.0",
    "controller": "did:web:crypto.iscc.codes:alice",
    "pubkey": "z6MkpFpVngrAUTSY6PagXa1x27qZqgdmmy3ZNWSBgyFSvBSx",
    "proof": "z3fVSTAfmNZTp1unwoXsyQa9sUx7gAxaZVavBLEPA5muup5ukxbCrirS8jcuhKzvQ3kp6UCJz2RA5wkZhYZ49o5wr"
  }
}