Add/change some comments in JWT key proto files.

- Replace "bigendian" with "big-endian".
- Add comment on encoding of (x,y) in ECDSA key.
- Add links to RFC where the JWA constants are defined.

PiperOrigin-RevId: 447934090

4 files changed, 34 insertions, 28 deletions

diff --git a/java_src/proto/jwt_ecdsa.proto b/java_src/proto/jwt_ecdsa.proto
index 64afc917e..4c80fe13b 100644
--- a/java_src/proto/jwt_ecdsa.proto
+++ b/java_src/proto/jwt_ecdsa.proto
@@ -22,17 +22,20 @@ option java_package = "com.google.crypto.tink.proto";
 option java_multiple_files = true;
 option go_package = "github.com/google/tink/proto/jwt_ecdsa_go_proto";
 
+// See https://datatracker.ietf.org/doc/html/rfc7518#section-3.4
 enum JwtEcdsaAlgorithm {
   ES_UNKNOWN = 0;
-  ES256 = 1;
-  ES384 = 2;
-  ES512 = 3;
+  ES256 = 1;  // ECDSA using P-256 and SHA-256
+  ES384 = 2;  // ECDSA using P-384 and SHA-384
+  ES512 = 3;  // ECDSA using P-521 and SHA-512
 }
 
 // key_type: type.googleapis.com/google.crypto.tink.JwtEcdsaPublicKey
 message JwtEcdsaPublicKey {
   uint32 version = 1;
   JwtEcdsaAlgorithm algorithm = 2;
+  // Affine coordinates of the public key in big-endian representation. The
+  // public key is a point (x, y) on the curve defined by algorithm.
   bytes x = 3;
   bytes y = 4;
 
diff --git a/java_src/proto/jwt_hmac.proto b/java_src/proto/jwt_hmac.proto
index c4ccba0dd..e54a51da2 100644
--- a/java_src/proto/jwt_hmac.proto
+++ b/java_src/proto/jwt_hmac.proto
@@ -22,11 +22,12 @@ option java_package = "com.google.crypto.tink.proto";
 option java_multiple_files = true;
 option go_package = "github.com/google/tink/proto/jwt_hmac_go_proto";
 
+// See https://datatracker.ietf.org/doc/html/rfc7518#section-3.2
 enum JwtHmacAlgorithm {
   HS_UNKNOWN = 0;
-  HS256 = 1;
-  HS384 = 2;
-  HS512 = 3;
+  HS256 = 1;  // HMAC using SHA-256
+  HS384 = 2;  // HMAC using SHA-384
+  HS512 = 3;  // HMAC using SHA-512
 }
 
 // key_type: type.googleapis.com/google.crypto.tink.JwtHmacKey
diff --git a/java_src/proto/jwt_rsa_ssa_pkcs1.proto b/java_src/proto/jwt_rsa_ssa_pkcs1.proto
index 8d01a4a0b..adf31c899 100644
--- a/java_src/proto/jwt_rsa_ssa_pkcs1.proto
+++ b/java_src/proto/jwt_rsa_ssa_pkcs1.proto
@@ -22,11 +22,12 @@ option java_package = "com.google.crypto.tink.proto";
 option java_multiple_files = true;
 option go_package = "github.com/google/tink/proto/rsa_ssa_pkcs1_go_proto";
 
+// See https://datatracker.ietf.org/doc/html/rfc7518#section-3.3
 enum JwtRsaSsaPkcs1Algorithm {
   RS_UNKNOWN = 0;
-  RS256 = 1;
-  RS384 = 2;
-  RS512 = 3;
+  RS256 = 1;  // RSASSA-PKCS1-v1_5 using SHA-256
+  RS384 = 2;  // RSASSA-PKCS1-v1_5 using SHA-384
+  RS512 = 3;  // RSASSA-PKCS1-v1_5 using SHA-512
 }
 
 // key_type: type.googleapis.com/google.crypto.tink.JwtRsaSsaPkcs1PublicKey
@@ -34,10 +35,10 @@ message JwtRsaSsaPkcs1PublicKey {
   uint32 version = 1;
   JwtRsaSsaPkcs1Algorithm algorithm = 2;
   // Modulus.
-  // Unsigned big integer in bigendian representation.
+  // Unsigned big integer in big-endian representation.
   bytes n = 3;
   // Public exponent.
-  // Unsigned big integer in bigendian representation.
+  // Unsigned big integer in big-endian representation.
   bytes e = 4;
 
   // Optional, custom kid header value to be used with "RAW" keys.
@@ -53,24 +54,24 @@ message JwtRsaSsaPkcs1PrivateKey {
   uint32 version = 1;
   JwtRsaSsaPkcs1PublicKey public_key = 2;
   // Private exponent.
-  // Unsigned big integer in bigendian representation.
+  // Unsigned big integer in big-endian representation.
   bytes d = 3;
 
   // The following parameters are used to optimize RSA signature computation.
   // The prime factor p of n.
-  // Unsigned big integer in bigendian representation.
+  // Unsigned big integer in big-endian representation.
   bytes p = 4;
   // The prime factor q of n.
-  // Unsigned big integer in bigendian representation.
+  // Unsigned big integer in big-endian representation.
   bytes q = 5;
   // d mod (p - 1).
-  // Unsigned big integer in bigendian representation.
+  // Unsigned big integer in big-endian representation.
   bytes dp = 6;
   // d mod (q - 1).
-  // Unsigned big integer in bigendian representation.
+  // Unsigned big integer in big-endian representation.
   bytes dq = 7;
   // Chinese Remainder Theorem coefficient q^(-1) mod p.
-  // Unsigned big integer in bigendian representation.
+  // Unsigned big integer in big-endian representation.
   bytes crt = 8;
 }
 
diff --git a/java_src/proto/jwt_rsa_ssa_pss.proto b/java_src/proto/jwt_rsa_ssa_pss.proto
index e59dd178f..431264576 100644
--- a/java_src/proto/jwt_rsa_ssa_pss.proto
+++ b/java_src/proto/jwt_rsa_ssa_pss.proto
@@ -22,11 +22,12 @@ option java_package = "com.google.crypto.tink.proto";
 option java_multiple_files = true;
 option go_package = "github.com/google/tink/proto/jwt_rsa_ssa_pss_go_proto";
 
+// See https://datatracker.ietf.org/doc/html/rfc7518#section-3.5
 enum JwtRsaSsaPssAlgorithm {
   PS_UNKNOWN = 0;
-  PS256 = 1;
-  PS384 = 2;
-  PS512 = 3;
+  PS256 = 1;  // RSASSA-PSS using SHA-256 and MGF1 with SHA-256
+  PS384 = 2;  // RSASSA-PSS using SHA-384 and MGF1 with SHA-384
+  PS512 = 3;  // RSASSA-PSS using SHA-512 and MGF1 with SHA-512
 }
 
 // key_type: type.googleapis.com/google.crypto.tink.JwtRsaSsaPssPublicKey
@@ -34,10 +35,10 @@ message JwtRsaSsaPssPublicKey {
   uint32 version = 1;
   JwtRsaSsaPssAlgorithm algorithm = 2;
   // Modulus.
-  // Unsigned big integer in bigendian representation.
+  // Unsigned big integer in big-endian representation.
   bytes n = 3;
   // Public exponent.
-  // Unsigned big integer in bigendian representation.
+  // Unsigned big integer in big-endian representation.
   bytes e = 4;
 
   // Optional, custom kid header value to be used with "RAW" keys.
@@ -53,24 +54,24 @@ message JwtRsaSsaPssPrivateKey {
   uint32 version = 1;
   JwtRsaSsaPssPublicKey public_key = 2;
   // Private exponent.
-  // Unsigned big integer in bigendian representation.
+  // Unsigned big integer in big-endian representation.
   bytes d = 3;
 
   // The following parameters are used to optimize RSA signature computation.
   // The prime factor p of n.
-  // Unsigned big integer in bigendian representation.
+  // Unsigned big integer in big-endian representation.
   bytes p = 4;
   // The prime factor q of n.
-  // Unsigned big integer in bigendian representation.
+  // Unsigned big integer in big-endian representation.
   bytes q = 5;
   // d mod (p - 1).
-  // Unsigned big integer in bigendian representation.
+  // Unsigned big integer in big-endian representation.
   bytes dp = 6;
   // d mod (q - 1).
-  // Unsigned big integer in bigendian representation.
+  // Unsigned big integer in big-endian representation.
   bytes dq = 7;
   // Chinese Remainder Theorem coefficient q^(-1) mod p.
-  // Unsigned big integer in bigendian representation.
+  // Unsigned big integer in big-endian representation.
   bytes crt = 8;
 }