NAME

Crypt::JWS::OpenSSL::Algorithm::ECC - Sign and verify tokens using ECDSA algorithms

VERSION

version 0.003

SYNOPSIS

use Crypt::JWS::OpenSSL::Algorithm::ECC;
my $jws = Crypt::JWS::OpenSSL::Algorithm::ECC->new;

my $token_1 = $jws->sign(
  algorithm => 'ES384',
  key       => $secp384r1_private_key_pem_content,
  message   => join('.', $base64urlEncodedHeader, $base64urlEncodedClaims),
);

my $token2 = $jws->sign(
  algorithm     => 'ES256',
  key           => $prime256v1_private_key_pem_content,
  message       => join('.', $base64urlEncodedHeader, $base64urlEncodedClaims),
  deterministic => 1
);

my $is_verified_1 = $jws->verify(
  algorithm => 'ES384',
  key       => $secp384r1_public_key_pem_content,
  message   => join('.', $base64urlEncodedHeader, $base64urlEncodedClaims),
  signature => $base64urlDecodedSignature,
);

my $is_verified_2 = $jws->verify(
  algorithm => 'ES256',
  key       => $prime256v1_public_key_pem_content,
  message   => join('.', $base64urlEncodedHeader, $base64urlEncodedClaims),
  signature => $base64urlDecodedSignature,
);

DESCRIPTION

This module uses Crypt::OpenSSL::ECDSA in combination with Crypt::OpenSSL::EC to sign and verify JWTs using elliptic curve digital signatures.

It is used within Crypt::JWS::OpenSSL but it can be used directly if you handle the Base64 url encoding and decoding elswhere.

METHODS

sign

my $token = $jwt->sign(
  algorithm => $algo,
  key       => $key,
  message   => $message
);

my $token_2 = $jwt->sign(
  algorithm         => $algo,
  key               => $key,
  message           => $message,
  non_deterministic => 1,
);

The method accepts an even numbered list or a hash reference. It returns a signature.

By default, the deterministic signing method is used.

algorithm

The name of the algorithm supported by the key parameter.

key

The pem encoded ECDSA private key or a hash reference containing a JWK.

It is more efficient to convert a JWK to a pem encoded key and use that for signing.

See Crypt::JWS::OpenSSL::Util::JWK

message

The Base64 url encoded JSON header and the Base64 url encoded JSON claims joined together with a '.' ( dot ).

non_deterministic

Set this value to 1 to sign using the non-deterministic method.

ECDSA signatures can created using either randomly generated parameters ( non-deterministic ) or calculating parameters from message content and the private key ( deterministic ).

The difference between non-deterministic and deterministic ECDSA signatures lies in how they generate a critical single-use nonce.

Non-deterministic (classic) ECDSA is notoriously fragile because it relies on a perfect random number generator. If that generator fails and a nonce is ever repeated or guessed, an attacker can steal the private key instantly. Deterministic ECDSA (RFC 6979) solves this by deriving the nonce mathematically from the message and the private key, entirely removing the need for a live random number generator during signing.

The final token is produced by Base64 encoding the raw signature returned by this method and adding it to the message seperated by a '.' ( dot );

This method returns a raw signature.

verify

my $is_verified = $jwt->verify(
  algorithm => $algo,
  key       => $key,
  message   => $message,
  signature => $raw_signature
);

The method accepts an even numbered list or a hash reference.

It returns true if signature matches a signature produced for the message by key, or false if not.

algorithm

The name of the algorithm supported by the key parameter.

key

The pem encoded ECDSA private key or a hash reference containing a JWK.

It is more efficient to convert the JWK to a pem encoded key and store that if you expect to be verifying regularly with this public key.

See Crypt::JWS::OpenSSL::Util::JWK

message

The Base64 url encoded JSON header and the Base64 url encoded JSON claims joined together with a '.' ( dot ) extracted from a token.

signature

The Base64 url decoded raw signature extracted from the token.

ALGORITHMS

ES256

ECDSA using P-256 ( prime256v1 ) and SHA-256

ES384

ECDSA using P-384 ( secp384r1 ) and SHA-384

ES512

ECDSA using P-521 ( secp521r1 ) and SHA-512

AUTHOR

Mark Dootson <mdootson@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2026 by Mark Dootson

This library is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.