JSON::WebToken(3pm)   User Contributed Perl Documentation  JSON::WebToken(3pm)


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

SYNOPSIS
         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.

AUTHOR
       xaicron <xaicron@cpan.org>

       zentooo

COPYRIGHT
       Copyright 2012 - xaicron

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

SEE ALSO
       <http://tools.ietf.org/html/draft-ietf-oauth-json-web-token>

perl v5.38.0                      2023-07-26               JSON::WebToken(3pm)