Início rápido: Crie a sua primeira chave externa usando a CLI do Azure (pré-visualização)

Importante

A gestão de chaves externas do Managed HSM está em pré-visualização. As funcionalidades de pré-visualização estão disponíveis sob a condição de concordar com os termos suplementares de utilização. Alguns aspetos desta funcionalidade podem mudar antes da disponibilidade geral.

Neste guia de início rápido, regista uma ligação ao EKM Proxy no seu Managed HSM e, em seguida, cria uma referência de chave no Managed HSM que aponta para uma chave no HSM operado pelo cliente. No fim, executa um ciclo de encapsulamento/desencapsulamento para confirmar que a integração funciona corretamente.

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, com a gestão de chaves externas ativada na subscrição pela equipa da sua conta Microsoft. Contacte a sua equipa de conta para solicitar a habilitação. 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. É assim que o proxy valida que a ligação vem do seu HSM gerido — 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.

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 estar à escuta na porta TCP 443; uma porta não predefinida não é suportada na versão preliminar.
  • --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. Não é gerado qualquer material de chaves no Managed HSM — este comando regista uma referência a uma chave existente identificada pelo seu identificador externo de chave.

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>. Use este URI ao configurar as definições de chave gerida pelo cliente (CMK) nos serviços do Azure.

Verificar encapsular/desencapsular

Confirme a integração de ponta a ponta com um ciclo de wrap/unwrap. As operações reais de encapsulamento e desencapsulamento ocorrem no seu proxy e no HSM externo — o Managed HSM encaminha o pedido e devolve o resultado.

Importante

Não uses az keyvault key encrypt para testar uma chave externa. Este comando executa uma operação encrypt, que a gestão externa de chaves não suporta — a gestão externa de chaves suporta apenas wrapKey e unwrapKey. Em vez disso, chame diretamente os pontos finais do plano de dados wrapkey e unwrapkey com az rest.

  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.

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

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

  • Last updated on