bibliothèque cliente Azure Attestation pour Python - 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 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 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).

Ce package a été testé avec Python 2.7, 3.6 à 3.9.

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

| Code sourcePackage (PyPI) | Documentation de référence sur les | API Documentation produit

Prise en main

Prérequis

  • Un abonnement Azure. Pour utiliser les services Azure, y compris le service Azure Attestation, vous avez besoin d’un abonnement. Si vous n’avez pas de compte Azure existant, vous pouvez vous inscrire à un essai gratuit ou utiliser les avantages de votre abonnement Visual Studio lorsque vous créez un compte.
  • 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.

Installer le package

Installez la bibliothèque cliente Azure Attestation pour Python avec PyPI :

pip install azure-security-attestation

Authentifier le client

Pour interagir avec le service Azure Attestation, vous devez créer une instance de la classe Client Attestation ou Attestation Administration Client. Vous avez besoin d’un point de terminaison d’attestation, que vous pouvez voir comme « URI d’attestation » dans le portail, et des informations d’identification client (ID client, clé secrète client, ID de locataire) pour instancier un objet client.

L’authentification des informations d’identification de la clé secrète client est utilisée dans cette section de prise en main, mais vous pouvez trouver d’autres façons de vous authentifier avec le package d’identité Azure. Pour utiliser le fournisseur DefaultAzureCredential indiqué ci-dessous ou d’autres fournisseurs d’informations d’identification fournis avec le Kit de développement logiciel (SDK) Azure, vous devez installer le package azure-identity :

pip 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 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 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 comment procéder 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 de client Azure Identity

Concepts clés

Quatre familles principales de fonctionnalités sont 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 Azure Attestation est disponible prend en charge une instance « partagée », qui peut être utilisée pour attester les enclaves SGX qui n’ont besoin que d’une vérification par rapport à la base de référence Azure (aucune stratégie n’est appliquée à l’instance partagée). L’attestation TPM n’est pas disponible dans l’instance partagée. 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’elle 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 du 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é 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 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.

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 a 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 de stratégie existants. Les API de 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 en mode « Isolé ». Lorsqu’une instance de MAA fonctionne en mode AAD, cela signifie que le client qui a créé l’instance d’attestation autorise Azure Active Directory et les stratégies de contrôle d’accès en fonction du rôle Azure à vérifier l’accès à l’instance d’attestation.

AttestationType

Le service 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ù la preuve d’attestation a été collectée à l’aide de l’API OpenEnclave oe_get_report ou oe_get_evidence .
  • SgxEnclave : 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ée sur la virtualisation dans lequel le module de plateforme sécurisée du processeur est utilisé pour fournir la preuve 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 validera 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 de client

Crée une instance du client d’attestation à l’uri endpoint.

attest_client = AttestationClient(
    endpoint=base_uri,
    credential=DefaultAzureCredential())

Obtenir la stratégie d’attestation

La set_policy 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 à récupérer.

policy, token = attest_client.get_policy(AttestationType.SGX_ENCLAVE)
print('Instance SGX policy: ', policy)
print('Token: ', 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.

Sous les couvertures, les API SetPolicy créent un jeton web JSON basé sur le document de stratégie et les informations de signature qui sont envoyés au service d’attestation.

policy_set_response = attest_client.set_policy(AttestationType.SGX_ENCLAVE,
    attestation_policy,
    signing_key=key,
    signing_certificate=signing_certificate)
new_policy, _ = attest_client.get_policy(AttestationType.SGX_ENCLAVE)
# `new_policy` will equal `attestation_policy`.

Si l’instance de service s’exécute en mode AAD, l’appel à set_policy peut être simplifié :

policy_set_response = attest_client.set_policy(AttestationType.SGX_ENCLAVE,            
    attestation_policy)
# Now retrieve the policy which was just set.
new_policy, _ = attest_client.get_policy(AttestationType.SGX_ENCLAVE)

Les clients doivent être en mesure de vérifier 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 existe deux propriétés fournies dans PolicyResult qui peuvent être utilisées pour vérifier que le service a reçu le document de stratégie :

  • policy_signer : si l’appel set_policy incluait un certificat de signature, il s’agit du certificat fourni au moment de l’appel set_policy . Si aucun signataire de stratégie n’a été défini, cette valeur est null.
  • policy_token_hash : il s’agit du hachage du jeton web JSON envoyé au service.

Pour vérifier le hachage, les clients peuvent générer un jeton de stratégie d’attestation et vérifier le hachage généré à partir de ce jeton :

from cryptography.hazmat.primitives import hashes

expected_policy = AttestationPolicyToken(
    attestation_policy,
    signing_key=key,
    signing_certificate=signing_certificate)
hasher = hashes.Hash(hashes.SHA256())
hasher.update(expected_policy.serialize().encode('utf-8'))
expected_hash = hasher.finalize()

# `expected_hash` will exactly match `policy_set_response.policy_token_hash`

Attester l’enclave SGX

Utilisez la méthode attest_sgx_enclave 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 de base de votre point de terminaison. Il suppose également que vous disposez d’un devis SGX (quote) généré à partir de l’enclave SGX que vous attestez, et des « données d’exécution » (runtime_data) qui sont référencées dans le devis SGX.

response, token = attest_client.attest_sgx_enclave(quote, runtime_data=runtime_data)

À ce stade, l’attribut enclave_held_data dans attestationResult contiendra le runtime_data binaire d’entrée.

Le jeton est maintenant passé à la « partie de confiance ». La partie de confiance vérifie que le jeton a été émis par le service d’attestation. Il extrait ensuite la clé asymétrique du champ EnclaveHeldData. La partie de confiance chiffre ensuite ses données de « clé » à l’aide de la clé asymétrique et les transmet à l’enclave.

encrypted_data = send_token_to_relying_party(attestationResult.Token)

À présent, les données chiffrées peuvent être passées dans l’enclave qui peut déchiffrer ces données.

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 get_signing_certificates pour récupérer les certificats qui peuvent être utilisés pour valider le jeton retourné par le service d’attestation.

signers = attest_client.get_signing_certificates()
for signer in signers:
    from cryptography.hazmat.backends import default_backend
    cert = cryptography.x509.load_pem_x509_certificate(signer.certificates[0].encode('ascii'), backend=default_backend())
    print('Cert  iss:', cert.issuer, '; subject:', cert.subject)

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 HttpResponseError codes d’erreur utiles. La plupart de ces erreurs peuvent être récupérées.

try:
    response, _ = attest_client.attest_sgx_enclave(
        quote,
        runtime_data=AttestationData(runtime_data, is_json=False))
except HttpResponseError as ex:
    # Ignore invalid quote errors.
    if ex.error == "InvalidParameter":
        pass
}

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