Dela via

Azure Attestation klientbibliotek för JavaScript – version 1.0.0

  • Artikel

Tjänsten Microsoft Azure Attestation (MAA) är en enhetlig lösning för fjärrkontroll av en plattforms pålitlighet och integritet för de binärfiler som körs i den. Tjänsten stöder attestering av plattformar som backas upp av TPM (Trusted Platform Modules) tillsammans med möjligheten att intyga tillståndet för betrodda körningsmiljöer (TEEs) som Intel(tm) Software Guard Extensions (SGX) enklaver och virtualiseringsbaserade säkerhets enklaver (VBS).

Attestering är en process för att visa att binärfiler för programvara instansierades korrekt på en betrodd plattform. Fjärranslutna förlitande parter kan sedan få förtroende för att endast sådan avsedd programvara körs på betrodd maskinvara. Azure Attestation är en enhetlig kundinriktad tjänst och ramverk för attestering.

Azure Attestation möjliggör banbrytande säkerhetsparadigm som Konfidentiell databehandling i Azure och Intelligent Edge-skydd. Kunder har begärt möjligheten att oberoende verifiera platsen för en dator, placeringen av en virtuell dator (VM) på den datorn och miljön där enklaver körs på den virtuella datorn. Azure Attestation kommer att ge dessa och många ytterligare kundförfrågningar.

Azure Attestation tar emot bevis från beräkningsentiteter, omvandlar dem till en uppsättning anspråk, validerar dem mot konfigurerbara principer och skapar kryptografiska bevis för anspråksbaserade program (till exempel förlitande parter och granskningsmyndigheter).

En mer fullständig vy över Azure-bibliotek finns i azure sdk typescript-versionen.

Obs! Det här är en förhandsversions-SDK för Microsoft Azure Attestation-tjänsten. Den tillhandahåller alla viktiga funktioner för att få åtkomst till Azure Attestation-tjänsten, den bör betraktas som "i förekommande fall" och kan komma att ändras i framtiden, vilket kan bryta kompatibiliteten med tidigare versioner.

Nyckellänkar:

Komma igång

Miljöer som stöds för närvarande

Mer information finns i vår supportprincip .

Förutsättningar

  • En Azure-prenumeration
  • En befintlig Azure Attestation-instans, eller så kan du använda den "delade providern" som är tillgänglig i varje Azure-region. Om du behöver skapa en Azure Attestation tjänstinstans kan du använda Azure Portal eller Azure CLI.

Installera @azure/attestation-paketet

Installera Microsoft Azure Attestation-klientbiblioteket för JavaScript med NPM:

npm install @azure/attestation

Autentisera klienten

För att kunna interagera med Microsoft Azure Attestation-tjänsten måste du skapa en instans av attesteringsklienten eller attesteringsadministrationsklientklassen. Du behöver en attesteringsinstans-URL, som antingen är "Attest URI" som visas i portalen, eller som en av de delade attesteringsprovidrar. Du behöver också klientautentiseringsuppgifter för att använda attesteringsadministrationsklienten eller anropa API:et attestTpm . Klientautentiseringsuppgifter kräver (klient-ID, klienthemlighet, klient-ID) för att instansiera ett klientobjekt.

I det här avsnittet kommer vi att autentisera med autentiseringsuppgifter för klienthemligheter via DefaultAzureCredential-providern , men vi erbjuder fler autentiseringsmekanismer via paketet @azure/identitet . Så här installerar @azure/identity du paketet:

npm install @azure/identity

Skapa/hämta autentiseringsuppgifter

Använd Azure CLI-kodfragmentet nedan för att skapa/hämta autentiseringsuppgifter för klienthemligheter.

  • Skapa ett huvudnamn för tjänsten och konfigurera dess åtkomst till Azure-resurser:

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

    Utdata:

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

  • Anteckna tjänstens huvudnamn objectId

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

    Utdata:

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

  • Använd de returnerade autentiseringsuppgifterna ovan för att ange miljövariabler för AZURE_CLIENT_ID (appId), AZURE_CLIENT_SECRET (lösenord) och AZURE_TENANT_ID (klientorganisation). I följande exempel visas ett sätt att göra detta i PowerShell:

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

