R3 Corda

Informações Gerais

Este guia de uso integrado com o software R3 Corda foi preparado usando as versões de software e firmware abaixo:

• SO Windows 10 (inglês)

• R3 Corda 4.7

• Firmware do HSM: 5.0.26.0 (ou superior)

• Cliente do HSM: 4.7.30 (ou superior)

Requisitos

1. Conectividade com o HSM (porta TCP 4433).

2. Software client do HSM instalado, (consulte o tópico Instalação).

3. Serviço do HSM iniciado.

4. Credenciais da partição do HSM onde será criada ou utilizada a chave privada.

Integração R3 Corda com o HSM

Implementação

O provider de criptografia Corda retorna objetos JCA que são utilizados externamente. Portanto o passo inicial é configurar esta API de integração para conexão com o HSM. Para mais detalhes sobre a API JCA/JCE do HSM consulte o tópico JCA/JCE.

Visão geral

O provider de criptografia Corda usa dois tipos de chaves:

1. simétricas

2. assimétricas

As chaves assimétricas são protegidas pela chave simétrica (wrapping ) e guardadas externamente ao HSM. A chave simétrica, chamada de wrapping key, é mantida no HSM e não é exportada (não há essa opção na interface do provider).

O provider implementa, e é chamado para executar, as seguintes operações:

• Gerar KEK (wrapping key);

• Gerar chave privada;

• Exportar chave privada encriptada pela KEK;

• Exportar chave pública;

• Remover chave privada do HSM;

• Assinar;

O provider Dinamo Corda implementa o modo WRAPPED que é o mais seguro disponível pela Corda.

Há dois modos de operação disponíveis. Nos dois modos a chave simétrica é gerada e mantida no HSM e a chave assimétrica é guardada fora do HSM. A diferença está no tratamento da chave assimétrica.

1. Wrapped: Gera e usa a chave privada dentro no HSM. A chave fora do HSM fica sempre encriptada pela KEK (wrapping key).

2. Degraded Wrapped Mode: Gera e usa a chave privada fora do HSM. A chave é gerada e usada na memória da aplicação. Ela vai para o HSM apenas para ser encriptada/decriptada pela KEK (wrapping key).

Nomes de chaves

Os nomes (aliases) de chaves não são compatíveis com os nomes de objetos do HSM, pois contém caracteres não aceitos e normalmente são maiores do que o máximo permitido pelo HSM.

Alguns exemplos de aliases do Corda:

1. Chaves simétricas (wrapping-key) : a74eb4c1-b4d9-4e1d-9e48-88e6abad7d63

2. Chaves não persistentes: 2f5f5b11-35bc-4eb3-8f6b-fb4e3d723a26

A abstração do provider permite tratar o nome da chave e repassar para o HSM um nome compatível. A solução é uma transformação dos aliases passados pelo Corda:

1. Fazer um hash MD5 do alias passados pelo Corda;

2. Transformar em uma string hexadecimal;

Esses aliases transformados são utilizados como aliases nas chamadas da JCA.

As transformações são feitas apenas em chaves não-efêmeras. Nesses casos, o alias original é guardado nos metadados do objeto, no atributo de label.

Em caso de erro, sempre usar o nome do alias original que foi recebido como parâmetro. Essas strings são validadas nos testes de compatibilidade.

Atributos das chaves

Os atributos das chaves simétricas e assimétricas são definidas nas configurações da JCA. Para mais detalhes consulte o tópico Configuração.

Tipo de chave	Exportável	Observações
Assimétrica	✔️	As chaves assimétricas são encriptadas por uma chave simétrica e guardadas fora do HSM. Deste modo, devem ser exportáveis. Elas são sempre exportadas.
Simétrica	❌	As chaves simétricas são usadas para proteger as chaves assimétricas e não saem do HSM. Desta forma podem ser não exportáveis. É o modo utilizado no exemplo da Corda. Não há impedimentos para trocar esse parâmetro.

