Azure 證明 JavaScript 的用戶端程式庫 - 1.0.0 版

Microsoft Azure 證明 (MAA) 服務是一種統一的解決方案，可遠端驗證平臺的可靠度，以及在其中執行之二進位檔的完整性。 此服務支援信賴平臺模組支援的平臺證明 (TPM) ，以及證明信任執行環境的狀態 (TEE) ，例如 Intel (tm) Software Guard Extensions (SGX) 記憶體保護區和虛擬化型安全性 (VBS) 記憶體保護區。

證明程序會證明軟體二進位檔已在信任的平台上正確地具現化。 然後，遠端信賴憑證者就可以放心地相信，只有這類預期的軟體會在受信任的硬體上執行。 Azure 證明是經過統整且面向客戶的證明服務與架構。

Azure 證明提供最新的安全性典範，例如 Azure 機密運算和智慧邊緣保護。 客戶一直希望能夠獨立驗證機器的位置、該機器上的虛擬機器 (VM) 狀態，以及該 VM 上所執行記憶體保護區內的環境。 Azure 證明可支援這些要求，以及許多額外的客戶要求。

Azure 證明會從計算實體接收證據、將其轉換成一組宣告、針對可設定的原則進行驗證，然後為宣告式應用程式 (例如信賴憑證者和稽核授權單位) 產生密碼編譯證明。

如需更完整的 Azure 程式庫檢視，請參閱 Azure sdk typescript 版本。

注意：這是 Microsoft Azure 證明 服務的預覽 SDK。 它提供存取Azure 證明服務的所有基本功能，應該視為「原狀」，且未來可能會中斷與舊版的相容性。

重要連結：

• 原始程式碼 \(英文\)
• 套件 (NPM)
• API 參考文件
• 產品文件

開始使用

目前支援的環境

• LTS 版本的 Node.js
• Safari、Chrome、Edge 和 Firefox 的最新版本。

如需詳細資訊，請參閱我們的支援原則。

必要條件

• Azure 訂用帳戶
• 現有的 Azure 證明 實例，或者您可以使用每個 Azure 區域中可用的「共用提供者」。 如果您需要建立Azure 證明服務實例，您可以使用 Azure 入口網站或Azure CLI。

安裝 @azure/attestation 套件

使用NPM安裝適用于 JavaScript 的 Microsoft Azure 證明 用戶端程式庫：

npm install @azure/attestation

驗證用戶端

若要與 Microsoft Azure 證明 服務互動，您必須建立證明用戶端或證明系統管理用戶端類別的實例。 您需要 證明實例 URL，這會是入口網站中顯示的「證明 URI」，或會是其中一個共用證明提供者。 您也需要用戶端認證，才能使用證明系統管理用戶端或呼叫 attestTpm API。 用戶端認證需要 (用戶端識別碼、用戶端密碼、租使用者識別碼) 具現化用戶端物件。

在此使用者入門一節中，我們將透過 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 證明服務可用的每個區域都支援「共用」實例，其可用來證明 SGX 記憶體保護區只需要對 azure 基準進行驗證， (共用提供者) 沒有套用原則。 共用提供者中無法使用 TPM 證明。 雖然共用實例需要 AAD 驗證，但沒有任何 RBAC 原則 - 任何具有有效 AAD 持有人權杖的客戶都可以使用共用實例來證明。

證明

SGX 或 TPM 證明是驗證從信任執行環境收集的辨識項的程式，以確保它符合該環境的 Azure 基準，以及套用至該環境的客戶定義原則。

證明服務權杖簽署憑證探索和驗證

Azure 證明服務的核心作業保證之一，就是服務在 TCB 外運作。 換句話說，Microsoft 操作員無法竄改服務的作業，或從用戶端傳送的資料損毀。 為了確保這項保證，證明服務的核心會在 Intel (tm) SGX 記憶體保護區中執行。

為了讓客戶確認作業實際上是在記憶體保護區內執行，來自證明服務的大多數回應都會編碼在 JSON Web 權杖中，此權杖是由證明服務記憶體保護區內保留的金鑰所簽署。

此權杖將由 MAA 服務針對指定實例所簽發的簽署憑證簽署。

如果 MAA 服務實例是在 SGX 記憶體保護區中執行服務的區域中執行，則可以使用 oe_verify_attestation_certificate API來驗證服務器所簽發的憑證。

