SSIMPL defines a self-sovereign identity framework backed by government-issued trust anchors and a peer-validated ledger.

Introduction

The internet has evolved rapidly, but with each iteration new challenges have emerged in protecting personal data. While legislation attempts to safeguard users’ rights, technical solutions are often necessary to prevent misuse and unauthorized access to sensitive information.

Current authentication and authorization methods rely heavily on centralized providers. OpenID Connect flows and other single sign-on mechanisms place identity management in the hands of commercial services, which cannot always guarantee the trustworthiness or privacy of the credentials they issue.

In contrast, physical-world identity verification relies on standardized, verifiable documents such as passports or driver’s licenses. Informal authorization uses signatures or initials, which provide contextually appropriate trust without centralized control. SSIMPL was designed to replicate these principles in the digital realm, providing self-sovereign, verifiable credentials while minimizing reliance on third-party intermediaries.

Overview

The SSIMPL protocol defines a Self-Sovereign Identity & Mondial Pseudonymous Ledger framework that allows individuals to maintain control over their digital identity while enabling verifiable credential issuance and revocation. It bridges physical trust anchors (e.g., ePassports) with digital identity systems, ensuring cryptographic verification without reliance on centralized authorities.

SSIMPL addresses several key problems:

1. User control over digital identity – eliminating reliance on centralized identity providers.
2. Verification of identities – ensuring online credentials correspond to real individuals using cryptographic proofs.
3. Sharing of identity-related data - allowing secure and transparent sharing of data

The protocol balances decentralization, peer authority, and optional server-assisted synchronization for efficiency and availability. Everything is made to be deterministic by default, so no authorities whatsoever are required except the one that signed the Trust Anchor (TA).

Identity Trust Model

SSIMPL identities are rooted in cryptographically verifiable credentials derived from Trust Anchors, such as government-issued ePassports. A valid wallet:

• MUST extract cryptographic material from a TA
• MUST perform an Active Authentication (AA) challenge.
• MUST derive a Verifiable Credential Root (VCR) tied to the user’s DID, as defined in [[DID]].

This ensures only owners of verifiable physical credentials can create valid DIDs.

Considerations

Identity is hard to verify by nature. Using a state-issued TA is not a perfect solution, but it's the best deterministic proof of (human) identity available at the moment.

Levels of Authentication

• Level 0: DID confirms human ownership (bot detection).
• Level 1: Level 0 + unverifiable attributes (e.g. the owners home address) requested via scope.
• Level 2: Level 1 + verifiable credentials requested via scope.

These different levels allow people to authenticate themselves on several levels, depending on the context. Say a person would like to order a product from a website. Using SSIMPL, the webshop could request a certain scope of credentials (like a shipping address). The owner of the identity could then approve or disapprove this request. This flow is very similar to Open ID Connect, except that there is no need for a 3rd party.

Roles

• Identity The owner of the TA.
• Wallet: The actual software responsible for encapsulating the owners TA.
• Peers: Mobile devices with the Wallet installed.
• Relay Peers: Servers that act both as Peers and distribution points, allowing other Peers to sync their ledger.

Wallet Specification

The wallet is a Self-Sovereign means of identification that can be installed and bootstrapped entirely independent of any authority. It solely relies on cryptographic proof. This cryptographic proof is contained within the so-called VCR. The Verifiable Credential Root is a VC, as defined in [[VC]], necessary to link the signer of this VC to the related public key & DID.

The VCR can also be used as the root of a chain of VCs. This way it can, either explicitly or implicitly, verify association to other credentials further up in the chain.

Wallet Requirements

Wallets MUST:

• Extract cryptographic material from a Trust Anchor (TA).
• Support Active Authentication challenge verification.
• Derive BIP32 keypairs (as defined in [[BIP32]]), from the BIP39 mnemonic (as defined in [[BIP39]]).
• Present the BIP39 mnemonic to the owner. Note: the BIP39 mnemonic should be stored redundantly, preferably offline.
• Store the master BIP32 keypair in a secure storage section of their device (e.g. Apple Keychain, Android Keystore).
• Sign and manage the VCR.
• Generate (BIP32 child) DIDs compliant with did:key for interoperability.
• Support JWT issuance and asymmetric key exchange.

Wallets SHOULD:

• Encrypt credentials for local storage.
• Extract and store additional VCs such as DG11 for user convenience.
• Send their signed VCR to Relay Peers.

Wallet Functionality

