Megosztás a következőn keresztül:

Azure Attestation JavaScript ügyfélkódtár – 1.0.0-s verzió

A Microsoft Azure Attestation (MAA) szolgáltatás egy egységes megoldás, amely távolról ellenőrzi a benne futó bináris fájlok platformjának megbízhatóságát és integritását. A szolgáltatás támogatja a megbízható platformmodulok (TPM-ek) által támogatott platformok igazolását, valamint a megbízható végrehajtási környezetek (TEE-k) állapotának igazolását, például az Intel(tm) Software Guard Extensions (SGX) enklávékat és a Virtualization-alapú biztonsági (VBS) enklávékat.

Az igazolás azt mutatja be, hogy a szoftver bináris fájljai megfelelően lettek példányosítva egy megbízható platformon. A távoli függő entitások ezután biztosak lehetnek abban, hogy csak az ilyen tervezett szoftverek futnak megbízható hardveren. Azure Attestation egy egységes ügyféloldali szolgáltatás és igazolási keretrendszer.

Azure Attestation olyan élvonalbeli biztonsági paradigmákat tesz lehetővé, mint az Azure Confidential Computing és az Intelligent Edge protection. Az ügyfelek azt kérték, hogy függetlenül ellenőrizzék a gép helyét, a virtuális gép (VM) állapotát a gépen, valamint azt a környezetet, amelyben enklávék futnak az adott virtuális gépen. Azure Attestation lehetővé teszi ezeket és számos további ügyfélkérést.

Azure Attestation bizonyítékokat kap a számítási entitásoktól, jogcímek készletévé alakítja őket, érvényesíti őket a konfigurálható szabályzatokkal szemben, és titkosítási bizonyítékokat állít elő a jogcímalapú alkalmazásokhoz (például függő entitásokhoz és naplózási hatóságokhoz).

Az Azure-kódtárak teljesebb megtekintéséhez tekintse meg az azure sdk typescript kiadását.

MEGJEGYZÉS: Ez egy előzetes verziójú SDK a Microsoft Azure Attestation szolgáltatáshoz. Az Azure Attestation szolgáltatás eléréséhez szükséges összes alapvető funkciót biztosítja, "aktuálisnak" kell tekinteni, és a jövőben olyan változásoknak kell alávetni, amelyek megszakíthatják a korábbi verziókkal való kompatibilitást.

Fő hivatkozások:

Első lépések

Jelenleg támogatott környezetek

További részletekért tekintse meg támogatási szabályzatunkat .

Előfeltételek

  • Azure-előfizetés
  • Meglévő Azure Attestation példány, vagy használhatja az egyes Azure-régiókban elérhető "megosztott szolgáltatót". Ha létre kell hoznia egy Azure Attestation szolgáltatáspéldányt, használhatja az Azure Portalt vagy az Azure CLI-t.

Telepítse a(z) @azure/attestation csomagot

Telepítse a JavaScripthez készült Microsoft Azure Attestation ügyfélkódtárat az NPM használatával:

npm install @azure/attestation

Az ügyfél hitelesítése

A Microsoft Azure Attestation szolgáltatás használatához létre kell hoznia egy példányt az Igazolási ügyfél vagy az Igazolási felügyelet ügyfélosztályból. Szüksége lesz egy igazolási példány URL-címére, amely a portálon látható "Attest URI" lesz, vagy az egyik megosztott igazolási szolgáltató lesz. Az igazolás-felügyeleti ügyfél használatához vagy az attestTpm API meghívásához ügyfél-hitelesítő adatokra is szüksége lesz. Az ügyfél-hitelesítő adatokhoz (ügyfélazonosító, titkos ügyfélkód, bérlőazonosító) szükség van egy ügyfélobjektum példányosításához.

Ebben az első lépések szakaszban az ügyfél titkos hitelesítő adatainak hitelesítését a DefaultAzureCredential szolgáltatón keresztül fogjuk használni, de további hitelesítési mechanizmusokat kínálunk a @azure/identitáscsomagon keresztül. A @azure/identity csomag telepítése:

