Udostępnij za pośrednictwem

biblioteka klienta Azure Attestation dla języka JavaScript — wersja 1.0.0

  • Artykuł

Usługa Microsoft Azure Attestation (MAA) to ujednolicone rozwiązanie do zdalnego weryfikowania wiarygodności platformy i integralności plików binarnych uruchomionych w niej. Usługa obsługuje zaświadczania platform wspieranych przez moduły TPM (Trusted Platform Modules) wraz z możliwością zaświadczania o stanie zaufanych środowisk wykonawczych (TEE), takich jak enklawy Intel(tm) Software Guard Extensions (SGX) i enklawy zabezpieczeń opartych na wirtualizacji (VBS).

Zaświadczanie to proces demonstrujący, że pliki binarne oprogramowania zostały prawidłowo utworzone na zaufanej platformie. Zdalne jednostki uzależnione mogą następnie mieć pewność, że na zaufanym sprzęcie działa tylko takie zamierzone oprogramowanie. Azure Attestation to ujednolicona usługa i struktura służąca do zaświadczania.

Azure Attestation umożliwia najnowocześniejsze paradygmaty zabezpieczeń, takie jak przetwarzanie poufne platformy Azure i ochrona za pomocą inteligentnej krawędzi. Klienci żądali możliwości niezależnego weryfikowania lokalizacji maszyny, stanu maszyny wirtualnej na tej maszynie oraz środowiska, w którym enklawy działają na tej maszynie wirtualnej. Azure Attestation umożliwią to i wiele dodatkowych żądań klientów.

Azure Attestation odbiera dowody z jednostek obliczeniowych, przekształca je w zestaw oświadczeń, weryfikuje je przed konfigurowalnymi zasadami i tworzy dowody kryptograficzne dla aplikacji opartych na oświadczeniach (na przykład jednostek uzależnionych i urzędów kontroli).

Aby uzyskać bardziej kompletny widok bibliotek platformy Azure, zobacz wydanie języka typescript zestawu SDK platformy Azure.

UWAGA: jest to zestaw SDK w wersji zapoznawczej dla usługi Microsoft Azure Attestation. Zapewnia ona wszystkie podstawowe funkcje dostępu do usługi Azure Attestation, należy ją traktować jako "w stanie" i może ulec zmianom w przyszłości, co może spowodować przerwanie zgodności z poprzednimi wersjami.

Linki kluczowe:

Wprowadzenie

Obecnie obsługiwane środowiska

Aby uzyskać więcej informacji, zobacz nasze zasady pomocy technicznej .

Wymagania wstępne

Instalowanie pakietu @azure/attestation

Zainstaluj bibliotekę klienta microsoft Azure Attestation dla języka JavaScript za pomocą narzędzia NPM:

npm install @azure/attestation

Uwierzytelnianie klienta

Aby wchodzić w interakcje z usługą Microsoft Azure Attestation, należy utworzyć wystąpienie klasy klienta zaświadczania lub klienta administracji zaświadczania. Potrzebny jest adres URL wystąpienia zaświadczania, który będzie widoczny w portalu "Attest URI" lub będzie jednym z udostępnionych dostawców zaświadczania. Poświadczenia klienta będą również potrzebne do korzystania z klienta administracji zaświadczania lub wywoływania interfejsu attestTpm API. Poświadczenia klienta wymagają (identyfikator klienta, klucz tajny klienta, identyfikator dzierżawy) w celu utworzenia wystąpienia obiektu klienta.

W tej sekcji wprowadzenie będziemy uwierzytelnianie przy użyciu poświadczeń wpisów tajnych klienta za pośrednictwem dostawcy DefaultAzureCredential , ale oferujemy więcej mechanizmów uwierzytelniania za pośrednictwem pakietu @azure/tożsamości . Aby zainstalować @azure/identity pakiet:

npm install @azure/identity

Tworzenie/pobieranie poświadczeń

Użyj poniższego fragmentu kodu interfejsu wiersza polecenia platformy Azure , aby utworzyć/pobrać poświadczenia wpisów tajnych klienta.

  • Utwórz jednostkę usługi i skonfiguruj jej dostęp do zasobów platformy Azure:

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

    Dane wyjściowe:

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

  • Zanotuj identyfikator objectId jednostki usługi

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

    Dane wyjściowe:

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

  • Użyj powyższych zwróconych poświadczeń, aby ustawić zmienne środowiskowe AZURE_CLIENT_ID (appId), AZURE_CLIENT_SECRET (hasło) i AZURE_TENANT_ID (dzierżawa). W poniższym przykładzie pokazano sposób wykonania tej czynności w programie PowerShell:

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