• Before any transaction, the Wallet MUST call either the Well-known Relay Peer, or one of it's known Relay Peers for the latest delta.
• If the Wallet is new, it must first be bootstrapped. Which means acquiring the full current Ledger. This is done by requesting delta's in chunks between epochs, starting with 0 (Unix Time). Until the Ledger is fully in place, the Wallet MUST NOT allow any transactions.
• Before any transaction, the Wallet MUST call either the Well-known Relay Peer, or one of it's known Relay Peers for the latest list of known Relay Peers.

Wallet Security

A SSIMPL Wallet has certain security scenario's that need to be addressed

• The owners TA is lost/stolen: The owner MUST revoke their current DID - No transactions can take place until a new TA has been used to bootstrap.
• The owners device is lost/stolen: The owner MUST use their BIP39 mnemonic to restore their Wallet on a new device, then the owner MUST revoke their current DID and reinitialize their wallet.
• The owners BIP39 mnemonic is lost/stolen: The owner MUST revoke their current DID and reinitialize their wallet. This will result in a double entry in respect to the same TA. But the 'older' one will be automatically ignored.
• The owners BIP39 mnemonic AND TA is lost/stolen: The owner MUST revoke their current DID (through Delegated Revocation) and reinitialize their wallet on a new device using a new TA.
• ⚠️The owners BIP39 mnemonic AND TA is lost/stolen AND Delegated Revocation hasn't been configured: There is currently no way to come back from this scenario. For 10 years since the VCR registration, a malicious actor could potentially impersonate the owner of the original Identity. SSIMPL implementations MUST therefore have a mandatory Delegated Revocation exchange flow.

Delegated Revocation

In order to mitigate the most dire scenario, SSIMPL offers a relatively straight-forward solution: two Peers (you and someone you trust, like a close relative) exchange a complete LedgerEntryRevocation. In case of emergency, either Peer can always revoke the other Peers DID. This is a two-sided solution of course: it provides a nice safety net, but also introduces another safety risk. For these kind of scenario's, there are rarely perfect solutions.

To support Delegated Revocation, an extra (otherwise optional) field is present: taId. Which allows future deny-listing of the use taId (e.g. the document number of the passport)

Example activation Process (in case of an ePassport)

1. User installs wallet.
2. Wallet prompts for MRZ line.
3. NFC scan and extraction of passport data.
4. Creation of Verifiable Credential Root (VCR).
5. BIP39 mnemonic generation (and presentation to the user).
6. BIP32 keypair derivation and storage.
7. Signing of the VCR.
8. Submission of the VCR to a Relay Peer.

Relay Peer Specification

The Relay Peer is a special kind of Peer in the sense that it is static and reachable over the internet on a fixed hostname. It acts like any other Peer, but it also adds a storage layer for the Ledger and serves as distribution point for the Ledger. All Relay Peers together form a subnetwork on which all other (mobile) Peers 'ride'. This is purely infrastructural to help communication between Peers. It doesn't give any special privileges or authorities to any of the Relay Peers and does therefore still fulfill all requirements to be called decentralized.

The well-known Relay Peer

In order to establish a stable network, there should always be one well-known Relay Peer, which allows another Relay Peer to find others within the network. It also serves as an entry point for freshly installed Wallets to bootstrap.

Relay Peer Responsibilities

• Announce themselves to a known (or the well-known) Relay Peer.
• Receive, validate and store new LedgerEntries.
• Receive, validate and store new LedgerEntryRevocations.
• Providing and storing a list of known Relay Peers for discovery.
• Responding to registration attempts from new Relay Peers.
• Gossiping about active Relay Peers.

Relay Peer Bootstrap and Verification

To enable deterministic network formation and secure onboarding of Relay Peers, the SSIMPL protocol defines a bootstrap and verification procedure.

The first time a new Relay Peer is bootstrapped, it MUST make itself known to a known (or a well-known Relay Peer, e.g., root.ssimpl.org) to obtain the first list of known Relay Peers. This is a hard-coded node that allows the network to kickstart itself and to have zero knowledge upfront when adding a new Relay Peer.

Relay Peer Registration

Upon first contact with the network, a new Relay Peer:

1. Contacts the Well-known Relay Peer (or another known Relay Peer) to announce its presence.
2. Provides its signed DID using the canonical SignatureEnvelope format.
3. Receives information about other Relay Peers in the network for further connections.
4. Requests delta's from one (or more) of the Relay Peers in the network in chunks based on the time between two epochs. Starting with 0 (Unix Time) if it has never been online and otherwise starting with the epoch it was last online.

