Sessões

São detalhadas abaixo as configurações para controle de balanceamento de carga e cache de sessões.

Variável	Descrição Rápida
`HSM_DISABLE_SESSION_CACHE`	Desabilita (valor em 1) o cache de sessão.
`HSM_SESSION_CACHE_TIMEOUT`	Tempo em segundos do timeout do cache de sessão.
`HSM_LOAD_BALANCE_LIST`	Caminho do arquivo com a lista de HSMs para o balanceamento.
`HSM_LB_FILE_REFRESH_INTERVAL`	Intervalo (em segundos) de atualização do arquivo de balanceamento.
`HSM_BALANCE_SUSPEND_TIME`	Tempo (em segundos) de suspensão automática de um HSM não responsivo da lisa de balanceamento.
`HSM_PIX_HTTP_CONN_REFRESH_INTERVAL`	Intervalo (em segundos) de atualização do carregamento dos objetos do HSM nas operações de Pix request(POST/GET/DELETE).
`HSM_DISABLE_TELL_ADDR`	Desabilita (valor em 1) o envio do endereço local do cliente ao HSM.

Cache de Sessão

Variável de ambiente a ser definida: HSM_DISABLE_SESSION_CACHE

Valor	Cache de Sessões
Não definida	habilitado
0	habilitado
1	desabilitado

Somente desabilite o cache de sessões se tiver certeza que a aplicação será de alguma forma beneficiada com esta configuração.

Em conjunto com o balanceamento funciona um sistema de cache de sessões, visando aperfeiçoar o uso de banda de rede e alocação/desalocação de recursos no HSM e no servidor da aplicação. Quando a aplicação solicita o término da sessão ao HSM, ela é finalizada logicamente (para a aplicação a sessão foi fechada com sucesso); a biblioteca do HSM (carregada no espaço de endereço do processo da aplicação) mantém por um determinado tempo a sessão física com o HSM; se uma nova sessão for solicitada, a biblioteca reutiliza aquela sessão física (re-autenticando localmente o usuário). Ao reutilizar uma sessão já estabelecida há um ganho por não se fazer novamente a negociação da sessão física, principalmente se a aplicação estiver usando sessões cifradas (TLS). O tipo da nova sessão (aberta ou cifrada) deve ser o mesmo da sessão física existente. Caso a sessão física no cache não seja reutilizada dentro do tempo de espera, ela é fisicamente encerrada.

O cache de sessões tem as seguintes características:

Intra-processo: o cache é feito por processo. Isso significa que 2 aplicações em uma mesma máquina terão um cache cada uma, sem compartilhar sessões entre os processos;
Centralizado: implementado na biblioteca do HSM. Desta forma o cache é habilitado em um ponto central e todas as outras bibliotecas dependentes dela herdarão a funcionalidade;
Transparente: para habilitar o cache de sessões é necessário apenas habilitar uma variável de ambiente. Não há necessidade de alteração na aplicação.

Observações:

Sessões com autenticação de 2o. fator não entram no cache. Um exemplo é o uso de OTP;
O cache de sessões pode ser ignorado, em uma determinada sessão, usando a flag CACHE_BYPASS em DOpenSesssion;
O cache de sessões é habilitado por padrão;
Uma sessão pode ser forçada a ser removida do cache utilizando a flag CLOSE_PHYSICALLY em DCloseSession;
Pode ser utilizado juntamente com o balanceamento de carga.
O tempo de espera até a sessão ser descartada pela biblioteca é de 04 minutos.

Um fluxo do cache de sessões pode ser representado como na figura abaixo:

---
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

Para mais detalhes consulte o tópico Cache de Sessão.

Timeout de Cache de Sessão

Variável de ambiente a ser definida: HSM_SESSION_CACHE_TIMEOUT

Valor	Tempo de Suspensão
Não definida	tempo de suspensão default de 180 segundos.
n	tempo em segundos do timeout.

O tempo de timeout para que uma sessão seja marcada como não reutilizável pelo cache de sessão. Este parâmetro define o valor inicial de timeout de cache de sessão de todas as sessões, mas elas podem ter seu valor alterado individualmente em tempo de execução utilizando as APIs.

Info

