Azure Attestation pustaka klien untuk Python - versi 1.0.0

Artikel
04/05/2023

Layanan Microsoft Azure Attestation (MAA) adalah solusi terpadu untuk memverifikasi kepercayaan platform dari jarak jauh dan integritas biner yang berjalan di dalamnya. Layanan ini mendukung pengesahan platform yang didukung oleh Trusted Platform Modules (TPM) bersama kemampuan untuk membuktikan status Trusted Execution Environments (TEEs) seperti enklave Intel(tm) Software Guard Extensions (SGX) dan enklave Keamanan berbasis Virtualisasi (VBS).

Attestation (pengesahan) adalah proses untuk menunjukkan bahwa biner perangkat lunak diinstansiasi dengan benar pada platform yang tepercaya. Pihak yang mengandalkan jarak jauh dapat memperoleh kepercayaan diri bahwa hanya perangkat lunak yang dimaksudkan yang beroperasi pada perangkat keras tepercaya. Azure Attestation adalah layanan terpadu yang berhubungan dengan pelanggan dan kerangka kerja untuk pengesahan.

Azure Attestation memungkinkan paradigma keamanan mutakhir seperti komputasi Azure Confidential dan perlindungan Intelligent Edge. Pelanggan telah meminta kemampuan untuk memverifikasi lokasi mesin secara independen, postur komputer virtual (VM) dalam mesin tersebut, dan lingkungan di mana enklave berjalan pada VM tersebut. Azure Attestation akan memberdayakan hal-hal ini dan permintaan pelanggan tambahan.

Azure Attestation menerima bukti dari entitas komputasi, mengubahnya menjadi serangkaian klaim, memvalidasinya terhadap kebijakan yang dapat dikonfigurasi, dan menghasilkan bukti kriptografi untuk aplikasi berbasis klaim (misalnya, mengandalkan pihak dan otoritas audit).

Paket ini telah diuji dengan Python 2.7, 3.6 hingga 3.9.

Untuk tampilan pustaka Azure yang lebih lengkap, lihat halaman rilis Azure SDK untuk Python.

Kode sumber | Paket (PyPI) | Dokumentasi | referensi API Dokumentasi produk

Memulai

Prasyarat

Langganan Azure. Untuk menggunakan layanan Azure, termasuk layanan Azure Attestation, Anda memerlukan langganan. Jika Anda tidak memiliki akun Azure yang sudah ada, Anda dapat mendaftar untuk uji coba gratis atau menggunakan manfaat Langganan Visual Studio saat membuat akun.
Instans Azure Attestation yang sudah ada, atau Anda dapat menggunakan "penyedia bersama" yang tersedia di setiap wilayah Azure. Jika Anda perlu membuat instans layanan Azure Attestation, Anda dapat menggunakan Portal Microsoft Azure atau Azure CLI.

Instal paketnya

Instal pustaka klien Azure Attestation untuk Python dengan PyPI:

pip install azure-security-attestation

Mengautentikasi klien

Untuk berinteraksi dengan layanan Azure Attestation, Anda harus membuat instans kelas Klien Pengesahan atau Klien Administrasi Pengesahan. Anda memerlukan titik akhir pengesahan, yang mungkin Anda lihat sebagai "URI Pengesahan" di portal, dan kredensial klien (id klien, rahasia klien, id penyewa) untuk membuat instans objek klien.

Autentikasi kredensial rahasia klien sedang digunakan di bagian memulai ini tetapi Anda dapat menemukan lebih banyak cara untuk mengautentikasi dengan paket identitas Azure. Untuk menggunakan penyedia DefaultAzureCredential yang ditunjukkan di bawah ini, atau penyedia kredensial lain yang disediakan dengan Azure SDK, Anda harus menginstal paket identitas azure:

pip install azure-identity

Membuat/Mendapatkan kredensial

Gunakan cuplikan Azure CLI di bawah ini untuk membuat/mendapatkan kredensial rahasia klien.

Buat perwakilan layanan dan konfigurasikan aksesnya ke sumber daya 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"
}

Perhatikan objectId perwakilan layanan

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

Output:

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