Ledger Specification

The SSIMPL ledger is a deterministically canonical, peer-replicated structure tracking valid DIDs, maintained across Peers and Relay Peers.

Goals

• Track valid DIDs without a central authority.
• Support bounded state and deterministic pruning.
• Enable single-peer verification.
• Eventual consistency via optional gossip or client/server synchronization.
• Mobile-friendly operation for large ledgers (5–30 GB).

State and Canonical Construction

1. Filter expired entries based on did_expiry and GRACE_PERIOD.
2. Normalize entries into canonical byte format.
3. Sort lexicographically by did_expiry then by hash(did).
4. Compute root_hash using a Merkle tree over the current, complete, pruned ledger.

Merkle Tree

The SSIMPL ledger uses a Merkle tree to enable efficient verification of ledger state and individual entries.

Structure

• Leaves: Hashes of canonical ledger entries.
• Branches: Hashes of concatenated child nodes.
• Root: root_hash representing the current canonical ledger state.

Updates

1. New ledger entries are appended as leaves.
2. The affected branches are rehashed up to the root.
3. Pruning does not delete nodes; the canonical ledger for the current epoch defines which entries are considered valid.

Merkle Proofs

• To prove inclusion of a DID xyz, a peer can provide the leaf hash and the branch hashes up to root_hash.
• Other peers can recompute the root from the proof and verify it matches the canonical root_hash.

Relation to Checkpoints

• Checkpoints store a root_hash for a specific epoch.
• Peers can verify their ledger or deltas by starting from the latest checkpoint and applying updates.

Validation Rules

An entry is valid if:

1. current_time < did_expiry + GRACE_PERIOD.
2. hash(verifiable_credential_root.data) equals verifiable_credential_root.signature_document.message.
3. The public key in the DID matches signature_document.signature.public_key.
4. Signature verification succeeds: verify_signature( verifiable_credential_root.signature_document.message, verifiable_credential_root.signature_document.signature.value, verifiable_credential_root.signature_document.signature.public_key, verifiable_credential_root.signature_document.signature.algorithm )

Expired or invalid entries are ignored and removed during canonical construction.

Pruning and Mutability

• Peers MAY remove their own entries and expired entries. To revoke a DID:

  1. Store a revocation payload on the local Ledger.
  2. Store and submit a revocation payload to (Relay) Peers.

• Peers MUST NOT remove valid entries or modify others' entries.

• Deterministic pruning ensures consistent ledger state across peers.

Synchronization

• Peers exchange { epoch, root_hash } metadata.
• Matching hash: No action required.
• Hash mismatch: Request missing entries or snapshots.
• Iterative delta exchange ensures eventual convergence.
• Relay Peers act as distribution points while also validating entries.
• Stateless Relay Peers may bootstrap from peers but should persist data for efficiency.

Merkle Checkpoints

To enable efficient verification of ledger history and prevent forks from propagating, the SSIMPL protocol introduces Merkle checkpoints. These checkpoints allow peers to validate that their current ledger state stems from a previously agreed-upon canonical state.

Definition

A Merkle checkpoint is a snapshot of the canonical ledger at a given epoch, containing:

• epoch — The deterministic epoch number of the snapshot
• root_hash — The canonical ledger Merkle root at that epoch
• metadata (optional) — Any additional information, such as total entry count, checkpoint creator DID, or a reference timestamp

Purpose

Merkle checkpoints serve three main purposes:

1. Anchoring history — They provide a trusted reference point for peers to verify that their current ledger is an extension of a previous canonical state.
2. Fork detection — Peers can detect divergence by comparing their checkpointed root hash with peers’ reported checkpoints.
3. Efficient synchronization — When a peer joins the network or recovers from offline mode, it can request deltas starting from the latest known checkpoint rather than from the genesis ledger.

Creation and Storage

• Peers MAY create checkpoints at deterministic intervals (e.g., end of each epoch).
• Relay Peers SHOULD store checkpoints for availability, enabling efficient delta requests for mobile peers.
• Checkpoints themselves are immutable; once created, they cannot be modified or deleted.

Verification

To verify a ledger using a checkpoint:

1. Obtain the checkpoint for the target epoch (epoch, root_hash).
2. Compute the canonical ledger state from the checkpoint epoch to the current state.
3. Recompute the Merkle root for the resulting ledger.
4. Confirm that the recomputed root matches the current root_hash.

