Document what an AesGcmKey represents.

As usual in Tink, Tink Keys represent fixed cryptographic functions. They should be documented in the proto; unfortunately we currently don't do this. I hope in the future we can add all these.

PiperOrigin-RevId: 429498845

proto/aes_gcm.proto

@@ -23,14 +23,44 @@ option java_multiple_files = true;
 option go_package = "github.com/google/tink/proto/aes_gcm_go_proto";
 option objc_class_prefix = "TINKPB";
 
-// only allowing IV size in bytes = 12 and tag size in bytes = 16
-// Thus, accept no params.
 message AesGcmKeyFormat {
   uint32 key_size = 2;
   uint32 version = 3;
 }
 
 // key_type: type.googleapis.com/google.crypto.tink.AesGcmKey
+//
+// A AesGcmKey is an AEAD key. Mathematically, it represents the functions
+// Encrypt and Decrypt which we define in the following.
+//
+// First, Tink computes a "output prefix" OP by considering the
+// "OutputPrefixType" message in Keyset.Key and the ID of the key using the
+// Tink function "AEAD-OutputPrefix": (AesGcmKeys must always be stored in a
+// keyset).
+//
+// AEAD-OutputPrefix(output_prefix_type, id):
+//     if output_prefix_type == RAW:
+//       return "";
+//     if output_prefix_type == TINK:
+//       return 0x01 + BigEndian(id)
+//     if output_prefix_type == CRUNCHY:
+//       return 0x00 + BigEndian(id)
+//
+// Then, the function defined by this is defined as:
+// [GCM], Section 5.2.1:
+//  * "Encrypt" maps a plaintext P and associated data A to a ciphertext given
+//    by the concatenation OP || IV || C || T. In addition to [GCM], Tink
+//    has the following restriction: IV is a uniformly random initialization
+//    vector of length 12 bytes and T is restricted to 16 bytes.
+//
+//  * If OP matches the result of AEAD-OutputPrefix, then "Decrypt" maps the
+//    input OP || IV || C || T and A to the the output P in the manner as
+//    described in [GCM], Section 5.2.2. If OP does not match, then "Decrypt"
+//    returns an error.
+// [GCM]: NIST Special Publication 800-38D: Recommendation for Block Cipher
+// Modes of Operation: Galois/Counter Mode (GCM) and GMAC.
+// http://csrc.nist.gov/publications/nistpubs/800-38D/SP-800-38D.pdf.
+
 message AesGcmKey {
   uint32 version = 1;
   bytes key_value = 3;

python/tink/proto/aes_gcm.proto

@@ -23,14 +23,44 @@ option java_multiple_files = true;
 option go_package = "github.com/google/tink/proto/aes_gcm_go_proto";
 option objc_class_prefix = "TINKPB";
 
-// only allowing IV size in bytes = 12 and tag size in bytes = 16
-// Thus, accept no params.
 message AesGcmKeyFormat {
   uint32 key_size = 2;
   uint32 version = 3;
 }
 
 // key_type: type.googleapis.com/google.crypto.tink.AesGcmKey
+//
+// A AesGcmKey is an AEAD key. Mathematically, it represents the functions
+// Encrypt and Decrypt which we define in the following.
+//
+// First, Tink computes a "output prefix" OP by considering the
+// "OutputPrefixType" message in Keyset.Key and the ID of the key using the
+// Tink function "AEAD-OutputPrefix": (AesGcmKeys must always be stored in a
+// keyset).
+//
+// AEAD-OutputPrefix(output_prefix_type, id):
+//     if output_prefix_type == RAW:
+//       return "";
+//     if output_prefix_type == TINK:
+//       return 0x01 + BigEndian(id)
+//     if output_prefix_type == CRUNCHY:
+//       return 0x00 + BigEndian(id)
+//
+// Then, the function defined by this is defined as:
+// [GCM], Section 5.2.1:
+//  * "Encrypt" maps a plaintext P and associated data A to a ciphertext given
+//    by the concatenation OP || IV || C || T. In addition to [GCM], Tink
+//    has the following restriction: IV is a uniformly random initialization
+//    vector of length 12 bytes and T is restricted to 16 bytes.
+//
+//  * If OP matches the result of AEAD-OutputPrefix, then "Decrypt" maps the
+//    input OP || IV || C || T and A to the the output P in the manner as
+//    described in [GCM], Section 5.2.2. If OP does not match, then "Decrypt"
+//    returns an error.
+// [GCM]: NIST Special Publication 800-38D: Recommendation for Block Cipher
+// Modes of Operation: Galois/Counter Mode (GCM) and GMAC.
+// http://csrc.nist.gov/publications/nistpubs/800-38D/SP-800-38D.pdf.
+
 message AesGcmKey {
   uint32 version = 1;
   bytes key_value = 3;