Gunakan kredensial yang dikembalikan di atas untuk mengatur variabel lingkungan AZURE_CLIENT_ID (appId), AZURE_CLIENT_SECRET (kata sandi), dan AZURE_TENANT_ID (penyewa). Contoh berikut ini memperlihatkan cara untuk melakukan ini di Powershell:
```
$Env:AZURE_CLIENT_ID="generated-app-ID"
$Env:AZURE_CLIENT_SECRET="random-password"
$Env:AZURE_TENANT_ID="tenant-ID"
```

Untuk informasi selengkapnya tentang AZURE Identity API dan cara menggunakannya, lihat Pustaka klien Azure Identity

Konsep utama

Ada empat keluarga utama fungsionalitas yang disediakan dalam SDK pratinjau ini:

Pengesahan enklave SGX dan TPM.
Penemuan dan validasi sertifikat penandatanganan Token Pengesahan MAA.
Manajemen Kebijakan Pengesahan.
Manajemen sertifikat manajemen kebijakan pengesahan (ya, manajemen manajemen kebijakan).

Layanan Microsoft Azure Attestation berjalan dalam dua mode terpisah: "Terisolasi" dan "AAD". Ketika layanan berjalan dalam mode "Terisolasi", pelanggan perlu memberikan informasi tambahan di luar kredensial autentikasi mereka untuk memverifikasi bahwa mereka berwenang untuk memodifikasi status instans pengesahan.

Akhirnya, setiap wilayah tempat layanan Azure Attestation tersedia mendukung instans "bersama", yang dapat digunakan untuk membuktikan enklave SGX yang hanya memerlukan verifikasi terhadap garis besar azure (tidak ada kebijakan yang diterapkan pada instans bersama). Pengesahan TPM tidak tersedia dalam instans bersama. Meskipun instans bersama memerlukan autentikasi AAD, instans tersebut tidak memiliki kebijakan RBAC - setiap pelanggan dengan token pembawa AAD yang valid dapat membuktikan menggunakan instans bersama.

Pengesahan

Pengesahan SGX atau TPM adalah proses memvalidasi bukti yang dikumpulkan dari lingkungan eksekusi tepercaya untuk memastikan bahwa ia memenuhi garis besar Azure untuk lingkungan tersebut dan kebijakan yang ditentukan pelanggan yang diterapkan ke lingkungan tersebut.

Penemuan dan validasi sertifikat penandatanganan token layanan pengesahan

Salah satu jaminan operasional inti dari Layanan Azure Attestation adalah bahwa layanan beroperasi "secara operasional dari TCB". Dengan kata lain, tidak mungkin operator Microsoft dapat mengubah pengoperasian layanan, atau merusak data yang dikirim dari klien. Untuk memastikan jaminan ini, inti layanan pengesahan berjalan dalam enklave SGX Intel(tm).

Untuk memungkinkan pelanggan memverifikasi bahwa operasi benar-benar dilakukan di dalam enklave, sebagian besar respons dari Layanan Pengesahan dikodekan dalam JSON Web Token, yang ditandatangani oleh kunci yang disimpan dalam enklave layanan pengesahan.

Token ini akan ditandatangani oleh sertifikat penandatanganan yang dikeluarkan oleh layanan MAA untuk instans yang ditentukan.

Jika instans layanan MAA berjalan di wilayah tempat layanan berjalan di enklave SGX, sertifikat yang dikeluarkan oleh server dapat diverifikasi menggunakan API oe_verify_attestation_certificate.

Manajemen Kebijakan

Setiap instans layanan pengesahan memiliki kebijakan yang diterapkan padanya yang menentukan kriteria tambahan yang telah ditentukan pelanggan.

Untuk informasi selengkapnya tentang kebijakan pengesahan, lihat Kebijakan Pengesahan

Manajemen sertifikat Manajemen Kebijakan

Ketika instans pengesahan berjalan dalam mode "Terisolasi", pelanggan yang membuat instans akan memberikan sertifikat manajemen kebijakan pada saat instans dibuat. Semua operasi modifikasi kebijakan mengharuskan pelanggan menandatangani data kebijakan dengan salah satu sertifikat manajemen kebijakan yang ada. API Manajemen Sertifikat Manajemen Kebijakan memungkinkan klien untuk "menggulung" sertifikat manajemen kebijakan.

Mode Terisolasi dan Mode AAD

