Skip to content

ISCC Signature#

IEP: 0019
Title: ISCC Signature
Author: Titusz Pan tp@iscc.io
Comments: https://github.com/iscc/iscc-ieps/issues/26
Status: Draft
Type: Core
Standard: IEP
License: CC-BY-4.0
Created: 2026-07-03
Updated: 2026-07-03

Note

This document is a DRAFT intended as input to ISO TC 46/SC 9/WG 18 for a future revision of ISO 24138.

1. Introduction#

This proposal defines the ISCC signature format (ISCC-SIG), a compact JSON signature format that provides cryptographic integrity and optional identity attribution for JSON documents.

An ISCC signature is a plain JSON object embedded as the signature member of the document it signs. The format is built from two primitives — Ed25519 signatures (RFC 8032) and the JSON Canonicalization Scheme (RFC 8785) — and is implementable without JSON-LD processing or JOSE libraries. Three signature types support use cases ranging from bare integrity proofs to standalone offline verification and full identity attribution via W3C DIDs or Controlled Identifier Documents.

ISCC signatures authenticate the messages of the ISCC Discovery Protocol (IEP-0013) and can sign any JSON document, including ISCC metadata.

2. Terminology#

Controller : The entity that controls a signing key, identified by a DID or HTTPS URL.

Controller document : A W3C Controlled Identifier Document or DID document that lists the verification methods authorized by a controller.

Verification method : An entry in a controller document that expresses an authorized public key as a Multikey (publicKeyMultibase).

JCS : JSON Canonicalization Scheme as defined in RFC 8785.

Multibase : Self-describing base-encoding format. In this specification, multibase strings use the z prefix indicating base58-btc encoding.

Multicodec : Self-describing binary prefix that identifies the type of encoded key material.

3. Signature Format#

An ISCC signature shall be a JSON object carried as the top-level signature member of the JSON document it signs:

Table 1 – ISCC signature members

Member Presence Type Definition
version mandatory string Shall equal ISCC-SIG v1.0
proof mandatory multibase Ed25519 signature over the canonical document
pubkey conditional multibase Ed25519 public key with multicodec prefix 0xed01
controller optional URI DID or HTTPS URL identifying the key controller
keyid optional string Verification method identifier within the controller document

An ISCC signature shall satisfy the following constraints:

  1. pubkey, if present, shall decode to 34 bytes: the multicodec prefix 0xed01 followed by a 32-byte Ed25519 public key.
  2. proof shall decode to a 64-byte Ed25519 signature value.
  3. If controller is present, pubkey shall be present.
  4. If keyid is present, controller shall be present.
  5. Members not listed in Table 1 shall not be present.

ISCC signature example (SELF_VERIFYING)

{
  "hello": "world",
  "signature": {
    "version": "ISCC-SIG v1.0",
    "pubkey": "z6MkpFpVngrAUTSY6PagXa1x27qZqgdmmy3ZNWSBgyFSvBSx",
    "proof": "z5D274u1mgx4zgWgDZb2iJJJMGTPwDh6EgJjFdcTSwyXMH13Sb4HqmBF9JJRFTr7NJnpxHb2d4uvLZngdAoMeFDnk"
  }
}

3.1 Signature Types#

The signature type is not encoded explicitly; it follows from member presence:

Table 2 – ISCC signature types

Type Members present Verification
PROOF_ONLY version, proof Requires a public key obtained out of band
SELF_VERIFYING version, pubkey, proof Standalone
IDENTITY_BOUND version, controller, pubkey, proof, optionally keyid Standalone, with identity attribution

NOTE: Protocols that embed ISCC signatures can restrict the permitted types. The ISCC Discovery Protocol (IEP-0013) requires pubkey and does not accept PROOF_ONLY signatures.

4. Signing#

A signing party shall create an ISCC signature as follows:

  1. Verify that the JSON document to be signed has no signature member.
  2. Add a signature object containing version and the members of the selected signature type, without a proof member.
  3. Canonicalize the complete document with JCS and encode as UTF-8.
  4. Compute the Ed25519 signature over the canonical bytes in accordance with RFC 8032.
  5. Encode the signature value as multibase and set it as signature.proof.

If verification in step 1 fails, the signing party shall not create a signature and shall report an error.

