NAME

   Mojo::JWT - JSON Web Token the Mojo way

SYNOPSIS

     my $jwt = Mojo::JWT->new(claims => {...}, secret => 's3cr3t')->encode;
     my $claims = Mojo::JWT->new(secret => 's3cr3t')->decode($jwt);

DESCRIPTION

   JSON Web Token is described in https://tools.ietf.org/html/rfc7519.
   Mojo::JWT implements that standard with an API that should feel
   familiar to Mojolicious users (though of course it is useful
   elsewhere). Indeed, JWT is much like Mojolicious::Sessions except that
   the result is a url-safe text string rather than a cookie.

   In JWT, the primary payload is called the claims, and a few claims are
   reserved, as seen in the IETF document. The header and the claims are
   signed when stringified to guard against tampering. Note that while
   signed, the data is not encrypted, so don't use it to send secrets over
   clear channels.

ATTRIBUTES

   Mojo::JWT inherits all of the attributes from Mojo::Base and implements
   the following new ones.

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 is an acceptable encoding algorithm, however for it to be used to
   decode, "allow_none" must be set.

allow_none

   To prevent spoofing attacks, allow_none must be explicitly set to a
   true value otherwise decoding a JWT which specifies the none algorithm
   will result in an exception. The default is of course false.

claims

   The payload to be encoded or else the claims from the most recent
   decoding. This must be a hash reference, array references are not
   allowed as the top-level JWT claims.

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 claims or was extracted from the claims during the most
   recent decoding.

header

   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.

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 claims or was extracted from the claims during the
   most recent decoding.

public

   The public key to be used in decoding an asymmetrically signed JWT (eg.
   RSA).

secret

   The symmetric secret (eg. HMAC) or else the private key used in
   encoding an asymmetrically signed JWT (eg. RSA).

set_iat

   If true (false by default), then the iat claim will be set to the value
   of "now" during "encode".

METHODS

   Mojo::JWT inherits all of the methods from Mojo::Base and implements
   the following new ones.

decode

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

     my $peek = sub { my ($jwt, $claims) = @_; ... };
     my $claims = $jwt->decode($token, $peek);

   Decode and parse a JSON Web Token string and return the claims hashref.
   Calling this function immediately sets the "token" to the passed in
   token. It also sets "algorithm" to undef and unsets "claims", "expires"
   and "not_before". These values are then set as part of the parsing
   process.

   Parsing occurs as follows

     * The "algorithm" is extracted from the header and set, if not
     present or permissible an exception is thrown

     * If a $peek callback is provided, it is called with the instance and
     claims as arguments

     * The signature is verified or an exception is thrown

     * The timing claims ("expires" and "not_before"), if present, are
     evaluated, failures result in exceptions. On success the values are
     set in the relevant attributes

     * The "claims" attribute is set and the claims are returned.

   Note that when the $peek callback is invoked, the claims have not yet
   been verified. This callback is most likely to be used to inspect the
   iss or issuer claim to determine a secret or key for decoding. The
   return value is ignored, changes should be made to the instances
   attributes directly. Since the "algorithm" has already been parsed, it
   is available via the instance attribute as well.

encode

     my $token = $jwt->encode;

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

   Note also that due to Perl's hash randomization, repeated encoding is
   not guaranteed to result in the same encoded string. However any
   encoded string will survive an encode/decode roundtrip.

header

     my $header = $jwt->header;

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

now

     my $time = $jwt->now;

   Returns the current time, currently implemented as the core time
   function.

sign_hmac

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

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

sign_rsa

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

   Returns the RSA signature for the given size and payload. The "secret"
   attribute is used as the private key. The result is not yet base64
   encoded. This method is provided mostly for the purposes of
   subclassing.

token

   The most recently encoded or decoded token. Note that any attribute
   modifications are not taken into account until "encode" is called
   again.

verify_rsa

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

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

SEE ALSO

   Acme::JWT

   JSON::WebToken

   http://jwt.io/

SOURCE REPOSITORY

   http://github.com/jberger/Mojo-JWT

AUTHOR

   Joel Berger, <[email protected]>

CONTRIBUTORS

   Christopher Raa (mishanti1)

COPYRIGHT AND LICENSE

   Copyright (C) 2015 by "AUTHOR" and "CONTRIBTORS".

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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.