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

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

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

Azure Attestation umożliwia najnowocześniejsze paradygmaty zabezpieczeń, takie jak przetwarzanie poufne platformy Azure i ochrona 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 weryfikacje kryptograficzne dla aplikacji opartych na oświadczeniach (na przykład jednostki uzależnione i urzędy inspekcji).

Ten pakiet został przetestowany przy użyciu języka Python 2.7, od 3.6 do 3.9.

Aby uzyskać bardziej kompletny widok bibliotek platformy Azure, zobacz stronę wydania zestawu Azure SDK dla języka Python.

Kod | źródłowy Pakiet (PyPI) | Dokumentacja referencyjna interfejsu | API Dokumentacja produktu

Wprowadzenie

Wymagania wstępne

• Subskrypcja platformy Azure. Aby korzystać z usług platformy Azure, w tym usługi Azure Attestation, musisz mieć subskrypcję. Jeśli nie masz istniejącego konta platformy Azure, możesz utworzyć konto bezpłatnej wersji próbnej lub skorzystać z korzyści z subskrypcji programu Visual Studio podczas tworzenia konta.
• Istniejące wystąpienie Azure Attestation lub można użyć "dostawcy udostępnionego" dostępnego w każdym regionie świadczenia usługi Azure. Jeśli musisz utworzyć wystąpienie usługi Azure Attestation, możesz użyć witryny Azure Portal lub interfejsu wiersza polecenia platformy Azure.

Instalowanie pakietu

Zainstaluj bibliotekę klienta Azure Attestation dla języka Python przy użyciu interfejsu PyPI:

pip install azure-security-attestation

Uwierzytelnianie klienta

Aby móc korzystać z usługi Azure Attestation, należy utworzyć wystąpienie klasy klienta zaświadczania lub klienta administracji zaświadczania. Potrzebny jest punkt końcowy zaświadczania, który może być widoczny jako "Attest URI" w portalu, a poświadczenia klienta (identyfikator klienta, klucz tajny klienta, identyfikator dzierżawy) w celu utworzenia wystąpienia obiektu klienta.

Uwierzytelnianie poświadczeń wpisu tajnego klienta jest używane w tej sekcji wprowadzenie, ale możesz znaleźć więcej sposobów uwierzytelniania za pomocą pakietu tożsamości platformy Azure. Aby użyć dostawcy DefaultAzureCredential pokazanego poniżej lub innych dostawców poświadczeń dostarczonych z zestawem Azure SDK, należy zainstalować pakiet azure-identity:

pip install azure-identity

Tworzenie/pobieranie poświadczeń

Użyj poniższego fragmentu kodu interfejsu wiersza polecenia platformy Azure , aby utworzyć/pobrać poświadczenia wpisu tajnego klienta.

• Utwórz jednostkę usługi i skonfiguruj 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, aby to zrobić 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 usługi Azure Identity

Kluczowe pojęcia

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

• Zaświadczania enklawy SGX i TPM.
• Odnajdywanie i walidacja certyfikatu podpisywania tokenu zaświadczania MAA.
• Zarządzanie zasadami zaświadczania.
• Zarządzanie certyfikatami zarządzania zasadami zaświadczania (tak, zarządzanie zasadami).

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

Na koniec każdy region, w którym dostępna jest usługa Azure Attestation, obsługuje wystąpienie "udostępnione", które może służyć do potwierdzania enklaw SGX, które wymagają weryfikacji tylko względem punktu odniesienia platformy Azure (nie ma żadnych zasad stosowanych do wystąpienia udostępnionego). Zaświadczenie modułu TPM nie jest dostępne w wystąpieniu udostępnionym. Mimo że 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 ze środowiska zaufanego wykonywania w celu zapewnienia, że spełnia on zarówno plan bazowy 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ć operacją 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 zakodowana w tokenie internetowym JSON, który jest podpisany 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 działa 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.

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, dostarczył certyfikat zarządzania zasadami w momencie utworzenia 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 "roll" certyfikaty 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, umożliwia 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 Azure Attestation obsługuje zaświadczanie różnych typów dowodów w zależności od środowiska. Obecnie usługa MAA obsługuje następujące środowiska zaufanego wykonywania:

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

