Migrating to Veramo 3.0

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.

In Veramo 3.0 we've separated some responsibilities of different plugins that deal with key management. This enables people to create new kinds of key management systems for Veramo in a way that makes it clearer where private data is stored and reduces the risk of leaking.

As you may already be aware, Veramo has a 2 layer approach to plugins. On the first layer there are top-level agent plugins that can register for events and that export methods to be directly callable on the agent object. These plugin methods can also call each other in the same execution context.

In many cases these agent plugins provide some common API for interacting with different protocols or standards implementations. This is where the second level plugins come in. These provide specific implementations that plug-into the top-level ones. These implementations aren't expected to be aware of each-other, so they don't directly interact.

Examples of this pattern include DIDResolver with implementations for various DID methods, DIDManager with IDIDProvider implementations, and of course KeyManager with implementations of AbstractKeyManagementSystem ( We sometimes refer to these as KMS).

What's new about key management?

The @veramo/kms-local is an implementation of AbstractKeyManagementSystem. In the previous versions it was responsible for implementing some crypto algorithms, but it would rely on the top-level @veramo/key-manager to provide the actual private key material.

In Veramo 3.0 @veramo/key-manager no longer stores any private key material. Instead, @veramo/kms-local now uses a PrivateKeyStore for hosting the key data. The @veramo/data-store package provides an implementation that uses a database for storing these keys encrypted by a SecretBox.

This means there will be some changes for the initial setup of these plugins, and also some changes related to how the database connection is made.

This also means that keyManagerGet() no longer returns private keys**. If your use-case requires that you export keys from Veramo, please raise an issue, or contact us on the github discussions page.

Ok, so how does it affect me?

If you're just starting out, simply follow one of the getting started guides. Easy-peasy.

If you're already working with Veramo and wish to upgrade existing agents to 3.0, you'll have to make some changes to your configuration, depending on how you're using the framework.

It boils down to these 3 steps, but keep reading for more details:

1. Update your database connection to use migrations
2. Remove the SecretBox parameter from KeyManager
3. Add a PrivateKeyStore parameter to KeyManagementSystem with a SecretBox that you were using before with KeyManager (and keep the same encryption key)

Typescript app config changes

If your agents are part of a typescript app, these changes will look like this:

import {
  // ...
  migrations, // 0. import default veramo migrations
  PrivateKeyStore,
} from '@veramo/data-store'

// 1. update your connection config to use migrations
dbConnection = createConnection({
  // ...
  synchronize: false, // switch this to false
  migrations, // add default veramo migrations
  migrationsRun: true, // add this flag
})

const agent = createAgent<>({
  // ...
  plugins: [
    // 2. key manager: remove SecretBox param
    new KeyManager({
      store: new KeyStore(dbConnection),
      kms: {
        // 3. kms-local: add PrivateKeyStore with SecretBox
        local: new KeyManagementSystem(new PrivateKeyStore(dbConnection, new SecretBox(secretKey))),
      },
    }),
    // ...
  ],
})

CLI config changes

# 0. update the version for your config file
version: 3.0
# ...

# 1. update your database connection to use migrations
dbConnection:
  $require: typeorm?t=function#createConnection
  $args:
    - type: sqlite
      database:
        $ref: /constants/databaseFile
      synchronize: false # switch off synchronize
      migrationsRun: true # turn on migrations
      migrations: # start with veramo default migrations
        $require: '@veramo/data-store?t=object#migrations'
      logging: false
      entities:
        $require: '@veramo/data-store?t=object#Entities'

# then update your keyManager config:
keyManager:
  $require: '@veramo/key-manager#KeyManager'
  $args:
    - store:
      $require: '@veramo/data-store#KeyStore'
      $args:
        - $ref: /dbConnection
        # 2. remove the SecretBox argument from KeyManager
      kms:
        local:
          $require: '@veramo/kms-local#KeyManagementSystem'
          $args:
            - $require: '@veramo/data-store#PrivateKeyStore'
              $args:
                - $ref: /dbConnection
                # 3. add the SecretBox argument from KeyManager to your PrivateKeyStore
                - $require: '@veramo/kms-local#SecretBox'
                  $args:
                    - $ref: /constants/secretKey

Easy, right?

The default migrations that we bundle with @veramo/data-store also take care of moving the encrypted keys to the new table. Make sure to use the same encryption key with SecretBox that you were using before to be able to decrypt the keys in their new location.

I was using my own AbstractKeyManagementSystem, what do I do now?

In that case, congrats! Let us know about it.

The most important thing to keep in mind is that KeyManager no longer holds any private key material. It only knows about which AbstractKeyManagementSystem holds the key.

This means that when a method like sign() is called on your KMS, you should only care about the kid property of the IKey param and nothing else.

Also, it is now the responsibility of the KMS implementation to compute publicKeyHex and to decorate a key with meta-data when it creates or imports it, before returning the descriptor to the calling KeyManager.

---

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.