Pular para o conteúdo principal

Armazenamento de chaves via PKCS #11

observação

Os repositórios de chaves PKCS #11 só são compatíveis com instalações em Windows Server e Linux. Para armazenar chaves em um HSM numa instância do Amplia hospedada no Azure App Services, use um repositório de chaves Azure Key Vault.

Dispositivos como HSMs (Hardware Security Modules) e tokens criptográficos USB normalmente oferecem suporte à comunicação pelo protocolo PKCS #11.

Para configurar um repositório de chaves PKCS #11 no Amplia, use as seguintes configurações:

  • Type: Pkcs11
  • Module: nome da biblioteca PKCS #11 (ex.: eTPKCS11.dll)
  • Pin: PIN do token, se necessário
  • TokenSerialNumber / TokenLabel (a partir da 4.8.0): se houver vários tokens, você pode especificar o token a ser usado com qualquer uma das duas configurações

Exemplo de configuração (arquivo .ini ou .conf):

[KeyStores:MyDevice]
Type=Pkcs11
Module=...
Pin=...

Exemplo de configuração (variáveis de ambiente):

KeyStores__MyDevice__Type=Pkcs11
KeyStores__MyDevice__Module=...
KeyStores__MyDevice__Pin=...

Exemplo de configuração (arquivo .json):

"KeyStores": {
	...,
	"MyDevice": {
		"Type": "Pkcs11",
		"Module": "...",
		"Pin": "..."
	},
	...
}

Repositórios de chaves PKCS #11 comuns​

Token criptográfico USB Safenet eToken (apenas um token conectado):

[KeyStores:eToken]
Type=Pkcs11
Module=eTPKCS11.dll
Pin=XXXX
KeyStores__eToken__Type=Pkcs11
KeyStores__eToken__Module=eTPKCS11.dll
KeyStores__eToken__Pin=XXXX
"eToken": {
	"Type": "Pkcs11",
	"Module": "eTPKCS11.dll",
	"Pin": "XXXX"
}

Token criptográfico USB Safenet eToken (vários tokens presentes, especificando o token a ser usado):

[KeyStores:eTokenA]
Type=Pkcs11
Module=eTPKCS11.dll
Pin=XXXX
TokenSerialNumber=01f5cfe4
KeyStores__eTokenA__Type=Pkcs11
KeyStores__eTokenA__Module=eTPKCS11.dll
KeyStores__eTokenA__Pin=XXXX
KeyStores__eTokenA__TokenSerialNumber=01f5cfe4
"eTokenA": {
	"Type": "Pkcs11",
	"Module": "eTPKCS11.dll",
	"Pin": "XXXX",
	"TokenSerialNumber": "01f5cfe4"
}

Usando um HSM Kryptus via PKCS #11​

dica

Para armazenar chaves em um HSM Kryptus, é recomendado usar o repositório de chaves Kryptus. Se, por algum motivo, você preferir se comunicar com o HSM via PKCS #11, continue lendo.

Você vai precisar dos seguintes parâmetros de um VHSM (HSM virtual) e de um usuário comum (não um usuário VCO) com autenticação por senha:

  • Endereço IP do VHSM
  • Porta HTTPS do VHSM (não a porta TTLV)
  • Nome de usuário e senha do usuário comum

Primeiro, obtenha com a Kryptus ou com a Lacuna a versão mais recente do arquivo kNET-PKCS11-Linux-X.Y.Z.tar. Em seguida, execute:

sudo su -
tar xf kNET-PKCS11-Linux-X.Y.Z.tar
cd kNET-PKCS11-Linux-X.Y.Z
./install.sh
mkdir -p /var/amplia/.config/kryptus/knet/pkcs11
touch /var/amplia/.config/kryptus/knet/pkcs11/config.json
chown -R root:amplia /var/amplia/.config
chmod -R a=,u+rwX,g+rX /var/amplia/.config
nano /var/amplia/.config/kryptus/knet/pkcs11/config.json

Cole o texto a seguir, substituindo os valores pelos seus:

{
  "connections": {
    "hsm_1": {
      "ip": "IP_ADDRESS_OF_YOUR_VHSM",
      "port": "HTTPS_PORT_OF_YOUR_VHSM"
    }
  },
  "users": {
    "SOME_USERNAME": {
      "authentication_type": "password",
      "connection": "hsm_1"
    }
  },
  "log_verbosity": "full"
}

Segundo a Kryptus, a entrada log_verbosity pode assumir um dos seguintes valores:

  • none: nada é registrado no log
  • key_only: apenas as operações com chaves e os erros são registrados no log
  • quiet: key_only + operações que usam o HSM, erros e avisos
  • info: quiet + operações PKCS #11 (observação: ignora a função C_GetTokenInfo)
  • verbose: info + argumentos resumidos das operações PKCS #11
  • full: registra tudo no log, com o máximo de detalhes possível
observação

Se nenhum nível de detalhamento for definido, ou seja, se o arquivo de configuração não tiver a entrada log_verbosity, o padrão será quiet.

Em seguida, no arquivo de configuração do Amplia:

[KeyStores:MyKryptusHsm]
Type=Pkcs11
Module=libkNETPKCS11.so
Pin=SOME_PASSWORD
KeyStores__MyKryptusHsm__Type=Pkcs11
KeyStores__MyKryptusHsm__Module=libkNETPKCS11.so
KeyStores__MyKryptusHsm__Pin=SOME_PASSWORD
"MyKryptusHsm": {
	"Type": "Pkcs11",
	"Module": "libkNETPKCS11.so",
	"Pin": "SOME_PASSWORD"
}

Para ter vários usuários no HSM, cada um mapeado para um repositório de chaves diferente no Amplia, adicione os usuários ao arquivo config.json e preencha a configuração TokenLabel de cada repositório de chaves no Amplia com o nome de usuário correspondente.

Alta disponibilidade​

Para habilitar a alta disponibilidade (HA), é necessário configurar uma lista de endereços IP e de portas no arquivo de configuração. O exemplo abaixo mostra a configuração necessária:

{
  "connections": {
    "hsm_1": {
      "ip": ["IP_ADDRESS_A", "IP_ADDRESS_B"],
      "port": ["HTTPS_PORT_ON_A", "HTTPS_PORT_ON_B"]
    }
  },
  ...
}

Veja também​

Ver em Markdown