Azure Attestation clientbibliotheek voor Python - versie 1.0.0

Artikel
04/05/2023

De MAA-service (Microsoft Azure Attestation) is een geïntegreerde oplossing voor het extern verifiëren van de betrouwbaarheid van een platform en de integriteit van de binaire bestanden die erin worden uitgevoerd. De service ondersteunt attestation van de platforms die worden ondersteund door Trusted Platform Modules (TPM's), naast de mogelijkheid om de status van Trusted Execution Environments (TEE's) te bevestigen, zoals Intel(tm) SGX-enclaves (Software Guard Extensions) en VBS-enclaves (Virtualization-Based Security).

Attestation is een proces voor het demonstreren dat de software-binaire bestanden op de juiste manier op een vertrouwd platform zijn geïnstantieerd. Externe relying party's kunnen dan betrouwbaarheid krijgen dat alleen dergelijke bedoelde software wordt uitgevoerd op vertrouwde hardware. Azure Attestation is een uniforme klantgerichte service en kader voor Attestation.

Met Azure Attestation kunnen geavanceerde beveiligingsmodellen, zoals Azure Confidential Computing en Intelligent Edge-beveiliging. Klanten hebben de mogelijkheid gevraagd om de locatie van een machine onafhankelijk te controleren, het postuur van een virtuele machine (VM) op die computer en de omgeving waarin enclaves op die VM worden uitgevoerd. Met Azure Attestation kunnen deze en vele bijkomende aanvragen van klanten worden gestimuleerd.

