Skip to content

refactor(signature): move ES256K out of the experimental package (RFC 8812) #727

Description

@Spomky

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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions