Context
ES256K (ECDSA over secp256k1 with SHA-256) is registered by RFC 8812 (August 2020) — alg ES256K and crv secp256k1 in the JOSE registries, "Optional" implementation requirement — and has been "Standards Track" for six years. The library still ships it in the experimental package (src/Experimental/Signature/ES256K.php, Jose\Experimental\Signature\ES256K, registered by signature_experimental.php in the bundle) next to the WebCrypto-only identifiers (RS1, HS1, A*CTR…) that have no RFC. The Experimental label tells users the algorithm may change or go away; RFC 8812 says the opposite.
secp256k1 has full support in the core already: Jose\Component\Core\Util\Ecc knows the curve, ECKey builds it, ES256KeyAnalyzer-style checks exist. Only the algorithm class and its bundle registration are misplaced.
The move is a namespace change, so a BC break for anyone type-hinting or instantiating Jose\Experimental\Signature\ES256K — 5.0.0 material, listed in #717.
Scope
Jose\Component\Signature\Algorithm\ES256K in src/Library/Signature/Algorithm/, extending ECDSA like ES256 / ES384 / ES512; signature_ecdsa.php registers it in the bundle alongside its siblings.
- In 4.3.x (preparation, no break): keep the experimental class as a thin
@deprecated subclass / alias of the new one so both FQCNs resolve to the same service; the bundle registers the algorithm once under the alias ES256K.
- In 5.0.0: delete
Jose\Experimental\Signature\ES256K, drop it from signature_experimental.php and from the jwt-experimental split's composer.json description.
- Key analyzer: an
ES256KKeyAnalyzer (secp256k1 coordinates length, alg consistency) where ES256KeyAnalyzer lives, if not already present under another name.
- Docs:
ES256K moves from the experimental table to the standard signature table, with the RFC 8812 reference and the known limitation that a secp256k1 key exported to PEM cannot be loaded back through KeyConverter on some OpenSSL builds (documented rather than fixed here); changelog and the 5.0.0 upgrade guide.
Out of scope
- The WebCrypto-only algorithms (
RS1, HS1, RSA-OAEP-384/512, A*CTR, A*CBC): no RFC, they stay experimental.
- Fixing the secp256k1 PEM round-trip.
Acceptance criteria
- RFC 8812 §3 sign / verify through
JWSBuilder / JWSVerifier with the new FQCN, all three serializations; the existing ES256K tests pass unchanged after the namespace swap.
- 4.3.x: a service definition referencing the old FQCN still compiles and produces the same algorithm; a deprecation is triggered at instantiation.
- 5.0.0: the old FQCN is gone,
grep -r 'Experimental\\Signature\\ES256K' returns nothing in src/, docs and bundle config.
References
Context
ES256K(ECDSA over secp256k1 with SHA-256) is registered by RFC 8812 (August 2020) —algES256Kandcrvsecp256k1in the JOSE registries, "Optional" implementation requirement — and has been "Standards Track" for six years. The library still ships it in the experimental package (src/Experimental/Signature/ES256K.php,Jose\Experimental\Signature\ES256K, registered bysignature_experimental.phpin the bundle) next to the WebCrypto-only identifiers (RS1,HS1,A*CTR…) that have no RFC. TheExperimentallabel tells users the algorithm may change or go away; RFC 8812 says the opposite.secp256k1 has full support in the core already:
Jose\Component\Core\Util\Eccknows the curve,ECKeybuilds it,ES256KeyAnalyzer-style checks exist. Only the algorithm class and its bundle registration are misplaced.The move is a namespace change, so a BC break for anyone type-hinting or instantiating
Jose\Experimental\Signature\ES256K— 5.0.0 material, listed in #717.Scope
Jose\Component\Signature\Algorithm\ES256Kinsrc/Library/Signature/Algorithm/, extendingECDSAlikeES256/ES384/ES512;signature_ecdsa.phpregisters it in the bundle alongside its siblings.@deprecatedsubclass / alias of the new one so both FQCNs resolve to the same service; the bundle registers the algorithm once under the aliasES256K.Jose\Experimental\Signature\ES256K, drop it fromsignature_experimental.phpand from thejwt-experimentalsplit'scomposer.jsondescription.ES256KKeyAnalyzer(secp256k1 coordinates length,algconsistency) whereES256KeyAnalyzerlives, if not already present under another name.ES256Kmoves from the experimental table to the standard signature table, with the RFC 8812 reference and the known limitation that a secp256k1 key exported to PEM cannot be loaded back throughKeyConverteron some OpenSSL builds (documented rather than fixed here); changelog and the 5.0.0 upgrade guide.Out of scope
RS1,HS1,RSA-OAEP-384/512,A*CTR,A*CBC): no RFC, they stay experimental.Acceptance criteria
JWSBuilder/JWSVerifierwith the new FQCN, all three serializations; the existing ES256K tests pass unchanged after the namespace swap.grep -r 'Experimental\\Signature\\ES256K'returns nothing insrc/, docs and bundle config.References