Bibliothèque cliente Azure Attestation pour JavaScript - version 1.0.2

Le service Microsoft Azure Attestation (MAA) est une solution unifiée permettant de vérifier à distance la fiabilité d’une plateforme et l’intégrité des binaires qui s’y exécutent. Le service prend en charge l’attestation des plateformes soutenues par des modules de plateforme sécurisée (TPMs) ainsi que la possibilité d’attester de l’état des enclaves d’environnements d’exécution approuvés (TEE), comme les enclaves d’Intel(tm) Software Guard Extensions (SGX) et les enclaves VBS (Virtualization-based Security).

L’attestation est un processus permettant de démontrer que les binaires logiciels ont été correctement instanciés sur une plateforme approuvée. Les parties de confiance distantes peuvent alors avoir l’assurance que seuls des logiciels de ce type s’exécutent sur du matériel approuvé. Azure Attestation est un framework et un service orientés client unifiés pour l’attestation.

Azure Attestation permet des paradigmes de sécurité de pointe tels que l’informatique confidentielle Azure et la protection Intelligent Edge. Les clients ont demandé la possibilité de vérifier indépendamment l’emplacement d’une machine, la posture d’une machine virtuelle sur cette machine et l’environnement dans lequel les enclaves s’exécutent sur cette machine virtuelle. Azure Attestation permet à ces clients et à de nombreuses demandes supplémentaires.

Azure Attestation reçoit des preuves des entités de calcul, les transforme en un ensemble de revendications, les valide par rapport aux stratégies configurables et produit des preuves de chiffrement pour les applications basées sur des revendications (par exemple, les parties de confiance et les autorités d’audit).

Pour une vue plus complète des bibliothèques Azure, consultez la version Azure SDK TypeScript.

REMARQUE : Il s’agit d’un SDK de pré-version pour le service Microsoft Azure Attestation. Il fournit toutes les fonctionnalités essentielles pour accéder au service Azure Attestation, il doit être considéré comme «as-is» et est sujet à des modifications futures qui pourraient rompre la compatibilité avec les versions précédentes.

Liens clés :

Premiers pas

Environnements actuellement pris en charge

Pour plus d’informations, consultez notre de stratégie de support .

Prerequisites

  • Un abonnement Azure
  • Une instance Azure Attestation existante, ou vous pouvez utiliser le « fournisseur partagé » disponible dans chaque région Azure. Si vous devez créer une instance de service Azure Attestation, vous pouvez utiliser Portail Azure ou Azure CLI.

Installer le package @azure/attestation

Installez la bibliothèque cliente Microsoft Azure Attestation pour JavaScript avec NPM :

npm install @azure/attestation

Authentifier le client

Pour interagir avec le service Microsoft Azure Attestation, vous devrez créer une instance de la classe Attestation Client ou Attestation Administration Client. Vous avez besoin d’une URL d’instance d’attestation, qui sera soit l'« URI d’attestation » affichée dans le portail, soit l’un des fournisseurs d’attestation partagés. Vous aurez également besoin des identifiants client pour utiliser le client d’administration de l’attestation ou appeler l’API attestTpm . Les identifiants client nécessitent (id client, secret client, id locataire) pour instancier un objet client.

Dans cette section de démarrage, nous nous authentifierons en utilisant des identifiants secrets client via le fournisseur DefaultAzureCredential , mais nous proposons davantage de mécanismes d’authentification via le paquet @azure/identité . Pour installer le @azure/identity paquet :

npm install @azure/identity

Créer/obtenir des informations d’identification

Utilisez l’extrait de code Azure CLI ci-dessous afin de créer ou d'obtenir des informations d’identification de clé secrète client.

  • Créez un principal de service et configurez son accès aux ressources Azure :

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

    Sortie:

    {
      "appId": "generated-app-ID",
      "displayName": "dummy-app-name",
      "name": "http://dummy-app-name",
      "password": "random-password",
      "tenant": "tenant-ID"
    }
    
  • Prenez note de l’objectId du principal de service

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

    Sortie:

    "<your-service-principal-object-id>"
    
  • Utilisez les identifiants retournés ci-dessus pour définir les variables d’environnement AZURE_CLIENT_ID (appId), AZURE_CLIENT_SECRET (mot de passe) et AZURE_TENANT_ID (locataire). L’exemple suivant montre un moyen d’effectuer cette opération dans PowerShell :

    $Env:AZURE_CLIENT_ID="generated-app-ID"
    $Env:AZURE_CLIENT_SECRET="random-password"
    $Env:AZURE_TENANT_ID="tenant-ID"