Setiap instans layanan Microsoft Azure Attestation beroperasi dalam mode "AAD" atau mode "Terisolasi". Saat instans MAA beroperasi dalam mode AAD, itu berarti bahwa pelanggan yang membuat instans pengesahan memungkinkan Azure Active Directory dan kebijakan kontrol Akses Berbasis Peran Azure untuk memverifikasi akses ke instans pengesahan.

AttestationType

Layanan Azure Attestation mendukung pengesahan berbagai jenis bukti tergantung pada lingkungan. Saat ini, MAA mendukung lingkungan Eksekusi Tepercaya berikut:

OpenEnclave - Prosesor Intel(tm) yang menjalankan kode di Enklave SGX tempat bukti pengesahan dikumpulkan menggunakan OpenEnclave oe_get_report atau oe_get_evidence API.
SgxEnclave - Prosesor Intel(tm) yang menjalankan kode di Enklave SGX tempat bukti pengesahan dikumpulkan menggunakan Intel SGX SDK.
Tpm - Lingkungan Keamanan Berbasis Virtualisasi tempat Modul Platform Tepercaya prosesor digunakan untuk memberikan bukti pengesahan.

Data Runtime dan Data Inittime

RuntimeData mengacu pada data yang disajikan ke logika pembuatan Kuotasi Intel SGX atau oe_get_report/oe_get_evidence API. Jika pemanggil ke API pengesahan menyediakan runtime_data atribut, layanan Azure Attestation akan memvalidasi bahwa 32 byte report_data pertama bidang di SGX Quote/OE Report/OE Evidence cocok dengan hash SHA256 dari runtime_data.

Data InitTime mengacu pada data yang digunakan untuk mengonfigurasi enklave SGX yang dibuktikan.

Perhatikan bahwa data InitTime tidak didukung pada komputer virtual Azure DCsv2-Series .

Konsep tambahan

Membuat instans klien

Membuat instans Klien Pengesahan di uri endpoint.

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

Mendapatkan kebijakan pengesahan

Metode ini set_policy mengambil kebijakan pengesahan dari layanan. Kebijakan Pengesahan di-instans berdasarkan jenis per pengesahan, AttestationType parameter menentukan jenis yang akan diambil.

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

Menetapkan kebijakan pengesahan untuk jenis pengesahan tertentu

Jika instans layanan pengesahan berjalan dalam mode Terisolasi, API set_policy perlu memberikan sertifikat penandatanganan (dan kunci privat) yang dapat digunakan untuk memvalidasi bahwa pemanggil berwenang untuk memodifikasi kebijakan pada instans pengesahan. Jika instans layanan berjalan dalam mode AAD, sertifikat dan kunci penandatanganan bersifat opsional.

Di bawah sampul, API SetPolicy membuat JSON Web Token berdasarkan dokumen kebijakan dan informasi penandatanganan yang dikirim ke layanan pengesahan.

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

Jika instans layanan berjalan dalam mode AAD, panggilan ke set_policy dapat disederhanakan:

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)

Klien harus dapat memverifikasi bahwa dokumen kebijakan pengesahan tidak dimodifikasi sebelum dokumen kebijakan diterima oleh enklave layanan pengesahan.

Ada dua properti yang disediakan dalam PolicyResult yang dapat digunakan untuk memverifikasi bahwa layanan menerima dokumen kebijakan:

policy_signer - jika set_policy panggilan menyertakan sertifikat penandatanganan, ini akan menjadi sertifikat yang disediakan pada saat set_policy panggilan. Jika tidak ada penanda tangan kebijakan yang ditetapkan, ini akan null.
policy_token_hash - ini adalah hash JSON Web Token yang dikirim ke layanan.

