Início rápido: Crie a sua primeira chave externa usando a CLI do Azure

Neste quickstart, liga o seu HSM externo ao HSM Gerido, cria uma referência de chave externa e testa o caminho de proteção de chaves. Depois, utiliza o URI da chave HSM gerida para configurar a encriptação em repouso com chave gerida pelo cliente (CMK) num serviço Azure compatível.

Para o modelo de encriptação e compatibilidade de serviços, veja O que é a gestão de chaves externas do Managed HSM?

Se preferir usar o portal Azure, veja Quickstart: Crie a sua primeira chave externa usando o portal Azure.

Prerequisites

Antes de começar, você precisa:

  • Um HSM gerido existente implementado em qualquer região pública do Azure, numa subscrição habilitada para gestão externa de chaves. Para criar um HSM Gerido, consulte Quickstart: Provisionar e ativar um HSM Gerido usando CLI do Azure.
  • Um Proxy EKM operacional acessível a partir do Azure. O proxy deve implementar a especificação da API Proxy EKM. Para ver os fornecedores suportados, consulte O que é a gestão externa de chaves do Managed HSM?.
  • Uma chave criada no seu HSM externo com um identificador de chave externo conhecido. O identificador de chave externa é o identificador que o seu proxy usa para consultar a chave.
  • O certificado de CA raiz (formato PEM) que assinou o certificado do servidor TLS do seu proxy.
  • CLI do Azure versão 2.x com a mais recente keyvault extensão instalada. Corre az extension add --name keyvault ou az extension update --name keyvault para obter a versão mais recente.
  • O Managed HSM EKM Administrator papel é gerir ligações externas de gestão de chaves, e o Managed HSM Crypto User papel de criar e usar chaves. Para os passos para a atribuição de funções, consulte Controlo de acesso a Managed HSM.

Iniciar sessão no Azure

az login

Defina a sua subscrição se tiver mais do que uma:

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

Mostrar o certificado de cliente HSM gerido

O HSM gerido apresenta um certificado de cliente X.509 ao seu Proxy EKM em cada ligação TLS mútua (mTLS) de entrada. Antes de criar a ligação externa de gestão de chaves, recupere o nome comum do sujeito do certificado e o certificado raiz da CA e permita-os listar no seu proxy. Isto permite ao proxy validar que a ligação vem do seu HSM Gerido, e 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 nas ligações que apresentem um certificado com o subjectCommonName e encadeado a um dos certificados na lista caCertificates acima. Os passos exatos dependem do seu fornecedor proxy.

Note

Para etapas de rotação e detalhes do ciclo de vida dos certificados, consulte Configurar a rede e o mTLS para a gestão de chaves externas no Managed HSM.

Criar a ligação externa de gestão de chaves

A ligação externa de gestão de chaves vincula o seu HSM Gerido a um único Proxy EKM. Contém o endereço proxy, a âncora de confiança da CA do servidor e um prefixo de caminho opcional.

Esta secção cria uma ligação pública à internet. Para o Private Link, siga antes Configurar o modelo Azure Private Link (pré-visualização) e depois continue com Verificar a ligação.

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

Referência do parâmetro:

  • --hsm-name: O nome do seu HSM gerido.
  • --host: O nome de anfitrião totalmente qualificado do seu proxy EKM. Por exemplo, proxy.contoso.com. O proxy deve ouvir na porta TCP 443; uma porta não padrão não é suportada.
  • --server-ca-certificate: Especifica o caminho para o ficheiro de certificado da CA raiz (formato PEM ou DER) usado para verificar o certificado do servidor TLS do proxy.
  • --path-prefix (opcional): Um prefixo do caminho do URL, caso o seu proxy multiplexe vários clientes ou grupos por caminho. Por exemplo, /contoso/prod.

Note

Passe o certificado de CA raiz para --server-ca-certificate, não para o certificado folha do proxy. O HSM gerido usa esta CA para validar toda a cadeia de certificados apresentada pelo seu proxy durante o handshake do mTLS. Passar o certificado de folha, em vez disso, faz com que o aperto de mão falhe em qualquer renovação de certificado.

Verifique a ligação

Depois de criar a ligação, verifique se o HSM Gerido consegue aceder ao seu proxy:

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

Este comando chama o endpoint do /info proxy através da ligação configurada. A produção 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 comuns de falha incluem regras de firewall que bloqueiam a porta do proxy, um valor incorreto de --host ou a rejeição, pelo proxy, do certificado de cliente do HSM Gerido. Para obter os passos de remediação, consulte Resolução de problemas da gestão de chaves externas do HSM Gerido.

Criar a chave externa

