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=>'PBES2-HS256+A128KW', enc=>'A128GCM', 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

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 algorithms defined in https://tools.ietf.org/html/rfc7518 - JSON Web Algorithms (JWA).

This module supports Compact JWS/JWE and Flattened JWS/JWE JSON serialization. General (multi-recipient) JSON serialization is not supported.

EXPORT

Nothing is exported by default.

You can export selected functions:

use Crypt::JWT qw(decode_jwt encode_jwt);

Or all of them at once:

use Crypt::JWT ':all';

FUNCTIONS

decode_jwt

my $data              = decode_jwt(%named_args);
my ($header, $data)   = decode_jwt(%named_args, decode_header=>1);

Returns the decoded payload (in scalar context) or the decoded header followed by the decoded payload (when decode_header => 1). Croaks on any verification, decryption, or claim-check failure.

Named arguments:

• token

  Mandatory. The serialized JWS or JWE token as a string. Both compact (.-separated, 3 segments for JWS / 5 for JWE) and flattened JSON serialization are accepted.

    ### JWS compact (3 segments)
    $t = "eyJhbGciOiJIUzI1NiJ9.dGVzdA.ujBihtLSr66CEWqN74SpLUkv28lra_CeHnxLmLNp4Jo";
    my $data = decode_jwt(token=>$t, key=>$k);
  
    ### JWE compact (5 segments)
    $t = "eyJlbmMiOiJBMTI4R0NNIiwiYWxnIjoiQTEyOEtXIn0.UusxEbzhGkORxTRq0xkFKhvzPrXb9smw.VGfOuq0Fxt6TsdqLZUpnxw.JajIQQ.pkKZ7MHS0XjyGmRsqgom6w";
    my $data = decode_jwt(token=>$t, key=>$k);
  

