enhancement: port CryptX cryptographic toolkit

[fglock]

Summary

Port the CPAN CryptX distribution to PerlOnJava so Perl code that depends on its cryptographic APIs can run without native XS code.

Motivation

CryptX is currently a major compatibility blocker for PerlOnJava applications using JWT, OAuth, OpenID Connect, SAML, XML signatures, ACME, encrypted credentials, and related protocols.

The immediate observed case is WebService::GoogleAPI::Client 0.27. Its dependency chain includes Mojo::JWT, which directly loads CryptX for JWT signing and verification. PerlOnJava's CPAN installer reports that CryptX contains XS/C code and cannot compile it. The resulting module load failure aborts all three upstream test programs before any subtests run.

CryptX also has a substantial reverse-dependency surface. Examples include Mojo::JWT, Crypt::JWT, XML::Sig, Net::SAML2, OIDC::Client, Net::ACME2, Net::SSH::Perl, KeePass::Reader, and encryption/database modules.

Proposed scope

Implement the Perl-facing CryptX API using Java-backed cryptography while preserving the upstream module names and behavior wherever practical.

At minimum, investigate and support the APIs required by Mojo::JWT:

• Crypt::Misc base64url helpers
• HMAC signing and verification used by HS JWT algorithms
• RSA signing and verification used by RS JWT algorithms
• key and digest handling needed by the supported JWT algorithms

Then expand coverage to the rest of the distribution's public families as feasible:

• Crypt::Digest::*
• Crypt::Mac::*
• Crypt::Cipher::* and Crypt::Mode::*
• Crypt::AuthEnc::*
• Crypt::PK::*
• Crypt::KeyDerivation
• Crypt::PRNG
• Crypt::Misc
• Crypt::ASN1

The implementation should use Java standard cryptography or existing project dependencies where they provide compatible primitives. It should not silently downgrade security or change algorithm semantics. Algorithms unavailable from the Java provider should fail explicitly and consistently with the Perl API.

Suggested approach

1. Obtain and inspect the upstream CryptX Perl and XS/C sources, preserving license and attribution.
2. Separate the pure-Perl wrappers and constants from the XS entry points.
3. Implement the required XS-facing methods in Java, using existing PerlOnJava module registration patterns.
4. Prefer standard Java cryptographic providers and well-defined encoding behavior.
5. Add a bundled module test suite derived from the upstream tests, beginning with the JWT-required surface.
6. Compare every new test with native system Perl before using it as a compatibility oracle.
7. Verify both JVM and interpreter backends.
8. Test downstream modules, especially Mojo::JWT, Mojo::JWT::Google, and WebService::GoogleAPI::Client.

Acceptance criteria

• use CryptX, use Crypt::Misc, and the JWT-required CryptX modules load under both PerlOnJava backends.
• Mojo::JWT can create and verify representative HS256 tokens with matching system-Perl results.
• Supported RSA JWT operations have matching system-Perl results, including invalid-signature rejection.
• Base64url encoding/decoding handles padding, empty values, binary data, and malformed input consistently.
• Upstream or focused bundled tests cover success cases, malformed inputs, wrong keys, wrong algorithms, and context-sensitive return values.
• WebService::GoogleAPI::Client no longer aborts at module load solely because CryptX is unavailable.
• Unsupported algorithms are reported clearly rather than producing incorrect cryptographic results.
• No native XS compilation is required for the supported port.

Related evidence

The CPAN tester failure is the WebService::GoogleAPI::Client 0.27 failure observed on 2026-09-02. Native system Perl can load CryptX and Mojo::JWT when the XS distribution is installed, while the PerlOnJava CPAN build explicitly skips CryptX's XS/C compilation.

References

• https://metacpan.org/dist/CryptX
• https://metacpan.org/dist/CryptX/requires
• https://metacpan.org/dist/Mojo-JWT