Inicio rápido: Creación de la primera clave externa mediante el CLI de Azure (versión preliminar)

Importante

La administración de claves externas de Managed HSM está en versión preliminar. Las características en versión preliminar están disponibles para usted en la condición de que acepte los términos de uso complementarios. Algunos aspectos de esta característica pueden cambiar antes de la disponibilidad general.

En esta guía de inicio rápido, registrará una conexión de EKM Proxy a su HSM administrado y, a continuación, creará una referencia de clave de HSM administrado que apunte a una clave de su HSM administrado por el cliente. Al final, se ejecuta una operación de encapsulado/desencapsulado de ida y vuelta para confirmar que la integración funciona.

Si prefiere usar el portal de Azure, consulte Inicio rápido: Creación de la primera clave externa mediante el portal de Azure.

Prerequisites

Antes de comenzar, necesita lo siguiente:

  • Un HSM administrado existente implementado en cualquier región pública de Azure, con la administración de claves externas habilitada en la suscripción por su equipo de cuenta de Microsoft. Póngase en contacto con el equipo de su cuenta para solicitar la habilitación. Para crear un HSM administrado, consulte Inicio rápido: Aprovisionamiento y activación de un HSM administrado mediante CLI de Azure.
  • Un proxy EKM operativo accesible desde Azure. El proxy debe implementar la especificación de la API de proxy de EKM. Para consultar los proveedores admitidos, consulte ¿Qué es la administración externa de claves de Managed HSM?.
  • Clave creada en el HSM externo con un identificador de clave externa conocido. El identificador de clave externa es el identificador que usa el proxy para buscar la clave.
  • El certificado de CA raíz (formato PEM) que firmó el certificado de servidor TLS de su proxy.
  • CLI de Azure versión 2.x con la extensión más reciente keyvault instalada. Ejecute az extension add --name keyvault o az extension update --name keyvault para obtener la versión más reciente.
  • Rol Managed HSM EKM Administrator para administrar conexiones de administración de claves externas y el Managed HSM Crypto User rol para crear y usar claves. Para conocer los pasos de asignación de roles, consulte Control de acceso de HSM administrado.

Iniciar sesión en Azure

az login

Establezca la suscripción si tiene más de una:

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

Mostrar el certificado de cliente de Managed HSM

El HSM administrado presenta un certificado de cliente X.509 a su proxy EKM en cada conexión TLS mutua (mTLS) entrante. Antes de crear la conexión con el sistema externo de gestión de claves, recupere el nombre común del sujeto del certificado y el certificado raíz de la entidad de certificación, y añádalos a la lista de permitidos de su proxy. Así es como el proxy valida que la conexión procede del HSM administrado, no de un autor de llamada arbitrario.

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

La salida tiene un aspecto similar al siguiente:

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

Configure su proxy para que confíe en las conexiones que presenten un certificado con el subjectCommonName y cuya cadena de confianza termine en uno de los certificados de la lista caCertificates anterior. Los pasos exactos dependen del proveedor de proxy.

Note

Para conocer los pasos de rotación y los detalles del ciclo de vida de los certificados, consulte Configuración de redes y mTLS para la administración de claves externas de HSM administrado.

Crear la conexión externa de gestión de claves

La conexión de administración de claves externas vincula su HSM administrado a un único Proxy de EKM. Contiene la dirección del proxy, el ancla de confianza de la CA del servidor y un prefijo de ruta opcional.

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

Referencia de parámetros:

  • --hsm-name: el nombre del HSM administrado.
  • --host: El nombre de host plenamente cualificado de su EKM Proxy. Por ejemplo: proxy.contoso.com. El proxy debe escuchar en el puerto TCP 443; No se admite un puerto no estándar en la versión preliminar.
  • --server-ca-certificate: especifica la ruta de acceso al archivo de certificado de entidad de certificación raíz (formato PEM o DER) que se usa para comprobar el certificado de servidor TLS del proxy.
  • --path-prefix (opcional): Un prefijo de ruta URL si tu proxy multiplexa varios clientes o grupos por ruta. Por ejemplo: /contoso/prod.

Note

Transmita el certificado raíz de la CA a --server-ca-certificate, no el certificado final del proxy. El HSM administrado usa esta autoridad de certificación para validar toda la cadena de certificados presentada por su proxy durante el protocolo de enlace de mTLS. Si se pasa el certificado leaf, el protocolo de enlace generará un error en cualquier renovación de certificado.

