Class AttestationAdministrationAsyncClient

java.lang.Object
com.azure.security.attestation.AttestationAdministrationAsyncClient

public final class AttestationAdministrationAsyncClient extends Object
The AttestationAdministrationAsyncClient 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 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

    • getAttestationPolicyWithResponse

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

      NOTE: The 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.

       Mono<AttestationResponse<String>> responseMono =
           client.getAttestationPolicyWithResponse(AttestationType.SGX_ENCLAVE, null);
       responseMono.subscribe(response -> System.out.printf("Current SGX policy: %s\n", response.getValue()));
       
      Parameters:
      attestationType - Specifies the trusted execution environment whose policy should be retrieved.
      validationOptions - Options used to validate the response returned by the attestation service.
      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.
    • getAttestationPolicy

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

      NOTE: The getAttestationPolicy 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, use the getAttestationPolicyWithResponse(AttestationType, AttestationTokenValidationOptions) API. The Response object is an instance of an AttestationResponse object and the caller can retrieve the full information 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.

       Mono<String> policyMono = client.getAttestationPolicy(AttestationType.SGX_ENCLAVE);
       policyMono.subscribe(policy -> System.out.printf("Current SGX policy: %s\n", policy));
       
      Parameters:
      attestationType - Specifies the trusted execution environment to be used to validate the evidence.
      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 Mono<String> getAttestationPolicy(AttestationType attestationType, AttestationTokenValidationOptions options)
      Retrieves the current policy for an attestation type.

      NOTE: The getAttestationPolicy 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, use the getAttestationPolicyWithResponse(AttestationType, AttestationTokenValidationOptions) API. The Response object is an instance of an AttestationResponse object and the caller can retrieve the full information 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.

       Mono<String> policyMono2 = client.getAttestationPolicy(AttestationType.SGX_ENCLAVE,
           new AttestationTokenValidationOptions()
               .setValidationSlack(Duration.ofSeconds(10)));
       policyMono2.subscribe(policy -> System.out.printf("Current SGX policy: %s\n", policy));
       
      Parameters:
      attestationType - Specifies the trusted execution environment to be used to validate the evidence.
      options - Token validation options to validate returned 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.
    • setAttestationPolicy

      public Mono<PolicyResult> setAttestationPolicy(AttestationType attestationType, String newAttestationPolicy)
      Sets the current policy for an attestation type with an unsecured attestation policy.

      Note that this API will only work on AAD mode attestation instances, because it sets the policy using an unsecured attestation token.

       String policyToSet = "version=1.0; authorizationrules{=> permit();}; issuancerules{};";
       Mono<PolicyResult> resultMono = client.setAttestationPolicy(AttestationType.OPEN_ENCLAVE, policyToSet);
       resultMono.subscribe(result -> {
           System.out.printf("Set Policy result: %s\n", result.getPolicyResolution());
       
      Parameters:
      attestationType - Specifies the trusted execution environment to be used to validate the evidence.
      newAttestationPolicy - Specifies the policy to be set on the instance.
      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.
    • setAttestationPolicy

      public Mono<PolicyResult> setAttestationPolicy(AttestationType attestationType, AttestationPolicySetOptions options)
      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{};";
       Mono<PolicyResult> resultMono = client.setAttestationPolicy(AttestationType.OPEN_ENCLAVE,
           new AttestationPolicySetOptions()
               .setAttestationPolicy(policyToSet)
               .setAttestationSigner(new AttestationSigningKey(certificate, privateKey)));
       resultMono.subscribe(result -> System.out.printf("Set Policy Result: %s\n", result.getPolicyResolution()));
       
      Parameters:
      attestationType - Specifies the trusted execution environment to be used to validate the evidence.
      options - Options for the setPolicy operation, including the new policy to be set.
      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.
    • setAttestationPolicyWithResponse

      public Mono<AttestationResponse<PolicyResult>> setAttestationPolicyWithResponse(AttestationType attestationType, AttestationPolicySetOptions options)
      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 include one of the configured policy signing certificates.
       Mono<AttestationResponse<PolicyResult>> resultWithResponseMono = client.setAttestationPolicyWithResponse(
           AttestationType.OPEN_ENCLAVE, new AttestationPolicySetOptions()
               .setAttestationPolicy(policyToSet)
               .setAttestationSigner(new AttestationSigningKey(certificate, privateKey)));
       resultWithResponseMono.subscribe(response -> {
           // Retrieve the token returned by the service from the response object and dump the issuer of
           // that token.
           System.out.printf("Response token issuer: %s\n", response.getToken().getIssuer());
       });
       
      Parameters:
      attestationType - Specifies the trusted execution environment to be used to validate the evidence.
      options - Options for the setPolicy 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.
    • 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 corresponding to the policy and signer.
    • resetAttestationPolicy

      public Mono<PolicyResult> resetAttestationPolicy(AttestationType attestationType)
      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 setAttestationPolicy(AttestationType, AttestationPolicySetOptions) API call.

      Reset an attestation policy to its defaults on an AAD instance

       Mono<PolicyResult> resultMono = client.resetAttestationPolicy(AttestationType.OPEN_ENCLAVE);
       resultMono.subscribe(result -> System.out.printf("Reset result: %s\n", result.getPolicyResolution()));
       
      Parameters:
      attestationType - Specifies the trusted execution environment to be used to validate the evidence.
      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.
    • resetAttestationPolicy

      public Mono<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 setAttestationPolicy(AttestationType, AttestationPolicySetOptions) API call.

      Reset an attestation policy to its defaults

       Mono<PolicyResult> resultMono = client.resetAttestationPolicy(AttestationType.OPEN_ENCLAVE,
           new AttestationPolicySetOptions()
               .setAttestationSigner(new AttestationSigningKey(certificate, privateKey)));
       resultMono.subscribe(result -> System.out.printf("Reset result: %s\n", result.getPolicyResolution().toString()));
       
      Parameters:
      attestationType - Specifies the trusted execution environment to be used to validate the evidence.
      options - Options for the setPolicy operation, including the new policy to be set.
      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.
    • resetAttestationPolicyWithResponse

      public Mono<AttestationResponse<PolicyResult>> resetAttestationPolicyWithResponse(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 setAttestationPolicy(AttestationType, AttestationPolicySetOptions) API call.

      Reset an attestation policy to its defaults

       Mono<AttestationResponse<PolicyResult>> resultWithResponseMono = client.resetAttestationPolicyWithResponse(
           AttestationType.OPEN_ENCLAVE, new AttestationPolicySetOptions()
               .setAttestationSigner(new AttestationSigningKey(certificate, privateKey)));
       resultWithResponseMono.subscribe(resultWithResponse -> System.out.printf("Reset result: %s\n",
           resultWithResponse.getValue().getPolicyResolution().toString()));
       
      Parameters:
      attestationType - Specifies the trusted execution environment to be used to validate the evidence.
      options - Options containing the signing key for the reset 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.
    • listPolicyManagementCertificates

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

      On an Isolated attestation instance, each setAttestationPolicy(AttestationType, AttestationPolicySetOptions) or 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.

       Mono<AttestationSignerCollection> signersMono = client.listPolicyManagementCertificates();
       signersMono.subscribe(signers -> 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 Mono<AttestationResponse<AttestationSignerCollection>> listPolicyManagementCertificatesWithResponse(AttestationTokenValidationOptions options)
      Retrieves the current set of attestation policy signing certificates for this instance.

      On an Isolated attestation instance, each setAttestationPolicy(AttestationType, AttestationPolicySetOptions) or 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.

       Mono<AttestationResponse<AttestationSignerCollection>> signersResponseMono =
           client.listPolicyManagementCertificatesWithResponse(
               new AttestationTokenValidationOptions().setValidationSlack(Duration.ofSeconds(10)));
       signersResponseMono.subscribe(response -> System.out.printf("There are %d signers on the instance\n",
           response.getValue().getAttestationSigners().size()));
       
      Parameters:
      options - Options used to validate the response from the attestation service.
      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 Mono<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.

       Mono<PolicyCertificatesModificationResult> addResultMono = client.addPolicyManagementCertificate(
           new PolicyManagementCertificateOptions(certificateToAdd, new AttestationSigningKey(certificate, privateKey)));
       addResultMono.subscribe(addResult -> 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 Mono<AttestationResponse<PolicyCertificatesModificationResult>> addPolicyManagementCertificateWithResponse(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.

       Mono<AttestationResponse<PolicyCertificatesModificationResult>> addResponseMono = client
           .addPolicyManagementCertificateWithResponse(new PolicyManagementCertificateOptions(certificateToAdd,
               new AttestationSigningKey(certificate, privateKey)));
       addResponseMono.subscribe(addResponse -> 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.
      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 Mono<PolicyCertificatesModificationResult> deletePolicyManagementCertificate(PolicyManagementCertificateOptions options)
      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.

       Mono<PolicyCertificatesModificationResult> removeResultMono = client.deletePolicyManagementCertificate(
           new PolicyManagementCertificateOptions(certificateToAdd, new AttestationSigningKey(certificate, privateKey)));
       removeResultMono.subscribe(removeResult -> System.out.printf("Result: %s\n",
           removeResult.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.
      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 Mono<AttestationResponse<PolicyCertificatesModificationResult>> deletePolicyManagementCertificateWithResponse(PolicyManagementCertificateOptions options)
      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.

       Mono<AttestationResponse<PolicyCertificatesModificationResult>> removeResponseMono = client
           .addPolicyManagementCertificateWithResponse(new PolicyManagementCertificateOptions(certificateToAdd,
               new AttestationSigningKey(certificate, privateKey)));
       removeResponseMono.subscribe(removeResponse -> 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.
      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.