The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
WWW-Suffit-1.08
River stage one • 7 direct dependents • 8 total dependents
++
/ WWW::Suffit::JWT

NAME

WWW::Suffit::JWT - JSON Web Token for Suffit authorization

SYNOPSIS

    use WWW::Suffit::JWT;

    my $jwt = WWW::Suffit::JWT->new(
        secret => "MySecret",
        payload => {foo => 'bar'},
    );
    my $token = $jwt->encode->token or die $jwt->error;
    my $payload = $jwt->decode($token)->payload;
    die $jwt->error if $jwt->error;

    use WWW::Suffit::RSA;
    my $rsa = WWW::Suffit::RSA->new(key_size => 1024);
    $rsa->keygen;
    my $private_key = $rsa->private_key;
    my $public_key = $rsa->public_key;
    my $jwt = WWW::Suffit::JWT->new(
        private_key => $private_key,
        payload => {foo => 'bar'},
        algorithm => 'RS512',
    );
    my $token = $jwt->encode->token or die $jwt->error;
    my $payload = $jwt->public_key($public_key)->decode($token)->payload;
    die $jwt->error if $jwt->error;

DESCRIPTION

JSON Web Token for Suffit authorization

This module based on Mojo::JWT

JSON Web Token is described in https://tools.ietf.org/html/rfc7519.

ATTRIBUTES

This class implements the following attributes

algorithm

The algorithm to be used to sign a JWT during encoding or else the algorithm that was used for the most recent decoding. Defaults to HS256 until a decode is performed.

    none    no integrity (NOTE: disabled for decode method)
    HS256   HMAC+SHA256 integrity
    HS384   HMAC+SHA384 integrity
    HS512   HMAC+SHA512 integrity
    RS256   RSA+PKCS1-V1_5 + SHA256 signature
    RS384   RSA+PKCS1-V1_5 + SHA384 signature
    RS512   RSA+PKCS1-V1_5 + SHA512 signature

NOTE! We recommend using RS512

error

    $jwt->error($new_error);
    my $error = $jwt->error;

Sets/gets the error string

expires

The epoch time value after which the JWT value should not be considered valid. This value (if set and not undefined) will be used as the exp key in the payload or was extracted from the payload during the most recent decoding.

Header - first part of JWT structure

You may set your own headers when encoding the JWT bypassing a hash reference to the "header" attribute. Please note that there are two default headers set. alg is set to the value of "algorithm" or 'HS256' and typ is set to 'JWT'. These cannot be overridden.

    my $header = $jwt->header;

Returns a hash reference representing the JWT header, constructed from instance attributes (see "algorithm").

iat

It is epoch time value that will be set as iat during "encode".

not_before

The epoch time value before which the JWT value should not be considered valid. This value (if set and not undefined) will be used as the nbf key in the payload or was extracted from the payload during the most recent decoding.

payload

Payload - second part of JWT structure

The payload is a user data structure to be encoded. This must be a hash reference only.

private_key

The RSA private key to be used in edcoding an asymmetrically signed JWT. See WWW::Suffit::RSA

public_key

The RSA public key to be used in decoding an asymmetrically signed JWT. See WWW::Suffit::RSA

secret

The symmetric secret used in encoding an symmetrically HMAC

token

The most recently encoded or decoded token.

    $jwt->token($new_token);
    my $token = $jwt->token;

Sets/gets the token

METHODS

This class inherits all of the methods from Mojo::Base and implements the following new ones

decode

    my $payload = $jwt->decode($token)->payload;

Decode and parse a JSON Web Token string and return the payload hashref (see "payload").

encode

    my $token = $jwt->encode->token;

Encode the data expressed in the instance attributes: "algorithm", "payload", "expires", "not_before". Note that if the timing attributes are given, they override existing keys in the "payload". Calling encode immediately clears the "token" and upon completion sets it to the result (See "token")

sign_hmac

    my $signature = $jwt->sign_hmac($size, $string);

Returns the HMAC SHA signature for the given size and string. The "secret" attribute is used as the symmetric key. The result is base64url encoded! This method is provided mostly for the purposes of subclassing.

sign_rsa

    my $signature = $jwt->sign_rsa($size, $string);

Returns the RSA signature for the given size and string. The "private_key" attribute is used as the private key. The result is base64url encoded! This method is provided mostly for the purposes of subclassing.

verify_hmac

    my $bool = $jwt->verify_hmac($size, $string, $signature);

Returns true if the given HMAC size algorithm validates the given string and signature. The "secret" attribute is used as the HMAC passphrase. The signature is base64url encoded! This method is provided mostly for the purposes of subclassing.

verify_rsa

    my $bool = $jwt->verify_rsa($size, $string, $signature);

Returns true if the given RSA size algorithm validates the given string and signature. The "public_key" attribute is used as the public key. The signature is base64url encoded! This method is provided mostly for the purposes of subclassing.

DEPENDENCIES

WWW::Suffit::RSA

HISTORY

See Changes file

TO DO

See TODO file

SEE ALSO

WWW::Suffit::RSA, Crypt::OpenSSL::RSA, Mojo::JWT, Acme::JWT, JSON::WebToken, https://jwt.io/

AUTHOR

Serż Minus (Sergey Lepenkov) https://www.serzik.com <abalama@cpan.org>

CONTRIBUTORS

Joel Berger, <joel.a.berger@gmail.com>

Christopher Raa (mishanti1)

Cameron Daniel (ccakes)

COPYRIGHT

Copyright (C) 1998-2023 D&D Corporation. All Rights Reserved

Copyright (C) 2023 by "CONTRIBTORS".

LICENSE

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

See LICENSE file and https://dev.perl.org/licenses/