Storage: HMAC service account support

.kokoro/continuous/storage-it.cfg

@@ -25,3 +25,8 @@ env_vars: {
     key: "GOOGLE_APPLICATION_CREDENTIALS"
     value: "keystore/73713_java_it_service_account"
 }
+
+env_vars: {
+    key: "IT_SERVICE_ACCOUNT_EMAIL"
+    value: "it-service-account@gcloud-devel.iam.gserviceaccount.com"
+}

google-cloud-clients/google-cloud-contrib/google-cloud-nio/src/main/java/com/google/cloud/storage/contrib/nio/testing/FakeStorageRpc.java

@@ -18,6 +18,8 @@
 
 import com.google.api.services.storage.model.Bucket;
 import com.google.api.services.storage.model.BucketAccessControl;
+import com.google.api.services.storage.model.HmacKey;
+import com.google.api.services.storage.model.HmacKeyMetadata;
 import com.google.api.services.storage.model.Notification;
 import com.google.api.services.storage.model.ObjectAccessControl;
 import com.google.api.services.storage.model.Policy;
@@ -67,6 +69,7 @@
  *         <li>checksums, etags
  *         <li>IAM operations
  *         <li>BucketLock operations
+ *         <li>HMAC key operations
  *       </ul>
  * </ul>
  */
@@ -420,6 +423,32 @@ public List<BucketAccessControl> listAcls(String bucket, Map<Option, ?> options)
     throw new UnsupportedOperationException();
   }
 
