biblioteca cliente de Azure Attestation para Python: versión 1.0.0

Artículo
04/05/2023

El servicio Microsoft Azure Attestation (MAA) es una solución unificada para comprobar de forma remota la confiabilidad de una plataforma e integridad de los archivos binarios que se ejecutan en él. El servicio admite la atestación de las plataformas respaldadas por módulos de plataforma segura (TPM) junto con la capacidad de atestiguar el estado de los entornos de ejecución de confianza (TEE), como los enclaves de Intel(tm) Software Guard Extensions (SGX) y los enclaves de seguridad basada en virtualización (VBS).

La atestación es un proceso que se utiliza para demostrar que se ha creado correctamente una instancia de los archivos binarios de software en una plataforma de confianza. Así, los usuarios de confianza remotos pueden tener la seguridad de que solo se ejecuta el software previsto en el hardware de confianza. Azure Attestation consta de un servicio y un marco de trabajo unificados orientados al cliente para la atestación.

Azure Attestation utiliza paradigmas de seguridad de vanguardia, como la computación confidencial en Azure y la protección de inteligencia perimetral. Los clientes llevan tiempo solicitando la posibilidad de comprobar de forma independiente la ubicación de una máquina, la posición de una máquina virtual en esa máquina y el entorno en el que se ejecutan los enclaves en esa máquina virtual. Con Azure Attestation se podrán satisfacer estas y muchas otras solicitudes de los clientes.

Azure Attestation recibe la evidencia de entidades de proceso, las convierte en un conjunto de notificaciones, las valida con respecto a directivas configurables y genera pruebas criptográficas para aplicaciones basadas en notificaciones (por ejemplo, usuarios de confianza y autoridades de auditoría).

Este paquete se ha probado con Python 2.7, 3.6 a 3.9.

Para obtener una vista más completa de las bibliotecas de Azure, consulte la página de versión del SDK de Azure para Python.

Código | fuente Paquete (PyPI) | Documentación | de referencia de API Documentación del producto

Introducción

Requisitos previos

Suscripción a Azure. Para usar los servicios de Azure, incluido el servicio Azure Attestation, necesitará una suscripción. Si no tiene una cuenta de Azure existente, puede registrarse para obtener una evaluación gratuita o usar las ventajas de la suscripción de Visual Studio al crear una cuenta.
Una instancia de Azure Attestation existente o puede usar el "proveedor compartido" disponible en cada región de Azure. Si necesita crear una instancia de servicio de Azure Attestation, puede usar Azure Portal o la CLI de Azure.

Instalar el paquete

Instale la biblioteca cliente de Azure Attestation para Python con PyPI:

pip install azure-security-attestation

Autenticar el cliente

Para interactuar con el servicio Azure Attestation, deberá crear una instancia de la clase Cliente de atestación o Cliente de administración de atestación. Necesita un punto de conexión de atestación, que puede ver como "URI de atestación" en el portal y credenciales de cliente (id. de cliente, secreto de cliente, identificador de inquilino) para crear una instancia de un objeto de cliente.

La autenticación de credenciales de secreto de cliente se usa en esta sección de introducción, pero puede encontrar más formas de autenticarse con el paquete de identidad de Azure. Para usar el proveedor DefaultAzureCredential que se muestra a continuación, u otros proveedores de credenciales proporcionados con el SDK de Azure, debe instalar el paquete azure-identity:

pip install azure-identity

Creación y obtención de credenciales

Use el fragmento de código de la CLI de Azure siguiente para crear o obtener credenciales de secreto de cliente.

Cree una entidad de servicio y configure su acceso a los recursos de Azure:

az ad sp create-for-rbac -n <your-application-name> --skip-assignment

Salida:

{
    "appId": "generated-app-ID",
    "displayName": "dummy-app-name",
    "name": "http://dummy-app-name",
    "password": "random-password",
    "tenant": "tenant-ID"
}

Tome nota del objectId de la entidad de servicio.

az ad sp show --id <appId> --query objectId

Salida:

"<your-service-principal-object-id>"