Se os timeouts de rede (send/receive) forem menores do que o timeout do cache de sessão, o menor prevalecerá para evitar a devolução de sessões inativas.

Desde: version 4.25.0.

Balanceamento de Carga

Variável de ambiente a ser definida: HSM_LOAD_BALANCE_LIST

Valor	Balanceamento de Carga
Não definida	desabilitado
nome do arquivo	usa a lista de HSMs

Contem o caminho e nome do arquivo com a lista de endereços IPs e portas dos HSMs. Em cada linha do arquivo deve ser indicado o endereço e a porta (usar 4433) de um HSM. Até dezesseis endereços podem ser informadas. O arquivo deverá ser em formato texto ASCII com o seguinte formato no conteúdo:

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

Exemplo:

10.0.20.1        4433
10.0.20.2        4433

É possível ter um esquema de balanceamento do tipo ativo-passivo, onde várias listas (até 16) são definidas, e a biblioteca vai passar de uma lista para outra, em esquema circular tipo round robin. Quando nenhum dos HSMs da lista atual responder ao pedido de abertura de sessão, a próxima lista passa a ser utilizada, e permanece sendo utilizada até que novamente nenhum dos HSMs responda e então a próxima lista é carregada e assim por diante. Esta funcionalidade está disponível a partir da versão 1.3.0.14 da biblioteca.

Para utilizar este esquema ativo-passivo crie cada lista de HSMs em um arquivo com o formato indicado acima, e no valor da variável de ambiente indique todos os arquivos, com o caminho completo, separando conforme o padrão do sistema operacional onde estiver executando a aplicação, ; para Windows e : para Unix/Linux.

O Dinamo dispõe de um mecanismo de balanceamento de carga, permitindo maior disponibilidade do ambiente e desempenho para as aplicações. É possível ter até 16 (dezesseis) unidades do Dinamo em sistema de balanceamento de carga, com a mesma quantidade de sessões em cada um dos equipamentos. O balanceamento de carga é transparente para a aplicação, ou seja, uma vez habilitado o balanceamento no ambiente, a aplicação se beneficia sem precisar de qualquer alteração.

O balanceamento funciona num esquema tipo round-robin, distribuindo conexões circularmente entre os HSM configurados para balanceamento. A unidade de balanceamento é a sessão com o HSM, independente da carga ou das APIs utilizadas em cada sessão e também da taxa de utilização de recursos em cada HSM. O HSM que vai estabelecer a sessão com a aplicação é definido pela estrutura de balanceamento e não pela aplicação. O esquema do balanceamento funciona por processo, ou seja, dentro de cada processo são suas sessões que serão balanceadas; caso dois processos rodem ao mesmo tempo, cada um terá uma estrutura de balanceamento separada e independente.

Caso a aplicação esteja utilizando objetos armazenados no HSM, é preciso que o objeto exista em todos os HSMs. O recomendado é que um HSM seja preparado inicialmente com todos os objetos usados pela aplicação e a partir dele seja gerado um backup, que será restaurado em todos os demais HSMs que fazem parte do conjunto de balanceamento.

Atenção

O balanceamento não pode ser usado por aplicações que criam objetos dentro da sessão, precisam persistir estes objetos entre sessões mas não utilizam o mecanismo de replicação do HSM, pois neste caso a criação do objeto não é replicada entre os HSMs e não há garantia que a próxima sessão será dirigida ao HSM onde o objeto foi criado. Para aplicações que criam objetos que devem persistir entre sessões, e o mecanismo de replicação do HSM não seja utilizado, é função da aplicação manter um mecanismo de sincronização entre as bases dos HSMs participantes do balanceamento. Tal mecanismo pode ser baseado por exemplo na exportação e importação de objetos.

O balanceamento de carga e o cache de sessões são habilitados por intermédio de variáveis de ambiente. Se a definição das variável de ambiente tiver escopo de sistema (system wide), todas as aplicações são beneficiadas pela estrutura de balanceamento e/ou cache (pois os processos herdam as definições de variáveis de ambiente do sistema). Também é possível fazer uma configuração definindo a variável de ambiente apenas para o processo particular de uma aplicação. Consulte a documentação do sistema operacional para detalhes sobre criação e escopo de variáveis de ambiente.

