Início Rápido: Criar sua primeira chave externa usando o CLI do Azure

Neste início rápido, você conecta seu HSM externo ao HSM Gerenciado, cria uma referência de chave externa e testa o caminho de proteção de chave. Em seguida, você usa o URI da chave HSM gerenciada para configurar a criptografia com chave gerenciada pelo cliente (CMK) em repouso em um serviço compatível do Azure.

Para obter o modelo de criptografia e a compatibilidade de serviço, consulte o que é gerenciamento de chave externa do Managed HSM?

Se você preferir usar o portal Azure, consulte Início Rápido: Criar sua primeira chave externa usando o portal Azure.

Pré-requisitos

Antes de começar, você precisa de:

• Um HSM gerenciado existente implantado em qualquer região pública Azure, em uma assinatura habilitada para gerenciamento de chaves externas. Para criar um HSM gerenciado, consulte Início Rápido: Provisionar e ativar um HSM Gerenciado usando CLI do Azure.
• Um Proxy EKM operacional acessível a partir do Azure. O proxy deve implementar a especificação da API de Proxy EKM. Para ver os fornecedores compatíveis, consulte O que é o gerenciamento de chaves externas do HSM gerenciado?.
• Uma chave criada no HSM externo com um identificador de chave externa conhecido. O identificador de chave externa é o identificador que seu proxy usa para pesquisar a chave.
• O certificado de AC raiz (formato PEM) que assinou o certificado de servidor TLS do proxy.
• CLI do Azure versão 2.x com a extensão mais recente keyvault instalada. Execute az extension add --name keyvault ou az extension update --name keyvault para obter a versão mais recente.
• A Managed HSM EKM Administrator função para gerenciar conexões de gerenciamento de chaves externas e a Managed HSM Crypto User função para criar e usar chaves. Para ver as etapas de atribuição de funções, consulte Controle de acesso do HSM gerenciado.

Entrar no Azure

az login

Defina sua assinatura se você tiver mais de uma:

az account set --subscription "<subscription-id>"

Mostrar o certificado do cliente Managed HSM

O HSM gerenciado apresenta um certificado de cliente X.509 ao seu Proxy EKM em todas as conexões de TLS mútuo (mTLS) de entrada. Antes de criar a conexão de gerenciamento externo de chaves, recupere o nome comum do titular do certificado e o certificado da CA raiz e adicione-o à lista de permissões no seu proxy. Isso permite que o proxy valide se a conexão vem do seu HSM Gerenciado, não de um chamador arbitrário.

az keyvault ekm-connection certificate show --hsm-name <Managed HSM Name>

A saída é semelhante a esta:

{
  "caCertificates": [
    "MIIDj...<truncated>...MrY="
  ],
  "subjectCommonName": "contoso.managedhsmclient.azure.net"
}

Configure o proxy para confiar em conexões que apresentem o certificado indicado em subjectCommonName e cuja cadeia termine em um dos certificados da lista caCertificates acima. As etapas exatas dependem do fornecedor proxy.

Criar a conexão externa de gerenciamento de chaves

A conexão de gerenciamento de chave externa associa seu HSM Gerenciado a um único Proxy EKM. Ele contém o endereço do proxy, a âncora de confiança da AC do servidor e um prefixo de caminho opcional.

Esta seção cria uma conexão de Internet pública. Para Link Privado, siga, em vez disso, Configurar o modelo de Link Privado do Azure (versão prévia) e, em seguida, continue com Verificar a conexão.

az keyvault ekm-connection create \
    --hsm-name <Managed HSM Name> \
    --host <EKMProxy Host> \
    --server-ca-certificate <Root cert> \
    [--path-prefix <prefix>]

Referência de parâmetro:

