Azure Attestation klientbibliotek för Python – version 1.0.0

Artikel
04/05/2023

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

Det här paketet har testats med Python 2.7, 3.6 till 3.9.

En mer fullständig vy över Azure-bibliotek finns på versionssidan för Azure SDK för Python.

Källkod | Paket (PyPI) | API-referensdokumentation | Produktdokumentation

Komma igång

Förutsättningar

En Azure-prenumeration. Om du vill använda Azure-tjänster, inklusive Azure Attestation-tjänsten, behöver du en prenumeration. Om du inte har ett befintligt Azure-konto kan du registrera dig för en kostnadsfri utvärderingsversion eller använda dina Visual Studio-prenumerationsförmåner när du skapar ett konto.
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 paketet

Installera Azure Attestation-klientbiblioteket för Python med PyPI:

pip install azure-security-attestation

Autentisera klienten

För att kunna interagera med Azure Attestation-tjänsten måste du skapa en instans av attesteringsklienten eller attesteringsadministrationsklientklassen. Du behöver en attesteringsslutpunkt som du kan se som "Attest URI" i portalen och klientautentiseringsuppgifter (klient-ID, klienthemlighet, klient-ID) för att instansiera ett klientobjekt.

Autentisering med klienthemligheter används i det här avsnittet för att komma igång, men du kan hitta fler sätt att autentisera med Azure-identitetspaketet. Om du vill använda DefaultAzureCredential-providern som visas nedan, eller andra leverantörer av autentiseringsuppgifter som medföljer Azure SDK, bör du installera paketet azure-identity:

pip 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:

SGX- och TPM-enklaverattestering.
Identifiering och validering av maa-attesteringstokensigneringscertifikat.
Attesteringsprinciphantering.
Certifikathanteringscertifikathantering för attesteringsprincip (ja, hantering av principer).

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 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 instansen). TPM-attestering är inte tillgängligt i den delade instansen. 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.

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

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

Skapa klientinstans

Skapar en instans av attesteringsklienten på uri endpoint.

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

Hämta attesteringsprincip

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

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

Under omslagen skapar SetPolicy-API:erna en JSON-webbtoken baserat på principdokumentet och signeringsinformationen som skickas till attesteringstjänsten.

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

Om tjänstinstansen körs i AAD-läge kan anropet till set_policy förenklas:

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)

Klienterna måste kunna kontrollera att dokumentet om attesteringsprincipen inte ändrades innan principdokumentet togs emot av attesteringstjänstens enklav.

Det finns två egenskaper i PolicyResult som kan användas för att verifiera att tjänsten tog emot principdokumentet:

policy_signer – om anropet set_policy innehöll ett signeringscertifikat är detta certifikatet som angavs vid tidpunkten för anropet set_policy . Om ingen principsignerare har angetts är detta null.
policy_token_hash – det här är hashen för JSON-webbtoken som skickas till tjänsten.

För att verifiera hashen kan klienter generera en attesteringsprinciptoken och verifiera hashen som genererats från den token:

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`

Attest SGX Enclave

Använd metoden attest_sgx_enclave för att intyga en SGX-enklav.

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.

Det här exemplet förutsätter att du har ett befintligt AttestationClient objekt som är konfigurerat med bas-URI:n för slutpunkten. Det förutsätter också att du har ett SGX-citat (quote) som genereras inifrån SGX-enklaven som du intygar och "Runtime Data" (runtime_data) som refereras till i SGX-citat.

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

Nu innehåller attributet enclave_held_data i attestationResult indatabinär runtime_data.

Token skickas nu till den förlitande parten. Den förlitande parten verifierar att token har utfärdats av attesteringstjänsten. Sedan extraheras den asymmetriska nyckeln från fältet EnclaveHeldData. Den förlitande parten krypterar sedan sina "nyckeldata" med hjälp av den asymmetriska nyckeln och överför dem tillbaka till enklaven.

encrypted_data = send_token_to_relying_party(attestationResult.Token)

Nu kan krypterade data skickas till enklaven som kan dekryptera dessa data.

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

Hämta tokencertifikat

Använd get_signing_certificates för att hämta certifikaten som kan användas för att verifiera token som returneras från attesteringstjänsten.

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)

Felsökning

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

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
}

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

Share via