/ 
Crypt-JWT-0.004
River stage two • 25 direct dependents • 29 total dependents
/ Crypt::JWT

NAME

Crypt::JWT - JSON Web Token (JWT, JWS, JWE) as defined by RFC7519, RFC7515, RFC7516

SYNOPSIS

# encoding
use Crypt::JWT qw(encode_jwt);
my $jws_token = encode_jwt(payload=>$data, alg=>'HS256', key=>'secret');
my $jwe_token = encode_jwt(payload=>$data, alg=>'A192GCMKW', enc=>'A192CBC_HS384', key=>'secret');

# decoding
use Crypt::JWT qw(decode_jwt);
my $data1 = decode_jwt(token=>$jws_token, key=>'secret');
my $data2 = decode_jwt(token=>$jwe_token, key=>'secret');

DESCRIPTION

BEWARE: experimental, unfinished, unstable, work in progress!!!

Implements JSON Web Token (JWT) - https://tools.ietf.org/html/rfc7519. The implementation covers not only JSON Web Signature (JWS) - https://tools.ietf.org/html/rfc7515, but also JSON Web Encryption (JWE) - https://tools.ietf.org/html/rfc7516.

The module implements all (100%) algorithms defined in https://tools.ietf.org/html/rfc7518 - JSON Web Algorithms (JWA).

FUNCTIONS

decode_jwt

my $data = decode_jwt(%named_args);

Named arguments:

  • token (mandatory)

    A string with either JWS or JWE JSON Web Token.

    ### JWS token example (3 segments)
$t="eyJhbGciOiJIUzI1NiJ9.dGVzdA.ujBihtLSr66CEWqN74SpLUkv28lra_CeHnxLmLNp4Jo";

### JWE token example (5 segments)
$t="eyJlbmMiOiJBMTI4R0NNIiwiYWxnIjoiQTEyOEtXIn0.UusxEbzhGkORxTRq0xkFKhvzPrXb9smw.VGfOuq0Fxt6TsdqLZUpnxw.JajIQQ.pkKZ7MHS0XjyGmRsqgom6w";

  • key (mostly mandatory)

    A key used for token decryption (JWE) or token signature validation (JWS). The value depends on alg token header value.

    JWS alg header      key value
------------------  ----------------------------------
none                no key required
HS256               string (raw octects) of any length
HS384               dtto
HS512               dtto
RS256               public RSA key, a string with PEM or DER or JSON/JWK key,
                    perl hash with JWK key, an instance of Crypt::PK::RSA or
                    Crypt::OpenSSL::RSA or Crypt::X509 or Crypt::OpenSSL::X509
RS384               public RSA key, see RS256
RS512               public RSA key, see RS256
PS256               public RSA key, see RS256
PS384               public RSA key, see RS256
PS512               public RSA key, see RS256
ES256               public ECC key, a string with PEM or DER or JSON/JWK key,
                    perl hash with JWK key, an instance of Crypt::PK::ECC
ES384               public ECC key, see ES256
ES512               public ECC key, see ES256

JWE alg header      key value
------------------  ----------------------------------
dir                 string (raw octects), length depends on 'enc' algorithm
A128KW              string (raw octects) 16 bytes
A192KW              string (raw octects) 24 bytes
A256KW              string (raw octects) 32 bytes
A128GCMKW           string (raw octects) 16 bytes
A192GCMKW           string (raw octects) 24 bytes
A256GCMKW           string (raw octects) 32 bytes
PBES2-HS256+A128KW  string (raw octects) of any length
PBES2-HS384+A192KW  string (raw octects) of any length
PBES2-HS512+A256KW  string (raw octects) of any length
RSA-OAEP            private RSA key, a string with PEM or DER or JSON/JWK key,
                    perl hash with JWK key, an instance of Crypt::PK::RSA or
                    Crypt::OpenSSL::RSA
RSA-OAEP-256        private RSA key, see RSA-OAEP
RSA1_5              private RSA key, see RSA-OAEP
ECDH-ES             private ECC key, a string with PEM or DER or JSON/JWK key,
                    perl hash with JWK key, an instance of Crypt::PK::ECC
