你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
Azure 证明 Java 客户端库 - 版本 1.1.18
Microsoft Azure 证明（预览版）是一个统一的解决方案，用于远程验证平台的可信度和在该平台中运行的二进制文件的完整性。 该服务支持对受信任的平台模块 (TPM) 支持的平台的证明，以及对受信任执行环境 (TEE) 的状态进行证明的功能，例如 Intel® Software Guard Extensions (SGX) enclave 和基于虚拟化的安全性 (VBS) enclave。
证明是演示如何在受信任的平台上正确实例化软件二进制文件的过程。 然后，远程信赖方可以确信只有此类软件在受信任的硬件上运行。 Azure 证明是一个统一的面向客户的认证服务和框架。
Azure 证明使用先进的安全范例，如 Azure 机密计算和智能边缘保护。 客户一直在请求独立验证计算机位置、计算机上的虚拟机 (VM) 状态以及在该 VM 上运行 enclave 的环境的功能。 Azure 证明将满足这些请求以及诸多其他客户请求。
Azure 证明从计算实体接收证据，将它们转换为一组声明，根据可配置的策略对其进行验证，并为基于声明的应用（例如信赖方和审核机构）生成加密证明。
注意：这是 Microsoft Azure 证明服务的初步 SDK。 它提供了访问Azure 证明服务的所有基本功能，但需要大量的基础结构才能正常工作。
入门
添加包
包括 BOM 文件
请将 azure-sdk-bom 包含在项目中，以依赖于库的正式发布 (GA) 版本。 在以下代码段中，将 {bom_version_to_target} 占位符替换为版本号。 若要详细了解 BOM，请参阅 AZURE SDK BOM 自述文件。
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-sdk-bom</artifactId>
<version>{bom_version_to_target}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
然后在依赖项部分中包括直接依赖项，不带版本标记，如下所示。
<dependencies>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-security-attestation</artifactId>
</dependency>
</dependencies>
包括直接依赖项
如果要依赖于 BOM 中不存在的特定库版本，请将直接依赖项添加到项目，如下所示。
<!-- Install the Azure Attestation SDK -->
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-security-attestation</artifactId>
<version>1.1.18</version>
</dependency>
先决条件
- Java 开发工具包 (JDK) 8 或更高版本。
- Azure 订阅
- 现有Azure 证明实例。 如果需要创建证明实例，可以使用 Azure Cloud Shell使用此 Azure CLI 命令创建一个证明实例。 将 和
<your-instance-name>替换为<your-resource-group-name>自己的唯一名称：
az attestation create --resource-group <your-resource-group-name> --name <your-instance-name>
验证客户端
若要与Azure 证明服务交互，客户端必须向服务提供 Azure Active Directory 持有者令牌。
提供持有者令牌的最简单方法是通过在此入门部分提供客户端机密凭据来使用 DefaultAzureCredential 身份验证方法，但可以找到使用 azure-identity 进行身份验证的更多方法。
关键概念
Microsoft Azure 证明服务以两种不同的模式运行：“独立”和“AAD”。 当服务在“独立”模式下运行时，客户需要提供身份验证凭据以外的其他信息，以验证他们是否有权修改证明实例的状态。
此预览版 SDK 中提供了四种主要客户端类型：
- SGX 和 TPM enclave 证明。
- MAA 证明令牌签名证书发现和验证。
- 证明策略管理。
- 证明策略管理证书管理 (是的，策略管理) 。
每个证明实例在两种不同的操作模式之一中运行：
- AAD 模式。
- 隔离模式
在“AAD”模式下，对服务的访问完全由 Azure 基于角色访问控制控制。 在“独立”模式下，客户端应提供其他证据来证明客户端有权修改服务。
最后，Microsoft Azure 证明服务可用的每个区域都支持一个“共享”实例，该实例可用于证明 SGX enclave，只需针对 azure 基线进行验证， (没有策略应用于共享实例) 。 TPM 证明在共享实例中不可用。 虽然共享实例需要 AAD 身份验证，但它没有任何 RBAC 策略 - 任何具有有效 AAD 持有者令牌的客户都可以使用共享实例进行证明。
证明
SGX 或 TPM 证明是验证从受信任的执行环境收集的证据的过程，以确保它满足该环境的 Azure 基线和应用于该环境的客户定义策略。
证明令牌签名证书发现和验证
MAA 服务的大多数响应都以 JSON Web 令牌的形式表示。 此令牌将由 MAA 服务为指定实例颁发的签名证书进行签名。 如果 MAA 服务实例在服务在 SGX enclave 中运行的区域中运行，则可以使用 oe_verify_attestation_certificate () API 验证服务器颁发的证书。
策略管理
每个证明服务实例都应用了一个策略，该策略定义了客户已定义的附加条件。
有关证明策略的详细信息，请参阅 证明策略
策略管理证书管理
当证明实例在“独立”模式下运行时，创建实例的客户将在创建实例时提供策略管理证书。 所有策略修改操作都要求客户使用现有策略管理证书之一对策略数据进行签名。 策略管理证书管理 API 使客户端能够添加、删除或枚举策略管理证书。
示例
实例化同步证明客户端
类 AttestationClientBuilder 用于创建证明客户端的实例：
AttestationClientBuilder attestationBuilder = new AttestationClientBuilder();
// Note that the "attest" calls do not require authentication.
AttestationClient client = attestationBuilder
.endpoint(endpoint)
.buildClient();
检索令牌验证证书
使用 listAttestationSigners 检索证书集，这些证书可用于验证从证明服务返回的令牌。
通常，不需要此信息，因为证明 SDK 将在与证明服务交互过程中执行验证，但提供 API 是为了完整性，方便客户独立验证证明结果。
AttestationSignerCollection certs = client.listAttestationSigners();
certs.getAttestationSigners().forEach(cert -> {
System.out.println("Found certificate.");
if (cert.getKeyId() != null) {
System.out.println(" Certificate Key ID: " + cert.getKeyId());
} else {
System.out.println(" Signer does not have a Key ID");
}
cert.getCertificates().forEach(chainElement -> {
System.out.println(" Cert Subject: " + chainElement.getSubjectDN().getName());
System.out.println(" Cert Issuer: " + chainElement.getIssuerDN().getName());
});
});
证明 SGX Enclave
attestSgxEnclave使用 方法来证明 SGX enclave。
BinaryData decodedRuntimeData = BinaryData.fromBytes(SampleCollateral.getRunTimeData());
BinaryData sgxQuote = BinaryData.fromBytes(SampleCollateral.getSgxEnclaveQuote());
// Attest evidence from an OpenEnclave enclave specifying runtime data which should be
// interpreted as binary data.
AttestationResult result = client.attestSgxEnclave(new AttestationOptions(sgxQuote)
.setRunTimeData(
new AttestationData(decodedRuntimeData, AttestationDataInterpretation.BINARY)));
String issuer = result.getIssuer();
System.out.println("Attest Sgx Enclave completed. Issuer: " + issuer);
System.out.printf("Runtime Data Length: %d\n", result.getEnclaveHeldData().getLength());
实例化同步管理客户端
所有管理客户端都经过身份验证。
AttestationAdministrationClientBuilder attestationBuilder = new AttestationAdministrationClientBuilder();
// Note that the "policy" calls require authentication.
AttestationAdministrationClient client = attestationBuilder
.endpoint(endpoint)
.credential(new DefaultAzureCredentialBuilder().build())
.buildClient();
获取证明策略
getAttestationPolicy使用 API 检索给定 TEE 的当前证明策略。
String currentPolicy = client.getAttestationPolicy(AttestationType.OPEN_ENCLAVE);
System.out.printf("Current policy for OpenEnclave is: %s\n", currentPolicy);
设置无符号证明策略
当证明实例处于 AAD 模式时，调用方可以使用便捷方法在实例上设置无符号证明策略。
// Set the listed policy on an attestation instance. Please note that this particular policy will deny all
// attestation requests and should not be used in production.
PolicyResult policyResult = client.setAttestationPolicy(AttestationType.OPEN_ENCLAVE,
"version=1.0; authorizationrules{=> deny();}; issuancerules{};");
System.out.printf("Policy set for OpenEnclave result: %s\n", policyResult.getPolicyResolution());
设置签名证明策略
对于独立模式证明实例，必须使用与证明实例上配置的证明签名证书关联的密钥对设置或重置策略请求进行签名。
// Set the listed policy on an attestation instance using a signed policy token.
PolicyResult policyResult = client.setAttestationPolicy(AttestationType.SGX_ENCLAVE,
new AttestationPolicySetOptions()
.setAttestationPolicy("version=1.0; authorizationrules{=> permit();}; issuancerules{};")
.setAttestationSigner(new AttestationSigningKey(certificate, privateKey)));
System.out.printf("Policy set for Sgx result: %s\n", policyResult.getPolicyResolution());
列出策略管理证书
当证明实例处于 Isolated 模式时，策略 API 需要额外的授权证明。 此证明通过 AttestationSigningKey 传递到集和重置策略 API 的参数提供。
每个 Isolated 模式实例都有一组证书，用于确定调用方是否有权设置证明策略。 设置证明策略后，客户端会向服务提供已签名的“令牌”，该服务由 中的 AttestationSigningKey密钥签名。 签名的令牌（包括 中的 AttestationSigningKey 证书）将发送到证明服务，这将验证令牌是否已使用与令牌中的公钥对应的私钥进行签名。 仅当令牌中的证书是策略管理令牌之一时，设置或重置策略操作才会成功。 此交互可确保客户端拥有与其中一个策略管理证书关联的私钥，从而获得执行操作的授权。
AttestationSignerCollection signers = client.listPolicyManagementCertificates();
System.out.printf("Instance %s contains %d signers.\n", endpoint, signers.getAttestationSigners().size());
for (AttestationSigner signer : signers.getAttestationSigners()) {
System.out.printf("Certificate Subject: %s", signer.getCertificates().get(0).getSubjectDN().toString());
}
添加策略管理证书
将新证书添加到策略管理证书集。 添加策略管理证书的请求必须使用与现有策略管理证书之一关联的私钥进行签名， (这可确保调用方有权) 更新策略证书集。
注意：添加同一证书两次不被视为错误 - 如果证书已存在，则忽略添加 (此可能令人吃惊的行为存在，因为重试可能会导致添加多次执行)
System.out.printf("Adding new certificate %s\n", certificateToAdd.getSubjectDN().toString());
PolicyCertificatesModificationResult modificationResult = client.addPolicyManagementCertificate(
new PolicyManagementCertificateOptions(certificateToAdd,
new AttestationSigningKey(isolatedCertificate, isolatedKey)));
System.out.printf("Updated policy certificate, certificate add result: %s\n",
modificationResult.getCertificateResolution());
System.out.printf("Added certificate thumbprint: %s\n", modificationResult.getCertificateThumbprint());
删除证明签名证书
从策略管理证书集中删除证书。 删除策略管理证书的请求必须使用与现有策略管理证书之一关联的私钥进行签名， (这可确保调用方有权) 更新策略证书集。
注意：删除不存在的证书不被视为错误 - 如果证书不存在，则会忽略删除， (出现这种可能令人惊讶的行为，因为重试可能会导致删除多次执行)
System.out.printf("Removing existing certificate %s\n", certificateToRemove.getSubjectDN().toString());
PolicyCertificatesModificationResult modificationResult = client.deletePolicyManagementCertificate(
new PolicyManagementCertificateOptions(certificateToRemove,
new AttestationSigningKey(isolatedCertificate, isolatedKey)));
System.out.printf("Updated policy certificate, certificate remove result: %s\n",
modificationResult.getCertificateResolution());
System.out.printf("Removed certificate thumbprint: %s\n", modificationResult.getCertificateThumbprint());
疑难解答
可在此处找到 MAA 服务的故障排除信息
后续步骤
有关 Microsoft Azure 证明服务的详细信息，请参阅我们的文档页。
贡献
本项目欢迎贡献和建议。 大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。 有关详细信息，请访问 https://cla.microsoft.com 。
提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。 直接按机器人提供的说明操作。 只需使用 CLA 对所有存储库执行一次这样的操作。
本项目采用 Microsoft 开源行为准则。 有关详细信息，请参阅“行为准则常见问题解答”，如有其他任何问题或意见，请联系 opencode@microsoft.com。
