feat: add minimum key length validation for HMAC and RSA

Author: jpadilla

CHANGELOG.rst

@@ -7,9 +7,21 @@ This project adheres to `Semantic Versioning <https://semver.org/>`__.
 `Unreleased <https://github.com/jpadilla/pyjwt/compare/2.10.1...HEAD>`__
 ------------------------------------------------------------------------
 
+Added
+~~~~~
+
+- Add minimum key length validation for HMAC and RSA keys (CWE-326).
+  Warns by default via ``InsecureKeyLengthWarning`` when keys are below
+  minimum recommended lengths per RFC 7518 Section 3.2 (HMAC) and
+  NIST SP 800-131A (RSA). Pass ``enforce_minimum_key_length=True`` in
+  options to ``PyJWT`` or ``PyJWS`` to raise ``InvalidKeyError`` instead.
+- Refactor ``PyJWT`` to own an internal ``PyJWS`` instance instead of
+  calling global ``api_jws`` functions.
+
 Fixed
 ~~~~~
 
+- Enforce ECDSA curve validation per RFC 7518 Section 3.4.
 - Fix build system warnings by @kurtmckee in `#1105 <https://github.com/jpadilla/pyjwt/pull/1105>`__
 - Validate key against allowed types for Algorithm family in `#964 <https://github.com/jpadilla/pyjwt/pull/964>`__
 - Add iterator for JWKSet in `#1041 <https://github.com/jpadilla/pyjwt/pull/1041>`__

docs/algorithms.rst

@@ -19,6 +19,38 @@ This library currently supports:
 * PS512 - RSASSA-PSS signature using SHA-512 and MGF1 padding with SHA-512
 * EdDSA - Both Ed25519 signature using SHA-512 and Ed448 signature using SHA-3 are supported. Ed25519 and Ed448 provide 128-bit and 224-bit security respectively.
 
+Minimum Key Length Requirements
+-------------------------------
+
+PyJWT enforces minimum key lengths per industry standards. Keys below these
+minimums will trigger an ``InsecureKeyLengthWarning`` by default, or raise
+``InvalidKeyError`` if ``enforce_minimum_key_length`` is enabled.
+
+.. list-table::
+   :header-rows: 1
+   :widths: auto
+
+   * - Algorithm
+     - Minimum Key Length
+     - Standard
+   * - HS256
+     - 32 bytes (256 bits)
+     - RFC 7518 Section 3.2
+   * - HS384
+     - 48 bytes (384 bits)
+     - RFC 7518 Section 3.2
+   * - HS512
+     - 64 bytes (512 bits)
+     - RFC 7518 Section 3.2
+   * - RS256/384/512
+     - 2048 bits
+     - NIST SP 800-131A
+   * - PS256/384/512
+     - 2048 bits
+     - NIST SP 800-131A
+
+See :ref:`key-length-validation` for configuration details.
+
 Asymmetric (Public-key) Algorithms
 ----------------------------------
 Usage of RSA (RS\*) and EC (EC\*) algorithms require a basic understanding

docs/api.rst

@@ -50,6 +50,13 @@ Types
     :members:
     :undoc-members:
 
+Warnings
+----------
+
+.. automodule:: jwt.warnings
+    :members:
+    :show-inheritance:
+
 Exceptions
 ----------
 

docs/usage.rst

@@ -404,6 +404,56 @@ By storing the `jti` of every token you've already processed in a database or ca
 If a token with a previously-seen `jti` shows up, you can reject the request, stopping the attack.
 
 
+.. _key-length-validation:
+
+Key Length Validation
+---------------------
+
+PyJWT validates that cryptographic keys meet minimum recommended lengths.
+By default, a warning (``InsecureKeyLengthWarning``) is emitted when a key
+is too short. You can configure PyJWT to raise an ``InvalidKeyError`` instead.
+
+The minimum key lengths are:
+
+* **HMAC** (HS256, HS384, HS512): Key must be at least as long as the hash
+  output (32, 48, or 64 bytes respectively), per `RFC 7518 Section 3.2
+  <https://www.rfc-editor.org/rfc/rfc7518#section-3.2>`_.
+* **RSA** (RS256, RS384, RS512, PS256, PS384, PS512): Key must be at least
+  2048 bits, per `NIST SP 800-131A
+  <https://csrc.nist.gov/publications/detail/sp/800-131a/rev-2/final>`_.
+
+By default, short keys produce a warning:
+
+.. code-block:: pycon
+
+    >>> import jwt
+    >>> jwt.encode({"some": "payload"}, "short", algorithm="HS256")  # doctest: +SKIP
+    # InsecureKeyLengthWarning: The HMAC key is 5 bytes long, which is below
+    # the minimum recommended length of 32 bytes for SHA256. See RFC 7518 Section 3.2.
+
+To enforce minimum key lengths (raise ``InvalidKeyError`` on short keys),
+pass ``enforce_minimum_key_length=True`` in the options when creating a
+``PyJWT`` or ``PyJWS`` instance:
+
+.. code-block:: pycon
+
+    >>> from jwt import PyJWT
+    >>> jwt = PyJWT(options={"enforce_minimum_key_length": True})
+    >>> jwt.encode({"some": "payload"}, "short", algorithm="HS256")
+    Traceback (most recent call last):
+      ...
+    jwt.exceptions.InvalidKeyError: The HMAC key is 5 bytes long, ...
+
+To suppress the warning without enforcing, use Python's standard
+``warnings`` module:
+
+.. code-block:: python
+
+    import warnings
+    import jwt
+
+    warnings.filterwarnings("ignore", category=jwt.InsecureKeyLengthWarning)
+
 Requiring Presence of Claims
 ----------------------------
 