Use las credenciales devueltas anteriores para establecer AZURE_CLIENT_ID (appId), AZURE_CLIENT_SECRET (contraseña) y variables de entorno de AZURE_TENANT_ID (inquilino). En el ejemplo siguiente se muestra una manera de hacerlo en PowerShell:
```
$Env:AZURE_CLIENT_ID="generated-app-ID"
$Env:AZURE_CLIENT_SECRET="random-password"
$Env:AZURE_TENANT_ID="tenant-ID"
```

Para más información sobre las API de identidad de Azure y cómo usarlas, consulte Biblioteca cliente de Identidad de Azure.

Conceptos clave

Hay cuatro familias principales de funcionalidades proporcionadas en este SDK de versión preliminar:

Atestación de enclave de SGX y TPM.
Validación y detección de certificados de firma de tokens de atestación MAA.
Administración de directivas de atestación.
Administración de certificados de administración de directivas de atestación (sí, administración de directivas).

El servicio Microsoft Azure Attestation se ejecuta en dos modos independientes: "Aislado" y "AAD". Cuando el servicio se ejecuta en modo "aislado", el cliente debe proporcionar información adicional más allá de sus credenciales de autenticación para comprobar que están autorizados para modificar el estado de una instancia de atestación.

Por último, cada región en la que el servicio Azure Attestation está disponible admite una instancia "compartida", que se puede usar para atestiguar enclaves SGX que solo necesitan verificación en la línea base de Azure (no hay ninguna directiva aplicada a la instancia compartida). La atestación de TPM no está disponible en la instancia compartida. Aunque la instancia compartida requiere autenticación de AAD, no tiene ninguna directiva de RBAC: ningún cliente con un token de portador de AAD válido puede atestiguar mediante la instancia compartida.

Atestación

La atestación de SGX o TPM es el proceso de validar la evidencia recopilada de un entorno de ejecución de confianza para asegurarse de que cumple la línea de base de Azure para ese entorno y las directivas definidas por el cliente aplicadas a ese entorno.

Validación y detección de certificados de firma de tokens del servicio de atestación

Una de las garantías operativas principales del servicio Azure Attestation es que el servicio funciona "operativamente fuera del TCB". En otras palabras, no hay ninguna manera de que un operador de Microsoft pueda alterar el funcionamiento del servicio o los datos dañados enviados desde el cliente. Para garantizar esta garantía, el núcleo del servicio de atestación se ejecuta en un enclave de Intel(tm) SGX.

Para permitir a los clientes comprobar que las operaciones se realizaron realmente dentro del enclave, la mayoría de las respuestas del servicio de atestación se codifican en un token web JSON, que está firmado por una clave contenida en el enclave del servicio de atestación.

Este token se firmará mediante un certificado de firma emitido por el servicio MAA para la instancia especificada.

Si la instancia de servicio MAA se ejecuta en una región donde el servicio se ejecuta en un enclave SGX, el certificado emitido por el servidor se puede comprobar mediante la API de oe_verify_attestation_certificate.

Administración de directivas

Cada instancia del servicio de atestación tiene aplicada una directiva que define criterios adicionales que el cliente ha definido.

Para obtener más información sobre las directivas de atestación, consulte Directiva de atestación.

Administración de certificados de administración de directivas

Cuando una instancia de atestación se ejecuta en modo "aislado", el cliente que creó la instancia proporcionará un certificado de administración de directivas en el momento en que se crea la instancia. Todas las operaciones de modificación de directivas requieren que el cliente firme los datos de la directiva con uno de los certificados de administración de directivas existentes. Las API de administración de certificados de administración de directivas permiten a los clientes "implementar" los certificados de administración de directivas.

Modo aislado y modo AAD

Cada instancia de servicio de Microsoft Azure Attestation funciona en modo "AAD" o en modo "Aislado". Cuando una instancia de MAA funciona en modo AAD, significa que el cliente que creó la instancia de atestación permite que Azure Active Directory y las directivas de control de acceso basado en roles de Azure comprueben el acceso a la instancia de atestación.

AttestationType

El servicio Azure Attestation admite la atestación de diferentes tipos de evidencia en función del entorno. Actualmente, MAA admite los siguientes entornos de ejecución de confianza:

