你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
Microsoft Azure 证明(MAA)服务是一种统一解决方案,用于远程验证平台的可信度以及运行在其中的二进制文件的完整性。 该服务支持对受信任的平台模块(TPM)支持的平台进行证明,同时能够证明受信任的执行环境(TEE)(例如 Intel(tm) 软件防护扩展(SGX)enclave 和基于虚拟化的安全性(VBS)enclave 的状态。
认证是用于在受信任的平台上正确地实例化软件二进制文件的过程。 然后,远程信赖方可以确信只有此类软件在受信任的硬件上运行。 Azure 证明是一个统一的面向客户的认证服务和框架。
Azure 证明支持先进的安全范例,例如 Azure 机密计算和智能边缘保护。 客户一直在请求独立验证计算机的位置、虚拟机(VM)的位置,以及在该 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 证明 for JavaScript with NPM:
npm install @azure/attestation
对客户端进行身份验证
要与 Microsoft Azure 证明 服务交互,您需要创建 Attestation Client 或 Attestation Administration Client 类的实例。 你需要一个认证 实例 URL,要么是门户中显示的“认证 URI”,要么是共享的认证提供者之一。
您还需要客户端凭据才能使用认证管理客户端或调用 attestTpm API。 客户端凭据要求( 客户端 ID、客户端密钥、租户 ID) 来实例化客户端对象。
在本入门部分,我们将通过 DefaultAzureCredential 提供程序使用客户端密钥凭据进行身份验证,但我们也通过 @azure/身份 包提供更多身份验证机制。 安装该 @azure/identity 软件包的方法如下:
npm install @azure/identity
创建/获取凭据
使用下面的 Azure CLI 代码片段创建/获取客户端机密凭据。
创建服务主体并配置其对 Azure 资源的访问权限:
az ad sp create-for-rbac -n <your-application-name> --skip-assignmentOutput:
{ "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 objectIdOutput:
"<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 enclaves(共享提供者没有任何策略)。 共享提供者中不提供 TPM 证明。 虽然共享实例需要 AAD 认证,但它没有任何 RBAC 策略——任何拥有有效 AAD 持有令牌的客户都可以使用共享实例进行认证。
Attestation
SGX 或 TPM 证明是验证从受信任执行环境收集的证据的过程,以确保它满足该环境和应用于该环境的客户定义的策略的 Azure 基线。
认证服务令牌签名证书的发现与验证
Azure 证明 服务的核心运营保障之一是该服务在“运营上直接在 TCB 内运行”。 换句话说,Microsoft 运营者不可能篡改服务的运行,或损坏客户端发送的数据。 为确保这一保障,认证服务的核心运行在 Intel(tm) SGX enclave 中。
为了让客户能够验证操作是否确实在 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 令牌响应的正文。
策略管理
每个证明服务实例都应用了一个策略,该策略定义了客户定义的附加条件。
有关证明策略的详细信息,请参阅 证明策略
策略管理证书管理
当证明实例以“隔离”模式运行时,创建实例的客户将在实例创建时提供了策略管理证书。 所有策略修改操作都要求客户使用现有的策略管理证书之一签署策略数据。 策略管理证书管理 API 使客户端能够“滚动”策略管理证书。
隔离模式与 AAD 模式
每个 Microsoft Azure 证明 服务实例都以“AAD”模式或“隔离”模式运行。 当 MAA 实例以 AAD 模式运行时,意味着创建该认证实例的客户允许 Azure Active Directory 和 Azure 基于角色的访问控制策略验证对该认证实例的访问。
AttestationType
Microsoft Azure 证明 服务支持根据不同环境认证不同类型的证据。 目前,MAA 支持以下受信任执行环境:
- OpenEnclave——在 SGX Enclave 中运行代码的 Intel™处理器,通过 OpenEnclave
oe_get_report或oe_get_evidenceAPI 收集了认证证据。 - SgxEnclave——在 SGX Enclave 中运行代码的 Intel™处理器,其中通过 Intel SGX SDK 收集了认证证据。
- Tpm——基于虚拟化的安全环境,使用处理器的可信平台模块提供证明证据。
运行时数据和初始时间数据
RuntimeData 指的是呈现给 Intel SGX 报价生成逻辑或 oe_get_report/oe_get_evidence API 的数据。 如果调用 attest API 的调用者提供了runtime_data属性,Azure 证明 服务将验证 SGX 报价/OE 报告/OE 证据中字段的前 32 字节report_data是否与 的 SHA256 哈希runtime_data匹配。
InitTime 数据指用于配置被认证的 SGX 飞区的数据。
请注意,Azure DCsv2 系列虚拟机不支持 InitTime 数据。
其他概念
Examples
创建客户端实例
使用默认的 Azure 凭据()DefaultAzureCredential在 uri endpoint创建一个 Attestation 客户端实例。
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 客户端实例。
请注意,管理客户端需要 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 方法从服务中检索证明策略。
鉴证策略按每个文献类型实例化,参数 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,
});
在这些文件下,setPolicy API 创建包含在策略文档certificate中并签署privateKey的 JSON Web 令牌,然后发送给认证服务。
如果客户端希望确保在政策文档被认证服务的 enclave 接收之前,该文档未被修改,他们可以使用 PolicyResult objct 中返回的属性,用于验证服务是否收到了策略文件:
-
policySigner- 如果setPolicy通话包含certificate,则该值为通话时setPolicy提供的证书。 如果未设置策略签署者,则此值为空。 -
policyTokenHash- 这是发送给服务的 setPolicy API 的 JSON Web 签名 的哈希值。
为了验证哈希值,客户端可以创建一个证明策略令牌(一个辅助类,表示用于设置证明策略的令牌),并验证由该令牌生成的哈希值:
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 enclave。
客户在与加密环境中互动时面临的核心挑战之一是如何确保您能够安全地与环境中运行的代码(“enclave code”)通信。
解决这一问题的一个方法是所谓的“安全密钥释放”,这是一种模式,使得与飞区代码实现安全通信。
为了实现“安全密钥释放”模式,飞区代码会生成一个临时不对称密钥。 然后它会将密钥的公开部分序列化为某种格式(可能是 JSON Web Key、PEM 或其他序列化格式)。
接着,enclave 代码会计算公钥的 SHA256 值,并将其作为输入传递给代码,代码生成一个 SGX 引号(对于 OpenEnclave,那就是 oe_get_evidence 或 oe_get_report)。
客户端随后将 SGX 报价和序列化密钥发送给认证服务。 认证服务会验证报价,确保报价中包含密钥的哈希值,并会发放“认证令牌”。
客户端随后可以将该认证令牌(包含序列化密钥)发送给第三方“依赖方”。 依赖方随后验证证明令牌是由认证服务创建的,因此序列化密钥可用于加密“依赖方”持有的部分数据,并发送给服务。
此示例展示了调用认证服务以获取与请求关联的认证令牌的一种常见模式。
此示例假设您有一个已为端点配置的 Attest URI 的现有 AttestationClient 对象。 它还假设你有一个从 SGX enclave 内部生成的 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`);
故障排除
大多数认证服务操作都会触发 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");
有关如何启用日志的更详细说明,可以查看 @azure/记录器包文档。
有关 MAA 服务的更多故障排除信息可在此处找到
后续步骤
有关 azure 证明服务Microsoft的详细信息,请参阅我们的 文档页。
Contributing
此项目欢迎贡献和建议。 大多数贡献要求你同意参与者许可协议(CLA),声明你有权(实际这样做)授予我们使用你的贡献的权利。 详情请访问贡献 者许可协议网站。
提交拉取请求时,CLA 机器人会自动确定是否需要提供 CLA 并适当修饰 PR(例如标签、注释)。 只需按照机器人提供的说明进行操作。 只需使用 CLA 在所有存储库中执行此操作一次。
该项目已采用 Microsoft开源行为准则。 欲了解更多信息,请参阅行为准则常见问题解答,或如有额外问题或意见时联系 opencode@microsoft.com 我们。
有关构建、测试和贡献这些库的详细信息,请参见 CONTRIBUTING.md 。
提供反馈
如果您遇到任何错误或有建议,请在项目的 “问题 ”部分提交问题。