Sdílet prostřednictvím

Azure Attestation klientská knihovna pro JavaScript – verze 1.0.0

  • Článek

Služba Microsoft Azure Attestation (MAA) je jednotné řešení pro vzdálené ověřování důvěryhodnosti platformy a integrity binárních souborů, které jsou v ní spuštěné. Služba podporuje ověřování platforem podporovaných čipem TPM (Trusted Platform Modules) a možnost otestování stavu důvěryhodných prostředí spouštění (TEE), jako jsou enklávy Intel(tm) Software Guard Extensions (SGX) a enklávy založené na virtualizaci (VBS).

Ověření identity je proces pro prokázání správné instance softwarových binárních souborů na důvěryhodné platformě. Vzdálené předávající strany pak můžou získat jistotu, že na důvěryhodném hardwaru běží jenom takový zamýšlený software. Azure Attestation je jednotná služba a architektura určená pro zákazníky pro ověřování.

Azure Attestation umožňuje špičková paradigmata zabezpečení, jako je důvěrné výpočetní prostředí Azure a inteligentní ochrana hraničních zařízení. Zákazníci požadovali možnost nezávisle ověřit umístění počítače, stav virtuálního počítače na daném počítači a prostředí, ve kterém jsou na daném virtuálním počítači spuštěné enklávy. Azure Attestation umožní tyto a mnoho dalších požadavků zákazníků.

Azure Attestation přijímá důkazy z výpočetních entit, mění je na sadu deklarací identity, ověřuje je podle konfigurovatelných zásad a vytváří kryptografické důkazy pro aplikace založené na deklarací identity (například předávající strany a auditní autority).

Podrobnější zobrazení knihoven Azure najdete ve verzi typescriptu sady Azure SDK.

POZNÁMKA: Toto je verze Preview sady SDK pro službu Microsoft Azure Attestation. Poskytuje všechny základní funkce pro přístup ke službě Azure Attestation, měla by být považována za "tak, jak je" a v budoucnu může být změněna, což může narušit kompatibilitu s předchozími verzemi.

Klíčové odkazy:

Začínáme

Aktuálně podporovaná prostředí

  • LtS verze Node.js
  • Nejnovější verze prohlížečů Safari, Chrome, Edge a Firefox.

Další podrobnosti najdete v našich zásadách podpory .

Požadavky

  • Předplatné Azure
  • Existující instance Azure Attestation nebo můžete použít "sdíleného zprostředkovatele", který je k dispozici v každé oblasti Azure. Pokud potřebujete vytvořit instanci služby Azure Attestation, můžete použít Azure Portal nebo Azure CLI.

Nainstalujte balíček @azure/attestation.

Nainstalujte klientskou knihovnu Microsoft Azure Attestation pro JavaScript pomocí NPM:

npm install @azure/attestation

Ověření klienta

Aby bylo možné pracovat se službou Microsoft Azure Attestation, budete muset vytvořit instanci třídy klienta ověření identity nebo klienta správy ověření identity. Potřebujete adresu URL instance ověření identity, která bude buď identifikátor URI attestu zobrazený na portálu, nebo bude jedním ze sdílených poskytovatelů ověření identity. Budete také potřebovat přihlašovací údaje klienta, abyste mohli používat klienta pro správu ověření identity nebo volat attestTpm rozhraní API. Přihlašovací údaje klienta vyžadují (ID klienta, tajný klíč klienta, ID tenanta) k vytvoření instance objektu klienta.

V této části Začínáme budeme ověřovat pomocí přihlašovacích údajů tajného klíče klienta prostřednictvím zprostředkovatele DefaultAzureCredential , ale prostřednictvím balíčku @azure/identity nabízíme více mechanismů ověřování. Instalace @azure/identity balíčku:

npm install @azure/identity

Vytvoření nebo získání přihlašovacích údajů