ECDH-ES+A128KW      private ECC key, see ECDH-ES
ECDH-ES+A192KW      private ECC key, see ECDH-ES
ECDH-ES+A256KW      private ECC key, see ECDH-ES

  • keypass (optional, default: undef)

    When 'key' parameter is an encrypted private RSA or ECC key this parameter may contain a password for private key decryption.

  • allow_none (optional, default: 0)

    1 - accept JWS tokens with none 'alg' header value (which means that token has no signature), BEWARE: DANGEROUS, UNSECURE!!!

    0 - do not allow JWS with none 'alg' header value

  • ignore_signature (optional, default: 0)

    1 - do not check signature on JWS tokens, BEWARE: DANGEROUS, UNSECURE!!!

    0 - check signature on JWS tokens

  • accepted_alg (optional, default: undef)

    undef means accept all 'alg' algorithms except 'none' (for accepting 'none' use allow_none)

    string name of accepted 'alg' algorithm (only one)

    ARRAY ref a list of accepted 'alg' algorithms

    Regexp that has to match 'alg' algorithm name

    my $payload = decode_jwt(token=>$t, key=>$k, accepted_enc=>'HS256');
#or
my $payload = decode_jwt(token=>$t, key=>$k, accepted_enc=>['HS256','HS384']);
#or
my $payload = decode_jwt(token=>$t, key=>$k, accepted_enc=>qr/^HS(256|384|512)$/);

  • accepted_enc (optional, default: undef)

    undef means accept all 'enc' algorithms

    string name of accepted 'enc' algorithm (only one)

    ARRAY ref a list of accepted 'enc' algorithms

    Regexp that has to match 'enc' algorithm name

    my $payload = decode_jwt(token=>$t, key=>$k, accepted_enc=>'A192GCM');
#or
my $payload = decode_jwt(token=>$t, key=>$k, accepted_enc=>['A192GCM','A256GCM']);
#or
my $payload = decode_jwt(token=>$t, key=>$k, accepted_enc=>qr/^A(128|192|256)GCM$/);

  • decode_payload (optional, default: undef)

    0 - do not decode payload, return it as a raw string (octects).

    1 - decode payload from JSON string, return it as perl hash ref (or array ref) - decode_json failure means fatal error (croak).

    undef - if possible decode payload from JSON string, if decode_json fails return payload as a raw string (octets).

  • decode_header (optional, default: 0)

    0 - do not return decoded header as a return value of decode_jwt()

    1 - return decoded header as a return value of decode_jwt()

    my $payload = decode_jwt(token=>$t, key=>$k);
#or
my ($header, $payload) = decode_jwt(token=>$t, key=>$k, decode_header=>1);

  • verify_iss (optional, default: undef)

    CODE ref - subroutine (with 'iss' claim value passed as argument) should return true otherwise verification fails

    Regexp ref - 'iss' claim value has to match given regexp otherwise verification fails

  • verify_aud (optional, default: undef)

    CODE ref - subroutine (with 'aud' claim value passed as argument) should return true otherwise verification fails

    Regexp ref - 'aud' claim value has to match given regexp otherwise verification fails

  • verify_sub (optional, default: undef)

    CODE ref - subroutine (with 'sub' claim value passed as argument) should return true otherwise verification fails

    Regexp ref - 'sub' claim value has to match given regexp otherwise verification fails

  • verify_jti (optional, default: undef)

    CODE ref - subroutine (with 'jti' claim value passed as argument) should return true otherwise verification fails

    Regexp ref - 'jti' claim value has to match given regexp otherwise verification fails

  • verify_iat (optional, default: undef)

    0 - ignore 'iat' claim

    1 - require valid 'iat' claim

    undef - 'iat' claim must be valid if present

  • verify_nbf (optional, default: undef)

    0 - ignore 'nbf' claim

    1 - require valid 'nbf' claim

    undef - 'nbf' claim must be valid if present

  • verify_exp (optional, default: undef)

    0 - ignore 'exp' claim

    1 - require valid 'exp' claim

    undef - 'exp' claim must be valid if present

  • leeway (optional, default: 0)

    Tolerance in seconds related to verify_exp, verify_nbf, verify_iat.

encode_jwt

my $token = encode_jwt(%named_args);

Named arguments:

payload (mandatory)

Value of this parameter can be a string/buffer or HASH ref or ARRAY ref

my $token = encode_jwt(payload=>"any raw data", key=>$k, alg=>'HS256');
#or
my $token = encode_jwt(payload=>{a=>1,b=>2}, key=>$k, alg=>'HS256');
#or
my $token = encode_jwt(payload=>[11,22,33,44], key=>$k, alg=>'HS256');

HASH refs and ARRAY refs payloads are serialized as JSON strings

alg (mandatory)

Supported JWE 'alg' algorithms:

dir
A128KW
A192KW
A256KW
A128GCMKW
A192GCMKW
A256GCMKW
PBES2-HS256+A128KW
PBES2-HS384+A192KW
PBES2-HS512+A256KW
RSA-OAEP
RSA-OAEP-256
RSA1_5
ECDH-ES+A128KW
ECDH-ES+A192KW
ECDH-ES+A256KW
ECDH-ES

