.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" 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 .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . 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 .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Mojo::JWT 3pm" .TH Mojo::JWT 3pm "2018-12-22" "perl v5.28.1" "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" Mojo::JWT \- JSON Web Token the Mojo way .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& my $jwt = Mojo::JWT\->new(claims => {...}, secret => \*(Aqs3cr3t\*(Aq)\->encode; \& my $claims = Mojo::JWT\->new(secret => \*(Aqs3cr3t\*(Aq)\->decode($jwt); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\s-1JSON\s0 Web Token is described in . Mojo::JWT implements that standard with an \s-1API\s0 that should feel familiar to Mojolicious users (though of course it is useful elsewhere). Indeed, \s-1JWT\s0 is much like Mojolicious::Sessions except that the result is a url-safe text string rather than a cookie. .PP In \s-1JWT,\s0 the primary payload is called the \f(CW\*(C`claims\*(C'\fR, and a few claims are reserved, as seen in the \s-1IETF\s0 document. The header and the claims are signed when stringified to guard against tampering. Note that while signed, the data is not encrypted, so don't use it to send secrets over clear channels. .SH "ATTRIBUTES" .IX Header "ATTRIBUTES" Mojo::JWT inherits all of the attributes from Mojo::Base and implements the following new ones. .SS "algorithm" .IX Subsection "algorithm" The algorithm to be used to sign a \s-1JWT\s0 during encoding or else the algorithm that was used for the most recent decoding. Defaults to \f(CW\*(C`HS256\*(C'\fR until a decode is performed. .PP \&\f(CW\*(C`none\*(C'\fR is an acceptable encoding algorithm, however for it to be used to decode, \*(L"allow_none\*(R" must be set. .SS "allow_none" .IX Subsection "allow_none" To prevent spoofing attacks, \f(CW\*(C`allow_none\*(C'\fR must be explicitly set to a true value otherwise decoding a \s-1JWT\s0 which specifies the \f(CW\*(C`none\*(C'\fR algorithm will result in an exception. The default is of course false. .SS "claims" .IX Subsection "claims" The payload to be encoded or else the claims from the most recent decoding. This must be a hash reference, array references are not allowed as the top-level \s-1JWT\s0 claims. .SS "expires" .IX Subsection "expires" The epoch time value after which the \s-1JWT\s0 value should not be considered valid. This value (if set and not undefined) will be used as the \f(CW\*(C`exp\*(C'\fR key in the claims or was extracted from the claims during the most recent decoding. .SS "header" .IX Subsection "header" You may set your own headers when encoding the \s-1JWT\s0 bypassing a hash reference to the \*(L"header\*(R" attribute. Please note that there are two default headers set. \fBalg\fR is set to the value of \*(L"algorithm\*(R" or '\s-1HS256\s0' and \fBtyp\fR is set to '\s-1JWT\s0'. These cannot be overridden. .SS "not_before" .IX Subsection "not_before" The epoch time value before which the \s-1JWT\s0 value should not be considered valid. This value (if set and not undefined) will be used as the \f(CW\*(C`nbf\*(C'\fR key in the claims or was extracted from the claims during the most recent decoding. .SS "public" .IX Subsection "public" The public key to be used in decoding an asymmetrically signed \s-1JWT\s0 (eg. \s-1RSA\s0). .SS "secret" .IX Subsection "secret" The symmetric secret (eg. \s-1HMAC\s0) or else the private key used in encoding an asymmetrically signed \s-1JWT\s0 (eg. \s-1RSA\s0). .SS "set_iat" .IX Subsection "set_iat" If true (false by default), then the \f(CW\*(C`iat\*(C'\fR claim will be set to the value of \*(L"now\*(R" during \*(L"encode\*(R". .SH "METHODS" .IX Header "METHODS" Mojo::JWT inherits all of the methods from Mojo::Base and implements the following new ones. .SS "decode" .IX Subsection "decode" .Vb 1 \& my $claims = $jwt\->decode($token); \& \& my $peek = sub { my ($jwt, $claims) = @_; ... }; \& my $claims = $jwt\->decode($token, $peek); .Ve .PP Decode and parse a \s-1JSON\s0 Web Token string and return the claims hashref. Calling this function immediately sets the \*(L"token\*(R" to the passed in token. It also sets \*(L"algorithm\*(R" to \f(CW\*(C`undef\*(C'\fR and unsets \*(L"claims\*(R", \*(L"expires\*(R" and \*(L"not_before\*(R". These values are then set as part of the parsing process. .PP Parsing occurs as follows .IP "\(bu" 4 The \*(L"algorithm\*(R" is extracted from the header and set, if not present or permissible an exception is thrown .IP "\(bu" 4 If a \f(CW$peek\fR callback is provided, it is called with the instance and claims as arguments .IP "\(bu" 4 The signature is verified or an exception is thrown .IP "\(bu" 4 The timing claims (\*(L"expires\*(R" and \*(L"not_before\*(R"), if present, are evaluated, failures result in exceptions. On success the values are set in the relevant attributes .IP "\(bu" 4 The \*(L"claims\*(R" attribute is set and the claims are returned. .PP Note that when the \f(CW$peek\fR callback is invoked, the claims have not yet been verified. This callback is most likely to be used to inspect the \f(CW\*(C`iss\*(C'\fR or issuer claim to determine a secret or key for decoding. The return value is ignored, changes should be made to the instances attributes directly. Since the \*(L"algorithm\*(R" has already been parsed, it is available via the instance attribute as well. .SS "encode" .IX Subsection "encode" .Vb 1 \& my $token = $jwt\->encode; .Ve .PP Encode the data expressed in the instance attributes: \*(L"algorithm\*(R", \*(L"claims\*(R", \*(L"expires\*(R", \*(L"not_before\*(R". Note that if the timing attributes are given, they override existing keys in the \*(L"claims\*(R". Calling \f(CW\*(C`encode\*(C'\fR immediately clears the \*(L"token\*(R" and upon completion sets it to the result as well as returning it. .PP Note also that due to Perl's hash randomization, repeated encoding is not guaranteed to result in the same encoded string. However any encoded string will survive an encode/decode roundtrip. .SS "header" .IX Subsection "header" .Vb 1 \& my $header = $jwt\->header; .Ve .PP Returns a hash reference representing the \s-1JWT\s0 header, constructed from instance attributes (see \*(L"algorithm\*(R"). .SS "now" .IX Subsection "now" .Vb 1 \& my $time = $jwt\->now; .Ve .PP Returns the current time, currently implemented as the core \f(CW\*(C`time\*(C'\fR function. .SS "sign_hmac" .IX Subsection "sign_hmac" .Vb 1 \& my $signature = $jwt\->sign_hmac($size, $payload); .Ve .PP Returns the \s-1HMAC SHA\s0 signature for the given size and payload. The \*(L"secret\*(R" attribute is used as the symmetric key. The result is not yet base64 encoded. This method is provided mostly for the purposes of subclassing. .SS "sign_rsa" .IX Subsection "sign_rsa" .Vb 1 \& my $signature = $jwt\->sign_rsa($size, $payload); .Ve .PP Returns the \s-1RSA\s0 signature for the given size and payload. The \*(L"secret\*(R" attribute is used as the private key. The result is not yet base64 encoded. This method is provided mostly for the purposes of subclassing. .SS "token" .IX Subsection "token" The most recently encoded or decoded token. Note that any attribute modifications are not taken into account until \*(L"encode\*(R" is called again. .SS "verify_rsa" .IX Subsection "verify_rsa" .Vb 1 \& my $bool = $jwt\->verify_rsa($size, $payload, $signature); .Ve .PP Returns true if the given \s-1RSA\s0 size algorithm validates the given payload and signature. The \*(L"public\*(R" attribute is used as the public key. This method is provided mostly for the purposes of subclassing. .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "Acme::JWT" 4 .IX Item "Acme::JWT" .PD 0 .IP "JSON::WebToken" 4 .IX Item "JSON::WebToken" .IP "" 4 .IX Item "" .PD .SH "SOURCE REPOSITORY" .IX Header "SOURCE REPOSITORY" .SH "AUTHOR" .IX Header "AUTHOR" Joel Berger, .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" Christopher Raa (mishanti1) .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright (C) 2015 by \*(L"\s-1AUTHOR\*(R"\s0 and \*(L"\s-1CONTRIBTORS\*(R"\s0. .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.