+  @Override
+  public HmacKey createHmacKey(String serviceAccountEmail) {
+    throw new UnsupportedOperationException();
+  }
+
+  @Override
+  public Tuple<String, Iterable<HmacKeyMetadata>> listHmacKeys(
+      String serviceAccountEmail, String pageToken, Long maxResults, boolean showDeletedKeys) {
+    throw new UnsupportedOperationException();
+  }
+
+  @Override
+  public HmacKeyMetadata updateHmacKey(HmacKeyMetadata hmacKeyMetadata) {
+    throw new UnsupportedOperationException();
+  }
+
+  @Override
+  public HmacKeyMetadata getHmacKey(String accessId) {
+    throw new UnsupportedOperationException();
+  }
+
+  @Override
+  public void deleteHmacKey(String accessId) {
+    throw new UnsupportedOperationException();
+  }
+
   @Override
   public ObjectAccessControl getDefaultAcl(String bucket, String entity) {
     throw new UnsupportedOperationException();

google-cloud-clients/google-cloud-storage/src/main/java/com/google/cloud/storage/HmacKey.java

@@ -5,6 +5,7 @@
 import java.io.Serializable;
 import java.util.Objects;
 
+/** HMAC key for a service account. */
 public class HmacKey implements Serializable {
 
   private static final long serialVersionUID = -1809610424373783062L;
@@ -20,6 +21,7 @@ public static Builder newBuilder(String secretKey) {
     return new Builder(secretKey);
   }
 
+  /** Builder for {@code HmacKey} objects. * */
   public static class Builder {
     private String secretKey;
     private HmacKeyMetadata metadata;
@@ -38,22 +40,25 @@ public Builder setMetadata(HmacKeyMetadata metadata) {
       return this;
     }
 
+    /** Creates an {@code HmacKey} object from this builder. * */
     public HmacKey build() {
       return new HmacKey(this);
     }
   }
 
+  /** Returns the secret key associated with this HMAC key. * */
   public String getSecretKey() {
     return secretKey;
   }
 
+  /** Returns the metadata associated with this HMAC key. * */
   public HmacKeyMetadata getMetadata() {
     return metadata;
   }
 
   @Override
   public int hashCode() {
-    return Objects.hash(secretKey,  metadata);
+    return Objects.hash(secretKey, metadata);
   }
 
   @Override
@@ -65,8 +70,7 @@ public boolean equals(Object obj) {
       return false;
     }
     final HmacKeyMetadata other = (HmacKeyMetadata) obj;
-    return Objects.equals(this.secretKey, secretKey)
-            && Objects.equals(this.metadata, metadata);
+    return Objects.equals(this.secretKey, secretKey) && Objects.equals(this.metadata, metadata);
   }
 
   com.google.api.services.storage.model.HmacKey toPb() {
@@ -99,6 +103,10 @@ public enum HmacKeyState {
     }
   }
 
+  /**
+   * The metadata for a service account HMAC key. This class holds all data associated with an HMAC
+   * key other than the secret key.
+   */
   public static class HmacKeyMetadata implements Serializable {
 
     private static final long serialVersionUID = 4571684785352640737L;
@@ -182,38 +190,53 @@ static HmacKeyMetadata fromPb(com.google.api.services.storage.model.HmacKeyMetad
           .build();
     }
 
+    /**
+     * Returns the access id for this HMAC key. This is the id needed to get or delete the key. *
+     */
     public String getAccessId() {
       return accessId;
     }
 
+    /**
+     * Returns HTTP 1.1 Entity tag for this HMAC key.
+     *
+     * @see <a href="http://tools.ietf.org/html/rfc2616#section-3.11">Entity Tags</a>
+     */
     public String getEtag() {
       return etag;
     }
 
+    /** Returns the resource name of this HMAC key. * */
     public String getId() {
       return id;
     }
 
+    /** Returns the project id associated with this HMAC key. * */
     public String getProjectId() {
       return projectId;
     }
 
+    /** Returns the service account associated with this HMAC key. * */
     public ServiceAccount getServiceAccount() {
       return serviceAccount;
     }
 
+    /** Returns the current state of this HMAC key. * */
     public HmacKeyState getState() {
       return state;
     }
 
+    /** Returns the creation time of this HMAC key. * */
     public Long getCreateTime() {
       return createTime;
     }
 
+    /** Returns the last updated time of this HMAC key. * */
     public Long getUpdateTime() {
       return updateTime;
     }
 
+    /** Builder for {@code HmacKeyMetadata} objects. * */
     public static class Builder {
       private String accessId;
       private String etag;
@@ -274,6 +297,7 @@ public Builder setProjectId(String projectId) {
         return this;
       }
 
+      /** Creates an {@code HmacKeyMetadata} object from this builder. * */
       public HmacKeyMetadata build() {
         return new HmacKeyMetadata(this);
       }

google-cloud-clients/google-cloud-storage/src/main/java/com/google/cloud/storage/Storage.java

@@ -2709,17 +2709,117 @@ Blob create(
    */
   List<Acl> listAcls(BlobId blob);
 
+  /**
+   * Creates a new HMAC Key for the provided service account, including the secret key. Note that
+   * the secret key is only returned upon creation via this method.
+   *
+   * <p>Example of creating a new HMAC Key.
+   *
+   * <pre>{@code
+   * ServiceAccount serviceAccount = ServiceAccount.of("my-service-account@google.com");
+   *
+   * HmacKey hmacKey = storage.createHmacKey(serviceAccount);
+   *
+   * String secretKey = hmacKey.getSecretKey();
+   * HmacKey.HmacKeyMetadata metadata = hmacKey.getMetadata();
+   * }</pre>
+   *
+   * @throws StorageException upon failure
+   */
   HmacKey createHmacKey(ServiceAccount serviceAccount);
 
+  /**
+   * Lists HMAC keys for a given service account. Note this returns {@code HmacKeyMetadata} objects,
+   * which do not contain secret keys.
+   *
+   * <p>Example of listing HMAC keys, specifying max results.
+   *
+   * <pre>{@code
+   * ServiceAccount serviceAccount = ServiceAccount.of("my-service-account@google.com");
+   *
+   * Page<HmacKey.HmacKeyMetadata> metadataPage = storage.listHmacKeys(serviceAccount, null, 10);
+   * for (HmacKey.HmacKeyMetadata hmacKeyMetadata : metadataPage.getValues()) {
+   *     //do something with the metadata
+   * }
+   * }</pre>
+   *
+   * @param serviceAccount the service account whose HMAC keys to list
+   * @param pageToken the page from which to start results
+   * @param maxResults the maximum amount of results that can be returned by this request
+   * @param showDeletedKeys whether to show keys with the DELETED state in the result
+   * @throws StorageException upon failure
+   */
   Page<HmacKeyMetadata> listHmacKeys(
-      ServiceAccount serviceAccount, String pageToken, Long maxResults);
+      ServiceAccount serviceAccount, String pageToken, Long maxResults, boolean showDeletedKeys);
 
+  /**
+   * Lists HMAC keys for a given service account. Note this returns {@code HmacKeyMetadata} objects,
+   * which do not contain secret keys. This is the same as calling {@code
+   * listHmacKeys(serviceAccount, null, null, false)}.
+   *
+   * <p>Example of listing HMAC keys.
+   *
+   * <pre>{@code
+   * ServiceAccount serviceAccount = ServiceAccount.of("my-service-account@google.com");
+   *
+   * Page<HmacKey.HmacKeyMetadata> metadataPage = storage.listHmacKeys(serviceAccount);
+   * for (HmacKey.HmacKeyMetadata hmacKeyMetadata : metadataPage.getValues()) {
+   *     //do something with the metadata
+   * }
+   * }</pre>
+   *
+   * @throws StorageException upon failure
+   */
   Page<HmacKeyMetadata> listHmacKeys(ServiceAccount serviceAccount);
 
+  /**
+   * Gets an HMAC key given its access id. Note that this returns a {@code HmacKeyMetadata} object,
+   * which does not contain the secret key.
+   *
+   * <p>Example of getting an HMAC key.
+   *
+   * <pre>{@code
+   * String hmacKeyAccessId = "my-access-id";
+   * HmacKey.HmackeyMetadata hmacKeyMetadata = storage.getHmacKey(hmacKeyAccessId);
+   * }</pre>
+   *
+   * @throws StorageException upon failure
+   */
   HmacKeyMetadata getHmacKey(String accessId);
 
+  /**
+   * Deletes an HMAC key given its access ID. Note that only an {@code INACTIVE} key can be deleted.
+   * Attempting to delete a key whose {@code HmacKey.HmacKeyState} is anything other than {@code
+   * INACTIVE} will fail.
+   *
+   * <p>Example of updating an HMAC key's state to INACTIVE and then deleting it.
+   *
+   * <pre>{@code
+   * String hmacKeyAccessId = "my-access-id";
+   * HmacKey.HmacKeyMetadata hmacKeyMetadata = storage.getHmacKey(hmacKeyAccessId);
+   *
+   * storage.updateHmacKeyState(hmacKeyMetadata, HmacKey.HmacKeyState.INACTIVE);
+   * storage.deleteHmacKey(hmacKeyMetadata.getAccessId());
+   * }</pre>
+   *
+   * @throws StorageException upon failure
+   */
   void deleteHmacKey(String accessId);
 
+  /**
+   * Updates the state of an HMAC key and returns the updated metadata.
+   *
+   * <p>Example of updating the state of a newly created HMAC key.
+   *
+   * <pre>{@code
+   * ServiceAccount serviceAccount = ServiceAccount.of("my-service-account@google.com");
+   * HmacKey key = storage.createHmacKey(serviceAccount);
+   *
+   * storage.updateHmacKeyState(hmacKey.getMetadata(), HmacKey.HmacKeyState.INACTIVE);
+   * }</pre>
+   *
+   * @throws StorageException upon failure
+   */
   HmacKeyMetadata updateHmacKeyState(
       final HmacKeyMetadata hmacKeyMetadata, final HmacKey.HmacKeyState state);
   /**

google-cloud-clients/google-cloud-storage/src/main/java/com/google/cloud/storage/StorageImpl.java

@@ -305,21 +305,25 @@ private static class HmacKeyMetadataPageFetcher implements NextPageFetcher<HmacK
     private final ServiceAccount serviceAccount;
     private final String nextPageToken;
     private final Long maxResults;
+    private final boolean showDeletedKeys;
 
     HmacKeyMetadataPageFetcher(
         StorageOptions serviceOptions,
         ServiceAccount serviceAccount,
         String nextPageToken,
-        Long maxResults) {
+        Long maxResults,
+        boolean showDeletedKeys) {
       this.serviceOptions = serviceOptions;
       this.serviceAccount = serviceAccount;
       this.nextPageToken = nextPageToken;
       this.maxResults = maxResults;
+      this.showDeletedKeys = showDeletedKeys;
     }
 
     @Override
     public Page<HmacKeyMetadata> getNextPage() {
-      return listHmacKeys(serviceOptions, serviceAccount, nextPageToken, maxResults);
+      return listHmacKeys(
+          serviceOptions, serviceAccount, nextPageToken, maxResults, showDeletedKeys);
     }
   }
 
@@ -1209,12 +1213,15 @@ public com.google.api.services.storage.model.HmacKey call() {
 
   @Override
   public Page<HmacKeyMetadata> listHmacKeys(
-      final ServiceAccount serviceAccount, final String pageToken, final Long maxResults) {
-    return listHmacKeys(getOptions(), serviceAccount, pageToken, maxResults);
+      final ServiceAccount serviceAccount,
+      final String pageToken,
+      final Long maxResults,
+      final boolean showDeletedKeys) {
+    return listHmacKeys(getOptions(), serviceAccount, pageToken, maxResults, showDeletedKeys);
   }
 
   public Page<HmacKeyMetadata> listHmacKeys(final ServiceAccount serviceAccount) {
-    return listHmacKeys(getOptions(), serviceAccount, null, null);
+    return listHmacKeys(getOptions(), serviceAccount, null, null, false);
   }
 
   @Override
@@ -1289,7 +1296,8 @@ private static Page<HmacKeyMetadata> listHmacKeys(
       final StorageOptions serviceOptions,
       final ServiceAccount serviceAccount,
       final String pageToken,
-      final Long maxResults) {
+      final Long maxResults,
+      final boolean showDeletedKeys) {
     try {
       Tuple<String, Iterable<com.google.api.services.storage.model.HmacKeyMetadata>> result =
           runWithRetries(
@@ -1302,7 +1310,8 @@ private static Page<HmacKeyMetadata> listHmacKeys(
                     call() {
                   return serviceOptions
                       .getStorageRpcV1()
-                      .listHmacKeys(serviceAccount.getEmail(), pageToken, maxResults);
+                      .listHmacKeys(
+                          serviceAccount.getEmail(), pageToken, maxResults, showDeletedKeys);
                 }
               },
               serviceOptions.getRetrySettings(),
@@ -1323,7 +1332,8 @@ public HmacKeyMetadata apply(
                     }
                   });
       return new PageImpl<>(
-          new HmacKeyMetadataPageFetcher(serviceOptions, serviceAccount, pageToken, maxResults),
+          new HmacKeyMetadataPageFetcher(
+              serviceOptions, serviceAccount, pageToken, maxResults, showDeletedKeys),
           cursor,
           metadata);
     } catch (RetryHelperException e) {

google-cloud-clients/google-cloud-storage/src/main/java/com/google/cloud/storage/spi/v1/HttpStorageRpc.java

@@ -1255,7 +1255,7 @@ public HmacKey createHmacKey(String serviceAccountEmail) {
 
   @Override
   public Tuple<String, Iterable<HmacKeyMetadata>> listHmacKeys(
-      String serviceAccountEmail, String pageToken, Long maxResults) {
+      String serviceAccountEmail, String pageToken, Long maxResults, boolean showDeletedKeys) {
     Span span = startSpan(HttpStorageRpcSpans.SPAN_NAME_LIST_HMAC_KEYS);
     Scope scope = tracer.withSpan(span);
     try {
@@ -1267,6 +1267,7 @@ public Tuple<String, Iterable<HmacKeyMetadata>> listHmacKeys(
               .setServiceAccountEmail(serviceAccountEmail)
               .setPageToken(pageToken)
               .setMaxResults(maxResults)
+              .setShowDeletedKeys(showDeletedKeys)
               .execute();
       return Tuple.<String, Iterable<HmacKeyMetadata>>of(
           hmacKeysMetadata.getNextPageToken(), hmacKeysMetadata.getItems());