File Coverage

blib/lib/Crypt/JWT.pm

Criterion	Covered	Total	%
statement	508	571	88.9
branch	342	510	67.0
condition	102	208	49.0
subroutine	46	46	100.0
pod	2	2	100.0
total	1000	1337	74.7

package Crypt::JWT;

use strict;
use warnings;

our $VERSION = '0.038';

use Exporter 'import';
our %EXPORT_TAGS = ( all => [qw(decode_jwt encode_jwt)] );
our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
our @EXPORT = qw();

use Carp;
use Crypt::Misc qw(decode_b64u encode_b64u slow_eq);
use JSON qw(decode_json encode_json);
use Crypt::PK::RSA;
use Crypt::PK::ECC;
use Crypt::PK::Ed25519;
use Crypt::PK::X25519;
use Crypt::PRNG qw(random_bytes);
use Crypt::KeyWrap ':all';
use Crypt::AuthEnc::GCM qw(gcm_encrypt_authenticate gcm_decrypt_verify);
use Crypt::Mac::HMAC qw(hmac);
use Compress::Raw::Zlib;
use Scalar::Util qw(looks_like_number);

# DoS guards on decode
our $MAX_PBES2_ITER     = 3_000_000;         # max accepted PBES2 'p2c' (iteration count)
our $MAX_INFLATED_SIZE  = 10 * 1024 * 1024;  # max accepted size of payload after 'zip' inflation

# Key-strength minimums. Values lower than the RFC 7518 strict requirement
# but high enough that the cryptographic security argument holds (see
# SECURITY CONSIDERATIONS in the POD). Tunable at startup if a deployer has
# a stronger or weaker policy.
our $MIN_HMAC_KEY_LEN   = 4;                 # minimum HMAC key length (bytes) for HS256/HS384/HS512
our $MIN_RSA_BITS       = 2048;              # minimum RSA modulus size (bits) for RS*/PS*/RSA-OAEP*/RSA1_5

# Compact-serialization token shape; precompiled to avoid rebuilding per decode_jwt() call.
my $TOKEN_RE_STRICT  = qr/^([a-zA-Z0-9_-]+)=*\.([a-zA-Z0-9_-]*)=*\.([a-zA-Z0-9_-]*)=*(?:\.([a-zA-Z0-9_-]+)=*\.([a-zA-Z0-9_-]+)=*)?$/;
my $TOKEN_RE_PADDING = qr/^([a-zA-Z0-9_-]+=*)\.([a-zA-Z0-9_-]*=*)\.([a-zA-Z0-9_-]*=*)(?:\.([a-zA-Z0-9_-]+=*)\.([a-zA-Z0-9_-]+=*))?$/;

# JWS: https://tools.ietf.org/html/rfc7515
# JWE: https://tools.ietf.org/html/rfc7516
# JWK: https://tools.ietf.org/html/rfc7517
# JWA: https://tools.ietf.org/html/rfc7518
# JWT: https://tools.ietf.org/html/rfc7519
# X25519/Ed25519 https://tools.ietf.org/html/rfc8037

sub _prepare_rsa_key {
  my ($key) = @_;
  croak "JWT: undefined RSA key" unless defined $key;
  croak "JWT: invalid RSA key (cannot be scalar)" unless ref $key;
  # we need Crypt::PK::RSA object
  my $pk;
  if    (ref($key) eq 'Crypt::PK::RSA')                 { $pk = $key }
  elsif (ref($key) eq 'HASH' || ref($key) eq 'SCALAR')  { $pk = Crypt::PK::RSA->new($key) }
  elsif (ref($key) eq 'ARRAY')                          { $pk = Crypt::PK::RSA->new(@$key) }
  else {
    # handle also: Crypt::OpenSSL::RSA, Crypt::X509, Crypt::OpenSSL::X509
    my $str;
    if (ref($key) eq 'Crypt::OpenSSL::RSA') {
      # https://metacpan.org/pod/Crypt::OpenSSL::RSA
      $str = $key->is_private ? $key->get_private_key_string : $key->get_public_key_string;
    }
    elsif (ref($key) =~ /^Crypt::(X509|OpenSSL::X509)$/) {
      # https://metacpan.org/pod/Crypt::X509
      # https://metacpan.org/pod/Crypt::OpenSSL::X509
      $str = $key->pubkey;
    }
    $pk = Crypt::PK::RSA->new(\$str) if defined $str && !ref($str);
  }
  croak "JWT: invalid RSA key" unless $pk;
  # RFC 7518 sec 3.3: "A key of size 2048 bits or larger MUST be used".
  # Check via Crypt::PK::RSA->size which returns the modulus size in bytes.
  my $bits = $pk->size * 8;
  croak "JWT: RSA modulus too small ($bits bits, minimum $MIN_RSA_BITS)" if $bits < $MIN_RSA_BITS;
  return $pk;
}

sub _prepare_ecc_key {
  my ($key) = @_;
  croak "JWT: undefined ECC key" unless defined $key;
  croak "JWT: invalid ECC key (cannot be scalar)" unless ref $key;
  # we need Crypt::PK::ECC object
  return $key                       if ref($key) eq 'Crypt::PK::ECC';
  return Crypt::PK::ECC->new($key)  if ref($key) eq 'HASH' || ref($key) eq 'SCALAR';
  return Crypt::PK::ECC->new(@$key) if ref($key) eq 'ARRAY';
  croak "JWT: invalid ECC key";
}

sub _prepare_ed25519_key {
  my ($key) = @_;
  croak "JWT: undefined Ed25519 key" unless defined $key;
  croak "JWT: invalid Ed25519 key (cannot be scalar)" unless ref $key;
  # we need Crypt::PK::Ed25519 object
  return $key                           if ref($key) eq 'Crypt::PK::Ed25519';
  return Crypt::PK::Ed25519->new($key)  if ref($key) eq 'HASH' || ref($key) eq 'SCALAR';
  return Crypt::PK::Ed25519->new(@$key) if ref($key) eq 'ARRAY';
  croak "JWT: invalid Ed25519 key";
}

sub _prepare_ecdh_key {
  my ($key) = @_;
  croak "JWT: undefined ECDH key" unless defined $key;
  croak "JWT: invalid ECDH key (cannot be scalar)" unless ref $key;

  # we need Crypt::PK::X25519 or Crypt::PK::ECC object
  return $key if ref($key) =~ /^Crypt::PK::(ECC|X25519)$/;

  if (ref($key) eq 'HASH' || ref($key) eq 'SCALAR') {
    #HACK: this is ugly
    my $rv = eval { Crypt::PK::ECC->new($key) } || eval { Crypt::PK::X25519->new($key) };
    return $rv if defined $rv;
  }
  if (ref($key) eq 'ARRAY') {
    #HACK: this is ugly
    my $rv = eval { Crypt::PK::ECC->new(@$key) } || eval { Crypt::PK::X25519->new(@$key) };
    return $rv if defined $rv;
  }
  croak "JWT: invalid ECDH key";
}