OpenEnclave: un procesador Intel(tm) que ejecuta código en un enclave SGX donde se recopiló la evidencia de atestación mediante la API de oe_get_report o oe_get_evidence OpenEnclave.
SgxEnclave: procesador Intel(tm) que ejecuta código en un enclave SGX donde se recopiló la evidencia de atestación mediante el SDK de Intel SGX.
Tpm: un entorno de seguridad basada en virtualización en el que se usa el módulo de plataforma segura del procesador para proporcionar la evidencia de atestación.

Datos en tiempo de ejecución e Inittime

RuntimeData hace referencia a los datos que se presentan a la lógica de generación de citas de Intel SGX o a las oe_get_report/oe_get_evidence API. Si el autor de la llamada a la API de atestación proporcionó un runtime_data atributo, el servicio de Azure Attestation validará que los primeros 32 bytes del report_data campo del informe de presupuestos SGX/OE/evidencia de OE coincidan con el hash SHA256 de runtime_data.

Los datos de InitTime hacen referencia a los datos que se usan para configurar el enclave SGX que se está atestiguando.

Tenga en cuenta que los datos de InitTime no se admiten en máquinas virtuales de la serie DCsv2 de Azure.

Conceptos adicionales

Ejemplos

Creación de una instancia de cliente de atestación
Atestación de un enclave de SGX
Obtención de la directiva de atestación
Recuperación de certificados de validación de tokens
Creación de una instancia de cliente de atestación

Creación de una instancia de cliente

Crea una instancia del cliente de atestación en el URI endpoint.

attest_client = AttestationClient(
    endpoint=base_uri,
    credential=DefaultAzureCredential())

Obtención de la directiva de atestación

El set_policy método recupera la directiva de atestación del servicio. Las directivas de atestación se crean por tipo de atestación, el AttestationType parámetro define el tipo que se va a recuperar.

policy, token = attest_client.get_policy(AttestationType.SGX_ENCLAVE)
print('Instance SGX policy: ', policy)
print('Token: ', token)

Establecimiento de una directiva de atestación para un tipo de atestación especificado

Si la instancia del servicio de atestación se ejecuta en modo aislado, la API de set_policy debe proporcionar un certificado de firma (y una clave privada) que se puede usar para validar que el autor de la llamada está autorizado para modificar la directiva en la instancia de atestación. Si la instancia de servicio se ejecuta en modo AAD, el certificado de firma y la clave son opcionales.

En segundo plano, las API setPolicy crean un token web JSON basado en el documento de directiva y la información de firma que se envía al servicio de atestación.

policy_set_response = attest_client.set_policy(AttestationType.SGX_ENCLAVE,
    attestation_policy,
    signing_key=key,
    signing_certificate=signing_certificate)
new_policy, _ = attest_client.get_policy(AttestationType.SGX_ENCLAVE)
# `new_policy` will equal `attestation_policy`.

Si la instancia de servicio se ejecuta en modo AAD, la llamada a set_policy se puede simplificar:

policy_set_response = attest_client.set_policy(AttestationType.SGX_ENCLAVE,            
    attestation_policy)
# Now retrieve the policy which was just set.
new_policy, _ = attest_client.get_policy(AttestationType.SGX_ENCLAVE)

Los clientes deben poder comprobar que el documento de directiva de atestación no se modificó antes de que el enclave del servicio de atestación recibiera el documento de directiva.

Hay dos propiedades proporcionadas en PolicyResult que se pueden usar para comprobar que el servicio recibió el documento de directiva:

policy_signer : si la set_policy llamada incluía un certificado de firma, este será el certificado proporcionado en el momento de la set_policy llamada. Si no se estableció ningún firmante de directiva, será null.
policy_token_hash : este es el hash del token web JSON enviado al servicio.

Para comprobar el hash, los clientes pueden generar un token de directiva de atestación y comprobar el hash generado a partir de ese token:

from cryptography.hazmat.primitives import hashes

expected_policy = AttestationPolicyToken(
    attestation_policy,
    signing_key=key,
    signing_certificate=signing_certificate)
hasher = hashes.Hash(hashes.SHA256())
hasher.update(expected_policy.serialize().encode('utf-8'))
expected_hash = hasher.finalize()

# `expected_hash` will exactly match `policy_set_response.policy_token_hash`

