Go to content

Implementation

The CSP Dinamo is referenced by JCA\JCE through the identifier ND .

CSP classes cannot be cloned.

The keystore file stores the relationship between the keys stored in the HSM and the CSP. This relationship is made in the following ways:

  1. Creating a key from the JCA/JCE APIs. In this way, the key is created in the HSM but is removed at the end of the program or when the key object is removed by the Java garbage collector. For this key to be kept in the HSM, it must be included in the keystore, so that it is guaranteed not to be removed at the end of the program.

  2. When loading a keystore the list of keys is loaded directly from the HSM. There is no physical file representation of the keystore, so when calling the load() happens null in the file and password parameters. The keys will be recognized as described in items 3 and 4. Key passwords are an empty string.

    Info

    The key name in HSM is a sequence of 16 random characters plus 3 characters JCA which are placed at the end of the key name, totaling 19 characters.

    Attention

    If the program ends with an unexpected failure, the key may not be removed from the HSM.

Nomenclature

The following key nomenclature must be followed for the correct interpretation of the private key, with its respective certificate (.cer) and CA certificate chain (p7b).

Object Name formation rule
Private key <id_chave>
Certificate <id_chave>_cert
Chain of certificates <id_chave>_chain

Info

When the certificate chain is loaded into the KeyStore, it is sorted according to RFC-5246.

Once the keys have been uploaded to the keystore, the certificate and certificate chain can be accessed via the respective recovery methods available under the private key alias.

keystoreinstance.GetCertificate(key_id)
keystoreinstance.GetCertificateChain(key_id)

Chains

Certificate chains are accepted with or without the head certificate (certificate related to the key itself).

In addition to the way described in the item above, key/chain relationships are allowed using MAPs (HSM objects that allow two other objects to be related). Using MAPs allows the relationship between a private key and a chain of certificates with names that do not follow the nomenclature described in item (3) and for the name of the Alias in the KeyStore to be defined in a more flexible way.

This relationship is as follows:

  1. The name of the MAP object inside the HSM will be the name of the Alias in the KeyStore;
  2. The object name of the first MAP Slot will be the name of the private key inside the HSM;
  3. The object name of the second MAP Slot will be the name of the certificate chain within the HSM;

Certificate chains are accepted with or without the head certificate (certificate related to the key itself).

Keystores

There are three types of keystore available on JCA/JCE Dinamo, described below.

TAC

It has all the permissions on the keys in the HSM, including removing and adding keys in the HSM.

keystoreintance.getInstance("TAC", "ND")

TACV

TAC Virtual, similar to the TAC type but the removal of keys is only virtual, i.e. the keys are only deleted from the keystore and not from the HSM.

keystoreintance.getInstance("TACV", "ND")`

TACCON

It behaves in the same way as the TAC type, except that the user id, password and IP address of the HSM must be entered in the following formats user:password@IP or accessToken@IP.

When using user and password, the user id and password fields are mandatory.

When using Access Tokens the field accessToken is mandatory. O Access Token is the structure DN_A_TOKEN in Base64 format; for example AToken returned by HSMCON or the TacAccessToken.getAToken() and transformed into Base64.

The IP address of the HSM can only be omitted when load balancing is active.

Attention

When using username and password, the two tabs : e @ should be used alwayseven if the IP address of the HSM is not entered. In the case of Access Tokens @ should be always used.

Ex: 

keystoreintance.getInstance("TACCON", "ND")
keyStore.load(null, ("usr:12345678@10.0.62.10").toCharArray())
keyStore.load(null, ("usr:12345678@").toCharArray())
keyStore.load(null, ("bHVhbgAAAAAAAAAAAAAAAGIwx1mtzLLQ9OkapMIzRrTNxAssvFeUvDh1mO7I4x5xAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=?@10.0.62.10").toCharArray())

ECCDHwithSHA256KDF

To use KeyAgreement ECCDHwithSHA256KDF with JCA DINAMO should be used to generate SecretKey the parameter spec DNECDHX963ParameterSpec.

Builder 1

To initialize DNECDHX963ParameterSpec the following parameters can be used.

Generates a persistent and exportable key.

  • kdfData KDF used to generate the key.
  • keyLen Key size, in bits, that will be generated in KeyAgreement.generateSecret(). The key size must be compatible with the algorithm passed in KeyAgreement.generateSecret().
    public DNECDHX963ParameterSpec(byte[] kdfData, int keyLen );

Builder 2

Initializes the parameters of the ECDH X9.63 algorithm, to be used in the KeyAgreement class.

  • kdfData KDF used to generate the key.
  • keyLen Key size, in bits, that will be generated in KeyAgreement.generateSecret(). The key size must be compatible with the algorithm passed in KeyAgreement.generateSecret().
  • exportable Informs whether the generated key will be exportable or not. Enter true for exportable and false for non-exportable.
  • temporary Informs whether the generated key will be temporary or not. Enter true for temporary and false for persistent.

java public DNECDHX963ParameterSpec(byte[] kdfData, int keyLen, boolean exportable, boolean temporary);