jwt/__init__.py

@@ -26,6 +26,7 @@
     PyJWTError,
 )
 from .jwks_client import PyJWKClient
+from .warnings import InsecureKeyLengthWarning
 
 __version__ = "2.10.1"
 
@@ -55,6 +56,8 @@
     "register_algorithm",
     "unregister_algorithm",
     "get_algorithm_by_name",
+    # Warnings
+    "InsecureKeyLengthWarning",
     # Exceptions
     "DecodeError",
     "ExpiredSignatureError",

jwt/algorithms.py

@@ -288,6 +288,13 @@ def from_jwk(jwk: str | JWKDict) -> Any:
         Deserializes a given key from JWK back into a key object
         """
 
+    def check_key_length(self, key: Any) -> str | None:
+        """
+        Return a warning message if the key is below the minimum
+        recommended length for this algorithm, or None if adequate.
+        """
+        return None
+
 
 class NoneAlgorithm(Algorithm):
     """
@@ -380,6 +387,17 @@ def from_jwk(jwk: str | JWKDict) -> bytes:
 
         return base64url_decode(obj["k"])
 
+    def check_key_length(self, key: bytes) -> str | None:
+        min_length = self.hash_alg().digest_size
+        if len(key) < min_length:
+            return (
+                f"The HMAC key is {len(key)} bytes long, which is below "
+                f"the minimum recommended length of {min_length} bytes for "
+                f"{self.hash_alg().name.upper()}. "
+                f"See RFC 7518 Section 3.2."
+            )
+        return None
+
     def sign(self, msg: bytes, key: bytes) -> bytes:
         return hmac.new(key, msg, self.hash_alg).digest()
 
@@ -400,10 +418,20 @@ class RSAAlgorithm(Algorithm):
         SHA512: ClassVar[type[hashes.HashAlgorithm]] = hashes.SHA512
 
         _crypto_key_types = ALLOWED_RSA_KEY_TYPES
+        _MIN_KEY_SIZE: ClassVar[int] = 2048
 
         def __init__(self, hash_alg: type[hashes.HashAlgorithm]) -> None:
             self.hash_alg = hash_alg
 
+        def check_key_length(self, key: AllowedRSAKeys) -> str | None:
+            if key.key_size < self._MIN_KEY_SIZE:
+                return (
+                    f"The RSA key is {key.key_size} bits long, which is below "
+                    f"the minimum recommended size of {self._MIN_KEY_SIZE} bits. "
+                    f"See NIST SP 800-131A."
+                )
+            return None
+
         def prepare_key(self, key: AllowedRSAKeys | str | bytes) -> AllowedRSAKeys:
             if isinstance(key, self._crypto_key_types):
                 return key

jwt/api_jws.py

@@ -16,11 +16,12 @@
 from .exceptions import (
     DecodeError,
     InvalidAlgorithmError,
+    InvalidKeyError,
     InvalidSignatureError,
     InvalidTokenError,
 )
 from .utils import base64url_decode, base64url_encode
-from .warnings import RemovedInPyjwt3Warning
+from .warnings import InsecureKeyLengthWarning, RemovedInPyjwt3Warning
 
 if TYPE_CHECKING:
     from .algorithms import AllowedPrivateKeys, AllowedPublicKeys