• key

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

  Since: 0.038 SECURITY: how the key argument is shaped matters.

  • A bare scalar (e.g. 'secret') is always interpreted as a raw octet string (HMAC secret, AES key, etc.).
  • PEM, DER, and JWK-JSON key material must be passed as a SCALAR ref (\$pem) or as an appropriate key object - never as a bare string.
  • If a public-key string is mistakenly passed as a bare scalar and accepted_alg is not set, an attacker who flips the token's alg to HS* can forge a signature using the public-key bytes as the HMAC secret (the so-called "alg confusion" attack).
  • For defense in depth, always pin the algorithm with accepted_alg.

  Overview of supported keys:

    JWS alg header      key value
    ------------------  ----------------------------------
    none                no key required
    HS256               string (raw octets) of any length (or perl HASH ref with JWK, kty=>'oct')
    HS384               same as HS256
    HS512               same as HS256
    RS256               public RSA key, perl HASH ref with JWK key structure,
                        a reference to SCALAR string with PEM or DER or JSON/JWK data,
                        object: Crypt::PK::RSA, Crypt::OpenSSL::RSA, 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, perl HASH ref with JWK key structure,
                        a reference to SCALAR string with PEM or DER or JSON/JWK data,
                        an instance of Crypt::PK::ECC
    ES256K              public ECC key, see ES256
    ES384               public ECC key, see ES256
    ES512               public ECC key, see ES256
    EdDSA               public Ed25519 key
  
    JWE alg header      key value
    ------------------  ----------------------------------
    dir                 string (raw octets) or perl HASH ref with JWK, kty=>'oct', length depends on 'enc' algorithm
    A128KW              string (raw octets) 16 bytes (or perl HASH ref with JWK, kty=>'oct')
    A192KW              string (raw octets) 24 bytes (or perl HASH ref with JWK, kty=>'oct')
    A256KW              string (raw octets) 32 bytes (or perl HASH ref with JWK, kty=>'oct')
    A128GCMKW           string (raw octets) 16 bytes (or perl HASH ref with JWK, kty=>'oct')
    A192GCMKW           string (raw octets) 24 bytes (or perl HASH ref with JWK, kty=>'oct')
    A256GCMKW           string (raw octets) 32 bytes (or perl HASH ref with JWK, kty=>'oct')
    PBES2-HS256+A128KW  string (raw octets) of any length (or perl HASH ref with JWK, kty=>'oct')
    PBES2-HS384+A192KW  string (raw octets) of any length (or perl HASH ref with JWK, kty=>'oct')
    PBES2-HS512+A256KW  string (raw octets) of any length (or perl HASH ref with JWK, kty=>'oct')
    RSA-OAEP            private RSA key, perl HASH ref with JWK key structure,
                        a reference to SCALAR string with PEM or DER or JSON/JWK data,
                        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 or X25519 key, perl HASH ref with JWK key structure,
                        a reference to SCALAR string with PEM or DER or JSON/JWK data,
                        an instance of Crypt::PK::ECC
    ECDH-ES+A128KW      private ECC or X25519 key, see ECDH-ES
    ECDH-ES+A192KW      private ECC or X25519 key, see ECDH-ES
    ECDH-ES+A256KW      private ECC or X25519 key, see ECDH-ES
  

  Example using the key from jwk token header:

    my $data = decode_jwt(token=>$t, key_from_jwk_header=>1);
    my ($header, $data) = decode_jwt(token=>$t, decode_header=>1, key_from_jwk_header=>1);
  

  Examples with raw octet keys:

    #string
    my $data = decode_jwt(token=>$t, key=>'secretkey');
    #binary key
    my $data = decode_jwt(token=>$t, key=>pack("H*", "788A6E38F36B7596EF6A669E94"));
    #perl HASH ref with JWK structure (key type 'oct')
    my $data = decode_jwt(token=>$t, key=>{kty=>'oct', k=>"GawgguFyGrWKav7AX4VKUg"});
  

  Examples with RSA keys:

    my $pem_key_string = <<'EOF';
    -----BEGIN PRIVATE KEY-----
    MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCoVm/Sl5r+Ofky
    jioRSZK26GW6WyjyfWKddsSi13/NOtCn0rRErSF/u3QrgGMpWFqKohqbi1VVC+SZ
    ...
    8c1vm2YFafgdkSk9Qd1oU2Fv1aOQy4VovOFzJ3CcR+2r7cbRfcpLGnintHtp9yek
    02p+d5g4OChfFNDhDtnIqjvY
    -----END PRIVATE KEY-----
    EOF
  
    my $jwk_key_json_string = '{"kty":"RSA","n":"0vx7agoebG...L6tSoc_BJECP","e":"AQAB"}';
  
    #a reference to SCALAR string with PEM or DER or JSON/JWK data,
    my $data = decode_jwt(token=>$t, key=>\$pem_key_string);
    my $data = decode_jwt(token=>$t, key=>\$der_key_string);
    my $data = decode_jwt(token=>$t, key=>\$jwk_key_json_string);
  
    #instance of Crypt::PK::RSA
    my $data = decode_jwt(token=>$t, key=>Crypt::PK::RSA->new('keyfile.pem'));
    my $data = decode_jwt(token=>$t, key=>Crypt::PK::RSA->new(\$pem_key_string));
  
    #instance of Crypt::OpenSSL::RSA
    my $data = decode_jwt(token=>$t, key=>Crypt::OpenSSL::RSA->new_private_key($pem_key_string));
  
    #instance of Crypt::X509 (public key only)
    my $data = decode_jwt(token=>$t, key=>Crypt::X509->new(cert=>$cert));
  
    #instance of Crypt::OpenSSL::X509 (public key only)
    my $data = decode_jwt(token=>$t, key=>Crypt::OpenSSL::X509->new_from_file('cert.pem'));
    my $data = decode_jwt(token=>$t, key=>Crypt::OpenSSL::X509->new_from_string($cert));
  
    #perl HASH ref with JWK structure (key type 'RSA')
    my $rsa_priv = {
      kty => "RSA",
      n   => "0vx7agoebGcQSuuPiLJXZpt...eZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
      e   => "AQAB",
      d   => "X4cTteJY_gn4FYPsXB8rdXi...FLN5EEaG6RoVH-HLKD9Mdx5ooGURknhnrRwUkC7h5fJLMWbFAKLWY2v7B6NqSzUvx0_YSf",
      p   => "83i-7IvMGXoMXCskv73TKr8...Z27zvoj6pbUQyLPBQxtPnwD20-60eTmD2ujMt5PoMrm8RmNhVWtjjMmMjOpSicFHjXOuVI",
      q   => "3dfOR9cuYq-0S-mkFLzgItg...q3hWeMuG0ouqnb3obLyuqjVZQ1dIrdgTnCdYzBcOW5r37AFXjift_NGiovonzhKpoVVS78",
      dp  => "G4sPXkc6Ya9y8oJW9_ILj4...zi_H7TkS8x5SdX3oE0oiYwxIiemTAu0UOa5pgFGyJ4c8t2VF40XRugKTP8akhFo5tA77Qe",
      dq  => "s9lAH9fggBsoFR8Oac2R_E...T2kGOhvIllTE1efA6huUvMfBcpn8lqW6vzzYY5SSF7pMd_agI3G8IbpBUb0JiraRNUfLhc",
      qi  => "GyM_p6JrXySiz1toFgKbWV...4ypu9bMWx3QJBfm0FoYzUIZEVEcOqwmRN81oDAaaBk0KWGDjJHDdDmFW3AN7I-pux_mHZG",
    };
    my $data = decode_jwt(token=>$t, key=>$rsa_priv);
  

  Examples with ECC keys:

    my $pem_key_string = <<'EOF';
    -----BEGIN EC PRIVATE KEY-----
    MHcCAQEEIBG1c3z52T8XwMsahGVdOZWgKCQJfv+l7djuJjgetdbDoAoGCCqGSM49
    AwEHoUQDQgAEoBUyo8CQAFPeYPvv78ylh5MwFZjTCLQeb042TjiMJxG+9DLFmRSM
    lBQ9T/RsLLc+PmpB1+7yPAR+oR5gZn3kJQ==
    -----END EC PRIVATE KEY-----
    EOF
  
    my $jwk_key_json_string = '{"kty":"EC","crv":"P-256","x":"MKB..7D4","y":"4Et..FyM"}';
  
    #a reference to SCALAR string with PEM or DER or JSON/JWK data,
    my $data = decode_jwt(token=>$t, key=>\$pem_key_string);
    my $data = decode_jwt(token=>$t, key=>\$der_key_string);
    my $data = decode_jwt(token=>$t, key=>\$jwk_key_json_string);
  
    #instance of Crypt::PK::ECC
    my $data = decode_jwt(token=>$t, key=>Crypt::PK::ECC->new('keyfile.pem'));
    my $data = decode_jwt(token=>$t, key=>Crypt::PK::ECC->new(\$pem_key_string));
  
    #perl HASH ref with JWK structure (key type 'EC')
    my $ecc_priv = {
      kty => "EC",
      crv => "P-256",
      x   => "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
      y   => "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
      d   => "870MB6gfuTJ4HtUnUvYMyJpr5eUZNP4Bk43bVdj3eAE",
    };
    my $data = decode_jwt(token=>$t, key=>$ecc_priv);
  