sub _prepare_oct_key {
  my ($key) = @_;
  croak "JWT: undefined oct key" unless defined $key;
  if (ref $key eq 'HASH' && $key->{k} && $key->{kty} && $key->{kty} eq 'oct') {
    return decode_b64u($key->{k});
  }
  elsif (!ref $key) {
    return $key;
  }
  croak "JWT: invalid oct key";
}

sub _kid_lookup {
  my ($kid, $kid_keys, $alg) = @_;
  return undef if !defined $kid || !defined $alg;
  $kid_keys = eval { decode_json($kid_keys) } if $kid_keys && !ref $kid_keys;
  croak "JWT: kid_keys must be a HASHREF or a valid JSON/HASH" if ref $kid_keys ne 'HASH';
  my $found;
  if (exists $kid_keys->{keys} && ref $kid_keys->{keys} eq 'ARRAY') {
    #FORMAT: { keys => [ {kid=>'A', kty=>?, ...}, {kid=>'B', kty=>?, ...} ] }
    my @keys = @{$kid_keys->{keys}};

    # Sanity-check the keyset before lookup. Both checks defend against
    # ambiguous keysets where the lookup result depends on iteration order
    # (a possible alg-confusion vector).
    #   1. Duplicate kids: a token's 'kid' header must resolve to one key.
    #   2. Mixed symmetry: a keyset that contains BOTH symmetric (kty=oct)
    #      and asymmetric (RSA/EC/OKP) keys lets an attacker pick the type
    #      that suits a forged token.
    my (%seen_kid, $has_oct, $has_asym);
    for my $k (@keys) {
      if (defined $k->{kid}) {
        croak "JWT: kid_keys contains duplicate kid '$k->{kid}'" if $seen_kid{$k->{kid}}++;
      }
      $has_oct  = 1 if ($k->{kty} || '') eq 'oct';
      $has_asym = 1 if ($k->{kty} || '') =~ /^(RSA|EC|OKP)$/;
    }
    croak "JWT: kid_keys mixes symmetric (oct) and asymmetric keys" if $has_oct && $has_asym;

    for (@keys) {
      if ($_->{kid} && $_->{kty} && $_->{kid} eq $kid) {
        $found = $_;
        last;
      }
    }
  }
  else {
    #FORMAT: { hexadec1 => "----BEGIN CERTIFICATE-----...", hexadec2 => "----BEGIN CERTIFICATE-----..." }
    #e.g. https://www.googleapis.com/oauth2/v1/certs
    return \$kid_keys->{$kid} if $kid_keys->{$kid} && !ref $kid_keys->{$kid};
  }
  return undef if !$found;
  return $found if $found->{kty} eq 'oct' && $alg =~ /^(HS|dir|PBES2-HS|A)/;
  return $found if $found->{kty} eq 'OKP' && $alg =~ /^(EdDSA|ECDH-ES)/;
  return $found if $found->{kty} eq 'EC'  && $alg =~ /^(ES|EC)/;
  return $found if $found->{kty} eq 'RSA' && $alg =~ /^(RS|PS)/;
  croak "JWT: key type '$found->{kty}' cannot be used with alg '$alg'";
}

sub _b64u_to_hash {
  my $b64url = shift;
  return undef unless $b64url;
  my $json = decode_b64u($b64url);
  return undef unless $json;
  my $hash = eval { decode_json($json) };
  return undef unless ref $hash eq 'HASH';
  return $hash;
}

sub _add_claims {
  my ($payload, %args) = @_;
  #### claims (defined for JWS only)
  # "exp"   Expiration Time
  # "nbf"   Not Before
  # "iat"   Issued At
  # "iss"   Issuer
  # "sub"   Subject
  # "aud"   Audience
  # "jti"   JWT ID
  my $now = time;
  $payload->{iat} = $now                       if $args{auto_iat};
  $payload->{exp} = $now + $args{relative_exp} if defined $args{relative_exp};
  $payload->{nbf} = $now + $args{relative_nbf} if defined $args{relative_nbf};
}

sub _check_jwk_constraints {
  # RFC 7517 sections 4.2/4.3/4.4: enforce JWK metadata when the key is supplied as
  # a JWK hash (either via 'key' directly or resolved via 'kid_keys'). For
  # non-JWK key forms (Crypt::PK::* objects, scalar refs, bare HMAC scalars)
  # there is no metadata to consult and we silently skip.
  my ($key, $alg, $what) = @_;   # $what is 'JWS' or 'JWE'
  return unless ref $key eq 'HASH';

  # 'alg' (sec 4.4): if present, must match. For JWS the same RSA/EC key can
  # legitimately verify across different hash sizes within the same family
  # (PS256 key verifying a PS384 token, ES512 key verifying an ES256 token,
  # etc.) - see RFC 7520 examples. So JWS matches by family (HS/RS/PS/ES/
  # EdDSA), while JWE - where a different alg means a different padding or
  # wrap mechanism, not just a hash size - still requires exact match.
  if (defined $key->{alg}) {
    my $jwk_alg = $key->{alg};
    my $ok;
    if ($what eq 'JWS') {
      my $fam_of = sub { $_[0] =~ /^(HS|RS|PS|ES|EdDSA)/ ? $1 : $_[0] };
      $ok = $fam_of->($jwk_alg) eq $fam_of->($alg);
    }
    else {
      $ok = $jwk_alg eq $alg;
    }
    croak "$what: JWK 'alg' ($jwk_alg) does not match token alg ($alg)" unless $ok;
  }

  # 'use' (sec 4.2): 'sig' for JWS verify, 'enc' for JWE decrypt
  my $expected_use = $what eq 'JWS' ? 'sig' : 'enc';
  if (defined $key->{use} && $key->{use} ne $expected_use) {
    croak "$what: JWK 'use' ($key->{use}) does not allow $expected_use op";
  }

  # 'key_ops' (sec 4.3): if present, must include the operation we are about to do
  if (ref $key->{key_ops} eq 'ARRAY') {
    my @want = $what eq 'JWS' ? ('verify') : ('decrypt', 'unwrapKey', 'deriveKey', 'deriveBits');
    my %ops  = map { $_ => 1 } @{$key->{key_ops}};
    my $found = 0;
    $found ||= $ops{$_} for @want;
    croak "$what: JWK 'key_ops' [@{$key->{key_ops}}] does not include any of: @want" unless $found;
  }

  # EC self-consistency: an EC JWK's 'alg' implies a specific curve per
  # RFC 7518 sec 3.4. If the JWK's 'crv' disagrees with what the 'alg'
  # demands, the JWK is malformed and we refuse to use it. ES521 is
  # accepted as a historical alias for ES512 (used in some older test
  # vectors and implementations).
  if (($key->{kty} || '') eq 'EC' && defined $key->{alg} && defined $key->{crv}) {
    my %ec_curve_for = (
      ES256  => 'P-256',
      ES256K => 'secp256k1',
      ES384  => 'P-384',
      ES512  => 'P-521',
      ES521  => 'P-521',
    );
    if (exists $ec_curve_for{$key->{alg}}) {
      croak "$what: JWK alg/crv mismatch ($key->{alg} requires $ec_curve_for{$key->{alg}}, got $key->{crv})"
        if $ec_curve_for{$key->{alg}} ne $key->{crv};
    }
    elsif ($key->{alg} =~ /^ES/) {
      croak "$what: JWK has unknown ECDSA alg '$key->{alg}'";
    }
  }
}

