Biblioteca de descarregamento de TLS do Azure Key Vault Managed HSM

O HSM gerido oferece uma biblioteca TLS Offload, que está em conformidade com a versão 2.40 do PKCS#11. O HSM gerido não suporta todas as funções listadas na especificação PKCS#11; em vez disso, a biblioteca TLS Offload suporta um conjunto limitado de mecanismos e funções de interface para SSL/TLS Offload apenas com F5 (BigIP) e Nginx, principalmente para gerar chaves de certificado do servidor TLS e gerar assinaturas digitais durante handshakes TLS.

Para mais informações, consulte Managed HSM TLS Offload Library GitHub.

A Biblioteca TLS Offload utiliza internamente a API REST do Azure Key Vault para interagir com o HSM Gerido.

Introdução

Atributos PKCS#11

Para integrar corretamente com o PKCS#11, gerar chaves (via C_GenerateKeyPair) e localizar objetos-chave (via C_FindObjectsInit/C_FindObjects) requer uma solução para armazenar os atributos PKCS#11 no objeto chave Azure Key Vault. A Biblioteca TLS Offload converte estes atributos PKCS#11 necessários em Etiquetas Azure Key Vault.

Estas "Etiquetas de Atributo" têm um prefixo especial:

p11_pri_{Nome do Atributo P11} - Atributos da Chave Privada
p11_pub_{Nome do Atributo P11} - Atributos de Chave Pública

A biblioteca TLS Offload define corretamente os atributos de Operações de Chave do Azure Key Vault e Key Lifetime, para que o serviço possa aplicar corretamente estas restrições às chaves geradas. Estes atributos também são armazenados como etiquetas, tal como outros atributos PKCS#11, para suportar capacidades de consulta.

As aplicações que utilizam a Biblioteca de Descarga TLS utilizam um ou mais atributos PKCS#11 para localizar e utilizar os objetos-chave.

Advertência

As chaves geradas pela TLS Offload Library e as suas Tags são acessíveis através da API REST do Azure Key Vault. Manipular estas Etiquetas de Atributos P11 usando a API REST do Azure Key Vault pode quebrar as aplicações da Biblioteca TLS Offload.

Geração de chaves

A Biblioteca de Descarga TLS inclui uma ferramenta de criação de chaves, mhsm_p11_create_key. Executar a ferramenta sem quaisquer argumentos de linha de comandos mostra o uso correto da ferramenta.

A ferramenta de criação de chaves requer um service principal, que é atribuído à função "Managed HSM Crypto User" no âmbito "/keys".

A ferramenta de criação de chaves lê as credenciais do principal de serviço a partir das variáveis de ambiente MHSM_CLIENT_ID e MHSM_CLIENT_SECRET:

MHSM_CLIENT_ID – deve corresponder ao ID da aplicação (cliente) do principal de serviço
MHSM_CLIENT_SECRET – deve ser definida para a palavra-passe do principal do serviço (cliente secreto)

Para Identidades Geridas, as variáveis de ambiente acima não são necessárias.

Use o --identity argumento para ativar identidade gerida com a ferramenta mhsm_p11_create_key.
O client_id da identidade gerida atribuída pelo utilizador deve ser especificado no ficheiro de configuração do HSM Gerido (mhsm-pkcs11.conf). Se a client_id identidade gerida atribuída pelo utilizador não for fornecida, será considerada como identidade gerida atribuída pelo sistema.

A ferramenta de criação de chaves gera aleatoriamente um nome para a chave no momento da criação. O ID completo da chave Azure Key Vault e o nome da chave são impressos na consola para sua conveniência.

MHSM_CLIENT_ID="<service-principal-application-id>" \
MHSM_CLIENT_SECRET="<service-principal-password>" \
mhsm_p11_create_key --RSA 4K --label tlsKey

Key is generated successfully. \
Managed HSM Key ID: https://<hsm-name>.managedhsm.azure.net/keys/p11-6a2155dc40c94367a0f97ab452dc216f/92f8aa2f1e2f4dc1be334c09a2639908 \
Key Name: p11-6a2155dc40c94367a0f97ab452dc216f

O --label argumento para a ferramenta de criação de chaves especifica a CKA_LABEL desejada para as chaves privada e pública geradas. Estes atributos são normalmente necessários para configurar soluções TLS Offload suportadas (por exemplo, a configuração SSL nginx 'ssl_certificate_key').

Precisas do nome da chave para qualquer alteração de atribuição de função através da CLI do Azure.

