bibliothèque de client Azure Attestation pour .NET - 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 reposant sur des modules de plateforme sécurisée (TPM), en plus de la possibilité d’attester de l’état des environnements d’exécution de confiance (TEE), tels que les enclaves Intel® SGX (Software Guard Extensions) et les enclaves de sécurité basée sur la virtualisation (VBS).

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

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 soumis à des modifications à l’avenir qui peuvent rompre la compatibilité avec les versions précédentes.

| Code sourcePackage (NuGet) | 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 Microsoft 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 un service Azure Attestation instance, vous pouvez utiliser le portail Azure ou Azure CLI.

Installer le package

Installez la bibliothèque de client Microsoft Azure Attestation pour .NET avec NuGet :

dotnet add package Azure.Security.Attestation --prerelease

Authentifier le client

Pour interagir avec le service Microsoft Azure Attestation, vous devez créer un instance de la classe Client Attestation ou Client d’administration d’attestation. Vous avez besoin d’une attestation instance URL, que vous pouvez voir sous le nom « Nom DNS » dans le portail, et d’informations d’identification de la clé secrète client (ID client, secret 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 l’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 :

dotnet add package 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 attestation instance.

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’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 le instance partagé. Bien que le instance partagé nécessite l’authentification AAD, il n’a pas de stratégie RBAC. Tout client disposant d’un jeton de porteur AAD valide peut attester à l’aide de la 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 le instance spécifié.

Si le service MAA instance 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 propriétés main : Token et Value. La Token propriété contient le jeton complet retourné par le service d’attestation, la Value propriété contient le corps de la réponse du jeton web JSON.

Gestion des stratégies

Une stratégie est appliquée à chaque service d’attestation instance 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éé le instance a fourni un certificat de gestion des stratégies au moment de la création du 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’un MAA instance fonctionne en mode AAD, cela signifie que le client qui a créé l’attestation instance permet aux stratégies de contrôle d’accès en fonction du rôle Azure Active Directory et Azure de vérifier l’accès à l’attestation instance.

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ù la preuve d’attestation a été collectée à l’aide d’OpenEnclave ou de oe_get_report l’API 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. Le service Azure Attestation vérifie que les 32 premiers octets du report_data champ dans le devis SGX/rapport OE/preuve OE correspondent au hachage SHA256 de RuntimeData.

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 .

Sécurité des threads

Nous garantissons que toutes les méthodes de instance client sont thread-safe et indépendantes les unes des autres (instructions). Cela garantit que la recommandation de réutilisation des instances clientes est toujours sécurisée, même entre les threads.

Concepts supplémentaires

Options | du client Accès à la réponse | Opérations | de longue duréeGestion des défaillances | Diagnostics | Moqueur | Durée de vie du client

Exemples

Créer un instance client

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

var options = new AttestationClientOptions();
return new AttestationClient(new Uri(endpoint), new DefaultAzureCredential(), options);

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

var client = new AttestationAdministrationClient(new Uri(endpoint), new DefaultAzureCredential());

AttestationResponse<string> policyResult = await client.GetPolicyAsync(AttestationType.SgxEnclave);
string result = policyResult.Value;

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

Si le service d’attestation instance s’exécute en mode isolé, l’API SetPolicy 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 le instance d’attestation. Si le service instance 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 envoyées au service d’attestation.

string attestationPolicy = "version=1.0; authorizationrules{=> permit();}; issuancerules{};";

X509Certificate2 policyTokenCertificate = new X509Certificate2(<Attestation Policy Signing Certificate>);
AsymmetricAlgorithm policyTokenKey = <Attestation Policy Signing Key>;

var setResult = client.SetPolicy(AttestationType.SgxEnclave, attestationPolicy, new AttestationTokenSigningKey(policyTokenKey, policyTokenCertificate));

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 :

  • PolicySigner - si l’appel SetPolicy incluait un certificat de signature, il s’agit du 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 du jeton web JSON envoyé au service.

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

// The SetPolicyAsync API will create an AttestationToken signed with the TokenSigningKey to transmit the policy.
// To verify that the policy specified by the caller was received by the service inside the enclave, we
// verify that the hash of the policy document returned from the Attestation Service matches the hash
// of an attestation token created locally.
TokenSigningKey signingKey = new TokenSigningKey(<Customer provided signing key>, <Customer provided certificate>)
var policySetToken = new AttestationToken(
    BinaryData.FromObjectAsJson(new StoredAttestationPolicy { AttestationPolicy = attestationPolicy }),
    signingKey);

using var shaHasher = SHA256Managed.Create();
byte[] attestationPolicyHash = shaHasher.ComputeHash(Encoding.UTF8.GetBytes(policySetToken.Serialize()));

Debug.Assert(attestationPolicyHash.SequenceEqual(setResult.Value.PolicyTokenHash.ToArray()));

Attester l’enclave SGX

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

L’un des principaux défis rencontrés par les clients lors de l’interaction avec les environnements chiffrés consiste à s’assurer que vous pouvez communiquer de manière fiable avec le code en cours d’exécution dans l’environnement (« code d’enclave »).

Une solution à ce problème est ce que l’on appelle « Mise en production de clé sécurisée », qui est un modèle qui permet ce type de communication avec le code d’enclave.

Pour implémenter le modèle « Mise en production de clé sécurisée », le code d’enclave génère une clé asymétrique éphémère. Il sérialise ensuite la partie publique de la clé dans un format quelconque (é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, qui 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 requête.

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 (binaryQuote) généré à partir de l’enclave SGX que vous attestez, et de « données d’exécution » (runtimeData) qui est référencé dans le devis SGX.

// Collect quote and runtime data from an SGX enclave.
// For the "Secure Key Release" scenario, the runtime data is normally a serialized asymmetric key.
// When the 'quote' (attestation evidence) is created specify the SHA256 hash of the runtime data when
// creating the evidence.
//
// When the generated evidence is created, the hash of the runtime data is included in the
// secured portion of the evidence.
//
// The Attestation service will validate that the Evidence is valid and that the SHA256 of the RuntimeData
// parameter is included in the evidence.
AttestationResponse<AttestationResult> attestationResult = client.AttestSgxEnclave(new AttestationRequest
{
    Evidence = BinaryData.FromBytes(binaryQuote),
    RuntimeData = new AttestationData(BinaryData.FromBytes(binaryRuntimeData), false),
});

// At this point, the EnclaveHeldData field in the attestationResult.Value property will hold the
// contain the input binaryRuntimeData.

// The token is now passed to the "relying party". The relying party will validate that the token was
// issued by the Attestation Service. It then extracts the asymmetric key from the EnclaveHeldData field.
// The relying party will then Encrypt it's "key" data using the asymmetric key and transmits it back
// to the enclave.
var encryptedData = SendTokenToRelyingParty(attestationResult.Token);

// Now the encrypted data can be passed into the enclave which can decrypt that data.

Pour plus d’informations sur la façon d’effectuer la validation des jetons d’attestation, consultez l’exemple d’attestation de service MAA.

Récupérer des certificats de jeton

Utilisez GetSigningCertificatesAsync pour récupérer les certificats qui peuvent être utilisés pour valider le jeton retourné par le service d’attestation.

var client = GetAttestationClient();

IReadOnlyList<AttestationSigner> signingCertificates = (await client.GetSigningCertificatesAsync()).Value;

Résolution des problèmes

La plupart des opérations du service Attestation lèvent une exception RequestFailedException en cas d’échec avec des codes d’erreur utiles. La plupart de ces erreurs peuvent être récupérées.

try
{
    AttestationResponse<AttestationResult> attestationResult = client.AttestSgxEnclave(new AttestationRequest
    {
        Evidence = BinaryData.FromBytes(binaryQuote),
        RuntimeData = new AttestationData(BinaryData.FromBytes(binaryRuntimeData), false),
    });
}
catch (RequestFailedException ex)
    when (ex.ErrorCode == "InvalidParameter")
    {
    // Ignore invalid quote errors.
    }

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.

Impressions