feat(jwk): add derive_key method for ECKey

Author: lepture

pyproject.toml

@@ -3,7 +3,7 @@ name = "joserfc"
 description = "The ultimate Python library for JOSE RFCs, including JWS, JWE, JWK, JWA, JWT"
 authors = [{name = "Hsiaoming Yang", email="[email protected]"}]
 dependencies = [
-    "cryptography",
+    "cryptography>=45.0.1",
 ]
 license = {text = "BSD-3-Clause"}
 requires-python = ">=3.9"

src/joserfc/_rfc7518/ec_key.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 import typing as t
 from functools import cached_property
+from cryptography.hazmat.primitives import hashes
 from cryptography.hazmat.primitives.asymmetric.ec import (
     generate_private_key,
+    derive_private_key,
     ECDH,
     EllipticCurvePublicKey,
     EllipticCurvePrivateKey,
@@ -13,12 +15,13 @@
     SECP384R1,
     SECP521R1,
 )
-from cryptography.hazmat.backends import default_backend
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
 from ..errors import InvalidExchangeKeyError, InvalidKeyCurveError
 from .._rfc7517.models import CurveKey
 from .._rfc7517.pem import CryptographyBinding
 from .._rfc7517.types import KeyParameters, AnyKey
-from ..util import base64_to_int, int_to_base64
+from ..util import base64_to_int, int_to_base64, to_bytes
 from ..registry import KeyParameter
 
 __all__ = ["ECKey"]
@@ -51,14 +54,10 @@ def register_curve(cls, name: str, curve: t.Type[EllipticCurve]) -> None:
     @classmethod
     def generate_private_key(cls, name: str) -> EllipticCurvePrivateKey:
         if name not in cls._dss_curves:
-            raise InvalidKeyCurveError("Invalid crv value: '{}'".format(name))
+            raise InvalidKeyCurveError(f"Invalid crv value: '{name}'")
 
         curve = cls._dss_curves[name]()
-        raw_key = generate_private_key(
-            curve=curve,
-            backend=default_backend(),
-        )
-        return raw_key
+        return generate_private_key(curve=curve)
 
     @classmethod
     def import_private_key(cls, obj: ECDictKey) -> EllipticCurvePrivateKey:
@@ -70,7 +69,7 @@ def import_private_key(cls, obj: ECDictKey) -> EllipticCurvePrivateKey:
         )
         d = base64_to_int(obj["d"])
         private_numbers = EllipticCurvePrivateNumbers(d, public_numbers)
-        return private_numbers.private_key(default_backend())
+        return private_numbers.private_key()
 
     @classmethod
     def export_private_key(cls, key: EllipticCurvePrivateKey) -> ECDictKey:
@@ -90,7 +89,7 @@ def import_public_key(cls, obj: ECDictKey) -> EllipticCurvePublicKey:
             base64_to_int(obj["y"]),
             curve,
         )
-        return public_numbers.public_key(default_backend())
+        return public_numbers.public_key()
 
     @classmethod
     def export_public_key(cls, key: EllipticCurvePublicKey) -> ECDictKey:
@@ -102,6 +101,13 @@ def export_public_key(cls, key: EllipticCurvePublicKey) -> ECDictKey:
         }
 
 
+# register default curves with their DSS (Digital Signature Standard) names
+# https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf
+ECBinding.register_curve("P-256", SECP256R1)
+ECBinding.register_curve("P-384", SECP384R1)
+ECBinding.register_curve("P-521", SECP521R1)
+
+
 class ECKey(CurveKey[EllipticCurvePrivateKey, EllipticCurvePublicKey]):
     key_type = "EC"
     #: Registry definition for EC Key
