Configuration Secrets

The Corda configuration system allows for any string configuration value to be marked as “secret”. When this configuration value is used, Corda delegates the resolution of this value to one of the following configured secrets lookup service:

• Default Secrets Service
• External Secrets Service

Default Secrets Service

Corda provides a default secrets lookup service. Implementation of this service is in the form of a service that uses symmetric encryption so that the value can be stored encrypted at rest and decrypted with an Advanced Encryption Standard (AES) key derived from a configured salt and passphrase when needed. The salt and passphrase must be specified in the deployment configuration.

For example, the following is a standard configuration:

{
  "database": {
     "pass": "mypassword"
  }
}

You can specify the pass value as a secret using the configSecret value, as follows:

{
  "database": {
     "pass": {
         "configSecret": {
           "encryptedSecret": "<encrypted-db-password>"
         }
     }
  }
}

You can use the Corda CLI A command line tool that supports various Corda-related tasks, including Corda Package Installer (CPI) creation and Corda cluster management. secret-config command to generate the configuration for an encrypted value.

External Secrets Service

Corda Enterprise supports integration with HashiCorp Vault as an external secret management system. This is the recommended deployment configuration. The URL at which the Vault instance is reachable, the Vault token, and the path to Corda created secrets must be specified in the deployment configuration.

For example, the following is a standard configuration:

{
  "database": {
     "pass": "mypassword"
  }
}

You can specify pass as a secret in Vault, as follows:

{
  "database": {
     "pass": {
         "configSecret": {
           "vaultPath": "<secret-path>",
           "vaultKey": "<secret-key>"
         }
     }
  }
}

You can use the Corda CLI secret-config command to generate the configuration for a value stored in Vault.

You can update a configuration value maintained in Vault in one of the following ways:

• Change the value in Vault. Corda caches configuration values for a short period of time. For this reason, you must handle changes so that old values remain valid for a short period of time to avoid downtime. For example, when changing database credentials, create the new credential before revoking the old one to guarantee a smooth transition.
• Add a new value in Vault, on a different path, and update the Corda configuration through the REST API. The relevant worker JVM processes that run in a cluster and perform a specific task. The processes required to form a cluster depend on the deployment topology. Workers increase or scale back their capacity depending on the number of available tasks. processes will pick up this new value asynchronously.