Delen via

Azure Attestation clientbibliotheek voor JavaScript - versie 1.0.0

  • Artikel

De MAA-service (Microsoft Azure Attestation) is een geïntegreerde oplossing voor het extern verifiëren van de betrouwbaarheid van een platform en de integriteit van de binaire bestanden die erin worden uitgevoerd. De service ondersteunt attestation van de platforms die worden ondersteund door TPM's (Trusted Platform Modules), naast de mogelijkheid om de status van TRUSTED Execution Environments (TEE's) zoals Intel(tm) SGX-enclaves (Software Guard Extensions) en VBS-enclaves (Virtualization-Based Security) te bevestigen.

Attestation is een proces voor het demonstreren dat de software-binaire bestanden op de juiste manier op een vertrouwd platform zijn geïnstantieerd. Externe relying party's kunnen dan betrouwbaarheid krijgen dat alleen dergelijke bedoelde software wordt uitgevoerd op vertrouwde hardware. Azure Attestation is een uniforme klantgerichte service en kader voor Attestation.

Met Azure Attestation kunnen geavanceerde beveiligingsmodellen, zoals Azure Confidential Computing en Intelligent Edge-beveiliging. Klanten hebben de mogelijkheid gevraagd om de locatie van een machine onafhankelijk te controleren, het postuur van een virtuele machine (VM) op die computer en de omgeving waarin enclaves op die VM worden uitgevoerd. Met Azure Attestation kunnen deze en vele bijkomende aanvragen van klanten worden gestimuleerd.

