Package com.azure.security.attestation

Class AttestationAdministrationClient

java.lang.Object
com.azure.security.attestation.AttestationAdministrationClient
public final class AttestationAdministrationClient extends Object
The AttestationAdministrationClient provides access to the administrative policy APIs implemented by the Attestation Service.

More information on attestation policies can be found here

There are two main families of APIs available from the Administration client.
  • Attestation Policy Management
  • Policy Management Certificate Management
Attestation service instances operate in three different modes:
  • Shared - a shared instance is a regional instance which is available to all customers. It does NOT support customer specified policy documents - there is only a default policy available for each attestation type
  • AAD - An attestation instance where the customer trusts Azure Active Directory (and Azure Role Based Access Control) to manage the security of their enclave.
  • Isolated - an attestation instance where the customer does *not* trust Azure Active Directory (and RBAC) to manage the security of their enclave

When an attestation instance is in Isolated mode, additional proof needs to be provided by the customer to verify that they are authorized to perform the operation specified.

When an Isolated mode attestation instance is created, the creator provides an X.509 certificate which forms the set of policy management certificates. Under the covers, each AttestationAdministrationAsyncClient.setAttestationPolicy(AttestationType, AttestationPolicySetOptions). API call must be signed with the private key which is associated with one of the policy management certificates. This signing operation allows the attestation service to verify that the caller is in possession of a private key which has been authorized to add or reset policies, or to modify the set of attestation policy certificates.

  • Method Details

    • getAttestationPolicy

      public String getAttestationPolicy(AttestationType attestationType)
      Retrieves the current policy for an attestation type.

      NOTE: The AttestationAdministrationAsyncClient.getAttestationPolicyWithResponse(AttestationType, AttestationTokenValidationOptions, Context) API returns the underlying attestation policy specified by the user. This is NOT the full attestation policy maintained by the attestation service. Specifically it does not include the signing certificates used to verify the attestation policy.

      To retrieve the signing certificates used to sign the policy, Response object returned from this API is an instance of an AttestationResponse object and the caller can retrieve the full policy object maintained by the service by calling the AttestationResponse.getToken() method. The returned AttestationToken object will be the value stored by the attestation service.

      Retrieve the current attestation policy for SGX enclaves.

       String policy = client.getAttestationPolicy(AttestationType.SGX_ENCLAVE);
      Parameters:
      attestationType - Specifies the trusted execution environment whose policy should be retrieved.
      Returns:
      the response to an attestation policy operation.
      Throws:
      IllegalArgumentException - thrown if parameters fail the validation.
      HttpResponseException - thrown if the request is rejected by server.
      RuntimeException - all other wrapped checked exceptions if the request fails to be sent.

    • getAttestationPolicy

      public String getAttestationPolicy(AttestationType attestationType, AttestationTokenValidationOptions options)
      Retrieves the current policy for an attestation type.

      NOTE: The AttestationAdministrationAsyncClient.getAttestationPolicyWithResponse(AttestationType, AttestationTokenValidationOptions, Context) API returns the underlying attestation policy specified by the user. This is NOT the full attestation policy maintained by the attestation service. Specifically it does not include the signing certificates used to verify the attestation policy.

      To retrieve the signing certificates used to sign the policy, Response object returned from this API is an instance of an AttestationResponse object and the caller can retrieve the full policy object maintained by the service by calling the AttestationResponse.getToken() method. The returned AttestationToken object will be the value stored by the attestation service.

      Retrieve the current attestation policy for SGX enclaves.

       Response<String> response = client.getAttestationPolicyWithResponse(AttestationType.SGX_ENCLAVE, null,
     Context.NONE);
      Parameters:
      attestationType - Specifies the trusted execution environment whose policy should be retrieved.
      options - Options used when validating the attestation token.
      Returns:
      the response to an attestation policy operation.
      Throws:
      IllegalArgumentException - thrown if parameters fail the validation.
      HttpResponseException - thrown if the request is rejected by server.
      RuntimeException - all other wrapped checked exceptions if the request fails to be sent.

    • getAttestationPolicyWithResponse

      public AttestationResponse<String> getAttestationPolicyWithResponse(AttestationType attestationType, AttestationTokenValidationOptions validationOptions, Context context)
      Retrieves the current policy for an attestation type.

      NOTE: The AttestationAdministrationAsyncClient.getAttestationPolicyWithResponse(AttestationType, AttestationTokenValidationOptions, Context) API returns the underlying attestation policy specified by the user. This is NOT the full attestation policy maintained by the attestation service. Specifically it does not include the signing certificates used to verify the attestation policy.

      To retrieve the signing certificates used to sign the policy, Response object returned from this API is an instance of an AttestationResponse object and the caller can retrieve the full policy object maintained by the service by calling the AttestationResponse.getToken() method. The returned AttestationToken object will be the value stored by the attestation service.

      Retrieve the current attestation policy for SGX enclaves.

       Response<String> response = client.getAttestationPolicyWithResponse(AttestationType.SGX_ENCLAVE, null,
     Context.NONE);
      Parameters:
      attestationType - Specifies the trusted execution environment whose policy should be retrieved.
      validationOptions - Options used when validating the token returned by the attestation service.
      context - Context for the operation.
      Returns:
      the attestation policy expressed as a string.
      Throws:
      IllegalArgumentException - thrown if parameters fail the validation.
      HttpResponseException - thrown if the request is rejected by server.
      RuntimeException - all other wrapped checked exceptions if the request fails to be sent.

    • setAttestationPolicy

      public PolicyResult setAttestationPolicy(AttestationType attestationType, String policyToSet)
      Sets the attestation policy for the specified attestation type for an AAD mode attestation instance. Note that this function will only work on AAD mode attestation instances, because there is no key signing certificate provided. More information about Attestation Policy can be found here.

      Set attestation policy to a constant value.

       String policyToSet = "version=1.0; authorizationrules{=> permit();}; issuancerules{};";
 PolicyResult result = client.setAttestationPolicy(AttestationType.OPEN_ENCLAVE, policyToSet);
      Parameters:
      attestationType - The AttestationType to be updated.
      policyToSet - Attestation Policy to set on the instance.
      Returns:
      PolicyResult expressing the result of the attestation operation.

    • setAttestationPolicy

      public PolicyResult setAttestationPolicy(AttestationType attestationType, AttestationPolicySetOptions options)
      Sets the attestation policy for the specified attestation type, with policy and signing key. Sets the current policy for an attestation type. Setting the attestation requires that the caller provide an AttestationPolicySetOptions object which provides the options for setting the policy. There are two major components to a setPolicy request:
      • The policy to set
      • A signing key used to sign the policy sent to the service (OPTIONAL)
      On Isolated mode attestation instances, the signing key MUST be one of the configured policy signing certificates. 
       String policyToSet = "version=1.0; authorizationrules{=> permit();}; issuancerules{};";
 PolicyResult result = client.setAttestationPolicy(AttestationType.OPEN_ENCLAVE,
     new AttestationPolicySetOptions()
         .setAttestationPolicy(policyToSet)
         .setAttestationSigner(new AttestationSigningKey(certificate, privateKey)));
      Parameters:
      attestationType - The AttestationType to be updated.
      options - AttestationPolicySetOptions for the request.
      Returns:
      PolicyResult expressing the result of the attestation operation.

    • setAttestationPolicyWithResponse

      public AttestationResponse<PolicyResult> setAttestationPolicyWithResponse(AttestationType attestationType, AttestationPolicySetOptions options, Context context)
      Sets the attestation policy for the specified attestation type. Setting the attestation requires that the caller provide an AttestationPolicySetOptions object which provides the options for setting the policy. There are two major components to a setPolicy request:
      • The policy to set
      • A signing key used to sign the policy sent to the service (OPTIONAL)
      On Isolated mode attestation instances, the signing key MUST include one of the configured policy signing certificates. 
       Response<PolicyResult> response = client.setAttestationPolicyWithResponse(AttestationType.OPEN_ENCLAVE,
     new AttestationPolicySetOptions()
         .setAttestationPolicy(policyToSet)
         .setAttestationSigner(new AttestationSigningKey(certificate, privateKey)), Context.NONE);
      Parameters:
      attestationType - The AttestationType to be updated.
      options - AttestationPolicySetOptions for the request.
      context - Context for the operation.
      Returns:
      PolicyResult expressing the result of the attestation operation.

    • calculatePolicyTokenHash

      public BinaryData calculatePolicyTokenHash(String policy, AttestationSigningKey signer)
      Calculates the PolicyTokenHash for a given policy string. The policyTokenHash claim in the PolicyResult class is the SHA-256 hash of the underlying policy set JSON Web Token sent to the attestation service. This helper API allows the caller to independently calculate SHA-256 hash of an attestation token corresponding to the value which would be sent to the attestation service. The value returned by this API must always match the value in the PolicyResult object, if it does not, it means that the attestation policy received by the service is NOT the one which the customer specified. For an example of how to check the policy token hash: 
       BinaryData expectedHash = client.calculatePolicyTokenHash(policyToSet, null);
 BinaryData actualHash = result.getPolicyTokenHash();
 String expectedString = Hex.toHexString(expectedHash.toBytes());
 String actualString = Hex.toHexString(actualHash.toBytes());
 if (!expectedString.equals(actualString)) {
     throw new RuntimeException("Policy was set but not received!!!");
 }
      Parameters:
      policy - AttestationPolicy document use in the underlying JWT.
      signer - Optional signing key used to sign the underlying JWT.
      Returns:
      A BinaryData containing the SHA-256 hash of the attestation policy token generated using the specified policy and signer.

    • resetAttestationPolicy

      public PolicyResult resetAttestationPolicy(AttestationType attestationType)
      Resets the attestation policy for the specified attestation type to the default value. Resets the current policy for an attestation type to the default policy. Note: This is a convenience method that will only work on attestation service instances in AAD mode. Each AttestationType has a "default" attestation policy, the resetAttestationPolicy API resets the value of the attestation policy to the "default" policy. This API allows an attestation instance owner to undo the result of a AttestationAdministrationAsyncClient.setAttestationPolicy(AttestationType, AttestationPolicySetOptions) API call.

      Reset an attestation policy to its defaults on an AAD instance

       PolicyResult result = client.resetAttestationPolicy(AttestationType.OPEN_ENCLAVE);
      Parameters:
      attestationType - The AttestationType to be updated.
      Returns:
      PolicyResult expressing the result of the attestation operation.

    • resetAttestationPolicy

      public PolicyResult resetAttestationPolicy(AttestationType attestationType, AttestationPolicySetOptions options)
      Resets the current policy for an attestation type to the default policy. Each AttestationType has a "default" attestation policy, the resetAttestationPolicy API resets the value of the attestation policy to the "default" policy. This API allows an attestation instance owner to undo the result of a AttestationAdministrationAsyncClient.setAttestationPolicy(AttestationType, AttestationPolicySetOptions) API call.

      Reset an attestation policy to its defaults

       PolicyResult result = client.resetAttestationPolicy(AttestationType.OPEN_ENCLAVE,
     new AttestationPolicySetOptions()
         .setAttestationSigner(new AttestationSigningKey(certificate, privateKey)));
      Parameters:
      attestationType - The AttestationType to be updated.
      options - AttestationPolicySetOptions for the request.
      Returns:
      PolicyResult expressing the result of the attestation operation.

    • resetAttestationPolicyWithResponse

      public AttestationResponse<PolicyResult> resetAttestationPolicyWithResponse(AttestationType attestationType, AttestationPolicySetOptions options, Context context)
      Resets the current policy for an attestation type to the default policy. Each AttestationType has a "default" attestation policy, the resetAttestationPolicy API resets the value of the attestation policy to the "default" policy. This API allows an attestation instance owner to undo the result of a AttestationAdministrationAsyncClient.setAttestationPolicy(AttestationType, AttestationPolicySetOptions) API call.

      Reset an attestation policy to its defaults

       Response<PolicyResult> response = client.resetAttestationPolicyWithResponse(AttestationType.OPEN_ENCLAVE,
     new AttestationPolicySetOptions()
         .setAttestationSigner(new AttestationSigningKey(certificate, privateKey)), Context.NONE);
      Parameters:
      attestationType - The AttestationType to be updated.
      options - AttestationPolicySetOptions for the request.
      context - Context for the operation.
      Returns:
      PolicyResult expressing the result of the attestation operation.

    • listPolicyManagementCertificates

      public AttestationSignerCollection listPolicyManagementCertificates()
      Retrieves the current set of attestation policy signing certificates for this instance.

      On an Isolated attestation instance, each AttestationAdministrationAsyncClient.setAttestationPolicy(AttestationType, AttestationPolicySetOptions) or AttestationAdministrationAsyncClient.resetAttestationPolicy(AttestationType, AttestationPolicySetOptions) API call must be signed with the private key corresponding to one of the certificates in the list returned by this API.

      This establishes that the sender is in possession of the private key associated with the configured attestation policy management certificates, and thus the sender is authorized to perform the API operation.

      Retrieve the set of policy management certificates for this instance.

       AttestationSignerCollection signers = client.listPolicyManagementCertificates();
 System.out.printf("There are %d signers on the instance\n", signers.getAttestationSigners().size());
      Returns:
      the response to an attestation policy operation.
      Throws:
      IllegalArgumentException - thrown if parameters fail the validation.
      HttpResponseException - thrown if the request is rejected by server.
      RuntimeException - all other wrapped checked exceptions if the request fails to be sent.

    • listPolicyManagementCertificatesWithResponse

      public AttestationResponse<AttestationSignerCollection> listPolicyManagementCertificatesWithResponse(AttestationTokenValidationOptions tokenValidationOptions, Context context)
      Retrieves the current set of attestation policy signing certificates for this instance.

      On an Isolated attestation instance, each AttestationAdministrationAsyncClient.setAttestationPolicy(AttestationType, AttestationPolicySetOptions) or AttestationAdministrationAsyncClient.resetAttestationPolicy(AttestationType, AttestationPolicySetOptions) API call must be signed with the private key corresponding to one of the certificates in the list returned by this API.

      This establishes that the sender is in possession of the private key associated with the configured attestation policy management certificates, and thus the sender is authorized to perform the API operation.

      Retrieve the set of policy management certificates for this instance.

       AttestationResponse<AttestationSignerCollection> signersResponse =
     client.listPolicyManagementCertificatesWithResponse(
         new AttestationTokenValidationOptions().setValidationSlack(Duration.ofSeconds(10)), Context.NONE);
 System.out.printf("There are %d signers on the instance\n",
     signersResponse.getValue().getAttestationSigners().size());
      Parameters:
      tokenValidationOptions - Options to be used validating the token returned by the attestation service.
      context - Context for the operation.
      Returns:
      the attestation policy expressed as a string.
      Throws:
      IllegalArgumentException - thrown if parameters fail the validation.
      HttpResponseException - thrown if the request is rejected by server.
      RuntimeException - all other wrapped checked exceptions if the request fails to be sent.

    • addPolicyManagementCertificate

      public PolicyCertificatesModificationResult addPolicyManagementCertificate(PolicyManagementCertificateOptions options)
      Adds a new certificate to the set of policy management certificates on this instance.

      Each Isolated mode attestation service instance maintains a set of certificates which can be used to authorize policy modification operations (in Isolated mode, each policy modification request needs to be signed with the private key associated with one of the policy management certificates).

      This API allows the caller to add a new certificate to the set of policy management certificates.

      The request to add a new certificate must be signed with one of the existing policy management certificates, so the PolicyManagementCertificateOptions object requires both the new certificate to be added and a AttestationSigningKey to sign the add request.

      Add a new certificate to the set of policy management certificates for this instance.

       PolicyCertificatesModificationResult addResult = client.addPolicyManagementCertificate(
     new PolicyManagementCertificateOptions(certificateToAdd, new AttestationSigningKey(certificate, privateKey)));
 System.out.printf(" Result: %s\n", addResult.getCertificateResolution().toString());

      Note: It is not considered an error to add the same certificate twice. If the same certificate is added twice, the service ignores the second add request.

      Parameters:
      options - Options for this API call, encapsulating both the X.509 certificate to add to the set of policy signing certificates and the signing key used to sign the request to the service.
      Returns:
      the response to an attestation policy operation.
      Throws:
      IllegalArgumentException - thrown if parameters fail the validation.
      HttpResponseException - thrown if the request is rejected by server.
      RuntimeException - all other wrapped checked exceptions if the request fails to be sent.

    • addPolicyManagementCertificateWithResponse

      public AttestationResponse<PolicyCertificatesModificationResult> addPolicyManagementCertificateWithResponse(PolicyManagementCertificateOptions options, Context context)
      Adds a new certificate to the set of policy management certificates on this instance. Each Isolated mode attestation service instance maintains a set of certificates which can be used to authorize policy modification operations (in Isolated mode, each policy modification request needs to be signed with the private key associated with one of the policy management certificates). This API allows the caller to add a new certificate to the set of policy management certificates. The request to add a new certificate must be signed with one of the existing policy management certificates, so the PolicyManagementCertificateOptions object requires both the new certificate to be added and a AttestationSigningKey to sign the add request.

      Add a new certificate to the set of policy management certificates for this instance.

       Response<PolicyCertificatesModificationResult> addResponse = client.addPolicyManagementCertificateWithResponse(
     new PolicyManagementCertificateOptions(certificateToAdd, new AttestationSigningKey(certificate, privateKey)),
     Context.NONE);
 System.out.printf(" Result: %s\n", addResponse.getValue().getCertificateResolution().toString());

      Note: It is not considered an error to add the same certificate twice. If the same certificate is added twice, the service ignores the second add request.

      Parameters:
      options - Options for this API call, encapsulating both the X.509 certificate to add to the set of policy signing certificates and the signing key used to sign the request to the service.
      context - Context for the operation.
      Returns:
      the response to an attestation policy operation.
      Throws:
      IllegalArgumentException - thrown if parameters fail the validation.
      HttpResponseException - thrown if the request is rejected by server.
      RuntimeException - all other wrapped checked exceptions if the request fails to be sent.

    • deletePolicyManagementCertificate

      public PolicyCertificatesModificationResult deletePolicyManagementCertificate(PolicyManagementCertificateOptions options)
      Deletes a policy management certificate from the set of policy management certificates.

      Each Isolated mode attestation service instance maintains a set of certificates which can be used to authorize policy modification operations (in Isolated mode, each policy modification request needs to be signed with the private key associated with one of the policy management certificates).

      This API allows the caller to remove an existing certificate from the set of policy management certificates.

      The request to add a new certificate must be signed with one of the existing policy management certificates, so the PolicyManagementCertificateOptions object requires both the new certificate to be added and a AttestationSigningKey to sign the add request.

      Add a new certificate to the set of policy management certificates for this instance.

       PolicyCertificatesModificationResult removeResult = client.deletePolicyManagementCertificate(
     new PolicyManagementCertificateOptions(certificateToAdd, new AttestationSigningKey(certificate, privateKey)));
 System.out.printf(" Result: %s\n", removeResult.getCertificateResolution().toString());

      Note: It is not considered an error to removethe same certificate twice. If the same certificate is removed twice, the service ignores the second remove request. This also means that it is not an error to remove a certificate which was not actually in the set of policy certificates.

      Parameters:
      options - Options for this API call, encapsulating both the X.509 certificate to remove from the set of policy signing certificates and the signing key used to sign the request to the service.
      Returns:
      the response to an attestation policy operation.
      Throws:
      IllegalArgumentException - thrown if parameters fail the validation.
      HttpResponseException - thrown if the request is rejected by server.
      RuntimeException - all other wrapped checked exceptions if the request fails to be sent.

    • deletePolicyManagementCertificateWithResponse

      public AttestationResponse<PolicyCertificatesModificationResult> deletePolicyManagementCertificateWithResponse(PolicyManagementCertificateOptions options, Context context)
      Removes a policy management certificate from the set of policy management certificates.

      Each Isolated mode attestation service instance maintains a set of certificates which can be used to authorize policy modification operations (in Isolated mode, each policy modification request needs to be signed with the private key associated with one of the policy management certificates).

      This API allows the caller to remove an existing certificate from the set of policy management certificates.

      The request to add a new certificate must be signed with one of the existing policy management certificates, so the PolicyManagementCertificateOptions object requires both the new certificate to be added and a AttestationSigningKey to sign the add request.

      Add a new certificate to the set of policy management certificates for this instance.

       Response<PolicyCertificatesModificationResult> removeResponse = client.addPolicyManagementCertificateWithResponse(
     new PolicyManagementCertificateOptions(certificateToAdd, new AttestationSigningKey(certificate, privateKey)),
     Context.NONE);
 System.out.printf(" Result: %s\n", removeResponse.getValue().getCertificateResolution().toString());

      Note: It is not considered an error to remove the same certificate twice. If the same certificate is removed twice, the service ignores the second remove request. This also means that it is not an error to remove a certificate which was not actually in the set of policy certificates.

      Parameters:
      options - Options for this API call, encapsulating both the X.509 certificate to remove from the set of policy signing certificates and the signing key used to sign the request to the service.
      context - Context for the operation.
      Returns:
      the response to an attestation policy operation.
      Throws:
      IllegalArgumentException - thrown if parameters fail the validation.
      HttpResponseException - thrown if the request is rejected by server.
      RuntimeException - all other wrapped checked exceptions if the request fails to be sent.