Add support for ES* algorithms (#22)

Author: RobertoPrevato

CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-03-10
+
+- Add support for ES* algorithms for keys.
+
 ## [1.0.4] - 2025-10-18 :musical_keyboard:
 
 - Add a `guardpost.protection` namespace with classes offering a strategy for

README.md

@@ -87,6 +87,7 @@ GuardPost is used in BlackSheep and has been tested with:
 - Okta
 
 ## If you have doubts about authentication vs authorization...
+
 `Authentication` answers the question: _Who is the user who is initiating the
 action?_, or more in general: _Who is the user, or what is the service, that is
 initiating the action?_.

examples/README.md

@@ -42,3 +42,21 @@ authorization.
 
 This example illustrates a basic use of an authorization strategy, with support for
 dependency injection for authorization requirements.
+
+
+## example-08.py
+
+This example illustrates how to validate JWTs signed with RSA keys (RS256),
+using an in-memory JWKS built from a generated RSA key pair.
+
+
+## example-09.py
+
+This example illustrates how to validate JWTs signed with EC keys (ES256, ES384,
+ES512), using an in-memory JWKS built from generated EC key pairs.
+
+
+## example-10.py
+
+This example illustrates how to validate JWTs signed with a symmetric secret key
+(HMAC), using the SymmetricJWTValidator with HS256, HS384, and HS512 algorithms.

examples/example-08.py

@@ -0,0 +1,69 @@
+"""
+This example illustrates how to validate JWTs signed with RSA keys (RS256),
+using an in-memory JWKS built from a generated RSA key pair.
+"""
+import asyncio
+import base64
+
+import jwt
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+
+from guardpost.jwks import JWKS, InMemoryKeysProvider
+from guardpost.jwts import AsymmetricJWTValidator
+
+
+def _int_to_base64url(value: int) -> str:
+    length = (value.bit_length() + 7) // 8
+    return base64.urlsafe_b64encode(value.to_bytes(length, "big")).rstrip(b"=").decode()
+
+
+def generate_rsa_key_pair():
+    """Generate an RSA private key and return (private_pem, jwk_dict)."""
+    private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+    private_pem = private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    pub_numbers = private_key.public_key().public_numbers()
+    jwk_dict = {
+        "kty": "RSA",
+        "kid": "my-rsa-key",
+        "n": _int_to_base64url(pub_numbers.n),
+        "e": _int_to_base64url(pub_numbers.e),
+    }
+    return private_pem, jwk_dict
+
+
+async def main():
+    # 1. Generate an RSA key pair and build an in-memory JWKS
+    private_pem, jwk_dict = generate_rsa_key_pair()
+    jwks = JWKS.from_dict({"keys": [jwk_dict]})
+    keys_provider = InMemoryKeysProvider(jwks)
+
+    # 2. Configure the validator for RS256
+    validator = AsymmetricJWTValidator(
+        valid_issuers=["https://example.com"],
+        valid_audiences=["my-api"],
+        keys_provider=keys_provider,
+        algorithms=["RS256"],
+    )
+
+    # 3. Sign a JWT with the RSA private key
+    payload = {"iss": "https://example.com", "aud": "my-api", "sub": "user-123"}
+    token = jwt.encode(
+        payload,
+        private_pem,
+        algorithm="RS256",
+        headers={"kid": "my-rsa-key"},
+    )
+
+    # 4. Validate the token — returns the decoded claims on success
+    claims = await validator.validate_jwt(token)
+
+    assert claims["sub"] == "user-123"
+    print("RSA JWT validated successfully. Claims:", claims)
+
+
+asyncio.run(main())

examples/example-09.py

@@ -0,0 +1,85 @@
+"""
+This example illustrates how to validate JWTs signed with EC keys (ES256, ES384,
+ES512), using an in-memory JWKS built from generated EC key pairs.
+"""
+import asyncio
+import base64
+
+import jwt
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+
+from guardpost.jwks import JWKS, InMemoryKeysProvider
+from guardpost.jwts import AsymmetricJWTValidator
+
+
+def _int_to_base64url(value: int, length: int) -> str:
+    return base64.urlsafe_b64encode(value.to_bytes(length, "big")).rstrip(b"=").decode()
+
+
+def generate_ec_key_pair(curve, kid: str, alg: str, crv: str):
+    """Generate an EC private key and return (private_pem, jwk_dict)."""
+    private_key = ec.generate_private_key(curve())
+    private_pem = private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    pub_numbers = private_key.public_key().public_numbers()
+    key_size = (curve().key_size + 7) // 8
+    jwk_dict = {
+        "kty": "EC",
+        "kid": kid,
+        "alg": alg,
+        "crv": crv,
+        "x": _int_to_base64url(pub_numbers.x, key_size),
+        "y": _int_to_base64url(pub_numbers.y, key_size),
+    }
+    return private_pem, jwk_dict
+
+
+async def main():
+    # 1. Generate EC key pairs for P-256 (ES256), P-384 (ES384), and P-521 (ES512)
+    key_configs = [
+        (ec.SECP256R1, "key-p256", "ES256", "P-256"),
+        (ec.SECP384R1, "key-p384", "ES384", "P-384"),
+        (ec.SECP521R1, "key-p521", "ES512", "P-521"),
+    ]
+    private_keys = {}
+    jwk_list = []
+    for curve, kid, alg, crv in key_configs:
+        private_pem, jwk_dict = generate_ec_key_pair(curve, kid, alg, crv)
+        private_keys[kid] = (private_pem, alg)
+        jwk_list.append(jwk_dict)
+
+    # 2. Build an in-memory JWKS and configure the validator for all EC algorithms
+    jwks = JWKS.from_dict({"keys": jwk_list})
+    keys_provider = InMemoryKeysProvider(jwks)
+    validator = AsymmetricJWTValidator(
+        valid_issuers=["https://example.com"],
+        valid_audiences=["my-api"],
+        keys_provider=keys_provider,
+        algorithms=["ES256", "ES384", "ES512"],
+    )
+
+    # 3. Sign and validate a JWT for each key
+    for kid, (private_pem, alg) in private_keys.items():
+        payload = {
+            "iss": "https://example.com",
+            "aud": "my-api",
+            "sub": f"user-signed-with-{kid}",
+        }
+        token = jwt.encode(
+            payload,
+            private_pem,
+            algorithm=alg,
+            headers={"kid": kid},
+        )
+
+        claims = await validator.validate_jwt(token)
+
+        assert claims["sub"] == f"user-signed-with-{kid}"
+        print(f"EC JWT ({alg}) validated successfully. Claims:", claims)
+
+
+asyncio.run(main())

examples/example-10.py

@@ -0,0 +1,56 @@
+"""
+This example illustrates how to validate JWTs signed with a symmetric secret key
+(HMAC), using the SymmetricJWTValidator with HS256, HS384, and HS512 algorithms.
+"""
+import asyncio
+
+import jwt
+
+from guardpost.jwts import SymmetricJWTValidator
+
+
+async def main():
+    # The secret must be at least 64 bytes to satisfy HS512's minimum key length.
+    secret = "super-secret-key-that-is-long-enough-for-all-hmac-algorithms-hs256-hs384-hs512!"
+
+    # 1. Validate a token signed with HS256 (default)
+    validator_hs256 = SymmetricJWTValidator(
+        valid_issuers=["https://example.com"],
+        valid_audiences=["my-api"],
+        secret_key=secret,
+        algorithms=["HS256"],
+    )
+
+    payload = {"iss": "https://example.com", "aud": "my-api", "sub": "user-123"}
+    token_hs256 = jwt.encode(payload, secret, algorithm="HS256")
+
+    claims = await validator_hs256.validate_jwt(token_hs256)
+    assert claims["sub"] == "user-123"
+    print("HS256 JWT validated successfully. Claims:", claims)
+
+    # 2. Validate a token signed with HS384
+    validator_hs384 = SymmetricJWTValidator(
+        valid_issuers=["https://example.com"],
+        valid_audiences=["my-api"],
+        secret_key=secret,
+        algorithms=["HS384"],
+    )
+
+    token_hs384 = jwt.encode(payload, secret, algorithm="HS384")
+    claims = await validator_hs384.validate_jwt(token_hs384)
+    print("HS384 JWT validated successfully. Claims:", claims)
+
+    # 3. Validate a token signed with HS512
+    validator_hs512 = SymmetricJWTValidator(
+        valid_issuers=["https://example.com"],
+        valid_audiences=["my-api"],
+        secret_key=secret,
+        algorithms=["HS512"],
+    )
+
+    token_hs512 = jwt.encode(payload, secret, algorithm="HS512")
+    claims = await validator_hs512.validate_jwt(token_hs512)
+    print("HS512 JWT validated successfully. Claims:", claims)
+
+
+asyncio.run(main())

guardpost/__about__.py

@@ -1 +1 @@
-__version__ = "1.0.4"
+__version__ = "1.1.0"

guardpost/jwks/__init__.py

@@ -2,10 +2,17 @@
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
 from enum import Enum
-from typing import List, Optional
+from typing import Dict, List, Optional, Type
 
 from cryptography.hazmat.backends import default_backend
 from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ec import (
+    SECP256R1,
+    SECP384R1,
+    SECP521R1,
+    EllipticCurve,
+    EllipticCurvePublicNumbers,
+)
 from cryptography.hazmat.primitives.asymmetric.rsa import RSAPublicNumbers
 
 from guardpost.errors import UnsupportedFeatureError
@@ -17,6 +24,13 @@ def _raise_if_missing(value: dict, *keys: str) -> None:
             raise ValueError(f"Missing {key}")
 
 
+_EC_CURVES: Dict[str, Type[EllipticCurve]] = {
+    "P-256": SECP256R1,
+    "P-384": SECP384R1,
+    "P-521": SECP521R1,
+}
+
+
 class KeyType(Enum):
     EC = "EC"
     RSA = "RSA"
@@ -40,29 +54,51 @@ class JWK:
     A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data
     structure that represents a cryptographic key.
 
+    Supports RSA keys (kty="RSA") and EC keys (kty="EC") with curves
+    P-256, P-384, and P-521.
+
     For more information: https://datatracker.ietf.org/doc/html/rfc7517
     """
 
     kty: KeyType
-    n: str
-    e: str
     pem: bytes
     kid: Optional[str] = None
+    # RSA parameters
+    n: Optional[str] = None
+    e: Optional[str] = None
+    # EC parameters
+    crv: Optional[str] = None
+    x: Optional[str] = None
+    y: Optional[str] = None
 
     @classmethod
     def from_dict(cls, value) -> "JWK":
         key_type = KeyType.from_str(value.get("kty"))
 
-        if key_type != KeyType.RSA:
-            raise UnsupportedFeatureError("This library supports only RSA public keys.")
-
-        _raise_if_missing(value, "n", "e")
-        return cls(
-            kty=key_type,
-            n=value["n"],
-            e=value["e"],
-            kid=value.get("kid"),
-            pem=rsa_pem_from_n_and_e(value["n"], value["e"]),
+        if key_type == KeyType.RSA:
+            _raise_if_missing(value, "n", "e")
+            return cls(
+                kty=key_type,
+                n=value["n"],
+                e=value["e"],
+                kid=value.get("kid"),
+                pem=rsa_pem_from_n_and_e(value["n"], value["e"]),
+            )
+
+        if key_type == KeyType.EC:
+            _raise_if_missing(value, "crv", "x", "y")
+            return cls(
+                kty=key_type,
+                crv=value["crv"],
+                x=value["x"],
+                y=value["y"],
+                kid=value.get("kid"),
+                pem=ec_pem_from_x_y_crv(value["x"], value["y"], value["crv"]),
+            )
+
+        raise UnsupportedFeatureError(
+            f"Unsupported key type: {key_type.value}. "
+            "This library supports RSA and EC public keys."
         )
 
 
@@ -131,3 +167,22 @@ def rsa_pem_from_n_and_e(n: str, e: str) -> bytes:
             format=serialization.PublicFormat.SubjectPublicKeyInfo,
         )
     )
+
+
+def ec_pem_from_x_y_crv(x: str, y: str, crv: str) -> bytes:
+    curve_cls = _EC_CURVES.get(crv)
+    if curve_cls is None:
+        raise ValueError(
+            f"Unsupported EC curve: {crv!r}. "
+            f"Supported curves: {', '.join(_EC_CURVES)}."
+        )
+    x_int = _decode_value(x)
+    y_int = _decode_value(y)
+    return (
+        EllipticCurvePublicNumbers(x=x_int, y=y_int, curve=curve_cls())
+        .public_key(default_backend())
+        .public_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PublicFormat.SubjectPublicKeyInfo,
+        )
+    )