Condividi tramite

attestazione di Azure libreria client per JavaScript - versione 1.0.0

  • Articolo

Il servizio Microsoft attestazione di Azure (MAA) è una soluzione unificata per verificare in remoto la attendibilità di una piattaforma e l'integrità dei file binari in esecuzione. Il servizio supporta l'attestazione delle piattaforme supportate dai moduli di piattaforma attendibili (TPMS) insieme alla possibilità di attestare lo stato degli ambienti di esecuzione attendibili (TEE), ad esempio le enclave di Intel(tm) Software Guard (SGX) e le 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).

Per una visualizzazione più completa delle librerie di Azure, vedere la versione di azure sdk typescript.

NOTA: questo è un SDK di anteprima per il servizio Microsoft attestazione di Azure. Fornisce tutte le funzionalità essenziali per accedere al servizio attestazione di Azure, deve essere considerato "come è" ed è soggetto a modifiche in futuro che potrebbero interrompere la compatibilità con le versioni precedenti.

Collegamenti principali:

Introduzione

Ambienti attualmente supportati

Per altre informazioni, vedere i criteri di supporto.

Prerequisiti

  • Una sottoscrizione di Azure
  • 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 @azure/attestation

Installare la libreria client di Microsoft attestazione di Azure per JavaScript con NPM:

npm install @azure/attestation

Autenticare il client

Per interagire con il servizio Microsoft attestazione di Azure, è necessario creare un'istanza della classe Client di attestazione o amministrazione attestazione. È necessario un URL dell'istanza di attestazione, che sarà l'URI di attestazione visualizzato nel portale o sarà uno dei provider di attestazioni condivisi. Sono necessarie anche credenziali client per usare il client di amministrazione attestazione o chiamare l'API attestTpm . Le credenziali client richiedono (ID client, segreto client, ID tenant) per creare un'istanza di un oggetto client.

In questa sezione introduttiva verrà eseguita l'autenticazione usando le credenziali del segreto client tramite il provider DefaultAzureCredential , ma vengono offerti altri meccanismi di autenticazione tramite il pacchetto @azure/identity . Per installare il @azure/identity pacchetto:

npm install @azure/identity

Creare/Ottenere 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'oggetto 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). Nell'esempio seguente viene illustrato 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à:

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 autorizzati a modificare lo stato di un'istanza di attestazione.

Infine, ogni area in cui il servizio Microsoft attestazione di Azure è disponibile supporta un'istanza "condivisa", che può essere usata per attestare enclave SGX che richiedono solo la verifica rispetto alla baseline di Azure (non sono presenti criteri applicati al provider condiviso). L'attestazione TPM non è disponibile nel provider condiviso. Sebbene l'istanza condivisa richieda 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 di attestazione 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 l'operazione del servizio o danneggiare i dati inviati dal client. Per garantire questa garanzia, il core 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 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 rilasciato 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 rilasciato dal server può essere verificato usando l'API oe_verify_attestation_certificate.

L'oggetto AttestationResponse contiene due attributi principali: token e value. L'attributo token contiene il token completo restituito dal servizio di attestazione, l'attributo value contiene il corpo della risposta del token Web JSON.

Gestione dei criteri

Ogni istanza del servizio di attestazione ha un criterio applicato a esso che definisce criteri aggiuntivi definiti dal cliente.

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

Gestione dei certificati di gestione dei criteri

Quando un'istanza di attestazione è in esecuzione in modalità "Isolato", il cliente che ha creato l'istanza 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 firma i dati dei criteri con uno dei certificati di gestione dei criteri esistenti. Le API gestione certificati di gestione dei criteri consentono ai client di eseguire il roll-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 è operativa in modalità AAD, significa che il cliente che ha creato l'istanza di attestazione consente ai criteri di controllo di Controllo degli accessi in base al ruolo di Azure Active Directory e azure di verificare l'accesso all'istanza di attestazione.

AttestazioneType

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

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

Dati di runtime e dati inittime

RuntimeData fa riferimento ai dati presentati alla logica di generazione di quote 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 convalida che i primi 32 byte del report_data campo nel report SGX quote/OE/OE corrispondano all'hash SHA256 dell'oggetto runtime_data.

I dati initTime fanno riferimento ai 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