npm install @azure/identity

Hitelesítő adatok létrehozása/lekérése

Az alábbi Azure CLI-kódrészlettel hozhat létre/kérhet le titkos ügyfélkód-hitelesítő adatokat.

  • Hozzon létre egy szolgáltatásnevet, és konfigurálja az Azure-erőforrásokhoz való hozzáférését:

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

    Kimenet:

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

  • Jegyezze fel a szolgáltatásnév objectId azonosítóját

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

    Kimenet:

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

  • A fenti visszaadott hitelesítő adatokkal állítsa be AZURE_CLIENT_ID (appId), AZURE_CLIENT_SECRET (jelszó) és AZURE_TENANT_ID (bérlői) környezeti változókat. Az alábbi példa bemutatja, hogyan teheti ezt meg a PowerShellben:

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

Az Azure Identity API-kkal és azok használatával kapcsolatos további információkért lásd: Azure Identity ügyfélkódtár

Fő fogalmak

Az előzetes verziójú SDK négy fő funkciócsaládot biztosít:

A Microsoft Azure Attestation szolgáltatás két külön módban fut: "Izolált" és "AAD". Ha a szolgáltatás "Izolált" módban fut, az ügyfélnek további információkat kell megadnia a hitelesítési hitelesítő adataikon kívül, hogy meggyőződjön arról, hogy jogosult egy igazolási példány állapotának módosítására.

Végül minden olyan régió, amelyben a Microsoft Azure Attestation szolgáltatás elérhető, támogatja a "megosztott" példányt, amely az olyan SGX-enklávék ellenőrzésére használható, amelyek csak az Azure alapkonfigurációján kell ellenőrzést végrehajtani (a megosztott szolgáltatóra nem vonatkoznak szabályzatok). A TPM-igazolás nem érhető el a megosztott szolgáltatóban. Bár a megosztott példányhoz AAD-hitelesítés szükséges, nem rendelkezik RBAC-szabályzatokkal – az érvényes AAD-tulajdonosi jogkivonattal rendelkező ügyfelek igazolhatják a megosztott példány használatát.

Igazolás

Az SGX- vagy TPM-igazolás egy megbízható végrehajtási környezetből gyűjtött bizonyítékok ellenőrzésének folyamata annak biztosítása érdekében, hogy az megfeleljen az adott környezet Azure-alapkonfigurációjának és az adott környezetre alkalmazott ügyfél által meghatározott szabályzatoknak.

Igazolási szolgáltatásjogkivonat-aláíró tanúsítvány felderítése és érvényesítése

A Azure Attestation Szolgáltatás egyik alapvető működési garanciája, hogy a szolgáltatás "a TCB-n kívül" működik. Más szóval, nincs mód arra, hogy egy Microsoft-operátor illetéktelenül módosítsa a szolgáltatás működését, vagy hogy az ügyféltől küldött adatok sérültek. A garancia biztosítása érdekében az igazolási szolgáltatás magja egy Intel(tm) SGX-enklávéban fut.

Annak érdekében, hogy az ügyfelek ellenőrizhessek, hogy a műveletek valóban az enklávéban történtek-e, az igazolási szolgáltatás legtöbb válasza egy JSON webes jogkivonatban van kódolva, amelyet az igazolási szolgáltatás enklávéjában tárolt kulcs ír alá.

Ezt a jogkivonatot a MAA szolgáltatás által a megadott példányhoz kiadott aláíró tanúsítvány fogja aláírni.

Ha a MAA-szolgáltatáspéldány olyan régióban fut, ahol a szolgáltatás egy SGX-enklávéban fut, akkor a kiszolgáló által kibocsátott tanúsítvány a oe_verify_attestation_certificate API-val ellenőrizhető.

Az AttestationResponse objektum két fő attribútumot tartalmaz: token és value. Az token attribútum tartalmazza az igazolási szolgáltatás által visszaadott teljes jogkivonatot, az value attribútum pedig a JSON webes jogkivonat-válasz törzsét.

Szabályzatkezelés

