How DIDComm works

How DIDComm v2.1 uses decentralised identifiers, messages, and envelopes to give parties authenticated, end-to-end encrypted communication, and what a mediator does.

Affinidi Messaging is built on DIDComm v2.1. This page explains the protocol’s building blocks: decentralised identifiers, the DIDComm message, the envelopes that sign and encrypt it, and the mediator that delivers it.

What is DIDComm

The DIDComm v2.1 protocol is an open standard for decentralised communication. It is built on Decentralised Identifiers (DIDs), which allow parties to exchange verifiable data such as credentials and establish secure communication channels without relying on centralised servers.

DIDComm fits the Self-Sovereign Identity (SSI) model. It acts as the communication layer that gives users full control over their privacy and identity during digital interactions.

Alice writes a DIDComm message to Bob. DIDComm signs it as Alice and encrypts it to Bob's key. The mediator stores and routes the encrypted message without being able to read it. DIDComm on Bob's side decrypts it with Bob's key and verifies Alice's signature, and Bob reads the verified message. Alice writes a DIDComm message to Bob. DIDComm signs it as Alice and encrypts it to Bob's key. The mediator stores and routes the encrypted message without being able to read it. DIDComm on Bob's side decrypts it with Bob's key and verifies Alice's signature, and Bob reads the verified message.

DIDComm v2.1 unlocks several key capabilities for secure, decentralised communication:

  • Verifiable Credential Exchange: Supports trusted issuance, transmission, and verification of digital credentials between holders and verifiers. This ensures data integrity and authenticity.

  • Encrypted AI Agent Communication: Enables confidential, end-to-end encrypted messaging between AI agents across different environments and transport layers.

  • Decentralised API Layer: Provides a secure, message-based alternative to traditional REST APIs. It offers strong message-level encryption that goes beyond standard transport-layer security.

Why use DIDComm

  • Trusted Digital Interaction: DIDComm uses DIDs to sign and verify message authenticity. Both parties can authenticate each other, reducing fraud risks, especially when interacting with businesses or AI agents.

  • Privacy by Design: Messages are sent with end-to-end encryption by default, minimising metadata exposure. This ensures that only the intended recipient can access the message content, while the messaging server or mediator sees only the routing metadata, such as the recipient and, for authcrypt, the sender.

  • End-to-end Encryption: Messages are encrypted using public key cryptography. The recipient’s public key, published via DID, ensures only the intended recipient can decrypt the content.

  • Interoperable and Transport-Agnostic: DIDComm works across devices and channels, including HTTP, WebSockets, and Bluetooth. It does not rely on transport security for trusted communication.

  • Flexible Implementation: DIDComm is modular and extensible. It supports diverse use cases, including RESTful APIs, and integrates with open standards like OID4VCI and OID4VP for credential exchange.

Key components

Decentralised Identifier (DID)

A DID is a globally unique identifier that enables secure interactions. It is central to Self-Sovereign Identity (SSI), which gives individuals control over their digital identity.

A DID has three parts, separated by colons. For example, in did:peer:2.VzDnaecahsBv8Wxte…:

PartExampleWhat it is
SchemedidAlways did.
DID methodpeerHow the DID is created and resolved.
Method-specific identifier2.VzDnaecahsBv8Wxte…Unique within the method.

DID resolution produces a DID Document containing public key details for encryption and verification, as well as service endpoints for authentication and messaging.

DIDComm Message

A JSON Web Message (JWM) is a lightweight, secure, and standardised format for structured communication using JSON. It includes headers, message types, routing metadata, and payloads designed to enable secure and interoperable communication across different systems.

Message format

The DIDComm message format defines how messages are structured for secure, interoperable communication between parties within a decentralised ecosystem.

{
    "id": "9c8dcdc3-b41c-46ed-8bae-9dd3ce016568",
    "typ": "application/didcomm-plain+json",
    "type": "https://affinidi.com/didcomm/protocols/1.0/data-response",
    "body": {
        "response_requested": true
    },
    "from": "did:peer:2.VzDnaecahsBv8WxteYAUfn8cSzZmZ5DKhtfLT1uKW52MpNzauu...",
    "to": [
        "did:web:mediator.example.com"
    ],
    "thid": null,
    "pthid": null,
    "extra_headers": {},
    "created_time": 1761540161,
    "expires_time": 1761540461,
    "from_prior": null,
    "attachments": []
}

