Go to content

Configuration

The JCA/JCE CSP of Dinamo is a layer above the native API of Dinamo. See the topic Environment variables for client library configuration options.

Configuring the JCA/JCE CSP can be done in two ways: graphical interface (GUI) or command line (CLI).

The steps required for configuration are as follows:

  1. Generate the configuration file Configuration.ND through the configuration program jca_config.jar;
  2. Copy the configuration file to the folder where the program that will use the CSP java from Dinamo is located.

Info

The JCA/JCE configuration program will create a file called Configuration.ND which should be copied to the folder where the program that uses the java CSP from Dinamo is located. The generated file can be used on any operating system platform.

To find the configuration file Configuration.NDIn addition to searching the application directory, the JCA uses the classpath.

Search sequence for Java applications in Application Server:

  1. Root directory of the application;
  2. /WEB-INF/classes;
  3. /WEB-INF/lib/*.jarwhere *.jar means a search inside the jars;
  4. Application server conf directory;
  5. JVM bootstrap classes;

Search string for executable Java applications:

  1. Root directory of the application (which can be the root of the encapsulated .jar, for example);
  2. Application classpath;

In addition to the standard search, the choice of configuration file can also be made via environment variable or system properties (System Properties).

  1. Name of property: dinamo.hsm.configfile

    Value: Full path to the configuration file including the file name.

  2. Environment variable: DIN_JCA_CONF_FILE

    Value: Full path to the configuration file including the file name.

When setting the configuration path using the options above, the search will be made using the path with the file name and not the default paths. The search order will be:

  1. System property;
  2. Environment variable;
  3. Standard search (described above);

The configuration program is called using the command line java -jar jca_config.jar. When you run the program without parameters, the graphical interface is initialized; when you call it with parameters, the interaction is done only via the command line.

Info

The following screens and options may vary depending on the version used.

Via Graphical User Interface (GUI)

  1. Run the program jca_config.jar without parameters: java -jar jca_config.jar.

    CSP JCA/JCE configuration screen
    CSP JCA/JCE configuration screen

  2. Configure load balancing according to your environment.

    • By selecting Enable, the Java CSP will use the load balancing configured in the client library.

    • If you select Disable, an IP must be specified. The load balancing configured in the library will be ignored and the specified IP will be used.

  3. Select User/Password and set up the HSM user and password. If you use Access Tokens select the Access Token option and fill in the field Access Token with the structure DN_A_TOKEN in Base64 format (e.g. AToken returned by hsmcon or by the TacAccessToken.getAToken() and transformed into Base64).

  4. Select the log level and the location of the log file.

  5. Select the public key export format that will be returned by the JCA: SubjectPublicKeyInfo or SubjectPublicKey.

    We recommend leaving this option unchecked. It should only be enabled when strictly necessary for the operation of the application.

  6. Select the type of session (with or without TLS channel protection). Checking the box disables the use of an encrypted session.

    We recommend leaving this option unchecked. It should only be enabled when strictly necessary for the operation of the application.

  7. Select the symmetric key export attribute. Checking the box enables the generation of exportable symmetric keys.

    Assess according to application needs.

  8. Select the asymmetric key export attribute. Checking the box enables the generation of exportable asymmetric keys.

    Assess according to application needs.

  9. OK to finish.

Via Command Line (CLI)

  1. Run the program jca_config.jar with parameters (Ex: java -jar jca_config.jar -help).

    java -jar jca_config.jar -h
Usage: java CSPConfig <options>
where possible options include:
-lb                           Enable load balance
-addr <address>               Disable load balance and set a specific HSM address
-usr <user name>              Specify HSM user name
-pwd <password>               Specify HSM user password
-at <accesstoken>             Specify access token in Base64. This option cannot be used with   -usr and -pwd.
-loglevel {none, info, warning, error, debug}Specify JCA/JCE's log level
-logpath <log path>           Specify JCA/JCE's log path
-spk                          Enable SubjectPublicKey export format[0-disabled/1-enabled]
-tls                          Enable TLS [0-disabled/1-enabled]
-ces                          Create exportable symmetric key [0-disabled/1-enabled]
-cea                          Create exportable asymmetric key [0-disabled/1-enabled]
-file                         Configuration file
-ls                           List file properties
-help | -h                    Print a synopsis of standard options

*Call CSPConfig with no options to start GUI mode.

    Info

    The default key export attribute setting is: exportable symmetric keys and non-exportable asymmetric keys.

    • Example 1: This call will configure load balancing, user and password, log level for debugging, exportable symmetric keys, non-exportable asymmetric keys and the path of the log file:

      java -jar jca_config.jar -lb -usr master -pwd 12345678 -loglevel debug -logpath c:\jca. log -spk 0 -tls 1 -ces 1 -cea 0 -file Configuration.ND

    • Example 2. This call will set up a specific IP, user and password, and with logging disabled:

      java -jar jca_config.jar -addr 10.0.1.2 -usr master -pwd 12345678 -loglevel none -spk 0 -tls 1 -file Configuration.ND

    • Example 3. This call will set up an Access Token.

      java -jar jca_config.jar -addr 10.0.1.2 -at bHVhbgAAAAAAAAAAAAAAAGIwx1mtzLLQ9OkapMIzRrTNxAssvFeUvDh1mO7I4x5xAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA= -loglevel none -spk 0 -tls 1 -file Configuration.ND

    • Example 4. This call will list the attributes of the configuration.

      java -jar jca_config.jar -file Configuration.ND -ls