Azure Attestation biblioteca cliente para .NET: versión 1.0.0

  • Artículo

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 posibilidad de atestiguar el estado de los entornos de ejecución de confianza (TEE), como los enclaves Software Guard Extensions de Intel® (SGX) y 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).

NOTA: Se trata de un SDK en versión preliminar para el servicio Microsoft Azure Attestation. Proporciona toda la funcionalidad esencial para acceder al servicio Azure Attestation, se debe considerar "tal cual" y está sujeta a cambios en el futuro, lo que puede interrumpir la compatibilidad con versiones anteriores.

Código | fuente Paquete (NuGet) | Documentación | de referencia de APIDocumentación del producto

Introducción

Requisitos previos

  • Suscripción a Azure. Para usar los servicios de Azure, incluido el servicio microsoft 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 Microsoft Azure Attestation para .NET con NuGet:

dotnet add package Azure.Security.Attestation --prerelease

Autenticar el cliente

Para interactuar con el servicio de Microsoft Azure Attestation, deberá crear una instancia de la clase Cliente de atestación o Cliente de administración de atestación. Necesita una dirección URL de instancia de atestación, que puede ver como "Nombre DNS" en el portal y credenciales de secreto 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 la 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:

dotnet add package 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:

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 Microsoft Azure Attestation está disponible admite una instancia "compartida", que se puede usar para atestiguar enclaves SGX que solo necesitan comprobació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.

El AttestationResponse objeto contiene dos propiedades principales: Token y Value. La Token propiedad contiene el token completo devuelto por el servicio de atestación, la Value propiedad contiene el cuerpo de la respuesta json Web Token.

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 Microsoft 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: procesador Intel(tm) que ejecuta código en un enclave SGX donde se recopiló la evidencia de atestación mediante OpenEnclave oe_get_report o oe_get_evidence api.
  • 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. El servicio Azure Attestation validará que los primeros 32 bytes del report_data campo del informe de presupuestos SGX/OE Report/OE Evidence coincidan con el hash SHA256 de RuntimeData.

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.

Seguridad para subprocesos

Garantizamos que todos los métodos de instancia de cliente sean seguros para subprocesos e independientes entre sí (guía). Esto garantiza que la recomendación de reutilizar instancias de cliente siempre es segura, incluso entre subprocesos.

Conceptos adicionales

Opciones | de cliente Acceso a la respuesta | Operaciones | de larga duraciónControl de errores | Diagnóstico | Burla | Duración del cliente

Ejemplos

Creación de una instancia de cliente

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

var options = new AttestationClientOptions();
return new AttestationClient(new Uri(endpoint), new DefaultAzureCredential(), options);

Obtención de la directiva de atestación

El GetPolicy 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.

var client = new AttestationAdministrationClient(new Uri(endpoint), new DefaultAzureCredential());

AttestationResponse<string> policyResult = await client.GetPolicyAsync(AttestationType.SgxEnclave);
string result = policyResult.Value;

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 setPolicy 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.

string attestationPolicy = "version=1.0; authorizationrules{=> permit();}; issuancerules{};";

X509Certificate2 policyTokenCertificate = new X509Certificate2(<Attestation Policy Signing Certificate>);
AsymmetricAlgorithm policyTokenKey = <Attestation Policy Signing Key>;

var setResult = client.SetPolicy(AttestationType.SgxEnclave, attestationPolicy, new AttestationTokenSigningKey(policyTokenKey, policyTokenCertificate));

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:

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

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

// The SetPolicyAsync API will create an AttestationToken signed with the TokenSigningKey to transmit the policy.
// To verify that the policy specified by the caller was received by the service inside the enclave, we
// verify that the hash of the policy document returned from the Attestation Service matches the hash
// of an attestation token created locally.
TokenSigningKey signingKey = new TokenSigningKey(<Customer provided signing key>, <Customer provided certificate>)
var policySetToken = new AttestationToken(
    BinaryData.FromObjectAsJson(new StoredAttestationPolicy { AttestationPolicy = attestationPolicy }),
    signingKey);

using var shaHasher = SHA256Managed.Create();
byte[] attestationPolicyHash = shaHasher.ComputeHash(Encoding.UTF8.GetBytes(policySetToken.Serialize()));

Debug.Assert(attestationPolicyHash.SequenceEqual(setResult.Value.PolicyTokenHash.ToArray()));

Atestación del enclave de SGX

Use el AttestSgxEnclave método para atestiguar 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 confiable 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 este tipo de comunicación 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 (binaryQuote) generada desde dentro del enclave de SGX que está atestiguando y "Datos en tiempo de ejecución" (runtimeData) a la que se hace referencia en la cita SGX.

// Collect quote and runtime data from an SGX enclave.
// For the "Secure Key Release" scenario, the runtime data is normally a serialized asymmetric key.
// When the 'quote' (attestation evidence) is created specify the SHA256 hash of the runtime data when
// creating the evidence.
//
// When the generated evidence is created, the hash of the runtime data is included in the
// secured portion of the evidence.
//
// The Attestation service will validate that the Evidence is valid and that the SHA256 of the RuntimeData
// parameter is included in the evidence.
AttestationResponse<AttestationResult> attestationResult = client.AttestSgxEnclave(new AttestationRequest
{
    Evidence = BinaryData.FromBytes(binaryQuote),
    RuntimeData = new AttestationData(BinaryData.FromBytes(binaryRuntimeData), false),
});

// At this point, the EnclaveHeldData field in the attestationResult.Value property will hold the
// contain the input binaryRuntimeData.

// The token is now passed to the "relying party". The relying party will validate that the token was
// issued by the Attestation Service. It then extracts the asymmetric key from the EnclaveHeldData field.
// The relying party will then Encrypt it's "key" data using the asymmetric key and transmits it back
// to the enclave.
var encryptedData = SendTokenToRelyingParty(attestationResult.Token);

// Now the encrypted data can be passed into the enclave which can decrypt that data.

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 GetSigningCertificatesAsync para recuperar los certificados que se pueden usar para validar el token devuelto por el servicio de atestación.

var client = GetAttestationClient();

IReadOnlyList<AttestationSigner> signingCertificates = (await client.GetSigningCertificatesAsync()).Value;

Solución de problemas

La mayoría de las operaciones del servicio de atestación producirán una excepción RequestFailedException en caso de error con códigos de error útiles. Muchos de estos errores son recuperables.

try
{
    AttestationResponse<AttestationResult> attestationResult = client.AttestSgxEnclave(new AttestationRequest
    {
        Evidence = BinaryData.FromBytes(binaryQuote),
        RuntimeData = new AttestationData(BinaryData.FromBytes(binaryRuntimeData), false),
    });
}
catch (RequestFailedException ex)
    when (ex.ErrorCode == "InvalidParameter")
    {
    // Ignore invalid quote errors.
    }

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.

Impresiones