Pomocí následujícího fragmentu kódu Azure CLI vytvořte nebo získejte přihlašovací údaje tajného klíče klienta.

  • Vytvořte instanční objekt a nakonfigurujte jeho přístup k prostředkům Azure:

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

    Výstup:

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

  • Poznamenejte si ID instančního objektu.

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

    Výstup:

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

  • Pomocí výše vrácených přihlašovacích údajů nastavte proměnné prostředí AZURE_CLIENT_ID (appId), AZURE_CLIENT_SECRET (heslo) a AZURE_TENANT_ID (tenant). Následující příklad ukazuje způsob, jak to udělat v PowerShellu:

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

Další informace o rozhraních API služby Azure Identity a jejich používání najdete v tématu Klientská knihovna Azure Identity.

Klíčové koncepty

Tato sada Preview SDK nabízí čtyři hlavní skupiny funkcí:

Služba Microsoft Azure Attestation běží ve dvou samostatných režimech: Izolované a AAD. Když je služba spuštěná v izolovaném režimu, musí zákazník zadat další informace nad rámec svých přihlašovacích údajů pro ověřování, aby ověřil, že má oprávnění ke změně stavu instance ověření identity.

A konečně každá oblast, ve které je služba Microsoft Azure Attestation k dispozici, podporuje "sdílenou" instanci, která se dá použít k otestování enkláv SGX, které vyžadují pouze ověření vůči směrnému plánu Azure (pro sdíleného poskytovatele se nepoužívají žádné zásady). Ověření identity čipem TPM není u sdíleného zprostředkovatele k dispozici. I když sdílená instance vyžaduje ověřování AAD, nemá žádné zásady RBAC – každý zákazník s platným nosným tokenem AAD může ověřit pomocí sdílené instance.

Attestation

Ověření identity SGX nebo TPM je proces ověřování důkazů shromážděných z důvěryhodného spouštěcího prostředí, aby se zajistilo, že splňují jak standardní hodnoty Azure pro dané prostředí, tak zásady definované zákazníkem pro toto prostředí.

Zjišťování a ověřování podpisového certifikátu tokenu služby ověření identity

Jednou ze základních provozních záruk služby Azure Attestation je, že služba funguje "provozně mimo TCB". Jinými slovy, neexistuje žádný způsob, jak by operátor Microsoftu mohl manipulovat s provozem služby nebo poškodit data odesílaná z klienta. Aby se zajistila tato záruka, jádro služby ověření identity běží v enklávě Intel(tm) SGX.

Aby mohli zákazníci ověřit, že operace byly skutečně provedeny uvnitř enklávy, většina odpovědí ze služby Ověření identity je zakódovaná do webového tokenu JSON, který je podepsaný klíčem uloženým v enklávě služby ověření identity.

Tento token se podepíše podpisovým certifikátem vystaveným službou MAA pro zadanou instanci.

Pokud je instance služby MAA spuštěná v oblasti, kde služba běží v enklávě SGX, je možné certifikát vystavený serverem ověřit pomocí rozhraní API oe_verify_attestation_certificate.

Objekt AttestationResponse obsahuje dva hlavní atributy: token a value. Atribut token obsahuje úplný token vrácený službou ověření identity, value atribut obsahuje tělo odpovědi webového tokenu JSON.

Správa zásad

Na každou instanci služby ověření identity se vztahují zásady, které definují další kritéria definovaná zákazníkem.

Další informace o zásadách ověření identity najdete v tématu Zásady ověření identity.

Správa certifikátů správy zásad

Pokud je instance ověření identity spuštěná v izolovaném režimu, zákazník, který instanci vytvořil, poskytne v okamžiku vytvoření instance certifikát pro správu zásad. Všechny operace úpravy zásad vyžadují, aby zákazník podepsal data zásad jedním z existujících certifikátů pro správu zásad. Rozhraní API pro správu certifikátů pro správu zásad umožňují klientům "roll" certifikáty pro správu zásad.

Izolovaný režim a režim AAD

Každá instance služby Microsoft Azure Attestation funguje buď v režimu AAD, nebo v izolovaném režimu. Pokud instance MAA funguje v režimu AAD, znamená to, že zákazník, který instanci ověření identity vytvořil, umožňuje službě Azure Active Directory a zásadám řízení přístupu na základě role Azure ověřit přístup k instanci ověření identity.