sub _check_accepted {
  my ($what, $value, $check) = @_;
  return unless defined $check;
  my $r = ref $check;
  if    ($r eq 'Regexp') { croak "JWT: $what '$value' does not match accepted_$what" if $value !~ $check }
  elsif ($r eq 'ARRAY')  { my %ok = map { $_ => 1 } @$check;
                           croak "JWT: $what '$value' not in accepted_$what" unless $ok{$value} }
  elsif (!$r)            { croak "JWT: $what '$value' not accepted_$what" if $value ne $check }
  else                   { croak "JWT: accepted_$what must be Regexp, ARRAY ref, or Scalar (got $r)" }
}

sub _verify_header {
  my ($header, %args) = @_;

  # currently we only check "typ" header parameter
  my $check = $args{verify_typ};
  return if !defined $check;

  if (exists $header->{typ}) {
    if (ref $check eq 'Regexp') {
      my $value = $header->{typ};
      $value = "" if !defined $value;
      croak "JWT: typ header re check failed" unless $value =~ $check;
    }
    elsif (ref $check eq 'CODE') {
      croak "JWT: typ header code check failed" unless $check->($header->{typ});
    }
    elsif (!ref $check) {
      my $value = $header->{typ};
      croak "JWT: typ header scalar check failed" unless defined $value && $value eq $check;
    }
    else {
      croak "JWT: verify_typ must be Regexp, Scalar or CODE";
    }
  }
  else {
    croak "JWT: typ header required but missing"
  }

}

sub _check_numeric_date {
  my ($payload, $claim) = @_;
  my $value = $payload->{$claim};
  croak "JWT: $claim claim must be a NumericDate"
    if !defined($value) || ref($value) || "$value" !~ /\A(?:0|[1-9][0-9]*)(?:\.[0-9]+)?\z/;
}

sub _verify_claims {
  my ($payload, %args) = @_;

  return if $args{ignore_claims};

  if (ref($payload) ne 'HASH') {
    # https://github.com/DCIT/perl-Crypt-JWT/issues/31
    # payload needs to be decoded into a HASH for checking any verify_XXXX
    for my $claim (qw(exp nbf iat iss sub aud jti)) {
      if (defined $args{"verify_$claim"} && $args{"verify_$claim"} != 0) {
        croak "JWT: cannot check verify_$claim (payload not decoded JSON/HASH)";
      }
    }
    return; # nothing to check
  }

  my $leeway = $args{leeway} || 0;
  my $now = time;

  ### exp
  if(defined $payload->{exp}) {
    if (!defined $args{verify_exp} || $args{verify_exp}==1) {
      _check_numeric_date($payload, 'exp');
      croak "JWT: exp claim check failed ($payload->{exp}/$leeway vs. $now)" if $payload->{exp} + $leeway <= $now;
    }
  }
  elsif ($args{verify_exp} && $args{verify_exp}==1) {
    croak "JWT: exp claim required but missing"
  }

  ### nbf
  if(defined $payload->{nbf}) {
    if (!defined $args{verify_nbf} || $args{verify_nbf}==1) {
      _check_numeric_date($payload, 'nbf');
      croak "JWT: nbf claim check failed ($payload->{nbf}/$leeway vs. $now)" if $payload->{nbf} - $leeway > $now;
    }
  }
  elsif ($args{verify_nbf} && $args{verify_nbf}==1) {
    croak "JWT: nbf claim required but missing"
  }

  ### iat
  if (exists $args{verify_iat}) { #default (non existing verify_iat) == no iat check
    if(defined $payload->{iat}) {
      if (!defined $args{verify_iat} || $args{verify_iat}==1) {
        _check_numeric_date($payload, 'iat');
        croak "JWT: iat claim check failed ($payload->{iat}/$leeway vs. $now)" if $payload->{iat} - $leeway > $now;
      }
    }
    elsif ($args{verify_iat} && $args{verify_iat}==1) {
      croak "JWT: iat claim required but missing"
    }
  }

  ### aud
  if (defined $args{verify_aud}) {
    my $check = $args{verify_aud};
    if (exists $payload->{aud}) {
      my $match = 0;
      # aud claim is a bit special as it can be either a string or an array of strings
      my @aud_list = ref $payload->{aud} eq 'ARRAY' ? @{$payload->{aud}} : ( $payload->{aud} );
      for my $value (@aud_list) {
        if (ref $check eq 'Regexp') {
          $value = "" if !defined $value;
          $match = 1 if $value =~ $check;
        }
        elsif (ref $check eq 'CODE') {
          $match = 1 if $check->($value);
        }
        elsif (!ref $check) {
          $match = 1 if defined $value && $value eq $check;
        }
      }
      croak "JWT: aud claim check failed" if !$match;
    }
    else {
      croak "JWT: aud claim required but missing"
    }
  }

  ### iss, sub, jti
  foreach my $claim (qw(iss sub jti)) {
    my $check = $args{"verify_$claim"};
    next unless (defined $check);

    if (exists $payload->{$claim}) {
      if (ref $check eq 'Regexp') {
        my $value = $payload->{$claim};
        $value = "" if !defined $value;
        croak "JWT: $claim claim re check failed" unless $value =~ $check;
      }
      elsif (ref $check eq 'CODE') {
        croak "JWT: $claim claim code check failed" unless $check->($payload->{$claim});
      }
      elsif (!ref $check) {
        my $value = $payload->{$claim};
        croak "JWT: $claim claim scalar check failed" unless defined $value && $value eq $check;
      }
      else {
        croak "JWT: verify_$claim must be Regexp, Scalar or CODE";
      }
    }
    else {
      croak "JWT: $claim claim required but missing"
    }
  }

}

sub _payload_zip {
  my ($payload, $header, $z) = @_;
  my @zip = ref $z eq 'ARRAY' ? @$z : ($z);
  if ($zip[0] eq 'deflate') {
    my $level = defined $zip[1] ? $zip[1] : 6;
    $header->{zip} = "DEF";
    my $d = Compress::Raw::Zlib::Deflate->new(-Bufsize => 1024, -WindowBits => -&MAX_WBITS(), -AppendOutput => 1, -Level => $level );
    my $output = '';
    $d->deflate($payload, $output) == Z_OK or croak "JWT: deflate failed";
    $d->flush($output) == Z_OK             or croak "JWT: deflate/flush failed";
    croak "JWT: deflate/output failed" unless $output;
    $payload = $output;
  }
  else {
    croak "JWT: unknown zip method '$zip[0]'";
  }
  return $payload;
}