Aby uzyskać więcej informacji na temat interfejsów API tożsamości platformy Azure i sposobu ich używania, zobacz Biblioteka klienta tożsamości platformy Azure

Kluczowe pojęcia

W tym zestawie SDK w wersji zapoznawczej dostępne są cztery główne rodziny funkcji:

Usługa Microsoft Azure Attestation działa w dwóch oddzielnych trybach: "Isolated" i "AAD". Gdy usługa jest uruchomiona w trybie "Izolowany", klient musi podać dodatkowe informacje poza poświadczeniami uwierzytelniania, aby sprawdzić, czy mają uprawnienia do modyfikowania stanu wystąpienia zaświadczania.

Na koniec każdy region, w którym jest dostępna usługa Microsoft Azure Attestation, obsługuje wystąpienie "udostępnione", które może służyć do zaświadczania enklaw SGX, które wymagają weryfikacji tylko względem punktu odniesienia platformy Azure (nie ma żadnych zasad stosowanych do dostawcy udostępnionego). Zaświadczenie modułu TPM nie jest dostępne u dostawcy udostępnionego. Chociaż wystąpienie udostępnione wymaga uwierzytelniania usługi AAD, nie ma żadnych zasad RBAC — każdy klient z prawidłowym tokenem elementu nośnego usługi AAD może potwierdzić użycie wystąpienia udostępnionego.

Zaświadczanie

Zaświadczanie SGX lub TPM to proces weryfikacji dowodów zebranych z zaufanego środowiska wykonawczego w celu zapewnienia, że spełnia zarówno punkt odniesienia platformy Azure dla tego środowiska, jak i zasady zdefiniowane przez klienta stosowane do tego środowiska.

Odnajdywanie i walidacja certyfikatu podpisywania tokenu usługi zaświadczania

Jedną z podstawowych gwarancji operacyjnych usługi Azure Attestation jest to, że usługa działa "operacyjnie poza TCB". Innymi słowy, nie ma możliwości, aby operator firmy Microsoft mógł manipulować działaniem usługi lub uszkodzić dane wysyłane z klienta. Aby zagwarantować tę gwarancję, rdzeń usługi zaświadczania działa w enklawie SGX Intel(tm).

Aby umożliwić klientom sprawdzenie, czy operacje zostały rzeczywiście wykonane wewnątrz enklawy, większość odpowiedzi z usługi zaświadczania jest kodowana w tokenie sieci Web JSON podpisanym przez klucz przechowywany w enklawie usługi zaświadczania.

Ten token zostanie podpisany przez certyfikat podpisywania wystawiony przez usługę MAA dla określonego wystąpienia.

Jeśli wystąpienie usługi MAA jest uruchomione w regionie, w którym usługa działa w enklawie SGX, certyfikat wystawiony przez serwer można zweryfikować przy użyciu interfejsu API oe_verify_attestation_certificate.

Obiekt AttestationResponse zawiera dwa główne atrybuty: token i value. Atrybut token zawiera pełny token zwrócony przez usługę zaświadczania, value atrybut zawiera treść odpowiedzi tokenu internetowego JSON.

Zarządzanie zasadami

Każde wystąpienie usługi zaświadczania ma zastosowane zasady definiujące dodatkowe kryteria zdefiniowane przez klienta.

Aby uzyskać więcej informacji na temat zasad zaświadczania, zobacz Zasady zaświadczania

Zarządzanie certyfikatami zarządzania zasadami

Gdy wystąpienie zaświadczania jest uruchomione w trybie "Izolowany", klient, który utworzył wystąpienie, udostępni certyfikat zarządzania zasadami podczas tworzenia wystąpienia. Wszystkie operacje modyfikacji zasad wymagają podpisania przez klienta danych zasad za pomocą jednego z istniejących certyfikatów zarządzania zasadami. Interfejsy API zarządzania certyfikatami zarządzania zasadami umożliwiają klientom "rzutowanie" certyfikatów zarządzania zasadami.

Tryb izolowany i tryb usługi AAD

Każde wystąpienie usługi Microsoft Azure Attestation działa w trybie "AAD" lub "Izolowanym". Gdy wystąpienie usługi MAA działa w trybie usługi AAD, oznacza to, że klient, który utworzył wystąpienie zaświadczania, zezwala usłudze Azure Active Directory i zasadom kontroli dostępu opartej na rolach platformy Azure w celu zweryfikowania dostępu do wystąpienia zaświadczania.

AttestationType

