.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "JSON::WebToken 3pm"
.TH JSON::WebToken 3pm 2024-09-01 "perl v5.40.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
JSON::WebToken \- JSON Web Token (JWT) implementation
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\&  use Test::More;
\&  use JSON;
\&  use JSON::WebToken;
\&
\&  my $claims = {
\&      iss => \*(Aqjoe\*(Aq,
\&      exp => 1300819380,
\&      \*(Aqhttp://example.com/is_root\*(Aq => JSON::true,
\&  };
\&  my $secret = \*(Aqsecret\*(Aq;
\&
\&  my $jwt = encode_jwt $claims, $secret;
\&  my $got = decode_jwt $jwt, $secret;
\&  is_deeply $got, $claims;
\&
\&  done_testing;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
JSON::WebToken is JSON Web Token (JWT) implementation for Perl
.PP
\&\fBTHIS MODULE IS ALPHA LEVEL INTERFACE.\fR
.SH METHODS
.IX Header "METHODS"
.ie n .SS "encode($claims [, $secret, $algorithm, $extra_headers ]) : String"
.el .SS "encode($claims [, \f(CW$secret\fP, \f(CW$algorithm\fP, \f(CW$extra_headers\fP ]) : String"
.IX Subsection "encode($claims [, $secret, $algorithm, $extra_headers ]) : String"
This method is encoding JWT from hash reference.
.PP
.Vb 9
\&  my $jwt = JSON::WebToken\->encode({
\&      iss => \*(Aqjoe\*(Aq,
\&      exp => 1300819380,
\&      \*(Aqhttp://example.com/is_root\*(Aq => JSON::true,
\&  }, \*(Aqsecret\*(Aq);
\&  # $jwt = join \*(Aq.\*(Aq,
\&  #     \*(AqeyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\*(Aq,
\&  #     \*(AqeyJleHAiOjEzMDA4MTkzODAsImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlLCJpc3MiOiJqb2UifQ\*(Aq
\&  #     \*(Aq4ldFxjibgJGz_uaIRCIq89b5ipR\-sbI2Uq7B2WNEDs0\*(Aq
.Ve
.PP
Default encryption algorithm is \f(CW\*(C`HS256\*(C'\fR. You can change algorithm as following:
.PP
.Vb 2
\&  my $pricate_key_string = \*(Aq...\*(Aq;
\&  my $public_key_string  = \*(Aq...\*(Aq;
\&
\&  my $jwt = JSON::WebToken\->encode({
\&      iss => \*(Aqjoe\*(Aq,
\&      exp => 1300819380,
\&      \*(Aqhttp://example.com/is_root\*(Aq => JSON::true,
\&  }, $pricate_key_string, \*(AqRS256\*(Aq);
\&
\&  my $claims = JSON::WebToken\->decode($jwt, $public_key_string);
.Ve
.PP
When you use RS256, RS384 or RS512 algorithm then, We need Crypt::OpenSSL::RSA.
.PP
If you want to create a \f(CW\*(C`Plaintext JWT\*(C'\fR, should be specify \f(CW\*(C`none\*(C'\fR for the algorithm.
.PP
.Vb 9
\&  my $jwt = JSON::WebToken\->encode({
\&      iss => \*(Aqjoe\*(Aq,
\&      exp => 1300819380,
\&      \*(Aqhttp://example.com/is_root\*(Aq => JSON::true,
\&  }, \*(Aq\*(Aq, \*(Aqnone\*(Aq);
\&  # $jwt = join \*(Aq.\*(Aq,
\&  #     \*(AqeyJhbGciOiJub25lIiwidHlwIjoiSldUIn0\*(Aq,
\&  #     \*(AqeyJleHAiOjEzMDA4MTkzODAsImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlLCJpc3MiOiJqb2UifQ\*(Aq,
\&  #     \*(Aq\*(Aq
.Ve
.ie n .SS "decode($jwt [, $secret, $verify_signature, $accepted_algorithms ]) : HASH"
.el .SS "decode($jwt [, \f(CW$secret\fP, \f(CW$verify_signature\fP, \f(CW$accepted_algorithms\fP ]) : HASH"
.IX Subsection "decode($jwt [, $secret, $verify_signature, $accepted_algorithms ]) : HASH"
This method is decoding hash reference from JWT string.
.PP
.Vb 1
\&  my $claims = JSON::WebToken\->decode($jwt, $secret, 1, ["RS256"]);
.Ve
.PP
Any signing algorithm (except "none") is acceptable by default,
so you should check it with \f(CW$accepted_algorithms\fR parameter.
.ie n .SS "add_signing_algorithm($algorithm, $class)"
.el .SS "add_signing_algorithm($algorithm, \f(CW$class\fP)"
.IX Subsection "add_signing_algorithm($algorithm, $class)"
This method is adding signing algorithm.
.PP
.Vb 2
\&  # resolve JSON::WebToken::Crypt::MYALG
\&  JSON::WebToken\->add_signing_algorithm(\*(AqMYALGXXX\*(Aq   => \*(AqMYALG\*(Aq);
\&
\&  # resolve Some::Class::Algorithm
\&  JSON::WebToken\->add_signing_algorithm(\*(AqSOMEALGXXX\*(Aq => \*(Aq+Some::Class::Algorithm\*(Aq);
.Ve
.PP
SEE ALSO JSON::WebToken::Crypt::HMAC or JSON::WebToken::Crypt::RAS.
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.ie n .SS "encode_jwt($claims [, $secret, $algorithm, $extra_headers ]) : String"
.el .SS "encode_jwt($claims [, \f(CW$secret\fP, \f(CW$algorithm\fP, \f(CW$extra_headers\fP ]) : String"
.IX Subsection "encode_jwt($claims [, $secret, $algorithm, $extra_headers ]) : String"
Same as \f(CWencode()\fR method.
.ie n .SS "decode_jwt($jwt [, $secret, $verify_signature, $accepted_algorithms ]) : Hash"
.el .SS "decode_jwt($jwt [, \f(CW$secret\fP, \f(CW$verify_signature\fP, \f(CW$accepted_algorithms\fP ]) : Hash"
.IX Subsection "decode_jwt($jwt [, $secret, $verify_signature, $accepted_algorithms ]) : Hash"
Same as \f(CWdecode()\fR method.
.SH "ERROR CODES"
.IX Header "ERROR CODES"
JSON::WebToken::Exception will be thrown with following code.
.SS ERROR_JWT_INVALID_PARAMETER
.IX Subsection "ERROR_JWT_INVALID_PARAMETER"
When some method arguments are not valid.
.SS ERROR_JWT_MISSING_SECRET
.IX Subsection "ERROR_JWT_MISSING_SECRET"
When secret is required. (\f(CW\*(C`alg != "none"\*(C'\fR)
.SS ERROR_JWT_INVALID_SEGMENT_COUNT
.IX Subsection "ERROR_JWT_INVALID_SEGMENT_COUNT"
When JWT segment count is not between 2 and 4.
.SS ERROR_JWT_INVALID_SEGMENT_ENCODING
.IX Subsection "ERROR_JWT_INVALID_SEGMENT_ENCODING"
When each JWT segment is not encoded by base64url.
.SS ERROR_JWT_UNWANTED_SIGNATURE
.IX Subsection "ERROR_JWT_UNWANTED_SIGNATURE"
When \f(CW\*(C`alg == "none"\*(C'\fR but signature segment found.
.SS ERROR_JWT_INVALID_SIGNATURE
.IX Subsection "ERROR_JWT_INVALID_SIGNATURE"
When JWT signature is invalid.
.SS ERROR_JWT_NOT_SUPPORTED_SIGNING_ALGORITHM
.IX Subsection "ERROR_JWT_NOT_SUPPORTED_SIGNING_ALGORITHM"
When given signing algorithm is not supported.
.SS ERROR_JWT_UNACCEPTABLE_ALGORITHM
.IX Subsection "ERROR_JWT_UNACCEPTABLE_ALGORITHM"
When given signing algorithm is not included in acceptable_algorithms.
.SH AUTHOR
.IX Header "AUTHOR"
xaicron <xaicron@cpan.org>
.PP
zentooo
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2012 \- xaicron
.SH LICENSE
.IX Header "LICENSE"
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
<http://tools.ietf.org/html/draft\-ietf\-oauth\-json\-web\-token>