Minden igazolási szolgáltatáspéldányra érvényes egy szabályzat, amely az ügyfél által meghatározott további feltételeket határozza meg.

Az igazolási szabályzatokkal kapcsolatos további információkért lásd: Igazolási szabályzat

Policy Management tanúsítványkezelés

Ha egy igazolási példány "Izolált" módban fut, a példányt létrehozó ügyfél a példány létrehozásakor egy szabályzatkezelési tanúsítványt ad meg. Minden szabályzatmódosítási művelethez az ügyfélnek alá kell írnia a szabályzatadatokat az egyik meglévő szabályzatkezelési tanúsítvánnyal. A Házirendkezelési tanúsítványkezelési API-k lehetővé teszik az ügyfelek számára a szabályzatkezelési tanúsítványok "roll" használatát.

Izolált mód és AAD mód

Minden Microsoft Azure Attestation szolgáltatáspéldány "AAD" vagy "Izolált" módban működik. Ha egy MAA-példány AAD módban működik, az azt jelenti, hogy az igazolási példányt létrehozó ügyfél lehetővé teszi az Azure Active Directory és az Azure Szerepköralapú hozzáférés-vezérlési szabályzatok számára az igazolási példányhoz való hozzáférés ellenőrzését.

Igazolástípus

A Microsoft Azure Attestation szolgáltatás a környezettől függően különböző típusú bizonyítékok igazolását támogatja. A MAA jelenleg a következő megbízható végrehajtási környezeteket támogatja:

  • OpenEnclave – Egy kódot futtató Intel(tm) processzor egy SGX Enklávéban, ahol az igazolási bizonyítékokat az OpenEnclave oe_get_report vagy oe_get_evidence az API használatával gyűjtötték össze.
  • SgxEnclave – Egy kódot futtató Intel(tm) processzor egy SGX Enklávéban, ahol az igazolási bizonyítékokat az Intel SGX SDK használatával gyűjtötték össze.
  • Tpm – Virtualizáláson alapuló biztonsági környezet, amelyben a processzor Megbízható platform modulja szolgál az igazolási bizonyítékok biztosítására.

Futtatókörnyezeti adatok és inittime-adatok

A RuntimeData olyan adatokra utal, amelyek az Intel SGX idézőjel-létrehozási logikájában vagy az oe_get_report/oe_get_evidence API-kban jelennek meg. Ha az attest API hívója adott meg egy runtime_data attribútumot, a Azure Attestation szolgáltatás ellenőrzi, hogy az SGX Quote/OE Report/OE Evidence mező első 32 bájtja report_data megegyezik-e a runtime_datafájl SHA256 kivonatával.

Az InitTime-adatok azokat az adatokat jelentik, amelyek az igazolás alatt álló SGX-enklávé konfigurálására szolgálnak.

Vegye figyelembe, hogy az InitTime-adatok nem támogatottak az Azure DCsv2 sorozatú virtuális gépeken.

További fogalmak

Példák

Ügyfélpéldány létrehozása

