Options for confidential identities

In Corda, all nodes are associated with a public key. However, when additional privacy is required, nodes can use confidential identities. A confidential identity is a new key pair, referred to as a confidential identity key, that can be communicated to other specific nodes, which then associate the new key pair with the node that generated them.

This system allows the confidential identity keys to be used to sign transactions, without the wider network being able to associate the key pair with the signing node. Confidential identity keys can be used either by using the KeyManagementService APIs, where a CorDapp generates a fresh key pair, and communicates it to other nodes; or with the SwapIdentitiesFlow and IdentitySyncFlow.

Warning

When using a confidential identity, the keys are stored in the node database in plaintext. In order to prevent the exposure of private keys in the event of a security breach, we highly recommend either the use of an HSM, or that the node database be encrypted at rest.

Using confidential identities with an HSM

By using an HSM, the confidential identity keys can be stored in the node database in an encrypted form. There are two supported modes for combining HSMs and confidential identities on Corda Enterprise; wrapped and degraded wrapped. Both of these modes are more secure than using confidential identities without an HSM.

Wrapped mode

The wrapped mode is the most secure, but requires specific APIs from the HSM, and not all HSMs are supported. The wrapped mode functions as detailed below:

  1. The node generates a symmetric AES key inside the HSM. This key is known as the wrapping key.
  2. When a confidential identity key is required, it is generated by the HSM and encrypted using the private wrapping key. The confidential identity key pair is then returned to the node as a public key and an encrypted private key.
  3. The node stores the public and encrypted private key.
  4. When the node needs to use the confidential identity key to sign data, the node provides the encrypted private key to the HSM, the HSM decrypts the key using the wrapping key, signs the data, and returns the signed data to the node.

This method prevents the node from having access to the unencrypted private key at any point in the key creation or data signing process.

Degraded wrapped mode

The degraded wrapped mode is slightly less secure than the wrapped mode, but can be supported by a wider variety of HSMs. The degraded wrapped mode functions as detailed below:

  1. The node generates the symmetric AES wrapping key inside the HSM.
  2. When a confidential identity key is required, the node generates the key pair in local memory, which is then sent to the HSM for encryption.
  3. The HSM encrypts the confidential identity key with the wrapping key, and returns the encrypted key to the node.
  4. When the node needs to use the confidential identity key to sign data, the HSM decrypts the private key, which is passed back unencrypted and used by the node to sign the data in memory.

The degraded wrapped mode is considered less secure than the wrapped mode, as the private key material is exposed to the node’s memory at two points:

  • The confidential identity key is created in the node’s memory before it is encrypted.
  • Data signing takes place in the node’s memory using the unencrypted private key, rather than inside the HSM.

Using confidential identities with a filesystem keystore

Confidential identities can be used with a keystore in the node filesystem. The filesystem keystore takes the role of the HSM, however, the filesystem keystore is only compatible with the degraded wrapped mode.

Warning

This method is less secure than the degraded wrapped HSM mode, and is recommended for use in development and testing scenarios only. The encrypted private key is exposed in the node’s memory and the associated wrapping key is also stored in the node’s filesystem.

Configuring nodes for confidential identities

Using an HSM with confidential identities is not enabled by default. To enable this, the node configuration file must include the freshIdentitiesConfiguration field.

The freshIdentitiesConfiguration field contains the following attributes:

Attribute Type Required Description
mode String Yes Defines the mode of operation, valid values are: WRAPPED or DEGRADED_WRAPPED.
masterKeyAlias String No Defines an alias for the wrapping key. The default value is wrapping-key-alias.
cryptoServiceConfiguration N/A Yes Contains the cryptoServiceName and cryptoServiceConf attributes.
cryptoServiceName String Yes Defines the type of HSM. Valid values can be found in the HSM documentation.
cryptoServiceConf String Yes Defines a path to the HSM configuration file to use, for details, see the HSM documentation.

A completed configuration file might appear as follows:

freshIdentitiesConfiguration: {
    mode: "DEGRADED_WRAPPED",
    cryptoServiceConfiguration: {
        cryptoServiceName: "BC_SIMPLE"
    },
    masterKeyAlias: "master-key",
}

Support matrix

The following table contains the current support and the associated configuration values:

Master key storage cryptoServiceName cryptoServiceConf mode
file-based keystore BC_SIMPLE not used DEGRADED_WRAPPED
Securosys PrimusX HSM PRIMUS_X path to the PrimusX configuration file WRAPPED

Additional notes

  • For Securosys’ PrimusX HSM, this feature has been tested with an HSM running firmware version 2.7.4 and the version 1.8.2 of the PrimusX JCA provider.
  • The wrapping key is generated during node registration. So, if you want to upgrade to this secure mode of using confidential identities after having used the previous one, you will have to re-run the node registration process, which will skip the steps that have been executed already and will just generate the wrapping key.