HSM support for Notaries

Overview

Each Notary workers needs access to three private key entries, corresponding to following entities:

• The distributed Notary identity, responsible for notarising transactions.
• The node certificate authority, responsible for issuing the legal identity and TLS certificates.
• The node legal identity, which represents the unique identity of the notary worker.

See the enterpriseConfiguration section of the corda-configuration-file doc for more information on how to configure each alias. When the private keys are stored in a HSM, only the certificates are stored in the keystore file.

The associated certificates for the distributed notary identity and node certificate authority are issued by the Identity Manager on the network. See Welcome to the Corda Enterprise Network Manager for more information. The legal identity certificate is issued by the node certificate authority.

The worker specific legal identity key pair is used for P2P messaging, whereas the single distributed notary identity key pair is used by all the notary workers of the CFT notary cluster to sign valid transactions. During operation, each notary worker will access the HSM and use the distributed notary key when processing notarisation requests.

For information on which HSMs are supported by Corda Enterprise, see the platform support matrix. Please read the section below for setup instructions and configuration details).

Detailed instructions to deploy to Azure Key Vault

These instructions assume that a single Azure Key Vault is being used across all notary workers.

Add the following entries to your workers node.conf files, replacing the placeholders with the relevant/chosen values:

cryptoServiceName: "AZURE_KEY_VAULT"
cryptoServiceConf: "<path to the crypto service configuration file>"
cryptoServiceTimeout: "<the desired timeout, default: 10000 milliseconds>"
enterpriseConfiguration {
  identityKeyAlias: "<CUSTOM_WORKER_IDENTITY_KEY_ALIAS>"
  clientCaKeyAlias: "<CUSTOM_WORKER_CA_KEY_ALIAS>"
  distributedNotaryKeyAlias: "<CUSTOM_DISTRIBUTED_KEY_ALIAS>" # optional - can omit to use default
}

path: <path to saved pkcs12 file>
alias: "1"
password: "<password used in the key vault creation>"
keyVaultURL: "https://<key vault name>.vault.azure.net/"
clientId: "<app id from creation of the service principle>"
protection: "SOFTWARE" # HARDWARE can be specified if using a premium vault

When the configuration files are ready, register the notary service identity using the HA Utilities tool and any worker’s node.conf file:

java -jar ha-utilities notary-registration \
     --config-file=node.conf \
     --network-root-truststore=<trust store> \
     --network-root-truststore-password=<password>

After successful registration, a keystore file is created by the tool in certificates/nodekeystore.jks this keystore contains the service identity certificate that all notary workers of this notary cluster share. Copy the file before registering the individual identity of the notary, to be able to distribute the file to all other notary workers.

cp certificates/nodekeystore.jks notary-service-keystore.jks

Register the individual identity of the notary using the Corda jar and the following command:

java -jar corda.jar initial-registration \
    --network-root-truststore-password=<password> \
    --network-root-truststore=<trust store>

To register a second notary worker, copy the notary-service-keystore.jks to the certificates directory of the next notary worker as certificates/nodekeystore.jks and repeat the above command.

Using Multiple HSMs

A highly-available HSM can be shared between notary workers in the current version of Corda, however each worker needs to be configured to use a unique alias for the identity and client ca key. See the enterpriseConfiguration section of the corda-configuration-file doc for more information on how to configure this.

If custom aliases have not been configured then, as each worker will attempt to create their identity and CA keys using the default alias, separate HSMs must be used. Also, as noted above, if a HA HSM is not available then each worker should be setup with its own HSM.

When a “one HSM per worker” setup is being used, the distributed notary service signing key has to be copied between the HSMs to ensure that each worker has access to it. As a consequence, your HSM of choice needs to provide a secure mechanism to copy keys between HSM instances.