物件 AttestationResponse 包含兩個主要屬性： token 和 value 。 屬性 token 包含證明服務傳回的完整權杖，屬性 value 包含 JSON Web 權杖回應的主體。

原則管理

每個證明服務實例都會套用原則，以定義客戶已定義的其他準則。

如需證明原則的詳細資訊，請參閱 證明原則

原則管理憑證管理

當證明實例以「隔離」模式執行時，建立實例的客戶會在建立實例時提供原則管理憑證。 所有原則修改作業都需要客戶使用其中一個現有的原則管理憑證來簽署原則資料。 原則管理憑證管理 API 可讓用戶端「變換」原則管理憑證。

隔離模式和 AAD 模式

每個 Microsoft Azure 證明服務實例都會以「AAD」模式或「隔離」模式運作。 當 MAA 實例以 AAD 模式運作時，這表示建立證明實例的客戶允許 Azure Active Directory 和 Azure 角色型存取控制原則來驗證證明實例的存取權。

AttestationType

Microsoft Azure 證明服務支援根據環境來證明不同類型的辨識項。 MAA 目前支援下列信任的執行環境：

• OpenEnclave - Intel (tm) 處理器，在 SGX 記憶體保護區中執行程式碼，其中使用 OpenEnclave oe_get_report 或 oe_get_evidence API 收集證明辨識項。
• SgxEnclave - Intel (tm) 處理器，在 SGX 記憶體保護區中執行程式碼，其中使用 Intel SGX SDK 收集證明辨識項。
• Tpm - 虛擬化型安全性環境，其中處理器的信賴平臺模組用來提供證明辨識項。

執行時間資料和 Inittime 資料

RuntimeData 是指呈現給 Intel SGX 報價產生邏輯或 oe_get_report/oe_get_evidence API 的資料。 如果證明 API 的呼叫端提供 runtime_data 屬性，則Azure 證明服務會驗證 SGX 引號/OE 報表/OE 辨識項中欄位的前 32 個位元組 report_data 符合 的 runtime_data SHA256 雜湊。

InitTime 資料是指用來設定要證明之 SGX 記憶體保護區的資料。

請注意，Azure DCsv2 系列 虛擬機器不支援 InitTime 資料。

其他概念

範例

• 建立證明用戶端實例
• 證明 SGX 記憶體保護區
• 取得證明原則
• 擷取權杖驗證憑證
• 建立證明用戶端實例

建立用戶端實例

使用預設 azure 認證 () DefaultAzureCredential ，在 uri endpoint 上建立證明用戶端的實例。

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

如果您未呼叫 attestTpm API，則不需要提供認證來存取證明用戶端。 這表示只要使用下列專案即可建立用戶端：

const client = new AttestationClient(endpoint);

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

在 uri endpoint 建立證明系統管理用戶端的實例。

請注意，系統管理用戶端 需要 Azure 認證。

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

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

取得證明原則

方法 getPolicy 會從服務擷取證明原則。 證明原則是以個別證明類型為基礎 AttestationType 來實例，參數會定義要擷取的實例類型。

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

為指定的證明類型設定證明原則

如果證明服務實例是以隔離模式執行，set_policy API 必須提供簽署憑證 (和私密金鑰) ，以便用來驗證呼叫端是否已獲授權修改證明實例上的原則。 如果服務實例是以 AAD 模式執行，則簽署憑證和金鑰是選擇性的。

如果服務實例是以 AAD 模式執行，則 setPolicy 的呼叫會如預期般執行：

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 的呼叫會要求用戶端能夠證明他們能夠存取其中一個原則管理私密金鑰和憑證。

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

實際上，setPolicy API 會建立 JSON Web 權杖 ，其中包含在原則檔 certificateprivateKey 上，並使用 簽署，然後傳送至證明服務。

如果用戶端想要確保證明原則檔在證明服務記憶體保護區收到原則檔之前未修改，則可以使用 PolicyResult 遮蔽中傳回的屬性，可用來驗證服務是否收到原則檔：

• policySigner - 如果 setPolicy 呼叫包含 certificate ，這個值將會是呼叫時 setPolicy 提供的憑證。 如果未設定任何原則簽署者，這會是 Null。
• policyTokenHash - 這是傳送至 setPolicy API 服務之 JSON Web 簽章 的雜湊。

若要驗證雜湊，用戶端可以在協助程式類別 (建立證明原則權杖，此類別代表用來設定證明原則的權杖) ，並驗證從該權杖產生的雜湊：

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