Atestación del enclave de SGX

Use el método attest_sgx_enclave para atestar un enclave SGX.

Uno de los principales desafíos que los clientes tienen que interactuar con entornos cifrados es cómo asegurarse de que puede comunicarse de forma segura con el código que se ejecuta en el entorno ("código de enclave").

Una solución a este problema es lo que se conoce como "Versión de clave segura", que es un patrón que permite la comunicación segura con código de enclave.

Para implementar el patrón "Secure Key Release", el código de enclave genera una clave asimétrica efímera. A continuación, serializa la parte pública de la clave en algún formato (posiblemente una clave web JSON o PEM, o algún otro formato de serialización).

A continuación, el código de enclave calcula el valor SHA256 de la clave pública y lo pasa como entrada al código que genera una cita SGX (para OpenEnclave, que sería la oe_get_evidence o oe_get_report).

A continuación, el cliente envía la cita SGX y la clave serializada al servicio de atestación. El servicio de atestación validará la cita y garantizará que el hash de la clave esté presente en la cita y emitirá un "Token de atestación".

A continuación, el cliente puede enviar ese token de atestación (que contiene la clave serializada) a un "usuario de confianza" de terceros. A continuación, el usuario de confianza valida que el servicio de atestación creó el token de atestación y, por tanto, la clave serializada se puede usar para cifrar algunos datos mantenidos por el "usuario de confianza" para enviar al servicio.

En este ejemplo se muestra un patrón común de llamar al servicio de atestación para recuperar un token de atestación asociado a una solicitud.

En este ejemplo se supone que tiene un objeto existente AttestationClient que está configurado con el URI base para el punto de conexión. También se supone que tiene una cita SGX (quote) generada desde dentro del enclave de SGX que está atestiguando y "Datos en tiempo de ejecución" (runtime_data) a la que se hace referencia en la cita SGX.

response, token = attest_client.attest_sgx_enclave(quote, runtime_data=runtime_data)

En este momento, el atributo enclave_held_data en attestationResult contendrá el runtime_data binario de entrada.

El token ahora se pasa al "usuario de confianza". El usuario de confianza validará que el token lo emitió el servicio de atestación. A continuación, extrae la clave asimétrica del campo EnclaveHeldData. Después, el usuario de confianza cifrará sus datos de "clave" mediante la clave asimétrica y lo transmitirá de nuevo al enclave.

encrypted_data = send_token_to_relying_party(attestationResult.Token)

Ahora los datos cifrados se pueden pasar al enclave que pueden descifrar esos datos.

Puede encontrar información adicional sobre cómo realizar la validación de tokens de atestación en el ejemplo de atestación del servicio MAA.

Recuperación de certificados de token

Use get_signing_certificates para recuperar los certificados que se pueden usar para validar el token devuelto por el servicio de atestación.

signers = attest_client.get_signing_certificates()
for signer in signers:
    from cryptography.hazmat.backends import default_backend
    cert = cryptography.x509.load_pem_x509_certificate(signer.certificates[0].encode('ascii'), backend=default_backend())
    print('Cert  iss:', cert.issuer, '; subject:', cert.subject)

Solución de problemas

La mayoría de las operaciones del servicio de atestación generarán excepciones definidas en Azure Core. Las API del servicio de atestación producirán un HttpResponseError error con códigos de error útiles. Muchos de estos errores son recuperables.

try:
    response, _ = attest_client.attest_sgx_enclave(
        quote,
        runtime_data=AttestationData(runtime_data, is_json=False))
except HttpResponseError as ex:
    # Ignore invalid quote errors.
    if ex.error == "InvalidParameter":
        pass
}

Puede encontrar información adicional de solución de problemas para el servicio MAA aquí.

Pasos siguientes

Para obtener más información sobre el servicio microsoft Azure Attestation, consulte nuestra página de documentación.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para obtener más información, visite el sitio del Contrato de licencia de colaborador.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Consulte CONTRIBUTING.md para obtener más información sobre la compilación, las pruebas y la contribución a estas bibliotecas.

Envío de comentarios

Si encuentra algún error o tiene sugerencias, envíe un problema en la sección Problemas del proyecto.

Impresiones

Compartir a través de