Azure Attestation ontvangt bewijs van berekeningsentiteiten, zet ze om in een set claims, valideert ze op basis van configureerbare beleidsregels en produceert cryptografische bewijzen voor op claims gebaseerde toepassingen (bijvoorbeeld relying party's en controle-instanties).

Dit pakket is getest met Python 2.7, 3.6 tot 3.9.

Zie de releasepagina van de Azure SDK voor Python voor een volledigere weergave van Azure-bibliotheken.

Broncode | Pakket (PyPI) | API-referentiedocumentatie | Productdocumentatie

Aan de slag

Vereisten

Een Azure-abonnement. Als u Azure-services wilt gebruiken, inclusief de Azure Attestation-service, hebt u een abonnement nodig. Als u geen bestaand Azure-account hebt, kunt u zich registreren voor een gratis proefversie of gebruikmaken van de voordelen van uw Visual Studio-abonnement wanneer u een account maakt.
Een bestaand Azure Attestation-exemplaar of u kunt de 'gedeelde provider' gebruiken die beschikbaar is in elke Azure-regio. Als u een Azure Attestation service-exemplaar wilt maken, kunt u azure portal of Azure CLI gebruiken.

Het pakket installeren

Installeer de Azure Attestation-clientbibliotheek voor Python met PyPI:

pip install azure-security-attestation

De client verifiëren

Als u wilt communiceren met de Azure Attestation-service, moet u een exemplaar van de klasse Attestation Client of Attestation Administration Client maken. U hebt een attestation-eindpunt nodig, dat u mogelijk ziet als 'Attest URI' in de portal, en clientreferenties (client-id, clientgeheim, tenant-id) om een clientobject te instantiëren.

Verificatie van clientgeheimreferenties wordt gebruikt in deze sectie Aan de slag, maar u kunt meer manieren vinden om te verifiëren met het Azure-identiteitspakket. Als u de hieronder weergegeven DefaultAzureCredential-provider of andere referentieproviders wilt gebruiken die bij de Azure SDK worden geleverd, moet u het pakket azure-identity installeren:

pip install azure-identity

Referenties maken/ophalen

Gebruik het onderstaande Azure CLI-fragment om referenties voor clientgeheimen te maken/op te halen.

Een service-principal maken en de toegang tot Azure-resources configureren:

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

Uitvoer:

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

Noteer de objectId van de service-principal

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

Uitvoer:

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

Gebruik de bovenstaande geretourneerde referenties om omgevingsvariabelen AZURE_CLIENT_ID (appId), AZURE_CLIENT_SECRET (wachtwoord) en AZURE_TENANT_ID (tenant) in te stellen. In het volgende voorbeeld ziet u een manier om dit te doen in PowerShell:
```
$Env:AZURE_CLIENT_ID="generated-app-ID"
$Env:AZURE_CLIENT_SECRET="random-password"
$Env:AZURE_TENANT_ID="tenant-ID"
```

Zie Azure Identity-clientbibliotheek voor meer informatie over de Azure Identity-API's en hoe u deze gebruikt

Belangrijkste concepten

Deze preview-SDK bevat vier belangrijke functionaliteitsfamilies:

Attestation van SGX- en TPM-enclave.
Detectie en validatie van certificaat voor MAA Attestation Token-ondertekening.
Attestation-beleidsbeheer.
Certificaatbeheer voor attestation-beleidsbeheer (ja, beleidsbeheer).

De Microsoft Azure Attestation-service wordt uitgevoerd in twee afzonderlijke modi: 'Isolated' en 'AAD'. Wanneer de service wordt uitgevoerd in de geïsoleerde modus, moet de klant naast de verificatiereferenties aanvullende informatie opgeven om te controleren of ze gemachtigd zijn om de status van een attestation-exemplaar te wijzigen.

Ten slotte ondersteunt elke regio waarin de Azure Attestation-service beschikbaar is een 'gedeeld' exemplaar, dat kan worden gebruikt om SGX-enclaves te bevestigen waarvoor alleen verificatie op basis van de Azure-basislijn nodig is (er worden geen beleidsregels toegepast op het gedeelde exemplaar). TPM-attestation is niet beschikbaar in het gedeelde exemplaar. Hoewel het gedeelde exemplaar AAD-verificatie vereist, heeft het geen RBAC-beleid. Elke klant met een geldig AAD Bearer-token kan bevestigen met behulp van het gedeelde exemplaar.

Attestation

SGX- of TPM-attestation is het proces van het valideren van bewijs dat is verzameld uit een vertrouwde uitvoeringsomgeving om ervoor te zorgen dat deze voldoet aan zowel de Azure-basislijn voor die omgeving als het door de klant gedefinieerde beleid dat op die omgeving wordt toegepast.

Detectie en validatie van certificaat voor tokenondertekening van attestation-service

Een van de belangrijkste operationele garanties van de Azure Attestation Service is dat de dienst "operationeel buiten de TCB" opereert. Met andere woorden, er is geen manier waarop een Microsoft-operator kan knoeien met de werking van de service of gegevens kan beschadigen die vanaf de client worden verzonden. Om deze garantie te garanderen, wordt de kern van de attestation-service uitgevoerd in een Intel(tm) SGX-enclave.

Om klanten in staat te stellen te controleren of bewerkingen daadwerkelijk in de enclave zijn uitgevoerd, worden de meeste antwoorden van de Attestation-service gecodeerd in een JSON-webtoken, dat is ondertekend door een sleutel die is opgeslagen in de enclave van de Attestation-service.

Dit token wordt ondertekend door een handtekeningcertificaat dat is uitgegeven door de MAA-service voor het opgegeven exemplaar.

Als het MAA-service-exemplaar wordt uitgevoerd in een regio waarin de service wordt uitgevoerd in een SGX-enclave, kan het certificaat dat door de server is uitgegeven, worden geverifieerd met behulp van de oe_verify_attestation_certificate-API.

Beleidsbeheer

Op elk attestation-service-exemplaar wordt een beleid toegepast dat aanvullende criteria definieert die de klant heeft gedefinieerd.

Zie Attestation-beleid voor meer informatie over Attestation-beleid

Certificaatbeheer voor beleidsbeheer

Wanneer een attestation-exemplaar wordt uitgevoerd in de geïsoleerde modus, heeft de klant die het exemplaar heeft gemaakt een certificaat voor beleidsbeheer opgegeven op het moment dat het exemplaar wordt gemaakt. Alle beleidswijzigingsbewerkingen vereisen dat de klant de beleidsgegevens ondertekent met een van de bestaande beleidsbeheercertificaten. Met de API's voor certificaatbeheer voor beleidsbeheer kunnen clients de beleidsbeheercertificaten 'rollen'.

Geïsoleerde modus en AAD-modus

Elk Microsoft Azure Attestation-service-exemplaar werkt in de AAD-modus of in de geïsoleerde modus. Wanneer een MAA-exemplaar in de AAD-modus werkt, betekent dit dat de klant die het attestation-exemplaar heeft gemaakt, toegangsbeheerbeleidsregels op basis van Azure Active Directory en Azure-rollen toestaat om de toegang tot het attestation-exemplaar te verifiëren.

AttestationType

De Azure Attestation-service ondersteunt het bevestigen van verschillende soorten bewijs, afhankelijk van de omgeving. Momenteel ondersteunt MAA de volgende omgevingen voor vertrouwde uitvoering:

OpenEnclave - Een Intel(tm) Processor die code uitvoert in een SGX-enclave waar het attestation-bewijs is verzameld met behulp van de OpenEnclave oe_get_report of oe_get_evidence API.
SgxEnclave - Een Intel(tm) Processor die code uitvoert in een SGX-enclave waar het attestation-bewijs is verzameld met behulp van de Intel SGX SDK.
Tpm: een op virtualisatie gebaseerde beveiligingsomgeving waarin de Trusted Platform Module van de processor wordt gebruikt om het attestation-bewijs te leveren.

Runtime-gegevens en Inittime-gegevens

RuntimeData verwijst naar gegevens die worden gepresenteerd aan de Intel SGX Quote Generation-logica of de oe_get_report/oe_get_evidence API's. Als de aanroeper voor de attest-API een runtime_data kenmerk heeft opgegeven, valideert de Azure Attestation-service dat de eerste 32 bytes van het report_data veld in het SGX Quote/OE Report/OE Evidence overeenkomen met de SHA256-hash van de runtime_data.

InitTime-gegevens verwijzen naar gegevens die worden gebruikt voor het configureren van de SGX-enclave die wordt getest.

Houd er rekening mee dat InitTime-gegevens niet worden ondersteund op virtuele machines uit de Azure DCsv2-serie .

Aanvullende concepten

Clientexemplaren maken

Hiermee maakt u een exemplaar van de Attestation-client op URI endpoint.

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

Attestation-beleid ophalen

Met set_policy de methode wordt het attestation-beleid opgehaald uit de service. Attestation-beleid wordt per attestation-type opgeslagen. De AttestationType parameter definieert het type dat moet worden opgehaald.

policy, token = attest_client.get_policy(AttestationType.SGX_ENCLAVE)
print('Instance SGX policy: ', policy)
print('Token: ', token)

Een attestation-beleid instellen voor een opgegeven attestation-type

Als het exemplaar van de attestation-service wordt uitgevoerd in de geïsoleerde modus, moet de api van set_policy een handtekeningcertificaat (en een persoonlijke sleutel) opgeven die kan worden gebruikt om te valideren dat de aanroeper is gemachtigd om beleid voor het attestation-exemplaar te wijzigen. Als het service-exemplaar wordt uitgevoerd in de AAD-modus, zijn het handtekeningcertificaat en de sleutel optioneel.

De SetPolicy-API's maken een JSON-webtoken op basis van het beleidsdocument en de ondertekeningsgegevens die naar de Attestation-service worden verzonden.

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

Als het service-exemplaar wordt uitgevoerd in de AAD-modus, kan de aanroep naar set_policy worden vereenvoudigd:

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)

