Introdução

Esta documentação descreve as APIs proprietárias do HSM, com as estruturas de dados, funções, códigos de retorno e exemplos. Sobre as configurações dos parâmetros da biblioteca, como balanceamento de carga e cache de sessões (estes parâmetros influenciam o funcionamento das APIs) consulte a documentação sobre Software cliente .

As APIs do HSM permitem a utilização de características de segurança/criptografia nas aplicações, no entanto esta documentação não cobre ou discute a teoria de segurança/criptografia e tampouco os detalhes, como pontos fortes e fracos de cada algoritmo específico e nem projetos de protocolo. Criptografia é um assunto complexo e avançado, é sempre recomendável consultar uma referência sólida e recente para fazer o melhor uso do HSM. Procure sempre entender o que está fazendo e o porquê de estar fazendo. Não simplesmente copie código para resolver os problemas no seu cenário. Muitas aplicações já foram desenvolvidas com sérios problemas de segurança apenas por que a ferramenta errada foi escolhida.

Interface de Programação

Os HSMs DINAMO proveem uma interface de programação cliente bastante rica e versátil, permitindo uma rápida e fácil integração em qualquer tipo de aplicação. A DINAMO fornece uma API para as plataformas Windows e Linux (distribuições Red Hat e Ubuntu) nos pacotes de software cliente. Consulte para versões específicas de Unix e Linux ou outras plataformas.

Observação: As sessões do HSM possuem afinidade sessão-thread. O que significa que a mesma sessão não pode ser utilizada em várias threads ao mesmo tempo.

As sessões de comunicação abertas pelo cliente até o serviço do HSM podem ser cifradas ou abertas. Quando cifradas é usado o protocolo TLS (Transport Layer Security). Há um timeout por inatividade de 20 (vinte) minutos, ou seja, após este período sem requisições do cliente para o servidor, o serviço do HSM termina imediatamente a sessão do cliente e somente abrindo uma nova conexão (com uma nova autenticação) o cliente conseguirá comunicação novamente. Este timeout evita travamento de sessões e acrescenta um nível de segurança ao canal.

Há um limite de 07 sessões simultâneas que podem receber notificações de log (follow).

Os HSMs DINAMO são desenhados com um gerenciamento de chaves simétricas e assimétricas bastante otimizado, tanto em termos de performance no cliente e no HSM, quanto de facilidade de programação. As operações de geração, recuperação e remoção de chaves são atômicas, e cada chave tem um identificador único. Os atributos específicos de cada chave (tipo, tamanho, valor, exportável, cifrada, etc.) são armazenados em estruturas de cache, o que oferece um substancial ganho de desempenho, sem comprometer a segurança. Todas as chaves armazenadas internamente com o atributo de criptografia habilitado são cifradas pela SVMK (Server Master Key), que por sua vez só é introduzida no sistema após a autenticação através do cartão Smart Card, e é mantida apenas em memória volátil.

A remoção de chaves é uma operação definitiva e não há como recuperar chaves apagadas, por isso a aplicação deve programar mecanismos de checagem antes de proceder a uma operação de remoção de chave. Uma mensagem encravada por uma chave apagada estará virtualmente perdida, pois somente através de ataque de força bruta será possível recuperar tal mensagem, o que pode ser computacionalmente inviável.

A função de probe permite que se verifique o estado do HSM com um mínimo de tráfego e de processamento.

Observação: A DINAMO está permanentemente aprimorando seus produtos, portanto é possível encontrar pequenas discordâncias entre a documentação e o produto recebido. Em caso de dúvida sinta-se a vontade para procurar o suporte da DINAMO e esclarecer suas dúvidas.

Na descrição dos parâmetros será utilizado [in] para indicar que o valor deste parâmetro deverá ser preenchido antes da função ser chamada (parâmetro de entrada), [out] para indicar que o valor será preenchido internamente na função e devolvido na saída (parâmetro de saída) e [in/out] para indicar que o parâmetro deverá ser preenchido antes da função ser chamada e poderá ser alterado internamente (parâmetro bidirecional).

Variáveis de Ambiente

Diversos aspectos do funcionamento da biblioteca podem ser configurados e controlados via variáveis de ambiente. Consulte na documentação do HSM o tópico Variáveis de Ambiente sobre as opções disponíveis e detalhes.

Notas

As interfaces de programação em diferentes linguagens disponíveis para o HSM:

Informações como características, inicialização, gerenciamento, integração e outras podem ser encontradas na documentação técnica do HSM .

Para informações sobre versões de software consulte as Notas de Lançamento e os Downloads DINAMO .