Biblioteca cliente Azure Attestation para JavaScript - versión 1.0.2

El servicio Microsoft Azure Attestation (MAA) es una solución unificada para verificar remotamente la fiabilidad de una plataforma y la integridad de los binarios que se ejecutan en su interior. 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 entornos de ejecución de confianza (TEE), como enclaves de Intel(tm) Software Guard Extensions (SGX) y enclaves de seguridad basada en virtualización (VBS).

La atestación es un proceso que se utiliza para demostrar que los archivos binarios de software se han instanciado correctamente 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 permite paradigmas de seguridad de vanguardia, como la computación confidencial de Azure y la protección de Intelligent Edge. Los clientes han estado solicitando la capacidad de comprobar de forma independiente la ubicación de una máquina, la posición de una máquina virtual (VM) en esa máquina y el entorno en el que se ejecutan enclaves en esa máquina virtual. Azure Attestation permitirá estas y muchas solicitudes de clientes adicionales.

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

Para una vista más completa de las bibliotecas de Azure, consulte la versión de typescript de Azure SDK.

NOTA: Este es un SDK de vista previa para el servicio Microsoft Azure Attestation. Proporciona toda la funcionalidad esencial para acceder al servicio Azure Attestation, debe considerarse 'as-is' y está sujeto a cambios futuros que puedan romper la compatibilidad con versiones anteriores.

Vínculos clave:

Cómo empezar

Entornos admitidos actualmente

Consulte nuestra de directiva de soporte técnico de para obtener más información.

Prerequisites

  • Un de suscripción de Azure de
  • Una instancia de Azure Attestation existente, o puedes usar el "proveedor compartido" disponible en cada región de Azure. Si necesitas crear una instancia de servicio de Azure Attestation, puedes utilizar Azure Portal o CLI de Azure.

Instalación del paquete @azure/attestation

Instale la biblioteca cliente Microsoft Azure Attestation para JavaScript con NPM:

npm install @azure/attestation

Autenticar el cliente

Para interactuar con el servicio Microsoft Azure Attestation, deberá crear una instancia de la clase Cliente de Attestation o Cliente de Administración de Attestation. Necesitas una URL de instancia de atestacion, que será o bien el "Attest URI" mostrado en el portal, o será uno de los proveedores compartidos de atestacion. También necesitará credenciales de cliente para utilizar el Cliente de Administración de Atestados o para llamar a la attestTpm API. Las credenciales de cliente requieren (id de cliente, secreto de cliente, id de inquilino) para instanciar un objeto cliente.

En esta sección de inicio, nos autenticaremos usando credenciales secretas de cliente a través del proveedor DefaultAzureCredential , pero ofrecemos más mecanismos de autenticación a través del paquete @azure/identity . Para instalar el @azure/identity paquete:

npm 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 secretas 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>"
    
  • Utilice las credenciales devueltas arriba para establecer las variables de entorno AZURE_CLIENT_ID (appId), AZURE_CLIENT_SECRET (contraseña) y AZURE_TENANT_ID (tenant). 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 APIs de Azure Identity y cómo utilizarlas, consulte la biblioteca cliente de Azure Identity

Conceptos clave

Este SDK de vista previa ofrece cuatro familias principales de funcionalidades:

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.

Finalmente, cada región en la que está disponible el servicio Microsoft Azure Attestation soporta una instancia "compartida", que puede usarse para atestar enclaves SGX que solo necesitan verificación contra la línea base de Azure (no se aplican políticas al proveedor compartido). La certificación TPM no está disponible en el proveedor compartido. Aunque la instancia compartida requiere autenticación AAD, no tiene políticas RBAC: cualquier cliente con un token portador AAD válido puede dar fe de usar la instancia compartida.

Attestation

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 base de Azure para ese entorno y las directivas definidas por el cliente aplicadas a ese entorno.

Descubrimiento y validación del certificado de firma de tokens del servicio de atestación

Una de las garantías operativas fundamentales del Azure Attestation Service es que el servicio opera "operativamente desde el TCB". En otras palabras, no hay forma de que un operador de Microsoft pueda manipular el funcionamiento del servicio o corromper datos enviados desde el cliente. Para garantizar esta garantía, el núcleo del servicio de atestación se ejecuta en un enclave Intel(tm) SGX.

Para permitir que los clientes verifiquen 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, firmado por una clave almacenada dentro del enclave del servicio de atestacion.

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

Si la instancia del servicio MAA se ejecuta en una región donde el servicio se ejecuta en un enclave SGX, entonces el certificado emitido por el servidor puede verificarse usando la API oe_verify_attestation_certificate.