證明 SGX 和開啟記憶體保護區

attestSgxEnclave使用 方法來證明 SGX 記憶體保護區。

客戶與加密環境互動的核心挑戰之一，是如何確保您可以安全地與環境中執行的程式碼通訊 (「記憶體保護區程式碼」) 。

此問題的其中一個解決方案是所謂的「安全金鑰發行」，這是一種模式，可啟用與記憶體保護區程式碼的安全通訊。

為了實作「安全金鑰發行」模式，記憶體保護區程式碼會產生暫時的非對稱金鑰。 然後，它會將金鑰的公用部分序列化為某些格式， (可能是 JSON Web 金鑰或 PEM，或某些其他序列化格式) 。

然後記憶體保護區程式碼會計算公開金鑰的 SHA256 值，並將其當做輸入傳遞給產生 OpenEnclave 的 SGX Quote (的程式碼，這會是 oe_get_evidence 或 oe_get_report) 。

然後，用戶端會將 SGX 引號和序列化金鑰傳送至證明服務。 證明服務會驗證引號，並確保金鑰的雜湊出現在引號中，併發出「證明權杖」。

然後，用戶端可以將該證明權杖傳送 (，其中包含序列化金鑰) 給協力廠商「信賴憑證者」。 信賴憑證者接著會驗證證明權杖是由證明服務所建立，因此序列化金鑰可用來加密「信賴憑證者」用來傳送至服務的某些資料。

此範例示範呼叫證明服務的常見模式，以擷取與要求相關聯的證明權杖。

此範例假設您有一個現有 AttestationClient 物件，其已設定端點的證明 URI。 它也會假設您有 OpenEnclave 報表 (report) 從您證明的 SGX 記憶體保護區內產生，而 「執行時間資料」 () binaryRuntimeData 在 SGX 引號中參考。

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

此外，傳送至證明服務的 也可能 binaryRuntimeData 要解譯為 JSON 資料。 在此情況下，用戶端應該在證明 API 呼叫中指定 runTimeJson ：

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

同樣地，如果您使用 Intel SDK 來產生「引號」，您可以使用下列專案來驗證報價：

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

如需有關如何執行證明權杖驗證的其他資訊，請參閱 MAA 服務證明範例。

擷取權杖憑證

使用 getSigningCertificates 來擷取可用來驗證從證明服務傳回的權杖的憑證。 請注意，此呼叫會建立具有 Azure 認證的用戶端，如果您呼叫 attestSgxEnclave 或 attestOpenEnclave API，則不需要此用戶端

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

const attestationSigners = await client.getAttestationSigners();

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

疑難排解

大部分證明服務作業都會引發 Azure Core中定義的例外狀況。 證明服務 API 會在失敗時擲回 RestError ，並出現有用的錯誤碼。 這些錯誤有許多是可復原的。

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

記錄

啟用記錄有助於找出失敗的相關實用資訊。 若要查看 HTTP 的要求和回應記錄，請將 AZURE_LOG_LEVEL 環境變數設定為 info。 或者，您可以在 @azure/logger 中呼叫 setLogLevel，以在執行階段啟用記錄：

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

setLogLevel("info");

如需如何啟用記錄的詳細指示，可參閱 @azure/logger 套件文件。

您可以在這裡找到 MAA 服務的其他疑難排解資訊

下一步

如需 Microsoft Azure 證明服務的詳細資訊，請參閱我們的檔頁面。

參與

此專案歡迎參與和提供建議。 大部分的參與都要求您同意「參與者授權合約 (CLA)」，宣告您有權且確實授與我們使用投稿的權利。 如需詳細資訊，請流覽 參與者授權合約網站。

當您提交提取要求時，CLA Bot 會自動判斷您是否需要提供 CLA，並適當地裝飾 PR (例如標籤、註解)。 請遵循 bot 提供的指示。 您只需要使用我們的 CLA 在所有存放庫上執行此動作一次。

此專案採用 Microsoft Open Source Code of Conduct (Microsoft 開放原始碼管理辦法)。 如需詳細資訊，請參閱「管理辦法常見問題集」，如有任何其他問題或意見請連絡 opencode@microsoft.com。

如需建置、測試及參與這些程式庫的詳細資訊，請參閱 CONTRIBUTING.md 。

提供意見反應

如果您遇到任何錯誤或有建議，請在專案的 [ 問題 ] 區段中提出問題。

相關專案

• Microsoft Azure SDK for JAVAscript