Mer information om Azure Identity-API:er och hur du använder dem finns i Azure Identity-klientbiblioteket

Viktiga begrepp

Det finns fyra huvudfamiljer med funktioner i den här förhandsversionen av SDK:et:

Microsoft Azure Attestation-tjänsten körs i två separata lägen: "Isolerad" och "AAD". När tjänsten körs i läget "Isolerad" måste kunden ange ytterligare information utöver sina autentiseringsuppgifter för att verifiera att de har behörighet att ändra tillståndet för en attesteringsinstans.

Slutligen stöder varje region där Microsoft Azure Attestation-tjänsten är tillgänglig en "delad" instans, som kan användas för att intyga SGX-enklaver som bara behöver verifiering mot Azure-baslinjen (det finns inga principer som tillämpas på den delade providern). TPM-attestering är inte tillgängligt i den delade providern. Den delade instansen kräver AAD-autentisering, men den har inga RBAC-principer – alla kunder med en giltig AAD-ägartoken kan intyga med den delade instansen.

Attestering

SGX- eller TPM-attestering är processen att verifiera bevis som samlas in från en betrodd körningsmiljö för att säkerställa att den uppfyller både Azure-baslinjen för den miljön och kunddefinierade principer som tillämpas på den miljön.

Identifiering och validering av attesteringstjänstens tokensigneringscertifikat

En av de viktigaste driftgarantierna för Azure Attestation Service är att tjänsten fungerar "operativt ur TCB". Med andra ord finns det inget sätt att en Microsoft-operatör kan manipulera driften av tjänsten eller skadade data som skickas från klienten. För att säkerställa den här garantin körs kärnan i attesteringstjänsten i en Intel(tm) SGX-enklav.

För att kunderna ska kunna kontrollera att åtgärder faktiskt utfördes i enklaven kodas de flesta svar från attesteringstjänsten i en JSON-webbtoken, som signeras av en nyckel som finns i attesteringstjänstens enklav.

Denna token signeras av ett signeringscertifikat som utfärdats av MAA-tjänsten för den angivna instansen.

Om MAA-tjänstinstansen körs i en region där tjänsten körs i en SGX-enklav kan certifikatet som utfärdas av servern verifieras med hjälp av oe_verify_attestation_certificate-API:et.

Objektet AttestationResponse innehåller två huvudattribut: token och value. Attributet token innehåller den fullständiga token som returneras av attesteringstjänsten. value Attributet innehåller brödtexten i JSON Web Token-svaret.

Principhantering

Varje attesteringstjänstinstans har en princip tillämpad på den som definierar ytterligare kriterier som kunden har definierat.

Mer information om attesteringsprinciper finns i Attesteringsprincip

Hantering av principhanteringscertifikat

När en attesteringsinstans körs i läget "Isolerad" har kunden som skapade instansen ett principhanteringscertifikat när instansen skapades. Alla principändringsåtgärder kräver att kunden signerar principdata med ett av de befintliga principhanteringscertifikaten. Api:erna för hantering av principhanteringscertifikat gör det möjligt för klienter att "rulla" principhanteringscertifikaten.

Isolerat läge och AAD-läge

Varje Microsoft Azure Attestation tjänstinstans fungerar antingen i "AAD"-läge eller "Isolerad"-läge. När en MAA-instans körs i AAD-läge innebär det att kunden som skapade attesteringsinstansen tillåter principer för Azure Active Directory- och Azure-rollbaserad åtkomstkontroll för att verifiera åtkomsten till attesteringsinstansen.

AttestationType