El AttestationResponse objeto contiene dos atributos principales: token y value. El token atributo contiene el token completo devuelto por el servicio de atestacion, el value atributo contiene el cuerpo de la respuesta del JSON Web Token.

Gestió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.

Gestión de certificados de Gestión de Políticas

Cuando una instancia de atestación se ejecuta en modo "Aislado", el cliente que creó la instancia habrá proporcionado un certificado de gestión de políticas en el momento en que se crea la instancia. Todas las operaciones de modificación de políticas requieren que el cliente firme los datos de la política con uno de los certificados de gestión de políticas existentes. Las APIs de Gestión de Certificados de Gestión de Políticas permiten a los clientes "rollar" los certificados de gestión de políticas.

Modo aislado y modo AAD

Cada instancia del servicio Microsoft Azure Attestation opera en modo "AAD" o modo "Aislado". Cuando una instancia MAA está operando en modo AAD, significa que el cliente que creó la instancia de atestación permite Azure Active Directory y Azure políticas de control de acceso basadas en roles para verificar el acceso a la instancia de atestación.

AttestationType

El servicio Microsoft Azure Attestation soporta la certificación de diferentes tipos de evidencia según el entorno. Actualmente, MAA soporta los siguientes entornos de Ejecución Confiable:

  • OpenEnclave: un procesador Intel(tm) que ejecuta código en un enclave SGX donde la evidencia de atestación se recopiló utilizando OpenEnclave oe_get_report o oe_get_evidence API.
  • SgxEnclave: Un procesador Intel(tm) que ejecuta código en un enclave SGX donde se recopiló la evidencia de atestación utilizando el Intel SGX SDK.
  • Tpm - Un entorno de seguridad basado en virtualización donde se utiliza el Módulo de Plataforma de Confianza del procesador para proporcionar la evidencia de atestación.

Datos de ejecución y datos de inicio

RuntimeData se refiere a datos que se presentan a la lógica de generación de cotizaciones Intel SGX o a las oe_get_report/oe_get_evidence APIs. Si el llamador a la API attest proporcionó un runtime_data atributo, el servicio Azure Attestation validará que los primeros 32 bytes del report_data campo en SGX Quote/OE Report/OE Evidence coinciden con el hash SHA256 de la runtime_data.

Los datos InitTime se refieren a datos que se utilizan para configurar el enclave SGX que se está atestando.

Tenga en cuenta que los datos InitTime no están soportados en máquinas virtuales Azure DCsv2-Series.

Conceptos adicionales

Examples

Crear instancia cliente

Crea una instancia del Cliente de Atestación en URI endpoint, utilizando las credenciales predeterminadas de Azure (DefaultAzureCredential).

import { DefaultAzureCredential } from "@azure/identity";
import { AttestationClient } from "@azure/attestation";

const endpoint = "https://<attestation-instance>.<region>.attest.azure.net";
const credentials = new DefaultAzureCredential();
const client = new AttestationClient(endpoint, credentials);

// Retrieve the set of attestation policy signers from the attestation client.
const attestationSigners = await client.getAttestationSigners();

Si no estás llamando a la attestTpm API, no necesitas proporcionar credenciales para acceder al cliente de atestacion. Esto significa que un cliente puede crearse simplemente con:

import { AttestationClient } from "@azure/attestation";

const endpoint = "https://<attestation-instance>.<region>.attest.azure.net";
const client = new AttestationClient(endpoint);

// Retrieve the set of attestation policy signers from the attestation client.
const attestationSigners = await client.getAttestationSigners();

Crea una instancia del Cliente de Administración de Atestados en URI endpoint.

Tenga en cuenta que el cliente de administración requiere credenciales de Azure.

import { AttestationAdministrationClient, KnownAttestationType } from "@azure/attestation";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = "https://<attestation-instance>.<region>.attest.azure.net";
const client = new AttestationAdministrationClient(endpoint, new DefaultAzureCredential());

// Retrieve the SGX policy from the specified attestation instance.
const policyResponse = await client.getPolicy(KnownAttestationType.SgxEnclave);

Obtener la política de atestación

El getPolicy método recupera la política de atestación del servicio. Las políticas de atestación se instancian por tipo de atestación; el AttestationType parámetro define el tipo de instancia a recuperar.

import { AttestationAdministrationClient, KnownAttestationType } from "@azure/attestation";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = "https://<attestation-instance>.<region>.attest.azure.net";
const client = new AttestationAdministrationClient(endpoint, new DefaultAzureCredential());

const policyResponse = await client.getPolicy(KnownAttestationType.OpenEnclave);