A mismatch indicates ledger tampering or divergence, and the peer MUST reject the inconsistent entries.

Pruning and Expiry

• Checkpoints older than a configurable retention window MAY be pruned to reduce storage overhead.
• Retention policies SHOULD be deterministic and consistent across peers to maintain canonical verification paths.

Security Considerations

• Checkpoint integrity — Checkpoints must be signed by the creating peer using their DID key.
• Fork prevention — Peers must reject any checkpoint that does not extend a known valid previous checkpoint.
• Replay attacks — Timestamps and epoch numbers help prevent replay of stale checkpoints.

Security Properties

• Single-peer revocation verification.
• Privacy-preserving registration.
• Resistance to illegal pruning and tampering.
• Bounded state growth.
• Eventual convergence under client/server synchronization.

Conclusion

SSIMPL provides a self-sovereign identity framework with a deterministic, peer-validated ledger, enabling secure, verifiable DIDs anchored in government-issued credentials.

All entries and operations are canonical, rule-derived, and independently verifiable by peers, ensuring a fully trustworthy and decentralized identity ecosystem.

Canonicalization Rules

To ensure that signatures are verifiable and consistent across all peers, every signed object in SSIMPL (including LedgerEntry and VerifiableCredentialRoot) MUST be serialized in a canonical form before hashing and signing. These rules remove ambiguity in encoding and field ordering, preventing mismatches between peers.

Object Serialization

1. Field Ordering
   • All objects MUST have their fields sorted lexicographically by key name.
   • Example: For {"b":2,"a":1}, canonical form is {"a":1,"b":2}.
2. Whitespace
   • No unnecessary whitespace is allowed.
   • Only minimal separators required by the serialization format are permitted.
3. Encoding
   • All strings MUST be UTF-8 encoded.
   • No BOM (Byte Order Mark) or non-standard characters are allowed.
4. Number Representation
   • Numbers MUST be represented without leading zeros (except zero itself) and without exponential notation.
   • Example: 1.0 → 1.0; 01 → invalid.

5. Boolean and Null

6. true, false, and null MUST use JSON literals exactly as shown (case-sensitive).

Nested Objects

• Recursion: Apply canonicalization rules recursively to all nested objects and arrays.
• Arrays MUST preserve element order.
• Elements MUST themselves be canonicalized if they are objects or arrays.

Signature Message

1. The message field in every SignatureEnvelope MUST be the hash of the canonical serialized data object.
2. Recommended hash function: SHA-256.
3. The hash input is strictly the canonical byte sequence of the data object (no additional metadata).
4. Signing the message binds the signer cryptographically to the exact canonical representation of the object.

Deterministic Encoding

There are many ways to encode raw bytes or strings, and more are being invented as we speak. It is highly inefficient to make these encodings contract-based. SSIMPL therefore highly recommends the use of the Multibase Data Format, as defined in [[Multibase]], which is deterministic.

• Multibase or Base64url encoding MUST be used consistently for any binary data (e.g., cryptographic proofs).
• Multibase-encoding SHOULD be used consistently for any binary data (e.g., cryptographic proofs).
• This ensures that all peers can reproduce the exact same byte sequence for verification.

Verification Procedure

To verify a signature:

1. Peer canonicalizes the data object according to the rules above.
2. Peer hashes the canonicalized bytes to compute the message.
3. Peer verifies that the computed message matches the message in signatureEnvelope.
4. Peer validates the signature using the provided publicKey and algorithm.
5. Only if all checks pass is the object considered valid.

Rationale

Canonicalization guarantees that:

• Signatures are deterministic and portable across implementations.
• Peers can independently verify credentials, ledger entries, and revocations.
• Forks, replay attacks, and accidental divergence due to encoding differences are prevented.

Canonical Signature Object Pattern

All cryptographically signed objects in SSIMPL MUST follow a uniform, canonical structure, known as the SignatureEnvelope**. This ensures consistency across all signed data, including ledger entries, Verifiable Credential Roots (VCR), revocations, and delta payloads.

Structure

Each signed object MUST include a SignatureEnvelope with the following structure:

• message — The cryptographic hash of the canonical serialization of the data object.
• signature — Object containing the signature itself:
  • publicKey — Base64url-encoded public key corresponding to the signing private key.
  • algorithm — Signature algorithm used (e.g., EdDSA, ECDSA).
  • value — Base64url-encoded signature value.
• signer — DID of the entity producing the signature.

Example (in JSON for clarity):

