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

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

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

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

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

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

FUNCTIONS
  decode_jwt
     my $data = decode_jwt(%named_args);

    Named arguments:

    token (mandatory)
        A string with either JWS or JWE JSON Web Token.

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

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

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

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

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

    keypass (optional, default: "undef")
        When 'key' parameter is an encrypted private RSA or ECC key this
        parameter may contain a password for private key decryption.

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

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

    ignore_signature (optional, default: 0)
        1 - do not check signature on JWS tokens, BEWARE: DANGEROUS,
        UNSECURE!!!

        0 - check signature on JWS tokens

    accepted_alg (optional, default: "undef")
        "undef" means accept all 'alg' algorithms except 'none' (for
        accepting 'none' use "allow_none")

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

        "ARRAY ref" a list of accepted 'alg' algorithms

        "Regexp" that has to match 'alg' algorithm name

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

    accepted_enc (optional, default: "undef")
        "undef" means accept all 'enc' algorithms

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

        "ARRAY ref" a list of accepted 'enc' algorithms

        "Regexp" that has to match 'enc' algorithm name

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

    decode_payload (optional, default: "undef")
        0 - do not decode payload, return it as a raw string (octects).

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

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

    decode_header (optional, default: 0)
        0 - do not return decoded header as a return value of decode_jwt()

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

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

  encode_jwt
     my $token = encode_jwt(%named_args);

    Named arguments:

    payload (mandatory)
        Value of this parameter can be a string/buffer or HASH ref or ARRAY
        ref

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

        HASH refs and ARRAY refs payloads are serialized as JSON strings

    alg (mandatory)
        Supported JWE 'alg' algorithms:

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

        Supported JWS algorithms:

         none   ...  no integrity (NOTE: disabled by default)
         HS256  ...  HMAC+SHA256 integrity
         HS384  ...  HMAC+SHA384 integrity
         HS512  ...  HMAC+SHA512 integrity
         RS256  ...  RSA+PKCS1-V1_5 + SHA256 signature
         RS384  ...  RSA+PKCS1-V1_5 + SHA384 signature
         RS512  ...  RSA+PKCS1-V1_5 + SHA512 signature
         PS256  ...  RSA+PSS + SHA256 signature
         PS384  ...  RSA+PSS + SHA384 signature
         PS512  ...  RSA+PSS + SHA512 signature
         ES256  ...  ECDSA + SHA256 signature
         ES384  ...  ECDSA + SHA384 signature
         ES512  ...  ECDSA + SHA512 signature

    enc (mandatory, for JWE only)
        Supported 'enc' algorithms:

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

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

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

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

    keypass (optional, default: "undef")
        When 'key' parameter is an encrypted private RSA or ECC key this
        parameter may contain a password for private key decryption.

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

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

    extra_headers (optional, default: "undef")
        This parameter may contain a HASH ref with items that will be added
        to JWT header.

    zip (optional, default: "undef")
        Compression method, currently 'deflate' is the only one supported.

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

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

