Azure Attestation klientské knihovny pro Python – verze 1.0.0

Článek
04/05/2023

Služba Microsoft Azure Attestation (MAA) je jednotné řešení pro vzdálené ověření důvěryhodnosti platformy a integrity binárních souborů, které v ní běží. Služba podporuje ověřování platforem, které jsou podporovány čipy TPM (Trusted Platform Modules) a schopnost osvědčovat stav prostředí důvěryhodného 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, který demonstruje, že se na důvěryhodné platformě správně vytvořily binární soubory softwaru. 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 pro ověřování identity pro zákazníky.

Azure Attestation umožňuje špičková paradigmata zabezpečení, jako je důvěrné výpočetní prostředí Azure a inteligentní ochrana Edge. 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í těmto a mnoha dalším zákaznickým požadavkům.

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 autority auditování).

Tento balíček byl testován s Pythonem 2.7, 3.6 až 3.9.

Podrobnější zobrazení knihoven Azure najdete na stránce s vydáním sady Azure SDK pro Python.

Zdrojový kód | Balíček (PyPI) | Referenční dokumentace k | rozhraní API Dokumentace k produktu

Začínáme

Požadavky

Předplatné Azure. Abyste mohli používat služby Azure, včetně služby Azure Attestation, budete potřebovat předplatné. Pokud nemáte existující účet Azure, můžete si při vytváření účtu zaregistrovat bezplatnou zkušební verzi nebo využít výhody předplatného sady Visual Studio.
Existující Azure Attestation instance nebo můžete použít sdíleného poskytovatele dostupného v každé oblasti Azure. Pokud potřebujete vytvořit instanci služby Azure Attestation, můžete použít Azure Portal nebo Azure CLI.

Instalace balíčku

Nainstalujte klientskou knihovnu Azure Attestation pro Python pomocí PyPI:

pip install azure-security-attestation

Ověření klienta

Abyste mohli pracovat se službou Azure Attestation, budete muset vytvořit instanci klientské třídy Klient ověření identity nebo Správa ověření identity. K vytvoření instance objektu klienta potřebujete koncový bod ověření identity, který se na portálu může zobrazit jako Identifikátor URI atestu, a přihlašovací údaje klienta (ID klienta, tajný klíč klienta, ID tenanta).

Ověřování přihlašovacích údajů pomocí tajného klíče klienta se používá v této části Začínáme, ale můžete najít další způsoby ověřování pomocí balíčku identit Azure. Pokud chcete použít zprostředkovatele DefaultAzureCredential uvedeného níže nebo jiné zprostředkovatele přihlašovacích údajů poskytované se sadou Azure SDK, měli byste nainstalovat balíček azure-identity:

pip install azure-identity

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

K vytvoření nebo získání přihlašovacích údajů tajného klíče klienta použijte následující fragment kódu Azure CLI .

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 objektu instančního objektu.

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

Výstup:

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

Výše uvedené přihlašovací údaje použijte k nastavení proměnných 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žití najdete v tématu Klientská knihovna identit Azure.

Klíčové koncepty

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

Ověření identity enklávy SGX a TPM.
Zjišťování a ověřování podpisového certifikátu tokenu MAA
Správa zásad ověření identity.
Správa certifikátů pro správu zásad ověření identity (ano, správa zásad).

Služba Microsoft Azure Attestation běží ve dvou samostatných režimech: Izolované a AAD. Pokud je služba spuštěná v izolovaném režimu, musí zákazník poskytnout další informace nad rámec svých přihlašovacích údajů 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 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í podle standardních hodnot Azure (na sdílenou instanci se nepoužívají žádné zásady). Ověření identity TPM není ve sdílené instanci 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 dané 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 odeslaná z klienta. Pro zajištění této záruky běží jádro služby ověření identity v enklávě Intel(tm) SGX.

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

Tento token bude podepsán 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 vydaný serverem ověřit pomocí rozhraní API oe_verify_attestation_certificate.

Správa zásad

Každá instance služby ověřování identity má na ni použitou zásadu, která definuje 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 při vytvoření instance certifikát pro správu zásad. Všechny operace úprav zásad vyžadují, aby zákazník podepsal data zásad pomocí některého z existujících certifikátů pro správu zásad. Rozhraní API pro správu certifikátů správy zásad umožňují klientům "vyrolovat" 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 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) s kódem v enklávě SGX, kde byly důkazy o ověření shromažďovány pomocí rozhraní OpenEnclave oe_get_report nebo oe_get_evidence API.
SgxEnclave – procesor Intel(tm) s kódem v enklávě SGX, kde byly shromážděny důkazy ověření pomocí sady Intel SGX SDK.
Tpm – prostředí zabezpečení založené na virtualizaci, ve kterém se k poskytnutí důkazu o ověření používá modul Trusted Platform Module procesoru.

Data modulu runtime a inicializační data

