Package com.azure.security.attestation.models

Class AttestationOptions

java.lang.Object
com.azure.security.attestation.models.AttestationOptions
public final class AttestationOptions extends Object

AttestationOptions represent the parameters sent to the AttestationClient.attestOpenEnclave(com.azure.core.util.BinaryData) or AttestationClient.attestSgxEnclave(com.azure.core.util.BinaryData)API.

Each AttestationOptions object expresses the options to attest an SGX enclave.

An enclave (or Trusted Execution Environment) is a chunk of code that is isolated from its host. When code is running inside an enclave, there is a real challenge - if the customer wants to communicate with code in the enclave, there is no way of establishing a secure communication channel that can verify communication to the enclave.

To support the "Secure Key Release" protocol which enables that communication, there are three key pieces of information required:

  • Attestation Evidence (typically an SGX quote or OpenEnclave report
  • InitTime Data - this is data specified when the TEE is created. (OPTIONAL)
  • RunTime Data - this can be a public key or other information. (OPTIONAL)

To perform an attestation operation, you need at minimum a set of attestation evidence.

For the Secure Key Release scenario, the InitTime Data and RunTime Data are expressed in the token returned by the Attestation Service, a relying party can use the InitTime Data to make decisions about whether the TEE can be trusted, and can use the RunTime Data as data which is known to have come from inside the enclave (if, for instance the RunTime Data is an asymmetric cryptographic key, it can be used to encrypt data that can only be decrypted by code inside the TEE).

For both InitTime and RunTime data, the data can be expressed in the token as either BINARY or JSON data. This can simplify the evaluation process in the relying party.

In addition to the evidence, InitTime and RunTime data, an Attest request can also take a "draft" attestation policy. This can be used to determine how an attestation policy effects the claims generated by the attestation service.

Note that when a client specifies a draft attestation policy the returned attestation token will not be signed by the attestation service. That is to ensure that the token cannot be used by a relying party.

The reason that both binary and JSON are represented as binary is that JSON encodings are ambiguous – there are many possible semantically identical JSON encodings of the same data. Since we’re going to take the SHA256 hash of the data, we accept a sequence of octets (byte[]) instead of a String (depending on your encoding, the same string can be encoded as different sequences of octets).

  • Constructor Details

    • AttestationOptions

      public AttestationOptions(BinaryData evidence)
      Creates a new AttestOpenEnclaveRequest object with the OpenEnclave report from the enclave to be attested. The evidence will typically take the form of either an OpenEnclave report or an Intel SGX quote.

      Create an AttestationOptions from an SGX quote:

       AttestationOptions options = new AttestationOptions(sgxQuote);
      Parameters:
      evidence - to be used in the attest request.

  • Method Details

    • getEvidence

      public BinaryData getEvidence()
      Returns the "evidence" to be presented to the attestation service.
      Returns:
      The attestation evidence to be presented to the attestation service.

    • setRunTimeData

      public AttestationOptions setRunTimeData(AttestationData attestationData)
      Set the RunTime Data property.

      Runtime data provided by the enclave at the time the evidence was generated. The attestation service will verify that the first 32 bytes of the report_data field of the quote contains the SHA256 hash of the runtime data, this ensures that the RunTime Data was known to the enclave.

      When the attestation service generates the attestation token, the RunTimeData will be added as one of two possible claims: AttestationResult.getRuntimeClaims() if the AttestationDataInterpretation specified for the RunTime Data was set to "JSON", or AttestationResult.getEnclaveHeldData() if the AttestationDataInterpretation specified for the RunTime Data was set to "BINARY", or

      Setting RunTime Data Property

       AttestationOptions optionsWithInitTimeData = new AttestationOptions(openEnclaveReport)
     .setInitTimeData(new AttestationData(inittimeData, AttestationDataInterpretation.BINARY));
      Parameters:
      attestationData - the runtimeData value to set.
      Returns:
      this AttestationOptions object itself.

    • getRunTimeData

      public AttestationData getRunTimeData()
      Retrieves the RunTimeData property to be sent to the service.

      Retrieve the RunTimeData value.

       AttestationData existingRuntimeData = attestationOptions.getRunTimeData();
      Returns:
      The RunTimeData value set by setRunTimeData(com.azure.security.attestation.models.AttestationData)

    • setInitTimeData

      public AttestationOptions setInitTimeData(AttestationData attestationData)

      Set the initTimeData property: The initTimeData is data presented at the time that the execution environment was instantiated. The MAA will verify that the init data was known to the execution environment. Note that InitTimeData is invalid for CoffeeLake processors.

      When the attestation service generates the attestation token, the InitTimeData will be added as AttestationResult.getInitTimeClaims() if the AttestationDataInterpretation for the AttestationData is set to "JSON".

      Setting InitTime Data Property

       AttestationOptions optionsWithInitTimeData = new AttestationOptions(openEnclaveReport)
     .setInitTimeData(new AttestationData(inittimeData, AttestationDataInterpretation.BINARY));
      Parameters:
      attestationData - the InitTimeData value to set.
      Returns:
      this AttestationOptions object itself.

    • getInitTimeData

      public AttestationData getInitTimeData()
      Retrieves the InitTimeData property to be sent to the service.

      Retrieve the InitTimeData value.

       AttestationOptions attestationOptions = new AttestationOptions(openEnclaveReport)
     .setInitTimeData(new AttestationData(inittimeData, AttestationDataInterpretation.JSON));

 AttestationData existingRuntimeData = attestationOptions.getInitTimeData();
      Returns:
      The InitTimeData value set by setInitTimeData(com.azure.security.attestation.models.AttestationData)

    • setDraftPolicyForAttestation

      public AttestationOptions setDraftPolicyForAttestation(String draftPolicyForAttestation)
      Set the draftPolicyForAttestation property: Attest against the provided draft policy.

      The setDraftPolicyForAttestation API can be used to determine how a proposed attestation policy would affect an attestation token.

      Note that the resulting token cannot be validated.

      Example of setting AttestationOptions with a draft policy.

       AttestationOptions request = new AttestationOptions(openEnclaveReport)
     .setDraftPolicyForAttestation("version=1.0; authorizationrules{=> permit();}; issuancerules{};");
      Parameters:
      draftPolicyForAttestation - the draftPolicyForAttestation value to set.
      Returns:
      this AttestationOptions object itself.

    • getDraftPolicyForAttestation

      public String getDraftPolicyForAttestation()
      Gets the draftPolicyForAttestation property which is used to attest against the draft policy.

      Gets the previously set draft policy for attestation.

       AttestationOptions getOptions = new AttestationOptions(openEnclaveReport)
     .setDraftPolicyForAttestation("version=1.0; authorizationrules{=> permit();}; issuancerules{};");

 String draftPolicy = getOptions.getDraftPolicyForAttestation();
      Returns:
      The draft policy if set.

    • setValidationOptions

      public AttestationOptions setValidationOptions(AttestationTokenValidationOptions validationOptions)
      Sets the options used to validate attestation tokens returned from the service.
      Parameters:
      validationOptions - Token Validation options to be used to enhance the validations already performed by the SDK.
      Returns:
      this AttestationOptions object.

    • getValidationOptions

      public AttestationTokenValidationOptions getValidationOptions()
      Returns the options used for token validation.
      Returns:
      attestation token validation options.