• keypass

  Optional. When the key parameter is an encrypted private RSA or ECC key (PEM/DER), this parameter holds the password used to decrypt it.

• kid_keys

  This parameter can be either a JWK Set JSON string (see RFC7517) or a perl HASH ref with JWK Set structure like this:

    my $keylist = {
      keys => [
        { kid=>"key1", kty=>"oct", k=>"GawgguFyGrWKav7AX4VKUg" },
        { kid=>"key2", kty=>"oct", k=>"ulxLGy4XqhbpkR5ObGh1gX" },
      ]
    };
    my $payload = decode_jwt(token=>$t, kid_keys=>$keylist);
  

  You can use "export_key_jwk" in Crypt::PK::RSA to generate a JWK for RSA:

    my $pubkey = Crypt::PK::RSA->new('rs256-4096-public.pem');
    my $jwk_hash = $pubkey->export_key_jwk('public', 1);
    $jwk_hash->{kid} = 'key1';
    my $keylist = {
      keys => [
        $jwk_hash,
      ]
    };
  

  The structure described above is used e.g. by https://www.googleapis.com/oauth2/v2/certs

    use Mojo::UserAgent;
    my $ua = Mojo::UserAgent->new;
    my $google_keys = $ua->get('https://www.googleapis.com/oauth2/v2/certs')->result->json;
    my $payload = decode_jwt(token => $t, kid_keys => $google_keys);
  

  Since: 0.019 An alternative structure (used e.g. by https://www.googleapis.com/oauth2/v1/certs) is also accepted:

    use LWP::Simple;
    my $google_certs = get('https://www.googleapis.com/oauth2/v1/certs');
    my $payload = decode_jwt(token => $t, kid_keys => $google_certs);
  

  When the token header contains a kid item, the corresponding key is looked up in the kid_keys list and used for token decoding (you do not need to pass the explicit key via the key parameter). Add a kid header on the encode side via "extra_headers".

  INCOMPATIBLE CHANGE Since: 0.023 When kid_keys is specified, decoding croaks if the token header does not contain a kid value or if the kid was not found in kid_keys.

• key_from_jwk_header

  Since: 0.023

  1 - use jwk header value for validating JWS signature if neither key nor kid_keys specified, BEWARE: DANGEROUS, INSECURE.

  0 (default) - ignore jwk header value when validating JWS signature

  Keep in mind that enabling key_from_jwk_header requires the jwk header to exist and to be a valid RSA/ECDSA public key (otherwise it croaks).

• allow_none

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

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

• ignore_signature

  1 - do not check signature on JWS tokens, BEWARE: DANGEROUS, INSECURE.

  0 (default) - check signature on JWS tokens

• accepted_alg

  Since: 0.038 SECURITY: strongly recommended. Pinning accepted_alg to the algorithm (or family) you actually expect prevents "alg confusion" attacks where a forged token swaps the alg header to a different family - see the SECURITY note under key.

  Accepted value types:

  • undef (default) - accept all alg algorithms except none (for accepting none use allow_none)
  • Scalar string - the single accepted alg name
  • ARRAY ref - list of accepted alg names
  • Regexp - the alg value must match this regexp

  Example:

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

  INCOMPATIBLE CHANGE Since: 0.038 Any other argument type (HASH ref, CODE ref, GLOB ref, etc.) now croaks at decode time; previously such typos silently became no-ops on the JWE side.

• accepted_enc

  JWE only. Restricts which content-encryption algorithms are accepted.

  Accepted value types (same shape as "accepted_alg"):

  • undef (default) - accept all enc algorithms
  • Scalar string - the single accepted enc name
  • ARRAY ref - list of accepted enc names
  • Regexp - the enc value must match this regexp

  Example:

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

• decode_payload

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

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

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

• decode_header

  0 (default) - decode_jwt returns just the decoded payload (scalar context).

  1 - decode_jwt returns ($header, $payload); useful when you need to inspect the JWT header (e.g. alg, kid, typ).

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

• verify_iss

  INCOMPATIBLE CHANGE Since: 0.024 If verify_iss is specified and the iss (Issuer) claim is completely missing, verification fails.

  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

  Scalar - 'iss' claim value has to be equal to given string. Since: 0.029

  undef (default) - do not verify 'iss' claim

• verify_aud

  INCOMPATIBLE CHANGE Since: 0.024 If verify_aud is specified and the aud (Audience) claim is completely missing, verification fails.

  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

  Scalar - 'aud' claim value has to be equal to given string. Since: 0.029

  undef (default) - do not verify 'aud' claim

  Since: 0.036 The aud claim may also be an array of strings. The check succeeds if at least one array element matches; the configured check (CODE, Regexp, Scalar) is applied individually to each element.

• verify_sub

  INCOMPATIBLE CHANGE Since: 0.024 If verify_sub is specified and the sub (Subject) claim is completely missing, verification fails.

  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

  Scalar - 'sub' claim value has to be equal to given string. Since: 0.029

  undef (default) - do not verify 'sub' claim

• verify_jti

  INCOMPATIBLE CHANGE Since: 0.024 If verify_jti is specified and the jti (JWT ID) claim is completely missing, verification fails.

  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

  Scalar - 'jti' claim value has to be equal to given string. Since: 0.029

  undef (default) - do not verify 'jti' claim

• verify_iat

  NOTE: verify_iat is asymmetric with verify_nbf/verify_exp. Omitting the key entirely (the true default) means "no iat check". Passing verify_iat => undef is not the same as omitting it - it explicitly enables the present-but-must-be-valid check below.

  undef - "validate-if-present" mode: if the payload contains an 'iat' claim it must not be in the future (modulo leeway), otherwise verification croaks; if 'iat' is absent, no error is raised. Useful when you want to honor an issuer's 'iat' when they provide one but not insist on it being there.

  0 - ignore 'iat' claim (same as omitting the key)

  1 - require valid 'iat' claim: payload must contain 'iat' and it must not be in the future (modulo leeway); croaks otherwise.

  If the verify_iat key is not passed at all, no iat check is performed regardless of whether the payload contains an 'iat' claim.

• verify_nbf

  undef (default) - Not Before 'nbf' claim must be valid if present

  0 - ignore 'nbf' claim

  1 - require valid 'nbf' claim

• verify_exp

  undef (default) - Expiration Time 'exp' claim must be valid if present

  0 - ignore 'exp' claim

  1 - require valid 'exp' claim

• leeway

  Tolerance in seconds related to verify_exp, verify_nbf and verify_iat. Default is 0.

• ignore_claims

  1 - do not check claims (iat, exp, nbf, iss, aud, sub, jti), BEWARE: DANGEROUS, INSECURE.

  0 (default) - check claims

• verify_typ

  Since: 0.036

  CODE ref - subroutine (with 'typ' header parameter value passed as argument) should return true otherwise verification fails

  Regexp ref - 'typ' header parameter value has to match given regexp otherwise verification fails

  Scalar - 'typ' header parameter value has to be equal to given string

  undef (default) - do not verify 'typ' header parameter

• tolerate_padding

  Since: 0.037 (semantics clarified Since: 0.038). Both modes accept tokens whose segments include trailing = Base64 padding characters (which are not produced by spec-compliant encoders); they differ only in what gets fed to the signature check.

  0 (default) - strip = padding from each segment before computing the signature input. Compatible with the strict RFC 7515 producer (no padding signed). If the producer signed the padded form, signature verification will fail in this mode.

  1 - keep = padding as part of the signature input. Required to verify tokens produced by libraries (some Java implementations) that include padding in the bytes that were signed.

encode_jwt

my $token = encode_jwt(%named_args);

Returns the encoded JWT as a string - either compact serialization (the default; three or five .-separated segments) or flattened JSON serialization (when serialization => 'flattened'; a JSON object). Croaks on bad arguments or unsupported algorithm combinations.

Named arguments:

• payload

  Mandatory. Accepts a string (raw bytes), a HASH ref, or an ARRAY ref. HASH ref and ARRAY ref payloads are serialized as JSON strings; string payloads are passed through verbatim.

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

• alg

  The 'alg' header value is mandatory for both JWE and JWS tokens.

  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
    ES256K ...  ECDSA + SHA256 signature
    ES384  ...  ECDSA + SHA384 signature
    ES512  ...  ECDSA + SHA512 signature
    EdDSA  ...  Ed25519 signature
  

• enc

  The 'enc' header is mandatory for JWE tokens.

  Supported 'enc' algorithms:

    A128GCM
    A192GCM
    A256GCM
    A128CBC-HS256
    A192CBC-HS384
    A256CBC-HS512
  

• key

  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 octets) of any length (or perl HASH ref with JWK, kty=>'oct')
    HS384               same as HS256
    HS512               same as HS256
    RS256               private RSA key, perl HASH ref with JWK key structure,
                        a reference to SCALAR string with PEM or DER or JSON/JWK data,
                        object: Crypt::PK::RSA, Crypt::OpenSSL::RSA, 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, perl HASH ref with JWK key structure,
                        a reference to SCALAR string with PEM or DER or JSON/JWK data,
                        an instance of Crypt::PK::ECC
    ES256K              private ECC key, see ES256
    ES384               private ECC key, see ES256
    ES512               private ECC key, see ES256
    EdDSA               private Ed25519 key
  
    JWE alg header      key value
    ------------------  ----------------------------------
    dir                 string (raw octets) or perl HASH ref with JWK, kty=>'oct', length depends on 'enc' algorithm
    A128KW              string (raw octets) 16 bytes (or perl HASH ref with JWK, kty=>'oct')
    A192KW              string (raw octets) 24 bytes (or perl HASH ref with JWK, kty=>'oct')
    A256KW              string (raw octets) 32 bytes (or perl HASH ref with JWK, kty=>'oct')
    A128GCMKW           string (raw octets) 16 bytes (or perl HASH ref with JWK, kty=>'oct')
    A192GCMKW           string (raw octets) 24 bytes (or perl HASH ref with JWK, kty=>'oct')
    A256GCMKW           string (raw octets) 32 bytes (or perl HASH ref with JWK, kty=>'oct')
    PBES2-HS256+A128KW  string (raw octets) of any length (or perl HASH ref with JWK, kty=>'oct')
    PBES2-HS384+A192KW  string (raw octets) of any length (or perl HASH ref with JWK, kty=>'oct')
    PBES2-HS512+A256KW  string (raw octets) of any length (or perl HASH ref with JWK, kty=>'oct')
    RSA-OAEP            public RSA key, perl HASH ref with JWK key structure,
                        a reference to SCALAR string with PEM or DER or JSON/JWK data,
                        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 or X25519 key, perl HASH ref with JWK key structure,
                        a reference to SCALAR string with PEM or DER or JSON/JWK data,
                        an instance of Crypt::PK::ECC
    ECDH-ES+A128KW      public ECC or X25519 key, see ECDH-ES
    ECDH-ES+A192KW      public ECC or X25519 key, see ECDH-ES
    ECDH-ES+A256KW      public ECC or X25519 key, see ECDH-ES
  

