libreria client attestazione di Azure per Python - versione 1.0.0

Il servizio Microsoft attestazione di Azure (MAA) è una soluzione unificata per verificare in remoto l'attendibilità di una piattaforma e l'integrità dei file binari in esecuzione al suo interno. Il servizio supporta l'attestazione delle piattaforme supportate da TPM (Trusted Platform Modules) insieme alla possibilità di attestare lo stato degli ambienti di esecuzione attendibili (TEE), ad esempio enclave Intel(tm) Software Guard Extensions (SGX) e enclave di sicurezza basata su virtualizzazione (VBS).

L'attestazione è un processo per dimostrare che siano state create istanze corrette dei binari software in una piattaforma attendibile. Le relying party remote possono quindi avere la certezza che solo tale software previsto venga eseguito su hardware attendibile. Attestazione di Azure è un servizio e framework unificato rivolto ai clienti per l'attestazione.

Attestazione di Azure rende disponibili paradigmi di sicurezza all'avanguardia, ad esempio il confidential computing di Azure e la protezione delle reti perimetrali intelligenti. I clienti chiedono di avere la possibilità di verificare in modo indipendente la posizione di un computer, la postura di una macchina virtuale (VM) in tale computer e l'ambiente in cui sono in esecuzione le enclavi nella VM. Attestazione di Azure risponde a queste e a molte altre richieste dei clienti.

Attestazione di Azure riceve evidenze dalle entità di calcolo, le converte in un set di attestazioni, le convalida in base a criteri configurabili e genera prove crittografiche per le applicazioni basate su attestazioni (ad esempio, relying party e autorità di controllo).

Questo pacchetto è stato testato con Python 2.7, da 3.6 a 3.9.

Per una visualizzazione più completa delle librerie di Azure, vedere la pagina della versione di Azure SDK per Python.

Codice | sorgente Pacchetto (PyPI) | Documentazione | di riferimento sulle APIDocumentazione del prodotto

Introduzione

Prerequisiti

• Una sottoscrizione di Azure. Per usare i servizi di Azure, incluso il servizio attestazione di Azure, è necessaria una sottoscrizione. Se non si ha un account Azure esistente, è possibile iscriversi per ottenere una versione di valutazione gratuita o usare i vantaggi della sottoscrizione di Visual Studio quando si crea un account.
• Un'istanza di attestazione di Azure esistente oppure è possibile usare il "provider condiviso" disponibile in ogni area di Azure. Se è necessario creare un'istanza del servizio attestazione di Azure, è possibile usare il portale di Azure o l'interfaccia della riga di comando di Azure.

Installare il pacchetto

Installare la libreria client attestazione di Azure per Python con PyPI:

pip install azure-security-attestation

Autenticare il client

Per interagire con il servizio attestazione di Azure, è necessario creare un'istanza della classe Client di attestazione o del client di amministrazione attestazione. È necessario un endpoint di attestazione, che può essere visualizzato come "URI di attestazione" nel portale e le credenziali client (ID client, segreto client, ID tenant) per creare un'istanza di un oggetto client.

L'autenticazione delle credenziali del segreto client viene usata in questa sezione introduttiva, ma è possibile trovare altri modi per eseguire l'autenticazione con il pacchetto di identità di Azure. Per usare il provider DefaultAzureCredential illustrato di seguito o altri provider di credenziali forniti con Azure SDK, è necessario installare il pacchetto azure-identity:

pip install azure-identity

Creare/Ottenere le credenziali

Usare il frammento di interfaccia della riga di comando di Azure seguente per creare/ottenere le credenziali del segreto client.

• Creare un'entità servizio e configurarne l'accesso alle risorse di Azure:

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

  Output:

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

• Prendere nota dell'objectId dell'entità servizio

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

  Output:

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

• Usare le credenziali restituite sopra per impostare le variabili di ambiente AZURE_CLIENT_ID (appId), AZURE_CLIENT_SECRET (password) e AZURE_TENANT_ID (tenant). L'esempio seguente illustra un modo per eseguire questa operazione in PowerShell:

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

Per altre informazioni sulle API di Identità di Azure e su come usarle, vedere Libreria client di Identità di Azure

Concetti chiave

In questo SDK di anteprima sono disponibili quattro famiglie principali di funzionalità:

• Attestazione dell'enclave SGX e TPM.
• Individuazione e convalida del certificato di firma del token di attestazione MAA.
• Gestione dei criteri di attestazione.
• Gestione dei certificati di gestione dei criteri di attestazione (sì, gestione dei criteri).

Il servizio Microsoft attestazione di Azure viene eseguito in due modalità separate: "Isolato" e "AAD". Quando il servizio è in esecuzione in modalità "Isolato", il cliente deve fornire informazioni aggiuntive oltre le credenziali di autenticazione per verificare che siano autorizzate a modificare lo stato di un'istanza di attestazione.