Supported JWS algorithms:

none   ...  no integrity (NOTE: disabled by default)
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
PS256  ...  RSA+PSS + SHA256 signature
PS384  ...  RSA+PSS + SHA384 signature
PS512  ...  RSA+PSS + SHA512 signature
ES256  ...  ECDSA + SHA256 signature
ES384  ...  ECDSA + SHA384 signature
ES512  ...  ECDSA + SHA512 signature
enc (mandatory, for JWE only)

Supported 'enc' algorithms:

A128GCM
A192GCM
A256GCM
A128CBC-HS256
A192CBC-HS384
A256CBC-HS512
key (mostly mandatory)

A key used for token encryption (JWE) or token signing (JWS). The value depends on alg token header value.

JWS alg header      key value
------------------  ----------------------------------
none                no key required
HS256               string (raw octects) of any length
HS384               dtto
HS512               dtto
RS256               private RSA key, a string with PEM or DER or JSON/JWK key,
                    perl hash with JWK key, an instance of Crypt::PK::RSA or
                    Crypt::OpenSSL::RSA or Crypt::X509 or Crypt::OpenSSL::X509
RS384               private RSA key, see RS256
RS512               private RSA key, see RS256
PS256               private RSA key, see RS256
PS384               private RSA key, see RS256
PS512               private RSA key, see RS256
ES256               private ECC key, a string with PEM or DER or JSON/JWK key,
                    perl hash with JWK key, an instance of Crypt::PK::ECC
ES384               private ECC key, see ES256
ES512               private ECC key, see ES256

JWE alg header      key value
------------------  ----------------------------------
dir                 string (raw octects), length depends on 'enc' algorithm
A128KW              string (raw octects) 16 bytes
A192KW              string (raw octects) 24 bytes
A256KW              string (raw octects) 32 bytes
A128GCMKW           string (raw octects) 16 bytes
A192GCMKW           string (raw octects) 24 bytes
A256GCMKW           string (raw octects) 32 bytes
PBES2-HS256+A128KW  string (raw octects) of any length
PBES2-HS384+A192KW  string (raw octects) of any length
PBES2-HS512+A256KW  string (raw octects) of any length
RSA-OAEP            public RSA key, a string with PEM or DER or JSON/JWK key,
                    perl hash with JWK key, an instance of Crypt::PK::RSA or
                    Crypt::OpenSSL::RSA
RSA-OAEP-256        public RSA key, see RSA-OAEP
RSA1_5              public RSA key, see RSA-OAEP
ECDH-ES             public ECC key, a string with PEM or DER or JSON/JWK key,
                    perl hash with JWK key, an instance of Crypt::PK::ECC
ECDH-ES+A128KW      public ECC key, see ECDH-ES
ECDH-ES+A192KW      public ECC key, see ECDH-ES
ECDH-ES+A256KW      public ECC key, see ECDH-ES
keypass (optional, default: undef)

When 'key' parameter is an encrypted private RSA or ECC key this parameter may contain a password for private key decryption.

allow_none (optional, default: 0)

1 - allow JWS with none 'alg' header value (which means that token has no signature), BEWARE: DANGEROUS, UNSECURE!!!

0 - do not allow JWS with none 'alg' header value

extra_headers (optional, default: undef)

This parameter may contain a HASH ref with items that will be added to JWT header.

zip (optional, default: undef)

Compression method, currently 'deflate' is the only one supported.

my $token = encode_jwt(payload=>$p, key=>$k, alg=>'HS256', zip=>'deflate');
#or define compression level
my $token = encode_jwt(payload=>$p, key=>$k, alg=>'HS256', zip=>['deflate', 9]);
auto_iat (optional, default: 0)

1 - set 'iat' (Issued At) claim to current time (epoch seconds since 1970) at the moment of token encoding

0 - do not set 'iat' claim

NOTE: claims are part of the payload and can be used only if the payload is a HASH ref!

relative_exp (optional, default: undef)

Set 'exp' claim (Expiration Time) to current time + relative_exp value (in seconds).

NOTE: claims are part of the payload and can be used only if the payload is a HASH ref!

relative_nbf (optional, default: undef)

Set 'nbf' claim (Not Before) to current time + relative_exp value (in seconds).

NOTE: claims are part of the payload and can be used only if the payload is a HASH ref!

auto_typ (optional, default: 0)

1 - set 'typ' header to value JWS for JWS tokens and JWE for JWE tokens.

0 - do not set 'typ' header

SEE ALSO

Crypt::Cipher::AES, Crypt::AuthEnc::GCM, Crypt::PK::RSA, Crypt::PK::ECC, Crypt::KeyDerivation, Crypt::KeyWrap