Instalar e configurar SoftHSM no Ubuntu

O que é SoftHSM

SoftHSM é uma implementação de um dispositivo criptográfico acessível via PKCS#11. PKCS#11 é uma API padrão para comunicação com HSMs (Hardware Security Modules) e smartcards. O propósito principal de um HSM é gerar chaves criptográficas e assinar/criptografar dados sem revelar a chave privada para aplicações externas.

Termo: PKCS#11 — padrão de interface para dispositivos criptográficos (HSMs e smartcards).

Contexto: SoftHSM foi desenvolvido para permitir que projetos como OpenDNSSEC funcionem mesmo quando não há HSM físico disponível. Ele serve tanto como ferramenta de teste quanto como alternativa de produção em cenários com requisitos de segurança compatíveis.

Variações e alternativas

• HSMs físicos populares: NitroKey, Smartcard-HSM.
• Alternativas de software: SoftHSM v2 (foco deste guia).
• Backends criptográficos suportados: OpenSSL e Botan.

Dependências e recomendações

• Backend: OpenSSL (recomendado) ou Botan. Se usar Botan, compile com suporte a GNU MP (–with-gnump) para melhorar operações com chaves públicas.
• SQLite3: necessário se optar por armazenamento de objetos em BD (–with-objectstore-backend-db).
• p11-kit: integrado por padrão; pode ser desativado (–disable-p11-kit) ou configurado.

Importante: mantenha pacotes de desenvolvimento do OpenSSL instalados (por exemplo, openssl-dev) antes de executar ./configure.

Baixar e compilar

Baixe o tarball oficial do OpenDNSSEC:

wget https://dist.opendnssec.org/source/softhsm-2.3.0.tar.gz

Extraia o pacote:

tar xzf softhsm-2.3.0.tar.gz

Execute o script de configuração para checar dependências:

./configure

Se faltar headers do OpenSSL, instale o pacote de desenvolvimento (exemplo em distribuições Debian/Ubuntu):

apt-get install openssl-dev

Após corrigir dependências, o ./configure deverá listar opções válidas e confirmar dependências atendidas:

Exemplo de opções do configure:

./configure --help

--disable-ecc        Disable support for ECC (default enabled)
--disable-gost       Disable support for GOST (default enabled)
--disable-visibility Disable hidden visibilty link mode [enabled]
--with-crypto-backend Select crypto backend (openssl|botan)
--with-openssl=PATH  Specify prefix of path of OpenSSL
--with-botan=PATH    Specify prefix of path of Botan
--with-migrate       Build the migration tool. Used when migrating
                     a SoftHSM v1 token database. Requires SQLite3
--with-objectstore-backend-db
                     Build with database object store (SQLite3)
--with-sqlite3=PATH  Specify prefix of path of SQLite3
--disable-p11-kit    Disable p11-kit integration (default enabled)
--with-p11-kit=PATH  Specify install path of the p11-kit module, will
                     override path given by pkg-config

Compile e instale:

make

make install

Arquivo de configuração

O arquivo de configuração padrão é /etc/softhsm2.conf. Para usar outro caminho, exporte a variável de ambiente SOFTHSM2_CONF:

export SOFTHSM2_CONF=Path_of_SoftHSM_Conf_file

Pontos importantes no softhsm2.conf: diretório de tokens, políticas de permissão de arquivo e backend selecionado.

Inicializar um token SoftHSM

Para começar a usar, inicialize um token com softhsm2-util:

softhsm2-util --init-token --slot 0 --label "Token-1"

Durante a inicialização será solicitado:

• PIN do Security Officer (SO) — usado para re-inicializar o token.
• PIN do usuário (User PIN) — entregue à aplicação que fará operações com o token (por exemplo, navegador).

Observação: após inicializar um token, slots adicionais podem ser criados automaticamente. Para localizar tokens, é recomendado pesquisar por label ou número de série.

Outras opções do softhsm2-util podem listar objetos, slots e exportar/importar chaves.

Exibir slots disponíveis:

Backup e restauração

Os tokens e seus objetos são armazenados nos caminhos configurados em softhsm2.conf. Backup pode ser feito por cópia regular de arquivos, mas considere:

• Fazer backup offline (desligar serviços que acessam os tokens antes de copiar).
• Proteger backups com criptografia e controle de acesso.
• Registrar hashes e metadados (label, serial) para garantir integridade.

Restauração: recopie os arquivos para o local configurado e ajuste permissões. Se usar backend SQLite, faça dump/restore via sqlite3 para consistência.

Integrar com OpenSC e testar mecanismos PKCS#11

Instale utilitários OpenSC para testar módulos PKCS#11:

apt-get install opensc

Teste o módulo PKCS#11 do SoftHSM:

pkcs11-tool --module /usr/local/lib/softhsm/libsofthsm2.so -l -t