Pour plus d’informations sur les API Azure Identity et comment les utiliser, voir Bibliothèque client Azure Identity

Concepts clés

Ce SDK de preview propose quatre grandes familles de fonctionnalités :

Le service Microsoft Azure Attestation s’exécute en deux modes distincts : « Isolé » et « AAD ». Lorsque le service s’exécute en mode « isolé », le client doit fournir des informations supplémentaires au-delà de ses informations d’identification d’authentification pour vérifier qu’il est autorisé à modifier l’état d’une instance d’attestation.

Enfin, chaque région où le service Microsoft Azure Attestation est disponible supporte une instance « partagée », qui peut être utilisée pour attester les enclaves SGX qui ne nécessitent que vérification par rapport à la base Azure (aucune politique n’est appliquée au fournisseur partagé). L’attestation TPM n’est pas disponible dans le fournisseur partagé. Bien que l’instance partagée nécessite une authentification AAD, elle ne dispose d’aucune politique RBAC – tout client disposant d’un jeton porteur AAD valide peut attester l’utilisation de l’instance partagée.

Attestation

L’attestation SGX ou TPM est le processus de validation des preuves collectées à partir d’un environnement d’exécution approuvé pour s’assurer qu’elle répond à la fois à la base de référence Azure pour cet environnement et aux stratégies définies par le client appliquées à cet environnement.

Découverte et validation du certificat de signature du jeton du service d’attestation

L’une des principales garanties opérationnelles du service Azure Attestation est que le service fonctionne « opérationnellement depuis le TCB ». En d’autres termes, il n’y a aucun moyen qu’un opérateur Microsoft puisse altuer le fonctionnement du service, ni corrompre les données envoyées par le client. Pour garantir cette garantie, le noyau du service d’attestation fonctionne dans une enclave Intel(tm) SGX.

Pour permettre aux clients de vérifier que les opérations ont effectivement été effectuées à l’intérieur de l’enclave, la plupart des réponses du Service d’Attestation sont encodées dans un jeton Web JSON, qui est signé par une clé contenue dans l’enclave du service d’attestation.

Ce jeton sera signé par un certificat de signature émis par le service MAA pour l’instance spécifiée.

Si l’instance de service MAA fonctionne dans une région où le service s’exécute dans une enclave SGX, alors le certificat émis par le serveur peut être vérifié à l’aide de l’API oe_verify_attestation_certificate.

L’objet AttestationResponse contient deux attributs principaux : token et value. L’attribut token contient le jeton complet retourné par le service d’attestation, l’attribut value contient le corps de la réponse du JSON Web Token.

Gestion des stratégies

Chaque instance de service d’attestation a une stratégie appliquée à celle-ci qui définit des critères supplémentaires que le client a définis.

Pour plus d’informations sur les stratégies d’attestation, consultez Stratégie d’attestation

Gestion des certificats de gestion des politiques

Lorsqu’une instance d’attestation fonctionne en mode « Isolé », le client qui l’a créée aura fourni un certificat de gestion de politique au moment de sa création. Toutes les opérations de modification de politique exigent que le client signe les données de politique avec l’un des certificats de gestion de politique existants. Les API de gestion des certificats de gestion des politiques permettent aux clients de « rouler » les certificats de gestion des politiques.

Mode isolé et mode AAD

Chaque instance de service Microsoft Azure Attestation fonctionne soit en mode « AAD », soit en mode « Isolé ». Lorsqu’une instance MAA fonctionne en mode AAD, cela signifie que le client ayant créé l’instance d’attestation permet aux politiques de contrôle d’accès basées sur Azure Active Directory et Azure Role Base pour vérifier l’accès à l’instance d’attestation.

AttestationType