Clients moeten kunnen controleren of het attestation-beleidsdocument niet is gewijzigd voordat het beleidsdocument is ontvangen door de enclave van de Attestation-service.

PolicyResult bevat twee eigenschappen die kunnen worden gebruikt om te controleren of de service het beleidsdocument heeft ontvangen:

policy_signer : als de set_policy aanroep een handtekeningcertificaat bevat, is dit het certificaat dat is opgegeven op het moment van de set_policy aanroep. Als er geen beleids ondertekenaar is ingesteld, is dit null.
policy_token_hash : dit is de hash van het JSON-webtoken dat naar de service is verzonden.

Om de hash te controleren, kunnen clients een attestation-beleidstoken genereren en de hash controleren die op die token is gegenereerd:

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

Gebruik de methode attest_sgx_enclave om een SGX-enclave te bevestigen.

Een van de belangrijkste uitdagingen voor klanten bij de interactie met versleutelde omgevingen is hoe u veilig kunt communiceren met de code die in de omgeving wordt uitgevoerd ('enclavecode').

Een oplossing voor dit probleem is wat bekend staat als 'Secure Key Release', een patroon dat beveiligde communicatie met enclavecode mogelijk maakt.

Als u het patroon 'Secure Key Release' wilt implementeren, genereert de enclavecode een kortstondige asymmetrische sleutel. Vervolgens wordt het openbare gedeelte van de sleutel geserialiseerd naar een bepaalde indeling (mogelijk een JSON-websleutel of PEM of een andere serialisatie-indeling).

