Bagikan melalui

Azure Attestation pustaka klien untuk JavaScript - versi 1.0.0

  • Artikel

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

Untuk tampilan pustaka Azure yang lebih lengkap, lihat rilis typescript azure sdk.

CATATAN: Ini adalah SDK pratinjau untuk layanan Microsoft Azure Attestation. Ini menyediakan semua fungsi penting untuk mengakses layanan Azure Attestation, itu harus dianggap 'apa adanya" dan dapat berubah di masa depan yang dapat merusak kompatibilitas dengan versi sebelumnya.

Tautan utama:

Memulai

Lingkungan yang didukung saat ini

Lihat kebijakan dukungan kami untuk detail selengkapnya.

Prasyarat

  • Langganan Azure
  • 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.

Pasang paket @azure/attestation

Instal pustaka klien Microsoft Azure Attestation untuk JavaScript dengan NPM:

npm install @azure/attestation

Mengautentikasi klien

Untuk berinteraksi dengan layanan Microsoft Azure Attestation, Anda harus membuat instans kelas Klien Pengesahan atau Klien Administrasi Pengesahan. Anda memerlukan url instans pengesahan, yang akan menjadi "URI Pengesahan" yang ditampilkan di portal, atau akan menjadi salah satu penyedia pengesahan bersama. Anda juga akan memerlukan kredensial klien untuk menggunakan Klien Administrasi Pengesahan atau memanggil attestTpm API. Kredensial klien memerlukan (id klien, rahasia klien, id penyewa) untuk membuat instans objek klien.

Di bagian memulai ini, kami akan mengautentikasi menggunakan kredensial rahasia klien melalui penyedia DefaultAzureCredential , tetapi kami menawarkan lebih banyak mekanisme autentikasi melalui paket @azure/identitas . Untuk menginstal @azure/identity paket:

npm 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:

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.

Terakhir, setiap wilayah tempat layanan Microsoft 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 ke penyedia bersama). Pengesahan TPM tidak tersedia di penyedia 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.

Objek AttestationResponse berisi dua atribut utama: token dan value. Atribut token berisi token lengkap yang dikembalikan oleh layanan pengesahan, value atribut berisi isi respons JSON Web Token.

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

Contoh

Membuat instans klien

Membuat instans Klien Pengesahan di uri endpoint, menggunakan kredensial azure default (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();

Jika Anda tidak memanggil attestTpm API, Anda tidak perlu memberikan kredensial untuk mengakses klien pengesahan. Ini berarti klien dapat dibuat hanya dengan:

const client = new AttestationClient(endpoint);

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

Membuat instans Klien Administrasi Pengesahan di uri endpoint.

Perhatikan bahwa klien administrasi memerlukan kredensial Azure.

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

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

Mendapatkan kebijakan pengesahan

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

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

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 penelepon berwenang untuk memodifikasi kebijakan pada instans pengesahan. Jika instans layanan berjalan dalam mode AAD, maka sertifikat dan kunci penandatanganan bersifat opsional.

Jika instans layanan berjalan dalam mode AAD, panggilan ke setPolicy seperti yang diharapkan:

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

Jika instans layanan berjalan dalam mode Terisolasi, panggilan ke setPolicy mengharuskan klien dapat membuktikan bahwa mereka memiliki akses ke salah satu kunci dan sertifikat privat manajemen kebijakan.

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

Di bawah sampul, api setPolicy membuat JSON Web Token yang berisi pada dokumen certificate kebijakan dan ditandatangani dengan privateKey yang kemudian dikirim ke layanan pengesahan.

Jika klien ingin memastikan bahwa dokumen kebijakan pengesahan tidak dimodifikasi sebelum dokumen kebijakan diterima oleh enklave layanan pengesahan, mereka dapat menggunakan properti yang dikembalikan dalam objct PolicyResult yang dapat digunakan untuk memverifikasi bahwa layanan menerima dokumen kebijakan:

  • policySigner - jika setPolicy panggilan menyertakan certificate, nilai ini akan menjadi sertifikat yang disediakan pada saat setPolicy panggilan. Jika tidak ada penanda tangan kebijakan yang ditetapkan, ini akan null.
  • policyTokenHash - ini adalah hash JSON Web Signature yang dikirim ke layanan untuk api setPolicy.

Untuk memverifikasi hash, klien dapat membuat token kebijakan pengesahan (kelas pembantu yang mewakili token yang digunakan untuk mengatur kebijakan pengesahan) dan memverifikasi hash yang dihasilkan dari token tersebut:

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

Membuktikan SGX dan Open Enclave

attestSgxEnclave Gunakan metode 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 menerapkan pola "Rilis Kunci Aman", 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 SGX Quote (untuk OpenEnclave, yang akan menjadi oe_get_evidence atau oe_get_report).

Klien kemudian mengirim kutipan SGX dan kunci berseri 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 itu (yang berisi kunci serial) ke pihak ke-3 "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 disimpan 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 Attest untuk titik akhir Anda. Ini juga mengasumsikan bahwa Anda memiliki laporan OpenEnclave (report) yang dihasilkan dari dalam enklave SGX yang Anda uji, dan "Data Runtime" (binaryRuntimeData) yang dirujuk dalam Kuotasi SGX.

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

Ada kemungkinan juga bahwa yang binaryRuntimeData dikirim ke layanan pengesahan dimaksudkan untuk ditafsirkan sebagai data JSON. Dalam hal ini, klien harus menentukan runTimeJson dalam panggilan API pengesahan:

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

Demikian pula, jika Anda menggunakan Intel SDK untuk menghasilkan "kutipan", Anda dapat memvalidasi kutipan menggunakan:

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

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

Mengambil Sertifikat Token

Gunakan getSigningCertificates untuk mengambil sertifikat yang dapat digunakan untuk memvalidasi token yang dikembalikan dari layanan pengesahan. Perhatikan bahwa panggilan ini membuat klien dengan kredensial azure, yang tidak diperlukan jika Anda memanggil attestSgxEnclave API atau attestOpenEnclave

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

const attestationSigners = await client.getAttestationSigners();

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

Pemecahan Masalah

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

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

Pencatatan

Mengaktifkan pengelogan dapat membantu menemukan informasi yang berguna tentang kegagalan. Untuk melihat log permintaan dan respons HTTP, atur variabel lingkungan AZURE_LOG_LEVEL ke info. Atau, pengelogan dapat diaktifkan saat runtime dengan memanggil setLogLevel di @azure/logger:

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

setLogLevel("info");

Untuk instruksi lebih rinci tentang cara mengaktifkan log, Anda dapat melihat dokumen paket @azure/pencatat.

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