Go to content

Environment configuration

The environment configuration defines the parameters of the native library and the HSM integration libraries. These parameters are kept in system environment variables.

The configuration made via the graphical console is in the scope (profile) of the user, and therefore valid and recognized only for applications running under the current user's profile.

Warning

There is no need for an administrative profile or elevation of privilege for the user to set or edit the environment configuration.

Sensitive information, such as password credentials and user IDs, is kept under the control of the Windows Credential Manager. There is no need to open the manager to edit credentials, but if you decide to do so, the procedure is:

  1. To open it, type credential manager in the taskbar search box (taskbar) and select Credential Manager.

  2. Select the tab Windows credentials. The credentials held by the console are in the Generic credentials and are prefixed with the string dinamo_.

    Windows Credential Manager
    Windows Credential Manager

The environment configuration options are grouped into tabs:

  1. Environment configuration
  2. Log
  3. MS CAPI
  4. Cloud MS CAPI
  5. PKCS#11
  6. Engine

The other options are direct actions:

  1. Start screen
  2. Check for updates
  3. Exit

Once you have finished editing the configuration, click the Apply button before switching tabs.

Session

Session tab

Session tab

Session cache

The checkbox Session cache checkbox enables and disables the library's session caching system. For more details on how the cache works, see the topic Session Cache.

Load balancing

The checkbox Load balancer checkbox enables and disables the library's load balancing system.

Dinamo has a load balancing mechanism, allowing greater availability of the environment and performance for applications. It is possible to have up to 16 (sixteen) HSM units in a load balancing system, with the same number of sessions on each device.

Warning

Load balancing is transparent to the application, i.e. once it is enabled in the environment, the application benefits without needing to make any changes.

It works on a round-robin basis, distributing connections circularly between the configured HSMs. The balancing unit is the session with the HSM, regardless of the load or APIs used in each session and also of the resource utilization rate. The HSM that will establish the session with the application is defined by the balancing structure and not by the application. The mechanism works per process, i.e. within each process it is its sessions that will be balanced; if two processes run at the same time, each will have a separate and independent balancing structure.

When this option is enabled, the IP address of the HSM where the session will be opened is read from the balancing list, and the IP address provided via the API is ignored.

Info

In the list of IP addresses, indicate the HSMs that will be part of the balancing, using the buttons + e - to add and remove entries in the list.

See Load Balancing for more details.

Connection

Connection attempts

Sets the number of retries to establish a connection with the HSM if the first attempt fails for some reason. The default value is 3.

Shipping timeout

Defines, within an established session, the maximum time (in milliseconds) that the library will wait for a confirmation response before deciding that the submission has failed and an error condition should be reported to the application.

An undefined value means working with the default time used in the operating system's TCP/IP protocol stack. Consult your particular operating system's documentation about this value.

Reception timeout

Defines, within an established session, the maximum time (in milliseconds) that the library will wait for a response to a request before deciding that communication has failed and an error condition should be reported to the application.

An undefined value means working with the default time used in the operating system's TCP/IP protocol stack. Consult your particular operating system's documentation about this value.

Suspension time

This is the suspension time (in seconds) in load balancing (BC), the period that the library will remove a problematic address from the balancing list.

During operation of the load balancing library, it may happen that one or more of the addresses in the list is unable to establish a session with the application. In this case, the library will temporarily remove the problematic address from the balancing list and will try a new connection after this period has expired.

Log

The log configuration set in the Log tab is used by all libraries (native, MS CAPI, PKCS#11 and JCA).

Dinamocon console

Dinamocon console

Global log level

The system has the following log levels:

  1. Only mistakes
  2. Debugging
  3. Disable

The level of information logged to file increases from level 1. At the Disabled level, no file log is generated.

During normal application operation, the log is usually disabled or set to the Error Only level, as the files generated can be quite large and have a negative impact on performance. Increase the log level when you need to generate more information for debugging problems or as an aid for support staff.

Standard output

This option causes the logs to be sent to the system's standard output(stdout).

Warning

This is the recommended option for use in environments with containerized applications.

Global log directory

Log files are generated individually for each process that loads the library; each process generates a log file that has the process ID (Process ID or PID) in the file name. For example, for a log file name tacndlib.log the generated files would be as follows tacndlib_<PID>.logsuch as tacndlib_3456.log, tacndlib_5947.logetc.

Define a folder for saving the libraries' log files. The applications must have write permission to the selected folder.

MS CAPI

See the Local Configuration topic for details on configuring the MS CAPI library or the MS Crypto API topic for general information on MS CAPI.

Cloud MS CAPI

See the Cloud Configuration topic for details on configuring the MS CAPI library or the MS Crypto API topic for general information on MS CAPI.

PKCS#11

See the Configuration topic for configuration details of the PKCS#11 library or the PKCS#11 topic for general information about PKCS#11.

Engine

See the Configuration topic for configuration details of the Engine OpenSSL library or the Engine OpenSSL topic for general information about Engine OpenSSL.

Configuration Scope

Using the Dinamocon console (or setting the environment variables in the user profile) the scope of the parameters is always per user.

To define a scope per application, it is necessary to load this application with a specific definition of the variables, for example by encapsulating the load in abatch file.

To define a global (system) scope, you need to define the variables in the system scope, for example via the control panel in the system variables area.

For details on each parameter and the corresponding variable, see the topic Environment variables.