De enclavecode berekent vervolgens de SHA256-waarde van de openbare sleutel en geeft deze door als invoer voor code die een SGX-offerte genereert (voor OpenEnclave is dat de oe_get_evidence of oe_get_report).

De client verzendt vervolgens de SGX-offerte en de geserialiseerde sleutel naar de attestation-service. De attestation-service valideert de offerte en zorgt ervoor dat de hash van de sleutel aanwezig is in de offerte en geeft een Attestation-token uit.

De client kan vervolgens dat Attestation-token (dat de geserialiseerde sleutel bevat) verzenden naar een 'relying party' van derden. De relying party valideert vervolgens dat het attestation-token is gemaakt door de attestation-service, en dus kan de geserialiseerde sleutel worden gebruikt voor het versleutelen van bepaalde gegevens die door de relying party worden bewaard en naar de service worden verzonden.

In dit voorbeeld ziet u een veelvoorkomend patroon voor het aanroepen van de Attestation-service om een attestation-token op te halen dat is gekoppeld aan een aanvraag.

In dit voorbeeld wordt ervan uitgegaan dat u een bestaand AttestationClient object hebt dat is geconfigureerd met de basis-URI voor uw eindpunt. Er wordt ook van uitgegaan dat u een SGX-offerte (quote) hebt gegenereerd vanuit de SGX-enclave die u bevestigt, en 'Runtime-gegevens' (runtime_data) waarnaar wordt verwezen in de SGX-offerte.

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

Op dit punt bevat het kenmerk enclave_held_data in attestationResult het binaire invoerbestand runtime_data.

Het token wordt nu doorgegeven aan de relying party. De relying party valideert dat het token is uitgegeven door de Attestation-service. Vervolgens wordt de asymmetrische sleutel geëxtraheerd uit het veld EnclaveHeldData. De relying party versleutelt vervolgens de 'sleutel'-gegevens met behulp van de asymmetrische sleutel en verzendt deze terug naar de enclave.

encrypted_data = send_token_to_relying_party(attestationResult.Token)

Nu kunnen de versleutelde gegevens worden doorgegeven aan de enclave die die gegevens kan ontsleutelen.

Meer informatie over het uitvoeren van attestation-tokenvalidatie vindt u in het MAA Service Attestation-voorbeeld.

Tokencertificaten ophalen

Gebruik get_signing_certificates om de certificaten op te halen die kunnen worden gebruikt om het token te valideren dat is geretourneerd door de attestation-service.

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)

Problemen oplossen

De meeste Attestation-servicebewerkingen genereren uitzonderingen die zijn gedefinieerd in Azure Core. De attestation-service-API's genereren een HttpResponseError fout met nuttige foutcodes. Veel van deze fouten kunnen worden hersteld.

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
}

Aanvullende informatie over probleemoplossing voor de MAA-service vindt u hier

Volgende stappen

Zie onze documentatiepagina voor meer informatie over de Microsoft Azure Attestation-service.

Bijdragen

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga voor meer informatie naar de site met de licentieovereenkomst voor inzenders.

Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit maar eenmaal te doen voor alle repo's waar gebruik wordt gemaakt van onze CLA.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Raadpleeg voor meer informatie de veelgestelde vragen over de gedragscode of neem contact op met opencode@microsoft.com als u aanvullende vragen of opmerkingen hebt.

Zie CONTRIBUTING.md voor meer informatie over het bouwen, testen en bijdragen aan deze bibliotheken.

Feedback geven

Als u fouten tegenkomt of suggesties hebt, kunt u een probleem melden in de sectie Problemen van het project.

Weergaven

Delen via