Skip to content
You are reading Consensys Quorum Plugins development version documentation and some displayed features may not be available in the stable release. You can switch to stable version using the version box at screen bottom.

Configure the encrypted storage plugin

Encrypt data at rest with the encrypted storage plugin and a 256-bit AES encryption key. Store the encryption key locally or in HashiCorp Vault.

TLS is enabled by default for communication between Hyperledger Besu and HashiCorp Vault. Configure TLS in the file used to retrieve the encryption key.


The encrypted storage plugin must be enabled when the node is started for the first time and the blockchain database is created. In other words, you cannot encrypt an existing unencrypted database.

The encryption key cannot be changed after the database is created.

Using a locally stored encryption key

Generate the encryption key before configuring encryption. In this example an encrypted key file is created using the openssl rand -out /myNode/encryptionKey 32 command.

Configure encrypted storage using a locally stored encryption key by enabling the encrypted storage plugin and setting the appropriate options.


besu --key-value-storage=encrypted-storage --plugin-encrypted-storage-key=/myNode/encryptionKey

The command line:

Using an encryption key stored in HashiCorp Vault


  • HashiCorp server must be running.
  • A KV version 2 secret mount must be enabled.


    Using Vault CLI, enable the KV v2 secret mount point:

    vault secrets enable -path=secret kv-v2


    Use kv-v2 type as indicated in KV v2 doc. Plugin only works with v2 secrets.

    Example Vault command to check if an existing secret is v1 or v2

    If the engine used is V2, the secret is versioned and you can see the metadata with version field:

    vault kv get /secret/DBEncryptionKey
    ====== Metadata ======
    Key              Value
    ---              -----
    created_time     2020-11-27T10:15:59.91752Z
    deletion_time    n/a
    destroyed        false
    version          1
    ==== Data ====
    Key      Value
    ---      -----
    value    477265617420706f7765723d677265617420726573706f6e736962696c697479
    ==== Data ====
    Key      Value
    ---      -----
    value    477265617420706f7765723d677265617420726573706f6e736962696c697479
  • Encryption key must be written to HashiCorp Vault as a hex string (without 0x prefix): Create the secret DBEncryptionKey in the secret KV v2 mount point.


    vault kv put /secret/DBEncryptionKey value=<Private Key without 0x prefix>
    vault kv put /secret/DBEncryptionKey value=477265617420706f7765723d677265617420726573706f6e736962696c697479


    Don’t use this example key! Use your own securely generated key.

  • HashiCorp Vault server certificate authority (CA) certificates. Supported truststore types include PEM, PKCS12, and JKS.

Create the TOML configuration file to obtain the encryption key from HashiCorp Vault and configure TLS:

Example /myNode/config.toml

hashicorp.timeout=30000 # in milliseconds


  • hashicorp.timeout is in milliseconds, example uses 30s, default is 10s.
  • Make sure to use a correct valid HashiCorp token.
  • hashicorp.keyPath syntax is the same as the path used in Hashicorp KV Secrets Engine Version 2 HTTP API
  • the v1 part in keyPath="/v1/secret/data/DBEncryptionKey" is not related to the secret engine version but to the vault HTTP API version. API v1 is used with both KV engine v1 and KV engine v2. Besu only uses KV engine V2.

Configure encrypted storage by enabling the encrypted storage plugin and setting the appropriate options.


besu --key-value-storage=encrypted-storage --plugin-encrypted-storage-hashicorp-config=/myNode/config.toml

Check Besu node DEBUG logs1 for confirmation that database encryption plugin started successfully:

2020-11-27 09:43:22.887+00:00 | main | DEBUG | EncryptedStoragePlugin | Extracting key from Hashicorp key provider.
2020-11-27 09:43:24.834+00:00 | main | DEBUG | EncryptedStoragePlugin | Starting plugin.
2020-11-27 09:43:24.835+00:00 | main | DEBUG | BesuPluginContextImpl | Started plugin of type
2020-11-27 09:43:24.835+00:00 | main | DEBUG | BesuPluginContextImpl | Plugin startup complete.

  1. All plugin lifecycle related logs are visible only at the DEBUG level. 

ConsenSys has acquired Quorum from J.P. Morgan. Please read the FAQ.
Questions or feedback? You can obtain paid professional support by ConsenSys at [email protected]