Complete the Attestation Administration APIs. (Azure#25480)

* Complete policy management management APIs

* Removed a bunch of dead code; cleaned up some comments

* Use Options for Set policy management certificates

* Mandatory parameters are now ctor parameters for PolicyManagementCertificateOptions object

Author: LarryOsterman

sdk/attestation/azure-security-attestation/CHANGELOG.md

@@ -45,6 +45,10 @@ be introduced later.)
 design guidelines.
  * Removed `buildPolicyClient`, `buildPolicyAsyncClient`, `buildPolicyCertificatesClient` and `buildPolicyCertificatesAsyncClient` methods 
 on the `AttestationClientBuilder` class and implemented a new `AttestationAdministrationClient` class which contains the administrative APIs.
+ * Removed `buildPolicyCertificatesClient` and `buildPolicyCertificatesAsyncClient`, and `PolicyCertificatesClient` and `PolicyCertificatesAsyncClient` replacing the functionality 
+with the  `listPolicyManagementCertificates`, `addPolicyManagementCertificate` and `removePolicyManagementCertificate` APIs on the `AttestationAdministrationClient` object.
+ * Removed `JsonWebKey`, `JsonWebKeySet`, `PolicyCertificatesModificationResult`, `PolicyCertificatesModifyResponse`, and `CertificatesResponse` objects 
+because they are no longer a part of the public API surface.
 
 ### Bugs Fixed
 * Attestation tests now all pass when run in Live mode.

sdk/attestation/azure-security-attestation/src/main/java/com/azure/security/attestation/AttestationAdministrationAsyncClient.java

@@ -12,10 +12,16 @@
 import com.azure.core.util.Context;
 import com.azure.security.attestation.models.AttestationPolicySetOptions;
 import com.azure.security.attestation.models.AttestationResponse;
+import com.azure.security.attestation.models.AttestationSigner;
 import com.azure.security.attestation.models.AttestationSigningKey;
+import com.azure.security.attestation.models.AttestationTokenValidationOptions;
 import com.azure.security.attestation.models.AttestationType;
+import com.azure.security.attestation.models.PolicyCertificatesModificationResult;
+import com.azure.security.attestation.models.PolicyManagementCertificateOptions;
 import com.azure.security.attestation.models.PolicyResult;
 