Dane środowiska uruchomieniowego i dane inittime

RuntimeData odnosi się do danych przedstawionych logiki generowania cudzysłowów Intel SGX lub oe_get_report/oe_get_evidence interfejsów API. Jeśli obiekt wywołujący do interfejsu API zaświadczenia dostarczył runtime_data atrybut, usługa Azure Attestation sprawdzi, czy pierwsze 32 bajty report_data pola w raporcie SGX Quote/OE Report/OE Evidence pasuje do skrótu SHA256 elementu 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 z serii Azure DCsv2 .

Dodatkowe pojęcia

Przykłady

• Tworzenie wystąpienia klienta zaświadczania
• Zaświadczaj enklawę SGX
• Uzyskiwanie zasad zaświadczania
• Pobieranie certyfikatów weryfikacji tokenu
• Tworzenie wystąpienia klienta zaświadczania

Tworzenie wystąpienia klienta

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

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

Uzyskiwanie zasad zaświadczania

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

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

W ramach okładek interfejsy API SetPolicy tworzą token internetowy JSON na podstawie dokumentu zasad i informacji o podpisywaniu wysyłanych do usługi zaświadczania.

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

Jeśli wystąpienie usługi jest uruchomione w trybie usługi AAD, wywołanie set_policy można uprościć:

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)

Klienci muszą mieć możliwość sprawdzenia, czy dokument zasad zaświadczania nie został zmodyfikowany przed odebraniem dokumentu zasad przez enklawę usługi zaświadczania.

W elemecie PolicyResult znajdują się dwie właściwości, których można użyć do sprawdzenia, czy usługa otrzymała dokument zasad:

• policy_signer — jeśli wywołanie set_policy zawiera certyfikat podpisywania, będzie to certyfikat podany w momencie wywołania set_policy . Jeśli nie ustawiono żadnego znaku zasad, będzie to miało wartość null.
• policy_token_hash — jest to skrót tokenu internetowego JSON wysyłanego do usługi.

Aby zweryfikować skrót, klienci mogą wygenerować token zasad zaświadczania i zweryfikować skrót wygenerowany na podstawie tego tokenu:

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`

Zaświadczaj SGX Enklawa

Użyj metody attest_sgx_enclave , 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 założono, że masz istniejący AttestationClient obiekt skonfigurowany przy użyciu podstawowego identyfikatora URI punktu końcowego. Przyjęto również założenie, że masz cudzysłówquote SGX wygenerowany na podstawie enklawy SGX, którą zaświadczasz, i "Dane środowiska uruchomieniowego" (runtime_data), do którego odwołujesz się w cudzysłowie SGX.

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

W tym momencie atrybut enclave_held_data w zaświadczaniuResult będzie przechowywać wejściowe runtime_data binarne.

Token jest teraz przekazywany do "jednostki uzależnionej". Jednostka uzależniona sprawdzi, czy token został wystawiony przez usługę zaświadczania. Następnie wyodrębnia klucz asymetryczny z pola EnclaveHeldData. Jednostka uzależniona następnie szyfruje swoje dane "klucz" przy użyciu klucza asymetrycznego i przesyła je z powrotem do enklawy.

encrypted_data = send_token_to_relying_party(attestationResult.Token)

Teraz zaszyfrowane dane można przekazać do enklawy, która może odszyfrować te dane.

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 get_signing_certificates do pobierania certyfikatów, których można użyć do zweryfikowania tokenu zwróconego z usługi zaświadczania.

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)

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ą HttpResponseError błąd z przydatnymi kodami błędów. Wiele z tych błędów można odzyskać.

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
}

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.