Controlo de acesso

A Biblioteca TLS Offload traduz o C_FindObjectsInit numa chamada REST API do Azure Key Vault, que opera no âmbito /keys. O serviço HSM gerido requer a permissão de leitura neste âmbito para que o Utilizador da Biblioteca de Descarga TLS autorize a operação de busca das chaves criadas através da ferramenta de criação de chaves.

Para mais informações sobre o RBAC local do HSM gerido, consulte:

A secção seguinte descreve diferentes abordagens para implementar controlo de acesso para o principal de serviço da Biblioteca TLS Offload e para a Identidade Gerida.

Princípio do serviço TLS Offload

O principal de serviço TLS Offload é usado pela aplicação que utiliza a Biblioteca TLS Offload para aceder a chaves, e deve ter, no mínimo, as seguintes permissões através de atribuições de funções:

Permissão de leitura de chaves para todas as chaves no HSM gerido
Permissão KeySign para as chaves necessárias para o descarregamento do TLS

Utilizador Administrativo

O Utilizador Administrador criará uma definição de função personalizada e atribuições de funções. Assim, o Utilizador Administrador deve ser atribuído a uma das seguintes funções incorporadas no âmbito "/".

Responsável pela Criptografia de HSM Gerenciado
Administrador de políticas de HSM gerenciado
Administrador de HSM Gerenciado

Princípio de serviço de geração de chaves

O principal de serviço de geração de chaves é utilizado com a ferramenta de criação de chaves (mhsm_p11_create_key) para gerar chaves de descarregamento TLS. Este principal de serviço deve ser atribuído ao papel "Utilizador Gerido de Criptografia HSM" no âmbito "/keys".

CLI do Azure (Interface de Linha de Comando da Azure)

O CLI do Azure pode ser usado para realizar tarefas como atribuição de papéis.

Abordagem permissiva

A abordagem permissiva é mais simples e adequada quando o HSM Gerido é usado exclusivamente para o descarregamento de TLS.

Atribuir o papel de Utilizador Cripto ao principal do serviço TLS Offload no âmbito "/keys". Isto dá ao principal do serviço TLS Offload a permissão para gerar chaves e encontrá-las para o TLS Offloading.

az keyvault role assignment create --hsm-name <hsm-name> \
--role "Managed HSM Crypto User"  \
--assignee <service-principal-id>  \
--scope /keys

Para Identidades Geridas, especifique os argumentos de comando da seguinte forma:

az keyvault role assignment create --hsm-name <hsm-name> \
      --role "Managed HSM Crypto User"  \
       --assignee-object-id <object-id>  \
       --assignee-principal-type MSI \
       --scope /keys

Abordagem granular

A abordagem granular implementa controlo de acesso detalhado. Requer duas entidades de serviço (entidade de serviço de TLS Offload e entidade de serviço de Geração de Chaves) e um Utilizador Administrador.

O objetivo é restringir as permissões do principal de serviço de descarregamento TLS para dar suporte apenas ao mínimo exigido para o descarregamento TLS. O utilizador deve ter permissão de Leitura para outras chaves, a fim de suportarem a função C_FindObject* da biblioteca.

Função de Leitura do Utilizador da Livraria de Descarregamento TLS

O primeiro passo para implementar a abordagem granular é criar um papel personalizado. Esta operação só precisa de ser feita uma vez.

O Utilizador Administrador (com funções de Oficial Criptográfico HSM Gerido, Administrador HSM Gerido ou Administrador de Políticas HSM Gerido) cria uma definição personalizada de função "Função de Leitura do Utilizador da Biblioteca TLS":

az keyvault role definition create --hsm-name <hsm-name> --role-definition '{ \
"roleName": "TLS Library User Read Role", \
"description": "Grant Read access to keys", \
"actions": [], \
"notActions": [], \
"dataActions": ["Microsoft.KeyVault/managedHsm/keys/read/action"], \
"notDataActions": [] \
}'

Gerar chaves

As chaves podem ser geradas usando o principal de serviço de geração de chaves com a ferramenta de criação de chaves (mhsm_p11_create_key).

Conceder permissão

O Utilizador Administrador atribui as seguintes funções ao principal do serviço TLS Offload.

Atribuir o papel "TLS Library User Read Role" no âmbito "/keys"
Atribuir a função "Utilizador Gestor de Criptografia HSM" no âmbito "/keys/{nome da chave}"