Microsoft Azure Attestation-tjänsten stöder attestering av olika typer av bevis beroende på miljö. För närvarande stöder MAA följande betrodda körningsmiljöer:

  • OpenEnclave – en Intel(tm)-processor som kör kod i en SGX-enklav där attesteringsbeviset samlades in med hjälp av OpenEnclave oe_get_report eller oe_get_evidence API:et.
  • SgxEnclave – en Intel(tm) processor som kör kod i en SGX Enclave där attesteringsbeviset samlades in med Intel SGX SDK.
  • Tpm – en virtualiseringsbaserad säkerhetsmiljö där processorns betrodda plattformsmodul används för att tillhandahålla attesteringsbevis.

Körningsdata och inittime-data

RuntimeData refererar till data som presenteras för genereringslogik för Intel SGX-citat eller oe_get_report/oe_get_evidence API:er. Om anroparen till attest-API:et angav ett runtime_data attribut verifierar Azure Attestation-tjänsten att de första 32 byteen report_data i fältet i SGX-citat/OE-rapport/OE-bevis matchar SHA256-hashen för runtime_data.

InitTime-data refererar till data som används för att konfigurera SGX-enklaven som ska intygas.

Observera att InitTime-data inte stöds på virtuella Datorer i Azure DCsv2-serien .

Ytterligare begrepp

Exempel

Skapa klientinstans