O balanceamento de carga m as seguintes características:

Intra-processo: o balanceamento de carga é feito por processo. Isso significa que 2 aplicações em uma mesma máquina terão conjuntos de balanceamento distintos;
Centralizado: implementado na biblioteca do HSM. Desta forma o balanceamento é habilitado em um ponto central e todas as outras bibliotecas dependentes dela herdarão a funcionalidade
Transparente: para habilitar o balanceamento é necessário apenas habilitar uma variável de ambiente. Não é necessário nenhuma alteração de código fonte da aplicação

Um diagrama estrutural do mecanismos de balanceamento de carga é mostrado na figura abaixo:

---
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

Para mais detalhes consulte o tópico Balanceamento de Carga.

Intervalo de Atualização

Variável de ambiente a ser definida: HSM_LB_FILE_REFRESH_INTERVAL

Valor	Intervalo de atualização
Não definida	somente na inicialização da biblioteca.
0	somente na inicialização da biblioteca.
n	recarga (em segundos) da lista de balanceamento.

As listas carregadas são as definidas na variável de ambiente HSM_LOAD_BALANCE_LIST.

Caso os arquivos da lista de balanceamento estejam corrompidos, inválidos a lista de balanceamento alterada não será atualizada.

Caso a lista de balanceamento alterada esteja igual a lista de balanceamento atual a atualização não será efetuada, para evitar o recarregamento desnecessário da lista de balanceamento.

Caso a lista de balanceamento seja atualizada, as sessões atuais serão marcadas para serem finalizadas ao término das operações e as novas sessões serão criadas utilizando a nova lista de balanceamento.

Tempo de Suspensão

Variável de ambiente a ser definida: HSM_BALANCE_SUSPEND_TIME

Valor	Tempo de Suspensão
Não definida	tempo de suspensão default de 120 segundos.
n	tempo em segundos de suspensão.

Durante a operação da biblioteca com balanceamento de carga pode acontecer de um ou mais dos endereços indicados na lista não conseguir estabelecer sessão com a aplicação. Neste caso a biblioteca vai retirar temporariamente da lista de balanceamento o endereço problemático e vai tentar uma nova conexão vencido este prazo.

Intervalo de Pix Request

Variável de ambiente a ser definida: HSM_PIX_HTTP_CONN_REFRESH_INTERVAL

Valor	Intervalo de atualização
Não definida	atualiza os objetos a cada operação de Pix Request.
0	atualiza os objetos a cada operação de Pix Request.
n	recarga (em segundos) da lista de balanceamento.

Em cada operação Pix Request (Requisições HTTP POST, GET e DELETE) é feito o carregamento dos objetos armazenados no HSM (handle de chave privada, certificado e cadeia do peer) para poder realizar o fechamento do túnel TLS.

A vantagem do recarregamento dos objetos à cada operação de Pix Request é que permite que, caso o objeto seja alterado, ele seja recarregado já na proxima operação. Por outro lado, estes recarregamento frequente causa um custo de performance desnecessário.

A vantagem de definir um intervalo de tempo para que haja o recarregamento dos objetos do HSM nas operações de Pix Request é um ganho de performance. Isto permite uma melhoria na performance com o custo de ter que esperar no máximo o tempo de recarga definido na variável de ambiente para que os novos objetos sejam recarregados. Como normalmente a troca de chaves e certificados é feita com pouca frequência, é possível configurar um intervalo para que os objetos sejam carregados com impacto reduzido.

Informar Endereço Local

Variável de ambiente a ser definida: HSM_DISABLE_TELL_ADDR

Valor	Informar Endereço Local
Não definida	habilitado
0	habilitado
1	desabilitado

Quando habilitado, a biblioteca informa ao HSM o endereço local do cliente ao estabelecer a sessão. Desta forma é possível identificar, através dos logs do HSM, o endereço do cliente que efetivamente originou a sessão mesmo quando exista um load balancer externo entre a aplicação e o HSM, situação em que o HSM veria apenas o endereço do balanceador.

Esta funcionalidade é habilitada por padrão (apenas para sessões autenticadas) e está disponível a partir das versões de firmware 5.12 e 6.10.