JavaScript 的 Azure 测试客户端库
微软Azure Attestation(MAA)服务是远程验证一个平台的可信赖性和运行在其内部的二进制完整性的统一解决方案. 该服务支持验证由受托平台模块(TPM)支持的平台,同时证明Intel(tm)软件守护扩展(SGX)飞地和虚拟化安全(VBS)飞地等可信执行环境(TEEs)状态的能力.
验证是证明软件二进制在被信任的平台上被适当即时化的过程. 远程依赖方可以由此获得信心,相信只有这种预定的软件在被信任的硬件上运行. Azure Attestation是统一的客户服务与证明框架.
Azure Attestation可以实现Azure机密计算和智能边缘保护等尖端安全范式. 客户一直要求有能力独立核实机器的位置、虚拟机器在该机器上的姿态以及飞地在该机器上运行的环境。 Azure Attestation将授权这些和许多其他客户请求.
Azure Attestation从计算实体获得证据,将它们变成一套索赔,对照可配置的政策予以验证,并为基于索赔的应用(例如依赖方和审计当局)提供加密证明.
关于Azure图书馆的更完整的视图,请参见: zure sdk 打印符发布。 。 。 .
注:这是微软Azure测试服务的预览SDK. 它为访问Azure Attestation服务提供了所有的基本功能,它应被视为'as-is',并且会在未来发生可能与之前版本相容的改变.
密钥链接 :
开始
目前得到支持的环境
- 节点.js的LTS版本
- Safari,Chrome,Edge,和Firefox的最新版本.
看我们的 支助政策 更多细节.
先决条件
- 一个 Azure 订阅
- 现有的 Azure 验证实例, 或者您可以使用每个 Azure 区域可用的“ 共享提供者 ” 。 如果您需要创建 Azure 验证服务实例, 您可以使用 Azure 门户或 阿苏尔CLI。 。 。 .
安装 @ azure/ 测试包
为 JavaScript 安装 Microsoft Azure 测试客户端库 国家预防机制数字 :
npm install @azure/attestation
认证客户端
为了与微软Azure Attestation服务互动,您需要创建实例 验证客户端 或者说 验证管理客户端 课。 你需要一个 证明实例url,它要么是"测试URI"
在门户中显示,或将成为共享证明提供者之一.
您还需要客户证书才能使用验证管理客户端或拨打 attestTpm API (英语). 客户证书要求 (客户身份、客户秘密、房客身份) 以即时化客户端对象.
在这个开始的部分,我们将通过客户秘密身份认证 默认标记 提供商,但我们通过 @azure/身份 软件包。 安装 @azure/ 身份软件包 :
npm install @azure/identity
创建/ 获取证书
使用 阿苏尔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" } -
注意服务对象
az ad sp show --id <appId> --query objectId输出 :
"<your-service-principal-object-id>" -
使用以上返回的证书设置 自动识别( C) (掌声), (原始内容存档于2013-10-12). AZURE CLIENT SECET (密码)和 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 提供了四大功能家族:
微软Azure Attestation服务以"孤立"和"AAD"两种不同模式运行. 当服务以“孤立”模式运行时,客户需要 提供超出其认证证书的额外信息,以核实其有权修改证明案例的状况.
最后,每个可获得微软Azure Attestation服务的区域都支持"共享"实例,即: 可以用来证明SGX飞地只需要对照Azure基线进行核查(没有适用于共享提供者的政策)。 TPM认证在共享提供者中不提供. 虽然共享实例需要AAD认证,但它没有任何RBAC政策——任何持有有效的AAD无记名标志的客户都可以使用共享实例证明.
证明
SGX或TPM证明是验证从下列来源收集的证据的过程: a. 可靠的执行环境,以确保既符合Azure的基线,又符合客户确定的适用于该环境的政策.
验证服务 签名证书的发现和验证
Azure Attestation Service的核心业务保障之一是该服务"业务上脱离了TCB". 换句话说,微软运营商不可能篡改服务运行,也不可能损坏客户端发送的数据. 为确保这一保证,认证服务的核心是英特尔(tm)SGX飞地.
为了让客户核实业务是否实际在飞地内进行,验证处的多数答复被编码为: JSON 网络键由验证局飞地的钥匙签名.
此符号将由 MAA 服务为指定实例签发的签名证书签名 .
如果MAA服务实例运行于该服务运行于SGX飞地的区域,那么 使用 oe 验证 检验 认证 API。 。 。 .
这个 AttestationResponse 对象包含两个主要属性: token 财务报告和审定财务报表 value编辑 token 属性包含由验证服务返回的完整符号 value 属性包含 JSON Web Token 响应的正文.
政策管理
每个证明服务案例都对其适用一项政策,规定客户界定的其他标准.
有关证明政策的更多信息,见: 证明政策
政策管理证书管理
当一个证明实例以“孤立”模式运行时,创建该实例的客户会提供 创建实例时的政策管理证书。 所有政策修改业务都要求客户签名 带有现有政策管理证书之一的政策数据。 政策管理证书管理 API 启用 客户端可以"滚动"政策管理证书.
孤立模式和 AAD 模式
每个微软Azure Attestation服务实例都以"AAD"模式或"孤立"模式运行. 当MAA实例以AAD模式运行时,这意味着创建验证实例的客户允许Azure Active Directory和Azure作用基于访问控制政策来验证验证实例的访问权限.
证明类型
Microsoft Azure Attestation服务支持根据环境证明不同类型的证据. 目前,MAA支持以下信任执行环境:
- OpenEnclave - 一个英特尔( tm) 使用 OpenEnclave 收集证明证据的 SGX 飞地中处理器运行代码
oe_get_report或者说oe_get_evidenceAPI (英语). - SgxEnclave - 一个英特尔( tm) 处理器在SGX Enclave运行代码,在那里使用Intel SGX SDK收集证明证据.
- Tpm - 一个基于虚拟化的安全环境,其中使用处理器的可信平台模块来提供证明证据.
运行时数据和初始数据
RuntimeData 指的是向 Intel SGX 引文生成逻辑或 oe_get_report编号 :oe_get_evidence APIs (英语). 如果要求提供证明的API提供了 runtime_data 属性, Azure 验证服务将验证 report_data 引文/OE报告/OE 证据中与 runtime_data。 。 。 .
InitTime数据是指用于配置被验证的SGX飞地的数据.
注意在 Azure 上不支持时空数据 DCsv2-网络 虚拟机.
其他概念
实例
创建客户端实例
在 uri 创建验证客户端实例 endpoint,使用默认值
全权证书DefaultAzureCredential) (中文(简体) ).
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。 。 。 .
注意行政客户 需求 阿苏雷证书.
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 方法从服务中获取证明政策.
政策按每份证明类型提出,即: 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 模式运行, 设置策略的调用与预期相同 :
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);
如果服务实例以孤立模式运行, 调用设置政策要求 客户能够证明他们可以使用其中一种政策管理私人钥匙 和证书.
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,
});
在封面下,设定的政策 API 创建 JSON 网络键 包含在政策文件中的 certificate 并签署 privateKey 然后被送到证明处.
如果客户希望确保证明文件在证明服务飞地收到政策文件之前不会被修改,他们可以使用返回的财产 政策成果 用于核实服务收到政策文件的指令:
policySigner- 如果说setPolicy呼叫包含acertificate,该值将是在setPolicy电话 如果没有设置政策标志, 则无效 .policyTokenHash- 这是大麻 JSON 网络签名 发送到 setPolicy API 的服务 .
为了验证散列,客户可以创建证明政策标志(一个代表用于设定证明政策标志的帮助类)并验证由该标志产生的散列:
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 和打开飞地
使用 attestSgxEnclave 证明SGX飞地的方法.
客户与加密环境互动的核心挑战之一是如何确保您能够安全地与环境运行的代码("飞地代码")进行通信.
这一问题的一个解决方案是被称作"安全密钥放出"(Secure Key Release),这是一种能够与飞地码安全地通信的图案.
为了实施"安全密钥放出"模式,飞地代码生成了电偶不对称的密钥. 然后将密钥的公用部分序列化到某些格式(可能是JSON Web密钥,或PEM,或一些其他的序列化格式).
飞地代码然后计算出公钥的SHA256值并传递给生成 SGX 引文的代码输入(对于 OpenEnclave,即: oe 获得 证据 或者说 获取报告( g)) (中文(简体) ).
然后客户端将SGX引文和序列密钥发送到验证服务. 证明服务将验证引文,并确保引文中包含密钥的散列并发布"Attestation Token".
随后客户端可以将Attestation Token(包含被序列化的密钥)发送给第3方"依赖方". 依赖方随后验证证明信由证明服务机构创建,因此序列式密钥可用于加密由"依赖方"持有的一些数据发送到服务机构.
这个例子显示了一种常见的模式,即调用证明服务来取回与请求有关的证明信使.
此示例假设您已有 AttestationClient 对象,它被配置在您的端点的 Attest URI 中。 它还假设您有 OpenEnclave 报告(report)从您正在证明的SGX飞地内生成,并"运行时数据"(Runtime Data)binaryRuntimeData页:1.
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数据。 在这种情况下,客户应说明 runTimeJson 内
证明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 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 证书的客户端, 如果您正在打电话, 不需要此权限
页:1 attestSgxEnclave 或者说 attestOpenEnclave APIs 密码
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`);
解决问题
多数验证服务业务将产生下列例外情况: 阿苏雷核心。验证服务 APIs将推出 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}`);
}
日志
允许伐木可能有助于发现有关失败的有用信息。 为了查看 HTTP 请求和回复的日志,设置 AZURE_LOG_LEVEL 环境变量改为 info。或者,可以在运行时拨打 setLogLevel 输入 @azure/logger数字 :
import { setLogLevel } from "@azure/logger";
setLogLevel("info");
关于如何启用日志的更详细指示,您可以查看 @ azure/ logger 包文件。 。 。 .
可以在 MAA 服务中找到其他故障排除信息 这里
今后的步骤
关于微软Azure Attestation服务的更多信息,请参见我们 文档页面。 。 。 .
捐款
该项目欢迎各方的贡献和建议。 大部分捐款都要求你同意一项贡献者许可协议(CLA),声明你有权并且实际上确实给了我们使用你的捐款的权利. 详情请访问 贡献者许可证协议网站。 。 。 .
在提交拉力请求时,CLA-bot会自动确定是否需要提供CLA并适当装饰PR(如标签,注释). 只需听从机器人的指示 你只需要用我们的CLA 一次就能完成.
该项目通过了 Microsoft 开源行为守则更多信息见《行为守则》FAQ或联系人 打开码@ microsoft.com 并附上任何其他问题或评论.
见 捐款额 详细介绍这些图书馆的建设、测试和贡献.
提供反馈
如果您遇到任何错误或有建议,请在 问题 项目部分.