feat(signature): move ES256K from the experimental package to the library (RFC 8812) - #736
Merged
Conversation
…rary (RFC 8812) ES256K - ECDSA over secp256k1 with SHA-256 - is registered by RFC 8812 since 2020, yet the library shipped it in the experimental package next to the WebCrypto-only identifiers that have no RFC. The "Experimental" label tells users the algorithm may change or go away; the RFC says the opposite. Jose\Component\Signature\Algorithm\ES256K now lives next to ES256, and the bundle registers it under the same "ES256K" alias. The experimental class survives until 5.0.0 as a deprecated subclass of the new one, its constructor raising the deprecation, so that instantiating it or type-hinting it keeps working; the library class is therefore not final, as Jose\Unsecured\Signature\None is not for the same reason. In the bundle the experimental service is kept, untagged and deprecated, for the applications that inject the old class: an alias to the new service would have handed them an object that is not an instance of the class they ask for. KoblitzCurve carries the secp256k1 parameters, which no Curve object described so far - only OpenSSL knew the curve, through its OID - so that ES256KKeyAnalyzer can check the keys the way the ES256 analyzer does. The 5.0.0 step, recorded in #717, is the deletion of the experimental class and its service. Closes #727
Spomky
force-pushed
the
feat/es256k-standard
branch
from
September 13, 2026 12:41
22b90d7 to
e4ab903
Compare
Spomky
added a commit
to web-token/jwt-doc
that referenced
this pull request
Sep 13, 2026
…FC 8812) (#54) web-token/jwt-framework#736 moves the algorithm to the library. The algorithm and curve tables gain the standard entry, the signature algorithms page a section with the "use" change and the secp256k1 PEM limitation, the experimental table loses the row, and the 4.2 → 4.3 guide carries the entry and the deprecation line; two older mentions of the experimental namespace are corrected.
38 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #727 — the 4.3 half (preparation, no break). The 5.0.0 half — deleting
Jose\Experimental\Signature\ES256Kand its service — goes to #717.What
ES256K(ECDSA over secp256k1 with SHA-256) has been registered by RFC 8812 since 2020 but was shipped in the experimental package.Jose\Component\Signature\Algorithm\ES256K extends ECDSA, next toES256. Not final — the deprecated experimental class extends it until 5.0.0, the same reasonJose\Unsecured\Signature\Noneis not final.Jose\Experimental\Signature\ES256Kbecomes an empty@deprecatedsubclass withtrigger_deprecationin the constructor (theNone/RSA15pattern). It is still anECDSAand aSignatureAlgorithm, and now also an instance of the library class.KoblitzCurve::secp256k1()(@internal): the SEC 2 parameters — noCurveobject described secp256k1 so far, only OpenSSL knew it through its OID. Generator-on-curve and the RFC test key are asserted.ES256KKeyAnalyzeronESKeyAnalyzer, wired in the bundle.signature_ecdsa.phpregisters the library class under theES256Kalias; insignature_experimental.phpthe old FQCN's service is kept, untagged and->deprecate()d, so thatJose\Experimental\Signature\ES256K $xstill autowires. A DI alias to the new service would have produced aTypeError(the library class is not an instance of the subclass). The algorithm is instantiated once by the manager; the deprecation only fires for whoever injects the old class.Acceptance criteria
JWSBuilder/JWSVerifier, compact/flattened/general ✔; the two existing ES256K vectors pass unchanged after the namespace swap ✔ (tests/SignatureAlgorithm/ECDSA/ES256KSignatureTest.php, moved fromExperimental/).DeprecatedES256KConsumerin the test bundle autowires the old class.ES256Kalias of the algorithm manager is served by the library class ✔.Backward compatibility
Reflection dump vs 4.3.x: additions only; the experimental class keeps its parents and interfaces. No behaviour change, one new deprecation.
QA
PHPUnit, ECS, Rector, Deptrac, PHPStan green; baseline +1 entry (constant access on the deprecated class in the config file, same pattern as
None/RSA15/EdDSA).Out of scope
The WebCrypto-only algorithms stay experimental; the secp256k1 PEM round-trip is documented, not fixed.
Documentation: web-token/jwt-doc.