Usługa Microsoft Azure Attestation obsługuje zaświadczanie różnych typów dowodów w zależności od środowiska. Obecnie program MAA obsługuje następujące zaufane środowiska wykonywania:

  • OpenEnclave — procesor Intel(tm) z uruchomionym kodem w enklawie SGX, w której zebrano dowody zaświadczania przy użyciu openenclave oe_get_report lub oe_get_evidence interfejsu API.
  • SgxEnclave — procesor Intel(tm) z uruchomionym kodem w enklawie SGX, w której zebrano dowody zaświadczania przy użyciu zestawu SDK Intel SGX.
  • Tpm — środowisko zabezpieczeń oparte na wirtualizacji, w którym moduł zaufanej platformy procesora jest używany do dostarczania dowodów zaświadczania.

Dane środowiska uruchomieniowego i dane inittime

RuntimeData odnosi się do danych prezentowanych logiki generowania cudzysłowów oe_get_report/oe_get_evidence Intel SGX lub interfejsów API. Jeśli obiekt wywołujący do interfejsu API zaświadczenia dostarczył runtime_data atrybut, usługa Azure Attestation zweryfikuje, że pierwsze 32 bajty report_data pola w obiekcie SGX Quote/OE Report/OE Evidence są zgodne z wartością skrótu SHA256 .runtime_data

Dane InitTime odnoszą się do danych używanych do konfigurowania atklawy SGX.

Należy pamiętać, że dane InitTime nie są obsługiwane na maszynach wirtualnych serii Azure DCsv2 .

Dodatkowe pojęcia

Przykłady

Tworzenie wystąpienia klienta