Le service Microsoft Azure Attestation supporte l’attestation de différents types de preuves selon l’environnement. Actuellement, MAA supporte les environnements d’exécution de confiance suivants :

  • OpenEnclave - Un processeur Intel(tm) exécutant du code dans une SGX Enclave où les preuves d’attestation ont été collectées via OpenEnclave oe_get_report ou oe_get_evidence API.
  • SgxEnclave - Un processeur Intel(tm) exécutant du code dans une enclave SGX où les preuves d’attestation ont été collectées à l’aide du SDK Intel SGX.
  • Tpm - Un environnement de sécurité basé sur la virtualisation où le module de plateforme de confiance du processeur est utilisé pour fournir les preuves d’attestation.

Données d’exécution et données d’initiation

RuntimeData désigne des données présentées à la logique de génération de citations Intel SGX ou aux oe_get_report/oe_get_evidence API. Si l’appelant de l’API attest a fourni un runtime_data attribut, le service Azure Attestation validera que les 32 premiers octets du report_data champ dans le SGX Quote/OE Report/OE Evidence correspondent au hachage SHA256 du runtime_data.

Les données InitTime désignent les données utilisées pour configurer l’enclave SGX attestée.

Notez que les données InitTime ne sont pas prises en charge sur les machines virtuelles Azure DCsv2-Series.

Concepts supplémentaires

Examples

Créer une instance client

Crée une instance du client d’attestation à l’URI endpoint, en utilisant les identifiants Azure par défaut (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 vous n’appelez pas l’API attestTpm , vous n’avez pas besoin de fournir des identifiants pour accéder au client d’attestation. Cela signifie qu’un client peut être créé simplement avec :

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

Crée une instance du client d’administration d’attestation à l’adresse URI endpoint.

Notez que le client d’administration nécessite des identifiants 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);

Obtenir la politique d’attestation

La getPolicy méthode récupère la politique d’attestation depuis le service. Les politiques d’attestation sont instanciées selon chaque type d’attestation, le AttestationType paramètre définit le type d’instance à récupérer.

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

Définir une politique d’attestation pour un type d’attestation spécifié

Si l’instance du service d’attestation fonctionne en mode isolé, l’API set_policy doit fournir un certificat de signature (et une clé privée) qui peuvent être utilisés pour valider que l’appelant est autorisé à modifier la politique sur l’instance d’attestation. Si l’instance de service fonctionne en mode AAD, alors le certificat de signature et la clé sont optionnels.

Si l’instance de service fonctionne en mode AAD, l’appel à setPolicy est comme prévu :

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 l’instance de service fonctionne en mode isolé, l’appel à setPolicy exige que le client puisse prouver qu’il a accès à l’une des clés privées et certificats de gestion de politiques.

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

Sous le couvert, les API setPolicy créent un jeton Web JSON contenu dans le document certificate de politique et signé avec celui privateKey , qui est ensuite envoyé au service d’attestation.

Si un client souhaite s’assurer que le document de politique d’attestation n’a pas été modifié avant sa réception par l’enclave du service d’attestation, il peut utiliser les propriétés retournées dans l’objectif PolicyResult qui peut être utilisé pour vérifier que le service a reçu le document de politique :

  • policySigner - Si l’appel setPolicy comprenait un certificate, cette valeur sera le certificat fourni au moment de l’appel setPolicy . Si aucun signataire de politique n’a été défini, cela sera nul.
  • policyTokenHash - il s’agit du hash de la signature web JSON envoyée au service pour l’API setPolicy.

Pour vérifier le hachage, les clients peuvent créer un jeton de politique d’attestation (une classe d’aide représentant le jeton utilisé pour définir la politique d’attestation) et vérifier le hachage généré à partir de ce jeton :

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

Attester SGX et Open Enclave

Utilisez la attestSgxEnclave méthode pour attester une enclave SGX.

L’un des principaux défis des clients lorsqu’ils interagissent avec des environnements chiffrés est de savoir comment s’assurer de pouvoir communiquer en toute sécurité avec le code qui s’exécute dans l’environnement (« code enclave »).

Une solution à ce problème est ce que l’on appelle « Secure Key Release », un schéma permettant une communication sécurisée avec le code de l’enclave.

