Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
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
- Versions LTS de Node.js
- Dernières versions de Safari, Chrome, Edge et Firefox.
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-assignmentSortie:
{ "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 objectIdSortie:
"<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 :
- Attestation SGX et TPM enclave.
- Découverte et validation du certificat de signature du jeton d’attestation MAA.
- Gestion des politiques d’attestation.
- Gestion des politiques d’attestation gestion des certificats (oui, gestion des politiques).
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_reportouoe_get_evidenceAPI. - 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 d’attestation
- Attester l’existence d’une enclave SGX
- Obtenir la politique d’attestation
- Récupérer les certificats de validation des jetons
- Créer une instance client d’attestation
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’appelsetPolicycomprenait uncertificate, cette valeur sera le certificat fourni au moment de l’appelsetPolicy. 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
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.
Projets connexes
Azure SDK for JavaScript