/ 
Crypt-JWS-OpenSSL-0.003
/ Crypt::JWS::OpenSSL::Algorithm::RSA

NAME

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

VERSION

version 0.003

SYNOPSIS

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

my $token = $jws->sign(
  algorithm => 'RS256',
  key       => $rsa_private_key_pem_content,
  message   => join('.', $base64urlEncodedHeader, $base64urlEncodedClaims),
);
  
my $is_verified = $jws->verify(
  algorithm => 'RS256',
  key       => $rsa_public_key_pem_content,
  message   => join('.', $base64urlEncodedHeader, $base64urlEncodedClaims),
  signature => $base64urlDecodedSignature,
);

DESCRIPTION

This module uses Crypt::OpenSSL::RSA to sign and verify JWTs using RSA 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
);

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

algorithm

The name of the algorithm supported by the key parameter.

key

The pem encoded RSA 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 ).

The final token is produced by Base64 encoding the 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 RSA public 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.

can_use_pkcs1_padding

if( $jws->can_use_pkcs1_padding ) {
  .......
}

The method returns true if RSASSA-PKCS-v1_5 padding is supported by your version of Crypt::OpenSSL::RSA.

RSA signatures can use two types of padding, RSASSA-PKCS-v1_5 and RSASSA-PSS.

Algorithms RS256, RS384 and RS512 use RSASSA-PKCS-v1_5 padding.

Unless you have Crypt::OpenSSL::RSA versions 0.36 or 0.37, you will be able to sign and verify tokens using these algorithms.

can_use_pkcs1_pss_padding

if( $jws->can_use_pkcs1_pss_padding ) {
  .......
}

The method returns true if RSASSA-PSS padding is supported by your version of Crypt::OpenSSL::RSA and OpenSSL

RSA signatures can use two types of padding, RSASSA-PKCS-v1_5 and RSASSA-PSS.

Algorithms PS256, PS384 and PS512 use RSASSA-PSS.

You need Crypt::OpenSSL::RSA versions >= 0.38 and OpenSSL 3 to sign and verify tokens using these algorithms.

ALGORITHMS

RS256

RSASSA-PKCS-v1_5 using SHA-256

RS384

RSASSA-PKCS-v1_5 using SHA-384

RS512

RSASSA-PKCS-v1_5 using SHA-512

PS256

RSASSA-PSS using SHA-256 and MGF1 with SHA-256

Needs Crypt::OpenSSL::RSA versions >= 0.38 and OpenSSL 3

PS384

RSASSA-PSS using SHA-384 and MGF1 with SHA-384

Needs Crypt::OpenSSL::RSA versions >= 0.38 and OpenSSL 3

PS512

RSASSA-PSS using SHA-512 and MGF1 with SHA-512

Needs Crypt::OpenSSL::RSA versions >= 0.38 and OpenSSL 3

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.