---
title: "Armazenamento de chaves via PKCS #11"
description: "Configuração do repositório de chaves PKCS #11 do Amplia para HSMs e tokens criptográficos USB, em Windows Server e Linux."
canonical: "https://docs.lacunasoftware.com/articles/amplia/on-premises/key-stores/pkcs11"
locale: "pt-BR"
product: "Amplia"
last_updated: "2026-10-08"
---

# 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](https://docs.lacunasoftware.com/articles/amplia/on-premises/key-stores/azure).

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*):

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

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

```bash
KeyStores__MyDevice__Type=Pkcs11
KeyStores__MyDevice__Module=...
KeyStores__MyDevice__Pin=...
```

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

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

## Repositórios de chaves PKCS #11 comuns

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

```ini
[KeyStores:eToken]
Type=Pkcs11
Module=eTPKCS11.dll
Pin=XXXX
```

```sh
KeyStores__eToken__Type=Pkcs11
KeyStores__eToken__Module=eTPKCS11.dll
KeyStores__eToken__Pin=XXXX
```

```json
"eToken": {
	"Type": "Pkcs11",
	"Module": "eTPKCS11.dll",
	"Pin": "XXXX"
}
```

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

```ini
[KeyStores:eTokenA]
Type=Pkcs11
Module=eTPKCS11.dll
Pin=XXXX
TokenSerialNumber=01f5cfe4
```

```sh
KeyStores__eTokenA__Type=Pkcs11
KeyStores__eTokenA__Module=eTPKCS11.dll
KeyStores__eTokenA__Pin=XXXX
KeyStores__eTokenA__TokenSerialNumber=01f5cfe4
```

```json
"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](https://docs.lacunasoftware.com/articles/amplia/on-premises/key-stores/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:

```sh
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:

```json
{
  "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:

```ini
[KeyStores:MyKryptusHsm]
Type=Pkcs11
Module=libkNETPKCS11.so
Pin=SOME_PASSWORD
```

```sh
KeyStores__MyKryptusHsm__Type=Pkcs11
KeyStores__MyKryptusHsm__Module=libkNETPKCS11.so
KeyStores__MyKryptusHsm__Pin=SOME_PASSWORD
```

```json
"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:

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

```

## Veja também

* [Repositórios de chaves](https://docs.lacunasoftware.com/articles/amplia/on-premises/key-stores)
* [Amplia on-premises](https://docs.lacunasoftware.com/articles/amplia/on-premises)