Claim sets
Claims generated in the process of attesting enclaves using Microsoft Azure Attestation can be divided into these categories:
- Incoming claims: The claims generated by Microsoft Azure Attestation after parsing the attestation evidence. The claims can be used by policy authors to define authorization rules in a custom policy.
- Outgoing claims: The claims generated by Azure Attestation and included in the attestation token.
- Property claims: The claims created as an output by Azure Attestation. It contains all the claims that represent properties of the attestation token, such as encoding of the report, validity duration of the report, and so on.
Incoming claims
SGX attestation
Claims to be used by policy authors to define authorization rules in an SGX attestation policy:
x-ms-sgx-is-debuggable: A boolean value, which indicates whether enclave debugging is enabled or not.
SGX enclaves can be loaded with debugging disabled, or enabled. When the flag is set to true in the enclave, it enables debugging features for the enclave code, which includes the ability to access enclave's memory. Hence it is recommended to set the flag to true only for development purposes. If enabled in production environment, SGX security guarantees are not retained.
Azure Attestation users can use the attestation policy to verify if debugging is disabled for the SGX enclave. Once the policy rule is added, attestation fails when a malicious user turns on the debugging support to gain access to the enclave content.
x-ms-sgx-product-id: An integer value, which indicates product ID of the SGX enclave.
The enclave author assigns a Product ID to each enclave. The Product ID enables the enclave author to segment enclaves signed using the same MRSIGNER. Customers can add a validation rule to the attestation policy to check if they are using the intended enclaves. Attestation fails if the enclave's product ID does not match the value published by the enclave author.
x-ms-sgx-mrsigner: A string value, which identifies the author of SGX enclave.
MRSIGNER is the hash of the enclave author's public key, which is associated with the private key used to sign the enclave binary. By validating MRSIGNER via an attestation policy, customers can verify if trusted binaries are running inside an enclave. When the policy claim does not match the enclave author's MRSIGNER, it implies that the enclave binary is not signed by a trusted source and the attestation fails.
When an enclave author prefers to rotate MRSIGNER for security reasons, Azure Attestation policy must be updated to support the new and old MRSIGNER values before the binaries are updated. Otherwise authorization checks fail, resulting in attestation failures.
Attestation policy must be updated using the format below.
Before key rotation
version= 1.0; authorizationrules { [ type=="x-ms-sgx-is-debuggable", value==false]&& [ type=="x-ms-sgx-mrsigner", value=="mrsigner1"] => permit(); };During key rotation
version= 1.0; authorizationrules { [ type=="x-ms-sgx-is-debuggable", value==false]&& [ type=="x-ms-sgx-mrsigner", value=="mrsigner1"] => permit(); [ type=="x-ms-sgx-is-debuggable", value==false ]&& [ type=="x-ms-sgx-mrsigner", value=="mrsigner2"] => permit(); };After key rotation
version= 1.0; authorizationrules { [ type=="x-ms-sgx-is-debuggable", value==false]&& [ type=="x-ms-sgx-mrsigner", value=="mrsigner2"] => permit(); };x-ms-sgx-mrenclave: A string value, which identifies the code and data loaded in enclave memory.
MRENCLAVE is one of the enclave measurements that can be used to verify the enclave binaries. It is the hash of the code running inside the enclave. The measurement changes with every change to the enclave binary code. By validating MRENCLAVE via an attestation policy, customers can verify if intended binaries are running inside an enclave. However, as MRENCLAVE is expected to change frequently with any trivial modification to the existing code, it is recommended to verify enclave binaries using MRSIGNER validation in an attestation policy.
x-ms-sgx-svn: An integer value, which indicates the security version number of the SGX enclave
The enclave author assigns a Security Version Number (SVN) to each version of the SGX enclave. When a security issue is discovered in the enclave code, enclave author increments the SVN value post vulnerability fix. To prevent interacting with insecure enclave code, customers can add a validation rule in the attestation policy. If the SVN of the enclave code does not match the version recommended by the enclave author, attestation fails.
These claims are considered deprecated but are fully supported and will continue to be included in the future. It is recommended to use the nondeprecated claim names:
| Deprecated claim | Recommended claim |
|---|---|
| $is-debuggable | x-ms-sgx-is-debuggable |
| $product-id | x-ms-sgx-product-id |
| $sgx-mrsigner | x-ms-sgx-mrsigner |
| $sgx-mrenclave | x-ms-sgx-mrenclave |
| $svn | x-ms-sgx-svn |
TPM attestation
Claims to be used by policy authors to define authorization rules in a TPM attestation policy:
- aikValidated: Boolean value containing information if the Attestation Identity Key (AIK) cert validates or not.
- aikPubHash: String containing the base64(SHA256(AIK public key in DER format)).
- tpmVersion: Integer value containing the Trusted Platform Module (TPM) major version.
- secureBootEnabled: Boolean value to indicate if secure boot is enabled.
- iommuEnabled: Boolean value to indicate if Input-output memory management unit (Iommu) is enabled.
- bootDebuggingDisabled: Boolean value to indicate if boot debugging is disabled.
- notSafeMode: Boolean value to indicate if the Windows is not running on safe mode.
- notWinPE: Boolean value indicating if Windows is not running in WinPE mode.
- vbsEnabled: Boolean value indicating if VBS is enabled.
- vbsReportPresent: Boolean value indicating if VBS enclave report is available.
VBS attestation
In addition to the TPM attestation policy claims, policy authors can use these claims to define authorization rules in a VBS attestation policy:
- enclaveAuthorId: String value containing the Base64Url encoded value of the enclave author id-The author identifier of the primary module for the enclave.
- enclaveImageId: String value containing the Base64Url encoded value of the enclave Image id-The image identifier of the primary module for the enclave.
- enclaveOwnerId: String value containing the Base64Url encoded value of the enclave Owner id-The identifier of the owner for the enclave.
- enclaveFamilyId: String value containing the Base64Url encoded value of the enclave Family ID. The family identifier of the primary module for the enclave.
- enclaveSvn: Integer value containing the security version number of the primary module for the enclave.
- enclavePlatformSvn: Integer value containing the security version number of the platform that hosts the enclave.
- enclaveFlags: The enclaveFlags claim is an Integer value containing Flags that describe the runtime policy for the enclave.
Outgoing claims
Common for all attestation types
Azure Attestation includes these claims in the attestation token for all attestation types:
- x-ms-ver: JWT schema version (expected to be "1.0").
- x-ms-attestation-type: String value representing attestation type.
- x-ms-policy-hash: Hash of Azure Attestation evaluation policy computed as BASE64URL(SHA256(UTF8(BASE64URL(UTF8(policy text))))).
- x-ms-policy-signer: JSON object with a "jwk" member representing the key a customer used to sign their policy, applicable when customer uploads a signed policy.
- x-ms-runtime: JSON object containing "claims" that are defined and generated within the attested environment, a specialization of the "enclave held data" concept, where the "enclave held data" is formatted as a UTF-8 encoding of well formed JSON.
- x-ms-inittime: JSON object containing "claims" that are defined and verified at initialization time of the attested environment.
These claim names are used from IETF JWT specification.
- "jti" (JWT ID) Claim - Unique identifier for the JWT.
- "iss" (Issuer) Claim - The principal that issued the JWT.
- "iat" (Issued At) Claim - The time at which the JWT was issued.
- "exp" (Expiration Time) Claim - Expiration time after which the JWT must not be accepted for processing.
- "nbf" (Not Before) Claim - Not Before time before which the JWT must not be accepted for processing.
These claim names are used from IETF EAT draft specification:
- "Nonce claim" (nonce) - An untransformed direct copy of an optional nonce value provided by a client.
Below claims are considered deprecated but are fully supported and will continue to be included in the future. It is recommended to use the nondeprecated claim names.
| Deprecated claim | Recommended claim |
|---|---|
| ver | x-ms-ver |
| tee | x-ms-attestation-type |
| policy_hash | x-ms-policy-hash |
| maa-policyHash | x-ms-policy-hash |
| policy_signer | x-ms-policy-signer |
| rp_data | nonce |
SGX attestation
These claims are generated and included in the attestation token by the service for SGX attestation:
- x-ms-sgx-is-debuggable: A Boolean, which indicates whether or not the enclave has debugging enabled or not.
- x-ms-sgx-product-id: Product ID value of the SGX enclave.
- x-ms-sgx-mrsigner: hex encoded value of the MRSIGNER field of the quote.
- x-ms-sgx-mrenclave: hex encoded value of the MRSIGNER field of the quote.
- x-ms-sgx-svn: security version number encoded in the quote.
- x-ms-sgx-ehd: enclave held data formatted as BASE64URL(enclave held data).
- x-ms-sgx-collateral: JSON object describing the collateral used to perform attestation. The value for the x-ms-sgx-collateral claim is a nested JSON object with the following key/value pairs:
- qeidcertshash: SHA256 value of Quoting Enclave (QE) Identity issuing certs.
- qeidcrlhash: SHA256 value of QE Identity issuing certs CRL list.
- qeidhash: SHA256 value of the QE Identity collateral.
- quotehash: SHA256 value of the evaluated quote.
- tcbinfocertshash: SHA256 value of the TCB Info issuing certs.
- tcbinfocrlhash: SHA256 value of the TCB Info issuing certs CRL list.
- tcbinfohash: SHA256 value of the TCB Info collateral.
- x-ms-sgx-report-data: SGX enclave report data field (usually SHA256 hash of x-ms-sgx-ehd).
These claims appear only in the attestation token generated for Intel® Xeon® Scalable processor-based server platforms. The claims will not appear if the SGX enclave is not configured with Key Separation and Sharing Support. The claim definitions can be found here:
- x-ms-sgx-config-id
- x-ms-sgx-config-svn
- x-ms-sgx-isv-extended-product-id
- x-ms-sgx-isv-family-id
These claims are considered deprecated, but are fully supported and will continue to be included in the future. It is recommended to use the nondeprecated claim names:
| Deprecated claim | Recommended claim |
|---|---|
| $is-debuggable | x-ms-sgx-is-debuggable |
| $product-id | x-ms-sgx-product-id |
| $sgx-mrsigner | x-ms-sgx-mrsigner |
| $sgx-mrenclave | x-ms-sgx-mrenclave |
| $svn | x-ms-sgx-svn |
| $maa-ehd | x-ms-sgx-ehd |
| $aas-ehd | x-ms-sgx-ehd |
| $maa-attestationcollateral | x-ms-sgx-collateral |
SEV-SNP attestation
The following claims are also supported by the SevSnpVm attestation type:
- x-ms-sevsnpvm-authorkeydigest: SHA384 hash of the author signing key.
- x-ms-sevsnpvm-bootloader-svn: AMD boot loader security version number (SVN).
- x-ms-sevsnpvm-familyId: Host Compatibility Layer (HCL) family identification string.
- x-ms-sevsnpvm-guestsvn: HCL security version number (SVN).
- x-ms-sevsnpvm-hostdata: Arbitrary data defined by the host at VM launch time.
- x-ms-sevsnpvm-idkeydigest: SHA384 hash of the identification signing key.
- x-ms-sevsnpvm-imageId: HCL image identification.
- x-ms-sevsnpvm-is-debuggable: Boolean value indicating whether AMD SEV-SNP debugging is enabled.
- x-ms-sevsnpvm-launchmeasurement: Measurement of the launched guest image.
- x-ms-sevsnpvm-microcode-svn: AMD microcode security version number (SVN).
- x-ms-sevsnpvm-migration-allowed: Boolean value indicating whether AMD SEV-SNP migration support is enabled.
- x-ms-sevsnpvm-reportdata: Data passed by HCL to include with report, to verify that transfer key and VM configuration are correct.
- x-ms-sevsnpvm-reportid: Report ID of the guest.
- x-ms-sevsnpvm-smt-allowed: Boolean value indicating whether SMT is enabled on the host.
- x-ms-sevsnpvm-snpfw-svn: AMD firmware security version number (SVN).
- x-ms-sevsnpvm-tee-svn: AMD trusted execution environment (TEE) security version number (SVN).
- x-ms-sevsnpvm-vmpl: VMPL that generated this report (0 for HCL).
TPM and VBS attestation
- cnf (Confirmation): The "cnf" claim is used to identify the proof-of-possession key. Confirmation claim as defined in RFC 7800, contains the public part of the attested enclave key represented as a JSON Web Key (JWK) object (RFC 7517).
- rp_data (relying party data): Relying party data, if any, specified in the request, used by the relying party as a nonce to guarantee freshness of the report. rp_data is only added if there is rp_data.
Property claims
TPM and VBS attestation
- report_validity_in_minutes: An integer claim to signify for how long the token is valid.
- Default value(time): One day in minutes.
- Maximum value(time): One year in minutes.
- omit_x5c: A Boolean claim indicating if Azure Attestation should omit the cert used to provide proof of service authenticity. If true, x5t is added to the attestation token. If false(default), x5c is added to the attestation token.
Next steps
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for