Partager via

bibliothèque cliente Azure Attestation pour JavaScript - version 1.0.0

  • Article

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 fichiers binaires qui s’y exécutent. Le service prend en charge l’attestation des plateformes soutenues par des modules de plateforme sécurisée (TPM) ainsi que la possibilité d’attester de l’état des environnements d’exécution approuvés (TEE), tels que les enclaves d’extensions SGX (Software Guard Extensions) Intel(tm) 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 de périphérie intelligente. Les clients ont demandé à pouvoir vérifier indépendamment la localisation d’un ordinateur, la posture d’une machine virtuelle sur cet ordinateur et l’environnement dans lequel les enclaves s’exécutent sur cette machine virtuelle. Azure Attestation permet de répondre à ces demandes des clients et à bien d’autres.

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

Pour obtenir une vue plus complète des bibliothèques Azure, consultez la version typescript du Kit de développement logiciel (SDK) Azure.

REMARQUE : Il s’agit d’un KIT de développement logiciel (SDK) en 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 « tel quel » et est sujet à des modifications à l’avenir qui risquent d’interrompre la compatibilité avec les versions précédentes.

Liens clés :

Prise en main

Environnements actuellement pris en charge

Pour plus d’informations, consultez notre politique de support .

Prérequis

  • 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 le portail Azure ou Azure CLI.

Installez 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 devez créer une instance de la classe Client d’attestation ou Client d’administration d’attestation. Vous avez besoin d’une URL d’instance d’attestation, qui sera soit « URI d’attestation » affichée dans le portail, soit l’un des fournisseurs d’attestation partagés. Vous aurez également besoin des informations d’identification du client pour utiliser le client d’administration d’attestation ou appeler l’API attestTpm . Les informations d’identification du client nécessitent (ID client, clé secrète client, ID de locataire) d’instancier un objet client.

Dans cette section de prise en main, nous allons nous authentifier à l’aide d’informations d’identification de secret client via le fournisseur DefaultAzureCredential , mais nous proposons davantage de mécanismes d’authentification via le package @azure/identité . Pour installer le @azure/identity package :

npm install @azure/identity

Créer/obtenir des informations d’identification

Utilisez l’extrait de code Azure CLI ci-dessous pour créer/obtenir des informations d’identification de secret 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 informations d’identification retournées 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 leur utilisation, consultez Bibliothèque cliente Azure Identity

Concepts clés

Il existe quatre grandes familles de fonctionnalités fournies dans ce KIT de développement logiciel (SDK) en préversion :

Le service Microsoft Azure Attestation s’exécute dans 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’authentification pour vérifier qu’il est autorisé à modifier l’état d’une instance d’attestation.