• --hsm-name: o nome do HSM gerenciado.
• --host: O nome de host totalmente qualificado do seu Proxy EKM. Por exemplo, proxy.contoso.com. O proxy deve escutar na porta TCP 443; Não há suporte para uma porta não padrão.
• --server-ca-certificate: Especifica o caminho para o arquivo de certificado da autoridade certificadora raiz (formato PEM ou DER) usado para verificar o certificado TLS do servidor proxy.
• --path-prefix (opcional): um prefixo do caminho do URL, caso seu proxy multiplexe vários clientes ou pools separados por caminho. Por exemplo, /contoso/prod.

Verificar a conexão

Depois de criar a conexão, verifique se o HSM Gerenciado pode alcançar seu proxy:

az keyvault ekm-connection check --hsm-name <Managed HSM Name>

Esse comando chama o endpoint do proxy /info pela conexão configurada. A saída bem-sucedida é semelhante a esta:

{
  "apiVersion": "1.0",
  "ekmProduct": "Contoso HSM v1.0.0",
  "ekmVendor": "Contoso HSM",
  "proxyName": "Contoso Proxy Service",
  "proxyVendor": "Contoso Proxy"
}

As causas de falha comuns incluem regras de firewall bloqueando a porta proxy, um valor incorreto --host ou o proxy rejeitando o certificado de cliente HSM gerenciado. Para obter as etapas de remediação, consulte Solucionar problemas no gerenciamento de chaves externas do HSM Gerenciado.

Criar a chave externa

Crie uma referência de chave HSM gerenciada que aponte para a chave externa em seu HSM. O HSM gerenciado não gera nenhum material de chave criptográfica. Esse comando registra uma referência a uma chave existente identificada pelo identificador de chave externa.

az keyvault key create \
    --external-key-id <external-key-identifier> \
    --hsm-name <Managed HSM Name> \
    --name <key-ref-name>

Referência de parâmetro:

• --external-key-id: o identificador de chave externa registrado em seu proxy. Esse é o identificador que o proxy usa para pesquisar a chave correta no HSM externo.
• --hsm-name: o nome do HSM gerenciado.
• --name: o nome que você deseja dar à referência de chave HSM gerenciada. Isso se torna parte do URI de chave que os serviços Azure usam.

O comando retorna o URI da chave no formulário https://<hsm-name>.managedhsm.azure.net/keys/<key-ref-name>/<version>. Mantenha esse URI para configurar seu serviço de Azure.

Verificar encapsulamento/desencapsulamento

Teste o caminho de proteção de chave com uma operação completa de wrap e unwrap. O HSM externo executa as operações por meio do proxy e o HSM Gerenciado retorna o resultado. Este teste confirma se o caminho de chave funciona. Ele não configura nem valida a integração do CMK de um serviço de Azure.

1. Crie um corpo da solicitação para a operação de encapsulamento. Defina value como o material de chave codificado em base64url que você deseja encapsular.

   {
     "alg": "RSA-OAEP-256",
     "value": "<base64url-encoded-plaintext-key>"
   }
   

   Guarde-o como wrapkey.json. Para chaves externas do AES, use "alg": "A256KW" em vez de RSA-OAEP-256.

2. Chame o ponto de extremidade wrapkey na sua referência de chave:

   az rest --method POST \
       --uri "https://<Managed HSM Name>.managedhsm.azure.net/keys/<key-ref-name>/wrapkey?api-version=7.5" \
       --resource "https://managedhsm.azure.net" \
       --headers "Content-Type=application/json" \
       --body @wrapkey.json
   

   A resposta retorna a versão da chave (kid) e um value campo que contém a chave encapsulada codificada em base64url. Copie o value para a próxima etapa.

3. Crie um corpo da solicitação para a operação de desencapsulamento, usando o value encapsulado da etapa anterior:

   {
     "alg": "RSA-OAEP-256",
     "value": "<wrapped-value-from-previous-step>"
   }
   

   Guarde-o como unwrapkey.json.

