Biblioteca de descarregamento do HSM TLS gerenciado pelo Azure

  • Artigo

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

Para obter mais informações, confira GitHub da biblioteca de descarregamento de TLS do HSM Gerenciado do Azure.

A biblioteca de descarregamento de TLS usa internamente a API REST do Azure Key Vault para interagir com o HSM Gerenciado do Azure.

Introdução

Atributos do PKCS#11

Para se integrar corretamente ao PKCS#11, gerar chaves (por meio de C_GenerateKeyPair) e localizar objetos de chave (por meio de C_FindObjectsInit/C_FindObjects) requer uma solução para armazenar atributos PKCS#11 no objeto chave do Azure Key Vault. A biblioteca de descarregamento de TLS converte esses atributos do PKCS#11 necessários em tags do Azure Key Vault.

Essas "Tags de Atributo" têm um prefixo especial:

  • p11_pri_{Nome do Atributo P11} – atributos de chave privada
  • p11_pub_{Nome do Atributo P11} – atributos de chave pública

A biblioteca de descarregamento de TLS define corretamente os atributos Operações de Chave do Azure Key Vault e Tempo de Vida da Chave para que o serviço possa impor corretamente essas restrições às chaves geradas. Esses atributos também são armazenados como tags, como outros atributos do PKCS#11, para dar suporte a recursos de consulta.

Os aplicativos que usam a biblioteca de descarregamento de TLS usam um ou mais atributos do PKCS#11 para localizar e usar os objetos de chave.

Aviso

As chaves geradas pela biblioteca de descarregamento de TLS e suas tags podem ser acessadas pela API REST do Azure Key Vault. Manipular essas tags de atributo P11 usando a API REST do Azure Key Vault pode interromper os aplicativos da biblioteca de descarregamento de TLS.

Geração de chave

A biblioteca de descarregamento de TLS inclui uma ferramenta de criação de chave, mhsm_p11_create_key. Executar a ferramenta sem argumentos de linha de comando mostra o uso correto da ferramenta.

A ferramenta de criação de chave requer uma entidade de serviço, que é atribuída à função "Usuário de Criptografia do HSM Gerenciado" no escopo "/keys".

A ferramenta de criação de chave lê as credenciais da entidade de serviço das variáveis de ambiente MHSM_CLIENT_ID e MHSM_CLIENT_SECRET:

  • MHSM_CLIENT_ID – deve ser definido como a ID do aplicativo (cliente) da entidade de serviço
  • MHSM_CLIENT_SECRET – deve ser definido como a senha da entidade de serviço (segredo do cliente)

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

  • Use o argumento --identity para habilitar a identidade gerenciada com a ferramenta mhsm_p11_create_key.
  • O client_id da identidade gerenciada atribuída pelo usuário deve ser citado no arquivo de configuração MHSM (mhsm-pkcs11.conf). Se o client_id de uma identidade gerenciada atribuída pelo usuário não for fornecido, ele a considerará como uma identidade gerenciada atribuída pelo sistema.

A ferramenta de criação de chave gera aleatoriamente um nome para a chave no momento da criação. A ID de chave completa do Azure Key Vault e o nome da chave estão impressos no console 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://myhsm.managedhsm.azure.net/keys/p11-6a2155dc40c94367a0f97ab452dc216f/92f8aa2f1e2f4dc1be334c09a2639908 \
Key Name: p11-6a2155dc40c94367a0f97ab452dc216f