• keypass

  Optional. When the key parameter is an encrypted private RSA or ECC key (PEM/DER), this parameter holds the password used to decrypt it.

• allow_none

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

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

• extra_headers

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

  If you want to use PBES2-based 'alg' like PBES2-HS512+A256KW you can set PBES2 salt len (p2s) in bytes and iteration count (p2c) via extra_headers like this:

    my $token = encode_jwt(payload=>$p, key=>$k, alg=>'PBES2-HS512+A256KW', extra_headers=>{p2c=>8000, p2s=>32});
    #NOTE: handling of p2s header is a special case, in the end it is replaced with the generated salt
  

  You can also use this to specify a kid value (see "kid_keys"):

    my $token = encode_jwt(payload=>$p, key=>$k, alg=>'RS256', extra_headers=>{kid=>'key1'});
  

• unprotected_headers

  A HASH ref with additional integrity-unprotected headers (JWS and JWE). Not available for compact serialization.

• shared_unprotected_headers

  A HASH ref with additional integrity-unprotected headers (JWE only). Not available for compact serialization.

• aad

  Additional Authenticated Data: a scalar of arbitrary bytes that is authenticated but not encrypted (JWE only). Not available for compact serialization.

• serialization

  Specify serialization method: compact (default) for Compact JWS/JWE serialization or flattened for Flattened JWS/JWE JSON serialization.

  General JSON serialization is not supported yet.