Enfin, chaque région dans laquelle le service Microsoft Azure Attestation est disponible prend en charge une instance « partagée », qui peut être utilisée pour attester les enclaves SGX qui nécessitent uniquement une vérification par rapport à la base de référence Azure (aucune stratégie 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 l’authentification AAD, elle n’a pas de stratégies RBAC . Tout client disposant d’un jeton de porteur AAD valide peut attester à l’aide 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’il respecte à la fois la base de référence Azure pour cet environnement et les stratégies définies par le client appliquées à cet environnement.

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

L’une des principales garanties opérationnelles du service Azure Attestation est que le service fonctionne « de manière opérationnelle hors du TCB ». En d’autres termes, il n’existe aucun moyen qu’un opérateur Microsoft puisse falsifier le fonctionnement du service ou endommager les données envoyées à partir du client. Pour garantir cette garantie, le cœur du service d’attestation s’exécute 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é conservée 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 s’exécute dans une région où le service s’exécute dans une enclave SGX, 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, et l’attribut value contient le corps de la réponse du jeton web JSON.

Gestion des stratégies

Une stratégie est appliquée à chaque instance de service d’attestation qui définit des critères supplémentaires définis par le client.

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

Gestion des certificats de gestion des stratégies

Lorsqu’une instance d’attestation s’exécute en mode « Isolé », le client qui a créé l’instance aura fourni un certificat de gestion des stratégies au moment de la création de l’instance. Toutes les opérations de modification de stratégie nécessitent que le client signe les données de stratégie avec l’un des certificats de gestion des stratégies existants. Les API Gestion des certificats de gestion des stratégies permettent aux clients de « roll » les certificats de gestion des stratégies.

Mode isolé et mode AAD

Chaque instance de service Microsoft Azure Attestation fonctionne en mode « AAD » ou « Isolé ». Lorsqu’une instance de MAA fonctionne en mode AAD, cela signifie que le client qui a créé l’instance d’attestation permet aux stratégies de contrôle d’accès en fonction du rôle Azure Active Directory et d’Azure de vérifier l’accès à l’instance d’attestation.

AttestationType

Le service Microsoft Azure Attestation prend en charge l’attestation de différents types de preuves en fonction de l’environnement. Actuellement, MAA prend en charge les environnements d’exécution approuvés suivants :

  • OpenEnclave : processeur Intel(tm) exécutant du code dans une enclave SGX où les preuves d’attestation ont été collectées à l’aide d’OpenEnclave ou de oe_get_report l’API oe_get_evidence .
  • 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 Kit de développement logiciel (SDK) Intel SGX.
  • Tpm : environnement de sécurité basé sur la virtualisation dans lequel le module de plateforme approuvée du processeur est utilisé pour fournir les preuves d’attestation.

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

RuntimeData fait référence aux données qui sont présentées à la logique de génération de devis Intel SGX ou aux oe_get_report/oe_get_evidence API. Si l’appelant de l’API d’attestation a fourni un runtime_data attribut, le service Azure Attestation valide que les 32 premiers octets du report_data champ dans la preuve SGX Quote/OE Report/OE correspondent au hachage SHA256 du runtime_data.

Les données InitTime font référence aux 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 de la série Azure DCsv2 .

Concepts supplémentaires

Exemples

Créer une instance cliente

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

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’uri endpoint.

Notez que le client d’administration nécessite des informations d’identification Azure.

  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 stratégie d’attestation

La getPolicy méthode récupère la stratégie d’attestation du service. Les stratégies d’attestation sont instances par type d’attestation, le AttestationType paramètre définit le type d’instance à récupérer.

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

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

Si l’instance du service d’attestation s’exécute en mode isolé, l’API set_policy doit fournir un certificat de signature (et une clé privée) qui peut être utilisé pour vérifier que l’appelant est autorisé à modifier la stratégie sur l’instance d’attestation. Si l’instance de service s’exécute en mode AAD, le certificat de signature et la clé sont facultatifs.

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

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 s’exécute en mode isolé, l’appel à setPolicy nécessite que le client puisse prouver qu’il a accès à l’un des certificats et clés privés de gestion de stratégie.

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 les couvertures, les API setPolicy créent un jeton web JSON contenant dans le document certificate de stratégie et signé avec le privateKey qui est ensuite envoyé au service d’attestation.

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

  • policySigner - si l’appel setPolicy incluait un certificate, cette valeur sera le certificat fourni au moment de l’appel setPolicy . Si aucun signataire de stratégie n’a été défini, cette valeur est null.
  • policyTokenHash - il s’agit du hachage 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 stratégie d’attestation (classe d’assistance qui représente le jeton utilisé pour définir la stratégie d’attestation) et vérifier le hachage généré à partir de ce jeton :

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

Attester SGX et Open Enclave

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

L’un des principaux défis auxquels les clients doivent faire face lors de l’interaction avec les environnements chiffrés est de s’assurer que vous pouvez communiquer en toute sécurité avec le code en cours d’exécution dans l’environnement (« code d’enclave »).

Une solution à ce problème est ce qu’on appelle la « mise en production de clé sécurisée », qui est un modèle qui permet une communication sécurisée avec du code d’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é dans un format (éventuellement une clé web JSON, ou PEM, ou un autre format de sérialisation).

Le code d’enclave calcule ensuite la valeur SHA256 de la clé publique et la transmet en tant qu’entrée au code qui génère un devis SGX (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 valide le devis et s’assure que le hachage de la clé est présent dans le devis et émet un « jeton d’attestation ».

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

Cet exemple montre un modèle courant d’appel au service d’attestation pour récupérer un jeton d’attestation associé à une demande.

Cet exemple suppose que vous disposez d’un objet existant AttestationClient configuré avec l’URI d’attest pour votre point de terminaison. Elle suppose également que vous disposez d’un rapport OpenEnclave (report) généré à partir de l’enclave SGX que vous attestez, et des « données d’exécution » (binaryRuntimeData) qui sont référencées dans le devis SGX.

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

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

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

De même, si vous utilisez le Kit de développement logiciel (SDK) Intel pour générer un « devis », vous pouvez valider le devis à l’aide de :

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

Vous trouverez des informations supplémentaires sur la façon d’effectuer la validation de jeton d’attestation dans l’exemple d’attestation de 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 informations d’identification Azure, qui n’est pas nécessaire si vous appelez les attestSgxEnclave API ou attestOpenEnclave

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

const attestationSigners = await client.getAttestationSigners();

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

Dépannage

La plupart des opérations du service Attestation déclenchent des exceptions définies dans Azure Core. Les API du service d’attestation lèvent un en cas d’échec avec des RestError codes d’erreur utiles. La plupart de ces erreurs peuvent être récupérées.

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

Journalisation

L’activation de la journalisation peut vous aider à mieux comprendre les échecs. Pour avoir 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 @azure/logger :

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

setLogLevel("info");

Pour obtenir des instructions plus détaillées sur l’activation des journaux, consultez les documents relatifs au package @azure/logger.

Vous trouverez des informations supplémentaires sur la résolution des problèmes pour le service MAA ici

Étapes suivantes

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

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez le site Contrat de licence contributeur.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Consultez CONTRIBUTING.md pour plus d’informations sur la création, le test et la contribution à ces bibliothèques.

Fournir des commentaires

Si vous rencontrez des bogues ou si vous avez des suggestions, signalez un problème dans la section Problèmes du projet.

Impressions