{
  "message": "<hash-of-canonical-data>",
  "signature": {
    "publicKey": "<multibase-encoded public key>",
    "algorithm": "<algorithm identifier>",
    "value": "<multibase-encoded signature>"
  },
  "signer": "<DID of signer>"
}

Usage

• Every signed object in SSIMPL, including LedgerEntry, VerifiableCredentialRoot, revocation entries, and delta updates, MUST include a signatureEnvelope.
• The message field MUST be derived from the canonical serialization of the associated data object, ensuring that identical logical objects produce identical hashes.
• This pattern guarantees interoperability, verifiability, and deterministic ordering for all signed objects across the network.

Rules and Notes

• Optional fields in the data object MUST NOT affect the canonical hash unless explicitly defined in the canonicalization rules.
• Implementations MUST reject signatures if the hash does not match the canonicalized data object.
• Adherence to this pattern is mandatory to ensure correct ledger validation, delta verification, and revocation processing.

This canonical signature object pattern provides a single, consistent approach for proving authorship and integrity across all SSIMPL objects.

SSIMPL API Specification

This section defines the reference API for Relay Peers in the SSIMPL protocol. It provides endpoints for DID registration, revocation, and ledger synchronization.

All requests MUST be authenticated using a Bearer token, containing a signed DID in the canonical SignatureEnvelope format, multibase-encoded.

You can also check the open-api spec here.

Endpoints

Register a Relay Peer

POST /peer

Purpose: Make a Relay Peer known to another Relay Peer.

Request payload: RelayPeerAnnouncement

Example:

{
  "data": {
    "did": "did:key:1234abc...example"
    "hostname": "some.hostname.org"
  },
  "signatureEnvelope": {
    ...
  }
}

Response: 201 CREATED

Perform a handshake

POST /peer/identity

Purpose: Allows (Relay) Peers to check the health an initial validity of the Relay Peer

Request payload SignedObject<DID>:

Example:

{
  "data":"did": "did:key:1234abc...example",
  "signatureEnvelope": {
    ...
  }
}

Response: 200 OK + SignedObject<DID>:

{
  "data":"did": "did:key:abc1234...example",
  "signatureEnvelope": {
    ...
  }
}

Request Ledger Delta

POST /ledger/delta

Purpose: Allows a Peer to request ledger entries that are newer than a given epoch, if the peer is out of sync.

Request payload LedgerDeltaRequest:

Example:

{
  "from": 42,
  "to": 420,
  "rootHash": "abcdef1234567890"
}

Response: 200 OK + LedgerDeltaResponse:

Example:

{
  "currentEpoch": 43,
  "authoritativeRootHash": "1234abcd5678ef90",
  "entries": [
    {
      "data": {
        "type":"ENTRY",
        "payload": {
          "verifiableCredentialRoot": {
            ...
          },
          "proof": {
            ...
          }
        },
      },
      "signatureEnvelope": {
        ...
      }
    },
    "data": {
        "type":"REVOCATION",
        "payload": {
          "did": "did:key:1234abc...example",
          "taId": "ABC1234XYZ",
        },
      },
      "signatureEnvelope": {
        ...
      }
    }
    "relayPeers": [
    {
      "data": {
        "did": ...,
        "hostname" ...,
      },
      "signatureEnvelope": {
        ...
      }
    }
  ]
}

Register a DID

POST /ledger

Purpose: Register a new DID on the ledger.

Request payload: LedgerEntry

Example:

{
  "data": {
    "verifiableCredentialRoot": {
      ...
    },
    "proof": {
      ...
    }
  },
  "signatureEnvelope": {
    ...
  }
}

Response: 201 CREATED

Revoke a DID

PUT /ledger

Purpose: Revoke a DID by submitting a revocation payload. Providing the taId means that the related TA can NEVER be used again to initialize a Wallet/register a DID. The taId is mandatory for Delegated Revocation.

Request payload: LedgerEntryRevocation

Example:

{
  "data": {
    "did": "did:key:z6Mkw...example",
    "taId": "(optional) ABC123XYZ"
  },
  "signatureEnvelope": {
    ...
  }
}

Response: 204 NO CONTENT

Shared Object Schemas

SignedObject (Signed<T>)

SignedObject: LedgerEntry

VerifiableCredentialRoot

SignedObject: LedgerEntryRevocation

Proof (Example, in case an ePassport is used as TA)

SignatureEnvelope

Signature

LedgerDeltaRequest

LedgerDeltaResponse

RelayPeerAnnouncement