• zip

  Compression method, currently 'deflate' is the only one supported. undef (default) means no compression.

    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

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

  0 (default) - do not set the iat claim.

  NOTE: takes effect only when the payload argument is a HASH ref; silently ignored for string/ARRAY-ref payloads. Same applies to relative_exp and relative_nbf.

• relative_exp

  Set the exp (Expiration Time) claim to current time + relative_exp value (in seconds). See note under auto_iat about HASH-ref payloads.

• relative_nbf

  Set the nbf (Not Before) claim to current time + relative_nbf value (in seconds). See note under auto_iat about HASH-ref payloads.

SECURITY CONSIDERATIONS

Configuration knobs

The library exposes four tunable package variables. Set them once at program startup (typically in a BEGIN block) before any encode_jwt/decode_jwt call.

• $Crypt::JWT::MAX_PBES2_ITER (default 3_000_000)

  Maximum accepted PBES2 p2c (iteration count) on decode. Caps CPU time spent on PBKDF2 for an attacker-controlled token. Since: 0.038

• $Crypt::JWT::MAX_INFLATED_SIZE (default 10 * 1024 * 1024)

  Maximum size (in bytes) of a payload after zip=DEF inflation. Caps memory blow-up from "zip-bomb" tokens. Since: 0.038

• $Crypt::JWT::MIN_HMAC_KEY_LEN (default 4)

  Minimum HMAC key length (bytes) for HS256/384/512. See "Key-strength minimums" below for the rationale and recommended override values. Since: 0.038