No exemplo seguinte, o nome da chave é "p11-6a2155dc40c94367a0f97ab452dc216f".

az keyvault role assignment create --hsm-name <hsm-name>  \
--role "TLS Library User Read Role"  \
--assignee <service-principal-id>  \
--scope /keys

az keyvault role assignment create --hsm-name <hsm-name>  \
--role "Managed HSM Crypto User"  \
--assignee <service-principal-id>  \
--scope /keys/p11-6a2155dc40c94367a0f97ab452dc216f

Ligação de identidade gerida

Pode controlar a ligação de Identidade Gerida através do ficheiro de configuração do Managed HSM (mhsm-pkcs11.conf).

"msi": {
    "identityMSI": false,
    "enableIMDSCache": false,
    "MSIClientId": "<MSI CLIENT ID>"
       }

identityMSI: Definir como true vai ativar o Azure Managed Identity (MSI).
enableIMDSCache: Armazena em cache, na memória, tokens de autenticação do Serviço de Metadados de Instância do Azure (IMDS) para partilha entre processos; isto não armazena em cache nenhuma chave MHSM.
MSIClientId: ID do cliente MSI para identidade gerida atribuída pelo utilizador.

Cache de Conexões

Para melhorar o desempenho das chamadas Sign para o Serviço de HSM Gerido, a Biblioteca de Descarregamento TLS armazena em cache as suas ligações TLS para os servidores do serviço de HSM Gerido. Por defeito, a Biblioteca TLS Offload armazena em cache até 20 ligações TLS. A cache de ligações pode ser controlada através do ficheiro de configuração do Managed HSM (mhsm-pkcs11.conf).

"ConnectionCache": {
        "Disable": false, 
        "MaxConnections": 20
}

Disable

Se este valor for verdadeiro, a Cache de Ligação será desativada. Ele é ativado por padrão.

MaxConnections

Especifica o número máximo de ligações no cache. O limite máximo de ligação deve ser configurado com base no número de sessões PKCS11 concorrentes utilizadas pela aplicação. As aplicações normalmente criam um pool de sessões PKCS11 e utilizam-nas a partir de um pool de threads para gerar pedidos de assinatura em paralelo. As MaxConnections devem corresponder ao número de solicitações de assinatura simultâneas geradas pelos aplicativos.

O Pedido de Assinatura Por Segundo (RPS) depende do número de pedidos concorrentes e do número de ligações em cache. Especificar um número superior ou mesmo o limite padrão não melhorará o RPS de assinatura se o número de pedidos de assinatura PKCS11 concorrentes for inferior a esse limite. O número máximo de ligações concorrentes para alcançar o modo de rajada do pool padrão B1 HSM é cerca de 30, dependendo do tipo de instância. Mas deves tentar com números diferentes para perceber o número ótimo de ligações concorrentes.

Consulte a documentação da sua candidatura ou contacte o fornecedor da sua aplicação para saber mais sobre como a aplicação utiliza a biblioteca PKCS11.

Utilização da Biblioteca de Descarregamento TLS

Gerar chaves

A Biblioteca de Descarga TLS inclui uma ferramenta de criação de chaves, mhsm_p11_create_key. Executar a ferramenta sem quaisquer argumentos de linha de comandos mostra o uso correto da ferramenta.

A ferramenta de criação de chaves requer um service principal, que é atribuído à função "Managed HSM Crypto User" no âmbito "/keys".

A ferramenta de criação de chaves lê as credenciais do principal de serviço a partir das variáveis de ambiente MHSM_CLIENT_ID e MHSM_CLIENT_SECRET.

MHSM_CLIENT_ID – deve corresponder ao ID da aplicação (cliente) do principal de serviço
MHSM_CLIENT_SECRET – deve ser definida para a palavra-passe do principal do serviço (cliente secreto)

A ferramenta de criação de chaves gera aleatoriamente um nome para a chave no momento da criação. O ID completo da chave do Azure Key Vault e o nome da chave são impressos na consola para maior comodidade.

MHSM_CLIENT_ID="<service-principal-application-id>" \
MHSM_CLIENT_SECRET="<service-principal-password>" \
mhsm_p11_create_key --RSA 4K --label tlsKey

Key is generated successfully.
Managed HSM Key ID: https://<hsm-name>.managedhsm.azure.net/keys/p11-6a2155dc40c94367a0f97ab452dc216f/92f8aa2f1e2f4dc1be334c09a2639908 \
Key Name: p11-6a2155dc40c94367a0f97ab452dc216f

