/ 
Crypt-JWT-0.003
⭐ Starred 54 / Crypt::JWT
Security Advisories (2)
CVE-2019-1010263 (2019-03-20)

Perl Crypt::JWT prior to 0.023 is affected by: Incorrect Access Control. The impact is: allow attackers to bypass authentication by providing a token by crafting with hmac(). The component is: JWT.pm, line 614. The attack vector is: network connectivity. The fixed version is: after commit b98a59b42ded9f9e51b2560410106207c2152d6c.

CVE-2019-1010161 (2019-03-20)

perl-CRYPT-JWT 0.022 and earlier is affected by: Incorrect Access Control. The impact is: bypass authentication. The component is: JWT.pm for JWT security token, line 614 in _decode_jws(). The attack vector is: network connectivity(crafting user-controlled input to bypass authentication). The fixed version is: 0.023.

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);

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]);

SEE ALSO

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