Deprecate KMS Registration functions in Golang.

In almost all uses cases, it is easier and less error-prone to directly use the KMS AEAD, instead of registering the KMS client.

PiperOrigin-RevId: 558052260
Change-Id: Icd21a905b7fb7adc5a03f9476becd7e20c202a0b

Author: juergw

aead/aead_key_templates.go

@@ -138,6 +138,10 @@ func XChaCha20Poly1305KeyTemplate() *tinkpb.KeyTemplate {
 // remote KEK.
 //
 // If either uri or dekTemplate contain invalid input, an error is returned.
+//
+// Deprecated: Instead, call kmsClient.GetAEAD to get a remote AEAD, create
+// an envelope AEAD using aead.NewKMSEnvelopeAEAD2.
+// There is no need to call registry.RegisterKMSClient anymore.
 func CreateKMSEnvelopeAEADKeyTemplate(uri string, dekTemplate *tinkpb.KeyTemplate) (*tinkpb.KeyTemplate, error) {
 	if !isSupporedKMSEnvelopeDEK(dekTemplate.GetTypeUrl()) {
 		return nil, fmt.Errorf("unsupported DEK key type %s. Only Tink AEAD key types are supported", dekTemplate.GetTypeUrl())

aead/aead_key_templates_test.go

@@ -174,6 +174,52 @@ func TestKMSEnvelopeAEADKeyTemplateMultipleKeysSameKEK(t *testing.T) {
 	}
 }
 
+// This test shows how migrate away from CreateKMSEnvelopeAEADKeyTemplate.
+func TestMigrateFromCreateKMSEnvelopeAEADKeyTemplateToNewKMSEnvelopeAEAD2(t *testing.T) {
+	kmsClient, err := fakekms.NewClient("fake-kms://")
+	if err != nil {
+		t.Fatalf("fakekms.NewClient('fake-kms://') failed: %v", err)
+	}
+	kekURI := "fake-kms://CM2b3_MDElQKSAowdHlwZS5nb29nbGVhcGlzLmNvbS9nb29nbGUuY3J5cHRvLnRpbmsuQWVzR2NtS2V5EhIaEIK75t5L-adlUwVhWvRuWUwYARABGM2b3_MDIAE"
+
+	// This code:
+	registry.RegisterKMSClient(kmsClient)
+	kmsEnvelopeAEADTemplate, err := aead.CreateKMSEnvelopeAEADKeyTemplate(kekURI, aead.AES128GCMKeyTemplate())
+	if err != nil {
+		t.Fatalf("CreateKMSEnvelopeAEADKeyTemplate() failed: %v", err)
+	}
+	handle, err := keyset.NewHandle(kmsEnvelopeAEADTemplate)
+	if err != nil {
+		t.Fatalf("keyset.NewHandle(kmsEnvelopeAEADTemplate) failed: %v", err)
+	}
+	aead1, err := aead.New(handle)
+	if err != nil {
+		t.Fatalf("aead.New(handle) failed: %v", err)
+	}
+	// can be replace by this:
+	kekAEAD, err := kmsClient.GetAEAD(kekURI)
+	if err != nil {
+		t.Fatalf("kmsClient.GetAEAD(kekURI) failed: %v", err)
+	}
+	aead2 := aead.NewKMSEnvelopeAEAD2(aead.AES128GCMKeyTemplate(), kekAEAD)
+
+	// Check that aead1 and aead2 are compatible.
+	plaintext := []byte("plaintext")
+	associatedData := []byte("associatedData")
+
+	ciphertext, err := aead1.Encrypt(plaintext, associatedData)
+	if err != nil {
+		t.Fatalf("aead1.Encrypt(plaintext, associatedData) failed: %v", err)
+	}
+	decrypted, err := aead2.Decrypt(ciphertext, associatedData)
+	if err != nil {
+		t.Fatalf("aead2.Decrypt(ciphertext, associatedData) failed: %v", err)
+	}
+	if !bytes.Equal(plaintext, decrypted) {
+		t.Fatalf("decrypted data doesn't match plaintext, got: %q, want: %q", decrypted, plaintext)
+	}
+}
+
 // Testing deprecated function, ignoring GoDeprecated.
 func TestCreateKMSEnvelopeAEADKeyTemplateCompatibleWithKMSEnevelopeAEADKeyTemplate(t *testing.T) {
 	fakeKmsClient, err := fakekms.NewClient("fake-kms://")

core/registry/registry.go

@@ -120,14 +120,24 @@ func Primitive(typeURL string, serializedKey []byte) (interface{}, error) {
 	return keyManager.Primitive(serializedKey)
 }
 
-// RegisterKMSClient is used to register a new KMS client
+// RegisterKMSClient is used to register a new KMS client.
+//
+// This function adds an object to a global list. It should only be called on
+// startup.
+//
+// Deprecated: It is preferable to not register clients. Instead, call
+// kmsClient.GetAEAD to get a remote AEAD, and then use it to encrypt
+// a keyset with keyset.Write, or to create an envelope AEAD using
+// aead.NewKMSEnvelopeAEAD2.
 func RegisterKMSClient(kmsClient KMSClient) {
 	kmsClientsMu.Lock()
 	defer kmsClientsMu.Unlock()
 	kmsClients = append(kmsClients, kmsClient)
 }
 
 // GetKMSClient fetches a KMSClient by a given URI.
+//
+// Deprecated: It is preferable to not register clients.
 func GetKMSClient(keyURI string) (KMSClient, error) {
 	kmsClientsMu.RLock()
 	defer kmsClientsMu.RUnlock()
@@ -140,6 +150,10 @@ func GetKMSClient(keyURI string) (KMSClient, error) {
 }
 
 // ClearKMSClients removes all registered KMS clients.
+//
+// Should only be used in tests.
+//
+// Deprecated: It is preferable to not register clients.
 func ClearKMSClients() {
 	kmsClientsMu.Lock()
 	defer kmsClientsMu.Unlock()