sub _payload_unzip {
  my ($payload, $z) = @_;
  if ($z eq "DEF") {
    my $d = Compress::Raw::Zlib::Inflate->new(
      -Bufsize     => $MAX_INFLATED_SIZE,
      -WindowBits  => -&MAX_WBITS(),
      -LimitOutput => 1,
    );
    my $output = '';
    my $status = $d->inflate($payload, $output);
    croak "JWT: inflated payload exceeds limit ($MAX_INFLATED_SIZE bytes)" if $status == Z_BUF_ERROR;
    croak "JWT: inflate failed (status=$status)" if $status != Z_STREAM_END;
    $payload = $output;
  }
  else {
    croak "JWT: unknown zip method '$z'";
  }
  return $payload;
}

sub _payload_enc {
  my ($payload) = @_;
  if (ref($payload) =~ /^(HASH|ARRAY)$/) {
    $payload = JSON->new->utf8->canonical->encode($payload);
  }
  else {
    utf8::downgrade($payload, 1) or croak "JWT: payload cannot contain wide character";
  }
  return $payload;
}

sub _payload_dec {
  my ($payload, $decode_payload) = @_;
  return $payload if defined $decode_payload && $decode_payload == 0;
  my $de = $payload;
  $de = eval { decode_json($de) };
  if ($decode_payload) {
    croak "JWT: payload not a valid JSON" unless $de;
    return $de;
  }
  else {
    return defined $de ? $de : $payload;
  }
}

sub _encrypt_jwe_cek {
  my ($key, $hdr) = @_;
  my $alg = $hdr->{alg};
  my $enc = $hdr->{enc};

  if ($alg eq 'dir') {
    return (_prepare_oct_key($key), '');
  }

  my $cek;
  my $ecek;
  if ($enc =~ /^A(128|192|256)GCM/) {
    $cek = random_bytes($1/8);
  }
  elsif ($enc =~ /^A(128|192|256)CBC/) {
    $cek = random_bytes(2*$1/8);
  }

  if ($alg =~ /^A(128|192|256)KW$/) {
    # RFC 7518 sec 4.4 wraps via "AES Key Wrap algorithm specified in RFC 3394"
    $ecek = aes_key_wrap(_prepare_oct_key($key), $cek, 'AES', 0);
    return ($cek, $ecek);
  }
  elsif ($alg =~ /^A(128|192|256)GCMKW$/) {
    my ($t, $i);
    ($ecek, $t, $i) = gcm_key_wrap(_prepare_oct_key($key), $cek);
    $hdr->{tag} = encode_b64u($t);
    $hdr->{iv}  = encode_b64u($i);
    return ($cek, $ecek);
  }
  elsif ($alg =~ /^PBES2-HS(512|384|256)\+A(128|192|256)KW$/) {
    my $len = looks_like_number($hdr->{p2s}) && $hdr->{p2s} >= 8 && $hdr->{p2s} <= 9999 ? $hdr->{p2s} : 16;
    my $salt = random_bytes($len);
    my $iter = looks_like_number($hdr->{p2c}) ? $hdr->{p2c} : 5000;
    $ecek = pbes2_key_wrap(_prepare_oct_key($key), $cek, $alg, $salt, $iter);
    $hdr->{p2s} = encode_b64u($salt);
    $hdr->{p2c} = $iter;
    return ($cek, $ecek);
  }
  elsif ($alg =~ /^RSA(-OAEP|-OAEP-256|1_5)$/) {
    $key = _prepare_rsa_key($key);
    $ecek = rsa_key_wrap($key, $cek, $alg);
    return ($cek, $ecek);
  }
  elsif ($alg =~ /^ECDH-ES\+A(128|192|256)KW$/) {
    $key = _prepare_ecdh_key($key);
    ($ecek, $hdr->{epk}) = ecdhaes_key_wrap($key, $cek, $alg, $hdr->{apu}, $hdr->{apv});
    return ($cek, $ecek);
  }
  elsif ($alg eq 'ECDH-ES') {
    $key = _prepare_ecdh_key($key);
    ($cek, $hdr->{epk}) = ecdh_key_wrap($key, $enc, $hdr->{apu}, $hdr->{apv});
    return ($cek, '');
  }
  croak "JWE: unknown alg '$alg'";
}

sub _decrypt_jwe_cek {
  my ($ecek, $key, $hdr) = @_;
  my $alg = $hdr->{alg};
  my $enc = $hdr->{enc};

  if ($alg eq 'dir') {
    return _prepare_oct_key($key);
  }
  elsif ($alg =~ /^A(128|192|256)KW$/) {
    return aes_key_unwrap(_prepare_oct_key($key), $ecek, 'AES', 0);
  }
  elsif ($alg =~ /^A(128|192|256)GCMKW$/) {
    return gcm_key_unwrap(_prepare_oct_key($key), $ecek, decode_b64u($hdr->{tag}), decode_b64u($hdr->{iv}));
  }
  elsif ($alg =~ /^PBES2-HS(512|384|256)\+A(128|192|256)KW$/) {
    my $p2c = $hdr->{p2c};
    croak "JWE: invalid p2c" unless looks_like_number($p2c) && $p2c >= 1 && $p2c <= $MAX_PBES2_ITER;
    return pbes2_key_unwrap(_prepare_oct_key($key), $ecek, $alg, decode_b64u($hdr->{p2s}), $p2c);
  }
  elsif ($alg =~ /^RSA(-OAEP|-OAEP-256|1_5)$/) {
    $key = _prepare_rsa_key($key);
    return rsa_key_unwrap($key, $ecek, $alg);
  }
  elsif ($alg =~ /^ECDH-ES\+A(128|192|256)KW$/) {
    $key = _prepare_ecdh_key($key);
    return ecdhaes_key_unwrap($key, $ecek, $alg, $hdr->{epk}, $hdr->{apu}, $hdr->{apv});
  }
  elsif ($alg eq 'ECDH-ES') {
    $key = _prepare_ecdh_key($key);
    return ecdh_key_unwrap($key, $enc, $hdr->{epk}, $hdr->{apu}, $hdr->{apv});
  }
  croak "JWE: unknown alg '$alg'";
}

