Merge pull request #318 from benmcollins/307-jwk-thumbprint

jwks: RFC 7638 JWK Thumbprint and RFC 9278 Thumbprint URI

Author: benmcollins

CMakeLists.txt

@@ -407,7 +407,7 @@ if (CHECK_FOUND)
 
 	# JWKS Tests
 	list (APPEND UNIT_TESTS jwt_jwks jwt_jwks_errors
-		jwt_ec jwt_rsa jwt_hs jwt_jwks_pem)
+		jwt_ec jwt_rsa jwt_hs jwt_jwks_pem jwt_thumbprint)
 
 	# Checker and Builder
 	list (APPEND UNIT_TESTS jwt_builder jwt_checker jwt_flipflop)

README.md

@@ -14,6 +14,7 @@ Standard | RFC
 ``JWK``  | :page_facing_up: [RFC-7517](https://datatracker.ietf.org/doc/html/rfc7517) | JSON Web Keys and Sets
 ``JWA``  | :page_facing_up: [RFC-7518](https://datatracker.ietf.org/doc/html/rfc7518) | JSON Web Algorithms
 ``JWT``  | :page_facing_up: [RFC-7519](https://datatracker.ietf.org/doc/html/rfc7519) | JSON Web Token
+``JWK Thumbprint`` | :page_facing_up: [RFC-7638](https://datatracker.ietf.org/doc/html/rfc7638) / [RFC-9278](https://datatracker.ietf.org/doc/html/rfc9278) | JWK Thumbprint and Thumbprint URI
 
 > [!NOTE]
 > Throughout this documentation you will see links such as the ones

include/jwt.h

@@ -2211,8 +2211,10 @@ jwk_set_t *jwks_create_fromurl(const char *url, int verify);
  */
 typedef enum {
 	JWK_KEY_NONE		= 0x0000,	/**< No options */
-	JWK_KEY_GEN_KID		= 0x0001,	/**< Generate a random (uuidv4)
-						     "kid" for each imported key */
+	JWK_KEY_GEN_KID		= 0x0001,	/**< Generate a deterministic
+						     "kid" (the @rfc{7638} JWK
+						     SHA-256 thumbprint) for each
+						     imported key */
 	JWK_KEY_TRY_HMAC	= 0x0002,	/**< If the input does not parse
 						     as a PEM/DER key, treat the
 						     raw bytes as an "oct" (HMAC)
@@ -2553,6 +2555,103 @@ char *jwks_item_export(const jwk_item_t *item, int priv);
 JWT_EXPORT
 char *jwks_export(const jwk_set_t *jwk_set, int priv);
 
+/**
+ * @brief Hash algorithm for a JWK Thumbprint
+ *
+ * Selects the digest used by jwks_item_thumbprint() and
+ * jwks_item_thumbprint_uri(). SHA-256 is the value 0, so it is the default for
+ * a zero-initialized argument and is what virtually all deployments use.
+ *
+ * @since 3.6.0
+ */
+typedef enum {
+	JWK_THUMBPRINT_SHA256 = 0,	/**< SHA-256 (default) */
+	JWK_THUMBPRINT_SHA384,		/**< SHA-384 */
+	JWK_THUMBPRINT_SHA512,		/**< SHA-512 */
+} jwk_thumbprint_alg_t;
+
+/**
+ * @brief Compute the JWK Thumbprint of a key
+ *
+ * @rfc{7638,3}
+ *
+ * Produces the base64url-encoded SHA-2 digest of the key's canonical JWK form:
+ * a JSON object containing only the members required for the key type, with no
+ * whitespace and the member names in lexicographic order. The result is a
+ * stable, deterministic fingerprint of the (public) key parameters, commonly
+ * used as a key id (@c "kid") or as the @c "jkt" confirmation value.
+ *
+ * The thumbprint is computed over public parameters and is identical whether
+ * the item was loaded from a JWK or from a PEM/DER key.
+ *
+ * @param item A JWK Item
+ * @param alg The thumbprint hash algorithm (see @ref jwk_thumbprint_alg_t);
+ *   @ref JWK_THUMBPRINT_SHA256 is the default.
+ * @return A newly allocated, nil-terminated base64url string the caller must
+ *   free with free(), or NULL on error (an unusable key, a missing required
+ *   member, or an invalid @p alg).
+ * @since 3.6.0
+ */
+JWT_EXPORT
+char *jwks_item_thumbprint(const jwk_item_t *item, jwk_thumbprint_alg_t alg);
+
+/**
+ * @brief Compute the JWK Thumbprint URI of a key
+ *
+ * @rfc{9278}
+ *
+ * As jwks_item_thumbprint(), but returns the RFC 9278 URI form:
+ * @c "urn:ietf:params:oauth:jwk-thumbprint:sha-256:<thumbprint>" (or
+ * @c sha-384 / @c sha-512 to match @p alg).
+ *
+ * @param item A JWK Item
+ * @param alg The thumbprint hash algorithm (see @ref jwk_thumbprint_alg_t);
+ *   @ref JWK_THUMBPRINT_SHA256 is the default.
+ * @return A newly allocated, nil-terminated URI string the caller must free
+ *   with free(), or NULL on error.
+ * @since 3.6.0
+ */
+JWT_EXPORT
+char *jwks_item_thumbprint_uri(const jwk_item_t *item, jwk_thumbprint_alg_t alg);
+
+/**
+ * @brief Find a key in a set by its JWK Thumbprint
+ *
+ * @rfc{7638}
+ *
+ * Returns the first item in @p jwk_set whose thumbprint (for the given hash)
+ * equals @p thumbprint. Unlike jwks_find_bykid(), this matches on the key's
+ * canonical, deterministic identity rather than the advisory @c "kid", so it
+ * works even when keys carry no (or an inconsistent) @c "kid" — e.g. matching a
+ * proof-of-possession @c "cnf"/@c "jkt" value against a set of known keys.
+ *
+ * @param jwk_set An existing jwk_set_t
+ * @param alg The hash used to produce @p thumbprint (see @ref jwk_thumbprint_alg_t)
+ * @param thumbprint A base64url JWK thumbprint, as from jwks_item_thumbprint()
+ * @return The matching jwk_item_t, or NULL if none matches or on bad input
+ * @since 3.6.0
+ */
+JWT_EXPORT
+jwk_item_t *jwks_find_bythumbprint(jwk_set_t *jwk_set, jwk_thumbprint_alg_t alg,
+				   const char *thumbprint);
+
+/**
+ * @brief Find a key in a set by its JWK Thumbprint URI
+ *
+ * @rfc{9278}
+ *
+ * As jwks_find_bythumbprint(), but takes the RFC 9278 URI form
+ * (@c "urn:ietf:params:oauth:jwk-thumbprint:sha-256:<thumbprint>"); the hash
+ * is taken from the URI's @c sha-NNN label.
+ *
+ * @param jwk_set An existing jwk_set_t
+ * @param uri A JWK Thumbprint URI, as from jwks_item_thumbprint_uri()
+ * @return The matching jwk_item_t, or NULL if none matches or on bad input
+ * @since 3.6.0
+ */
+JWT_EXPORT
+jwk_item_t *jwks_find_bythumbprint_uri(jwk_set_t *jwk_set, const char *uri);
+
 /**
  * @brief Retrieve binary octet data of a key
  *

libjwt/gnutls/sign-verify.c

@@ -454,6 +454,34 @@ static int gnutls_verify_sha_pem(jwt_t *jwt, const char *head,
 	return jwt->error;
 }
 
+/* @rfc{7638} One-shot SHA-2 digest used by the JWK thumbprint. */
+static int gnutls_sha(int sha_bits, const unsigned char *in, size_t in_len,
+		      unsigned char *out, unsigned int *out_len)
+{
+	gnutls_digest_algorithm_t alg;
+
+	switch (sha_bits) {
+	case 256:
+		alg = GNUTLS_DIG_SHA256;
+		break;
+	case 384:
+		alg = GNUTLS_DIG_SHA384;
+		break;
+	case 512:
+		alg = GNUTLS_DIG_SHA512;
+		break;
+	default:
+		return 1; // LCOV_EXCL_LINE
+	}
+
+	if (gnutls_hash_fast(alg, in, in_len, out))
+		return 1; // LCOV_EXCL_LINE
+
+	*out_len = gnutls_hash_get_len(alg);
+
+	return 0;
+}
+
 /* Export our ops */
 struct jwt_crypto_ops jwt_gnutls_ops = {
 	.name			= "gnutls",
@@ -475,6 +503,8 @@ struct jwt_crypto_ops jwt_gnutls_ops = {
 	/* Native-key -> JWK conversion, done natively by GnuTLS. */
 	.key2jwk_params		= gnutls_key2jwk_params,
 
+	.sha			= gnutls_sha,
+
 	.jwe_implemented	= 1,
 	.rng			= gnutls_rng,
 	.encrypt_aes_gcm	= gnutls_encrypt_aes_gcm,

libjwt/jwk-export.c

@@ -24,26 +24,20 @@
 #include <jwt.h>
 #include "jwt-private.h"
 
-/* Generate an RFC 4122 version 4 UUID string into the caller's buffer (which
- * must be at least 37 bytes), using the active backend's CSPRNG. Returns 0 on
- * success. */
-static int uuidv4(char out[37])
+/* Set a deterministic @rfc{7638} "kid" (the SHA-256 JWK thumbprint) on @jwk
+ * when JWK_KEY_GEN_KID is requested. @jwk must already carry the key's members
+ * (its kty plus the type's public parameters). A no-op if the thumbprint
+ * cannot be computed (e.g. a key missing a required public member). */
+static void gen_kid(jwt_json_t *jwk, jwk_key_type_t kty, unsigned int flags)
 {
-	uint8_t b[16];
+	char_auto *tp = NULL;
 
-	if (jwt_ops->rng == NULL || jwt_ops->rng(b, sizeof(b)))
-		return -1; // LCOV_EXCL_LINE
+	if (!(flags & JWK_KEY_GEN_KID))
+		return;
 
-	/* version 4 and RFC 4122 variant */
-	b[6] = (b[6] & 0x0F) | 0x40;
-	b[8] = (b[8] & 0x3F) | 0x80;
-
-	snprintf(out, 37,
-		"%02x%02x%02x%02x-%02x%02x-%02x%02x-%02x%02x-%02x%02x%02x%02x%02x%02x",
-		b[0], b[1], b[2], b[3], b[4], b[5], b[6], b[7],
-		b[8], b[9], b[10], b[11], b[12], b[13], b[14], b[15]);
-
-	return 0;
+	tp = jwt_jwk_thumbprint(jwk, kty, 256);
+	if (tp != NULL)
+		jwt_json_obj_set(jwk, "kid", jwt_json_create_str(tp));
 }
 
 /* For HMAC keys: treat the raw bytes as an "oct" key, guessing the alg from the
@@ -103,7 +97,6 @@ int jwt_key2jwk(const char *key, size_t len, unsigned int flags,
 	jwk_export_t kp;
 	jwt_json_t *jwk, *ops;
 	const char *kty;
-	char kid[37];
 	int r, i;
 
 	memset(&kp, 0, sizeof(kp));
@@ -135,13 +128,11 @@ int jwt_key2jwk(const char *key, size_t len, unsigned int flags,
 		jwt_json_obj_set(jwk, "key_ops", ops);
 	}
 
-	if ((flags & JWK_KEY_GEN_KID) && uuidv4(kid) == 0)
-		jwt_json_obj_set(jwk, "kid", jwt_json_create_str(kid));
-
 	/* HMAC fallback for unparseable input. */
 	if (r != 0) {
 		jwk_export_clear(&kp);
 		process_hmac_key(jwk, (const unsigned char *)key, len);
+		gen_kid(jwk, JWK_KEY_TYPE_OCT, flags);
 		jwt_json_arr_append(out_array, jwk);
 		return 0;
 	}
@@ -175,6 +166,8 @@ int jwt_key2jwk(const char *key, size_t len, unsigned int flags,
 		}
 	}
 
+	gen_kid(jwk, kp.kty, flags);
+
 	jwk_export_clear(&kp);
 	jwt_json_arr_append(out_array, jwk);