Crea un'istanza del client di attestazione all'uri endpoint, usando le credenziali di Azure predefinite (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();

Se non si chiama l'API attestTpm , non è necessario specificare le credenziali per accedere al client di attestazione. Ciò significa che un client può essere creato semplicemente con:

const client = new AttestationClient(endpoint);

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

Crea un'istanza del client di amministrazione attestazione all'uri endpoint.

Si noti che il client di amministrazione richiede le credenziali di Azure.

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

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

Ottenere i criteri di attestazione

Il getPolicy metodo recupera i criteri di attestazione dal servizio. I criteri di attestazione vengono istanze in base al tipo di attestazione, il AttestationType parametro definisce il tipo di istanza da recuperare.

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

Impostare un criterio di attestazione per un tipo di attestazione specificato

Se l'istanza del servizio di attestazione è in esecuzione in modalità isolata, 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.

Se l'istanza del servizio è in esecuzione in modalità AAD, la chiamata a setPolicy è come previsto:

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

Se l'istanza del servizio è in esecuzione in modalità isolata, la chiamata a setPolicy richiede che il client possa dimostrare di avere accesso a una delle chiavi private e dei certificati di gestione dei criteri.

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

Nelle copertine, le API setPolicy creano un token Web JSON contenente il documento dei criteri e firmato con il privateKey quale certificate viene quindi inviato al servizio di attestazione.

Se un client vuole assicurarsi che il documento dei criteri di attestazione non sia stato modificato prima che il documento dei criteri sia stato ricevuto dall'enclave del servizio attestazione, può usare le proprietà restituite nell'objct PolicyResult che può essere usato per verificare che il servizio abbia ricevuto il documento dei criteri:

  • policySigner - se la setPolicy chiamata includeva un certificatevalore , questo valore sarà il certificato fornito al momento della setPolicy chiamata. Se non è stato impostato alcun segno di criterio, questo sarà Null.
  • policyTokenHash - questo è l'hash della firma Web JSON inviata al servizio per l'API setPolicy.

Per verificare l'hash, i client possono creare un token di criteri di attestazione (una classe helper che rappresenta il token usato per impostare i criteri di attestazione) e verificare l'hash generato da tale token:

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

Attesta SGX e Open Enclave

Usare il attestSgxEnclave metodo per attestare un enclave SGX.

Uno dei principali problemi che i clienti hanno a disposizione degli ambienti crittografati è come garantire che sia possibile comunicare in modo sicuro con il codice in esecuzione nell'ambiente ("codice enclave").

Una soluzione a questo problema è ciò che è noto come "Secure Key Release", che è un modello che consente la comunicazione sicura con codice enclave.

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

Il codice enclave calcola quindi il valore SHA256 della chiave pubblica e lo passa come input al codice che genera una citazione SGX (per OpenEnclave, ovvero il oe_get_evidence o il oe_get_report).

Il client invia quindi la citazione SGX e la chiave serializzata al servizio di attestazione. Il servizio di attestazione convalida la citazione e garantisce che l'hash della chiave sia presente nella citazione 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 convalida quindi che il token di attestazione è stato creato dal servizio di attestazione e quindi la chiave serializzata può essere usata per crittografare alcuni dati mantenuti dalla "relying party" per inviare al servizio.

In questo esempio viene illustrato 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 attestazione per l'endpoint. Si presuppone inoltre di avere un report OpenEnclave () generato dall'enclave SGX che si sta attestando e "Runtime Data" (reportbinaryRuntimeData) a cui si fa riferimento nella citazione SGX.

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

È anche possibile che il binaryRuntimeData servizio di attestazione inviato al servizio di attestazione venga interpretato come dati JSON. In tal caso, il client deve specificare runTimeJson nella chiamata API di attestazione:

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

Analogamente, se si usa Intel SDK per generare una "citazione", è possibile convalidare la citazione usando:

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

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 getSigningCertificates per recuperare i certificati che possono essere usati per convalidare il token restituito dal servizio di attestazione. Si noti che questa chiamata crea un client con credenziali di Azure, che non è necessaria se si chiamano le attestSgxEnclave API o attestOpenEnclave

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

const attestationSigners = await client.getAttestationSigners();

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

Risoluzione dei problemi

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

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

Registrazione

L'abilitazione della registrazione consente di individuare informazioni utili sugli errori. Per visualizzare un log di richieste e risposte HTTP, impostare la variabile di ambiente AZURE_LOG_LEVEL su info. In alternativa, la registrazione può essere abilitata in fase di esecuzione chiamando setLogLevel in @azure/logger:

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

setLogLevel("info");

Per istruzioni più dettagliate su come abilitare i log, è possibile esaminare la documentazione del pacchetto @azure/logger.

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

Vedere CONTRIBUTING.md per informazioni dettagliate sulla creazione, il test e il contributo a queste librerie.

Commenti e suggerimenti

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

Impression