sub _encrypt_jwe_payload {
  my ($cek, $enc, $b64u_header, $b64u_aad, $payload) = @_;
  my $aad = defined $b64u_aad ? "$b64u_header.$b64u_aad" : $b64u_header;
  if ($enc =~ /^A(128|192|256)GCM$/) {
    # https://tools.ietf.org/html/rfc7518#section-5.3
    my $len1 = $1/8;
    my $len2 = length($cek);
    croak "JWE: wrong AES key length ($len1 vs. $len2) for $enc" unless $len1 == $len2;
    my $iv = random_bytes(12); # for AESGCM always 12 (96 bits)
    my ($ct, $tag) = gcm_encrypt_authenticate('AES', $cek, $iv, $aad, $payload);
    return ($ct, $iv, $tag);
  }
  elsif ($enc =~ /^A(128|192|256)CBC-HS(256|384|512)$/) {
    # https://tools.ietf.org/html/rfc7518#section-5.2
    my ($size, $hash) = ($1/8, "SHA$2");
    my $key_len = length($cek) / 2;
    my $mac_key = substr($cek, 0, $key_len);
    my $aes_key = substr($cek, $key_len, $key_len);
    croak "JWE: wrong AES key length ($key_len vs. $size)" unless $key_len == $size;
    my $iv = random_bytes(16); # for AES always 16
    my $m = Crypt::Mode::CBC->new('AES');
    my $ct = $m->encrypt($payload, $aes_key, $iv);
    my $aad_len = length($aad);
    # RFC 7518 5.2.2.1: AL = AAD length in bits as 64-bit big-endian.
    # Split aad_len*8 into two 32-bit halves; both intermediate values
    # stay within 32-bit range, so this is safe on 32-bit Perl too.
    my $al_hi = $aad_len >> 29;
    my $al_lo = ($aad_len & 0x1FFFFFFF) << 3;
    my $mac_input = $aad . $iv . $ct . pack('N2', $al_hi, $al_lo);
    my $mac = hmac($hash, $mac_key, $mac_input);
    my $sig_len = length($mac) / 2;
    my $sig = substr($mac, 0, $sig_len);
    return ($ct, $iv, $sig);
  }
  croak "JWE: unsupported enc '$enc'";
}

sub _decrypt_jwe_payload {
  my ($cek, $enc, $aad, $ct, $iv, $tag) = @_;
  if ($enc =~ /^A(128|192|256)GCM$/) {
    # https://tools.ietf.org/html/rfc7518#section-5.3
    my $len1 = $1/8;
    my $len2 = length($cek);
    croak "JWE: wrong AES key length ($len1 vs. $len2) for $enc" unless $len1 == $len2;
    return gcm_decrypt_verify('AES', $cek, $iv, $aad, $ct, $tag);
  }
  elsif ($enc =~ /^A(128|192|256)CBC-HS(256|384|512)$/) {
    # https://tools.ietf.org/html/rfc7518#section-5.2
    my ($size, $hash) = ($1/8, "SHA$2");
    my $key_len = length($cek) / 2;
    my $mac_key = substr($cek, 0, $key_len);
    my $aes_key = substr($cek, $key_len, $key_len);
    croak "JWE: wrong AES key length ($key_len vs. $size)" unless $key_len == $size;
    my $aad_len = length($aad); # AAD == original encoded header
    # RFC 7518 5.2.2.1: AL = AAD length in bits as 64-bit big-endian.
    # Split aad_len*8 into two 32-bit halves; both intermediate values
    # stay within 32-bit range, so this is safe on 32-bit Perl too.
    my $al_hi = $aad_len >> 29;
    my $al_lo = ($aad_len & 0x1FFFFFFF) << 3;
    my $mac_input = $aad . $iv . $ct . pack('N2', $al_hi, $al_lo);
    my $mac = hmac($hash, $mac_key, $mac_input);
    my $sig_len = length($mac) / 2;
    my $sig = substr($mac, 0, $sig_len);
    croak "JWE: tag mismatch" unless slow_eq($sig, $tag);
    my $m = Crypt::Mode::CBC->new('AES');
    my $pt = $m->decrypt($ct, $aes_key, $iv);
    return $pt;
  }
  croak "JWE: unsupported enc '$enc'";
}

sub _encode_jwe {
  my %args = @_;
  my $payload = $args{payload};
  my $alg     = $args{alg};
  my $enc     = $args{enc};
  my $header  = $args{extra_headers} ? \%{$args{extra_headers}} : {};
  croak "JWE: missing 'enc'" if !defined $enc;
  croak "JWE: missing 'payload'" if !defined $payload;
  # add claims to payload
  _add_claims($payload, %args) if ref $payload eq 'HASH';
  # serialize payload
  $payload = _payload_enc($payload);
  # compress payload
  $payload = _payload_zip($payload, $header, $args{zip}) if $args{zip}; # may set some header items
  # prepare header
  $header->{alg} = $alg;
  $header->{enc} = $enc;
  # key
  croak "JWE: missing 'key'" if !$args{key};
  my $key = defined $args{keypass} ? [$args{key}, $args{keypass}] : $args{key};
  # prepare cek
  my ($cek, $ecek) = _encrypt_jwe_cek($key, $header); # adds some header items
  # encode header
  my $json_header = encode_json($header);
  my $b64u_header = encode_b64u($json_header);
  my $b64u_aad    = defined $args{aad} ? encode_b64u($args{aad}) : undef;
  # encrypt payload
  my ($ct, $iv, $tag) = _encrypt_jwe_payload($cek, $enc, $b64u_header, $b64u_aad, $payload);
  # return token parts
  return ( $b64u_header,
           encode_b64u($ecek),
           encode_b64u($iv),
           encode_b64u($ct),
           encode_b64u($tag),
           $b64u_aad);
}

sub _decode_jwe {
  my ($b64u_header, $b64u_ecek, $b64u_iv, $b64u_ct, $b64u_tag, $b64u_aad, $unprotected, $shared_unprotected, %args) = @_;
  my $header = _b64u_to_hash($b64u_header);
  my $ecek   = decode_b64u($b64u_ecek);
  my $ct     = decode_b64u($b64u_ct);
  my $iv     = decode_b64u($b64u_iv);
  my $tag    = decode_b64u($b64u_tag);
  croak "JWE: invalid header part" if $b64u_header && !$header;
  croak "JWE: invalid ecek part"   if $b64u_ecek   && !$ecek;
  croak "JWE: invalid ct part"     if $b64u_ct     && !$ct;
  croak "JWE: invalid iv part"     if $b64u_iv     && !$iv;
  croak "JWE: invalid tag part"    if $b64u_tag    && !$tag;

  my $key;
  if (exists $args{key}) {
    $key = defined $args{keypass} ? [$args{key}, $args{keypass}] : $args{key};
  }
  elsif (exists $args{kid_keys}) {
    # BEWARE: stricter approach since 0.023
    # when 'kid_keys' specified it croaks if header doesn't contain 'kid' value or if 'kid' wasn't found in 'kid_keys'
    my $k = _kid_lookup($header->{kid}, $args{kid_keys}, $header->{alg});
    croak "JWE: kid_keys lookup failed" if !defined $k;
    $key = $k;
  }
  croak "JWE: missing key" if !defined $key;

  _check_accepted('alg', $header->{alg}, $args{accepted_alg});
  _check_accepted('enc', $header->{enc}, $args{accepted_enc});
  # For 'dir' the JWK is used directly as the CEK, so its 'alg' field (when
  # present) names the content-encryption algorithm (the JWE 'enc'), not
  # 'dir' itself. RFC 7518 sec 3.4.2 / common JWK convention.
  my $effective_alg = defined $header->{alg} && $header->{alg} eq 'dir' ? $header->{enc} : $header->{alg};
  _check_jwk_constraints($key, $effective_alg, 'JWE');

  # SECURITY INVARIANT: merge order matters. The protected header (%$header)
  # MUST come last so its values win over the unprotected/shared-unprotected
  # ones (which travel outside the AEAD and are attacker-mutable). Crypto-
  # critical fields - 'alg', 'enc', 'epk', 'p2c', 'p2s', 'iv', 'tag', 'zip',
  # 'apu', 'apv' - are read from this merged hash by _decrypt_jwe_cek and
  # below; flipping the order, or letting _decrypt_jwe_cek run against an
  # attacker-controlled header, breaks the JWE security model.
  $header = { %$shared_unprotected, %$unprotected, %$header };
  my $cek = _decrypt_jwe_cek($ecek, $key, $header);
  my $aad = defined $b64u_aad ? "$b64u_header.$b64u_aad" : $b64u_header;
  my $payload = _decrypt_jwe_payload($cek, $header->{enc}, $aad, $ct, $iv, $tag);
  $payload = _payload_unzip($payload, $header->{zip}) if $header->{zip};
  $payload = _payload_dec($payload, $args{decode_payload});
  _verify_claims($payload, %args); # croaks on error
  _verify_header($header, %args); # croaks on error
  return ($header, $payload);
}

