Skip to Content
DocumentationCompanion MemoryPrivate messaging (DIDComm)

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 designDIDComm
Question it answersWho 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?
IdentifiersKERI identifiers (design). Today a key id in Companion Memory’s own did:keri:D formdid:key, did:peer and did:web
Changing keysKey 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 offlineNot its jobRelays (“mediators”) hold and forward envelopes they cannot read
StatusDesign only: no key event log exists in Companion MemoryLibrary 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:

NameWhat 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.
EnvelopeWho can read itProves the sender to the recipientProvable to others
AnonymousThe recipientNoNo
AuthenticatedThe recipientYesNo
Signed, then encrypted anonymouslyThe recipientYesYes
Authenticated, with the sender hiddenThe recipientYesNo

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.

The 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:key needs no setup and no network. The identifier is the public key. It cannot change keys.
  • did:peer carries 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:web is 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:keri is 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.

  1. The envelope is well formed and in a shape DIDComm allows. Nothing is guessed or repaired.
  2. A key this Companion holds is one of the recipients.
  3. 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.
  4. The message decrypts, or the signature verifies.
  5. 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.
  6. The message has not expired, allowing for a minute of clock difference.
  7. 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

CapabilityStatus
Encrypt and decrypt authenticated and anonymous messagesBuilt as a library
Sign and verify messages, and sign then encryptBuilt as a library
Hide the sender from the first relayBuilt as a library
Wrap a message for a route through relays, working out the route from DID documentsBuilt as a library (sending side)
Trust ping, feature discovery, problem reports, out-of-band invitationsBuilt as a library
Announce a move from one DID to anotherBuilt as a library
Remember messages already seen, and answer a messageBuilt 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 offlineNot built
Keep keys in the device keychain, keep the memory of seen messages across restartsNot built
Identities backed by a KERI key event log (did:webs)Not built
did:webvh, and did:peer in its long formNot built
Issue and present credentials over DIDCommNot built
The Trust Spanning ProtocolNot 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

Last updated on