Configure Encrypted Private Key Storage with GCP KMS¶

Important

The following section describes the steps needed to enable Encrypted Private Key Storage in Canton using GCP KMS. These steps include configuring GCP KMS, as well as configuring this particular mode of operation.

GCP KMS Configuration¶

To start using this feature you must first enable GCP KMS for Canton:

–Configure GCP KMS for Canton–

The following IAM permissions are required:

cloudkms.cryptoKeyVersions.create
cloudkms.cryptoKeyVersions.useToEncrypt
cloudkms.cryptoKeyVersions.useToDecrypt
cloudkms.cryptoKeys.get

When you are using cross-account keys, you do not need the cloudkms.cryptoKeyVersions.create permission.

Encrypted Private Key Storage Configuration¶

Both new and existing nodes can be configured to use this feature. In both cases, keys are stored encrypted in the Canton node’s database

The example below configures encrypted private key storage with GCP KMS, for all nodes, in a simple distributed sync domain environment.

canton.domain-managers.domainManager1.crypto = ${_shared_gcp.crypto}
canton.sequencers.sequencer1.crypto = ${_shared_gcp.crypto}
canton.mediators.mediator1.crypto = ${_shared_gcp.crypto}
canton.participants.participant1.crypto = ${_shared_gcp.crypto}

_shared_gcp {
  # Configure an GCP KMS
  crypto {
    kms {
      type = gcp
      location-id = us-east1
      project-id = gcp-kms-testing
      key-ring-id = canton-test-keys-2023
      audit-logging = false # optional, default is false
    }

    # Configure an encrypted store with KMS
    private-key-store {
      encryption.type = kms
      # In this example we are using the same wrapper key for all nodes. This is not recommended and you should
      # either let Canton generate those keys or choose a different one for each node.
      encryption.wrapper-key-id = canton-kms-test-key
    }
  }
}

As seen before, crypto.kms configures GCP KMS. Subsequently, crypto.private-key-store.encryption.type = kms enables encrypted private key storage using a KMS.

Finally crypto.private-key-store.encryption.wrapper-key-id is an optional field to specify an existing (default) KMS key to use as the encryption key. If this field is left empty, Canton creates a new key.

Supported values are:

Key name: test-key
Key RN (Resource Name): projects/gcp-kms-testing/locations/us-east1/keyRings/canton-test-keys/cryptoKeys/test-key/cryptoKeyVersions/1

Note that if you are using an existing GCP key, it should be created as follows:

Key algorithm: GOOGLE_SYMMETRIC_ENCRYPTION
Key purpose: ENCRYPT_DECRYPT

After subsequent restarts the operator does not need to specify the identifier for the wrapper key; Canton stores the generated wrapper key ID in the database.

Important

Restoring from a database backup requires access to the wrapper keys used during the encryption of the data in the backup. Deleting the wrapper keys renders the backup unusable.

Revert Encrypted Private Key Storage¶

Encrypted Private Key Storage can be reverted back to unencrypted storage. To prevent accidental reverts, simply deleting the private-key-store configuration does not revert to unencrypted storage. Instead, the following configuration must be added:

canton.participants.participant1.crypto.private-key-store.encryption.reverted = true # default is false

Warning

This forces Canton to decrypt its private keys and store them in clear; it is not recommended.

Encrypted private key storage can be enabled again by deleting the reverted field and reconfiguring it as shown in Encrypted Private Key Storage Configuration.

Manual Wrapper Key Rotation¶

GCP offers automatic KMS symmetric key rotation (user-defined time). Canton extends this by enabling node administrators to manually rotate the KMS wrapper key using the following command:

participant1.keys.secret.rotate_wrapper_key(newWrapperKeyId)

You can pass a wrapper key ID to change to or let Canton generate a new key based on the current GCP KMS configuration.

Warning

It is not currently possible to change the key specification (e.g. enable multi-region) during rotation.

Interoperability¶

Nodes configured with and without encrypted private key storage can interact with each other, including nodes using different KMS providers.