O parâmetro -t executa testes dos mecanismos disponíveis.

Lista de comandos essenciais (cheat sheet)

• Inicializar token:

softhsm2-util --init-token --slot 0 --label "Token-1"

• Listar slots e informações:

softhsm2-util --show-slots
pkcs11-tool --module /usr/local/lib/softhsm/libsofthsm2.so -l --show-info

• Criar chave RSA dentro do token (exemplo):

pkcs11-tool --module /usr/local/lib/softhsm/libsofthsm2.so -l --keypairgen --key-type rsa:2048 --id 01 --label "mykey"

• Fazer backup dos arquivos do token (exemplo):

sudo systemctl stop meu-servico-que-usa-softhsm
cp -a /var/lib/softhsm /backup/softhsm-YYYYMMDD
sudo systemctl start meu-servico-que-usa-softhsm

Segurança e hardening

• Controle de acesso: arquivos do token devem pertencer a usuário e grupo restrito (por exemplo, root:softhsm) e permissões 700/600.
• PINs: use PINs complexos e políticas de expiração/lockout quando suportado pela aplicação.
• Logs: registre operações administrativas separadamente e proteja-os.
• Isolamento: execute SoftHSM em hosts dedicados ou VMs se usado em produção para reduzir superfície de ataque.
• SELinux/AppArmor: aplique perfis mínimos que permitam apenas o necessário para leitura/escrita do diretório configurado.

Observação: SoftHSM é um HSM em software — para requisitos regulatórios/alto risco, prefira HSMs físicos certificados.

Procedimento operacional padrão (SOP) — instalar e inicializar

1. Atualizar sistema e instalar dependências (openssl-dev, sqlite3, pkg-config, p11-kit).
2. Baixar tarball e verificar checksum (se disponível).
3. ./configure com backend desejado (–with-crypto-backend=openssl).
4. make && make install.
5. Configurar /etc/softhsm2.conf e exportar SOFTHSM2_CONF se necessário.
6. Inicializar token com softhsm2-util e registrar SO PIN e User PIN em cofre seguro.
7. Testar com pkcs11-tool e integrar aplicação (configurar module path).
8. Realizar backup inicial e testar restauração em ambiente isolado.

Checklist por função

Administrador de sistema:

• Instalar dependências e compilar.
• Configurar permissões e backups.
• Documentar caminhos e variáveis de ambiente.

Operador de segurança:

• Gerenciar PINs no cofre de credenciais.
• Auditar logs de acesso.
• Atualizar políticas de SELinux/AppArmor.

Desenvolvedor/Integradora:

• Apontar aplicação para libsofthsm2.so.
• Validar operações PKCS#11 (assinatura, geração de chaves).
• Testar migração se houver SoftHSM v1.

Migração e compatibilidade

• Migração de SoftHSM v1 requer a ferramenta de migração (–with-migrate) e SQLite3. Teste a migração em ambiente não produtivo.
• Ao trocar backend (OpenSSL vs Botan), revalide formatos de chaves e operações suportadas.
• Verifique compatibilidade de aplicativos que usam p11-kit e ajuste módulos conforme necessário.

Resolução de problemas comuns

• Erro no configure por OpenSSL header ausente: instale pacote de desenvolvimento (openssl-dev).
• Permissões negadas ao acessar tokens: verifique dono/grupo e permissões do diretório configurado.
• Módulo PKCS#11 não encontrado pela aplicação: confirme caminho para libsofthsm2.so e que o processo tem permissão para ler o arquivo.
• Chave não encontrada: liste objetos com softhsm2-util ou pkcs11-tool e valide label/ID.

Quando não usar SoftHSM

• Ambiente regulado que exige HSM certificado (FIPS, Common Criteria) — use HSM físico certificado.
• Cenários de alto risco onde isolamento físico de chave é obrigatório.

Mini-metodologia de testes de integração

1. Inicialize um token de teste com labels e PINs conhecidos.
2. Gere uma chave RSA 2048 dentro do token.
3. Peça à aplicação para usar a chave para assinar um documento e valide a assinatura externamente.
4. Exporte logs e verifique que apenas operações permitidas foram realizadas.
5. Teste restauração do backup e repita os passos para verificar integridade.

Conclusão

SoftHSM é uma solução prática para testar e operar funcionalidades de HSM via PKCS#11 quando um HSM físico não está disponível. Para produção, avalie requisitos de conformidade e risco antes de optar por SoftHSM. Use backups seguros, políticas de PIN, isolamento e controles de acesso para reduzir exposição.

Resumo rápido:

• Instale dependências, configure e compile com o backend desejado.
• Inicialize tokens com softhsm2-util e proteja PINs.
• Teste com pkcs11-tool e integre sua aplicação apontando para libsofthsm2.so.

Importante: para cenários que exigem certificação de hardware ou maior garantia de proteção de chave, prefira HSMs físicos certificados.