+import java.util.List;
+
 /**
  *
  * The AttestationAdministrationClient provides access to the administrative policy APIs
@@ -58,7 +64,7 @@ public final class AttestationAdministrationClient {
      *
      * <p>
      * <b>NOTE:</b>
-     *     The {@link AttestationAdministrationClient#getAttestationPolicyWithResponse(AttestationType, Context)} API returns the underlying
+     *     The {@link AttestationAdministrationClient#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.
@@ -73,15 +79,16 @@ public final class AttestationAdministrationClient {
      *  </p>
      *
      * @param attestationType Specifies the trusted execution environment whose policy should be retrieved.
+     * @param validationOptions Options used when validating the token returned by the attestation service.
      * @param context Context for the operation.
      * @throws IllegalArgumentException thrown if parameters fail the validation.
      * @throws HttpResponseException thrown if the request is rejected by server.
      * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent.
      * @return the attestation policy expressed as a string.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
-    public Response<String> getAttestationPolicyWithResponse(AttestationType attestationType, Context context) {
-        return asyncClient.getAttestationPolicyWithResponse(attestationType, context).block();
+    public Response<String> getAttestationPolicyWithResponse(AttestationType attestationType, AttestationTokenValidationOptions validationOptions, Context context) {
+        return asyncClient.getAttestationPolicyWithResponse(attestationType, validationOptions, context).block();
     }
 
     /**
@@ -94,7 +101,7 @@ public Response<String> getAttestationPolicyWithResponse(AttestationType attesta
      *     policy.
      *     </p>
      *     <p>
-     *         To retrieve the signing certificates used to sign the policy, use the {@link AttestationAdministrationClient#getAttestationPolicyWithResponse(AttestationType, Context)} API.
+     *         To retrieve the signing certificates used to sign the policy, use the {@link AttestationAdministrationClient#getAttestationPolicyWithResponse(AttestationType, AttestationTokenValidationOptions, Context)} API.
      *         The {@link Response} object is an instance of an {@link com.azure.security.attestation.models.AttestationResponse} object
      *         and the caller can retrieve the full information maintained by the service by calling the {@link AttestationResponse#getToken()} method.
      *         The returned {@link com.azure.security.attestation.models.AttestationToken} object will be
@@ -247,4 +254,122 @@ public Response<PolicyResult> resetAttestationPolicyWithResponse(AttestationType
     }
 
 //  endregion
+
+    /**
+     * Retrieves the current set of attestation policy signing certificates for this instance.
+     *
+     * <p>
+     * On an Isolated attestation instance, each {@link AttestationAdministrationAsyncClient#setAttestationPolicy(AttestationType, AttestationPolicySetOptions)}
+     * or {@link 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.
+     *</p>
+     * <p>
+     *     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.
+     * </p>
+     *
+     * @param tokenValidationOptions Options to be used validating the token returned by the attestation service.
+     * @param context Context for the operation.
+     * @throws IllegalArgumentException thrown if parameters fail the validation.
+     * @throws HttpResponseException thrown if the request is rejected by server.
+     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent.
+     * @return the attestation policy expressed as a string.
+     */
+    @ServiceMethod(returns = ReturnType.SINGLE)
+    public Response<List<AttestationSigner>> listPolicyManagementCertificatesWithResponse(AttestationTokenValidationOptions tokenValidationOptions, Context context) {
+        return asyncClient.listPolicyManagementCertificatesWithResponse(tokenValidationOptions, context).block();
+    }
+
+    /**
+     /**
+     * Retrieves the current set of attestation policy signing certificates for this instance.
+     *
+     * <p>
+     * On an Isolated attestation instance, each {@link AttestationAdministrationAsyncClient#setAttestationPolicy(AttestationType, AttestationPolicySetOptions)}
+     * or {@link 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.
+     * </p>
+     * <p>
+     *     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.
+     * </p>
+     *
+     *
+     * @throws IllegalArgumentException thrown if parameters fail the validation.
+     * @throws HttpResponseException thrown if the request is rejected by server.
+     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent.
+     * @return the response to an attestation policy operation.
+     */
+    @ServiceMethod(returns = ReturnType.SINGLE)
+    public List<AttestationSigner> listPolicyManagementCertificates() {
+        return asyncClient.listPolicyManagementCertificates().block();
+    }
+
+    /**
+     * Adds a new attestation policy certificate to the set of policy management certificates.
+     *
+     * @param 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.
+     * @throws IllegalArgumentException thrown if parameters fail the validation.
+     * @throws HttpResponseException thrown if the request is rejected by server.
+     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent.
+     * @return the response to an attestation policy operation.
+     */
+    @ServiceMethod(returns = ReturnType.SINGLE)
+    public PolicyCertificatesModificationResult addPolicyManagementCertificate(PolicyManagementCertificateOptions options) {
+        return asyncClient.addPolicyManagementCertificate(options).block();
+    }
+
+    /**
+     * Adds a new attestation policy certificate to the set of policy management certificates.
+     *
+     * @param 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.
+     * @param context Context for the operation.
+     * @throws IllegalArgumentException thrown if parameters fail the validation.
+     * @throws HttpResponseException thrown if the request is rejected by server.
+     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent.
+     * @return the response to an attestation policy operation.
+     */
+    @ServiceMethod(returns = ReturnType.SINGLE)
+    public Response<PolicyCertificatesModificationResult> addPolicyManagementCertificateWithResponse(PolicyManagementCertificateOptions options, Context context) {
+        return asyncClient.addPolicyManagementCertificateWithResponse(options, context).block();
+    }
+
+    /**
+     * Adds a new attestation policy certificate to the set of policy management certificates.
+     *
+     * @param 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.
+     * @throws IllegalArgumentException thrown if parameters fail the validation.
+     * @throws HttpResponseException thrown if the request is rejected by server.
+     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent.
+     * @return the response to an attestation policy operation.
+     */
+    @ServiceMethod(returns = ReturnType.SINGLE)
+    public PolicyCertificatesModificationResult removePolicyManagementCertificate(PolicyManagementCertificateOptions options) {
+        return asyncClient.removePolicyManagementCertificate(options).block();
+    }
+
+    /**
+     * Adds a new attestation policy certificate to the set of policy management certificates.
+     *
+     * @param 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.
+     * @param context Context for the operation.
+     * @throws IllegalArgumentException thrown if parameters fail the validation.
+     * @throws HttpResponseException thrown if the request is rejected by server.
+     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent.
+     * @return the response to an attestation policy operation.
+     */
+    @ServiceMethod(returns = ReturnType.SINGLE)
+    public Response<PolicyCertificatesModificationResult> removePolicyManagementCertificateWithResponse(PolicyManagementCertificateOptions options, Context context) {
+        return asyncClient.removePolicyManagementCertificateWithResponse(options, context).block();
+    }
+
+
 };

