Pular para conteúdo

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

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 1. 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.

Perigo

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.

Perigo

É 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:

  • 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=

  • 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

Exemplo de configuração JCA

Perigo

É 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;

Info

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;

Perigo

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.