Skip to main content

Veramo 2.0 with DIDComm v2

· 4 min read
Mircea Nistor

We are excited to announce a new major release of Veramo!

This new release brings together a bunch of fixes and features that we've been working on recently, including some from the community (thank you for your contributions!).

You can get a detailed list of changes in the release description. Depending on how you're using Veramo you might be impacted by some breaking changes that had to be added in this release.

Added support for DIDComm v2​

Our @veramo/did-comm package got a boost of functionality with new support for DIDComm v2 over HTTP. This plugin now exports 3 new methods:

As you may have guessed, the existing sendMessageDIDCommAlpha1() method should no longer be used. We hope that the name of the method already suggested instability. This will be removed in Veramo 4.x.

To send a message you now pack it and then send the packed message:

const message = {
  type: 'test',
  to: receiver.did,
  from: sender.did,
  id: '123',
  body: { hello: 'world' },
}
const packedMessage = await agent.packDIDCommMessage({
  packing: 'authcrypt',
  message,
})
const result = await agent.sendDIDCommMessage({
  messageId: '123',
  packedMessage,
  recipientDidUrl: receiver.did,
})

According to DIDComm v2 spec, the recipient DID document must have a DIDCommMessaging service endpoint and a keyAgreementKey listed. The key agreement key is used to pack (encrypt) the message and the service endpoint is where the message is sent.

Added a basic plugin for DID discovery​

We imagine that apps dealing with DIDs may need some look-up capabilities, so we created a DIDDiscovery plugin that can mediate this. Multiple DIDDiscovery providers will be asked to find matches based on a query string. We provide 2 basic providers for this, one covers DID aliases and another covers DIDs that are the subject of Credentials with a name claim.

const result = await agent.discoverDid({ query: 'alice' })

expect(result.results[0].matches[0]).toEqual({
  did: 'did:example:some-did-with-alias-alice',
  metaData: {
    alias: 'alice',
  },
})

These basic providers only look in the local database for these matches. Future providers could search other data stores, or find DIDs by keys or by .well-known/did-config matches... you name it. Imagination is the limit here.

Added generic signing and shared-secret capabilities​

The @veramo/key-manager now exports 2 new methods:

  • keyManagerSign() - support all signing algorithms that lower level key management systems provide.
  • keyManagerSharedSecret() - compute shared secrets between a locally managed secret key and an external public key.

These are supposed to start phasing out the previous methods keyManagerSignJWT(), keyManagerSignEthTX() and keyManagerEncryptJWE()/keyManagerDecryptJWE().

The new signer can accommodate multiple algorithms implemented by your AbstractKeyManagementSystem implementations:

Example 1. signing JWT:

const jwsSignature = await agent.keyManagerSign({
  algorithm: 'ES256K',
  data: 'bla.bla',
  encoding: 'utf-8',
  keyRef: myKey.kid,
})

Example 2. signing an ethereum transaction:

const txData = serialize({
  to: '0xce31a19193d4b23f4e9d6163d7247243bAF801c3',
  value: 300000,
  gasLimit: 43092000,
  gasPrice: 20000000000,
  nonce: 1,
})

const rawTx = await agent.keyManagerSign({
  algorithm: 'eth_signTransaction',
  data: txData,
  encoding: 'hex',
  keyRef: myKey.kid,
})

Get DIDComm v2 out of the box with @veramo/remote-server & did:web​

If you are using @veramo/remote-server#WebDidDocRouter and @veramo/did-provider-web it is now easier than ever to receive DIDComm messages. The did-provider-web bootstraps your new did:web with Ed25519 and X25519 keys to be used for keyAgreement as well as listing an HTTP DIDCommMessaging endpoint by default.

Just as before, you still have to configure your express app with the proper hostname(s) to match your did:web identifiers.

Simpler setup for react-native​

@veramo/kms-local-react-native is not needed any more. It is now replaced by @veramo/kms-local which can be used in all environments. Some extra ceremony is still needed on react-native but the overall experience should be simpler.

Take a look at the React-native tutorial to see how to set that up.

As always, if there are any issues, let us know abut them, and if there are questions, please use the discussions page to get them answered and stay tuned for more.