feat: implement minimum key length validation for HMAC and RSA algorithms

[amanjolhe]

---

Security Fix: CVE-2025-45768 – Enforce Minimum Key Length Validation with Configurable API

This PR resolves CVE-2025-45768 by enforcing minimum key length requirements for HMAC and RSA algorithms, with a professional function-based API for configuration, in compliance with RFC 7518 and NIST SP800-117.

🔒 Security Enhancements

• HMAC Algorithms:
  • HS256: Minimum 32 bytes (256 bits)
  • HS384: Minimum 48 bytes (384 bits)
  • HS512: Minimum 64 bytes (512 bits)
• RSA Algorithms:
  • Minimum 2048-bit key size enforced
• Validation Coverage:
  • Enhanced validation in prepare_key() and from_jwk() methods
  • Applies to all key input formats: bytes, PEM, and JWK

🚀 New API Functions

• set_min_key_length_enforcement(enforce: bool) – Configure validation behavior
  • True (default): Raises InvalidKeyError for weak keys
  • False (deprecated): Issues security warnings but allows operation
• get_min_key_length_enforcement() -> bool – Get current enforcement mode
• Deprecation Warning System – Warns when enforcement is disabled

📚 Documentation & Testing

• Comprehensive Documentation:
  • New "Security Considerations" section in usage docs
  • Key generation examples and best practices
• Robust Test Suite:
  • 5 new API configuration tests
  • All existing tests updated (333 total passing)
  • Test secrets upgraded to meet security requirements

⚠️ Breaking Change

• Default Behavior: Keys below minimum length are rejected with InvalidKeyError
• Migration Path: Temporarily disable enforcement with deprecation warnings
• Future: Enforcement will be mandatory in PyJWT 3.0

Example Usage

import jwt

# Default: enforcement enabled (recommended)
jwt.encode(payload, strong_secret, algorithm='HS256')

# Temporary migration mode (deprecated)
jwt.algorithms.set_min_key_length_enforcement(False)
jwt.encode(payload, weak_secret, algorithm='HS256')  # Issues warning

# Check current mode
is_enforced = jwt.algorithms.get_min_key_length_enforcement()

[amanjolhe]

Hello @jpadilla, @auvipy ,please review. The last PR was removed because I made my repository private.

[amanjolhe]

Hi @auvipy , This is the same PR you approved earlier today. I just wanted to check when the security fix will be released, as our organization’s project is currently using this library. It has been flagged by both CxOne and Black Duck, and many companies are now considering migrating to alternative libraries due to the issue. Also, could you please share when you're planning to release the next version? Clean scan releases on our projects are currently blocked until we get a green signal from both CxOne and Black Duck.

[auvipy]

hopefully very soon.

[abij]

Note the build fails because the "docs/index.rst" have examples which are not updated. The key length is too short.

[amanjolhe]

Hello @auvipy @abij , Can You trigger workflows I made changes in doc files.

[jpadilla]

I wont be able to review this for a couple of days. Whatever we do should have the option of just a warning vs enforcement.

[amanjolhe]

I wont be able to review this for a couple of days. Whatever we do should have the option of just a warning vs enforcement.

I'll implement two methods to give users the option to enable or disable enforcement as needed.

[amanjolhe]

@jpadilla I made the enforcement configurable, added two new APIs, included comments in the code, and updated the documentation.

[cleder]

@amanjolhe when you merge main back into your branch, the tests should turn green

[JanEgner]

Thanks @amanjolhe for taking this up! Just one thing - I'm in two minds about the enforcement. While "secure by default" is obviously a Good Thing, this change will be a breaking one in some (perhaps HMAC) cases and that would be unexpected in a point release.