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. Consulte também o Manual de Software cliente sobre as configurações dos parâmetros da biblioteca, como balanceamento de carga e cache de sessões; alguns destes parâmetros influenciam o funcionamento das APIs.

As APIs do HSM permitem a utilização de características de segurança/criptografia nas aplicações, no entanto este manual 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

O HSM Dinamo provê 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 Networks fornece uma API para as plataformas Windows, Unix e Linux no pacote Dinamo. 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 Dinamo podem ser cifradas ou abertas. Quando cifradas é usado o protocolo TLS (Transport Layer Security). Há um timeout por inatividade de 05 (cinco) minutos, ou seja, após um período de 20 minutos sem requisições do cliente para o servidor, o serviço do Dinamo termina imediatamente a sessão do cliente e somente abrindo uma nova conexão (com uma nova autenticação) o cliente conseguirá comunicação com o Dinamo 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.

O HSM Dinamo foi desenhado 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 Dinamo com um mínimo de tráfego e de processamento.

Observação: A Dinamo Networks 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 Networks e esclarecer suas dúvidas.

Consulte o Manual do Usuário sobre opções de parâmetros de configuração da API Nativa.

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

Todas as funções exportadas pelas bibliotecas do Dinamo tem seu nome prefixado com a letra “D”.

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.