Establecer una política 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 pueda usarse para validar que el llamante está autorizado a modificar la política en la instancia de atestacion. Si la instancia de servicio se ejecuta en modo AAD, entonces el certificado de firma y la clave son opcionales.

Si la instancia de servicio se ejecuta en modo AAD, la llamada a setPolicy es la esperada:

import { AttestationAdministrationClient, KnownAttestationType } from "@azure/attestation";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = "https://<attestation-instance>.<region>.attest.azure.net";
const client = new AttestationAdministrationClient(endpoint, new DefaultAzureCredential());

const newPolicy = `<New Attestation Policy>`;

// Set the new attestation policy. Set the policy as an unsecured policy.
const setPolicyResult = await client.setPolicy(KnownAttestationType.SgxEnclave, newPolicy);

Si la instancia de servicio se ejecuta en modo aislado, la llamada a setPolicy requiere que el cliente pueda demostrar que tiene acceso a una de las claves privadas y certificados de gestión de políticas.

import { AttestationAdministrationClient, KnownAttestationType } from "@azure/attestation";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = "https://<attestation-instance>.<region>.attest.azure.net";
const client = new AttestationAdministrationClient(endpoint, new DefaultAzureCredential());

const newPolicy = `<New Policy Document>`;

// Set the new attestation policy. Set the policy as an secured policy.
const privateKey = "<Retrieve isolated mode private key from storage>";
const certificate = "<Retrieve certificate associated with that private key>";

const setPolicyResult = await client.setPolicy(KnownAttestationType.OpenEnclave, newPolicy, {
  privateKey: privateKey,
  certificate: certificate,
});

Bajo las cubiertas, las APIs setPolicy crean un token web JSON que contiene el documento certificate de política y está firmado con él privateKey , que luego se envía al servicio de atestacion.

Si un cliente desea asegurarse de que el documento de política de atestación no fue modificado antes de que el enclave del servicio de atestación lo recibiera, puede utilizar las propiedades devueltas en el objetivo PolicyResult que puede usarse para verificar que el servicio recibió el documento de política:

  • policySigner - Si la setPolicy llamada incluía un certificate, este valor será el certificado proporcionado en el momento de la setPolicy llamada. Si no se ha establecido ningún firmante de política, esto será nulo.
  • policyTokenHash - este es el hash de la firma web JSON enviada al servicio para la API setPolicy.

Para verificar el hash, los clientes pueden crear un token de política de atestación (una clase auxiliar que representa el token utilizado para establecer la política de atestacion) y verificar el hash generado a partir de ese token:

import { createAttestationPolicyToken } from "@azure/attestation";
import { createHash } from "node:crypto";

// Set the new attestation policy. Set the policy as an secured policy.
const privateKey = "<Retrieve isolated mode private key from storage>";
const certificate = "<Retrieve certificate associated with that private key>";

const expectedPolicy = createAttestationPolicyToken(`<Policy Document>`, privateKey, certificate);

// Use your favorite SHA256 hash generator function to create a hash of the stringified JWS.
const expectedHash = createHash("sha256").update(expectedPolicy.serialize()).digest("hex");

Attest SGX y Open Enclave

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

Uno de los principales retos que tienen los clientes al interactuar con entornos cifrados es cómo garantizar que se puede comunicar 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 "Secure Key Release", que es un patrón que permite la comunicación segura con código del enclave.

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

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

El cliente envía entonces la cotización SGX y la clave serializada al servicio de atestacion. El servicio de atestación validará la cotización y se asegurará de que el hash de la clave esté presente en la cotización y emitirá un "Token de Atestación".

El cliente puede entonces enviar ese Token de Atestación (que contiene la clave serializada) a una "parte confiable" de terceros. La parte que confia valida entonces que el token de atestación fue creado por el servicio de atestación y, por tanto, la clave serializada puede usarse para cifrar algunos datos en poder de la "parte confiada" para enviar al servicio.

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

Este ejemplo asume que tienes un objeto existente AttestationClient configurado con el URI Attest para tu endpoint. También asume que tienes un informe OpenEnclave (report) generado dentro del enclave SGX que estás dando la prueba, y "Datos de Ejecución" (binaryRuntimeData) que se menciona en la cotización SGX.

import { DefaultAzureCredential } from "@azure/identity";
import { AttestationClient } from "@azure/attestation";

const endpoint = "https://<attestation-instance>.<region>.attest.azure.net";
const credentials = new DefaultAzureCredential();
const client = new AttestationClient(endpoint, credentials);

const report = new Uint8Array(0); // Report data from the enclave.
const binaryRuntimeData = new Uint8Array(0); // Runtime data from the enclave.

