Biblioteca de descarga de TLS de HSM administrado de Azure
HSM administrado por Azure ofrece una biblioteca de descarga TLS que es compatible con PKCS#11 versión 2.40. HSM administrado por Azure no admite todas las funciones enumeradas en la especificación PKCS#11; en su lugar, la biblioteca de descarga TLS admite un conjunto limitado de mecanismos y funciones de interfaz solo para la descarga SSL/TLS con F5 (BigIP) y Nginx, principalmente para generar claves de certificado de servidor TLS y generar firmas digitales durante los protocolos de enlace TLS.
Para más información, consulte la Biblioteca de descarga de TLS de HSM administrado de Azure GitHub.
La biblioteca de descarga de TLS usa internamente la API de REST de Azure Key Vault para interactuar con HSM administrado de Azure.
Primeros pasos
Atributos PKCS#11
Para integrarse correctamente con PKCS#11, la generación de claves (a través de C_GenerateKeyPair) y la localización de objetos de clave (mediante C_FindObjectsInit/C_FindObjects) requiere una solución para almacenar atributos PKCS#11 en el objeto de clave de Azure Key Vault. La biblioteca de descarga de TLS convierte estos atributos PKCS#11 necesarios en etiquetas de Azure Key Vault.
Estas "etiquetas de atributo" tienen un prefijo especial:
- p11_pri_{P11 Attribute Name}: atributos de clave privada
- p11_pub_{P11 Attribute Name}: atributos de clave pública
La biblioteca de descarga de TLS establece correctamente los atributos de operaciones de clave y duración de claves de Azure Key Vault para que el servicio pueda aplicar correctamente estas restricciones en las claves generadas. Estos atributos también se almacenan como etiquetas como otros atributos PKCS#11 para admitir funcionalidades de consulta.
Las aplicaciones que usan la biblioteca de descarga TLS usan uno o varios atributos PKCS#11 para buscar y usar los objetos de clave.
Advertencia
Las claves generadas por la biblioteca de descarga de TLS y sus etiquetas son accesibles a través de la API de REST de Azure Key Vault. Manipular estas etiquetas de atributo P11 mediante la API de REST de Azure Key Vault puede interrumpir las aplicaciones de la biblioteca de descarga de TLS.
Generación de la clave
La biblioteca de descarga de TLS incluye una herramienta de creación de claves, mhsm_p11_create_key. La ejecución de la herramienta sin ningún argumento de línea de comandos muestra el uso correcto de la herramienta.
La herramienta de creación de claves requiere una entidad de servicio que se asigna al rol "Usuario criptográfico de HSM administrado" en el ámbito "/keys".
La herramienta de creación de claves lee las credenciales de la entidad de servicio de las variables de entorno MHSM_CLIENT_ID y MHSM_CLIENT_SECRET:
- MHSM_CLIENT_ID: debe establecerse en el id. de aplicación (cliente) de la entidad de servicio
- MHSM_CLIENT_SECRET: debe establecerse en la contraseña de la entidad de servicio (secreto de cliente)
En el caso de las identidades administradas, las variables de entorno anteriores no son necesarias.
- Use el argumento
--identitypara habilitar la identidad administrada con la herramienta mhsm_p11_create_key. - La identidad administrada asignada por el usuario
client_iddebe citarse en el archivo de configuración de MHSM (mhsm-pkcs11.conf). Si no se proporciona la propiedadclient_idde una identidad administrada asignada por el usuario, se considerará como identidad administrada asignada por el sistema.
La herramienta de creación de claves genera aleatoriamente un nombre para la clave al momento de la creación. El id. de clave completo de Azure Key Vault y el nombre de la clave se imprimen en la consola para su comodidad.
MHSM_CLIENT_ID="<service-principal-application-id>" \
MHSM_CLIENT_SECRET="<service-principal-password>" \
mhsm_p11_create_key --RSA 4K --label tlsKey
Key is generated successfully. \
Managed HSM Key ID: https://myhsm.managedhsm.azure.net/keys/p11-6a2155dc40c94367a0f97ab452dc216f/92f8aa2f1e2f4dc1be334c09a2639908 \
Key Name: p11-6a2155dc40c94367a0f97ab452dc216f
El argumento --label de la herramienta de creación de claves especifica el CKA_LABEL deseado para las claves privadas y públicas generadas. Normalmente, estos atributos son necesarios para configurar las soluciones de descarga de TLS admitidas (por ejemplo, el valor de configuración SSL de Nginx "ssl_certificate_key").
Necesita el nombre de clave para cualquier cambio de asignación de roles a través de la CLI de Azure.
Control de acceso
La biblioteca de descarga de TLS traduce el C_FindObjectsInit en una llamada API de REST de Azure Key Vault, que funciona en el ámbito /keys. El servicio MHSM requiere un permiso de lectura en este ámbito para que el usuario de la Biblioteca de descarga TLS autorice la operación de búsqueda para las claves creadas a través de la herramienta de creación de claves.
Para más información sobre RBAC local de HSM administrado de Azure, consulte:
- Roles integrados de RBAC local de HSM administrado de Azure
- Administración de roles de HSM administrado de Azure
En la sección siguiente, se describen diferentes enfoques para implementar el control de acceso para la entidad de servicio de la biblioteca de descarga de TLS y la identidad administrada.
Entidad de servicio de descarga de TLS
La aplicación que usa la Biblioteca de descarga de TLS usa la entidad de servicio de descarga TLS para acceder a las claves y debe tener como mínimo el siguiente permiso a través de la asignaciones de roles:
- Permiso KeyRead para todas las claves del HSM administrado
- Permiso KeySign para las claves necesarias para la descarga de TLS
Usuario administrador
El usuario administrador creará una definición de roles personalizada y asignaciones de roles. Por lo tanto, el usuario administrador debe asignarse a uno de los siguientes roles integrados en el ámbito "/":
- Managed HSM Crypto Officer
- Managed HSM Policy Administrator
- Managed HSM Administrator
Entidad de servicio de generación de claves
La entidad de servicio de generación de claves se usa con la herramienta de creación de claves (mhsm_p11_create_key) para generar claves de descarga TLS. Esta entidad de servicio debe asignarse al rol "Usuario criptográfico de HSM administrado" en el ámbito "/keys".
Azure CLI
La CLI de Azure se puede usar para realizar tareas como la asignación de roles.
Enfoque permisivo
El enfoque permisivo es más sencillo y adecuado cuando el HSM administrado de Azure se usa exclusivamente para la descarga de TLS.
Asigne el rol de usuario criptográfico a la entidad de servicio de descarga de TLS en el ámbito "/keys". Esto proporciona a la entidad de servicio de descarga TLS el permiso para generar claves y buscarlas para la descarga de TLS.
az keyvault role assignment create --hsm-name ContosoMHSM \
--role "Managed HSM Crypto User" \
--assignee TLSOffloadServicePrincipal@contoso.com \
--scope /keys
En Identidades administradas, especifique los argumentos de comando de la siguiente manera:
az keyvault role assignment create --hsm-name ContosoMHSM \
--role "Managed HSM Crypto User" \
--assignee-object-id <object_id> \
--assignee-principal-type MSI \
--scope /keys
Enfoque granular
El enfoque granular implementa un control de acceso específico. Requiere dos entidades de servicio (entidad de servicio de descarga de TLS y entidad de servicio de generación de claves) y un usuario administrador.
El objetivo es restringir los permisos de la entidad de servicio de descarga de TLS para admitir el mínimo necesario para la descarga de TLS. El usuario debe tener un permiso de lectura para que otras claves admitan la función C_FindObject* de la biblioteca.
Rol de lectura del usuario de la biblioteca de descarga de TLS
El primer paso para implementar el enfoque granular es crear un rol personalizado. Solo es necesario hacerlo una vez.
El usuario administrador (con el rol de oficial criptográfico de HSM administrado o administrador de HSM administrado o administrador de directivas de HSM administrado) crea una definición de rol personalizada de "Rol de lectura de usuario de biblioteca TLS":
az keyvault role definition create --hsm-name ContosoMHSM --role-definition '{ \
"roleName": "TLS Library User Read Role", \
"description": "Grant Read access to keys", \
"actions": [], \
"notActions": [], \
"dataActions": ["Microsoft.KeyVault/managedHsm/keys/read/action"], \
"notDataActions": [] \
}'
Generar claves
Las claves se pueden generar mediante la entidad de servicio de generación de claves con la herramienta de creación de claves (mhsm_p11_create_key).
Concesión de permisos
El usuario administrador asigna los siguientes roles a la entidad de servicio de descarga TLS.
- Asignación del rol "Rol de lectura del usuario de la biblioteca TLS" en el ámbito "/keys"
- Asignar el rol "Usuario criptográfico de HSM administrado" en el ámbito "/keys/{key name}"
En el ejemplo siguiente, el nombre de clave es "p11-6a2155dc40c94367a0f97ab452dc216f".
az keyvault role assignment create --hsm-name ContosoMHSM \
--role "TLS Library User Read Role" \
--assignee TLSOffloadServicePrincipal@contoso.com \
--scope /keys
az keyvault role assignment create --hsm-name ContosoMHSM \
--role "Managed HSM Crypto User" \
--assignee TLSOffloadServicePrincipal@contoso.com \
--scope /keys/p11-6a2155dc40c94367a0f97ab452dc216f
Almacenamiento en caché de conexiones
Para mejorar el rendimiento de las llamadas de inicio de sesión al servicio HSM administrado, la biblioteca de descarga de TLS almacenará en caché sus conexiones TLS para los servidores de servicio HSM administrados. De forma predeterminada, la biblioteca de descarga de TLS almacenará en caché hasta 20 conexiones TLS. El almacenamiento en caché de conexión se puede controlar a través del archivo de configuración de MHSM (mhsm-pkcs11.conf).
"ConnectionCache": {
"Disable": false,
"MaxConnections": 20
}
Deshabilitar
Si este valor fuera verdadero, se deshabilitará el almacenamiento en la caché de conexiones. Se habilita de forma predeterminada.
MaxConnections
Especifica el número máximo de conexiones que se vayan a almacenar en caché. El límite máximo de conexiones debería configurarse en función del número de sesiones PKCS11 simultáneas que use la aplicación. Las aplicaciones suelen crear un grupo de sesiones PKCS11 y las usan desde un grupo de subprocesos para generar solicitudes de firma en paralelo. MaxConnections debe coincidir con el número de solicitudes de firma simultáneas generadas por las aplicaciones.
La solicitud de firma por segundo (RPS) depende del número de solicitudes simultáneas y del número de conexiones almacenadas en caché. Si se especifica un número mayor o, incluso, el límite predeterminado, no se mejorará el RPS de firma si el número de solicitudes de firma PKCS11 simultáneas fuera inferior a este límite. El número máximo de conexiones simultáneas para lograr el modo de ráfaga del grupo de HSM estándar B1 es de aproximadamente 30, según el tipo de instancia. Pero debería probar con números diferentes para averiguar el número óptimo de conexiones simultáneas.
Consulte la documentación de la aplicación o póngase en contacto con el proveedor de la aplicación para obtener más información sobre cómo la aplicación usa la biblioteca PKCS11.
Uso de la biblioteca de descarga de TLS
Generar claves
La biblioteca de descarga de TLS incluye una herramienta de creación de claves, mhsm_p11_create_key. La ejecución de la herramienta sin ningún argumento de línea de comandos muestra el uso correcto de la herramienta.
La herramienta de creación de claves requiere una entidad de servicio que se asigna al rol "Usuario criptográfico de HSM administrado" en el ámbito "/keys".
La herramienta de creación de claves lee las credenciales de la entidad de servicio de las variables de entorno MHSM_CLIENT_ID y MHSM_CLIENT_SECRET.
- MHSM_CLIENT_ID: debe establecerse en el id. de aplicación (cliente) de la entidad de servicio
- MHSM_CLIENT_SECRET: debe establecerse en la contraseña de la entidad de servicio (secreto de cliente)
La herramienta de creación de claves genera aleatoriamente un nombre para la clave al momento de la creación. El id. completo de la clave de Azure Key Vault y el nombre de clave se imprimen en la consola para su comodidad.
MHSM_CLIENT_ID="<service-principal-application-id>" \
MHSM_CLIENT_SECRET="<service-principal-password>" \
mhsm_p11_create_key --RSA 4K --label tlsKey
Key is generated successfully.
Managed HSM Key ID: https://myhsm.managedhsm.azure.net/keys/p11-6a2155dc40c94367a0f97ab452dc216f/92f8aa2f1e2f4dc1be334c09a2639908 \
Key Name: p11-6a2155dc40c94367a0f97ab452dc216f
El argumento --label de la herramienta de creación de claves especifica el CKA_LABEL deseado para las claves privadas y públicas generadas. Normalmente, estos atributos son necesarios para configurar las soluciones de descarga de TLS admitidas (por ejemplo, el valor de configuración SSL de Nginx "ssl_certificate_key").
El nombre de clave es necesario si planea implementar el acceso granular a las claves.
Implementación de TLS sin claves
Hay dos enfoques para generar una clave y usar la clave para un TLS sin clave: un enfoque más sencillo y más permisivo, y un enfoque granular que ofrece una mejor seguridad. Los enfoques difieren en el esfuerzo de implementación y la aplicación de seguridad.
Enfoque más sencillo
- Creación de una entidad de servicio para la biblioteca de descarga TLS (por ejemplo, TLSOffload ServicePrincipal)
- Asigne el rol de usuario criptográfico de HSM administrado a la entidad de servicio de descarga de TLS en el ámbito "/keys".
az keyvault role assignment create --hsm-name ContosoMHSM \ --role "Managed HSM Crypto User" \ --assignee TLSOffloadServicePrincipal@contoso.com \ --scope /keys - Genere la clave con la etiqueta necesaria siguiendo los pasos descritos en Cómo generar claves mediante la biblioteca de descarga de TLS.
- Configuración del servidor TLS para usar la biblioteca de descarga de TLS de HSM administrado como biblioteca de interfaz PKCS#11
- Configure el servidor TLS (por ejemplo, el valor de configuración SSL de Nginx "ssl_certificate_key") con la etiqueta de clave y las credenciales de la entidad de servicio de descarga de TLS
Enfoque granular
- Cree un usuario administrador (por ejemplo, TLSOffloadAdminUser) con el siguiente rol:
- Rol "Agente criptográfico de HSM administrado" en el ámbito "/"
- Cree una entidad de servicio de generación de claves (por ejemplo, TLSOffloadKeyGenServicePrincipal) para la generación de claves de descarga de TLS y asigne el rol siguiente:
- Rol "Usuario criptográfico de HSM administrado" en el ámbito "/keys".
- Creación de una entidad de servicio para la descarga de TLS (por ejemplo, TLSOffload ServicePrincipal)
- El usuario administrador crea la siguiente definición de roles personalizados:
az keyvault role definition create --hsm-name ContosoMHSM --role-definition '{ \ "roleName": "TLS Library User Read Role", \ "description": "Grant Read access to keys", \ "actions": [], \ "notActions": [], \ "dataActions": ["Microsoft.KeyVault/managedHsm/keys/read/action"], \ "notDataActions": [] }' - Genere una clave con la etiqueta necesaria siguiendo los pasos descritos en "Cómo generar claves mediante la biblioteca de descarga de TLS". Use la entidad de servicio de generación de claves (por ejemplo, TLSOffloadKeyGenServicePrincipal) al generar claves. Anote la etiqueta de clave y el nombre de la clave. Por ejemplo:
- Etiqueta de clave: tlsKey
- Nombre de clave: p11-6a2155dc40c94367a0f97ab452dc216f
- El usuario administrador asigna los siguientes roles a la entidad de servicio de descarga de TLS
- "Rol de lectura del usuario de la biblioteca TLS" en el ámbito "/keys"
- Rol de "Usuario criptográfico de HSM administrado" en el ámbito "/keys/{key name}"
az keyvault role assignment create --hsm-name ContosoMHSM \ --role " TLS Library User Read Role" \ --assignee TLSOffloadServicePrincipal @contoso.com \ --scope /keys az keyvault role assignment create --hsm-name ContosoMHSM \ --role "Managed HSM Crypto User" \ --assignee TLSOffloadServicePrincipal@contoso.com \ --scope /keys/p11-6a2155dc40c94367a0f97ab452dc216f - Configuración del servidor TLS para usar la Biblioteca de descarga de TLS de HSM administrado de Azure como biblioteca de interfaz PKCS#11
- Configure el servidor TLS (por ejemplo, el valor de configuración SSL de Nginx "ssl_certificate_key") con la etiqueta de clave y las credenciales de la entidad de servicio de descarga de TLS