Claim sets

Claims generated in the process of attesting enclaves using Microsoft Azure Attestation can be divided into the below categories:

  • Incoming claims: The claims generated by Microsoft Azure Attestation after parsing the attestation evidence and 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. This 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 will not be 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 will fail 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. By adding a validation rule in the attestation policy, customers can check if they are using the intended enclaves. Attestation will fail 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 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 will fail resulting in attestation failures.

    Attestation policy must be updated using the below format.

    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 which 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 will fail.

Below claims are considered deprecated but are fully supported and will continue to be included in the future. It is recommended to use the non-deprecated 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 has been validated 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, below claims can be used by policy authors 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 the below 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. This is applicable when customer uploads a signed policy

Below 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 at
  • "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

Below 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 non-deprecated 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

SGX attestation

Below 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 “mrenclave” 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

Below claims are considered deprecated but are fully supported and will continue to be included in the future. It is recommended to use the non-deprecated 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

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 will be added to the attestation token. If false(default), x5c will be added to the attestation token.

Next steps