O argumento --label para a ferramenta de criação de chave especifica o CKA_LABEL desejado para as chaves privadas e públicas geradas. Normalmente, esses atributos são necessários para configurar soluções de descarregamento de TLS com suporte (por exemplo, a configuração de SSL do nginx `ssl_certificate_key').

Você precisa do nome da chave para qualquer alteração de atribuição de função por meio da CLI do Azure.

Controle de acesso

A biblioteca de descarregamento de TLS converte o C_FindObjectsInit em uma chamada à API REST do Azure Key Vault que opera no escopo /keys. O serviço MHSM requer a permissão de leitura nesse escopo para que o usuário da biblioteca de descarregamento de TLS autorize a operação de localização para as chaves criadas por meio da ferramenta de criação de chave.

Para obter mais informações sobre o RBAC local do HSM Gerenciado do Azure, confira:

A seção a seguir descreve diferentes abordagens para implementar o controle de acesso para a entidade de serviço biblioteca de descarregamento de TLS e Identidade Gerenciada.

Entidade de serviço de descarregamento de TLS

A entidade de serviço de descarregamento de TLS é usada pelo aplicativo que usa a biblioteca de descarregamento de TLS para acessar chaves e deve ter, no mínimo, a seguinte permissão por meio de atribuições de função:

  • Permissão KeyRead para todas as chaves no HSM gerenciado
  • Permissão KeySign para as chaves necessárias para o descarregamento de TLS

Usuário administrador

O usuário administrador criará uma definição de função personalizada e atribuições de função. Portanto, o usuário administrador deve ser atribuído a uma das seguintes funções internas no escopo "/":

  • Responsável pela Criptografia do HSM Gerenciado
  • Administrador de Política do HSM Gerenciado
  • Administrador de HSM Gerenciado

Entidade de serviço de geração de chave

A entidade de serviço de geração de chave é usada com a ferramenta de criação de chave (mhsm_p11_create_key) para gerar chaves de descarregamento de TLS. Essa entidade de serviço deve ser atribuída à função "Usuário de Criptografia do HSM Gerenciado" no escopo "/keys".

CLI do Azure

A CLI do Azure pode ser usada para executar tarefas como atribuição de função.

Abordagem permissiva

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

Atribua a função Usuário de Criptografia à entidade de serviço de descarregamento de TLS no escopo "/keys". Isso dá à entidade de serviço de descarregamento de TLS a permissão para gerar chaves e encontrá-las para descarregamento de TLS.

az keyvault role assignment create --hsm-name ContosoMHSM \
--role "Managed HSM Crypto User"  \
--assignee TLSOffloadServicePrincipal@contoso.com  \
--scope /keys

Para Identidades Gerenciadas, especifique os argumentos de comando da seguinte maneira:

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

Abordagem granular

A abordagem granular implementa o controle de acesso refinado. Ele requer duas entidades de serviço (entidade de serviço de descarregamento de TLS e entidade de serviço de geração de chaves) e um usuário administrador.

O objetivo é restringir as permissões da entidade de serviço de descarregamento de TLS para dar suporte ao mínimo necessário para descarregamento de TLS. O usuário deve ter a permissão de leitura para outras chaves para dar suporte à função C_FindObject* da biblioteca.

Função de leitura do usuário da biblioteca de descarregamento de TLS

A primeira etapa na implementação da abordagem granular é criar uma função personalizada. Essa operação só precisa ser feita uma vez.

O usuário administrador (com a função de Responsável pela Criptografia do HSM Gerenciado, Administrador do HSM Gerenciado ou Administrador de Política do HSM Gerenciado) cria uma definição de função personalizada de função "Função de Leitura do Usuário da Biblioteca de TLS":

az keyvault role definition create --hsm-name ContosoMHSM --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 a entidade de serviço Geração de Chaves com a ferramenta de criação de chave (mhsm_p11_create_key).

Conceder permissão

O usuário administrador atribui as seguintes funções à entidade de serviço de descarregamento de TLS.

  • Atribuir a função "Função de Leitura do Usuário da Biblioteca de TLS" no escopo "/keys"
  • Atribuir a função "Usuário de Criptografia HSM Gerenciado" no escopo "/keys/{key name}"

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

az keyvault role assignment create --hsm-name ContosoMHSM  \
--role "TLS Library User Read Role"  \
--assignee TLSOffloadServicePrincipal@contoso.com  \
--scope /keys

az keyvault role assignment create --hsm-name ContosoMHSM  \
--role "Managed HSM Crypto User"  \
--assignee TLSOffloadServicePrincipal@contoso.com  \
--scope /keys/p11-6a2155dc40c94367a0f97ab452dc216f

Cache de conexão

Para melhorar o desempenho das chamadas de sinal para o Serviço HSM Gerenciado, a Biblioteca de Descarregamento de TLS armazena em cache suas conexões TLS com os servidores de serviço HSM gerenciados. Por padrão, a Biblioteca de Descarregamento de TLS armazena em cache até 20 conexões TLS. O cache de conexão pode ser controlado por meio do arquivo de configuração MHSM (mhsm-pkcs11.conf).

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

Desabilitar

Se esse valor for true, o Cache de Conexão será desabilitado. Ele é habilitador por padrão.

MaxConnections

Especifica o número máximo de conexões com o cache. O limite máximo de conexão deve ser configurado com base no número de sessões PKCS11 simultâneas que estão sendo usadas pelo aplicativo. Os aplicativos normalmente criam um pool de sessões PKCS11 e as usam de um pool de threads para gerar solicitações de assinatura em paralelo. O MaxConnections deve corresponder ao número de solicitações de assinatura simultâneas geradas pelos aplicativos.

O RPS (Solicitação de Assinatura por Segundo) depende do número de solicitações simultâneas e do número de conexões armazenadas em cache. Especificar um número maior ou até mesmo o limite padrão não melhorará o RPS de assinatura se o número de solicitações de assinatura PKCS11 simultâneas for menor que esse limite. O número máximo de conexões simultâneas para alcançar o modo de intermitência do pool de HSM Standard B1 é de cerca de 30, dependendo do tipo de instância. Mas você deve tentar com números diferentes para descobrir o número ideal de conexões simultâneas.

Consulte a documentação do aplicativo ou entre em contato com o fornecedor do aplicativo para saber mais sobre como o aplicativo usa a biblioteca PKCS11.

Usando a biblioteca de descarregamento de TLS

Gerar chaves

A biblioteca de descarregamento de TLS inclui uma ferramenta de criação de chave, mhsm_p11_create_key. Executar a ferramenta sem argumentos de linha de comando mostra o uso correto da ferramenta.

A ferramenta de criação de chave requer uma entidade de serviço, que é atribuída à função "Usuário de Criptografia do HSM Gerenciado" no escopo "/keys".

A ferramenta de criação de chave lê as credenciais da entidade de serviço das variáveis de ambiente MHSM_CLIENT_ID e MHSM_CLIENT_SECRET.

  • MHSM_CLIENT_ID – deve ser definido como a ID do aplicativo (cliente) da entidade de serviço
  • MHSM_CLIENT_SECRET – deve ser definido como a senha da entidade de serviço (segredo do cliente)

A ferramenta de criação de chave gera aleatoriamente um nome para a chave no momento da criação. A ID de chave completa do Azure Key Vault e o nome da chave estão impressos no console 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://myhsm.managedhsm.azure.net/keys/p11-6a2155dc40c94367a0f97ab452dc216f/92f8aa2f1e2f4dc1be334c09a2639908 \
Key Name: p11-6a2155dc40c94367a0f97ab452dc216f

O argumento --label para a ferramenta de criação de chave especifica o CKA_LABEL desejado para as chaves privadas e públicas geradas. Normalmente, esses atributos são necessários para configurar soluções de descarregamento de TLS com suporte (por exemplo, a configuração de SSL do nginx `ssl_certificate_key').

O nome da chave será necessário se você estiver planejando implementar o acesso granular às chaves.

Implementar TLS sem chave

Há duas abordagens para gerar uma chave e usar a chave para o Key Less TLS: 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 imposição de segurança.

Abordagem mais simples

  1. Criar uma entidade de serviço para a biblioteca de descarregamento de TLS (por exemplo, TLSOffload ServicePrincipal)
  2. Atribua a função "Usuário de Criptografia HSM Gerenciado" à entidade de serviço de descarregamento de TLS no escopo "/keys". 
    az keyvault role assignment create --hsm-name ContosoMHSM \
--role "Managed HSM Crypto User"  \
--assignee TLSOffloadServicePrincipal@contoso.com  \
--scope /keys
  3. Gere a chave com o rótulo necessário seguindo as etapas em Como gerar chaves usando a biblioteca de descarregamento de TLS.
  4. Configurar o servidor TLS para usar a biblioteca de descarregamento de TLS do HSM gerenciado como a biblioteca de interfaces PKCS#11
  5. Configurar o servidor TLS (por exemplo, a configuração de SSL nginx `ssl_certificate_key') com o rótulo de chave e as credenciais da entidade de serviço de descarregamento de TLS

Abordagem granular

  1. Crie um usuário administrador (por exemplo, TLSOffloadAdminUser) com a seguinte função:
    • Função "Responsável pela Criptografia do HSM Gerenciado" no escopo "/"
  2. Crie uma entidade de serviço de geração de chaves (por exemplo, TLSOffloadKeyGenServicePrincipal) para a geração de chave de descarregamento de TLS e atribua a seguinte função:
    • Função "Usuário de Criptografia do HSM Gerenciado" no escopo "/keys".
  3. Criar uma entidade de serviço para o descarregamento de TLS (por exemplo, TLSOffload ServicePrincipal)
  4. O usuário administrador cria a seguinte definição de função personalizada: 
    az keyvault role definition create --hsm-name ContosoMHSM --role-definition '{ \
"roleName": "TLS Library User Read Role", \
"description": "Grant Read access to keys", \ 
"actions": [], \
"notActions": [], \
"dataActions": ["Microsoft.KeyVault/managedHsm/keys/read/action"], \
"notDataActions": []
}'
  5. Gere a chave com o rótulo necessário seguindo as etapas em “Como gerar chaves usando a biblioteca de descarregamento de TLS”. Use a entidade de serviço de geração de chave (por exemplo, TLSOffloadKeyGenServicePrincipal) ao gerar chaves. Anote o rótulo da chave e o nome da chave. Por exemplo:
    • Rótulo da chave: tlsKey
    • Nome da chave: p11-6a2155dc40c94367a0f97ab452dc216f
  6. O usuário administrador atribui as seguintes funções à entidade de serviço de descarregamento de TLS
    • Função "Função de Leitura do Usuário da Biblioteca de TLS" no escopo "/keys"
    • Função "Usuário de Criptografia HSM Gerenciado" no escopo "/keys/{key name}"
    az keyvault role assignment create --hsm-name ContosoMHSM  \
--role " TLS Library User Read Role"  \
--assignee TLSOffloadServicePrincipal @contoso.com  \
--scope /keys

az keyvault role assignment create --hsm-name ContosoMHSM  \
--role "Managed HSM Crypto User"  \
--assignee TLSOffloadServicePrincipal@contoso.com  \
--scope /keys/p11-6a2155dc40c94367a0f97ab452dc216f
  7. Configurar o servidor TLS para usar a biblioteca de descarregamento de TLS do HSM gerenciado do Azure como a biblioteca de interfaces PKCS#11
  8. Configurar o servidor TLS (por exemplo, a configuração de SSL nginx `ssl_certificate_key') com o rótulo de chave e as credenciais da entidade de serviço de descarregamento de TLS

Próximas etapas