RuntimeData odkazuje na data, která jsou prezentována do logiky generování nabídek Intel SGX nebo oe_get_report/oe_get_evidence rozhraní API. Pokud volající rozhraní API pro ověření zadal runtime_data atribut, služba Azure Attestation ověří, že prvních 32 bajtů report_data pole v SGX Quote/ OE Report/ OE Evidence odpovídá hodnotě hash runtime_dataSHA256 .

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

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

Další koncepty

Příklady

Vytvoření instance klienta ověření identity
Atestování enklávy SGX
Získání zásad ověření identity
Načtení ověřovacích certifikátů tokenů
Vytvoření instance klienta ověření identity

Vytvoření instance klienta

Vytvoří instanci klienta ověření identity v identifikátoru URI endpoint.

attest_client = AttestationClient(
    endpoint=base_uri,
    credential=DefaultAzureCredential())

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

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

policy, token = attest_client.get_policy(AttestationType.SGX_ENCLAVE)
print('Instance SGX policy: ', policy)
print('Token: ', 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é.

Na pozadí rozhraní API SetPolicy vytvoří webový token JSON na základě dokumentu zásad a podpisových informací, které se odesílají službě ověření identity.

policy_set_response = attest_client.set_policy(AttestationType.SGX_ENCLAVE,
    attestation_policy,
    signing_key=key,
    signing_certificate=signing_certificate)
new_policy, _ = attest_client.get_policy(AttestationType.SGX_ENCLAVE)
# `new_policy` will equal `attestation_policy`.

Pokud je instance služby spuštěná v režimu AAD, můžete zjednodušit volání set_policy:

policy_set_response = attest_client.set_policy(AttestationType.SGX_ENCLAVE,            
    attestation_policy)
# Now retrieve the policy which was just set.
new_policy, _ = attest_client.get_policy(AttestationType.SGX_ENCLAVE)

Klienti musí být schopni ověřit, že dokument zásad ověření identity nebyl změněn před přijetím dokumentu zásad enklávem služby ověření identity.

PolicyResult obsahuje dvě vlastnosti, které je možné použít k ověření, že služba přijala dokument zásad:

policy_signer – pokud set_policy volání obsahovalo podpisový certifikát, bude to certifikát poskytnutý v době set_policy volání. Pokud nebyla nastavena žádná podepisující zásada, bude mít hodnotu null.
policy_token_hash – jedná se o hodnotu hash webového tokenu JSON odeslaného službě.

K ověření hodnoty hash můžou klienti vygenerovat token zásad ověření identity a ověřit hodnotu hash vygenerovanou z daného tokenu:

from cryptography.hazmat.primitives import hashes

expected_policy = AttestationPolicyToken(
    attestation_policy,
    signing_key=key,
    signing_certificate=signing_certificate)
hasher = hashes.Hash(hashes.SHA256())
hasher.update(expected_policy.serialize().encode('utf-8'))
expected_hash = hasher.finalize()

# `expected_hash` will exactly match `policy_set_response.policy_token_hash`

Atest SGX Enkláva

K otestování enklávy SGX použijte metodu attest_sgx_enclave .

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ý pomocí základního identifikátoru URI pro váš koncový bod. Předpokládá také, že máte vygenerovanou citaci SGX (quote) z enklávy SGX, kterou ověřujete, a "Runtime Data" (runtime_data), která je odkazována v citaci SGX.

response, token = attest_client.attest_sgx_enclave(quote, runtime_data=runtime_data)

V tomto okamžiku bude atribut enclave_held_data v attestationResult obsahovat vstupní binární runtime_data.

Token se teď předává předávající straně. Předávající strana ověří, že token vydala služba ověření identity. Potom extrahuje asymetrický klíč z pole EnclaveHeldData. Předávající strana pak zašifruje data "klíče" pomocí asymetrického klíče a přenese je zpět do enklávy.

encrypted_data = send_token_to_relying_party(attestationResult.Token)

Šifrovaná data se teď dají předat do enklávy, která je může dešifrovat.

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ží get_signing_certificates k načtení certifikátů, které lze použít k ověření tokenu vráceného službou ověření identity.

signers = attest_client.get_signing_certificates()
for signer in signers:
    from cryptography.hazmat.backends import default_backend
    cert = cryptography.x509.load_pem_x509_certificate(signer.certificates[0].encode('ascii'), backend=default_backend())
    print('Cert  iss:', cert.issuer, '; subject:', cert.subject)

Poradce při potížích

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í HttpResponseError selhání s užitečnými kódy chyb. Mnoho z těchto chyb je možné obnovit.

try:
    response, _ = attest_client.attest_sgx_enclave(
        quote,
        runtime_data=AttestationData(runtime_data, is_json=False))
except HttpResponseError as ex:
    # Ignore invalid quote errors.
    if ex.error == "InvalidParameter":
        pass
}

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

Sdílet prostřednictvím