From 3d791a5706ed67ead89b538cc43d2c4f07a627ae Mon Sep 17 00:00:00 2001 From: Juerg Wullschleger Date: Mon, 4 Dec 2023 13:39:36 -0800 Subject: [PATCH] Deprecate KmsClients, and its add and get functions. PiperOrigin-RevId: 587826898 Change-Id: I8d4d47c3200063955466e752ceb9e89b354d16bf --- .../com/google/crypto/tink/KmsClients.java | 20 ++++++++++++- .../crypto/tink/aead/KmsAeadKeyManager.java | 19 +++++++++--- .../tink/aead/KmsEnvelopeAeadKeyManager.java | 12 +++++++- .../com/google/crypto/tink/aead/BUILD.bazel | 5 ++++ .../tink/aead/KmsAeadKeyManagerTest.java | 24 +++++++++++++++ .../aead/KmsEnvelopeAeadKeyManagerTest.java | 30 +++++++++++++++++++ 6 files changed, 104 insertions(+), 6 deletions(-) diff --git a/src/main/java/com/google/crypto/tink/KmsClients.java b/src/main/java/com/google/crypto/tink/KmsClients.java index 43e25d36b..dcdc3b2d9 100644 --- a/src/main/java/com/google/crypto/tink/KmsClients.java +++ b/src/main/java/com/google/crypto/tink/KmsClients.java @@ -30,15 +30,31 @@ *

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 autoClients; private static final CopyOnWriteArrayList 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. + * + *

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)) { diff --git a/src/main/java/com/google/crypto/tink/aead/KmsAeadKeyManager.java b/src/main/java/com/google/crypto/tink/aead/KmsAeadKeyManager.java index c745b214a..a4042344e 100644 --- a/src/main/java/com/google/crypto/tink/aead/KmsAeadKeyManager.java +++ b/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. + * + *

It requires that a {@code KmsClient} that can handle {@code kekUri} is registered. Avoid + * registering it more than once. + * + *

Note: 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) { diff --git a/src/main/java/com/google/crypto/tink/aead/KmsEnvelopeAeadKeyManager.java b/src/main/java/com/google/crypto/tink/aead/KmsEnvelopeAeadKeyManager.java index a48219044..a18192792 100644 --- a/src/main/java/com/google/crypto/tink/aead/KmsEnvelopeAeadKeyManager.java +++ b/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). * + *

It requires that a {@code KmsClient} that can handle {@code kekUri} is registered. Avoid + * registering it more than once. + * *

Note: 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. * - *

The second argument of the passed in template is used ignoring the Variant, and assuming + *

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(); diff --git a/src/test/java/com/google/crypto/tink/aead/BUILD.bazel b/src/test/java/com/google/crypto/tink/aead/BUILD.bazel index 56506731d..7f6a5648a 100644 --- a/src/test/java/com/google/crypto/tink/aead/BUILD.bazel +++ b/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", diff --git a/src/test/java/com/google/crypto/tink/aead/KmsAeadKeyManagerTest.java b/src/test/java/com/google/crypto/tink/aead/KmsAeadKeyManagerTest.java index a07829599..998af96db 100644 --- a/src/test/java/com/google/crypto/tink/aead/KmsAeadKeyManagerTest.java +++ b/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"; diff --git a/src/test/java/com/google/crypto/tink/aead/KmsEnvelopeAeadKeyManagerTest.java b/src/test/java/com/google/crypto/tink/aead/KmsEnvelopeAeadKeyManagerTest.java index 9dddfaf84..abfdc807f 100644 --- a/src/test/java/com/google/crypto/tink/aead/KmsEnvelopeAeadKeyManagerTest.java +++ b/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();