Sessions

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

Variable	Quick Description
HSM_DISABLE_SESSION_CACHE	Disables (set to 1) the session cache.
HSM_LOAD_BALANCE_LIST	Path to the file with the list of HSMs for balancing.
HSM_LB_FILE_REFRESH_INTERVAL	Balance file update interval (in seconds).
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.

Session cache

Environment variable to be defined: HSM_DISABLE_SESSION_CACHE

Value	Session cache
Not defined	enabled
0	enabled
1	disabled

Only disable session caching if you are sure that the application will benefit in some way from this configuration.

For more details see the topic Session Cache.

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: caching is done per process. This means that 2 applications on the same machine will each have a cache, without sharing sessions between the 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 you just need to enable an environment variable. There is no need to change the application.

Comments:

1. Sessions with 2nd factor authentication are not cached. An example is the use of OTP;
2. The session cache can be ignored in a given session using the CACHE_BYPASS flag in DOpenSesssion;
3. Session caching is enabled by default;
4. A session can be forced to be removed from the cache using the CLOSE_PHYSICALLY flag in DCloseSession;
5. It can be used in conjunction with load balancing.
6. The waiting time before 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

Load balancing

Environment variable to be defined: 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

It is possible to have an active-passive balancing scheme, where several lists (up to 16) are defined, and the library moves from one list to another, in a circular round robin scheme. When none of the HSMs in the current list responds to the request to open a session, the next list is used, and remains in use until none of the HSMs respond again, and then the next list is loaded, and so on. This functionality is available from version 1.3.0.14 of the library.

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 is system wide, all applications benefit from the balancing and/or caching structure (because the processes inherit the environment variable definitions from the system). It is also possible to make a configuration by setting the environment variable only for the particular process of an application. Consult the operating system documentation for details on creating and scoping environment variables.

Load balancing has the following characteristics:

1. Intra-process: load balancing is done per process. This means that 2 applications on the same machine will have different 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 balancing you just need to enable an environment variable. No changes to the application's source code are required

A structural diagram of the load balancing mechanism 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

Update interval

Environment variable to be defined: 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 environment variable HSM_LOAD_BALANCE_LIST.

If the balance list files are corrupted or invalid, the changed balance list will not be updated.

If the changed balance list is the same as the current balance list, the update will not be carried out, to avoid unnecessary reloading of the balance list.

If the balance list is updated, the current sessions will be marked for termination at the end of operations and new sessions will be created using the new balance list.

Suspension time

Environment variable to be defined: HSM_BALANCE_SUSPEND_TIME

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

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.

Interval from Pix Request

Environment variable to be defined: 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.