JSON::WebToken - JSON Web Token (JWT) implementation

NAME SYNOPSIS DESCRIPTION METHODS encode($claims [, $secret, $algorithm, $extra_headers ]) : String decode($jwt [, $secret, $verify_signature, $accepted_algorithms ]) : HASH add_signing_algorithm($algorithm, $class) FUNCTIONS encode_jwt($claims [, $secret, $algorithm, $extra_headers ]) : String decode_jwt($jwt [, $secret, $verify_signature, $accepted_algorithms ]) :Hash ERROR CODES ERROR_JWT_INVALID_PARAMETER ERROR_JWT_MISSING_SECRET ERROR_JWT_INVALID_SEGMENT_COUNT ERROR_JWT_INVALID_SEGMENT_ENCODING ERROR_JWT_UNWANTED_SIGNATURE ERROR_JWT_INVALID_SIGNATURE ERROR_JWT_NOT_SUPPORTED_SIGNING_ALGORITHM ERROR_JWT_UNACCEPTABLE_ALGORITHM AUTHOR COPYRIGHT LICENSE SEE ALSO

NAME

JSON::WebToken − JSON Web Token (JWT) implementation

use Test::More;
use JSON;
use JSON::WebToken;
my $claims = {
iss => 'joe',
exp => 1300819380,
'http://example.com/is_root' => JSON::true,
};
my $secret = 'secret';
my $jwt = encode_jwt $claims, $secret;
my $got = decode_jwt $jwt, $secret;
is_deeply $got, $claims;
done_testing;

DESCRIPTION

JSON::WebToken is JSON Web Token (JWT) implementation for Perl

THIS MODULE IS ALPHA LEVEL INTERFACE.

METHODS

encode($claims [, $secret, $algorithm, $extra_headers ]) : String

This method is encoding JWT from hash reference.

my $jwt = JSON::WebToken−>encode({
iss => 'joe',
exp => 1300819380,
'http://example.com/is_root' => JSON::true,
}, 'secret');
# $jwt = join '.',
# 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9',
# 'eyJleHAiOjEzMDA4MTkzODAsImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlLCJpc3MiOiJqb2UifQ'
# '4ldFxjibgJGz_uaIRCIq89b5ipR−sbI2Uq7B2WNEDs0'

Default encryption algorithm is "HS256". You can change algorithm as following:

my $pricate_key_string = '...';
my $public_key_string = '...';
my $jwt = JSON::WebToken−>encode({
iss => 'joe',
exp => 1300819380,
'http://example.com/is_root' => JSON::true,
}, $pricate_key_string, 'RS256');
my $claims = JSON::WebToken−>decode($jwt, $public_key_string);

When you use RS256, RS384 or RS512 algorithm then, We need Crypt::OpenSSL::RSA.

If you want to create a "Plaintext JWT", should be specify "none" for the algorithm.

my $jwt = JSON::WebToken−>encode({
iss => 'joe',
exp => 1300819380,
'http://example.com/is_root' => JSON::true,
}, '', 'none');
# $jwt = join '.',
# 'eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0',
# 'eyJleHAiOjEzMDA4MTkzODAsImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlLCJpc3MiOiJqb2UifQ',
# ''

decode($jwt [, $secret, $verify_signature, $accepted_algorithms ]) : HASH

This method is decoding hash reference from JWT string.

my $claims = JSON::WebToken−>decode($jwt, $secret, 1, ["RS256"]);

Any signing algorithm (except "none") is acceptable by default, so you should check it with $accepted_algorithms parameter.

add_signing_algorithm($algorithm, $class)

This method is adding signing algorithm.

# resolve JSON::WebToken::Crypt::MYALG
JSON::WebToken−>add_signing_algorithm('MYALGXXX' => 'MYALG');
# resolve Some::Class::Algorithm
JSON::WebToken−>add_signing_algorithm('SOMEALGXXX' => '+Some::Class::Algorithm');

SEE ALSO JSON::WebToken::Crypt::HMAC or JSON::WebToken::Crypt::RAS.

FUNCTIONS

encode_jwt($claims [, $secret, $algorithm, $extra_headers ]) : String

Same as encode() method.

decode_jwt($jwt [, $secret, $verify_signature, $accepted_algorithms ]) :Hash

Same as decode() method.

ERROR CODES

JSON::WebToken::Exception will be thrown with following code.

ERROR_JWT_INVALID_PARAMETER

When some method arguments are not valid.

ERROR_JWT_MISSING_SECRET

When secret is required. ("alg != "none"")

ERROR_JWT_INVALID_SEGMENT_COUNT

When JWT segment count is not between 2 and 4.

ERROR_JWT_INVALID_SEGMENT_ENCODING

When each JWT segment is not encoded by base64url.

ERROR_JWT_UNWANTED_SIGNATURE

When "alg == "none"" but signature segment found.

ERROR_JWT_INVALID_SIGNATURE

When JWT signature is invalid.

ERROR_JWT_NOT_SUPPORTED_SIGNING_ALGORITHM

When given signing algorithm is not supported.

ERROR_JWT_UNACCEPTABLE_ALGORITHM

When given signing algorithm is not included in acceptable_algorithms.