Merge pull request #330 from benmcollins/312-typ-allowlist

jwt: typ media-type helper + algorithm allowlist (RFC 8725)

Author: benmcollins

CMakeLists.txt

@@ -418,6 +418,9 @@ if (CHECK_FOUND)
 	# RFC 7797 unencoded / detached payload
 	list (APPEND UNIT_TESTS jws_b64)
 
+	# RFC 8725 typ helper + algorithm allowlist
+	list (APPEND UNIT_TESTS jwt_typ_alg)
+
 	# ML-DSA (FIPS 204 / RFC 9964). The test is a no-op unless the build
 	# enabled WITH_ML_DSA against a capable backend.
 	list (APPEND UNIT_TESTS jwt_mldsa)

README.md

@@ -16,6 +16,8 @@ Standard | RFC
 ``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
 ``cnf``  | :page_facing_up: [RFC-7800](https://datatracker.ietf.org/doc/html/rfc7800) | Proof-of-Possession (confirmation) claim helpers
+``Unencoded Payload`` | :page_facing_up: [RFC-7797](https://datatracker.ietf.org/doc/html/rfc7797) | JWS unencoded (``b64=false``) and detached payloads
+``BCP 225`` | :page_facing_up: [RFC-8725](https://datatracker.ietf.org/doc/html/rfc8725) | JWT Best Current Practices (``typ`` check, algorithm allowlist)
 
 > [!NOTE]
 > Throughout this documentation you will see links such as the ones

include/jwt.h

@@ -658,6 +658,22 @@ int jwt_builder_setb64(jwt_builder_t *builder, int b64);
 JWT_EXPORT
 int jwt_builder_set_detached(jwt_builder_t *builder, int detached);
 
+/**
+ * @brief Set the token media type ("typ" header)
+ *
+ * A convenience setter for the ``"typ"`` header parameter, naming the token's
+ * media type — e.g. ``"at+jwt"`` (RFC 9068), ``"dpop+jwt"``, ``"secevent+jwt"``.
+ * Equivalent to setting the ``"typ"`` header directly. Pair it with
+ * jwt_checker_expect_typ() on the verifying side.
+ *
+ * @param builder Pointer to a builder object
+ * @param typ The media type string, or NULL to clear it
+ * @return 0 on success, non-zero otherwise with error set in the builder
+ * @since 3.6.0
+ */
+JWT_EXPORT
+int jwt_builder_settyp(jwt_builder_t *builder, const char *typ);
+
 /**
  * @brief Set IssuedAt usage on builder
  *
@@ -985,6 +1001,42 @@ JWT_EXPORT
 int jwt_checker_setkeyring(jwt_checker_t *checker, const jwk_set_t *keyring,
 			   jwt_verify_policy_t policy);
 
+/**
+ * @brief Require a specific token media type ("typ" header)
+ *
+ * When set, jwt_checker_verify() rejects a token whose ``"typ"`` header does not
+ * match @p typ. The comparison is case-insensitive and tolerates the optional
+ * ``application/`` prefix (RFC 6838), so ``expect_typ(c, "at+jwt")`` accepts both
+ * ``"at+jwt"`` and ``"application/at+jwt"``. This is the standardized
+ * cross-JWT-confusion defense (@rfc{8725} §3.11).
+ *
+ * @param checker Pointer to a checker object
+ * @param typ The required media type, or NULL to clear the requirement
+ * @return 0 on success, non-zero otherwise with error set in the checker
+ * @since 3.6.0
+ */
+JWT_EXPORT
+int jwt_checker_expect_typ(jwt_checker_t *checker, const char *typ);
+
+/**
+ * @brief Set an allowlist of acceptable algorithms
+ *
+ * Restricts the algorithms jwt_checker_verify() will accept to the given set,
+ * checked before any signature work (@rfc{8725}). Useful when verifying against
+ * a keyring (jwt_checker_setkeyring()) where several algorithms are acceptable,
+ * e.g. ``{JWT_ALG_RS256, JWT_ALG_ES256}``. A token whose ``"alg"`` is not in the
+ * set is rejected, which also blocks an ``alg:none`` downgrade. Passing @p n as
+ * 0 (or @p algs as NULL) clears the allowlist.
+ *
+ * @param checker Pointer to a checker object
+ * @param algs An array of acceptable ::jwt_alg_t values (copied)
+ * @param n The number of entries in @p algs
+ * @return 0 on success, non-zero otherwise with error set in the checker
+ * @since 3.6.0
+ */
+JWT_EXPORT
+int jwt_checker_setalgs(jwt_checker_t *checker, const jwt_alg_t *algs, size_t n);
+
 /**
  * @brief Set a callback for generating tokens
  *

libjwt/jwt-common.c

@@ -55,6 +55,10 @@ void FUNC(free)(jwt_common_t *__cmd)
 	/* @rfc{7797} Free any raw payload (jwt_builder_setpayload()). */
 	jwt_scrub_and_free(__cmd->c.payload_raw, __cmd->c.payload_raw_len);
 
+	/* @rfc{8725} Free the checker's typ expectation / algorithm allowlist. */
+	jwt_freemem(__cmd->c.expected_typ);
+	jwt_freemem(__cmd->c.alg_allowlist);
+
 	memset(__cmd, 0, sizeof(*__cmd));
 
 	jwt_freemem(__cmd);
@@ -663,6 +667,61 @@ int jwt_checker_setkeyring(jwt_checker_t *checker, const jwk_set_t *keyring,
 	return 0;
 }
 
+int jwt_checker_expect_typ(jwt_checker_t *checker, const char *typ)
+{
+	char *copy = NULL;
+
+	if (checker == NULL)
+		return 1;
+
+	if (typ != NULL) {
+		size_t n = strlen(typ) + 1;
+
+		copy = jwt_malloc(n);
+		if (copy == NULL) {
+			jwt_write_error(checker, "Error allocating memory"); // LCOV_EXCL_LINE
+			return 1; // LCOV_EXCL_LINE
+		}
+		memcpy(copy, typ, n);
+	}
+
+	jwt_freemem(checker->c.expected_typ);
+	checker->c.expected_typ = copy;
+
+	return 0;
+}
+
+int jwt_checker_setalgs(jwt_checker_t *checker, const jwt_alg_t *algs, size_t n)
+{
+	jwt_alg_t *copy = NULL;
+	size_t i;
+
+	if (checker == NULL)
+		return 1;
+
+	if (algs != NULL && n > 0) {
+		for (i = 0; i < n; i++) {
+			if (algs[i] >= JWT_ALG_INVAL) {
+				jwt_write_error(checker,
+					"Invalid algorithm in allowlist");
+				return 1;
+			}
+		}
+		copy = jwt_malloc(n * sizeof(jwt_alg_t));
+		if (copy == NULL) {
+			jwt_write_error(checker, "Error allocating memory"); // LCOV_EXCL_LINE
+			return 1; // LCOV_EXCL_LINE
+		}
+		memcpy(copy, algs, n * sizeof(jwt_alg_t));
+	}
+
+	jwt_freemem(checker->c.alg_allowlist);
+	checker->c.alg_allowlist = copy;
+	checker->c.n_alg_allowlist = copy ? n : 0;
+
+	return 0;
+}
+
 static const struct jwt_signature *checker_sig_at(const jwt_checker_t *checker,
 						  unsigned int index)
 {
@@ -766,6 +825,27 @@ int jwt_builder_set_detached(jwt_builder_t *builder, int detached)
 	return 0;
 }
 
+int jwt_builder_settyp(jwt_builder_t *builder, const char *typ)
+{
+	jwt_json_t *v;
+
+	if (builder == NULL)
+		return 1;
+
+	if (typ == NULL) {
+		jwt_json_obj_del(builder->c.headers, "typ");
+		return 0;
+	}
+
+	v = jwt_json_create_str(typ);
+	if (v == NULL || jwt_json_obj_set(builder->c.headers, "typ", v)) {
+		jwt_write_error(builder, "Error setting \"typ\" header"); // LCOV_EXCL_LINE
+		return 1; // LCOV_EXCL_LINE
+	}
+
+	return 0;
+}
+
 jwt_signature_t *jwt_builder_add_signature(jwt_builder_t *builder,
 					   jwt_alg_t alg, const jwk_item_t *key)
 {

libjwt/jwt-private.h

@@ -122,6 +122,14 @@ struct jwt_common {
 	size_t payload_raw_len;
 	int b64;
 	int detached;
+
+	/* --- @rfc{8725} Checker ergonomics ---
+	 * @expected_typ: if set, the token's "typ" must match it (case-insensitive,
+	 * optional "application/" prefix). @alg_allowlist: if non-empty, the token's
+	 * "alg" must be one of these (checked before the signature). */
+	char *expected_typ;
+	jwt_alg_t *alg_allowlist;
+	size_t n_alg_allowlist;
 };
 
 struct jwt_builder {

libjwt/jwt-verify.c

@@ -8,6 +8,7 @@
 
 #include <stdlib.h>
 #include <string.h>
+#include <strings.h>
 #include <stdio.h>
 
 #include <jwt.h>
@@ -420,9 +421,58 @@ static jwt_claims_t __verify_jti(jwt_t *jwt)
 }
 
 /* This is after parsing and possibly a user callback. */
+/* @rfc{8725,3.11} Compare a media type ignoring case and an optional
+ * "application/" prefix (RFC 6838), so "at+jwt" matches "application/at+jwt". */
+static int jwt_typ_matches(const char *want, const char *got)
+{
+	if (!strncasecmp(want, "application/", 12))
+		want += 12;
+	if (!strncasecmp(got, "application/", 12))
+		got += 12;
+
+	return !strcasecmp(want, got);
+}
+
+/* @rfc{8725} Does the parsed header (@jwt->headers) and algorithm (@jwt->alg)
+ * satisfy the checker's "typ" expectation and algorithm allowlist? Returns 1 if
+ * acceptable (or nothing is configured), 0 if it should be rejected. */
+static int jwt_typ_alg_ok(jwt_t *jwt)
+{
+	jwt_checker_t *checker = jwt->checker;
+	size_t i;
+
+	if (checker == NULL)
+		return 1; // LCOV_EXCL_LINE
+
+	if (checker->c.expected_typ != NULL) {
+		jwt_json_t *t = jwt_json_obj_get(jwt->headers, "typ");
+		const char *got = (t && jwt_json_is_string(t))
+			? jwt_json_str_val(t) : NULL;
+
+		if (got == NULL || !jwt_typ_matches(checker->c.expected_typ, got))
+			return 0;
+	}
+
+	if (checker->c.n_alg_allowlist > 0) {
+		for (i = 0; i < checker->c.n_alg_allowlist; i++)
+			if (checker->c.alg_allowlist[i] == jwt->alg)
+				return 1;
+		return 0;
+	}
+
+	return 1;
+}
+
 static int __verify_config_post(jwt_t *jwt, const jwt_config_t *config,
 				unsigned int sig_len)
 {
+	/* @rfc{8725} Enforce the typ expectation / algorithm allowlist first. */
+	if (!jwt_typ_alg_ok(jwt)) {
+		jwt_write_error(jwt,
+			"Token rejected by \"typ\" or algorithm policy");
+		return 1;
+	}
+
 	/* Yes, we do this before checking a signature. @rfc{7797} An unencoded
 	 * (b64=false) payload is opaque, not JSON claims, so skip claim checks. */
 	if (jwt->b64 && __verify_claims(jwt)) {
@@ -695,6 +745,13 @@ static int verify_entry(jwt_checker_t *checker, jwt_t *jwt,
 		}
 	}
 
+	/* @rfc{8725} A signature whose "typ"/alg does not meet the checker's
+	 * expectation is simply not accepted (skipped), so the policy decides. */
+	if (!jwt_typ_alg_ok(jwt)) {
+		jwt->headers = NULL;
+		return 0;
+	}
+
 	/* Seed the candidate: a kid-named keyring key (a binding assertion, no
 	 * fallback), or the checker's single key. A keyless keyring entry scans. */
 	kid = json_str(s->protected, "kid");