Létrehozza az igazolási ügyfél egy példányát az uri-n endpointaz alapértelmezett Azure-beli hitelesítő adatokkal (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();

Ha nem hívja meg az attestTpm API-t, nem kell hitelesítő adatokat megadnia az igazolási ügyfél eléréséhez. Ez azt jelenti, hogy az ügyfél egyszerűen a következőkkel hozható létre:

const client = new AttestationClient(endpoint);

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

Létrehozza az Igazolási felügyeleti ügyfél egy példányát az uri-n endpoint.

Vegye figyelembe, hogy a felügyeleti ügyfélnek Azure-beli hitelesítő adatokra van szüksége .

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

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

Igazolási szabályzat lekérése

A getPolicy metódus lekéri az igazolási szabályzatot a szolgáltatásból. Az igazolási szabályzatok példányonkénti típusonként vannak megadva, a AttestationType paraméter határozza meg a lekérendő példány típusát.

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

Igazolási szabályzat beállítása egy megadott igazolási típushoz

Ha az igazolási szolgáltatáspéldány izolált módban fut, a set_policy API-nak meg kell adnia egy aláíró tanúsítványt (és titkos kulcsot), amely alapján ellenőrizheti, hogy a hívó jogosult-e módosítani a szabályzatot az igazolási példányon. Ha a szolgáltatáspéldány AAD módban fut, az aláíró tanúsítvány és a kulcs megadása nem kötelező.

Ha a szolgáltatáspéldány AAD módban fut, a setPolicy beállítása a várt módon történik:

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

Ha a szolgáltatáspéldány izolált módban fut, a setPolicy hívásához az ügyfélnek bizonyítania kell, hogy hozzáféréssel rendelkezik az egyik szabályzatkezelési titkos kulcshoz és tanúsítványhoz.

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

A borítók alatt a setPolicy API-k létrehoznak egy JSON-webjogkivonatot , amely tartalmazza a szabályzatdokumentumot certificate , és alá van írva az privateKey igazolási szolgáltatásnak.

Ha egy ügyfél meg szeretné győződni arról, hogy az igazolási szabályzat dokumentuma nem lett módosítva, mielőtt az igazolási szolgáltatás enklávéja megkapta volna a szabályzatdokumentumot, használhatja a PolicyResult objctban visszaadott tulajdonságokat, amelyek segítségével ellenőrizheti, hogy a szolgáltatás megkapta-e a szabályzatdokumentumot:

  • policySigner - ha a setPolicy hívás tartalmaz egy certificateértéket, akkor ez az érték lesz a hívás időpontjában setPolicy megadott tanúsítvány. Ha nincs beállítva szabályzat-aláíró, az null értékű lesz.
  • policyTokenHash - ez a setPolicy API szolgáltatásnak küldött JSON-webaláírás kivonata.

A kivonat ellenőrzéséhez az ügyfelek létrehozhatnak egy igazolási szabályzat jogkivonatát (egy segédosztályt, amely az igazolási szabályzat beállításához használt jogkivonatot jelöli), és ellenőrizhetik a jogkivonatból létrehozott kivonatot:

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

Az SGX igazolása és az Enklávé megnyitása

A metódus használatával attestSgxEnclave tanúsítsa az SGX-enklávét.

Az ügyfelek által a titkosított környezetekkel való kommunikáció egyik fő kihívása annak biztosítása, hogy biztonságosan kommunikálhasson a környezetben futó kóddal ("enklávé kód").

Erre a problémára az egyik megoldás az úgynevezett "Biztonságos kulcs kiadása", amely egy olyan minta, amely lehetővé teszi a biztonságos kommunikációt az enklávé kóddal.

A "Secure Key Release" minta implementálásához az enklávékód egy rövid élettartamú aszimmetrikus kulcsot hoz létre. Ezután szerializálja a kulcs nyilvános részét valamilyen formátumra (esetleg JSON-webkulcsra vagy PEM-re vagy más szerializálási formátumra).

Az enklávékód ezután kiszámítja a nyilvános kulcs SHA256-értékét, és bemenetként továbbítja azt a kódnak, amely SGX-idézőjelet hoz létre (OpenEnclave esetén ez a oe_get_evidence vagy oe_get_report).

Az ügyfél ezután elküldi az SGX-ajánlatot és a szerializált kulcsot az igazolási szolgáltatásnak. Az igazolási szolgáltatás ellenőrzi az árajánlatot, és meggyőződik arról, hogy a kulcs kivonata megtalálható az ajánlatban, és kiad egy "Igazolási jogkivonatot".

Az ügyfél ezután elküldheti ezt az igazolási jogkivonatot (amely tartalmazza a szerializált kulcsot) egy külső "függő entitásnak". A függő entitás ezután ellenőrzi, hogy az igazolási jogkivonatot az igazolási szolgáltatás hozta-e létre, és így a szerializált kulcs segítségével titkosíthatja a "függő entitás" által tárolt egyes adatokat a szolgáltatásnak való küldéshez.

Ez a példa az igazolási szolgáltatásba való behívás egyik gyakori mintáját mutatja be egy kérelemhez társított igazolási jogkivonat lekéréséhez.

Ez a példa feltételezi, hogy rendelkezik egy meglévő AttestationClient objektummal, amely a végpontHoz tartozó Attest URI-val van konfigurálva. Azt is feltételezi, hogy rendelkezik egy OpenEnclave-jelentéssel (report) az igazolni kívánt SGX-enklávéból, valamint a "Futtatókörnyezeti adatok" (binaryRuntimeData) jelentésből, amelyre az SGX-ajánlat hivatkozik.

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

Az is lehetséges, hogy az binaryRuntimeData igazolási szolgáltatásnak küldött adatokat JSON-adatokként kell értelmezni. Ebben az esetben az ügyfélnek meg kell adnia runTimeJson az attest API-hívásban:

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

Hasonlóképpen, ha az Intel SDK-t használja egy "idézőjel" létrehozásához, a következővel ellenőrizheti az árajánlatot:

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

Az igazolási jogkivonat érvényesítéséről további információt a MAA szolgáltatásigazolási mintájában talál.

Jogkivonat-tanúsítványok lekérése

A használatával getSigningCertificates lekérheti az igazolási szolgáltatásból visszaadott jogkivonat ellenőrzésére használható tanúsítványokat. Vegye figyelembe, hogy ez a hívás azure-beli hitelesítő adatokkal rendelkező ügyfelet hoz létre, amely nem szükséges a vagy attestOpenEnclave API-k attestSgxEnclave meghívásához

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

const attestationSigners = await client.getAttestationSigners();

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

Hibaelhárítás

A legtöbb igazolási szolgáltatásművelet kivételeket hoz létre az Azure Core-ban. Az igazolási szolgáltatás API-jai hasznos hibakódokkal jeleznek RestError hibát. Számos ilyen hiba helyreállítható.

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

Naplózás

A naplózás engedélyezése segíthet a hibákról szóló hasznos információk feltárásában. A HTTP-kérések és válaszok naplójának megtekintéséhez állítsa a környezeti változót a AZURE_LOG_LEVEL értékre info. A naplózás futásidőben is engedélyezhető a következő hívással setLogLevel@azure/logger:

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

setLogLevel("info");

A naplók engedélyezésére vonatkozó részletesebb útmutatásért tekintse meg a @azure/logger csomag dokumentációt.

A MAA szolgáltatással kapcsolatos további hibaelhárítási információk itt találhatók

Következő lépések

A Microsoft Azure Attestation szolgáltatással kapcsolatos további információkért tekintse meg dokumentációs oldalunkat.

Közreműködés

A projektben szívesen fogadjuk a hozzájárulásokat és a javaslatokat. A legtöbb hozzájáruláshoz el kell fogadnia egy Közreműködői licencszerződést (CLA-t), amelyben kijelenti, hogy jogosult arra, hogy ránk ruházza hozzájárulása felhasználási jogát, és ezt ténylegesen meg is teszi. A részletekért látogasson el a Közreműködői licencszerződés webhelyére.

A lekéréses kérelmek elküldésekor egy CLA-robot automatikusan meghatározza, hogy kell-e biztosítania CLA-t, és megfelelően kitölti a lekéréses kérelmet (például címke, megjegyzés). Egyszerűen csak kövesse a robot által megadott utasításokat. Ezt csak egyszer kell elvégeznie az összes olyan tárházban, amely a CLA-t használja.

A projekt a Microsoft nyílt forráskódú projekteket szabályozó etikai kódexe, a Microsoft Open Source Code of Conduct hatálya alá esik. További információért tekintse át a viselkedési szabályzat GYIK dokumentumát, illetve további kérdések vagy megjegyzések esetén írjon az opencode@microsoft.com e-mail-címre.

A kódtárak készítéséről, teszteléséről és közreműködéséről további információt a CONTRIBUTING.md talál.

Visszajelzés küldése

Ha bármilyen hibába ütközik, vagy javaslatai vannak, küldjön egy problémát a projekt Problémák szakaszában.

Megjelenések

  • Last updated on