4. Chame o ponto de extremidade unwrapkey para confirmar a correção do tempo de ida e volta:

   az rest --method POST \
       --uri "https://<Managed HSM Name>.managedhsm.azure.net/keys/<key-ref-name>/unwrapkey?api-version=7.5" \
       --resource "https://managedhsm.azure.net" \
       --headers "Content-Type=application/json" \
       --body @unwrapkey.json
   

   Uma resposta bem-sucedida retorna o texto sem formatação value original que você embrulhou na primeira etapa. Se o desencapsulamento falhar, consulte Solucionar problemas no gerenciamento de chaves externas do HSM gerenciado para ver códigos de erro de proxy e etapas de remediação.

Usar a chave com um serviço do Azure

Conclua a integração da carga de trabalho seguindo a documentação de configuração do CMK do serviço Azure:

1. Confirme se o serviço dá suporte a CMKs com HSM Gerenciado e se o tipo e o algoritmo da sua chave externa atendem aos requisitos dele.
2. Conceda a identidade usada pelo serviço as permissões RBAC locais do HSM gerenciado necessárias. Para obter diretrizes de atribuição de função, consulte o controle de acesso do HSM gerenciado.
3. Defina as configurações do CMK do serviço com o URI da chave HSM gerenciada. Use o formato de URI com controle de versão ou sem controle de versão exigido por esse serviço. Para Armazenamento do Azure, consulte Configurar chaves gerenciadas pelo cliente com Managed HSM do Azure Key Vault.
4. Confirme se o serviço relata a configuração de CMK esperada e execute uma operação de leitura/gravação na carga de trabalho protegida. Revise o diagnóstico do serviço e os logs do gerenciamento de chaves externas do Managed HSM se a operação falhar.

O serviço Azure usa sua integração existente com o Managed HSM. Não precisa da API específica do fornecedor do seu HSM externo nem das suas credenciais.

Exibir logs de auditoria

Cada chamada ao Proxy EKM produz uma entrada EkmProxyOperation nos logs de diagnóstico do HSM gerenciado. Para consultá-los em Log Analytics:

AzureDiagnostics
| where ResourceProvider == "MICROSOFT.KEYVAULT"
| where OperationName contains "Ekm"
| project TimeGenerated, Resource, OperationName, requestUri_s, ResultType, ResultDescription

O log inclui o tipo de operação (encapsular ou desembrulhar), o identificador de chave externa, o código de status HTTP retornado pelo proxy e a latência de ida e volta. Para obter o guia completo de registro em log e monitoramento, incluindo a configuração de alertas e a correlação de logs no lado do proxy, consulte Registro em log e monitoramento para gerenciamento de chaves externas para HSM gerenciado.

Limpar os recursos

Se você configurou um serviço Azure para usar essa chave, migre a carga de trabalho para outra chave antes de excluir a referência ou a conexão. Mantenha a chave externa e sua conexão pelo tempo que os dados, backups ou instantâneos da carga de trabalho exigirem isso.

Para remover os recursos criados neste Início Rápido:

1. Exclua a referência de chave HSM gerenciada:

   az keyvault key delete \
       --hsm-name <Managed HSM Name> \
       --name <key-ref-name>
   

2. Excluir a conexão de gerenciamento externo de chaves:

   az keyvault ekm-connection delete \
       --hsm-name <Managed HSM Name>
   

Excluir a referência de chave HSM gerenciada não afeta o material de chave no HSM externo. Essa chave permanece em seu HSM até você removê-la lá.

Próximas Etapas 

• Início Rápido: Crie sua primeira chave externa usando o portal Azure: conclua o mesmo fluxo no portal Azure.
• Ciclo de vida de chave externa no gerenciamento de chaves externas do HSM gerenciado: rotação de chaves, controle de versão e desativação de chaves externas.
• Configurar a rede e o mTLS para gerenciamento de chave externa do HSM Gerenciado: conectividade com a Internet pública, integração do Link Privado (versão preliminar) e rotação de certificados.
• Registro em log e monitoramento para gerenciamento de chaves externas do Managed HSM: regras de alerta, consultas KQL (Linguagem de Consulta Kusto) e correlação de logs de proxy.
• Solucionar problemas de gerenciamento de chave externa do HSM gerenciado: códigos de erro, diagnóstico de proxy e etapas de correção.