Verifique la conexión

Después de crear la conexión, compruebe que el HSM administrado puede acceder a su proxy:

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

Este comando invoca el punto de conexión /info del proxy a través de la conexión configurada. La salida correcta tiene un aspecto similar al siguiente:

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

Entre las causas comunes de errores se incluyen reglas de firewall que bloquean el puerto proxy, un valor incorrecto --host o el proxy que rechaza el certificado de cliente HSM administrado. Para conocer los pasos de corrección, consulte Solución de problemas de administración de claves externas de HSM administrado.

Creación de la clave externa

Crea una referencia de clave de HSM administrado que apunte a la clave externa de tu HSM. No se genera ningún material de clave dentro de HSM administrado: este comando registra una referencia a una clave existente identificada por su identificador de clave externa.

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

Referencia de parámetros:

  • --external-key-id: identificador de clave externa registrado en el proxy. Este es el identificador que usa el proxy para buscar la clave correcta en el HSM externo.
  • --hsm-name: el nombre del HSM administrado.
  • --name: el nombre que desea asignar a la referencia de clave HSM administrada. Esto pasa a formar parte del URI de la clave que usan los servicios de Azure.

Importante

El identificador de clave externa es inmutable durante la vigencia de una versión de clave. No se puede cambiar después de la creación. Para rotar la clave, cree una nueva versión de clave con un nuevo identificador de clave externa mediante az keyvault key create con el mismo --name. El URI de clave (URI de HSM + nombre de clave) permanece estable entre versiones; solo cambia el segmento de versión.

El comando devuelve el URI de clave con el formato https://<hsm-name>.managedhsm.azure.net/keys/<key-ref-name>/<version>. Use este URI al configurar las opciones de clave administrada por el cliente (CMK) en Azure servicios.

Verifica el proceso de envoltura/desenvoltura

Confirma la integración de extremo a extremo con un ciclo completo de envoltura/desenvoltura. Las operaciones reales de envoltura y desenvoltura tienen lugar en su proxy y en el HSM externo; el HSM administrado enruta la solicitud y devuelve el resultado.

Importante

No utilice az keyvault key encrypt para comprobar una clave externa. Ese comando ejecuta una operación encrypt, que la gestión externa de claves no admite; la gestión externa de claves solo admite wrapKey y unwrapKey. En su lugar, llame directamente a los puntos de conexión del plano de datos wrapkey y unwrapkey con az rest.

  1. Cree un cuerpo de solicitud para la operación de envoltura. Establezca value en el material de clave codificado en base64url que desee envolver.

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

    Guárdelo como wrapkey.json. Para las claves externas de AES, use "alg": "A256KW" en lugar de RSA-OAEP-256.

  2. Llama al punto de conexión wrapkey de tu referencia de clave:

    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

    La respuesta devuelve la versión de la clave (kid) y un campo value que contiene la clave encapsulada codificada en base64url. Copie el value para el siguiente paso.

  3. Crea un cuerpo de solicitud para la operación de desempaquetado, utilizando el value empaquetado del paso anterior:

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

    Guárdelo como unwrapkey.json.

  4. Llama al punto de conexión unwrapkey para confirmar que el ciclo de ida y vuelta es correcto:

    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

    Una respuesta satisfactoria devuelve el texto sin formato original value que incluyó en el primer paso. Si el desempaquetado genera un error, consulta Solución de problemas de la administración de claves externas de Managed HSM para conocer los códigos de error del proxy y los pasos de corrección.

Visualización de registros de auditoría

Cada llamada al Proxy de EKM genera una entrada EkmProxyOperation en los registros de diagnóstico de Managed HSM. Para consultarlos en Log Analytics:

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

El registro incluye el tipo de operación (encapsular o desencapsular), el identificador de clave externa, el código de estado HTTP devuelto por el proxy y la latencia de ida y vuelta. Para consultar la guía completa de registro y supervisión, incluida la configuración de alertas y la correlación de registros del lado del proxy, véase Registro y supervisión de la administración de claves externas de HSM administrado.

Limpieza de recursos

Para eliminar los recursos creados en esta guía de inicio rápido:

  1. Elimine la referencia de clave de HSM administrado:

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

  2. Elimine la conexión de administración de claves externas:

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

La eliminación de la referencia de clave de HSM administrado no afecta al material de clave de su HSM externo. Esa clave permanece en el HSM hasta que la quite allí.

Pasos siguientes

  • Last updated on