sub _sign_jws {
  my ($b64u_header, $b64u_payload, $alg, $key) = @_;
  return '' if $alg eq 'none'; # no integrity
  my $sig;
  my $data = "$b64u_header.$b64u_payload";
  if ($alg =~ /^HS(256|384|512)$/) { # HMAC integrity
    $key = _prepare_oct_key($key);
    croak "JWS: HMAC key shorter than minimum ($MIN_HMAC_KEY_LEN bytes)" if length($key) < $MIN_HMAC_KEY_LEN;
    $sig = hmac("SHA$1", $key, $data);
  }
  elsif ($alg =~ /^RS(256|384|512)/) { # RSA+PKCS1-V1_5 signatures
    my $pk = _prepare_rsa_key($key);
    $sig  = $pk->sign_message($data, "SHA$1", 'v1.5');
  }
  elsif ($alg =~ /^PS(256|384|512)/) { # RSA+PSS signatures
    my $hash = "SHA$1";
    my $hashlen = $1/8;
    my $pk = _prepare_rsa_key($key);
    $sig  = $pk->sign_message($data, $hash, 'pss', $hashlen);
  }
  elsif ($alg =~ /^ES(256|256K|384|512)$/) { # ECDSA signatures
    my $hash = {ES256 => 'SHA256', ES256K => 'SHA256', ES384 => 'SHA384', ES512 => 'SHA512'}->{$alg};
    my $pk = _prepare_ecc_key($key);
    $sig  = $pk->sign_message_rfc7518($data, $hash);
  }
  elsif ($alg eq 'EdDSA') { # Ed25519 signatures
    my $pk = _prepare_ed25519_key($key);
    $sig  = $pk->sign_message($data);
  }
  return encode_b64u($sig);
}

sub _verify_jws {
  my ($b64u_header, $b64u_payload, $b64u_sig, $alg, $key) = @_;
  my $sig = decode_b64u($b64u_sig);
  croak "JWS: invalid sig part" if $b64u_sig && !$sig;
  my $data = "$b64u_header.$b64u_payload";

  if ($alg eq 'none' ) { # no integrity
    return 1;
  }
  elsif ($alg =~ /^HS(256|384|512)$/) { # HMAC integrity
    $key = _prepare_oct_key($key);
    croak "JWS: HMAC key shorter than minimum ($MIN_HMAC_KEY_LEN bytes)" if length($key) < $MIN_HMAC_KEY_LEN;
    return 1 if slow_eq($sig, hmac("SHA$1", $key, $data));
  }
  elsif ($alg =~ /^RS(256|384|512)/) { # RSA+PKCS1-V1_5 signatures
    my $hash = "SHA$1";
    my $pk = _prepare_rsa_key($key);
    return 1 if $pk->verify_message($sig, $data, $hash, 'v1.5');
  }
  elsif ($alg =~ /^PS(256|384|512)/) { # RSA+PSS signatures
    my $hash = "SHA$1";
    my $hashlen = $1/8;
    my $pk = _prepare_rsa_key($key);
    return 1 if $pk->verify_message($sig, $data, $hash, 'pss', $hashlen);
  }
  elsif ($alg =~ /^ES(256|256K|384|512)$/) { # ECDSA signatures
    my $hash = {ES256 => 'SHA256', ES256K => 'SHA256', ES384 => 'SHA384', ES512 => 'SHA512'}->{$alg};
    my $pk = _prepare_ecc_key($key);
    return 1 if $pk->verify_message_rfc7518($sig, $data, $hash);
  }
  elsif ($alg eq 'EdDSA') { # Ed25519 signatures
    my $pk = _prepare_ed25519_key($key);
    return 1 if $pk->verify_message($sig, $data);
  }
  return 0;
}

sub _encode_jws {
  my %args = @_;
  my $payload = $args{payload};
  my $alg     = $args{alg};
  my $header  = $args{extra_headers} ? \%{$args{extra_headers}} : {};
  croak "JWS: missing 'payload'" if !defined $payload;
  croak "JWS: alg 'none' not allowed" if $alg eq 'none' && !$args{allow_none};
  # add claims to payload
  _add_claims($payload, %args) if ref $payload eq 'HASH';
  # serialize payload
  $payload = _payload_enc($payload);
  # compress payload
  $payload = _payload_zip($payload, $header, $args{zip}) if $args{zip}; # may set some header items
  # encode payload
  my $b64u_payload = encode_b64u($payload);
  # prepare header
  $header->{alg} = $alg;
  # encode header
  my $json_header = encode_json($header);
  my $b64u_header = encode_b64u($json_header);
  # key
  croak "JWS: missing 'key'" if !$args{key} && $alg ne 'none';
  my $key = defined $args{keypass} ? [$args{key}, $args{keypass}] : $args{key};
  # sign header
  my $b64u_signature = _sign_jws($b64u_header, $b64u_payload, $alg, $key);
  return ($b64u_header, $b64u_payload, $b64u_signature);
}