Azure Attestation ontvangt bewijs van berekeningsentiteiten, zet ze om in een set claims, valideert ze op basis van configureerbare beleidsregels en produceert cryptografische bewijzen voor op claims gebaseerde toepassingen (bijvoorbeeld relying party's en controle-instanties).

Zie de azure sdk typescript-release voor een volledigere weergave van Azure-bibliotheken.

OPMERKING: dit is een preview-SDK voor de Microsoft Azure Attestation-service. Het biedt alle essentiële functionaliteit voor toegang tot de Azure Attestation service, moet worden beschouwd als 'as-is' en is onderhevig aan wijzigingen in de toekomst waardoor de compatibiliteit met eerdere versies kan worden verbroken.

Belangrijke koppelingen:

Aan de slag

Momenteel ondersteunde omgevingen

Zie ons ondersteuningsbeleid voor meer informatie.

Vereisten

  • Een Azure-abonnement
  • Een bestaand Azure Attestation-exemplaar of u kunt de 'gedeelde provider' gebruiken die beschikbaar is in elke Azure-regio. Als u een Azure Attestation service-exemplaar wilt maken, kunt u azure portal of Azure CLI gebruiken.

Installeer het pakket @azure/attestation

Installeer de Microsoft Azure Attestation-clientbibliotheek voor JavaScript met NPM:

npm install @azure/attestation

De client verifiëren

Als u wilt communiceren met de Microsoft Azure Attestation-service, moet u een exemplaar maken van de klasse Attestation Client of Attestation Administration Client. U hebt de URL van een attestation-exemplaar nodig. Dit is de 'Attest-URI' die wordt weergegeven in de portal, of een van de gedeelde attestation-providers. U hebt ook clientreferenties nodig om de Attestation-beheerclient te gebruiken of de attestTpm API aan te roepen. Clientreferenties vereisen (client-id, clientgeheim, tenant-id) om een clientobject te instantiëren.

In deze sectie aan de slag verifiëren we met behulp van referenties voor clientgeheimen via de provider DefaultAzureCredential , maar we bieden meer verificatiemechanismen via het pakket @azure/identity . Het pakket installeren @azure/identity :

npm install @azure/identity

Referenties maken/ophalen

Gebruik het onderstaande Azure CLI-fragment om referenties voor clientgeheimen te maken/op te halen.

  • Maak een service-principal en configureer de toegang tot Azure-resources:

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

    Uitvoer:

    {
  "appId": "generated-app-ID",
  "displayName": "dummy-app-name",
  "name": "http://dummy-app-name",
  "password": "random-password",
  "tenant": "tenant-ID"
}

  • Noteer de objectId van de service-principal

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

    Uitvoer:

    "<your-service-principal-object-id>"

  • Gebruik de bovenstaande geretourneerde referenties om AZURE_CLIENT_ID (appId), AZURE_CLIENT_SECRET (wachtwoord) en AZURE_TENANT_ID (tenant) omgevingsvariabelen in te stellen. In het volgende voorbeeld ziet u een manier om dit te doen in PowerShell:

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

Zie Azure Identity-clientbibliotheek voor meer informatie over de Azure Identity-API's en hoe u deze kunt gebruiken

Belangrijkste concepten

Deze preview-SDK bevat vier belangrijke typen functionaliteit:

De Microsoft Azure Attestation-service wordt uitgevoerd in twee afzonderlijke modi: 'Isolated' en 'AAD'. Wanneer de service wordt uitgevoerd in de geïsoleerde modus, moet de klant naast de verificatiereferenties aanvullende informatie opgeven om te controleren of ze gemachtigd zijn om de status van een attestation-exemplaar te wijzigen.

Ten slotte ondersteunt elke regio waarin de Microsoft Azure Attestation-service beschikbaar is een 'gedeeld' exemplaar, dat kan worden gebruikt om SGX-enclaves te bevestigen die alleen hoeven te worden geverifieerd op basis van de Azure-basislijn (er worden geen beleidsregels toegepast op de gedeelde provider). TPM-attestation is niet beschikbaar in de gedeelde provider. Hoewel het gedeelde exemplaar AAD-verificatie vereist, heeft het geen RBAC-beleid. Elke klant met een geldig AAD Bearer-token kan bevestigen met behulp van het gedeelde exemplaar.

Attestation

SGX- of TPM-attestation is het proces van het valideren van bewijs dat is verzameld uit een vertrouwde uitvoeringsomgeving om ervoor te zorgen dat deze voldoet aan zowel de Azure-basislijn voor die omgeving als het door de klant gedefinieerde beleid dat op die omgeving wordt toegepast.

Certificaatdetectie en -validatie van attestation-servicetokenondertekening

Een van de belangrijkste operationele garanties van de Azure Attestation Service is dat de service "operationeel vanuit de TCB" werkt. Met andere woorden, er is geen manier waarop een Microsoft-operator kan knoeien met de werking van de service of beschadigde gegevens die vanaf de client worden verzonden. Om deze garantie te garanderen, wordt de kern van de attestation-service uitgevoerd in een Intel(tm) SGX-enclave.

Om klanten in staat te stellen te controleren of bewerkingen daadwerkelijk in de enclave zijn uitgevoerd, worden de meeste antwoorden van de Attestation-service gecodeerd in een JSON-webtoken, dat is ondertekend door een sleutel die is opgeslagen in de enclave van de attestation-service.

Dit token wordt ondertekend door een handtekeningcertificaat dat is uitgegeven door de MAA-service voor het opgegeven exemplaar.

Als het MAA-service-exemplaar wordt uitgevoerd in een regio waar de service wordt uitgevoerd in een SGX-enclave, kan het certificaat dat door de server is uitgegeven, worden geverifieerd met behulp van de oe_verify_attestation_certificate-API.

Het AttestationResponse object bevat twee hoofdkenmerken: token en value. Het token kenmerk bevat het volledige token dat wordt geretourneerd door de attestation-service, het value kenmerk bevat de hoofdtekst van het JSON-webtoken-antwoord.

Beleidsbeheer

Op elk attestation-service-exemplaar is een beleid toegepast dat aanvullende criteria definieert die de klant heeft gedefinieerd.

Zie Attestation-beleid voor meer informatie over attestation-beleid

Beleidsbeheercertificaatbeheer

Wanneer een attestation-exemplaar wordt uitgevoerd in de geïsoleerde modus, heeft de klant die het exemplaar heeft gemaakt, een certificaat voor beleidsbeheer opgegeven op het moment dat het exemplaar wordt gemaakt. Alle beleidswijzigingsbewerkingen vereisen dat de klant de beleidsgegevens ondertekent met een van de bestaande beleidsbeheercertificaten. Met de API's voor beleidsbeheercertificaatbeheer kunnen clients de beleidsbeheercertificaten 'rollen'.

Geïsoleerde modus en AAD-modus

Elk Microsoft Azure Attestation-service-exemplaar werkt in de AAD-modus of in de geïsoleerde modus. Wanneer een MAA-exemplaar wordt uitgevoerd in de AAD-modus, betekent dit dat de klant die het attestation-exemplaar heeft gemaakt, toegangsbeheerbeleid op basis van Azure Active Directory en Azure-rollen toestaat om de toegang tot het attestation-exemplaar te verifiëren.

AttestationType

De Microsoft Azure Attestation-service ondersteunt het bevestigen van verschillende soorten bewijs, afhankelijk van de omgeving. Op dit moment ondersteunt MAA de volgende omgevingen voor vertrouwde uitvoering:

  • OpenEnclave : een Intel(tm) Processor die code uitvoert in een SGX Enclave waarbij het attestation-bewijs is verzameld met behulp van de OpenEnclave oe_get_report of oe_get_evidence API.
  • SgxEnclave : een Intel(tm) Processor die code uitvoert in een SGX Enclave waarbij het attestation-bewijs is verzameld met behulp van de Intel SGX SDK.
  • Tpm: een op virtualisatie gebaseerde beveiligingsomgeving waarin de Trusted Platform Module van de processor wordt gebruikt om het attestation-bewijs te leveren.

Runtime-gegevens en Inittime-gegevens

RuntimeData verwijst naar gegevens die worden gepresenteerd aan de Intel SGX Quote-generatielogica of de oe_get_report/oe_get_evidence API's. Als de aanroeper van de attest-API een runtime_data kenmerk heeft opgegeven, valideert de Azure Attestation-service dat de eerste 32 bytes van het report_data veld in de SGX Quote/OE Report/OE Evidence overeenkomen met de SHA256-hash van de runtime_data.

InitTime-gegevens verwijzen naar gegevens die worden gebruikt voor het configureren van de SGX-enclave die wordt getest.

Houd er rekening mee dat InitTime-gegevens niet worden ondersteund op virtuele machines uit de Azure DCV2-serie .

Aanvullende concepten

Voorbeelden

Clientexemplaar maken

Hiermee maakt u een exemplaar van de Attestation-client op URI endpoint, met behulp van de standaard Azure-referenties (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();

Als u de attestTpm API niet aanroept, hoeft u geen referenties op te geven voor toegang tot de Attestation-client. Dit betekent dat een client eenvoudig kan worden gemaakt met:

const client = new AttestationClient(endpoint);

// Retrieve the set of attestation policy signers from the attestation client.
const attestationSigners = await client.getAttestationSigners();

Hiermee maakt u een exemplaar van de Attestation-beheerclient op URI endpoint.

Houd er rekening mee dat voor de beheerclient Azure-referenties zijn vereist .

  const client = new AttestationAdministrationClient(endpoint, new DefaultAzureCredential());

  // Retrieve the SGX policy from the specified attestation instance.
  const policyResponse = await client.getPolicy(KnownAttestationType.SgxEnclave);

Attestation-beleid ophalen

Met getPolicy de methode wordt het attestation-beleid opgehaald uit de service. Attestation-beleid wordt per attestation-type gebruikt. De AttestationType parameter definieert het type exemplaar dat moet worden opgehaald.

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

Een attestation-beleid instellen voor een opgegeven attestation-type

Als het exemplaar van de attestation-service wordt uitgevoerd in de geïsoleerde modus, moet de set_policy API een handtekeningcertificaat (en een persoonlijke sleutel) opgeven die kunnen worden gebruikt om te valideren dat de aanroeper gemachtigd is om beleid voor het Attestation-exemplaar te wijzigen. Als het service-exemplaar wordt uitgevoerd in de AAD-modus, zijn het handtekeningcertificaat en de sleutel optioneel.

Als het service-exemplaar wordt uitgevoerd in de AAD-modus, wordt setPolicy aangeroepen zoals verwacht:

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

Als het service-exemplaar wordt uitgevoerd in de geïsoleerde modus, vereist de aanroep van setPolicy dat de client kan bewijzen dat ze toegang hebben tot een van de persoonlijke sleutels en certificaten voor beleidsbeheer.

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

Onder de omslag maken de setPolicy-API's een JSON-webtoken met in het beleidsdocument certificate en ondertekend met de privateKey die vervolgens wordt verzonden naar de attestation-service.

Als een client ervoor wil zorgen dat het attestation-beleidsdocument niet is gewijzigd voordat het beleidsdocument werd ontvangen door de enclave van de attestation-service, kunnen ze de eigenschappen gebruiken die worden geretourneerd in de policyResult-objct , die kunnen worden gebruikt om te controleren of de service het beleidsdocument heeft ontvangen:

  • policySigner - als de setPolicy aanroep een certificatebevat, is deze waarde het certificaat dat is opgegeven op het moment van de setPolicy aanroep. Als er geen beleids ondertekenaar is ingesteld, is dit null.
  • policyTokenHash - dit is de hash van de JSON-webhandtekening die is verzonden naar de service voor de setPolicy-API.

Om de hash te controleren, kunnen clients een attestation-beleidstoken maken (een helperklasse die het token vertegenwoordigt dat wordt gebruikt om het attestation-beleid in te stellen) en de hash controleren die is gegenereerd op die token:

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

Attest SGX en Open Enclave

Gebruik de attestSgxEnclave methode om een SGX-enclave te bevestigen.

Een van de belangrijkste uitdagingen voor klanten bij de interactie met versleutelde omgevingen is hoe u veilig kunt communiceren met de code die in de omgeving wordt uitgevoerd ('enclavecode').

Een oplossing voor dit probleem is wat bekend staat als 'Secure Key Release', een patroon dat beveiligde communicatie met enclavecode mogelijk maakt.

Als u het patroon 'Secure Key Release' wilt implementeren, genereert de enclavecode een kortstondige asymmetrische sleutel. Vervolgens wordt het openbare gedeelte van de sleutel geserialiseerd naar een bepaalde indeling (mogelijk een JSON-websleutel of PEM of een andere serialisatie-indeling).

De enclavecode berekent vervolgens de SHA256-waarde van de openbare sleutel en geeft deze door als invoer voor code die een SGX-offerte genereert (voor OpenEnclave is dat de oe_get_evidence of oe_get_report).

De client verzendt vervolgens de SGX-offerte en de geserialiseerde sleutel naar de attestation-service. De attestation-service valideert de offerte en zorgt ervoor dat de hash van de sleutel aanwezig is in de offerte en geeft een Attestation-token uit.

De client kan vervolgens dat Attestation-token (dat de geserialiseerde sleutel bevat) verzenden naar een 'relying party' van derden. De relying party valideert vervolgens dat het attestation-token is gemaakt door de attestation-service, en dus kan de geserialiseerde sleutel worden gebruikt voor het versleutelen van bepaalde gegevens die door de relying party worden bewaard en naar de service worden verzonden.

In dit voorbeeld ziet u een veelvoorkomend patroon voor het aanroepen van de Attestation-service om een attestation-token op te halen dat is gekoppeld aan een aanvraag.

In dit voorbeeld wordt ervan uitgegaan dat u een bestaand AttestationClient object hebt dat is geconfigureerd met de Attest-URI voor uw eindpunt. Er wordt ook van uitgegaan dat u een OpenEnclave-rapport (report) hebt gegenereerd vanuit de SGX-enclave die u bevestigt, en 'Runtime-gegevens' (binaryRuntimeData) waarnaar wordt verwezen in de SGX-offerte.

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

Het is ook mogelijk dat de binaryRuntimeData verzonden naar de attestation-service is bedoeld om te worden geïnterpreteerd als JSON-gegevens. In dat geval moet de client in de attest-API-aanroep opgeven runTimeJson :

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

Als u de Intel SDK gebruikt om een 'offerte' te genereren, kunt u de offerte valideren met behulp van:

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

Meer informatie over het uitvoeren van attestation-tokenvalidatie vindt u in het MAA Service Attestation-voorbeeld.

Tokencertificaten ophalen

Gebruik getSigningCertificates om de certificaten op te halen die kunnen worden gebruikt om het token te valideren dat is geretourneerd door de attestation-service. Houd er rekening mee dat deze aanroep een client met Azure-referenties maakt, die niet nodig is als u de attestSgxEnclave API's of attestOpenEnclave aanroept

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

const attestationSigners = await client.getAttestationSigners();

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

Problemen oplossen

De meeste Attestation-servicebewerkingen genereren uitzonderingen die zijn gedefinieerd in Azure Core. De attestation-service-API's genereren een RestError fout met nuttige foutcodes. Veel van deze fouten kunnen worden hersteld.

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

Logboekregistratie

Het inschakelen van logboekregistratie kan helpen bij het ontdekken van nuttige informatie over fouten. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de AZURE_LOG_LEVEL omgevingsvariabele in op info. U kunt logboekregistratie ook tijdens runtime inschakelen door aan te roepen setLogLevel in de @azure/logger:

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

setLogLevel("info");

Voor meer gedetailleerde instructies over het inschakelen van logboeken kunt u de @azure-/loggerpakketdocumenten bekijken.

Aanvullende informatie over probleemoplossing voor de MAA-service vindt u hier

Volgende stappen

Zie onze documentatiepagina voor meer informatie over de Microsoft Azure Attestation-service.

Bijdragen

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga voor meer informatie naar de site met de licentieovereenkomst voor inzenders.

Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit maar eenmaal te doen voor alle repo's waar gebruik wordt gemaakt van onze CLA.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Raadpleeg voor meer informatie de veelgestelde vragen over de gedragscode of neem contact op met opencode@microsoft.com als u aanvullende vragen of opmerkingen hebt.

Zie CONTRIBUTING.md voor meer informatie over het bouwen, testen en bijdragen aan deze bibliotheken.

Feedback geven

Als u fouten tegenkomt of suggesties hebt, kunt u een probleem melden in de sectie Problemen van het project.

Weergaven