jwcrypto: JOSE Web Standards Implementation

Warnings

• breaking The JWT module introduced security fixes in v1.4.0 (CVE-2022-3102) that prevent token type substitution attacks. This required changes to token validation, defaulting to 'JWS' unless explicitly set or inferred. Old applications might break if they relied on implicit auto-detection without specifying `expect_type` or allowing mixed-type tokens.
  Fix: Explicitly set the `expect_type` argument in `jwt.JWT` validation, or ensure that only appropriate algorithms are used to prevent type confusion. A 'born-deprecated' module-level variable can temporarily restore old behavior, but refactoring is strongly recommended.
• deprecated The `RSA1_5` algorithm is considered deprecated due to severe security vulnerabilities (Bleichenbacher RSA padding oracle, Million messages attack). Using it can lead to decryption of intercepted messages or forging signatures.
  Fix: Avoid using `RSA1_5`. If absolutely necessary, it requires explicit re-enabling at object instantiation. Consider migrating to `RSA-OAEP` or `RSASSA-PSS` for secure RSA operations.
• breaking Support for Python 3.6 and 3.7 was dropped starting with version 1.5.3. Installations on these Python versions will likely encounter compatibility issues.
  Fix: Upgrade your Python environment to version 3.8 or newer to ensure compatibility and receive continued updates and security patches.
• breaking The minimum required version for the `cryptography` library was raised to 3.4 in `jwcrypto` v1.5.0. Older versions of `cryptography` will cause dependency resolution failures or runtime errors.
  Fix: Ensure `cryptography>=3.4` is installed. `pip install --upgrade cryptography` can resolve this.
• gotcha JWT payloads are base64-encoded, not encrypted. This means anyone with the token can easily decode and read its contents. Storing sensitive information directly in a JWT payload is a major security risk.
  Fix: Never store sensitive, confidential, or personally identifiable information (PII) directly in a JWT payload. Use JWE (JSON Web Encryption) if the content needs to be confidential, or store sensitive data securely on the server and use the JWT to reference it.
• gotcha Lack of proper validation for the `kid` (Key ID) header parameter can lead to key confusion attacks, where an attacker might influence which key is used for verification.
  Fix: Implement strict validation of the `kid` parameter to ensure it corresponds to an expected key from a trusted source. Do not allow arbitrary `kid` values to dictate key selection without proper authorization.
• gotcha Versions 1.5.1 and 1.5.6 addressed potential Denial of Service (DoS) vulnerabilities related to PBKDF2 symmetric keys (v1.5.1) and high compression ratios (v1.5.6). Older versions might be susceptible.
  Fix: Upgrade to the latest version of `jwcrypto` (1.5.6 or newer) to patch these potential DoS vectors and ensure your application is protected against these specific attacks.

Install

• pip install jwcrypto Install jwcrypto

Imports

• JWK

  from jwcrypto import jwk

• JWS

  from jwcrypto import jws

• JWE

  from jwcrypto import jwe

• JWT

  from jwcrypto import jwt

• json_encode, json_decode

  from jwcrypto.common import json_encode, json_decode

Quickstart

This quickstart demonstrates how to generate a symmetric key, sign a payload using JWS, and then verify the signed token. It utilizes `jwk` for key management and `jws` for signature operations, along with `jwcrypto.common` for JSON encoding.

from jwcrypto import jwk, jws
from jwcrypto.common import json_encode

# 1. Generate a symmetric key
key = jwk.JWK.generate(kty='oct', size=256)

# 2. Define the payload and JWS headers
payload = "My Integrity protected message"
jwstoken = jws.JWS(payload.encode('utf-8'))

# 3. Add signature to the token
jwstoken.add_signature(
    key,
    None,
    json_encode({"alg": "HS256"}),
    json_encode({"kid": key.thumbprint()})
)

# 4. Serialize the JWS token
signed_token = jwstoken.serialize()
print(f"Signed JWS: {signed_token}")

# 5. Verify the JWS token
verifier_token = jws.JWS()
verifier_token.deserialize(signed_token)
verifier_token.verify(key)

# 6. Access the verified payload
verified_payload = verifier_token.payload.decode('utf-8')
print(f"Verified Payload: {verified_payload}")