Share via

Azure Attestation biblioteca cliente para JavaScript: 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 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).

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

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.

Vínculos principales:

Introducción

Entornos admitidos actualmente

Para más información, consulte la directiva de compatibilidad.

Prerrequisitos

  • Una suscripción de Azure
  • 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 @azure/attestation

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

npm install @azure/attestation

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 será el "URI de atestación" que se muestra en el portal o será uno de los proveedores de atestación compartidos. También necesitará credenciales de cliente para usar el cliente de administración de atestación o llamar a la attestTpm API. Las credenciales de cliente requieren (id. de cliente, secreto de cliente, identificador de inquilino) para crear una instancia de un objeto de cliente.

En esta sección de introducción, se autenticará mediante credenciales de secreto de cliente mediante el proveedor DefaultAzureCredential , pero ofrecemos más mecanismos de autenticación a través del paquete de @azure/identity . Para instalar el paquete de @azure/identity:

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 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 verificación en la línea base de Azure (no hay ninguna directiva aplicada al proveedor compartido). La atestación de TPM no está disponible en el proveedor compartido. 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 atributos principales: token y value. El token atributo contiene el token completo devuelto por el servicio de atestación, el value atributo 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. 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

Crea una instancia del cliente de atestación en el URI endpointmediante las credenciales predeterminadas de Azure (DefaultAzureCredential).

const credentials = new DefaultAzureCredential();
const client = new AttestationClient(endpoint, {credentials: credentials});

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

Si no llama a la attestTpm API, no es necesario proporcionar credenciales para acceder al cliente de atestación. Esto significa que un cliente se puede crear simplemente con:

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 atestación en el URI endpoint.

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

  const client = new AttestationAdministrationClient(endpoint, new DefaultAzureCredential());

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

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 de instancia que se va a recuperar.

const policyResult = await adminClient.getPolicy(attestationType);

// The text policy document is available in the `policyResult.body`
// property.

// The actual attestation token returned by the MAA service is available
// in `policyResult.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.

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

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 y certificados privados de administración de directivas.

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
  }
);

En segundo plano, las API setPolicy crean un token web JSON que contiene en el documento certificate de directiva y firman con el privateKey que se envía al servicio de atestación.

Si un cliente desea asegurarse de 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, puede usar las propiedades devueltas en el objct PolicyResult que se puede usar para comprobar que el servicio recibió el documento de directiva:

  • 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 estableció ningún firmante de directiva, será null.
  • policyTokenHash : este es el hash de la firma web JSON enviada al servicio para la API setPolicy.

Para comprobar el hash, los clientes pueden crear un token de directiva de atestación (una clase auxiliar que representa el token usado para establecer la directiva de atestación) y comprobar el hash generado a partir de ese token:

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

// Use your favorite SHA256 hash generator function to create a hash of the
// stringized JWS.
const expectedHash = generateSha256Hash(expectedPolicy.serialize());

// The hash returned in expectedHash should match the value in
// `setResult.body.policyTokenHash`.

Atestación de SGX y Open Enclave

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 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 de atestación para el punto de conexión. También se supone que tiene un informe de OpenEnclave (report) generado desde dentro del enclave SGX que está atestiguando y "Datos en tiempo de ejecución" (binaryRuntimeData) a los que se hace referencia en la cita SGX.

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

También es posible que el binaryRuntimeData enviado al servicio de atestación se interprete como datos JSON. En ese caso, el cliente debe especificar runTimeJson en la llamada API de atestación:

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

Del mismo modo, si usa el SDK de Intel para generar una "cita", puede validar la cita mediante:

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

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 getSigningCertificates para recuperar los certificados que se pueden usar para validar el token devuelto por el servicio de atestación. Tenga en cuenta que esta llamada crea un cliente con credenciales de Azure, que no es necesario si llama a las attestSgxEnclave API o attestOpenEnclave .

const credentials = new DefaultAzureCredential();
const client = new AttestationClient(endpoint, {credentials: credentials});

const attestationSigners = await client.getAttestationSigners();

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

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 RestError error con códigos de error útiles. Muchos de estos errores son recuperables.

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

Registro

La habilitación del registro puede ayudar a descubrir información útil sobre los 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 @azure/logger:

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

setLogLevel("info");

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, consulte los documentos del paquete @azure/logger.

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