sdk/attestation/azure-security-attestation/src/main/java/com/azure/security/attestation/AttestationAdministrationClient.java

@@ -16,19 +16,62 @@
 import com.azure.core.util.serializer.SerializerAdapter;
 import com.azure.security.attestation.implementation.AttestationClientImpl;
 import com.azure.security.attestation.implementation.AttestationClientImplBuilder;
+import com.azure.security.attestation.models.AttestationPolicySetOptions;
 import com.azure.security.attestation.models.AttestationTokenValidationOptions;
+import com.azure.security.attestation.models.AttestationType;
 
 import java.net.MalformedURLException;
 import java.net.URL;
 import java.util.Objects;
 
-/** A builder for creating a new instance of the AttestationClient type. */
+/**
+ * A builder for creating a new instance of the AttestationClient type.
+ *
+ * The AttestationAdministrationClient provides access to the administrative policy APIs
+ * implemented by the Attestation Service.
+ * <p>
+ * More information on attestation policies can be found <a href='https://docs.microsoft.com/azure/attestation/basic-concepts#attestation-policy'>here</a>
+ * </p>
+ *
+ * There are two main families of APIs available from the Administration client.
+ * <ul>
+ *     <li>Attestation Policy Management</li>
+ *     <li>Policy Management Certificate Management</li>
+ * </ul>
+ *
+ * The Policy Management APIs provide the ability to retrieve, modify and reset attestation policies.
+ * The policy management APIs are:
+ * <ul>
+ *     <li>
+ * {@link AttestationAdministrationClient#getAttestationPolicy(AttestationType)}
+ * </li>
+ *     <li>
+ * {@link AttestationAdministrationAsyncClient#getAttestationPolicy(AttestationType)}
+ * </li>
+ *     <li>
+ * {@link AttestationAdministrationClient#setAttestationPolicy(AttestationType, AttestationPolicySetOptions)}
+ * </li>
+ *     <li>
+ * {@link AttestationAdministrationAsyncClient#setAttestationPolicy(AttestationType, AttestationPolicySetOptions)}
+ * </li>
+ *     <li>
+ * {@link AttestationAdministrationClient#resetAttestationPolicy(AttestationType, AttestationPolicySetOptions)}
+ * </li>
+ *     <li>
+ * {@link AttestationAdministrationAsyncClient#resetAttestationPolicy(AttestationType, AttestationPolicySetOptions)}
+ * </li>
+ * </ul>
+ * <p>
+ *     The Policy Management Certificate APIs provide the ability to manage the certificates which are
+ *     used to establish authorization for Isolated mode attestation service instances. They include apis to
+ *     enumerate, add and remove policy management certificates.
+ * </p>
+ *
+ */
 @ServiceClientBuilder(
         serviceClients = {
             AttestationAdministrationClient.class,
             AttestationAdministrationAsyncClient.class,
-            PolicyCertificatesClient.class,
-            PolicyCertificatesAsyncClient.class,
         })
 public final class AttestationAdministrationClientBuilder {
     private static final String SDK_NAME = "name";
@@ -239,23 +282,4 @@ private AttestationClientImpl buildInnerClient() {
         }
         return clientImplBuilder.buildClient();
     }
-
-    /**
-     * Builds an instance of PolicyCertificatesAsyncClient async client.
-     *
-     * @return an instance of PolicyCertificatesAsyncClient.
-     */
-    public PolicyCertificatesAsyncClient buildPolicyCertificatesAsyncClient() {
-        return new PolicyCertificatesAsyncClient(buildInnerClient().getPolicyCertificates());
-    }
-
-    /**
-     * Builds an instance of PolicyCertificatesClient sync client.
-     *
-     * @return an instance of PolicyCertificatesClient.
-     */
-    public PolicyCertificatesClient buildPolicyCertificatesClient() {
-        return new PolicyCertificatesClient(buildInnerClient().getPolicyCertificates());
-    }
-
 }