Typ ověření identity

Služba Microsoft Azure Attestation podporuje testování různých typů důkazů v závislosti na prostředí. V současné době MAA podporuje následující důvěryhodná spouštěcí prostředí:

  • OpenEnclave – procesor Intel(tm) se spuštěným kódem v enklávě SGX, kde byly důkazy o ověření shromážděny pomocí OpenEnclave oe_get_report nebo oe_get_evidence rozhraní API.
  • SgxEnclave – procesor Intel(tm) se spuštěným kódem v enklávě SGX, kde byly důkazy o ověření shromážděny pomocí sady Intel SGX SDK.
  • Tpm – prostředí zabezpečení založené na virtualizaci, ve kterém se k zajištění důkazů ověření identity používá modul Trusted Platform Module procesoru.

Data modulu runtime a data inicializačního času

RuntimeData odkazuje na data, která jsou prezentována do logiky generování citací Intel SGX nebo oe_get_report/oe_get_evidence rozhraní API. Pokud volající rozhraní API pro ověření poskytl runtime_data atribut, služba Azure Attestation ověří, že prvních 32 bajtů report_data pole v nabídce SGX, sestavě OE nebo důkazu OE odpovídá hodnotě runtime_datahash SHA256 .

Data InitTime odkazují na data, která se používají ke konfiguraci atestované enklávy SGX.

Upozorňujeme, že data InitTime se nepodporují na virtuálních počítačích Azure DCsv2-Series .

Další koncepty

Příklady

Vytvoření instance klienta

Vytvoří instanci klienta ověření identity na adrese URI endpointpomocí výchozích přihlašovacích údajů 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();

Pokud rozhraní API nevoláte attestTpm , nemusíte zadávat přihlašovací údaje pro přístup ke klientovi ověření identity. To znamená, že klienta je možné vytvořit jednoduše pomocí:

const client = new AttestationClient(endpoint);

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

Vytvoří instanci klienta pro správu ověření identity v URI endpoint.

Všimněte si, že klient pro správu vyžaduje přihlašovací údaje Azure.

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

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

Získání zásad ověření identity

Metoda getPolicy načte zásadu ověření identity ze služby. Zásady ověření identity jsou instanční na základě jednotlivých typů ověření identity, parametr AttestationType definuje typ instance, která se má načíst.

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

Nastavení zásad ověření identity pro zadaný typ ověření identity

Pokud instance služby ověření identity běží v izolovaném režimu, musí rozhraní SET_POLICY API poskytnout podpisový certifikát (a privátní klíč), který lze použít k ověření, že volající má oprávnění upravovat zásady v instanci ověření identity. Pokud instance služby běží v režimu AAD, podpisový certifikát a klíč jsou volitelné.

Pokud instance služby běží v režimu AAD, volání setPolicy je podle očekávání:

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

Pokud instance služby běží v izolovaném režimu, volání setPolicy vyžaduje, aby klient mohl prokázat, že má přístup k jednomu z privátních klíčů a certifikátů správy zásad.

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

Rozhraní SETPolicy API pod popisky vytvoří webový token JSON obsahující dokument certificate zásad a podepsaný pomocí privateKey příkazu, který se pak odešle službě ověření identity.

Pokud chce klient zajistit, aby se dokument zásad ověření identity před přijetím dokumentu zásad do enklávy služby ověření identity nezměnil, může použít vlastnosti vrácené v objektu PolicyResult , které lze použít k ověření, že služba přijala dokument zásad:

  • policySigner – pokud setPolicy volání obsahovalo certificate, bude tato hodnota certifikát poskytnutý v době setPolicy volání. Pokud nebyla nastavena žádná podepisující zásada, bude mít hodnotu null.
  • policyTokenHash – Toto je hodnota hash webového podpisu JSON odeslaného službě pro rozhraní SETPolicy API.

K ověření hodnoty hash můžou klienti vytvořit token zásad ověření identity (pomocnou třídu, která představuje token použitý k nastavení zásad ověření identity) a ověřit hodnotu hash vygenerovanou z daného tokenu:

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

Atest SGX a Open Enclave