const attestationResult = await client.attestOpenEnclave(report, {
  runTimeData: binaryRuntimeData,
});

También es posible que el binaryRuntimeData envío enviado al servicio de atestación esté destinado a interpretarse como datos JSON. En ese caso, el cliente debe especificar runTimeJson en la llamada de API de atestamiento:

import { DefaultAzureCredential } from "@azure/identity";
import { AttestationClient } from "@azure/attestation";

const endpoint = "https://<attestation-instance>.<region>.attest.azure.net";
const credentials = new DefaultAzureCredential();
const client = new AttestationClient(endpoint, credentials);

const report = new Uint8Array(0); // Report data from the enclave.
const binaryRuntimeData = new Uint8Array(0); // Runtime JSON data from the enclave.

const attestationResult = await client.attestOpenEnclave(report, {
  runTimeJson: binaryRuntimeData,
});

De manera similar, si usas el Intel SDK para generar una "cotización", puedes validar la cotización usando:

import { DefaultAzureCredential } from "@azure/identity";
import { AttestationClient } from "@azure/attestation";

const endpoint = "https://<attestation-instance>.<region>.attest.azure.net";
const credentials = new DefaultAzureCredential();
const client = new AttestationClient(endpoint, credentials);

const quote = new Uint8Array(0); // Quote data.
const binaryRuntimeData = new Uint8Array(0); // Runtime JSON data from the enclave.

const attestationResult = await client.attestSgxEnclave(quote, {
  runTimeData: binaryRuntimeData,
});

Información adicional sobre cómo realizar la validación de tokens de atestación puede encontrarse en el Ejemplo de Atestación de Servicio MAA.

Recuperación de certificados de token

Úsase getSigningCertificates para recuperar los certificados que pueden usarse para validar el token devuelto desde el servicio de atestacion. Tenga en cuenta que esta llamada crea un cliente con credenciales de Azure, que no es necesario si está llamando a las attestSgxEnclave APIs de OR attestOpenEnclave

import { DefaultAzureCredential } from "@azure/identity";
import { AttestationClient } from "@azure/attestation";

const endpoint = "https://<attestation-instance>.<region>.attest.azure.net";
const credentials = new DefaultAzureCredential();
const client = new AttestationClient(endpoint, credentials);

const attestationSigners = await client.getAttestationSigners();

console.log(`There are ${attestationSigners.length} signers`);

Troubleshooting

La mayoría de las operaciones del servicio de Attestation generarán excepciones definidas en Azure Core. Las APIs del servicio de atestación mostrarán un RestError fallo de encendido con códigos de error útiles. Muchos de estos errores son recuperables.

import { DefaultAzureCredential } from "@azure/identity";
import { AttestationClient } from "@azure/attestation";

const endpoint = "https://<attestation-instance>.<region>.attest.azure.net";
const credentials = new DefaultAzureCredential();
const client = new AttestationClient(endpoint, credentials);

const openEnclaveReport = new Uint8Array(0); // Open enclave report data

try {
  await client.attestSgxEnclave(openEnclaveReport);
} catch (error) {
  console.log(`Exception thrown for invalid request: ${error.message}`);
}

Logging

Habilitar el registro puede ayudar a descubrir información útil sobre errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la variable de entorno AZURE_LOG_LEVEL en info. Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel en el @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, puede consultar los documentos del paquete de @azure/registrador.

Aquí se puede encontrar información adicional para la resolución de problemas del servicio MAA

Pasos siguientes

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

Contributing

Este proyecto da la bienvenida a las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia de colaborador (CLA) declarando que tiene derecho a, y en realidad, concedanos los derechos para usar su contribución. Para más detalles, visite el sitio del Acuerdo de Licencia de Colaborador.

Al enviar una solicitud de incorporación de cambios, un bot CLA determinará automáticamente si necesita proporcionar un CLA y decorar la solicitud de incorporación de cambios de forma adecuada (por ejemplo, etiqueta, comentario). Solo tiene que seguir las instrucciones proporcionadas por el bot. Solo tendrá que hacerlo una vez en todos los repositorios mediante nuestro CLA.

Este proyecto ha adoptado el código de conducta de código abierto de Microsoft. Para más información, consulte las Preguntas frecuentes sobre el Código de Conducta o contacte opencode@microsoft.com con cualquier pregunta o comentario adicional.

Consulte CONTRIBUTING.md para más detalles sobre la construcción, prueba y contribución a estas bibliotecas.

Proporcionar comentarios

Si encuentra algún error o tiene sugerencias, por favor presente un problema en la sección de Problemas del proyecto.