@@ -51,7 +52,7 @@ def __init__(
 
     @staticmethod
     def _get_default_options() -> SigOptions:
-        return {"verify_signature": True}
+        return {"verify_signature": True, "enforce_minimum_key_length": False}
 
     def register_algorithm(self, alg_id: str, alg_obj: Algorithm) -> None:
         """
@@ -180,6 +181,14 @@ def encode(
         if isinstance(key, PyJWK):
             key = key.key
         key = alg_obj.prepare_key(key)
+
+        key_length_msg = alg_obj.check_key_length(key)
+        if key_length_msg:
+            if self.options.get("enforce_minimum_key_length", False):
+                raise InvalidKeyError(key_length_msg)
+            else:
+                warnings.warn(key_length_msg, InsecureKeyLengthWarning, stacklevel=2)
+
         signature = alg_obj.sign(signing_input, key)
 
         segments.append(base64url_encode(signature))
@@ -339,6 +348,13 @@ def _verify_signature(
                 raise InvalidAlgorithmError("Algorithm not supported") from e
             prepared_key = alg_obj.prepare_key(key)
 
+        key_length_msg = alg_obj.check_key_length(prepared_key)
+        if key_length_msg:
+            if self.options.get("enforce_minimum_key_length", False):
+                raise InvalidKeyError(key_length_msg)
+            else:
+                warnings.warn(key_length_msg, InsecureKeyLengthWarning, stacklevel=4)
+
         if not alg_obj.verify(signing_input, prepared_key, signature):
             raise InvalidSignatureError("Signature verification failed")
 

jwt/api_jwt.py

@@ -8,7 +8,7 @@
 from datetime import datetime, timedelta, timezone
 from typing import TYPE_CHECKING, Any, Union, cast
 
-from . import api_jws
+from .api_jws import PyJWS, _jws_global_obj
 from .exceptions import (
     DecodeError,
     ExpiredSignatureError,
@@ -52,6 +52,8 @@ def __init__(self, options: Options | None = None) -> None:
         if options is not None:
             self.options = self._merge_options(options)
 
+        self._jws = PyJWS(options=self._get_sig_options())
+
     @staticmethod
     def _get_default_options() -> FullOptions:
         return {
@@ -65,6 +67,15 @@ def _get_default_options() -> FullOptions:
             "verify_jti": True,
             "require": [],
             "strict_aud": False,
+            "enforce_minimum_key_length": False,
+        }
+
+    def _get_sig_options(self) -> SigOptions:
+        return {
+            "verify_signature": self.options["verify_signature"],
+            "enforce_minimum_key_length": self.options.get(
+                "enforce_minimum_key_length", False
+            ),
         }
 
     def _merge_options(self, options: Options | None = None) -> FullOptions:
@@ -139,7 +150,7 @@ def encode(
             json_encoder=json_encoder,
         )
 
-        return api_jws.encode(
+        return self._jws.encode(
             json_payload,
             key,
             algorithm,
@@ -249,8 +260,12 @@ def decode_complete(
                 stacklevel=2,
             )
 
-        sig_options: SigOptions = {"verify_signature": verify_signature}
-        decoded = api_jws.decode_complete(
+        merged_options = self._merge_options(options)
+
+        sig_options: SigOptions = {
+            "verify_signature": verify_signature,
+        }
+        decoded = self._jws.decode_complete(
             jwt,
             key=key,
             algorithms=algorithms,
@@ -260,7 +275,6 @@ def decode_complete(
 
         payload = self._decode_payload(decoded)
 
-        merged_options = self._merge_options(options)
         self._validate_claims(
             payload,
             merged_options,
@@ -576,6 +590,7 @@ def _validate_iss(
 
 
 _jwt_global_obj = PyJWT()
+_jwt_global_obj._jws = _jws_global_obj
 encode = _jwt_global_obj.encode
 decode_complete = _jwt_global_obj.decode_complete
 decode = _jwt_global_obj.decode

jwt/types.py

@@ -11,6 +11,8 @@ class SigOptions(TypedDict):
 
     verify_signature: bool
     """verify the JWT cryptographic signature"""
+    enforce_minimum_key_length: bool
+    """Default: ``False``. Raise :py:class:`jwt.exceptions.InvalidKeyError` instead of warning when keys are below minimum recommended length."""
 
 
 class Options(TypedDict, total=False):
@@ -47,6 +49,8 @@ class Options(TypedDict, total=False):
     """Default: ``verify_signature``. Check that ``nbf`` (not before) claim value is in the past (if present in payload). """
     verify_sub: bool
     """Default: ``verify_signature``. Check that ``sub`` (subject) claim is a string and matches ``subject`` (if present in payload). """
+    enforce_minimum_key_length: bool
+    """Default: ``False``. Raise :py:class:`jwt.exceptions.InvalidKeyError` instead of warning when keys are below minimum recommended length."""
 
 
 # The only difference between Options and FullOptions is that FullOptions
@@ -62,3 +66,4 @@ class FullOptions(TypedDict):
     verify_jti: bool
     verify_nbf: bool
     verify_sub: bool
+    enforce_minimum_key_length: bool

jwt/warnings.py

@@ -1,2 +1,11 @@
 class RemovedInPyjwt3Warning(DeprecationWarning):
+    """Warning for features that will be removed in PyJWT 3."""
+
+    pass
+
+
+class InsecureKeyLengthWarning(UserWarning):
+    """Warning emitted when a cryptographic key is shorter than the minimum
+    recommended length. See :ref:`key-length-validation` for details."""
+
     pass