/ 
Crypt-JWT-Tiny-0.002
/ Crypt::JWT::Tiny

NAME

Crypt::JWT::Tiny - A small HMAC-only JWT implementation

VERSION

version 0.002

SYNOPSIS

# encoding
use Crypt::JWT::Tiny 'encode_jwt';
my $jws_token = encode_jwt(claims => $data, alg => 'HS256', key => $secret);

# decoding
use Crypt::JWT::Tiny 'decode_jwt';
my $claims = decode_jwt(token => $jws_token, alg => 'HS256', key => $secret);

DESCRIPTION

This is a tiny JWT implementation. It only depends on core modules, and as such can only support the HMAC algorithms (HS256, HS384 and HS512). If you need more than that, I recommend looking for a more complete implementation of JWT.

FUNCTIONS

encode_jwt

Returns the encoded JWT as a string using the compact serialization format. Croaks on bad arguments or unsupported algorithm. It takes the following named arguments

claims

Mandatory. It takes a hash ref of claims that will be JSON serialized.

my %claims = (iss => 'me', aud => 'you', sub => 'him');
my $token = encode_jwt(claims => \%claims, key => $k, alg => 'HS256');
alg

Mandatory. The algorithm used to sign the token. Three values are currently supported:

  • HS256

    HMAC using SHA-256

  • HS384

    HMAC using SHA-384

  • HS512

    HMAC using SHA-512

key

Mandatory. The secret key used to sign the token. This must be a binary string. It is required to be at least as long as the hash output (e.g. 32 bytes for SHA-256).

kid

The key identifier. If any is given this will be added to the token's header.

typ

The type of the token. If any is given (typically JWT), it will be added to the token's header.

relative_exp

Set the exp (Expiration Time) claim to current time + relative_exp value (in seconds). This will not overwrite an existing value.

It is highly recommended to either add an exp expiration time using relative_exp or add an iat and check with max_age.

relative_nbf

Set the nbf (Not Before) claim to current time + relative_nbf value (in seconds). This will not overwrite an existing value.

auto_iat

This will automatically add an iat (creation time) value to the claims. This will overwrite an existing value.

decode_jwt

This decodes a JWT to a hashref of claims, or croaks when any error is encountered.

It will automatically verify exp and nbf, and on request also iss, aud, typ and iat.

token

Mandatory. The token to be decoded.

alg

Mandatory. The algorithm used to verify the token. This is either a string, or a array ref of strings.

key

Mandatory. The secret key used to verify the token. This must either be a binary string, or a function reference to a function that is passed the (decoded) headers as a hash and must return the appropriate key. One should note that the input values should be treated as coming from an untrusted source.

iss

This will check if the passed issuer equals the received issuer.

aud

This will check if passed audience is listed among the received audiences.

typ

The type of the token. If any is given (typically JWT, or at+jwt for access tokens), it must match the value in the token. It is matched case-insensitively.

max_age

If given, the token must contain an iat claim and be no older than this many seconds (plus leeway).

leeway

Number of seconds of clock skew to tolerate when checking timestamps. Defaults to 0.

AUTHOR

Leon Timmermans <fawaka@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Leon Timmermans.

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