Infine, ogni area in cui il servizio attestazione di Azure è disponibile supporta un'istanza "condivisa", che può essere usata per attestare le enclave SGX che richiedono solo la verifica rispetto alla baseline di Azure (non sono applicati criteri all'istanza condivisa). L'attestazione TPM non è disponibile nell'istanza condivisa. Anche se l'istanza condivisa richiede l'autenticazione AAD, non dispone di criteri di controllo degli accessi in base al ruolo. Qualsiasi cliente con un token di connessione AAD valido può attestare usando l'istanza condivisa.

Attestazione

L'attestazione SGX o TPM è il processo di convalida delle prove raccolte da un ambiente di esecuzione attendibile per garantire che soddisfi sia la baseline di Azure per tale ambiente che i criteri definiti dal cliente applicati a tale ambiente.

Individuazione e convalida del certificato di firma del token del servizio di attestazione

Una delle garanzie operative principali del servizio attestazione di Azure è che il servizio opera "in modo operativo fuori dal TCB". In altre parole, non è possibile che un operatore Microsoft possa manomettere il funzionamento del servizio o danneggiare i dati inviati dal client. Per garantire questa garanzia, il nucleo del servizio di attestazione viene eseguito in un enclave SGX Intel(tm).

Per consentire ai clienti di verificare che le operazioni siano state effettivamente eseguite all'interno dell'enclave, la maggior parte delle risposte del servizio di attestazione viene codificata in un token Web JSON, firmato da una chiave contenuta nell'enclave del servizio di attestazione.

Questo token verrà firmato da un certificato di firma emesso dal servizio MAA per l'istanza specificata.

Se l'istanza del servizio MAA è in esecuzione in un'area in cui il servizio viene eseguito in un enclave SGX, il certificato emesso dal server può essere verificato usando l'API oe_verify_attestation_certificate.

Gestione dei criteri

A ogni istanza del servizio di attestazione è applicato un criterio che definisce criteri aggiuntivi definiti dal cliente.

Per altre informazioni sui criteri di attestazione, vedere Criteri di attestazione

Gestione dei certificati di Gestione criteri

Quando un'istanza di attestazione è in esecuzione in modalità "Isolato", il cliente che ha creato l'istanza di avrà fornito un certificato di gestione dei criteri al momento della creazione dell'istanza. Tutte le operazioni di modifica dei criteri richiedono che il cliente firmi i dati dei criteri con uno dei certificati di gestione dei criteri esistenti. Le API di gestione dei certificati di gestione dei criteri consentono ai client di "eseguire il roll" dei certificati di gestione dei criteri.

Modalità isolata e modalità AAD

Ogni istanza del servizio microsoft attestazione di Azure opera in modalità "AAD" o in modalità "Isolato". Quando un'istanza maa opera in modalità AAD, significa che il cliente che ha creato l'istanza di attestazione consente ad Azure Active Directory e ai criteri di controllo degli accessi in base al ruolo di Azure di verificare l'accesso all'istanza di attestazione.

AttestationType

Il servizio attestazione di Azure supporta l'attestazione di diversi tipi di evidenza a seconda dell'ambiente. Attualmente, MAA supporta gli ambienti di esecuzione attendibili seguenti:

• OpenEnclave: un processore Intel(tm) che esegue codice in un'enclave SGX in cui è stata raccolta l'evidenza di attestazione usando l'API OpenEnclave oe_get_report o oe_get_evidence .
• SgxEnclave: processore Intel(tm) che esegue codice in un'enclave SGX in cui è stata raccolta l'evidenza di attestazione tramite Intel SGX SDK.
• Tpm: ambiente di sicurezza basato su virtualizzazione in cui viene usato il modulo Trusted Platform del processore per fornire l'evidenza di attestazione.

Dati di runtime e dati inittime

RuntimeData fa riferimento ai dati presentati alla logica di generazione delle offerte Intel SGX o alle oe_get_report/oe_get_evidence API. Se il chiamante all'API di attestazione ha fornito un runtime_data attributo, il servizio attestazione di Azure convaliderà che i primi 32 byte del report_data campo nell'evidenza report/OE SGX quote/OE corrispondano all'hash SHA256 dell'oggetto runtime_data.

I dati InitTime fanno riferimento a dati usati per configurare l'enclave SGX da attestare.

Si noti che i dati InitTime non sono supportati nelle macchine virtuali serie DCsv2 di Azure.

Concetti aggiuntivi

Esempio

• Creare un'istanza client di attestazione
• Attestare un enclave SGX
• Ottenere i criteri di attestazione
• Recuperare i certificati di convalida dei token
• Creare un'istanza client di attestazione

Creare un'istanza client

Crea un'istanza del client di attestazione in corrispondenza dell'uri endpoint.

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

Ottenere i criteri di attestazione

Il set_policy metodo recupera i criteri di attestazione dal servizio. I criteri di attestazione vengono istanze per tipo di attestazione, il AttestationType parametro definisce il tipo da recuperare.

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

Impostare un criterio di attestazione per un tipo di attestazione specificato

Se l'istanza del servizio di attestazione è in esecuzione in modalità isolato, l'API set_policy deve fornire un certificato di firma (e una chiave privata) che può essere usato per verificare che il chiamante sia autorizzato a modificare i criteri nell'istanza di attestazione. Se l'istanza del servizio è in esecuzione in modalità AAD, il certificato di firma e la chiave sono facoltativi.