Skapar en instans av attesteringsklienten på uri endpointmed standardautentiseringsuppgifterna för Azure (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();

Om du inte anropar API:et attestTpm behöver du inte ange autentiseringsuppgifter för att få åtkomst till attesteringsklienten. Det innebär att en klient kan skapas helt enkelt med:

const client = new AttestationClient(endpoint);

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

Skapar en instans av attesteringsadministrationsklienten på uri endpoint.

Observera att administrationsklienten kräver autentiseringsuppgifter för Azure.

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

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

Hämta attesteringsprincip

Metoden getPolicy hämtar attesteringsprincipen från tjänsten. Attesteringsprinciper instanseras per attesteringstyp. Parametern AttestationType definierar vilken typ av instans som ska hämtas.

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

Ange en attesteringsprincip för en angiven attesteringstyp

Om attesteringstjänstinstansen körs i isolerat läge måste set_policy-API:et tillhandahålla ett signeringscertifikat (och en privat nyckel) som kan användas för att verifiera att anroparen har behörighet att ändra principen på attesteringsinstansen. Om tjänstinstansen körs i AAD-läge är signeringscertifikatet och nyckeln valfria.

Om tjänstinstansen körs i AAD-läge är anropet till setPolicy som förväntat:

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

Om tjänstinstansen körs i isolerat läge kräver anropet till setPolicy att klienten ska kunna bevisa att de har åtkomst till en av de privata nycklar och certifikat för principhantering.

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

Under omslagen skapar setPolicy-API:erna en JSON-webbtoken som innehåller i principdokumentet certificate och signeras med privateKey som sedan skickas till attesteringstjänsten.

Om en klient vill se till att dokumentet om attesteringsprincipen inte ändrades innan principdokumentet togs emot av attesteringstjänstens enklav, kan de använda egenskaperna som returneras i PolicyResult objct som kan användas för att verifiera att tjänsten tog emot principdokumentet:

  • policySigner - om anropet setPolicy inkluderade ett certificate, kommer det här värdet att vara certifikatet som angavs vid tidpunkten för anropet setPolicy . Om ingen principsignerare har angetts är detta null.
  • policyTokenHash – det här är hashen för JSON-webbsignaturen som skickas till tjänsten för setPolicy-API:et.

För att verifiera hashen kan klienter skapa en attesteringsprinciptoken (en hjälpklass som representerar den token som används för att ange attesteringsprincipen) och verifiera den hash som genereras från den 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 och Open Enclave

attestSgxEnclave Använd metoden för att intyga en SGX-enklaver.

En av de viktigaste utmaningarna som kunderna har när de interagerar med krypterade miljöer är att säkerställa att du på ett säkert sätt kan kommunicera med koden som körs i miljön ("enklaverkod").

En lösning på det här problemet är det som kallas "Secure Key Release", vilket är ett mönster som möjliggör säker kommunikation med enklaverkod.

För att implementera mönstret "Secure Key Release" genererar enklaverkoden en tillfällig asymmetrisk nyckel. Den serialiserar sedan den offentliga delen av nyckeln till något format (eventuellt en JSON-webbnyckel eller PEM eller något annat serialiseringsformat).

Enklavens kod beräknar sedan SHA256-värdet för den offentliga nyckeln och skickar den som indata till kod som genererar ett SGX-citat (för OpenEnclave är det oe_get_evidence eller oe_get_report).

Klienten skickar sedan SGX-offerten och den serialiserade nyckeln till attesteringstjänsten. Attesteringstjänsten validerar offerten och ser till att nyckelns hash finns i offerten och utfärdar en "attesteringstoken".

Klienten kan sedan skicka attesteringstoken (som innehåller den serialiserade nyckeln) till en tredje parts "förlitande part". Den förlitande parten verifierar sedan att attesteringstoken skapades av attesteringstjänsten, och därmed kan den serialiserade nyckeln användas för att kryptera vissa data som lagras av den "förlitande parten" för att skicka till tjänsten.

Det här exemplet visar ett vanligt mönster för att anropa till attesteringstjänsten för att hämta en attesteringstoken som är associerad med en begäran.

I det här exemplet förutsätts att du har ett befintligt AttestationClient objekt som är konfigurerat med attest-URI:n för slutpunkten. Det förutsätter också att du har en OpenEnclave-rapport (report) som genereras inifrån SGX-enklaven som du intygar och "Runtime Data" (binaryRuntimeData) som refereras till i SGX-citat.

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

Det är också möjligt att sändningen binaryRuntimeData till attesteringstjänsten är avsedd att tolkas som JSON-data. I så fall ska klienten ange runTimeJson i api-anropet för attest:

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

Om du använder Intel SDK för att generera en "offert" kan du verifiera offerten med hjälp av:

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

Ytterligare information om hur du utför validering av attesteringstoken finns i MAA-tjänstattesteringsexemplet.

Hämta tokencertifikat

Använd getSigningCertificates för att hämta certifikaten som kan användas för att verifiera token som returneras från attesteringstjänsten. Observera att det här anropet skapar en klient med Azure-autentiseringsuppgifter som inte behövs om du anropar API:erna attestSgxEnclave eller attestOpenEnclave

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

const attestationSigners = await client.getAttestationSigners();

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

Felsökning

De flesta attesteringstjänståtgärder genererar undantag som definierats i Azure Core. Attesteringstjänstens API:er utlöser ett RestError fel med användbara felkoder. Många av dessa fel kan återställas.

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

Loggning

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg över HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info. Du kan också aktivera loggning vid körning genom att anropa setLogLevel i @azure/logger:

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

setLogLevel("info");

Mer detaljerade anvisningar om hur du aktiverar loggar finns i @azure-/loggningspaketdokumenten.

Ytterligare felsökningsinformation för MAA-tjänsten finns här

Nästa steg

Mer information om Microsoft Azure Attestation-tjänsten finns på vår dokumentationssida.

Bidra

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns på webbplatsen för deltagarlicensavtalet.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla repor som använder vårt licensavtal för bidrag.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Läs Vanliga frågor och svar om uppförandekoden eller kontakta opencode@microsoft.com om du har några andra frågor eller kommentarer.

Mer information om hur du skapar, testar och bidrar till dessa bibliotek finns i CONTRIBUTING.md .

Ge feedback

Om du stöter på buggar eller har förslag kan du ange ett problem i avsnittet Problem i projektet.

Visningar