Untuk memverifikasi hash, klien dapat menghasilkan token kebijakan pengesahan dan memverifikasi hash yang dihasilkan dari token tersebut:

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`

Membuktikan SGX Enklave

Gunakan metode attest_sgx_enclave untuk membuktikan enklave SGX.

Salah satu tantangan inti yang telah berinteraksi dengan pelanggan dengan lingkungan terenkripsi adalah cara memastikan bahwa Anda dapat berkomunikasi dengan aman dengan kode yang berjalan di lingkungan ("kode enklave").

Salah satu solusi untuk masalah ini adalah apa yang dikenal sebagai "Rilis Kunci Aman", yang merupakan pola yang memungkinkan komunikasi aman dengan kode enklave.

Untuk mengimplementasikan pola "Secure Key Release", kode enklave menghasilkan kunci asimetris sementara. Kemudian menserialisasikan bagian publik kunci ke beberapa format (mungkin JSON Web Key, atau PEM, atau beberapa format serialisasi lainnya).

Kode enklave kemudian menghitung nilai SHA256 dari kunci publik dan meneruskannya sebagai input ke kode yang menghasilkan Kutipan SGX (untuk OpenEnclave, yang akan menjadi oe_get_evidence atau oe_get_report).

Klien kemudian mengirim kutipan SGX dan kunci serial ke layanan pengesahan. Layanan pengesahan akan memvalidasi kuotasi dan memastikan bahwa hash kunci ada dalam kuotasi dan akan mengeluarkan "Token Pengesahan".

Klien kemudian dapat mengirim Token Pengesahan (yang berisi kunci serial) ke pihak ketiga "pihak yang mengandalkan". Pihak yang mengandalkan kemudian memvalidasi bahwa token pengesahan dibuat oleh layanan pengesahan, dan dengan demikian kunci berseri dapat digunakan untuk mengenkripsi beberapa data yang dipegang oleh "pihak yang mengandalkan" untuk dikirim ke layanan.

Contoh ini menunjukkan satu pola umum panggilan ke layanan pengesahan untuk mengambil token pengesahan yang terkait dengan permintaan.

Contoh ini mengasumsikan bahwa Anda memiliki objek yang sudah ada AttestationClient yang dikonfigurasi dengan URI dasar untuk titik akhir Anda. Ini juga mengasumsikan bahwa Anda memiliki Kuotasi SGX (quote) yang dihasilkan dari dalam enklave SGX yang Anda membuktikan, dan "Data Runtime" (runtime_data) yang dirujuk dalam Kuotasi SGX.

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

Pada titik ini, atribut enclave_held_data di attestationResult akan menyimpan runtime_data biner input.

Token sekarang diteruskan ke "pihak yang mengandalkan". Pihak yang mengandalkan akan memvalidasi bahwa token dikeluarkan oleh Layanan Pengesahan. Kemudian mengekstrak kunci asimetris dari bidang EnclaveHeldData. Pihak yang mengandalkan kemudian akan Mengenkripsi data "kunci" menggunakan kunci asimetris dan mengirimkannya kembali ke enklave.

encrypted_data = send_token_to_relying_party(attestationResult.Token)

Sekarang data terenkripsi dapat diteruskan ke enklave yang dapat mendekripsi data tersebut.

Informasi tambahan tentang cara melakukan validasi token pengesahan dapat ditemukan dalam Sampel Pengesahan Layanan MAA.

Mengambil Sertifikat Token

Gunakan get_signing_certificates untuk mengambil sertifikat yang dapat digunakan untuk memvalidasi token yang dikembalikan dari layanan pengesahan.

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)

Pemecahan Masalah

Sebagian besar operasi layanan Pengesahan akan memunculkan pengecualian yang ditentukan dalam Azure Core. API layanan pengesahan akan memunculkan HttpResponseError kegagalan dengan kode kesalahan yang bermanfaat. Banyak dari kesalahan ini dapat dipulihkan.

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
}

Informasi pemecahan masalah tambahan untuk layanan MAA dapat ditemukan di sini

Langkah berikutnya

Untuk informasi selengkapnya tentang layanan Microsoft Azure Attestation, silakan lihat halaman dokumentasi kami.

Berkontribusi

Proyek ini menyambut baik kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi situs Perjanjian Lisensi Kontributor.

Ketika Anda mengirimkan permintaan tarik, CLA-bot akan secara otomatis menentukan apakah Anda perlu memberikan CLA dan menghias PR dengan tepat (misalnya, label, komentar). Cukup ikuti instruksi yang diberikan oleh bot. Anda hanya perlu melakukan ini sekali di semua repos menggunakan CLA kami.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat TANYA JAWAB Umum Kode Etik atau kontak opencode@microsoft.com dengan pertanyaan atau komentar tambahan apa pun.

Lihat CONTRIBUTING.md untuk detail tentang membangun, menguji, dan berkontribusi pada pustaka ini.

Berikan Umpan Balik

Jika Anda menemukan bug atau memiliki saran, silakan ajukan masalah di bagian Masalah proyek.

Tayangan

Bagikan melalui