@@ -175,20 +181,85 @@ def generate_key(
         """
         if crv is None:
             crv = "P-256"
-
         raw_key = cls.binding.generate_private_key(crv)
-        if private:
-            key = cls(raw_key, raw_key, parameters)
+        return _wrap_key(cls, raw_key, private, auto_kid, parameters)
+
+    @classmethod
+    def derive_key(
+        cls: t.Type["ECKey"],
+        secret: bytes | str,
+        crv: str = "P-256",
+        parameters: KeyParameters | None = None,
+        private: bool = True,
+        auto_kid: bool = False,
+        kdf_name: t.Literal["HKDF", "PBKDF2"] = "HKDF",
+        kdf_options: dict[str, t.Any] | None = None,
+    ) -> "ECKey":
+        """
+        Generate an elliptic curve cryptographic key derived from a secret input using a key
+        derivation function (KDF). This allows the creation of deterministic elliptic curve
+        keys based on given input data, curve specification, and KDF options.
+
+        :param secret: The input secret used for key derivation
+        :param crv: ECKey curve name
+        :param parameters: extra parameter in JWK
+        :param private: generate a private key or public key
+        :param auto_kid: add ``kid`` automatically
+        :param kdf_name: Key derivation function name
+        :param kdf_options: Additional options for the KDF
+        """
+        try:
+            curve_class = cls.binding._dss_curves[crv]
+        except KeyError:
+            raise InvalidKeyCurveError(f"Invalid crv value: '{crv}'")
+
+        curve = curve_class()
+        length = (curve.group_order.bit_length() + 7) // 8 * 2
+
+        if kdf_options is None:
+            kdf_options = {}
+
+        algorithm = kdf_options.pop("algorithm", None)
+        if algorithm is None:
+            algorithm = hashes.SHA256()
+
+        kdf_options.setdefault("salt", to_bytes(f"joserfc:EC:{kdf_name}:{crv}"))
+        if kdf_name == "HKDF":
+            kdf_options.setdefault("info", b"")
+            hkdf = HKDF(
+                algorithm=algorithm,
+                length=length,
+                **kdf_options,
+            )
+            seed = hkdf.derive(to_bytes(secret))
+        elif kdf_name == "PBKDF2":
+            kdf_options.setdefault("iterations", 100000)
+            pbkdf2 = PBKDF2HMAC(
+                algorithm=algorithm,
+                length=length,
+                **kdf_options,
+            )
+            seed = pbkdf2.derive(to_bytes(secret))
         else:
-            pub_key = raw_key.public_key()
-            key = cls(pub_key, pub_key, parameters)
-        if auto_kid:
-            key.ensure_kid()
-        return key
+            raise ValueError(f"Invalid kdf value: '{kdf_name}'")
 
+        d = int.from_bytes(seed, "big") % curve.group_order
+        raw_key = derive_private_key(d, curve)
+        return _wrap_key(cls, raw_key, private, auto_kid, parameters)
 
-# register default curves with their DSS (Digital Signature Standard) names
-# https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf
-ECBinding.register_curve("P-256", SECP256R1)
-ECBinding.register_curve("P-384", SECP384R1)
-ECBinding.register_curve("P-521", SECP521R1)
+
+def _wrap_key(
+    cls: t.Type["ECKey"],
+    raw_key: EllipticCurvePrivateKey,
+    private: bool,
+    auto_kid: bool,
+    parameters: KeyParameters | None = None,
+) -> ECKey:
+    if private:
+        key = cls(raw_key, raw_key, parameters)
+    else:
+        pub_key = raw_key.public_key()
+        key = cls(pub_key, pub_key, parameters)
+    if auto_kid:
+        key.ensure_kid()
+    return key

src/joserfc/_rfc8037/okp_key.py

@@ -261,7 +261,7 @@ def derive_key(
                 }
             )
 
-        :param secret: The input secret used for key derivation.
+        :param secret: The input secret used for key derivation
         :param crv: OKPKey curve name
         :param parameters: extra parameter in JWK
         :param private: generate a private key or public key

tests/jwk/test_ec_key.py

@@ -1,4 +1,5 @@
 from unittest import TestCase
+from cryptography.hazmat.primitives import hashes
 from joserfc.jwk import ECKey, OctKey
 from joserfc.errors import (
     InvalidExchangeKeyError,
@@ -97,3 +98,34 @@ def test_key_eq(self):
 
     def test_key_eq_with_different_types(self):
         self.assertNotEqual(self.default_key, OctKey.generate_key())
+
+    def test_derive_key_errors(self):
+        self.assertRaises(InvalidKeyCurveError, ECKey.derive_key, "secret", "invalid")
+        self.assertRaises(ValueError, ECKey.derive_key, "secret", kdf_name="invalid")
+
+    def test_derive_key_with_default_kwargs(self):
+        key1 = ECKey.derive_key("ec-secret-key")
+        key2 = ECKey.derive_key("ec-secret-key")
+        self.assertEqual(key1, key2)
+
+        for crv in ["P-256", "P-384", "P-521", "secp256k1"]:
+            key1 = ECKey.derive_key("ec-secret-key", crv)
+            key2 = ECKey.derive_key("ec-secret-key", crv)
+            self.assertEqual(key1, key2)
+
+        for crv in ["P-256", "P-384", "P-521", "secp256k1"]:
+            key1 = ECKey.derive_key("ec-secret-key", crv, kdf_name="PBKDF2")
+            key2 = ECKey.derive_key("ec-secret-key", crv, kdf_name="PBKDF2")
+            self.assertEqual(key1, key2)
+
+    def test_derive_key_with_new_salt(self):
+        curves = ["P-256", "P-384", "P-521", "secp256k1"]
+        for crv in curves:
+            key1 = ECKey.derive_key("ec-secret-key", crv, kdf_options={"salt": b"salt"})
+            key2 = ECKey.derive_key("ec-secret-key", crv, kdf_options={"salt": b"salt"})
+            self.assertEqual(key1, key2)
+
+    def test_derive_key_with_different_hash(self):
+        key1 = ECKey.derive_key("ec-secret-key", "P-256", kdf_options={"algorithm": hashes.SHA256()})
+        key2 = ECKey.derive_key("ec-secret-key", "P-256", kdf_options={"algorithm": hashes.SHA512()})
+        self.assertNotEqual(key1, key2)