Pour implémenter le modèle « Secure Key Release », le code de l’enclave génère une clé asymétrique éphémère. Il sérialise ensuite la partie publique de la clé vers un format (éventuellement une clé Web JSON, un PEM, ou un autre format de sérialisation).

Le code de l’enclave calcule ensuite la valeur SHA256 de la clé publique et la transmet en entrée au code qui génère un SGX Quote (pour OpenEnclave, ce serait le oe_get_evidence ou oe_get_report).

Le client envoie ensuite le devis SGX et la clé sérialisée au service d’attestation. Le service d’attestation validera le devis, veillera à ce que le hash de la clé soit présent dans le devis, puis émettra un « jeton d’attestation ».

Le client peut alors envoyer ce jeton d’attestation (qui contient la clé sérialisée) à une « partie de confiance » tierce. La partie dépendant valide alors que le jeton d’attestation a été créé par le service d’attestation, et ainsi la clé sérialisée peut être utilisée pour chiffrer certaines données détenues par la « partie détenant » à envoyer au service.

Cet exemple montre un schéma courant consistant à appeler le service d’attestation pour récupérer un jeton d’attestation associé à une requête.

Cet exemple suppose que vous avez un objet existant AttestationClient configuré avec l’URI Attest pour votre point de terminaison. Il suppose également que vous disposez d’un rapport OpenEnclave (report) généré à partir de l’enclave SGX que vous attestez, et de « Runtime Data » (binaryRuntimeData) qui est référencée dans le devis 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,
});

Il est également possible que l’envoi binaryRuntimeData envoyé au service d’attestation soit destiné à être interprété comme une donnée JSON. Dans ce cas, le client doit spécifier runTimeJson dans l’appel API attest :

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 même, si vous utilisez le SDK Intel pour générer un « devis », vous pouvez valider le devis en utilisant :

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

Des informations supplémentaires sur la manière d’effectuer la validation des jetons d’attestation sont disponibles dans l’exemple d’attestation du service MAA.

Récupérer des certificats de jeton

Utilisez getSigningCertificates pour récupérer les certificats qui peuvent être utilisés pour valider le jeton retourné par le service d’attestation. Notez que cet appel crée un client avec des identifiants Azure, ce qui n’est pas nécessaire si vous appelez les attestSgxEnclave API 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 plupart des opérations de service Attestation susciteront des exceptions définies dans Azure Core. Les API du service d’attestation afficheront un RestError échec de l’on avec des codes d’erreur utiles. La plupart de ces erreurs sont récupérables.

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

L’activation de la journalisation peut vous aider à découvrir des informations utiles sur les échecs. Pour afficher un journal des requêtes et réponses HTTP, définissez la variable d’environnement AZURE_LOG_LEVEL sur info. Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans la @azure/logger:

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

setLogLevel("info");

Pour obtenir des instructions plus détaillées sur l’activation des journaux, vous pouvez consulter la documentationdu package @azure/enregistreur d’événements.

Des informations supplémentaires de dépannage pour le service MAA sont disponibles ici

Étapes suivantes

Pour plus d’informations sur le service Microsoft Azure Attestation, consultez notre page de documentation.

Contributing

Ce projet accueille les contributions et suggestions. La plupart des contributions vous obligent à accepter un contrat de licence contributeur (CLA) déclarant que vous avez le droit, et en fait, de nous accorder les droits d’utilisation de votre contribution. Pour plus de détails, consultez le site du contrat de licence des contributeurs.

Lorsque vous envoyez une demande de tirage( pull request), un bot CLA détermine automatiquement si vous devez fournir un CLA et décorer correctement la demande de tirage (par exemple, étiquette, commentaire). Suivez simplement les instructions fournies par le bot. Vous n’aurez besoin de le faire qu’une seule fois sur tous les dépôts à l’aide de notre CLA.

Ce projet a adopté le Code de conduite Open Source Microsoft. Pour plus d’informations, consultez la FAQ sur le Code de conduite ou contactez-nous opencode@microsoft.com pour toute question ou commentaire supplémentaire.

Consultez CONTRIBUTING.md pour plus de détails sur la création, les tests et la contribution à ces bibliothèques.

Fournir des commentaires

Si vous rencontrez des bugs ou avez des suggestions, veuillez signaler un problème dans la section Problèmes du projet.