O nome da chave é necessário se planeia implementar acesso granular às chaves.

Implementar TLS sem chave

Existem duas abordagens para gerar uma chave e usar a chave para o TLS Sem Chave: uma abordagem mais simples e permissiva, e uma abordagem granular, que oferece melhor segurança. As abordagens diferem no esforço de implementação e na aplicação da segurança.

Abordagem mais simples

Criar um principal de serviço para a Biblioteca de Descarga TLS (por exemplo, TLSOffload ServicePrincipal)

Atribuir o papel de "Utilizador Gerido de Criptografia HSM" ao principal do serviço TLS Offload no âmbito "/keys".

az keyvault role assignment create --hsm-name <hsm-name> \
--role "Managed HSM Crypto User"  \
--assignee <service-principal-id>  \
--scope /keys

Gerar chave com o rótulo necessário seguindo os passos em Como gerar chaves usando a Biblioteca de Descarga TLS.
Configure o servidor TLS para usar a Managed HSM TLS Offload Library como biblioteca de interface PKCS#11
Configure o servidor TLS (por exemplo, a configuração SSL nginx 'ssl_certificate_key') com o rótulo da chave e as credenciais principais do serviço TLS Offload

Abordagem granular

Crie um Utilizador Administrador (por exemplo, TLSOffloadAdminUser) com a seguinte função:
- Função de "Gestor de Criptografia HSM" no âmbito "/"
Crie um principal de serviço de geração de chaves (por exemplo, TLSOffloadKeyGenServicePrincipal) para a geração de chaves TLS Offload e atribua o seguinte papel:
- Função de "Utilizador Gestor de Criptografia HSM" no âmbito "/keys".
Criar um serviço principal para o TLS Offloading (por exemplo, TLSOffload ServicePrincipal)

O Utilizador Administrador cria a seguinte definição de função personalizada:

az keyvault role definition create --hsm-name <hsm-name> --role-definition '{ \
"roleName": "TLS Library User Read Role", \
"description": "Grant Read access to keys", \ 
"actions": [], \
"notActions": [], \
"dataActions": ["Microsoft.KeyVault/managedHsm/keys/read/action"], \
"notDataActions": []
}'

Gerar uma chave com o rótulo obrigatório após "Como gerar chaves usando a Biblioteca de Descarga TLS". Use o principal de serviço de Geração de Chaves (por exemplo, TLSOffloadKeyGenServicePrincipal) ao gerar chaves. Anota a Etiqueta da Chave e o Nome da Chave. Por exemplo:
- Etiqueta de Chave: tlsKey
- Nome-chave: p11-6a2155dc40c94367a0f97ab452dc216f

O Utilizador Administrador atribui as seguintes funções ao principal do serviço TLS Offload

Função "TLS Library User Read Role" no âmbito "/keys"
Função "Utilizador Gestor de Criptografia HSM" no âmbito "/keys/{nome da chave}"

az keyvault role assignment create --hsm-name <hsm-name>  \
--role " TLS Library User Read Role"  \
--assignee <service-principal-id>  \
--scope /keys

az keyvault role assignment create --hsm-name <hsm-name>  \
--role "Managed HSM Crypto User"  \
--assignee <service-principal-id>  \
--scope /keys/p11-6a2155dc40c94367a0f97ab452dc216f

Configure o servidor TLS para usar a Managed HSM TLS Offload Library como biblioteca de interface PKCS#11
Configure o servidor TLS (por exemplo, a configuração SSL nginx 'ssl_certificate_key') com o rótulo da chave e as credenciais principais do serviço TLS Offload

Passos seguintes

Comentários

Esta página foi útil?

Last updated on 2026-07-03

Biblioteca de descarregamento de TLS do Azure Key Vault Managed HSM

Introdução

Atributos PKCS#11

Geração de chaves

Controlo de acesso

Princípio do serviço TLS Offload

Utilizador Administrativo

Princípio de serviço de geração de chaves

CLI do Azure (Interface de Linha de Comando da Azure)

Abordagem permissiva

Abordagem granular

Função de Leitura do Utilizador da Livraria de Descarregamento TLS

Gerar chaves

Conceder permissão

Ligação de identidade gerida

Cache de Conexões

Utilização da Biblioteca de Descarregamento TLS

Gerar chaves

Implementar TLS sem chave

Abordagem mais simples

Abordagem granular

Passos seguintes

Comentários

Recursos adicionais