R3 Corda

General Information

This user guide integrated with the R3 software Corda has been prepared using the software and firmware versions below: - OS Windows 10 (English) - R3 Corda 4.7 - HSM firmware: 5.0.26.0 (or higher) - HSM client: 4.7.30 (or higher)

Requirements

Connectivity with the HSM (TCP port 4433).
HSM client software installed (see Installation topic).
HSM service started.
Credentials of the HSM partition where the private key will be created or used.

R3 integration Corda with HSM

Implementation

The encryption provider Corda returns JCA objects that are used externally. So the initial step is to configure this integration API to connect to the HSM. For more details on the HSM's JCA/JCE API, see the JCA/JCE topic.

Overview

The encryption provider Corda uses two types of keys: 1. symmetric 1. asymmetric

The asymmetric keys are protected by the symmetric key(wrapping ) and stored externally to the HSM. The symmetric key, called the wrapping key, is kept in the HSM and is not exported (there is no such option in the provider interface).

The provider implements, and is called to execute, the following operations:

Generate KEK(wrapping key);
Generate private key;
Export private key encrypted by KEK;
Export public key;
Remove private key from HSM;
Sign;

The provider Dinamo Corda provider implements WRAPPED mode, which is the most secure mode available from Corda.

Two modes of operation are available. In both modes, the symmetric key is generated and maintained in the HSM and the asymmetric key is stored outside the HSM. The difference lies in the treatment of the asymmetric key.

Wrapped: Generates and uses the private key inside the HSM. The key outside the HSM is always encrypted by the KEK(wrapping key).
Degraded Wrapped Mode: Generates and uses the private key outside the HSM. The key is generated and used in the application's memory. It only goes into the HSM to be encrypted/decrypted by the KEK(wrapping key).

Key names

Keyaliases are not compatible with HSM object names, as they contain characters that are not accepted and are usually longer than the maximum allowed by HSM.

Some examples of aliases from Corda:

Symmetric keys (wrapping-key) : a74eb4c1-b4d9-4e1d-9e48-88e6abad7d63
Non-persistent keys: 2f5f5b11-35bc-4eb3-8f6b-fb4e3d723a26

The provider abstraction allows the key name to be processed and a compatible name to be passed on to the HSM. The solution is a transformation of the aliases passed by Corda:

Make an MD5 hash of the aliases passed in by Corda;
Transform into a hexadecimal string;

These transformed aliases are used as aliases in JCA calls.

Transformations are only made to non-ephemeral keys. In these cases, the original alias is stored in the object's metadata, in the label attribute.

Danger

In the event of an error, always use the name of the original alias that was received as a parameter. These strings are validated in compatibility tests.

Key attributes

The attributes of the symmetric and asymmetric keys are defined in the JCA settings. For more details, see the Configuration topic.

Key type	Exportable	Observations
Asymmetrical	✔️	Asymmetric keys are encrypted by a symmetric key and stored outside the HSM. They must therefore be exportable. They are always exported.
Symmetrical	❌	Symmetric keys are used to protect asymmetric keys and do not leave the HSM. They can therefore be non-exportable. This is the mode used in the example at Corda. There is no obstacle to changing this parameter.

Danger

You can only use 01 configured user per application. Do not use multiple users in the same process.

Configuration

Because we use the JCA in the implementation, the configuration is done via the file Configuration.ND of the JCA. The asymmetric keys must be set as exportable and the symmetric keys optionally set as non-exportable. The name of the Crypto service Dinamo is:

DINAMO

In the configuration files corda

freshIdentitiesConfFiguretion {
    mode="WRAPPED"
    cryptoServiceConfiguretion {
       cryptoServiceName="DINAMO"
       cryptoServiceConf="dinamo.conf"
    }
    buthaveKeyAlias="master_key"
}

The configuration file dinamo.conf may be empty or contain the hsm.config.file. The field hsm.config.file must be entered in the JCA configuration file. Enter the file name with full path. Do not use quotation marks " and if Windows uses \\ to separate the folders.

Examples of accepted content:

ini hsm.config.file=C:\\corda-4.7-full-release\\repository\\com\\r3\\corda\\corda-hsm-tck\\4.7\cordaconfidential.nd
ini hsm.config.file=
Empty file

Configure the JCA configuration file:

Mark asymmetric keys as exportable;
Mark symmetric keys as non-exportable (optional).

Danger

You can only use 01 configured user per application. Do not use multiple users in the same process.

The JCA and JNI files Dinamo can be located in the same folder as the Provider Corda Dinamo , which is the default driver folder for Corda or a specific one indicated in the configuration Corda.

ndjca.jar
tancjavalib.jar
dinamo_corda.jar

The binary library (TacNDJavaLib.so or TacNDJavaLib.dll) of the JNI must be available at PATH of the operating system.

The provider Dinamo Corda are available via SLF4Jjust like Corda. The configuration for log generation is done in the same way as Corda. You may need to enter the spec of provider Dinamo Corda. Just create the file cordaspec.conf with the content below and inform where necessary.

Tests

The compatibility tests Corda are available at website Corda and can be downloaded after signing up for the Trial. - Download the file corda-4.7-full-release.tar.gz and unzip; - The test is available in the .\repository\com\r3\corda\corda-hsm-tck\4.7; - It is executed with the command java -jar corda-hsm-tck-4.7.jar more options, described below;

Info

The test application is available in the deps in corda\4.7\bin

Prerequisites:

02 files are required after installing and configuring JCA Dinamo:
1. Archive of provider configuration Dinamo Corda. We will call this file corda.properties;
2. Archive of provider specifications Dinamo Corda. We will call this file cordaspec.conf;
The provider 's properties file can be configured as described in the Configuration section. The specifications file must have the following contents.
```
supporttedSchemes: ["RSA_SHA256", "ECDSA_SECP256R1_SHA256", "ECDSA_SECP256K1_SHA256"]

supptedSchemesForWrappingOperations: ["RSA_SHA256", "ECDSA_SECP256R1_SHA256", "ECDSA_SECP256K1_SHA256"]

supptedWrappingMode: WRAPPED

sessionIinctivityTimeortMinutes: 20
```

Execution

To run the interface test, use the command below.

Replace: - c:\cordaprovider: by the path to the folder containing dinamo_corda.jar including the JCA jars; - c:\corda.properties: by path with filename of configuration file Dinamo Corda; - c:\cordaspec.conf: by path with filename of specifications file Dinamo Corda;

Danger

Do not use relative paths, some tests are run in folders outside the current directory.

java -jar .\corda-hsm-tck-4.7.jar -n "DINAMO" -d "c:\cordaprovider" -r ".\rest-results" -lc "c:\corda.properties" -s "c:\cordaspec.conf" -cc "c:\corda.properties" -tc "c:\corda.properties" -t interface

Further tests can be carried out by changing the -t. See help.