Private messaging (DIDComm)
DIDComm is a standard from the Decentralized Identity Foundation for sending messages between parties that are named by decentralized identifiers (DIDs). A message is encrypted to the keys of the person or Companion it is for, can prove who sent it, and does not care how it travels: HTTPS, a WebSocket, a QR code or a relay in the middle. The current version is 2.1 ; didcomm.org lists the protocols built on it.
Status. DIDComm Messaging v2.1 is mounted in Companion Memory at
GET /didcomm/did, POST /didcomm/oob, POST /didcomm/oob/parse, and
POST /didcomm/message (DidcommModule / DidcommController).
The agent creates and parses _oob= invitations offline (refusing _oobid=
remote URLs to prevent SSRF), unpacks and decrypts (authcrypt/anoncrypt)
envelopes, verifies JWS signatures, and handles trust-ping and
discover-features protocols. The feature is off by default behind
the ENABLE_DIDCOMM_MESSAGING=true feature flag. When disabled, all routes
return 404 Not Found.
How it sits next to KERI
Decentralized trust (KERI and ToIP) is about who a Companion is: identifiers that belong to their controller, and key histories that show when keys changed. DIDComm is about how to send that Companion something only it can read. They answer different questions, so Companion Memory keeps them apart and lets one plug into the other.
| KERI design | DIDComm | |
|---|---|---|
| Question it answers | Who is this Companion, and are these still its keys? | How do I send it something only it can read, and how does it know it came from me? |
| Identifiers | KERI identifiers (design). Today a key id in Companion Memory’s own did:keri:D form | did:key, did:peer and did:web |
| Changing keys | Key event logs and pre-rotation (design) | A did:key cannot rotate. A did:peer is made per relationship. A message can announce a move to a new DID |
| Delivery when the other side is offline | Not its job | Relays (“mediators”) hold and forward envelopes they cannot read |
| Status | Design only: no key event log exists in Companion Memory | Library built, not connected |
DIDComm never reads a key event log. It asks a resolver for the DID document of the other party and uses the keys that document lists. That is the join: a resolver for a conformant KERI-backed method such as did:webs would make a KERI identity a DIDComm identity without any change to how messages are built or checked.
did:keri is deliberately not accepted as a DIDComm identifier today. Companion Memory’s did:keri:D key id is its own spelling of an Ed25519 public key and not a CESR identifier, and there is no key event log behind it. A messaging layer that accepted it would encrypt to a name that looks like a KERI identifier and proves nothing a plain did:key does not.
The same Ed25519 key can carry three names with three different meanings:
| Name | What it proves |
|---|---|
did:keri:D<key> (Companion Memory) | The key. Not CESR, and no key event log |
did:key:z6Mk… | The key. It cannot rotate: a new key is a new identity |
the X25519 key derived from it, z6LS… | The key to encrypt to. It is the same key in a form Diffie-Hellman can use |
A Companion that already has an Ed25519 device key can therefore take part in DIDComm with no new key material. That is a statement about the key and not about KERI.
What a DIDComm message gives you
- Confidentiality. The message is encrypted to the keys the recipient’s DID document lists. A relay in the middle cannot read it.
- Integrity. Any change to the message, or to the list of recipients, breaks decryption.
- Authentication, if you choose it. An authenticated message proves to the recipient who sent it. Only the recipient can check this, and the recipient could have forged it, which is deliberate: it is how a private conversation differs from a signed statement.
- Proof for others, if you choose it. A signed message can be shown to a third party. Signing is optional because it costs you the ability to speak off the record.
- Threads and lifetimes. Messages carry thread identifiers, and an optional time after which the sender no longer stands behind them.
| Envelope | Who can read it | Proves the sender to the recipient | Provable to others |
|---|---|---|---|
| Anonymous | The recipient | No | No |
| Authenticated | The recipient | Yes | No |
| Signed, then encrypted anonymously | The recipient | Yes | Yes |
| Authenticated, with the sender hidden | The recipient | Yes | No |
In the last case a second, anonymous layer hides which key the sender used from the first relay on the route.
Sending through a relay
A Companion behind a home router cannot be reached directly. It publishes the address of a relay in its DID document, and senders wrap the message once for each relay on the way.
sequenceDiagram
autonumber
actor Alice as Alice's Companion
participant Relay as Relay (mediator)
actor Bob as Bob's Companion
Alice->>Alice: Encrypt the message to Bob's keys
Alice->>Alice: Wrap it in a "forward" for the relay
Alice->>Relay: Send the outer envelope
Relay->>Relay: Open the outer layer only.<br/>It reads "next: Bob" and an opaque blob
Relay->>Bob: Deliver the blob
Bob->>Bob: Decrypt, check the sender's key in Alice's DID documentThe relay learns where the envelope goes and how big it is. It never learns what is in it. The relay cannot change the message without Bob noticing, and it cannot make one up as Alice.
Identities Companion Memory can use
did:keyneeds no setup and no network. The identifier is the public key. It cannot change keys.did:peercarries its own keys and its delivery address inside the identifier. It is made for one relationship, so it does not link two relationships together.did:webis a document on a domain the owner controls. It suits organisations rather than people, and it is only as safe as the domain. When this is connected, the fetch must go through the same restricted outbound connection Companion Memory uses for peers; the library only builds the address and checks that the document that comes back is for the DID that was asked for.did:keriis refused, as explained above.
What is checked when a message arrives
The library accepts a message only when every one of these holds. The first failure is a refusal.
- The envelope is well formed and in a shape DIDComm allows. Nothing is guessed or repaired.
- A key this Companion holds is one of the recipients.
- For an authenticated message, the sender’s key is taken from the sender’s own DID document, in the section reserved for encryption keys. For a signed one, it is in the section reserved for authentication. A valid signature from a key the DID does not list for that purpose is not a signature by that DID.
- The message decrypts, or the signature verifies.
- The identities at every layer agree. The sender named in the message is the sender whose key opened it, and the message is addressed to the identity it was decrypted for.
- The message has not expired, allowing for a minute of clock difference.
- For a receiver that keeps a memory of what it has seen: the message has not arrived before.
The library also reports what was proven, separately from what the message says. A message sent anonymously may say it is from Alice. It is still reported as anonymous, because anyone can write that.
What stays private
- The reason for a refusal is not sent back. Every cryptographic failure looks the same, and a problem report carries a fixed code, so a failure does not tell an attacker which check to work around.
- A relay sees the recipient’s key identifier, the size and the timing. It does not see the content, and with a hidden sender it does not see the sender’s key.
- An invitation in a link or QR code is public. It holds no secrets, and any identifier in it should be replaced by a private one over the first encrypted exchange. Opening one does not authenticate whoever made it; the owner confirms the relationship.
- Asking what a Companion supports answers only with protocols it chooses to list, and only to a sender who has proven who they are.
Carrying other protocols
DIDComm carries any JSON message and attachments without changing them, so a document with its own signature survives the trip intact. Two projects Companion Memory is evaluating use it:
- The Trust Tasks registry defines a DIDComm binding : a Trust Task document is the body of an authenticated DIDComm message. Nothing in Companion Memory uses that binding yet.
- OpenVTC agents speak DIDComm v2, and prefer the newer Trust Spanning Protocol where both sides have it.
What exists today
| Capability | Status |
|---|---|
| Encrypt and decrypt authenticated and anonymous messages | Built as a library |
| Sign and verify messages, and sign then encrypt | Built as a library |
| Hide the sender from the first relay | Built as a library |
| Wrap a message for a route through relays, working out the route from DID documents | Built as a library (sending side) |
| Trust ping, feature discovery, problem reports, out-of-band invitations | Built as a library |
| Announce a move from one DID to another | Built as a library |
| Remember messages already seen, and answer a message | Built as a library, in memory only |
| Receive from the internet (an HTTP endpoint or a socket) | Not built |
| Run a relay, and hold messages for a Companion that is offline | Not built |
| Keep keys in the device keychain, keep the memory of seen messages across restarts | Not built |
Identities backed by a KERI key event log (did:webs) | Not built |
did:webvh, and did:peer in its long form | Not built |
| Issue and present credentials over DIDComm | Not built |
| The Trust Spanning Protocol | Not built |
The library decrypts and verifies every message in the DIDComm specification’s own test appendix and in the reference implementation’s test vectors, across the three content ciphers, four curves and three signature algorithms the standard defines. It has also been run against the reference implementation itself, in both directions: that implementation read the messages this code produced, and this code read what it produced, for the ciphers, signature algorithms, envelopes and routes in the table above. The reference does not support the P-384 and P-521 curves, so those two are checked only against the published test messages. That run found and fixed one bug, in how ES256K signatures were written. It has not been checked against a live OpenVTC relay.
Standards used
- DIDComm Messaging v2.1 (Decentralized Identity Foundation)
- ECDH-1PU for authenticated encryption, and JOSE: RFC 7516 (JWE), RFC 7515 (JWS), RFC 7518 (algorithms)
did:key,did:peeranddid:web- The DIDComm protocols for routing , trust ping , feature discovery , problem reports and out-of-band invitations
Related
- Decentralized trust (KERI and ToIP) — the identity design this sits beside
- Asking and sharing architecture — how grants and disclosure ceilings work, over the HTTP requests peers send today
- Asking other Companions — the
/asksscreens