Início Rápido: Criar sua primeira chave externa usando o CLI do Azure (versão prévia)

Neste Início Rápido, você registra uma conexão de Proxy EKM com seu HSM gerenciado e, em seguida, cria uma referência de chave HSM gerenciada que aponta para uma chave no HSM operado pelo cliente. Ao final, você executa um ciclo de encapsulamento e desencapsulamento para confirmar que a integração funciona.

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 do Azure, com o gerenciamento de chaves externas habilitado na assinatura pela equipe da sua conta da Microsoft. Contate sua equipe de conta para solicitar a habilitação. 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. É assim que o proxy valida que a conexão vem do 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.

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 na versão prévia.
• --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. Nenhum material de chave é gerado dentro do HSM Gerenciado – 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>. Use esse URI ao definir as configurações de CMK (chave gerenciada pelo cliente) em serviços de Azure.

Verificar encapsulamento/desencapsulamento

Confirme a integração de ponta a ponta com um processo de ida e volta de encapsulamento e desencapsulamento. As operações de encapsulamento e desencapsagem reais ocorrem no proxy e no HSM externo — o HSM gerenciado roteia a solicitação e retorna o resultado.

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.

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

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: Criar 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 gerenciado de chaves externas do HSM — conectividade com a Internet pública e rotação de certificados
• Registro em log e monitoramento para gerenciamento de chaves externas do HSM gerenciado — regras de alerta, consultas da KQL (Linguagem de Consulta Kusto) e correlação de logs de proxy
• Solucionar problemas de gerenciamento de chaves externas do HSM gerenciado — códigos de erro, diagnóstico de proxy e etapas de correção