É possível utilizar apenas 01 usuário configurado por aplicação. Não usar múltiplos usuários no mesmo processo.

Configuração

Por usarmos a JCA na implementação, a configuração é feita via arquivo Configuration.ND da JCA. É preciso setar as chaves assimétricas como exportáveis e as simétricas opcionalmente como não exportáveis. O nome do Crypto service Dinamo é:

DINAMO

Nos arquivos de configuração corda

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

O arquivo de configuração dinamo.conf poderá estar vazio ou conter o campo hsm.config.file. O campo hsm.config.file deverá ser informado no arquivo de configuração da JCA. Informar nome do arquivo com caminho completo. Não usar aspas " e no caso do Windows usar \\ para separar as pastas.

Exemplos de conteúdo aceitos:

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

• hsm.config.file=

• Arquivo vazio

Fazer a configuração do arquivo de configuração da JCA:

• Marcar chaves assimétricas como exportáveis;

• Marcar chaves simétricas como não exportáveis (opcional).

Exemplo de configuração JCA

É possível utilizar apenas 01 usuário configurado por aplicação. Não usar múltiplos usuários no mesmo processo.

Os arquivos da JCA e JNI Dinamo podem ficar na mesma pasta do Provider Corda Dinamo, que é pasta padrão de drivers do Corda ou uma específica indicada na configuração Corda.

• ndjca.jar

• tancjavalib.jar

• dinamo_corda.jar

A biblioteca binária (TacNDJavaLib.so ou TacNDJavaLib.dll) da JNI deve estar disponível no PATH do sistema operacional.

Os logs do provider Dinamo Corda estão disponíveis via SLF4J, assim como o Corda. A configuração para a geração de logs é feita da mesma maneira que o Corda. Pode ser necessário informar o arquivo de spec do provider Dinamo Corda. Basta criar o arquivo cordaspec.conf com o conteúdo abaixo e informar onde necessário.

Testes

Os testes de compatibilidade Corda estão disponíveis no site da Corda e podem ser baixados após se inscrever para o Trial.

• Baixar o arquivo corda-4.7-full-release.tar.gz e descompactar;

• O teste está disponível na pasta .\repository\com\r3\corda\corda-hsm-tck\4.7;

• É executado com o comando java -jar corda-hsm-tck-4.7.jar mais opções, descritas mais abaixo;

O aplicativo de teste está disponível na pasta deps em corda\4.7\bin

• Pré requisitos:

  São necessários 02 arquivos após instalação e configuração da JCA Dinamo:

  1. Arquivo de configuração do provider Dinamo Corda. Chamaremos este arquivo de corda.properties;

  2. Arquivo de especificações do provider Dinamo Corda. Chamaremos este arquivo de cordaspec.conf;

  O arquivo de propriedades do provider pode ser configurado como descrito na seção de Configuração. O arquivo de especificações deve ter o conteúdo abaixo.

  supportedSchemes: ["RSA_SHA256", "ECDSA_SECP256R1_SHA256", "ECDSA_SECP256K1_SHA256"]
  
  supportedSchemesForWrappingOperations: ["RSA_SHA256", "ECDSA_SECP256R1_SHA256", "ECDSA_SECP256K1_SHA256"]
  
  supportedWrappingMode: WRAPPED
  
  sessionInactivityTimeoutMinutes: 20

Execução

Para executar o teste de interface, use o comando abaixo.

Substituir:

• c:\cordaprovider: pelo caminho para pasta onde contém o dinamo_corda.jar incluindo os jars da JCA;

• c:\corda.properties: pelo caminho com nome do arquivo do arquivo de configuração Dinamo Corda;

• c:\cordaspec.conf: pelo caminho com nome do arquivo do arquivo de especificações Dinamo Corda;

Não usar path relativo, alguns testes são executados em pastas externas ao diretório corrente.

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

Outros testes podem ser realizados alterando a opção -t. Ver help.