• $Crypt::JWT::MIN_RSA_BITS (default 2048)

  Minimum RSA modulus size (bits). Applies to all RSA-based algorithms (RS256/384/512, PS256/384/512, RSA-OAEP, RSA-OAEP-256, RSA1_5). Since: 0.038

Key-strength minimums

The library enforces the following minimums; tokens that try to sign or verify with weaker keys are rejected with a croak. Both knobs are package variables and can be tuned at startup if a deployer has a stricter or looser policy.

• HMAC keys for HS<n>: minimum length 4 bytes (overridable via $Crypt::JWT::MIN_HMAC_KEY_LEN). Applies to encode_jwt and decode_jwt on the HS256 / HS384 / HS512 paths. Tokens that try to sign or verify with a shorter key are rejected with a croak.

  CAUTION: this default is intentionally much lower than RFC 7518 section 3.2, which requires the key to be at least the size of the hash output (32 / 48 / 64 bytes for HS256 / HS384 / HS512). The 4-byte floor is a backward-compatibility compromise - the library has long accepted short keys and many existing deployments rely on that - that just blocks the most trivially weak keys (single characters, two-letter strings) while leaving the policy decision in the deployer's hands. Cryptographically, HMAC security is bounded by the entropy of the key: 16 random bytes (128 bits) is the smallest size that gives a comfortable security margin against brute-force key recovery; below that you start losing real security.

• RSA modulus size: minimum 2048 bits (overridable via $Crypt::JWT::MIN_RSA_BITS). Applies to RS256/384/512, PS256/384/512, RSA-OAEP, RSA-OAEP-256, and RSA1_5 - both signing/encryption and verification/decryption. RSA keys with smaller moduli are rejected. This matches RFC 7518 section 3.3: "A key of size 2048 bits or larger MUST be used with these algorithms".

SEE ALSO

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

LICENSE

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

COPYRIGHT

Copyright (c) 2015-2026 DCIT, a.s. https://www.dcit.cz / Karel Miko