Sessions

The configurations for load balancing control and session caching are detailed below.

Variable	Quick Description
HSM_DISABLE_SESSION_CACHE	Disables session caching (value set to 1).
HSM_SESSION_CACHE_TIMEOUT	The session cache timeout duration in seconds.
HSM_LOAD_BALANCE_LIST	Path to the file containing the list of HSMs for load balancing.
HSM_LB_FILE_REFRESH_INTERVAL	Update interval (in seconds) for the load balancing file.
HSM_BALANCE_SUSPEND_TIME	Time (in seconds) of automatic suspension of a non-responsive HSM from the balancing loop.
HSM_PIX_HTTP_CONN_REFRESH_INTERVAL	Update interval (in seconds) for loading HSM objects in Pix request (POST/GET/DELETE) operations.
HSM_DISABLE_TELL_ADDR	Disables (value set to 1) the transmission of the client's local address to the HSM.

Session Cache

Environment variable to be set: HSM_DISABLE_SESSION_CACHE

Value	Session cache
Not defined	enabled
0	enabled
1	disabled

Only disable the session cache if you are certain that the application will benefit from this configuration.

In conjunction with balancing, a session caching system works to improve the use of network bandwidth and the allocation/deallocation of resources in the HSM and on the application server. When the application requests that the session be terminated from the HSM, it is terminated logically (for the application, the session has been successfully closed); the HSM library (loaded into the address space of the application process) maintains the physical session with the HSM for a certain period of time; if a new session is requested, the library reuses that physical session (re-authenticating the user locally). By reusing an already established session, there is a benefit in not having to negotiate the physical session again, especially if the application is using encrypted sessions (TLS). The type of the new session (open or encrypted) must be the same as the existing physical session. If the physical session in the cache is not reused within the timeout period, it is physically terminated.

The session cache has the following characteristics:

1. Intra-process: The cache is implemented per process. This means that two applications on the same machine will each have their own cache, without sharing sessions between processes;
2. Centralized: implemented in the HSM library. This way the cache is enabled at a central point and all other libraries dependent on it inherit the functionality;
3. Transparent: to enable session caching, only an environment variable needs to be enabled. No application changes are required.

Remarks:

1. Sessions with 2nd factor authentication are not cached. An example is the use of OTP;
2. Session caching can be bypassed in a specific session by using the CACHE_BYPASS flag in DOpenSession;
3. Session caching is enabled by default;
4. A session can be forced to be removed from the cache by using the CLOSE_PHYSICALLY flag in DCloseSession;
5. Can be used in conjunction with load balancing.
6. The waiting time until the session is discarded by the library is 04 minutes.

A session cache flow can be represented as in the figure below:

---
title: Fluxo de cache de sessões
---

%%{ init: { 'flowchart': { 'curve': 'basis' }} }%%
sequenceDiagram
    autonumber
    participant app as Aplicação
    participant lib as Biblioteca
    participant hsm as HSM

    app ->> lib: Início da sessão 1
    activate app
    lib ->> hsm: Abre sessão
    activate lib
    activate hsm
    loop Sessão 1
        %% necessário manter o espaço após o spi: (ou usar um text)
        app -->> lib: Requisição
        lib -->> app: Resposta
    end
    app ->> lib: Fim da sessão 1
    deactivate app

    Note right of lib: A sessão física<br>permanece aberta

    app ->> lib: Início da sessão 2
    activate app
    Note right of lib: A sessão existente<br>é reutilizada
    loop Sessão 2
        %% necessário manter o espaço após o spi: (ou usar um text)
        app -->> lib: Requisição
        lib -->> app: Resposta
    end
    app ->> lib: Fim da sessão 2
    deactivate app
    deactivate lib
    deactivate hsm

For more details see the topic Session Cache.

Session Cache Timeout

Environment variable to be set: HSM_SESSION_CACHE_TIMEOUT

Value	Suspension Time
Not defined	default suspension time of 180 seconds.
n	timeout duration in seconds.

The timeout period after which a session is marked as non-reusable by the session cache. This parameter sets the initial session cache timeout value for all sessions, but this value can be changed individually at runtime using the APIs.

Info

If the network timeouts (send/receive) are shorter than the session cache timeout, the shorter one will take precedence to prevent inactive sessions from being returned.

As of: version 4.25.0.

Load Balancing

Environment variable to be set: HSM_LOAD_BALANCE_LIST

Value	Load Balancing
Not defined	disabled
file name	use the list of HSMs

It contains the path and name of the file with the list of IP addresses and ports of the HSMs. Each line of the file must contain the address and port (use 4433) of an HSM. Up to sixteen addresses can be entered. The file must be in ASCII text format with the following content:

<endereco_ip_1>        <porta>
<endereco_ip_2>        <porta>
...
<endereco_ip_16>        <porta>

Example:

10.0.20.1        4433
10.0.20.2        4433

An active-passive load balancing scheme can be implemented, where multiple lists (up to 16) are defined, and the library cycles through them in a round-robin fashion. If none of the HSMs in the current list respond to a session opening request, the next list will be utilized and will remain in use until none of its HSMs respond, at which point the subsequent list is loaded, and so on. This functionality is available from library version 1.3.0.14.

To use this active-passive scheme, create each list of HSMs in a file with the format indicated above, and in the value of the environment variable indicate all the files, with the full path, separated according to the standard of the operating system where you are running the application, ; for Windows and : for Unix/Linux.

Dinamo has a load balancing mechanism, allowing for greater availability of the environment and performance for applications. It is possible to have up to 16 (sixteen) Dinamo units in a load balancing system, with the same number of sessions on each device. Load balancing is transparent to the application, i.e. once load balancing has been enabled in the environment, the application benefits from it without the need for any changes.

