Skip to main content

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.

important

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​

Prerequisites:

  • 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

  • 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>

  • 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.serverHost="localhost"
hashicorp.serverPort=8200
hashicorp.token="s.Ewt5ZAmkY2T9JoF9YJ1g0toy"
hashicorp.keyPath="/v1/secret/data/DBEncryptionKey"
hashicorp.keyName="value"
hashicorp.timeout=30000 # in milliseconds
hashicorp.tlsEnable=true
hashicorp.tlsVerifyHost=true
hashicorp.tlsTrustStoreType="PEM"
hashicorp.tlsTrustStorePath="/myNode/vault/ssl/vault.crt"
note
  • 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.

example
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 tech.pegasys.plus.plugin.encryptedstorage.EncryptedStoragePlugin.
2020-11-27 09:43:24.835+00:00 | main | DEBUG | BesuPluginContextImpl | Plugin startup complete.

*[CA]: Certificate Authority

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