Crie uma referência de chave HSM gerida que aponte para a chave externa no seu HSM. O HSM gerido não gera nenhum material de chave. Este comando regista uma referência a uma chave existente identificada pelo seu identificador externo.

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

Referência do parâmetro:

  • --external-key-id: O identificador de chave externa registado no seu proxy. Este é o identificador que o proxy usa para procurar a chave correta no seu HSM externo.
  • --hsm-name: O nome do seu HSM gerido.
  • --name: O nome que pretende dar à referência da chave do HSM gerido. Isto torna-se parte do URI-chave que os serviços do Azure utilizam.

Importante

O identificador externo de chave é imutável durante toda a vida útil de uma versão de chave. Não podes mudar isso depois da criação. Para efetuar a rotação da chave, crie uma nova versão da chave com um novo identificador externo da chave usando az keyvault key create com o mesmo --name. O URI da chave (URI HSM + nome da chave) mantém-se estável entre as versões; apenas o segmento de versão muda.

O comando devolve o URI-chave na forma https://<hsm-name>.managedhsm.azure.net/keys/<key-ref-name>/<version>. Guarde este URI para configurar o seu serviço Azure.

Verificar encapsular/desencapsular

Teste o caminho de proteção da chave com um wrap and unwrap round trip. O HSM externo realiza as operações através do seu proxy, e o Managed HSM devolve o resultado. Este teste confirma que o key path funciona. Não configura nem valida a integração CMK de um serviço Azure.

Note

Utilize os wrapkey endpoints do plano de dados e unwrapkey com az rest para este teste. az keyvault key encrypt chama uma operação de API de chave diferente e não substitui o wrapping de uma chave de encriptação de dados.

  1. Crie um corpo de pedido para a operação de enrolamento. Define value para o material de chave codificado base64url que queres envolver.

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

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

  2. Chame o wrapkey endpoint na sua referência 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 devolve a versão da chave (kid) e um value campo contendo a chave encapsulada codificada base64url. Copie o value para o passo seguinte.

  3. Crie um corpo de pedido para a operação de desdobramento, usando o wrapped value do passo anterior:

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

    Guarde-o como unwrapkey.json.

  4. Chame o endpoint unwrapkey para confirmar a correção da operação 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 com êxito retorna o texto simples original value que incluiu no primeiro passo. Se o desencapsulamento falhar, consulte Troubleshoot Managed HSM external key management para ver os códigos de erro do proxy e os passos para resolução.

Usar a chave com um serviço Azure

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

  1. Confirme que o serviço suporta CMKs com HSM gerido e que o tipo e algoritmo da sua chave externa cumprem os seus requisitos.
  2. Conceda à identidade usada pelo serviço as permissões RBAC locais do HSM gerido necessárias. Para orientações sobre atribuição de funções, veja Controlo de acesso Managed HSM.
  3. Configure as definições CMK do serviço com o URI da chave HSM gerida. Utilize o formato de URI, versionado ou não versionado, exigido por esse serviço. Para Armazenamento do Azure, veja Configurar chaves geridas pelo cliente com Azure Key Vault Managed HSM.
  4. Confirme que o serviço reporta a configuração CMK esperada, depois execute uma operação de leitura/escrita na carga de trabalho protegida. Revise os registos de diagnóstico do serviço e os registos da gestão externa de chaves do Managed HSM caso a operação falhe.

O serviço Azure utiliza a sua integração existente com o Managed HSM. Não precisa da API ou credenciais específicas do seu HSM externo.

Visualizar registos de auditoria

Cada chamada do EKM Proxy produz uma entrada EkmProxyOperation nos registos de diagnóstico do Managed HSM. Para consultar estes no Log Analytics:

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

O registo inclui o tipo de operação (enrolar ou desdobrar), o identificador externo da chave, o código de estado HTTP devolvido pelo proxy e a latência de ida e volta. Para consultar o guia completo de registo e monitorização, incluindo a configuração de alertas e a correlação de registos do lado do proxy, consulte Registo e monitorização da gestão de chaves externas do HSM Gerido.

Limpeza de recursos

Se configurou um serviço Azure para usar esta chave, migre a carga de trabalho para outra chave antes de eliminar a referência ou a ligação. Mantenha a chave externa e a sua ligação durante o tempo em que os dados, backups ou snapshots da carga de trabalho o exigirem.

Para eliminar os recursos criados neste início rápido:

  1. Eliminar a referência da chave do Managed HSM:

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

  2. Eliminar a ligação à gestão externa de chaves:

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

Eliminar a referência à chave do Managed HSM não afeta o material criptográfico da chave no seu HSM externo. Essa chave permanece no teu HSM até a removeres lá.

Passos seguintes

  • Última atualização a