Balancing works on a round-robin basis, distributing connections circularly between the HSMs configured for balancing. The balancing unit is the session with the HSM, regardless of the load or APIs used in each session and also the resource utilization rate in each HSM. The HSM that will establish the session with the application is defined by the balancing framework and not by the application. The balancing scheme 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.

If the application is using objects stored in the HSM, the object must exist in all the HSMs. It is recommended that an HSM is initially prepared with all the objects used by the application and a backup is generated from it, which will be restored in all the other HSMs that are part of the balancing set.

Attention

Balancing cannot be used by applications that create objects within a session, need to persist these objects between sessions but do not use the HSM's replication mechanism, because in this case the creation of the object is not replicated between the HSMs and there is no guarantee that the next session will be directed to the HSM where the object was created. For applications that create objects that must persist between sessions, and the HSM replication mechanism is not used, it is up to the application to maintain a synchronization mechanism between the bases of the HSMs participating in the balancing. This mechanism can be based on exporting and importing objects, for example.

Load balancing and session caching are enabled via environment variables. If the environment variable definition has a system-wide scope, all applications benefit from the load balancing and/or caching structure (as processes inherit system environment variable definitions). It is also possible to configure the environment variable only for a specific application's process. Refer to the operating system documentation for details on creating and scoping environment variables.

Load balancing has the following characteristics:

1. Intra-process: Load balancing is performed per process. This means that two applications on the same machine will have distinct load balancing sets;
2. Centralized: implemented in the HSM library. This way balancing is enabled at a central point and all other libraries dependent on it inherit the functionality
3. Transparent: To enable load balancing, it is only necessary to enable an environment variable. No changes to the application's source code are required.

A structural diagram of the load balancing mechanisms is shown in the figure below:

---
title: Balanceamento de carga
---

%%{ init: { 'flowchart': { 'curve': 'basis' } } }%%

flowchart LR

    classDef red_s stroke:#f00
    s1.1[Sessão 1]
    s2.1[Sessão 2]
    sn.1[Sessão n]
    lib1((biblioteca<br>fa:fa-list-ol)):::red_s

    s1.2[Sessão 1]
    s2.2[Sessão 2]
    sn.2[Sessão n]
    lib2((biblioteca<br>fa:fa-list-ol)):::red_s

    hsm1[fa:fa-network-wired HSM 1]
    hsm2[fa:fa-network-wired HSM 2]
    hsmn[fa:fa-network-wired HSM n]

    subgraph Processo 1
    s1.1 --> lib1
    s2.1 --> lib1
    sn.1 --> lib1
    end

    subgraph Processo 2
    s1.2 --> lib2
    s2.2 --> lib2
    sn.2 --> lib2
    end

    %%subgraph Pool de HSMs
    hsm1:::red_s
    hsm2:::red_s
    hsmn:::red_s
    %%end

    lib1 -...-> hsm1
    lib1 -...-> hsm2
    lib1 -...-> hsmn

    lib2 -...-> hsm1
    lib2 -...-> hsm2
    lib2 -...-> hsmn

For more details, see the "Load Balancing" topic.

Update interval

Environment variable to be set: HSM_LB_FILE_REFRESH_INTERVAL

Value	Update Interval
Not defined	only at library startup.
0	only at library startup.
n	reload (in seconds) of the balance list.

The lists loaded are those defined in the HSM_LOAD_BALANCE_LIST environment variable.

If the load balancing list files are corrupted or invalid, the modified load balancing list will not be updated.

If the modified load balancing list is identical to the current load balancing list, the update will not be performed to prevent unnecessary reloading of the load balancing list.

If the load balancing list is updated, current sessions will be marked for termination upon completion of operations, and new sessions will be created using the new load balancing list.

Suspension Time

Environment variable to be set: HSM_BALANCE_SUSPEND_TIME

Value	Suspension Time
Not defined	default suspension time of 120 seconds.
n	suspension time in seconds.

During library operation with load balancing, it may occur that one or more of the addresses specified in the list fail to establish a session with the application. In such a case, the library will temporarily remove the problematic address from the load balancing list and will attempt a new connection after this period expires.

Interval from Pix Request

Environment variable to be set: HSM_PIX_HTTP_CONN_REFRESH_INTERVAL

Value	Update Interval
Not defined	updates the objects with each Pix Request operation.
0	updates the objects with each Pix Request operation.
n	reload (in seconds) of the balance list.

Each Pix Request operation ( HTTP POST, GET and DELETE requests) loads the objects stored in the HSM (private key handle, certificate and peer chain) in order to close the TLS tunnel.

The advantage of reloading objects after each Pix Request operation is that it allows the object to be reloaded in the next operation if it changes. On the other hand, this frequent reloading causes an unnecessary performance cost.

The advantage of setting a time interval for reloading HSM objects in Pix Request operations is a performance gain. This allows for an improvement in performance at the cost of having to wait no longer than the reload time defined in the environment variable for the new objects to be reloaded. As the exchange of keys and certificates is usually done infrequently, it is possible to set an interval for the objects to be reloaded with reduced impact.

Enter Local Address

Environment variable to be set: HSM_DISABLE_TELL_ADDR

Value	Enter Local Address
Not defined	enabled
0	enabled
1	disabled

When enabled, the library reports the client's local address to the HSM when establishing the session. This makes it possible to identify, through the HSM logs, the address of the client that actually initiated the session, even when there is an external load balancer between the application and the HSM—a situation in which the HSM would only see the load balancer's address.

This feature is enabled by default (only for authenticated sessions) and is available starting with firmware versions 5.12 and 6.10.