Configuração

A biblioteca PKCS#11 do HSM Dinamo está em uma camada acima da API nativa do Dinamo. Você pode consultar as opções de configuração da biblioteca cliente no Manual de Usuário.

A configuração é feita através de variáveis de ambiente (com prefixo DFENCE_PKCS11_) que devem ser setadas no escopo do sistema, do usuário ou do processo que faz o carregamento da biblioteca.

Info

Atenção: Sempre que forem alteradas as variáveis de ambiente é necessário que se reinicie a aplicação.

User

DFENCE_PKCS11_USER

Id (nome) do usuário (userid) do HSM que será utilizado pela PKCS#11.

Variável deve ser definida com o id do usuário para que a biblioteca PKCS#11 funcione corretamente.

Obs: caso use o parâmetro pPin para informar o id do usuário (ver variável DFENCE_PKCS11_SPECIAL_PWD abaixo) não há necessidade de definir DFENCE_PKCS11_USER.

Endereço IP

DFENCE_PKCS11_IP

Endereço IP do HSM.

Variável deve ser definida com o endereço IP do HSM para que a PKCS#11 funcione corretamente.

Obs: caso use o parâmetro pPin para informar o endereço IP do HSM (ver variável DFENCE_PKCS11_SPECIAL_PWD abaixo) o endereço IP definido aqui será usado nas funções PKCS#11 não autenticadas (ex: C_GetTokenInfo, C_GetSlotInfo, etc ) e o endereço IP informado em pPin será usado na operação de autenticação.

Special PIN

DFENCE_PKCS11_SPECIAL_PWD

Habilita a passagem do id de usuário, senha e endereço IP do HSM no parâmetro pPin da função PKCS#11 C_Login.

Variável não definida ou variável definida para 0: o parâmetro pPin (na função PKCS#11 C_Login) deverá receber apenas a senha (password) do usuário do HSM:

password

Variável definida para 1: o parâmetro pPin (em C_Login ) deverá receber o id do usuário (userid), a senha (password) o endereço IP do HSM (ip) no formato:

userid:password@ip

Ex.: master:12345678@10.0.62.10

Caso o balanceamento de carga esteja habilitado o IP será ignorado internamente.

Para as funções PKCS#11 não autenticadas o endereço IP utilizado será aquele informado na varíável DFENCE_PKCS11_IP.

Encrypted

DFENCE_PKCS11_ENCRYPTED

Define se a conexão feita com o HSM deve ser encriptada (TLS) ou em texto claro (clear text).

Variável não definida ou variável definida para 1: a conexão com o HSM será encriptada.

Variável definida para 0: a conexão com o HSM será em texto claro.

É recomendado que se utilize a conexão encriptada.

Auto Reconnect

DFENCE_PKCS11_AUTO_RECONNECT

Habilita a tentativa de reconexão automática de sessões do HSM em casos de falha.

Variável não definida ou definida em 0: auto-reconnect é desabilitado.

Variável definida em 1: auto-reconnect é habilitado.

É recomendado que se utilize o auto-reconnect habilitado.

O auto-reconnect está disponível nas APIs que acessam o HSM e que não fazem parte de operações que necessitem de mais de uma etapa para serem finalizadas.

Exemplos de APIs que não contam com o auto-reconnect: C_Encrypt, C_EncryptUpdate, C_Decrypt, C_DecryptUpdate etc. Em caso de falha de rede nestas funções, deve-se fechar a sessão que falhou, abrir uma nova e refazer a operação.

Log Path

DFENCE_PKCS11_LOG_PATH

Caminho com o nome do arquivo que conterá os logs gerados pela biblioteca.

Variável não definida o log não é gerado.

Variável definida deve conter caminho e nome do arquivo.

Ex.: c:\tacndp11.log

Log Level

DFENCE_PKCS11_LOG_LEVEL

Define o nível de log.

Os níveis de log são:

0 : apenas erros; registra apenas situações de erro. (que normalmente impedem a execução do serviço solicitado).
3 : depuração; registra informações detalhadas de operação, além das mensagens de erro.
1000 : desabilitado; nenhum evento é registrado em log.

Em condições normais de operação, é recomendável manter o mínimo de log da biblioteca. O nível de depuração pode ser usado para diagnosticar problemas de operação.

Log Flush

DFENCE_PKCS11_LOG_FLUSH

Habilita a escrita das mensagens de log diretamente no arquivo de log, sem utilizar buffer.

Variável não definida ou definida para 0: as mensagens de log são buferizadas e gravadas no arquivo de logs em intervalos.

Variável definida para 1: as mensagens de log são gravadas diretamente no arquivo.

A biblioteca pode manter um pequeno buffer de mensagens de log antes de fazer a gravação física no arquivo. Isto permite ganhos de desempenho. Em condições de erro ou situações de diagnóstico, é interessante que o registro seja gravada imediatamente após sua ocorrência.

Large Find List

DFENCE_PKCS11_LARGE_FIND_LIST

Habilita o uso de busca para grandes quantidades de objetos.

Variável não definida ou definida para 0: utiliza o sistema de busca padrão com limite de leitura de 512 objetos por usuário. Os objetos que estiverem acima do limite de 512 objetos não são listados na busca.

Permite que se façam outras chamadas utilizando a mesma sessão durante uma operação de busca.

Exemplo permitido:

C_FindObjectsInit(session1);
    . . .
    C_FindObjects(session1);
    . . .
    C_GetAttributeValue(session1);
    . . .
C_FindObjectsFinal(session1);

Variável definida para 1: utiliza o sistema de busca para grandes quantidades de objetos por usuário.

Busca por quantidades maiores do que 512 objetos, mas não permite que se façam outras chamadas utilizando a mesma sessão durante uma operação de busca.

Exemplo permitido:

C_FindObjectsInit(session1);
    . . .
    C_FindObjects(session1);
    . . .
C_FindObjectsFinal(session1);
. . .
C_GetAttributeValue(session1);

Exemplo não permitido:

C_FindObjectsInit(session1);
    . . .
    C_FindObjects(session1);
    . . .
    C_GetAttributeValue(session1);
    . . .
C_FindObjectsFinal(session1);

Objetos Não Privados

HSM_PKCS11_NON_PRIVATE_OBJECTS_SUPPORT

Habilita a criação de objetos não privados (atributo CKA_PRIVATE igual a 0).

O atributo de objeto CKA_PRIVATE indica se um objeto é privado ou público no que diz respeito aos seus requisitos de acesso. No contexto da PKCS#11, um objeto público pode ser acessado por uma sessão autenticada ou não autenticada, já o objeto privado pode ser acessado apenas utilizando uma sessão autenticada.

Para permitir a criação de objetos públicos (CKA_PRIVATE igual a 0), esta variável de ambiente deve ser utilizada.

Variável não definida ou definida para 0: não permite a geração de objetos públicos (CKA_PRIVATE igual a 0).

Variável definida para 1: permite a geração de objetos públicos (CKA_PRIVATE igual a 0).

Atributos Conflitantes

HSM_PKCS11_DISABLE_CONFLICTING_ATTR

Permite o uso de atributos conflitantes (ex. CKA_SENSITIVE e CKA_EXTRACTABLE com valores CK_TRUE).

Para permitir a criação de objetos com atributos conflitantes, esta variável de ambiente deve ser utilizada. Atualmente, esta opção tem validade para os atributos CKA_SENSITIVE e CKA_EXTRACTABLE.

Variável não definida ou definida para 0: não permite a geração de objetos com atributos conflitantes.

Variável definida para 1: permite a geração de objetos com atributos conflitantes.