Le API SetPolicy creano un token Web JSON in base al documento dei criteri e alle informazioni di firma inviate al servizio di attestazione.

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

Se l'istanza del servizio è in esecuzione in modalità AAD, la chiamata a set_policy può essere semplificata:

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)

I client devono essere in grado di verificare che il documento dei criteri di attestazione non sia stato modificato prima che il documento dei criteri sia stato ricevuto dall'enclave del servizio di attestazione.

In PolicyResult sono disponibili due proprietà che possono essere usate per verificare che il servizio abbia ricevuto il documento dei criteri:

• policy_signer : se la set_policy chiamata includeva un certificato di firma, questo sarà il certificato fornito al momento della set_policy chiamata. Se non è stato impostato alcun firmatario di criteri, sarà Null.
• policy_token_hash : si tratta dell'hash del token Web JSON inviato al servizio.

Per verificare l'hash, i client possono generare un token dei criteri di attestazione e verificare l'hash generato da tale 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`

Attestare l'enclave SGX

Usare il metodo attest_sgx_enclave per attestare un enclave SGX.

Uno dei principali problemi che i clienti hanno a che fare con gli ambienti crittografati consiste nel garantire che sia possibile comunicare in modo sicuro con il codice in esecuzione nell'ambiente ("codice enclave").

Una soluzione a questo problema è quella nota come "Secure Key Release", che è un modello che consente la comunicazione sicura con il codice enclave.

Per implementare il modello "Secure Key Release", il codice dell'enclave genera una chiave asimmetrica temporanea. Serializza quindi la parte pubblica della chiave in un formato (possibilmente una chiave Web JSON o PEM o un altro formato di serializzazione).

Il codice dell'enclave calcola quindi il valore SHA256 della chiave pubblica e lo passa come input al codice che genera un'offerta SGX (per OpenEnclave, che sarebbe il oe_get_evidence o oe_get_report).

Il client invia quindi l'offerta SGX e la chiave serializzata al servizio di attestazione. Il servizio di attestazione convaliderà l'offerta e garantirà che l'hash della chiave sia presente nell'offerta e emetterà un "Token di attestazione".

Il client può quindi inviare tale token di attestazione (che contiene la chiave serializzata) a una "relying party" di terze parti. La relying party verifica quindi che il token di attestazione sia stato creato dal servizio di attestazione e quindi la chiave serializzata possa essere usata per crittografare alcuni dati contenuti nella "relying party" da inviare al servizio.

Questo esempio mostra un modello comune di chiamata al servizio di attestazione per recuperare un token di attestazione associato a una richiesta.

In questo esempio si presuppone che sia presente un oggetto esistente AttestationClient configurato con l'URI di base per l'endpoint. Si presuppone inoltre che sia presente un'offerta SGX (quote) generata dall'interno dell'enclave SGX che si sta attestando e "Dati di runtime" (runtime_data) a cui si fa riferimento nell'offerta SGX.

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

A questo punto, l'attributo enclave_held_data nell'attestazioneResult conterrà il runtime_data binario di input.

Il token viene ora passato alla "relying party". La relying party convaliderà che il token è stato emesso dal servizio di attestazione. Estrae quindi la chiave asimmetrica dal campo EnclaveHeldData. La relying party crittografa quindi i dati "chiave" usando la chiave asimmetrica e li trasmette all'enclave.

encrypted_data = send_token_to_relying_party(attestationResult.Token)

Ora i dati crittografati possono essere passati all'enclave che può decrittografare i dati.

Altre informazioni su come eseguire la convalida del token di attestazione sono disponibili nell'esempio di attestazione del servizio MAA.

Recuperare i certificati token

Usare get_signing_certificates per recuperare i certificati che possono essere usati per convalidare il token restituito dal servizio di attestazione.

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)

Risoluzione dei problemi

La maggior parte delle operazioni del servizio di attestazione genererà eccezioni definite in Azure Core. Le API del servizio di attestazione genereranno un HttpResponseError errore con codici di errore utili. Molti di questi errori sono ripristinabili.

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
}

Altre informazioni sulla risoluzione dei problemi per il servizio MAA sono disponibili qui

Passaggi successivi

Per altre informazioni sul servizio Microsoft attestazione di Azure, vedere la pagina della documentazione.

Contributo

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, visitare il sito del Contratto di licenza collaboratore.

Quando si invia una richiesta pull, un bot CLA determina automaticamente se è necessario specificare un contratto CLA e completare la richiesta pull in modo appropriato (ad esempio con un'etichetta e un commento). Seguire le istruzioni specificate dal bot. È sufficiente eseguire questa operazione una sola volta per tutti i repository che usano il contratto CLA Microsoft.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento Open Source di Microsoft) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.

Per informazioni dettagliate sulla compilazione, il test e il contributo a queste librerie, vedere CONTRIBUTING.md.

Commenti e suggerimenti

Se si verificano bug o si hanno suggerimenti, segnalare un problema nella sezione Problemi del progetto.