Tworzy wystąpienie klienta zaświadczania o identyfikatorze URI endpointprzy użyciu domyślnych poświadczeń platformy Azure (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();

Jeśli nie wywołujesz interfejsu attestTpm API, nie musisz podawać poświadczeń w celu uzyskania dostępu do klienta zaświadczania. Oznacza to, że klient można utworzyć po prostu za pomocą polecenia:

const client = new AttestationClient(endpoint);

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

Tworzy wystąpienie klienta administracyjnego zaświadczania o identyfikatorze URI endpoint.

Należy pamiętać, że klient administracyjny wymaga poświadczeń platformy Azure.

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

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

Uzyskiwanie zasad zaświadczania

Metoda getPolicy pobiera zasady zaświadczania z usługi. Zasady zaświadczania są wystąpieniami poszczególnych typów zaświadczania. AttestationType Parametr definiuje typ wystąpienia do pobrania.

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

Ustawianie zasad zaświadczania dla określonego typu zaświadczania

Jeśli wystąpienie usługi zaświadczania jest uruchomione w trybie izolowanym, interfejs API set_policy musi podać certyfikat podpisywania (i klucz prywatny), który może służyć do sprawdzania, czy obiekt wywołujący ma uprawnienia do modyfikowania zasad w wystąpieniu zaświadczania. Jeśli wystąpienie usługi jest uruchomione w trybie usługi AAD, certyfikat podpisywania i klucz są opcjonalne.

Jeśli wystąpienie usługi jest uruchomione w trybie usługi AAD, wywołanie ustawieniaPolicy jest zgodnie z oczekiwaniami:

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

Jeśli wystąpienie usługi jest uruchomione w trybie izolowanym, wywołanie ustawieniaPolicy wymaga, aby klient mógł udowodnić, że ma dostęp do jednego z kluczy prywatnych i certyfikatów zarządzania zasadami.

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

W obszarze okładek interfejsy API setPolicy tworzą token internetowy JSON zawierający dokument certificate zasad i podpisany privateKey przy użyciu elementu, który następnie jest wysyłany do usługi zaświadczania.

Jeśli klient chce upewnić się, że dokument zasad zaświadczania nie został zmodyfikowany przed odebraniem dokumentu zasad przez enklawę usługi zaświadczania, może użyć właściwości zwróconych w obiekcie PolicyResult , które można użyć do sprawdzenia, czy usługa otrzymała dokument zasad:

  • policySigner — jeśli wywołanie setPolicy zawiera wartość certificate, ta wartość będzie certyfikatem podanym w momencie wywołania setPolicy . Jeśli nie ustawiono żadnego znaku zasad, będzie to miało wartość null.
  • policyTokenHash — jest to skrót sygnatury sieci Web JSON wysłanej do usługi dla interfejsu API setPolicy.

Aby zweryfikować skrót, klienci mogą utworzyć token zasad zaświadczania (klasa pomocnika reprezentująca token używany do ustawiania zasad zaświadczania) i zweryfikować skrót wygenerowany na podstawie tego tokenu:

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

Zaświadczaj SGX i Open Enklawy

attestSgxEnclave Użyj metody, aby potwierdzić enklawę SGX.

Jednym z podstawowych wyzwań, przed którymi klienci wchodzą w interakcje z zaszyfrowanymi środowiskami, jest zapewnienie, że można bezpiecznie komunikować się z kodem działającym w środowisku ("kod enklawy").

Jednym z rozwiązań tego problemu jest to, co jest znane jako "Secure Key Release", czyli wzorzec, który umożliwia bezpieczną komunikację z kodem enklawy.

Aby zaimplementować wzorzec "Secure Key Release", kod enklawy generuje efemeryczny klucz asymetryczny. Następnie serializuje publiczną część klucza do określonego formatu (być może klucz internetowy JSON lub PEM lub inny format serializacji).

Kod enklawy oblicza następnie wartość SHA256 klucza publicznego i przekazuje go jako dane wejściowe do kodu, który generuje cudzysłów SGX (dla OpenEnclave, które byłyby oe_get_evidence lub oe_get_report).

Następnie klient wysyła cytat SGX i serializowany klucz do usługi zaświadczania. Usługa zaświadczania zweryfikuje cudzysłów i upewni się, że skrót klucza znajduje się w cudzysłowie i wyda "Token zaświadczania".

Następnie klient może wysłać ten token zaświadczania (który zawiera klucz serializowany) do innej firmy "jednostki uzależnionej". Jednostka uzależniona sprawdza następnie, czy token zaświadczania został utworzony przez usługę zaświadczania, a tym samym zserializowany klucz może służyć do szyfrowania niektórych danych przechowywanych przez jednostkę uzależnioną do wysłania do usługi.

W tym przykładzie przedstawiono jeden typowy wzorzec wywoływania do usługi zaświadczania w celu pobrania tokenu zaświadczania skojarzonego z żądaniem.

W tym przykładzie przyjęto założenie, że masz istniejący AttestationClient obiekt skonfigurowany przy użyciu identyfikatora URI narzędzia Attest dla punktu końcowego. Przyjęto również założenie, że masz raport OpenEnclave (report) wygenerowany na podstawie enklawy SGX, który potwierdzasz, i "Dane środowiska uruchomieniowego" (binaryRuntimeData), do którego odwołujesz się w cudzysłowie SGX.

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

Istnieje również możliwość, że binaryRuntimeData wysyłane do usługi zaświadczania mają być interpretowane jako dane JSON. W takim przypadku klient powinien określić runTimeJson w wywołaniu zaświadczającego interfejsu API:

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

Podobnie, jeśli używasz zestawu Intel SDK do wygenerowania "cudzysłowu", możesz zweryfikować cudzysłów przy użyciu:

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

Dodatkowe informacje na temat przeprowadzania weryfikacji tokenu zaświadczania można znaleźć w przykładzie zaświadczania usługi MAA.

Pobieranie certyfikatów tokenu

Służy getSigningCertificates do pobierania certyfikatów, których można użyć do zweryfikowania tokenu zwróconego z usługi zaświadczania. Należy pamiętać, że to wywołanie tworzy klienta z poświadczeniami platformy Azure, które nie jest potrzebne w przypadku wywoływania attestSgxEnclave interfejsów API lub attestOpenEnclave

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

const attestationSigners = await client.getAttestationSigners();

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

Rozwiązywanie problemów

Większość operacji usługi zaświadczania będzie zgłaszać wyjątki zdefiniowane w usłudze Azure Core. Interfejsy API usługi zaświadczania zgłaszają RestError błąd z przydatnymi kodami błędów. Wiele z tych błędów można odzyskać.

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

Rejestrowanie

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań HTTP i odpowiedzi, ustaw zmienną AZURE_LOG_LEVEL środowiskową na info. Możesz też włączyć rejestrowanie w czasie wykonywania, wywołując polecenie w elemecie setLogLevel@azure/logger:

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

setLogLevel("info");

Aby uzyskać bardziej szczegółowe instrukcje dotyczące włączania dzienników, zapoznaj się z dokumentami dotyczącymi pakietu @azure/rejestratora.

Dodatkowe informacje dotyczące rozwiązywania problemów z usługą MAA można znaleźć tutaj

Następne kroki

Aby uzyskać więcej informacji na temat usługi Microsoft Azure Attestation, zobacz naszą stronę dokumentacji.

Współtworzenie

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź witrynę współautora umowy licencyjnej.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Wystarczy zrobić to raz dla wszystkich repozytoriów, w przypadku których jest używana nasza umowa CLA.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub wyślij wiadomość e-mail na adres opencode@microsoft.com w przypadku jakichkolwiek dodatkowych pytań lub komentarzy.

Aby uzyskać szczegółowe informacje na temat kompilowania, testowania i współtworzenia tych bibliotek, zobacz CONTRIBUTING.md .

Przekazywanie opinii

Jeśli wystąpią jakiekolwiek usterki lub masz sugestie, zgłoś problem w sekcji Problemy w projekcie.

Wrażenia