Použijte metodu attestSgxEnclave k otestování enklávy SGX.

Jedním ze základních výzev, které zákazníci používají při interakci s šifrovanými prostředími, je zajistit bezpečnou komunikaci s kódem spuštěným v prostředí ("kód enklávy").

Jedním z řešení tohoto problému je to, co se označuje jako "Secure Key Release", což je vzor, který umožňuje zabezpečenou komunikaci s kódem enklávy.

Pro implementaci vzoru "Secure Key Release" vygeneruje kód enklávy dočasný asymetrický klíč. Potom serializuje veřejnou část klíče do nějakého formátu (možná webový klíč JSON, PEM nebo jiný formát serializace).

Kód enklávy pak vypočítá hodnotu SHA256 veřejného klíče a předá ji jako vstup do kódu, který vygeneruje citaci SGX (pro OpenEnclave to bude oe_get_evidence nebo oe_get_report).

Klient pak odešle nabídku SGX a serializovaný klíč službě ověření identity. Služba ověření identity ověří nabídku a ověří, že hodnota hash klíče je v uvozovce, a vydá token ověření identity.

Klient pak může tento token ověření identity (který obsahuje serializovaný klíč) odeslat třetí straně "předávající straně". Předávající strana pak ověří, že token ověření identity byl vytvořen službou ověření identity, a proto serializovaný klíč může být použit k šifrování některých dat uchovávaných "předávající stranou" k odeslání do služby.

Tento příklad ukazuje jeden běžný vzor volání do služby ověření identity za účelem načtení tokenu ověření identity přidruženého k požadavku.

V tomto příkladu se předpokládá, že máte existující AttestationClient objekt, který je nakonfigurovaný s identifikátorem URI attest pro váš koncový bod. Předpokládá také, že máte sestavu OpenEnclave (report) vygenerovanou z enklávy SGX, kterou ověřujete, a "Runtime Data" (binaryRuntimeData), na kterou odkazuje citace SGX.

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

Je také možné, že odeslání do služby ověření identity je zamýšleno tak, binaryRuntimeData aby bylo interpretováno jako data JSON. V takovém případě by klient měl runTimeJson zadat ve volání rozhraní API pro ověření:

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

Podobně pokud k vygenerování "nabídky" používáte sadu Intel SDK, můžete nabídku ověřit pomocí:

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

Další informace o tom, jak provést ověření tokenu ověření identity, najdete v ukázce ověření identity služby MAA.

Načtení certifikátů tokenů

Slouží getSigningCertificates k načtení certifikátů, které lze použít k ověření tokenu vráceného službou ověření identity. Upozorňujeme, že toto volání vytvoří klienta s přihlašovacími údaji Azure, které nejsou potřeba, pokud voláte attestSgxEnclave rozhraní API nebo attestOpenEnclave .

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

const attestationSigners = await client.getAttestationSigners();

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

Řešení potíží

Většina operací služby Ověření identity vyvolá výjimky definované v Azure Core. Rozhraní API služby ověřování identity způsobí RestError selhání s užitečnými kódy chyb. Mnoho z těchto chyb je možné obnovit.

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

protokolování

Povolení protokolování může pomoct odhalit užitečné informace o selháních. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou AZURE_LOG_LEVEL prostředí na info. Případně je možné protokolování povolit za běhu voláním setLogLevel v :@azure/logger

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

setLogLevel("info");

Podrobnější pokyny k povolení protokolů najdete v dokumentaci k balíčkům @azure/protokolovacího nástroje.

Další informace o řešení potíží pro službu MAA najdete tady.

Další kroky

Další informace o službě Microsoft Azure Attestation najdete na naší stránce dokumentace.

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete na webu Licenční smlouva pro přispěvatele.

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování. S případnými dalšími dotazy nebo připomínkami se obraťte na adresu opencode@microsoft.com.

Podrobnosti o sestavování, testování a přispívání do těchto knihoven najdete v CONTRIBUTING.md .

Zadání zpětné vazby

Pokud narazíte na nějaké chyby nebo máte návrhy, nahlaste problém v části Problémy projektu.

Imprese