NOTE: The proof member is absent — not empty — during canonicalization. The signed scope covers the complete document including version, pubkey, controller, and keyid; none of these members can be substituted after signing without invalidating the proof.

5. Verification#

A verifier shall verify an ISCC signature as follows:

  1. Verify that signature.version equals ISCC-SIG v1.0.
  2. Obtain the verification key from signature.pubkey or, if absent, from an out-of-band source.
  3. Create a copy of the signed document and remove signature.proof; all other members remain.
  4. Canonicalize the copy with JCS and encode as UTF-8.
  5. Verify the Ed25519 signature decoded from signature.proof over the canonical bytes against the verification key.

If any step fails, the verifier shall reject the signature.

A verifier that expects a specific signing key shall verify that signature.pubkey, if present, equals the expected key.

6. Identity Verification#

When controller is present, a verifier may additionally verify that the signing key is authorized by the identified controller:

  1. Obtain the controller document by dereferencing controller: did:key and did:web URIs in accordance with their DID method specifications; HTTPS URLs by fetching the Controlled Identifier Document published at the URL.
  2. Verify that the controller document lists a verification method that satisfies all of the following:
    • its controller property equals signature.controller;
    • its publicKeyMultibase property equals signature.pubkey;
    • if keyid is present: its id property, or the fragment of its id property, equals keyid.

The signature is attributed to the controller if and only if both steps succeed.

NOTE: When keyid is absent, the public key itself acts as the key identifier.

7. Security Considerations#

Implementations shall use a well-reviewed Ed25519 library and shall reject signatures with malleable encodings (RFC 8032). The JCS-canonicalized bytes are the integrity anchor: implementations should verify their JCS implementation against the test vectors of RFC 8785. An ISCC signature proves possession of the secret key over the signed content; it does not by itself prove freshness or prevent replay. Protocols that embed ISCC signatures shall add nonces or timestamps where replay matters (see IEP-0013). A PROOF_ONLY signature does not commit to a public key; the signed document alone does not identify the signer. Controller documents are mutable: identity verification reflects the controller document at resolution time, and controllers revoke or rotate keys by updating the document.

8. Test Vectors#

All test vectors use the following Ed25519 keypair. The secret key is multibase-encoded with the multicodec prefix 0x8026 (Ed25519 secret key). The keypair is published for testing and shall not be used operationally.

public key:  z6MkpFpVngrAUTSY6PagXa1x27qZqgdmmy3ZNWSBgyFSvBSx
secret key:  z3u2So9EAtuYVuxGog4F2ksFGws8YT7pBPs4xyRbv3NJgrNA
controller:  did:web:crypto.iscc.codes:alice

Ed25519 signature generation is deterministic. Conforming implementations shall reproduce the following signatures for the document {"hello": "world"}, where payload is the JCS-canonical UTF-8 signing input and proof is the resulting signature value:

PROOF_ONLY
payload: {"hello":"world","signature":{"version":"ISCC-SIG v1.0"}}
proof:   z5mGkSPsC8bSah37m7RfPsBDYSCWnJQbQYBAZQD9r2THDhSJqN5uzsXD2fvnKMswjCs6rMgwS4QK9z712GgdDceSu

SELF_VERIFYING
payload: {"hello":"world","signature":{"pubkey":"z6MkpFpVngrAUTSY6PagXa1x27qZqgdmmy3ZNWSBgyFSvBSx","version":"ISCC-SIG v1.0"}}
proof:   z5D274u1mgx4zgWgDZb2iJJJMGTPwDh6EgJjFdcTSwyXMH13Sb4HqmBF9JJRFTr7NJnpxHb2d4uvLZngdAoMeFDnk

IDENTITY_BOUND
payload: {"hello":"world","signature":{"controller":"did:web:crypto.iscc.codes:alice","pubkey":"z6MkpFpVngrAUTSY6PagXa1x27qZqgdmmy3ZNWSBgyFSvBSx","version":"ISCC-SIG v1.0"}}
proof:   z52f1T5wnmgAWVFz84PmCzF74s6PQRaSFZxo4GzBfEaZ95P4nMgvJVN37BHNxjjyxuUmGmptoAP8kBDxZ3C7XhoJP

9. References#

9.1 Normative#

9.2 Informative#