Skip to content

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

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

R3 integration Corda

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.

  1. Wrapped: Generates and uses the private key inside the HSM. The key outside the HSM is always encrypted by the KEK(wrapping key).

  2. 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:

  1. Symmetric keys(wrapping-key) : a74eb4c1-b4d9-4e1d-9e48-88e6abad7d63
  2. 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:

  1. Make an MD5 hash of the aliases passed in by Corda;
  2. 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 our implementation, configuration is done via the JCA's Configuration.ND file. Asymmetric keys must be set as exportable and symmetric keys optionally set as non-exportable. The name of the Crypto service Dinamo is:

DINAMO

In the configuration files corda

freshIdentitiesConfiguration {
    mode="WRAPPED"
    cryptoServiceConfiguration {
       cryptoServiceName="DINAMO"
       cryptoServiceConf="dinamo.conf"
    }
    masterKeyAlias="master_key"
}

The configuration file dinamo.conf may be empty or contain the hsm.config.file field. The hsm.config.file field must be entered in the JCA configuration file. Enter the file name with full path. Do not use quotation marks " and in the case of Windows use \\ 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).

JCA configuration example

JCA configuration example

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 JNI binary library(TacNDJavaLib.so or TacNDJavaLib.dll) must be available in the PATH of the operating system.

The provider 's Dinamo Corda logs are available via SLF4J, just like Corda. Log generation is configured in the same way as Corda. You may need to enter the provider 's spec file Dinamo Corda. Simply create the file cordaspec.conf with the content below and enter it where necessary.

Tests

The compatibility tests Corda are available on the Corda website and can be downloaded after signing up for the Trial. - Download the file corda-4 .7-full-release.tar.gz and unzip; - The trial is available in the .\repository\com\r3\ folder corda\ corda-hsm-tck\4 .7; - It is run with the command java -jar corda -hsm-tck-4 .7.jar plus options, described below;

Info

The test application is available in the deps folder at corda\4 .7\bin

  • Prerequisites:

    02 files are required after installing and configuring JCA Dinamo:

    1. Provider configuration file Dinamo Corda . We'll call this file corda.properties;
    2. Provider specification file Dinamo Corda . We'll 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.

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

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

supportedWrappingMode: WRAPPED

sessionInactivityTimeoutMinutes: 20

Execution

To run the interface test, use the command below.

Replace: - c:\cordaprovider: with the path to the folder containing dinamo_corda .jar including the JCA jars; - c:\corda.properties: the path with the file name of the configuration file Dinamo Corda ; - c:\cordaspec.conf: by the path with the file name of the 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

Other tests can be performed by changing the -t option. See help.