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.

   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>

DEVELOPMENT SPONSORED BY

       Restore Health Corporation, <http://restorehc.com>

AUTHOR

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

COPYRIGHT AND LICENSE

       Copyright (C) 2015 by Joel Berger

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