sub _decode_jws {
  my ($b64u_header, $b64u_payload, $b64u_sig, $unprotected_header, %args) = @_;
  my $header = _b64u_to_hash($b64u_header);
  croak "JWS: invalid header part" if $b64u_header && !$header;
  $unprotected_header = {} if ref $unprotected_header ne 'HASH';

  if (!$args{ignore_signature}) {
    my $alg = $header->{alg};
    croak "JWS: missing header 'alg'" unless $alg;
    croak "JWS: alg 'none' not allowed" if $alg eq 'none' && !$args{allow_none};
    croak "JWS: alg 'none' expects no signature" if $alg eq 'none' && defined $b64u_sig && length($b64u_sig) > 0;

    _check_accepted('alg', $alg, $args{accepted_alg});

    if ($alg ne 'none') {
      my $key;
      if (exists $args{key}) {
        $key = defined $args{keypass} ? [$args{key}, $args{keypass}] : $args{key};
      }
      elsif (exists $args{kid_keys}) {
        # BEWARE: stricter approach since 0.023
        # when 'kid_keys' specified it croaks if header doesn't contain 'kid' value or if 'kid' wasn't found in 'kid_keys'
        my $kid = exists $header->{kid} ? $header->{kid} : $unprotected_header->{kid};
        my $k = _kid_lookup($kid, $args{kid_keys}, $alg);
        croak "JWS: kid_keys lookup failed" if !defined $k;
        $key = $k;
      }
      elsif ($args{key_from_jwk_header}) {
        # BEWARE: stricter approach since 0.023
        # - header 'jwk' is by default ignored (unless given: key_from_jwk_header => 1)
        # - only RSA/ECDSA public keys are accepted
        my $k = $header->{jwk};
        croak "JWS: jwk header does not contain a key" if !defined $k || ref($k) ne 'HASH' || !defined $k->{kty};
        croak "JWS: jwk header allowed only for RSA/ECDSA" if $alg !~ /^(RS|PS|ES)/ || $k->{kty} !~ /^(RSA|EC)$/;
        croak "JWS: jwk header must be a public key" if $k->{d} || $k->{p} || $k->{q} || $k->{dp} || $k->{dq} || $k->{qi};
        $key = $k;
      }
      croak "JWS: missing key" if !defined $key;
      _check_jwk_constraints($key, $alg, 'JWS');

      my $valid = _verify_jws($b64u_header, $b64u_payload, $b64u_sig, $alg, $key);
      croak "JWS: invalid signature" if !$valid;
    }
  }
  my $payload = decode_b64u($b64u_payload);
  croak "JWS: invalid payload part" if $b64u_payload && !$payload;
  $payload = _payload_unzip($payload, $header->{zip}) if $header->{zip};
  $payload = _payload_dec($payload, $args{decode_payload});
  _verify_claims($payload, %args); # croaks on error
  $header = { %$unprotected_header, %$header }; # merge headers
  _verify_header($header, %args); # croaks on error
  return ($header, $payload);
}

sub encode_jwt {
  my %args = @_;

  croak "JWT: missing 'alg'" unless $args{alg};
  my $ser = $args{serialization} || 'compact';
  if ($args{alg} =~ /^(none|EdDSA|(HS|RS|PS)(256|384|512)|ES(256|256K|384|512))$/) {
    ###JWS
    my ($b64u_header, $b64u_payload, $b64u_signature) = _encode_jws(%args);
    if ($ser eq 'compact') { # https://tools.ietf.org/html/rfc7515#section-7.1
      croak "JWT: cannot use 'unprotected_headers' with compact serialization" if defined $args{unprotected_headers};
      return "$b64u_header.$b64u_payload.$b64u_signature";
    }
    elsif ($ser eq 'flattened') { # https://tools.ietf.org/html/rfc7515#section-7.2.2
      my $token = { protected => $b64u_header, payload => $b64u_payload, signature => $b64u_signature };
      $token->{header} = \%{$args{unprotected_headers}} if ref $args{unprotected_headers} eq 'HASH';
      return encode_json($token);
    }
    else {
      croak "JWT: unsupported JWS serialization '$ser'";
    }
  }
  elsif ($args{alg} =~ /^(dir|A(128|192|256)KW|A(128|192|256)GCMKW|PBES2-(HS256\+A128KW|HS384\+A192KW|HS512\+A256KW)|RSA-OAEP|RSA-OAEP-256|RSA1_5|ECDH-ES\+A(128|192|256)KW|ECDH-ES)$/) {
    ### JWE
    my ($b64u_header, $b64u_ecek, $b64u_iv, $b64u_ct, $b64u_tag, $b64u_aad) = _encode_jwe(%args);
    if ($ser eq 'compact') { # https://tools.ietf.org/html/rfc7516#section-7.1
      croak "JWT: cannot use 'aad' with compact serialization" if defined $args{aad};
      croak "JWT: cannot use 'unprotected_headers' with compact serialization" if defined $args{unprotected_headers};
      croak "JWT: cannot use 'shared_unprotected_headers' with compact serialization" if defined $args{shared_unprotected_headers};
      return "$b64u_header.$b64u_ecek.$b64u_iv.$b64u_ct.$b64u_tag";
    }
    elsif ($ser eq 'flattened') { # https://tools.ietf.org/html/rfc7516#section-7.2.2
      my $token = {
        protected     => $b64u_header,
        encrypted_key => $b64u_ecek,
        iv            => $b64u_iv,
        ciphertext    => $b64u_ct,
        tag           => $b64u_tag,
      };
      # header: JWE Per-Recipient Unprotected Header when the JWE Per-Recipient Unprotected Header
      $token->{header} = \%{$args{unprotected_headers}} if ref $args{unprotected_headers} eq 'HASH';
      # unprotected: JWE Shared Unprotected Header
      $token->{unprotected} = \%{$args{shared_unprotected_headers}} if ref $args{shared_unprotected_headers} eq 'HASH';
      # aad: Additional Authenticated Data (AAD)
      $token->{aad} = $b64u_aad if defined $b64u_aad;
      return encode_json($token);
    }
    else {
      croak "JWT: unsupported JWE serialization '$ser'";
    }
  }
  else {
      croak "JWT: unexpected alg '$args{alg}'";
  }
}

sub decode_jwt {
  my %args = @_;
  my ($header, $payload);

  if (!$args{token}) {
    croak "JWT: missing token";
  }
  my $token_re = $args{tolerate_padding} ? $TOKEN_RE_PADDING : $TOKEN_RE_STRICT;
  if ($args{token} =~ $token_re) {
    if (defined($5) && length($5) > 0) {
        # JWE token (5 segments)
        ($header, $payload) = _decode_jwe($1, $2, $3, $4, $5, undef, {}, {}, %args);
    }
    else {
        # JWS token (3 segments)
        ($header, $payload) = _decode_jws($1, $2, $3, {}, %args);
    }
  }
  elsif ($args{token} =~ /^\s*\{.*?\}\s*$/s) {
    my $hash = decode_json($args{token});
    if (defined $hash->{payload} && $hash->{protected}) {
      # Flattened JWS JSON Serialization
      ($header, $payload) = _decode_jws($hash->{protected}, $hash->{payload}, $hash->{signature}, $hash->{header}, %args);
    }
    elsif ($hash->{ciphertext} && $hash->{protected}) {
      # Flattened JWE JSON Serialization
      ($header, $payload) = _decode_jwe($hash->{protected}, $hash->{encrypted_key}, $hash->{iv}, $hash->{ciphertext}, $hash->{tag}, $hash->{aad}, $hash->{header}, $hash->{unprotected}, %args);
    }
    else {
      croak "JWT: unsupported JWS/JWT JSON Serialization";
    }
  }
  else {
    croak "JWT: invalid token format";
  }
  return ($header, $payload) if $args{decode_header};
  return $payload;
}

1;

#### URLs
# https://metacpan.org/pod/JSON::WebToken
# https://metacpan.org/pod/Mojo::JWT
# https://bitbucket.org/b_c/jose4j/wiki/JWE%20Examples
# https://bitbucket.org/b_c/jose4j/wiki/JWS%20Examples
# https://github.com/dvsekhvalnov/jose-jwt/tree/master/JWT/jwe
# https://github.com/progrium/ruby-jwt
# https://github.com/jpadilla/pyjwt/