Key properties of the DIDComm Message:

PropertyDescription
idA message ID, unique across all messages the sender sends.
typeA URI or a string that references a message schema or protocol definition. It helps agents understand how to process the message.
toAn array list of DIDs of the recipients.
fromThe DID of the sender.
thid / pthidThreading fields for message context, such as reply threads and conversation grouping.
expires_timeThe message expiry time used by the sender when they will consider the message as “expired”.
attachmentsContains external content within a message, such as documents, credentials, images, or other data, without embedding them directly in the message body.

For more details about the structure of DIDComm Message, refer to the  Plaintext Message Structure section of the DIDComm v2.1 specification.

DIDComm Envelopes

DIDComm messages can be composed into different formats, plaintext, signed, and encrypted. Within the DIDComm protocol, these formats are referred to as envelopes.

Plaintext

A message that is neither signed nor encrypted. Readable by anyone, with no integrity or authenticity guarantees.

Use when: Non-sensitive data, debugging, or as inner content wrapped by a signed or encrypted envelope.

Signed

Digitally signed but not encrypted. Anyone can read it, but the recipient can cryptographically prove who signed it. This property is called non-repudiation: the sender cannot deny having sent the message.

Use when: The message’s origin must be verifiable to the recipient or third parties.

Encrypted

Sealed for one or more recipients. Uses either authenticated or anonymous encryption.

  • authcrypt: proves the sender’s identity to the recipient. Intermediaries can see the sender’s key ID unless the message is also wrapped in anoncrypt.
  • anoncrypt: hides sender identity from the recipient and intermediaries.

Use when: Only the intended recipients should be able to read the message.

Combining DIDComm Envelopes

DIDComm envelopes can be nested to achieve specific combinations of the following security properties:

  • Confidentiality: Ensures that only intended recipients can read the message content. Mediators and intermediaries cannot read a message encrypted to its recipient.

  • Sender Authenticity: Allows recipients to verify the identity of the sender, ensuring the message originates from a trusted source.

  • Non-repudiation: Prevents the sender from denying that they sent the message, thanks to cryptographic signing.

  • Sender Anonymity: Protects the sender’s identity from being exposed to mediators or intermediaries during message routing, when the message is wrapped with anoncrypt.

Each combination below shows the security properties it provides. Choose based on your application’s requirements.

plaintext

No security properties. Readable by anyone.

signed(plaintext)

  • Sender Authenticity
  • Non-repudiation

anoncrypt(plaintext)

  • Confidentiality
  • Sender Anonymity

authcrypt(plaintext)

  • Confidentiality
  • Sender Authenticity

authcrypt(sign(plaintext))

  • Confidentiality
  • Sender Authenticity
  • Non-repudiation

anoncrypt(authcrypt(plaintext))

  • Confidentiality
  • Sender Authenticity
  • Sender Anonymity

anoncrypt(sign(plaintext)) All properties

  • Confidentiality
  • Sender Authenticity
  • Non-repudiation
  • Sender Anonymity

For the full list of envelope media types, see IANA Media Types in the DIDComm v2.1 specification.

Mediator (Agents)

A mediator is a messaging server that routes messages securely between parties, such as individuals, businesses, or AI agents. A mediator cannot read the content of a message encrypted to its recipient. It reads only the routing envelope, and anything sent to it in plaintext or encrypted to the mediator itself.

Mediators provide capabilities such as:

  • Message Routing: Mediators handle encrypted forward messages and pass them on to the intended recipient. The mediator opens only the forward wrapper to learn the next hop, and the inner message encrypted to the recipient stays unreadable to it.

  • Message Storage & Pickup: Temporarily store messages and enable asynchronous communication.

A DIDComm mediator stores and forwards messages for recipients who are offline, independent of the transport protocol.

What’s next

  Read more about DIDComm Mediator

  Integrate DIDComm for Dart

  Integrate DIDComm for Rust