Microsoft Azure 證明(MAA)服務是一種統一解決方案,用於遠端驗證平台的可信度以及其內部執行的二進位檔案完整性。 該服務支援由可信平台模組(TPMs)支援的平台認證,並能對可信執行環境(TEE)如 Intel™ 軟體守護擴充(SGX)enclaves 及基於虛擬化的安全(VBS)enclave 進行認證。
證明程序會證明軟體二進位檔已在信任的平台上正確地具現化。 然後,遠端信賴方就可以確信,只有這類預定的軟體會在受信任的硬體上執行。 Azure 證明是經過統整且面向客戶的證明服務與架構。
Azure 認證能實現尖端安全範式,如 Azure 機密運算與智慧邊緣保護。 客戶一直要求能夠獨立驗證機器的位置、該機器上虛擬機(VM)的狀態,以及該虛擬機上執行的 enclave 環境。 Azure 認證將賦能這些以及許多額外的客戶需求。
Azure 認證從計算實體接收證據,將其轉化為一組理賠,根據可配置的政策驗證,並為基於理賠的應用(例如依賴方與稽核機關)產生密碼學證明。
如需更完整的 Azure 函式庫檢視,請參閱 azure SDK Typescript 版本。
注意:這是 Microsoft Azure 證明 服務的預覽 SDK。 它提供存取Azure 證明服務的所有必要功能,應視為「as-is」,未來可能會有變更,可能導致與舊版本的相容性受損。
主要連結:
開始使用
目前支援的環境
- Node.js的 LTS 版本
- 最新版的 Safari、Chrome、Edge 和 Firefox。
如需詳細資訊,請參閱我們的支援原則。
Prerequisites
- Azure 訂用帳戶
- 現有的 Azure 證明 實例,或您可以使用每個 Azure 區域提供的「共用提供者」。 如果您需要建立 Azure 證明 服務實例,可以使用 Azure 入口網站 或 Azure CLI。
安裝 @azure/attestation 套件
安裝 Microsoft Azure 證明 客戶端函式庫用於 JavaScript with NPM:
npm install @azure/attestation
驗證客戶端
若要與 Microsoft Azure 證明 服務互動,您需要建立 Attestation Client 或 Attestation Administration Client 類別的實例。 你需要一個 attestation instance 的 URL,它要麼是入口網站中顯示的「Attest URI」,要麼是共享的阿塔塞普提供者之一。
您也需要用戶端憑證才能使用認證管理用戶端或呼叫 attestTpm API。 用戶端憑證需要( client id、client secret、tenant id) 來實例化用戶端物件。
在本入門章節中,我們將透過 DefaultAzureCredential 提供者使用用戶端密鑰認證進行驗證,但我們也透過 @azure/身份 套件提供更多驗證機制。 安裝套件 @azure/identity 的方法如下:
npm install @azure/identity
建立/取得憑證
請使用下方的 Azure CLI 片段來建立或取得客戶端秘密憑證。
建立服務主體並設定其對 Azure 資源的存取權限:
az ad sp create-for-rbac -n <your-application-name> --skip-assignment輸出:
{ "appId": "generated-app-ID", "displayName": "dummy-app-name", "name": "http://dummy-app-name", "password": "random-password", "tenant": "tenant-ID" }請注意服務主體的「objectId」
az ad sp show --id <appId> --query objectId輸出:
"<your-service-principal-object-id>"使用上述回傳的認證來設定 AZURE_CLIENT_ID (appId)、 AZURE_CLIENT_SECRET (密碼)及 AZURE_TENANT_ID (租戶)環境變數。 以下範例展示了在 Powershell 中實現此操作的方法:
$Env:AZURE_CLIENT_ID="generated-app-ID"
$Env:AZURE_CLIENT_SECRET="random-password"
$Env:AZURE_TENANT_ID="tenant-ID"
如需有關 Azure 身份識別 API 及其使用方式的更多資訊,請參閱 Azure 身份識別用戶端函式庫
關鍵概念
此預覽 SDK 提供四大主要功能族:
- SGX 與 TPM 飛地認證。
- MAA 認證憑證簽署憑證的發現與驗證。
- 認證政策管理。
- 認證政策管理憑證管理(是的,政策管理管理)。
Microsoft Azure 認證服務有兩種獨立模式:「隔離」與「AAD」。 當服務以「隔離」模式運行時,客戶需要提供除認證憑證外的額外資訊,以驗證他們是否有權修改證明實例的狀態。
最後,每個提供 Microsoft Azure 證明 服務的區域都支援一個「共享」實例,可用來證明只需與 Azure 基準驗證的 SGX 附屬區(共享提供者不適用任何政策)。 TPM 證明在共用提供者中無法提供。 雖然共享實例需要 AAD 驗證,但不具備任何 RBAC 政策——任何擁有有效 AAD 持有憑證的客戶都可以使用該共享實例來證明。
Attestation
SGX 或 TPM 認證是驗證從受信任執行環境中收集的證據的過程,以確保其符合該環境的 Azure 基準及客戶自訂的政策。
認證服務令牌簽署憑證的發現與驗證
Azure 證明 服務的核心營運保證之一是該服務「在 TCB 內運作」。 換句話說,Microsoft 營運商不可能篡改服務的運作,或破壞客戶端傳送的資料。 為確保此項保證,認證服務的核心運行於 Intel(tm) SGX 隱居區中。
為了讓客戶能夠驗證操作是否確實在 enclave 內執行,來自 Attestation Service 的大多數回應都以 JSON Web Token 編碼,該 Web Token 由持有於 attestation service enclave 內的金鑰簽署。
此憑證將由 MAA 服務為指定實例簽發的簽署憑證簽署。
如果 MAA 服務實例運行於該服務在 SGX enclave 的區域,則可透過 oe_verify_attestation_certificate API 驗證伺服器所發出的憑證。
該 AttestationResponse 物件包含兩個主要屬性: token 以及 value。 屬性包含 token 由證明服務回傳的完整令牌,該 value 屬性包含 JSON Web Token 回應的主體。
原則管理
每個證明服務實例都有一套政策,定義客戶所定義的額外標準。
欲了解更多關於公證政策的資訊,請參閱 公證政策
政策管理憑證管理
當證明實例以「隔離」模式執行時,建立該實例的客戶會在實例建立時提供政策管理憑證。 所有政策修改操作都要求客戶使用現有的政策管理憑證之一簽署政策資料。 政策管理憑證管理 API 讓用戶端能夠「滾」政策管理憑證。
隔離模式與 AAD 模式
每個 Microsoft Azure 證明 服務實例皆以「AAD」模式或「隔離」模式運作。 當 MAA 實例以 AAD 模式運作時,表示建立該認證實例的客戶允許 Azure Active Directory 與 Azure 基於角色的存取控制原則驗證對該認證實例的存取權限。
AttestationType
Microsoft Azure 證明 服務支援依據環境不同類型驗證不同類型的證據。 目前,MAA 支援以下受信任執行環境:
- OpenEnclave——一個在 SGX Enclave 中執行程式碼的 Intel(tm) 處理器,並透過 OpenEnclave
oe_get_report或oe_get_evidenceAPI 收集認證證據。 - SgxEnclave——一款在 SGX Enclave 中執行程式碼的 Intel(tm) 處理器,並透過 Intel SGX SDK 收集認證證據。
- Tpm - 基於虛擬化的安全環境,使用處理器的可信平台模組提供證明證據。
執行時資料與初始時間資料
RuntimeData 指的是呈現給 Intel SGX 報價產生邏輯或 oe_get_report/oe_get_evidence API 的資料。 如果 attest API 的呼叫者提供了runtime_data屬性,Azure 證明 服務將驗證 SGX Quote/OE Report/OE Evidence 中欄位report_data的前 32 位元組是否與 的 SHA256 雜湊runtime_data值相符。
InitTime 資料指的是用於設定被認證的 SGX 隔間的資料。
請注意,Azure DCsv2 系列虛擬機器不支援 InitTime 資料。
附加概念
範例
建立用戶端實例
使用預設的 Azure 憑證(DefaultAzureCredential)建立 uri endpoint的 Attestation Client 實例。
import { DefaultAzureCredential } from "@azure/identity";
import { AttestationClient } from "@azure/attestation";
const endpoint = "https://<attestation-instance>.<region>.attest.azure.net";
const credentials = new DefaultAzureCredential();
const client = new AttestationClient(endpoint, credentials);
// Retrieve the set of attestation policy signers from the attestation client.
const attestationSigners = await client.getAttestationSigners();
如果您不 attestTpm 呼叫 API,則無需提供憑證即可存取認證用戶端。 這表示客戶端只需以下方式即可建立:
import { AttestationClient } from "@azure/attestation";
const endpoint = "https://<attestation-instance>.<region>.attest.azure.net";
const client = new AttestationClient(endpoint);
// Retrieve the set of attestation policy signers from the attestation client.
const attestationSigners = await client.getAttestationSigners();
建立一個位於 uri endpoint的 Attestation Administration Client 實例。
請注意,管理用戶端需要 Azure 憑證。
import { AttestationAdministrationClient, KnownAttestationType } from "@azure/attestation";
import { DefaultAzureCredential } from "@azure/identity";
const endpoint = "https://<attestation-instance>.<region>.attest.azure.net";
const client = new AttestationAdministrationClient(endpoint, new DefaultAzureCredential());
// Retrieve the SGX policy from the specified attestation instance.
const policyResponse = await client.getPolicy(KnownAttestationType.SgxEnclave);
取得認證政策
此 getPolicy 方法從服務中擷取證明原則。
Attestation Policy 會依照每個 attestation 類型進行實例化,該 AttestationType 參數定義要擷取的實例類型。
import { AttestationAdministrationClient, KnownAttestationType } from "@azure/attestation";
import { DefaultAzureCredential } from "@azure/identity";
const endpoint = "https://<attestation-instance>.<region>.attest.azure.net";
const client = new AttestationAdministrationClient(endpoint, new DefaultAzureCredential());
const policyResponse = await client.getPolicy(KnownAttestationType.OpenEnclave);
為指定的證明類型設定證明原則
如果認證服務實例以隔離模式執行,set_policy API 需要提供一份簽署憑證(以及私鑰),用來驗證呼叫者是否被授權修改該認證實例的政策。 如果服務實例以 AAD 模式執行,則簽署憑證與金鑰為可選。
如果服務實例以 AAD 模式執行,對 setPolicy 的呼叫如下:
import { AttestationAdministrationClient, KnownAttestationType } from "@azure/attestation";
import { DefaultAzureCredential } from "@azure/identity";
const endpoint = "https://<attestation-instance>.<region>.attest.azure.net";
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);
如果服務實例以隔離模式執行,呼叫 setPolicy 需要用戶端能證明他們能存取其中一個政策管理私鑰與憑證。
import { AttestationAdministrationClient, KnownAttestationType } from "@azure/attestation";
import { DefaultAzureCredential } from "@azure/identity";
const endpoint = "https://<attestation-instance>.<region>.attest.azure.net";
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,
});
在這些 Covers 之下,setPolicy API 會建立一個包含政策文件certificate並簽署privateKey的 JSON Web Token ,然後傳送給認證服務。
如果客戶希望確保在政策文件被認證服務的 enclave 收到之前,該文件並未被修改,他們可以使用 PolicyResult 物件中回傳的屬性,以驗證服務是否收到該政策文件:
-
policySigner- 若setPolicy通話包含 ,certificate則此值為通話時提供的setPolicy憑證。 如果未設定任何政策簽署者,則此值為空。 -
policyTokenHash- 這是傳送給服務的 set Policy API 的 JSON Web Signature 雜湊值。
為了驗證雜湊值,用戶端可以建立一個 attestation policy token(代表用來設定 attestation policy 的 token 的輔助類別),並驗證由該 token 產生的雜湊值:
import { createAttestationPolicyToken } from "@azure/attestation";
import { createHash } from "node:crypto";
// 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 expectedPolicy = createAttestationPolicyToken(`<Policy Document>`, privateKey, certificate);
// Use your favorite SHA256 hash generator function to create a hash of the stringified JWS.
const expectedHash = createHash("sha256").update(expectedPolicy.serialize()).digest("hex");
請證明 SGX 與 Open Enclave
使用該 attestSgxEnclave 方法來認證 SGX 飛地。
客戶在與加密環境互動時面臨的核心挑戰之一,是如何確保您能安全地與環境中執行的程式碼(「隔離程式碼」)通訊。
解決這個問題的一種方法是所謂的「安全金鑰釋放」,這是一種模式,能讓與 enclave 程式碼進行安全通訊。
為了實作「安全金鑰釋放」模式,飛區程式碼會產生一個短暫的非對稱金鑰。 接著它會將公鑰部分序列化成某種格式(可能是 JSON Web Key、PEM 或其他序列化格式)。
接著,enclave 程式碼會計算公鑰的 SHA256 值,並將其作為輸入傳給程式碼,程式碼會產生 SGX 引號(在 OpenEnclave,則是 oe_get_evidence 或 oe_get_report)。
客戶端接著將 SGX 報價和序列化金鑰傳送給認證服務。 認證服務會驗證報價,確保報價中包含金鑰的雜湊值,並會發出「證明令牌」。
客戶端接著可以將該證明令牌(包含序列化金鑰)傳送給第三方「依賴方」。 依賴方隨後會驗證該證明令牌是由該證明服務所建立,因此序列化的金鑰可以用來加密「依賴方」持有的部分資料,並傳送給該服務。
此範例展示了一個常見模式:呼叫到證明服務以取得與請求相關聯的證明權杖。
此範例假設您已有已設定端點 Attest URI 的物件 AttestationClient 。 它也假設你有從你測試的 SGX 接點內產生的 OpenEnclave 報告report(),以及 SGX 報價中引用的「執行時資料」(binaryRuntimeData)。
import { DefaultAzureCredential } from "@azure/identity";
import { AttestationClient } from "@azure/attestation";
const endpoint = "https://<attestation-instance>.<region>.attest.azure.net";
const credentials = new DefaultAzureCredential();
const client = new AttestationClient(endpoint, credentials);
const report = new Uint8Array(0); // Report data from the enclave.
const binaryRuntimeData = new Uint8Array(0); // Runtime data from the enclave.
const attestationResult = await client.attestOpenEnclave(report, {
runTimeData: binaryRuntimeData,
});
也有可能傳送給認證服務的檔案 binaryRuntimeData 是打算被解讀為 JSON 資料。 在這種情況下,客戶端應在 attest API 呼叫中指定 runTimeJson :
import { DefaultAzureCredential } from "@azure/identity";
import { AttestationClient } from "@azure/attestation";
const endpoint = "https://<attestation-instance>.<region>.attest.azure.net";
const credentials = new DefaultAzureCredential();
const client = new AttestationClient(endpoint, credentials);
const report = new Uint8Array(0); // Report data from the enclave.
const binaryRuntimeData = new Uint8Array(0); // Runtime JSON data from the enclave.
const attestationResult = await client.attestOpenEnclave(report, {
runTimeJson: binaryRuntimeData,
});
同樣地,如果你使用 Intel SDK 來產生「報價」,你可以用以下方式驗證該報價:
import { DefaultAzureCredential } from "@azure/identity";
import { AttestationClient } from "@azure/attestation";
const endpoint = "https://<attestation-instance>.<region>.attest.azure.net";
const credentials = new DefaultAzureCredential();
const client = new AttestationClient(endpoint, credentials);
const quote = new Uint8Array(0); // Quote data.
const binaryRuntimeData = new Uint8Array(0); // Runtime JSON data from the enclave.
const attestationResult = await client.attestSgxEnclave(quote, {
runTimeData: binaryRuntimeData,
});
關於如何執行證明令牌驗證的更多資訊,請參閱 MAA 服務認證範例。
取得代幣憑證
用 getSigningCertificates 來擷取可用來驗證從認證服務回傳的憑證。 請注意,此呼叫會建立一個具有 Azure 憑證的用戶端,但如果您呼叫 attestSgxEnclave OR attestOpenEnclave API 則不需要
import { DefaultAzureCredential } from "@azure/identity";
import { AttestationClient } from "@azure/attestation";
const endpoint = "https://<attestation-instance>.<region>.attest.azure.net";
const credentials = new DefaultAzureCredential();
const client = new AttestationClient(endpoint, credentials);
const attestationSigners = await client.getAttestationSigners();
console.log(`There are ${attestationSigners.length} signers`);
Troubleshooting
大多數 Attestation 服務操作都會觸發 Azure Core 中定義的例外。 認證服務 API 會在失敗時拋出 RestError 帶有實用錯誤代碼的錯誤代碼。 許多錯誤是可以恢復的。
import { DefaultAzureCredential } from "@azure/identity";
import { AttestationClient } from "@azure/attestation";
const endpoint = "https://<attestation-instance>.<region>.attest.azure.net";
const credentials = new DefaultAzureCredential();
const client = new AttestationClient(endpoint, credentials);
const openEnclaveReport = new Uint8Array(0); // Open enclave report data
try {
await client.attestSgxEnclave(openEnclaveReport);
} catch (error) {
console.log(`Exception thrown for invalid request: ${error.message}`);
}
Logging
啟用記錄可能有助於找出有關失敗的實用資訊。 若要查看 HTTP 要求和回應的記錄,請將 AZURE_LOG_LEVEL 環境變數設定為 info。 或者,您可以在運行時間啟用記錄,方法是在 setLogLevel中呼叫 @azure/logger:
import { setLogLevel } from "@azure/logger";
setLogLevel("info");
如需如何啟用記錄的詳細指示,請參閱
關於 MAA 服務的更多故障排除資訊,請 見此處
下一步
欲了解更多關於 Microsoft Azure 認證服務的資訊,請參閱我們的 文件頁面。
Contributing
此項目歡迎參與和建議。 大部分的捐款都要求您同意「參與者許可協定」(CLA),宣告您有權,而且實際上確實會授與我們使用您貢獻的許可權。 詳情請參閱 貢獻者授權協議網站。
當您提交提取要求時,CLA-Bot 會自動判斷您是否需要提供 CLA 並適當裝飾 PR(例如標籤、批註)。 只要遵循 Bot 所提供的指示即可。 您只需要使用我們的 CLA 在所有存放庫上執行此動作一次。
此專案採用了 Microsoft 開放原始碼管理辦法。 欲了解更多資訊,請參閱行為準則常見問題集,或如有其他問題或意見,請與我們聯絡 opencode@microsoft.com 。
請參閱 CONTRIBUTING.md ,了解如何建置、測試及貢獻這些函式庫。
提供意見反應
如果您遇到任何錯誤或有建議,請在本專案的 「問題 」區段提出問題。