=pod

=head1 NAME

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

=head1 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');

=head1 DESCRIPTION

Implements B - L.
The implementation covers not only B - L,
but also B - L.

The module implements all algorithms defined in L - B.

This module supports B and B serialization. General (multi-recipient) JSON serialization is not supported.

=head1 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';

=head1 FUNCTIONS

=head2 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 C 1>). Croaks
on any verification, decryption, or claim-check failure.

Named arguments:

=over

=item token

Mandatory. The serialized JWS or JWE token as a string. Both compact
(C<.>-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);

=item key

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

B B how the C argument is shaped matters.

=over

=item *

A bare scalar (e.g. C<'secret'>) is always interpreted as a raw octet
string (HMAC secret, AES key, etc.).

=item *

PEM, DER, and JWK-JSON key material B be passed as a SCALAR ref
(C<\$pem>) or as an appropriate key object - never as a bare string.

=item *

If a public-key string is mistakenly passed as a bare scalar and
C is not set, an attacker who flips the token's C to
C can forge a signature using the public-key bytes as the HMAC
secret (the so-called "alg confusion" attack).

=item *

For defense in depth, B pin the algorithm with C.

=back

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

=item keypass

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

=item 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 L 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 L

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

B An alternative structure (used e.g. by L) 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 C item, the corresponding key is looked up in the C list and used for token
decoding (you do not need to pass the explicit key via the C parameter). Add a C header on the encode side via L.

B When C is specified, decoding croaks if the token header does not contain a C value or
if the C was not found in C.

=item key_from_jwk_header

B

C<1> - use C header value for validating JWS signature if neither C nor C specified, B

C<0> (default) - ignore C header value when validating JWS signature

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

=item allow_none

C<1> - accept JWS tokens with C 'alg' header value (which means that token has no signature), B

C<0> (default) - do not allow JWS with C 'alg' header value

=item ignore_signature

C<1> - do not check signature on JWS tokens, B

C<0> (default) - check signature on JWS tokens

=item accepted_alg

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

Accepted value types:

=over

=item *

C (default) - accept all C algorithms except C (for accepting C use C)

=item *

Scalar string - the single accepted C name

=item *

ARRAY ref - list of accepted C names

=item *

C - the C value must match this regexp

=back

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

B 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.

=item accepted_enc

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

Accepted value types (same shape as L):

=over

=item *

C (default) - accept all C algorithms

=item *

Scalar string - the single accepted C name

=item *

ARRAY ref - list of accepted C names

=item *

C - the C value must match this regexp

=back

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

=item decode_payload

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

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

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

=item decode_header

C<0> (default) - C returns just the decoded payload (scalar
context).

C<1> - C returns C<($header, $payload)>; useful when you need
to inspect the JWT header (e.g. C, C, C).

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

=item verify_iss

B If C is specified and the
C (Issuer) claim is completely missing, verification fails.

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

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

C - 'iss' claim value has to be equal to given string. B

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

=item verify_aud

B If C is specified and the
C (Audience) claim is completely missing, verification fails.

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

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

C - 'aud' claim value has to be equal to given string. B

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

B The C 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.

=item verify_sub

B If C is specified and the
C (Subject) claim is completely missing, verification fails.

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

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

C - 'sub' claim value has to be equal to given string. B

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

=item verify_jti

B If C is specified and the
C (JWT ID) claim is completely missing, verification fails.

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

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

C - 'jti' claim value has to be equal to given string. B

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

=item verify_iat

B C is asymmetric with C/C.
Omitting the key entirely (the true default) means "no iat check".
Passing C undef> is B the same as omitting it - it
explicitly enables the present-but-must-be-valid check below.

C - "validate-if-present" mode: if the payload contains an 'iat'
claim it must not be in the future (modulo C), 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.

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

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

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

=item verify_nbf

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

C<0> - ignore 'nbf' claim

C<1> - require valid 'nbf' claim

=item verify_exp

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

C<0> - ignore 'exp' claim

C<1> - require valid 'exp' claim

=item leeway

Tolerance in seconds related to C, C and C. Default is C<0>.

=item ignore_claims

C<1> - do not check claims (iat, exp, nbf, iss, aud, sub, jti), B

C<0> (default) - check claims

=item verify_typ

B

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

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

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

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

=item tolerate_padding

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

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

C<1> - keep C<=> 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.

=back

=head2 encode_jwt

 my $token = encode_jwt(%named_args);

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

Named arguments:

=over

=item 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');

=item 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

=item enc

The 'enc' header is mandatory for JWE tokens.

Supported 'enc' algorithms:

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

=item key

A key used for token encryption (JWE) or token signing (JWS). The value depends on C 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

=item keypass

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

=item allow_none

C<1> - allow JWS with C 'alg' header value (which means that token has no signature), B

C<0> (default) - do not allow JWS with C 'alg' header value

=item 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 C you can set PBES2 salt len (p2s) in bytes and
iteration count (p2c) via C 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 C value (see L):

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

=item unprotected_headers

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

=item shared_unprotected_headers

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

=item aad

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

=item serialization

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

General JSON serialization is not supported yet.

=item zip

Compression method, currently 'deflate' is the only one supported. C (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]);

=item auto_iat

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

C<0> (default) - do not set the C claim.

B takes effect only when the C argument is a HASH ref;
silently ignored for string/ARRAY-ref payloads. Same applies to
C and C.

=item relative_exp

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

=item relative_nbf

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

=back

=head1 SECURITY CONSIDERATIONS

=head2 Configuration knobs

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

=over

=item C<$Crypt::JWT::MAX_PBES2_ITER> (default C<3_000_000>)

Maximum accepted PBES2 C (iteration count) on decode. Caps CPU time
spent on PBKDF2 for an attacker-controlled token. B

=item C<$Crypt::JWT::MAX_INFLATED_SIZE> (default C<10 * 1024 * 1024>)

Maximum size (in bytes) of a payload after C inflation. Caps
memory blow-up from "zip-bomb" tokens. B

=item C<$Crypt::JWT::MIN_HMAC_KEY_LEN> (default C<4>)

Minimum HMAC key length (bytes) for HS256/384/512. See L
minimums> below for the rationale and recommended override values.
B

=item C<$Crypt::JWT::MIN_RSA_BITS> (default C<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).
B

=back

=head2 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.

=over

=item *

BnE:> minimum length B<4 bytes> (overridable via
C<$Crypt::JWT::MIN_HMAC_KEY_LEN>). Applies to C and
C on the HS256 / HS384 / HS512 paths. Tokens that try to sign
or verify with a shorter key are rejected with a croak.

B this default is intentionally B 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.

=item *

B minimum B<2048 bits> (overridable via
C<$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".

=back

=head1 SEE ALSO

L, L, L, L, L, L

=head1 LICENSE

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

=head1 COPYRIGHT

Copyright (c) 2015-2026 DCIT, a.s. L / Karel Miko