Deprecate KmsClients, and its add and get functions.

PiperOrigin-RevId: 587826898
Change-Id: I8d4d47c3200063955466e752ceb9e89b354d16bf

src/main/java/com/google/crypto/tink/KmsClients.java

@@ -30,15 +30,31 @@
  * <p>This class consists exclusively of static methods that register and load {@link
  * KmsClient}-objects.
  *
+ * @deprecated Registering KmsClient is discouraged. Instead call {@link KmsClient#getAead} to get a
+ *     remote {@link Aead}. Use this {@link Aead} to encrypt a keyset with {@link
+ *     TinkProtoKeysetFormat#serializeEncryptedKeyset}, or to create an envelope {@link Aead} using
+ *     {@link com.google.crypto.tink.aead.KmsEnvelopeAead#create}.
  * @since 1.0.0
  */
+@Deprecated // We do not recommend using this API, but there are no plans to remove it.
 public final class KmsClients {
   // The list of KmsClients loaded automatically using ServiceLoader.
   private static List<KmsClient> autoClients;
 
   private static final CopyOnWriteArrayList<KmsClient> clients = new CopyOnWriteArrayList<>();
 
-  /** Adds a client to the list of known {@link KmsClient}-objects. */
+  /**
+   * Adds a client to the list of known {@link KmsClient}-objects.
+   *
+   * <p>This function will always add the {@code client} to a global list. So this function should
+   * only be called on startup and not on every operation. Otherwise this list may keep growing.
+   *
+   * @deprecated Registering KmsClient is discouraged. Instead call {@link KmsClient#getAead} to get
+   *     a remote {@link Aead}. Use this {@link Aead} to encrypt a keyset with {@link
+   *     TinkProtoKeysetFormat#serializeEncryptedKeyset}, or to create an envelope {@link Aead}
+   *     using {@link com.google.crypto.tink.aead.KmsEnvelopeAead#create}.
+   */
+  @Deprecated // We do not recommend using this API, but there are no plans to remove it.
   public static void add(KmsClient client) {
     clients.add(client);
   }
@@ -47,8 +63,10 @@ public static void add(KmsClient client) {
    * Returns the first {@link KmsClient} registered with {@link KmsClients#add} that supports {@code
    * keyUri}.
    *
+   * @deprecated Instead, keep your own instance or list of {@link KmsClient}.
    * @throws GeneralSecurityException if cannot found any KMS clients that support {@code keyUri}
    */
+  @Deprecated // We do not recommend using this API, but there are no plans to remove it.
   public static KmsClient get(String keyUri) throws GeneralSecurityException {
     for (KmsClient client : clients) {
       if (client.doesSupport(keyUri)) {

src/main/java/com/google/crypto/tink/aead/KmsAeadKeyManager.java

@@ -109,12 +109,23 @@ public static void register(boolean newKeyAllowed) throws GeneralSecurityExcepti
    * Returns a new {@link KeyTemplate} that can generate a {@link
    * com.google.crypto.tink.proto.KmsAeadKey} whose key encrypting key (KEK) is pointing to {@code
    * kekUri}. Keys generated by this key template uses RAW output prefix to make them compatible
-   * with the remote KMS' encrypt/decrypt operations. Unlike other templates, when you call {@link
-   * KeysetHandle#generateNew} with this template, Tink does not generate new key material, but only
-   * creates a reference to the remote KEK.
+   * with the remote KMS' encrypt/decrypt operations.
+   *
+   * <p>It requires that a {@code KmsClient} that can handle {@code kekUri} is registered. Avoid
+   * registering it more than once.
+   *
+   * <p><b>Note: </b> Unlike other templates, when you call {@link KeysetHandle#generateNew} with
+   * this template, Tink does not generate new key material, but only creates a reference to the
+   * remote KEK.
+   *
+   * @deprecated Instead of registring a {@code KmsClient}, and creating an {@code Aead} using
+   *     {@code
+   *     KeysetHandle.generateNew(KmsAeadKeyManager.createKeyTemplate(kekUri)).getPrimitive(Aead.class)},
+   *     create the {@code Aead} directly using {@code kmsClient.getAead(kekUri)}, without
+   *     registering any {@code KmsClient}.
    */
+  @Deprecated // We do not recommend using this API, but there are no plans to remove it.
   public static KeyTemplate createKeyTemplate(String kekUri) {
-    KmsAeadKeyFormat format = createKeyFormat(kekUri);
     try {
       return KeyTemplate.createFrom(LegacyKmsAeadParameters.create(kekUri));
     } catch (GeneralSecurityException e) {

src/main/java/com/google/crypto/tink/aead/KmsEnvelopeAeadKeyManager.java

@@ -224,14 +224,24 @@ private static LegacyKmsEnvelopeAeadParameters.DekParsingStrategy getRequiredPar
    * key encrypting key (KEK) is pointing to {@code kekUri} and DEK template is {@code dekTemplate}
    * (or a derived version of it).
    *
+   * <p>It requires that a {@code KmsClient} that can handle {@code kekUri} is registered. Avoid
+   * registering it more than once.
+   *
    * <p><b>Note: </b> Unlike other templates, when you call {@link KeysetHandle#generateNew} with
    * this template Tink does not generate new key material, but instead creates a reference to the
    * remote KEK.
    *
-   * <p>The second argument of the passed in template is used ignoring the Variant, and assuming
+   * <p>The second argument of the passed in template is ignoring the Variant, and assuming
    * NO_PREFIX instead.
+   *
+   * @deprecated Instead of registring a {@code KmsClient}, and creating an {@code Aead} using
+   *     {@code KeysetHandle.generateNew(KmsEnvelopeAeadKeyManager.createKeyTemplate(keyUri,
+   *     KeyTemplates.get("AES128_GCM"))).getPrimitive(Aead.class)}, create the {@code Aead}
+   *     directly using {@code KmsEnvelopeAead.create(PredefinedAeadParameters.AES256_GCM,
+   *     kmsClient.getAead(keyUri))}, without registering any {@code KmsClient}.
    */
   @AccessesPartialKey
+  @Deprecated // We do not recommend using this API, but there are no plans to remove it.
   public static KeyTemplate createKeyTemplate(String kekUri, KeyTemplate dekTemplate) {
     try {
       Parameters parameters = dekTemplate.toParameters();

src/test/java/com/google/crypto/tink/aead/BUILD.bazel

@@ -121,15 +121,19 @@ java_test(
         "//src/main/java/com/google/crypto/tink/aead:aes_gcm_siv_parameters",
         "//src/main/java/com/google/crypto/tink/aead:aes_gcm_siv_proto_serialization",
         "//src/main/java/com/google/crypto/tink/aead:cha_cha20_poly1305_parameters",
+        "//src/main/java/com/google/crypto/tink/aead:kms_envelope_aead",
         "//src/main/java/com/google/crypto/tink/aead:kms_envelope_aead_key_manager",
         "//src/main/java/com/google/crypto/tink/aead:legacy_kms_envelope_aead_parameters",
+        "//src/main/java/com/google/crypto/tink/aead:predefined_aead_parameters",
         "//src/main/java/com/google/crypto/tink/aead:x_cha_cha20_poly1305_parameters",
         "//src/main/java/com/google/crypto/tink/internal:key_template_proto_converter",
         "//src/main/java/com/google/crypto/tink/internal:key_type_manager",
+        "//src/main/java/com/google/crypto/tink/internal:util",
         "//src/main/java/com/google/crypto/tink/mac:hmac_key_manager",
         "//src/main/java/com/google/crypto/tink/subtle:random",
         "//src/main/java/com/google/crypto/tink/testing:fake_kms_client",
         "//src/main/java/com/google/crypto/tink/testing:test_util",
+        "@maven//:com_google_code_findbugs_jsr305",
         "@maven//:com_google_protobuf_protobuf_java",
         "@maven//:com_google_truth_truth",
         "@maven//:junit_junit",
@@ -238,6 +242,7 @@ java_test(
         "//src/main/java/com/google/crypto/tink/aead:aead_config",
         "//src/main/java/com/google/crypto/tink/aead:kms_aead_key_manager",
         "//src/main/java/com/google/crypto/tink/aead:legacy_kms_aead_parameters",
+        "//src/main/java/com/google/crypto/tink/subtle:random",
         "//src/main/java/com/google/crypto/tink/testing:fake_kms_client",
         "//src/main/java/com/google/crypto/tink/testing:test_util",
         "@maven//:com_google_truth_truth",

src/test/java/com/google/crypto/tink/aead/KmsAeadKeyManagerTest.java

@@ -21,6 +21,7 @@
 import com.google.crypto.tink.Aead;
 import com.google.crypto.tink.KeysetHandle;
 import com.google.crypto.tink.KmsClients;
+import com.google.crypto.tink.subtle.Random;
 import com.google.crypto.tink.testing.FakeKmsClient;
 import com.google.crypto.tink.testing.TestUtil;
 import org.junit.Before;
@@ -45,6 +46,29 @@ public void testKmsAead_success() throws Exception {
     TestUtil.runBasicAeadTests(keysetHandle.getPrimitive(Aead.class));
   }
 
+  @Test
+  public void createKeyTemplateGenerateNewGetPrimitive_isSameAs_clientGetAead()
+      throws Exception {
+    String keyUri = FakeKmsClient.createFakeKeyUri();
+
+    // Create Aead primitive using createKeyTemplate, generateNew, and getPrimitive.
+    // This requires that a KmsClient that supports keyUri is registered.
+    KeysetHandle keysetHandle =
+        KeysetHandle.generateNew(KmsAeadKeyManager.createKeyTemplate(keyUri));
+    Aead aead1 = keysetHandle.getPrimitive(Aead.class);
+
+    // Create Aead using FakeKmsClient.getAead.
+    // No KmsClient needs to be registered.
+    Aead aead2 = new FakeKmsClient().getAead(keyUri);
+
+    // Test that aead1 and aead2 are the same.
+    byte[] plaintext = Random.randBytes(20);
+    byte[] associatedData = Random.randBytes(20);
+    byte[] ciphertext = aead1.encrypt(plaintext, associatedData);
+    byte[] decrypted = aead2.decrypt(ciphertext, associatedData);
+    assertThat(decrypted).isEqualTo(plaintext);
+  }
+
   @Test
   public void createKeyTemplate() throws Exception {
     String keyUri = "some example KEK URI";

src/test/java/com/google/crypto/tink/aead/KmsEnvelopeAeadKeyManagerTest.java

@@ -27,6 +27,7 @@
 import com.google.crypto.tink.KmsClients;
 import com.google.crypto.tink.internal.KeyTemplateProtoConverter;
 import com.google.crypto.tink.internal.KeyTypeManager;
+import com.google.crypto.tink.internal.Util;
 import com.google.crypto.tink.mac.HmacKeyManager;
 import com.google.crypto.tink.proto.KeyData.KeyMaterialType;
 import com.google.crypto.tink.proto.KmsEnvelopeAeadKey;
@@ -38,6 +39,8 @@
 import com.google.protobuf.ExtensionRegistryLite;
 import java.nio.ByteBuffer;
 import java.security.GeneralSecurityException;
+import javax.annotation.Nullable;
+import org.junit.Assume;
 import org.junit.BeforeClass;
 import org.junit.Test;
 import org.junit.runner.RunWith;
@@ -442,6 +445,33 @@ public void createKeyTemplate_aesctrhmac_works() throws Exception {
     assertThat(template2.toParameters()).isEqualTo(parameters);
   }
 
+  @Test
+  public void createKeyTemplateGenerateNewGetPrimitive_isSameAs_create() throws Exception {
+    @Nullable Integer apiLevel = Util.getAndroidApiLevel();
+    Assume.assumeTrue(apiLevel == null || apiLevel >= 30); // Run the test on java and android >= 30
+
+    String keyUri = FakeKmsClient.createFakeKeyUri();
+
+    // Create Aead primitive using createKeyTemplate, generateNew, and getPrimitive.
+    // This requires that a KmsClient that supports keyUri is registered.
+    KeyTemplate template =
+        KmsEnvelopeAeadKeyManager.createKeyTemplate(keyUri, KeyTemplates.get("AES128_GCM"));
+    KeysetHandle keysetHandle = KeysetHandle.generateNew(template);
+    Aead aead1 = keysetHandle.getPrimitive(Aead.class);
+
+    // Create Aead using FakeKmsClient.getAead and KmsEnvelopeAead.create.
+    // No KmsClient needs to be registered.
+    Aead keyEncryptionAead = new FakeKmsClient().getAead(keyUri);
+    Aead aead2 = KmsEnvelopeAead.create(PredefinedAeadParameters.AES256_GCM, keyEncryptionAead);
+
+    // Test that aead1 and aead2 are the same.
+    byte[] plaintext = Random.randBytes(20);
+    byte[] associatedData = Random.randBytes(20);
+    byte[] ciphertext = aead1.encrypt(plaintext, associatedData);
+    byte[] decrypted = aead2.decrypt(ciphertext, associatedData);
+    assertThat(decrypted).isEqualTo(plaintext);
+  }
+
   @Test
   public void multipleAeadsWithSameKekAndSameDekTemplate_canDecryptEachOther() throws Exception {
     String kekUri = FakeKmsClient.createFakeKeyUri();