Crypt::JWT(3pm)

1Crypt::JWT(3)         User Contributed Perl Documentation        Crypt::JWT(3)
2
3
4

NAME

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

SYNOPSIS

10          # encoding
11          use Crypt::JWT qw(encode_jwt);
12          my $jws_token = encode_jwt(payload=>$data, alg=>'HS256', key=>'secret');
13          my $jwe_token = encode_jwt(payload=>$data, alg=>'PBES2-HS256+A128KW', enc=>'A128GCM', key=>'secret');
14
15          # decoding
16          use Crypt::JWT qw(decode_jwt);
17          my $data1 = decode_jwt(token=>$jws_token, key=>'secret');
18          my $data2 = decode_jwt(token=>$jwe_token, key=>'secret');
19

DESCRIPTION

21       Implements JSON Web Token (JWT) -
22       <https://tools.ietf.org/html/rfc7519>.  The implementation covers not
23       only JSON Web Signature (JWS) - <https://tools.ietf.org/html/rfc7515>,
24       but also JSON Web Encryption (JWE) -
25       <https://tools.ietf.org/html/rfc7516>.
26
27       The module implements all (100%) algorithms defined in
28       <https://tools.ietf.org/html/rfc7518> - JSON Web Algorithms (JWA).
29
30       This module supports Compact JWS/JWE and Flattened JWS/JWE JSON
31       serialization, general JSON serialization is not supported yet.
32

EXPORT

34       Nothing is exported by default.
35
36       You can export selected functions:
37
38         use Crypt::JWT qw(decode_jwt encode_jwt);
39
40       Or all of them at once:
41
42         use Crypt::JWT ':all';
43

FUNCTIONS

45   decode_jwt
46        my $data = decode_jwt(%named_args);
47
48       Named arguments:
49
50       token
51           Mandatory argument, a string with either JWS or JWE JSON Web Token.
52
53            ### JWS token example (3 segments)
54            $t = "eyJhbGciOiJIUzI1NiJ9.dGVzdA.ujBihtLSr66CEWqN74SpLUkv28lra_CeHnxLmLNp4Jo";
55            my $data = decode_jwt(token=>$t, key=>$k);
56
57            ### JWE token example (5 segments)
58            $t = "eyJlbmMiOiJBMTI4R0NNIiwiYWxnIjoiQTEyOEtXIn0.UusxEbzhGkORxTRq0xkFKhvzPrXb9smw.VGfOuq0Fxt6TsdqLZUpnxw.JajIQQ.pkKZ7MHS0XjyGmRsqgom6w";
59            my $data = decode_jwt(token=>$t, key=>$k);
60
61       key A key used for token decryption (JWE) or token signature validation
62           (JWS).  The value depends on the "alg" token header value.
63
64            JWS alg header      key value
65            ------------------  ----------------------------------
66            none                no key required
67            HS256               string (raw octects) of any length (or perl HASH ref with JWK, kty=>'oct')
68            HS384               dtto
69            HS512               dtto
70            RS256               public RSA key, perl HASH ref with JWK key structure,
71                                a reference to SCALAR string with PEM or DER or JSON/JWK data,
72                                object: Crypt::PK::RSA, Crypt::OpenSSL::RSA, Crypt::X509 or Crypt::OpenSSL::X509
73            RS384               public RSA key, see RS256
74            RS512               public RSA key, see RS256
75            PS256               public RSA key, see RS256
76            PS384               public RSA key, see RS256
77            PS512               public RSA key, see RS256
78            ES256               public ECC key, perl HASH ref with JWK key structure,
79                                a reference to SCALAR string with PEM or DER or JSON/JWK data,
80                                an instance of Crypt::PK::ECC
81            ES256K              public ECC key, see ES256
82            ES384               public ECC key, see ES256
83            ES512               public ECC key, see ES256
84            EdDSA               public Ed25519 key
85
86            JWE alg header      key value
87            ------------------  ----------------------------------
88            dir                 string (raw octects) or perl HASH ref with JWK, kty=>'oct', length depends on 'enc' algorithm
89            A128KW              string (raw octects) 16 bytes (or perl HASH ref with JWK, kty=>'oct')
90            A192KW              string (raw octects) 24 bytes (or perl HASH ref with JWK, kty=>'oct')
91            A256KW              string (raw octects) 32 bytes (or perl HASH ref with JWK, kty=>'oct')
92            A128GCMKW           string (raw octects) 16 bytes (or perl HASH ref with JWK, kty=>'oct')
93            A192GCMKW           string (raw octects) 24 bytes (or perl HASH ref with JWK, kty=>'oct')
94            A256GCMKW           string (raw octects) 32 bytes (or perl HASH ref with JWK, kty=>'oct')
95            PBES2-HS256+A128KW  string (raw octects) of any length (or perl HASH ref with JWK, kty=>'oct')
96            PBES2-HS384+A192KW  string (raw octects) of any length (or perl HASH ref with JWK, kty=>'oct')
97            PBES2-HS512+A256KW  string (raw octects) of any length (or perl HASH ref with JWK, kty=>'oct')
98            RSA-OAEP            private RSA key, perl HASH ref with JWK key structure,
99                                a reference to SCALAR string with PEM or DER or JSON/JWK data,
100                                an instance of Crypt::PK::RSA or Crypt::OpenSSL::RSA
101            RSA-OAEP-256        private RSA key, see RSA-OAEP
102            RSA1_5              private RSA key, see RSA-OAEP
103            ECDH-ES             private ECC or X25519 key, perl HASH ref with JWK key structure,
104                                a reference to SCALAR string with PEM or DER or JSON/JWK data,
105                                an instance of Crypt::PK::ECC
106            ECDH-ES+A128KW      private ECC or X25519 key, see ECDH-ES
107            ECDH-ES+A192KW      private ECC or X25519 key, see ECDH-ES
108            ECDH-ES+A256KW      private ECC or X25519 key, see ECDH-ES
109
110           Example using the key from "jwk" token header:
111
112            my $data = decode_jwt(token=>$t, key_from_jwk_header=>1);
113            my ($header, $data) = decode_jwt(token=>$t, decode_header=>1, key_from_jwk_header=>1);
114
115           Examples with raw octet keys:
116
117            #string
118            my $data = decode_jwt(token=>$t, key=>'secretkey');
119            #binary key
120            my $data = decode_jwt(token=>$t, key=>pack("H*", "788A6E38F36B7596EF6A669E94"));
121            #perl HASH ref with JWK structure (key type 'oct')
122            my $data = decode_jwt(token=>$t, key=>{kty=>'oct', k=>"GawgguFyGrWKav7AX4VKUg"});
123
124           Examples with RSA keys:
125
126            my $pem_key_string = <<'EOF';
127            -----BEGIN PRIVATE KEY-----
128            MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCoVm/Sl5r+Ofky
129            jioRSZK26GW6WyjyfWKddsSi13/NOtCn0rRErSF/u3QrgGMpWFqKohqbi1VVC+SZ
130            ...
131            8c1vm2YFafgdkSk9Qd1oU2Fv1aOQy4VovOFzJ3CcR+2r7cbRfcpLGnintHtp9yek
132            02p+d5g4OChfFNDhDtnIqjvY
133            -----END PRIVATE KEY-----
134            EOF
135
136            my $jwk_key_json_string = '{"kty":"RSA","n":"0vx7agoebG...L6tSoc_BJECP","e":"AQAB"}';
137
138            #a reference to SCALAR string with PEM or DER or JSON/JWK data,
139            my $data = decode_jwt(token=>$t, key=>\$pem_key_string);
140            my $data = decode_jwt(token=>$t, key=>\$der_key_string);
141            my $data = decode_jwt(token=>$t, key=>\$jwk_key_json_string);
142
143            #instance of Crypt::PK::RSA
144            my $data = decode_jwt(token=>$t, key=>Crypt::PK::RSA->new('keyfile.pem'));
145            my $data = decode_jwt(token=>$t, key=>Crypt::PK::RSA->new(\$pem_key_string));
146
147            #instance of Crypt::OpenSSL::RSA
148            my $data = decode_jwt(token=>$t, key=>Crypt::OpenSSL::RSA->new_private_key($pem_key_string));
149
150            #instance of Crypt::X509 (public key only)
151            my $data = decode_jwt(token=>$t, key=>Crypt::X509->new(cert=>$cert));
152
153            #instance of Crypt::OpenSSL::X509 (public key only)
154            my $data = decode_jwt(token=>$t, key=>Crypt::OpenSSL::X509->new_from_file('cert.pem'));
155            my $data = decode_jwt(token=>$t, key=>Crypt::OpenSSL::X509->new_from_string($cert));
156
157            #perl HASH ref with JWK structure (key type 'RSA')
158            my $rsa_priv = {
159              kty => "RSA",
160              n   => "0vx7agoebGcQSuuPiLJXZpt...eZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
161              e   => "AQAB",
162              d   => "X4cTteJY_gn4FYPsXB8rdXi...FLN5EEaG6RoVH-HLKD9Mdx5ooGURknhnrRwUkC7h5fJLMWbFAKLWY2v7B6NqSzUvx0_YSf",
163              p   => "83i-7IvMGXoMXCskv73TKr8...Z27zvoj6pbUQyLPBQxtPnwD20-60eTmD2ujMt5PoMrm8RmNhVWtjjMmMjOpSicFHjXOuVI",
164              q   => "3dfOR9cuYq-0S-mkFLzgItg...q3hWeMuG0ouqnb3obLyuqjVZQ1dIrdgTnCdYzBcOW5r37AFXjift_NGiovonzhKpoVVS78",
165              dp  => "G4sPXkc6Ya9y8oJW9_ILj4...zi_H7TkS8x5SdX3oE0oiYwxIiemTAu0UOa5pgFGyJ4c8t2VF40XRugKTP8akhFo5tA77Qe",
166              dq  => "s9lAH9fggBsoFR8Oac2R_E...T2kGOhvIllTE1efA6huUvMfBcpn8lqW6vzzYY5SSF7pMd_agI3G8IbpBUb0JiraRNUfLhc",
167              qi  => "GyM_p6JrXySiz1toFgKbWV...4ypu9bMWx3QJBfm0FoYzUIZEVEcOqwmRN81oDAaaBk0KWGDjJHDdDmFW3AN7I-pux_mHZG",
168            };
169            my $data = decode_jwt(token=>$t, key=>$rsa_priv});
170
171           Examples with ECC keys:
172
173            my $pem_key_string = <<'EOF';
174            -----BEGIN EC PRIVATE KEY-----
175            MHcCAQEEIBG1c3z52T8XwMsahGVdOZWgKCQJfv+l7djuJjgetdbDoAoGCCqGSM49
176            AwEHoUQDQgAEoBUyo8CQAFPeYPvv78ylh5MwFZjTCLQeb042TjiMJxG+9DLFmRSM
177            lBQ9T/RsLLc+PmpB1+7yPAR+oR5gZn3kJQ==
178            -----END EC PRIVATE KEY-----
179            EOF
180
181            my $jwk_key_json_string = '{"kty":"EC","crv":"P-256","x":"MKB..7D4","y":"4Et..FyM"}';
182
183            #a reference to SCALAR string with PEM or DER or JSON/JWK data,
184            my $data = decode_jwt(token=>$t, key=>\$pem_key_string);
185            my $data = decode_jwt(token=>$t, key=>\$der_key_string);
186            my $data = decode_jwt(token=>$t, key=>\$jwk_key_json_string);
187
188            #instance of Crypt::PK::ECC
189            my $data = decode_jwt(token=>$t, key=>Crypt::PK::ECC->new('keyfile.pem'));
190            my $data = decode_jwt(token=>$t, key=>Crypt::PK::ECC->new(\$pem_key_string));
191
192            #perl HASH ref with JWK structure (key type 'EC')
193            my $ecc_priv = {
194              kty => "EC",
195              crv => "P-256",
196              x   => "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
197              y   => "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
198              d   => "870MB6gfuTJ4HtUnUvYMyJpr5eUZNP4Bk43bVdj3eAE",
199            };
200            my $data = decode_jwt(token=>$t, key=>$ecc_priv});
201
202       keypass
203           When 'key' parameter is an encrypted private RSA or ECC key this
204           optional parameter may contain a password for private key
205           decryption.
206
207       kid_keys
208           This parametes can be either a JWK Set JSON string (see RFC7517) or
209           a perl HASH ref with JWK Set structure like this:
210
211             my $keylist = {
212               keys => [
213                 { kid=>"key1", kty=>"oct", k=>"GawgguFyGrWKav7AX4VKUg" },
214                 { kid=>"key2", kty=>"oct", k=>"ulxLGy4XqhbpkR5ObGh1gX" },
215               ]
216             };
217             my $payload = decode_jwt(token=>$t, kid_keys=>$keylist);
218
219           You can use "export_key_jwk" in Crypt::PK::RSA to generate a JWK
220           for RSA:
221
222             my $pubkey = Crypt::PK::RSA->new('rs256-4096-public.pem');
223             my $jwk_hash = $pubkey->export_key_jwk('public', 1);
224             $jwk_hash->{kid} = 'key1';
225             my $keylist = {
226               keys => [
227                 $jwk_hash,
228               ]
229             };
230
231           The structure described above is used e.g. by
232           <https://www.googleapis.com/oauth2/v2/certs>
233
234             use Mojo::UserAgent;
235             my $ua = Mojo::UserAgent->new;
236             my $google_keys => $ua->get('https://www.googleapis.com/oauth2/v2/certs')->result->json;
237             my $payload = decode_jwt(token => $t, kid_keys => $google_keys);
238
239           SINCE 0.019 we also support alternative structure used e.g. by
240           <https://www.googleapis.com/oauth2/v1/certs>:
241
242             use LWP::Simple;
243             my $google_certs = get('https://www.googleapis.com/oauth2/v1/certs');
244             my $payload = decode_jwt(token => $t, kid_keys => $google_certs);
245
246           When the token header contains "kid" item the corresponding key is
247           looked up in "kid_keys" list and used for token decoding (you do
248           not need to pass the explicit key via "key" parameter). Add a kid
249           header using "extra_headers".
250
251           INCOMPATIBLE CHANGE in 0.023: When "kid_keys" is specified it
252           croaks if token header does not contain "kid" value or if "kid" was
253           not found in "kid_keys".
254
255       key_from_jwk_header
256           SINCE 0.023
257
258           1 - use "jwk" header value for validating JWS signature if neither
259           "key" nor "kid_keys" specified, BEWARE: DANGEROUS, UNSECURE!!!
260
261           0 (default) - ignore "jwk" header value when validating JWS
262           signature
263
264           Keep in mind that enabling "key_from_jwk_header" requires "jwk"
265           header to exist and be an valid RSA/ECDSA public key (otherwise it
266           croaks).
267
268       allow_none
269           1 - accept JWS tokens with "none" 'alg' header value (which means
270           that token has no signature), BEWARE: DANGEROUS, UNSECURE!!!
271
272           0 (default) - do not allow JWS with "none" 'alg' header value
273
274       ignore_signature
275           1 - do not check signature on JWS tokens, BEWARE: DANGEROUS,
276           UNSECURE!!!
277
278           0 (default) - check signature on JWS tokens
279
280       accepted_alg
281           "undef" (default) means accept all 'alg' algorithms except 'none'
282           (for accepting 'none' use "allow_none")
283
284           "string" name of accepted 'alg' algorithm (only one)
285
286           "ARRAY ref" a list of accepted 'alg' algorithms
287
288           "Regexp" that has to match 'alg' algorithm name
289
290            my $payload = decode_jwt(token=>$t, key=>$k, accepted_alg=>'HS256');
291            #or
292            my $payload = decode_jwt(token=>$t, key=>$k, accepted_alg=>['HS256','HS384']);
293            #or
294            my $payload = decode_jwt(token=>$t, key=>$k, accepted_alg=>qr/^HS(256|384|512)$/);
295
296       accepted_enc
297           "undef" (default) means accept all 'enc' algorithms
298
299           "string" name of accepted 'enc' algorithm (only one)
300
301           "ARRAY ref" a list of accepted 'enc' algorithms
302
303           "Regexp" that has to match 'enc' algorithm name
304
305            my $payload = decode_jwt(token=>$t, key=>$k, accepted_enc=>'A192GCM');
306            #or
307            my $payload = decode_jwt(token=>$t, key=>$k, accepted_enc=>['A192GCM','A256GCM']);
308            #or
309            my $payload = decode_jwt(token=>$t, key=>$k, accepted_enc=>qr/^A(128|192|256)GCM$/);
310
311       decode_payload
312           0 - do not decode payload, return it as a raw string (octects).
313
314           1 - decode payload from JSON string, return it as perl hash ref (or
315           array ref) - decode_json failure means fatal error (croak).
316
317           "undef" (default) - if possible decode payload from JSON string, if
318           decode_json fails return payload as a raw string (octets).
319
320       decode_header
321           0 (default) - do not return decoded header as a return value of
322           decode_jwt()
323
324           1 - return decoded header as a return value of decode_jwt()
325
326            my $payload = decode_jwt(token=>$t, key=>$k);
327            #or
328            my ($header, $payload) = decode_jwt(token=>$t, key=>$k, decode_header=>1);
329
330       verify_iss
331           INCOMPATIBLE CHANGE in 0.024: If "verify_iss" is specified and
332           claim "iss" (Issuer) is completely missing it is a failure since
333           0.024
334
335           "CODE ref" - subroutine (with 'iss' claim value passed as argument)
336           should return "true" otherwise verification fails
337
338           "Regexp ref" - 'iss' claim value has to match given regexp
339           otherwise verification fails
340
341           "Scalar" - 'iss' claim value has to be equal to given string (since
342           0.029)
343
344           "undef" (default) - do not verify 'iss' claim
345
346       verify_aud
347           INCOMPATIBLE CHANGE in 0.024: If "verify_aud" is specified and
348           claim "aud" (Audience) is completely missing it is a failure since
349           0.024
350
351           "CODE ref" - subroutine (with 'aud' claim value passed as argument)
352           should return "true" otherwise verification fails
353
354           "Regexp ref" - 'aud' claim value has to match given regexp
355           otherwise verification fails
356
357           "Scalar" - 'aud' claim value has to be equal to given string (since
358           0.029)
359
360           "undef" (default) - do not verify 'aud' claim
361
362       verify_sub
363           INCOMPATIBLE CHANGE in 0.024: If "verify_sub" is specified and
364           claim "sub" (Subject) is completely missing it is a failure since
365           0.024
366
367           "CODE ref" - subroutine (with 'sub' claim value passed as argument)
368           should return "true" otherwise verification fails
369
370           "Regexp ref" - 'sub' claim value has to match given regexp
371           otherwise verification fails
372
373           "Scalar" - 'sub' claim value has to be equal to given string (since
374           0.029)
375
376           "undef" (default) - do not verify 'sub' claim
377
378       verify_jti
379           INCOMPATIBLE CHANGE in 0.024: If "verify_jti" is specified and
380           claim "jti" (JWT ID) is completely missing it is a failure since
381           0.024
382
383           "CODE ref" - subroutine (with 'jti' claim value passed as argument)
384           should return "true" otherwise verification fails
385
386           "Regexp ref" - 'jti' claim value has to match given regexp
387           otherwise verification fails
388
389           "Scalar" - 'jti' claim value has to be equal to given string (since
390           0.029)
391
392           "undef" (default) - do not verify 'jti' claim
393
394       verify_iat
395           "undef" - Issued At 'iat' claim must be valid (not in the future)
396           if present
397
398           0 (default) - ignore 'iat' claim
399
400           1 - require valid 'iat' claim
401
402       verify_nbf
403           "undef" (default) - Not Before 'nbf' claim must be valid if present
404
405           0 - ignore 'nbf' claim
406
407           1 - require valid 'nbf' claim
408
409       verify_exp
410           "undef" (default) - Expiration Time 'exp' claim must be valid if
411           present
412
413           0 - ignore 'exp' claim
414
415           1 - require valid 'exp' claim
416
417       leeway
418           Tolerance in seconds related to "verify_exp", "verify_nbf" and
419           "verify_iat". Default is 0.
420
421       ignore_claims
422           1 - do not check claims (iat, exp, nbf, iss, aud, sub, jti),
423           BEWARE: DANGEROUS, UNSECURE!!!
424
425           0 (default) - check claims
426
427   encode_jwt
428        my $token = encode_jwt(%named_args);
429
430       Named arguments:
431
432       payload
433           Value of this mandatory parameter can be a string/buffer or HASH
434           ref or ARRAY ref
435
436            my $token = encode_jwt(payload=>"any raw data", key=>$k, alg=>'HS256');
437            #or
438            my $token = encode_jwt(payload=>{a=>1,b=>2}, key=>$k, alg=>'HS256');
439            #or
440            my $token = encode_jwt(payload=>[11,22,33,44], key=>$k, alg=>'HS256');
441
442           HASH refs and ARRAY refs payloads are serialized as JSON strings
443
444       alg The 'alg' header value is mandatory for both JWE and JWS tokens.
445
446           Supported JWE 'alg' algorithms:
447
448            dir
449            A128KW
450            A192KW
451            A256KW
452            A128GCMKW
453            A192GCMKW
454            A256GCMKW
455            PBES2-HS256+A128KW
456            PBES2-HS384+A192KW
457            PBES2-HS512+A256KW
458            RSA-OAEP
459            RSA-OAEP-256
460            RSA1_5
461            ECDH-ES+A128KW
462            ECDH-ES+A192KW
463            ECDH-ES+A256KW
464            ECDH-ES
465
466           Supported JWS algorithms:
467
468            none   ...  no integrity (NOTE: disabled by default)
469            HS256  ...  HMAC+SHA256 integrity
470            HS384  ...  HMAC+SHA384 integrity
471            HS512  ...  HMAC+SHA512 integrity
472            RS256  ...  RSA+PKCS1-V1_5 + SHA256 signature
473            RS384  ...  RSA+PKCS1-V1_5 + SHA384 signature
474            RS512  ...  RSA+PKCS1-V1_5 + SHA512 signature
475            PS256  ...  RSA+PSS + SHA256 signature
476            PS384  ...  RSA+PSS + SHA384 signature
477            PS512  ...  RSA+PSS + SHA512 signature
478            ES256  ...  ECDSA + SHA256 signature
479            ES256K ...  ECDSA + SHA256 signature
480            ES384  ...  ECDSA + SHA384 signature
481            ES512  ...  ECDSA + SHA512 signature
482            EdDSA  ...  Ed25519 signature
483
484       enc The 'enc' header is mandatory for JWE tokens.
485
486           Supported 'enc' algorithms:
487
488            A128GCM
489            A192GCM
490            A256GCM
491            A128CBC-HS256
492            A192CBC-HS384
493            A256CBC-HS512
494
495       key A key used for token encryption (JWE) or token signing (JWS). The
496           value depends on "alg" token header value.
497
498            JWS alg header      key value
499            ------------------  ----------------------------------
500            none                no key required
501            HS256               string (raw octects) of any length (or perl HASH ref with JWK, kty=>'oct')
502            HS384               dtto
503            HS512               dtto
504            RS256               private RSA key, perl HASH ref with JWK key structure,
505                                a reference to SCALAR string with PEM or DER or JSON/JWK data,
506                                object: Crypt::PK::RSA, Crypt::OpenSSL::RSA, Crypt::X509 or Crypt::OpenSSL::X509
507            RS384               private RSA key, see RS256
508            RS512               private RSA key, see RS256
509            PS256               private RSA key, see RS256
510            PS384               private RSA key, see RS256
511            PS512               private RSA key, see RS256
512            ES256               private ECC key, perl HASH ref with JWK key structure,
513                                a reference to SCALAR string with PEM or DER or JSON/JWK data,
514                                an instance of Crypt::PK::ECC
515            ES256K              private ECC key, see ES256
516            ES384               private ECC key, see ES256
517            ES512               private ECC key, see ES256
518            EdDSA               private Ed25519 key
519
520            JWE alg header      key value
521            ------------------  ----------------------------------
522            dir                 string (raw octects) or perl HASH ref with JWK, kty=>'oct', length depends on 'enc' algorithm
523            A128KW              string (raw octects) 16 bytes (or perl HASH ref with JWK, kty=>'oct')
524            A192KW              string (raw octects) 24 bytes (or perl HASH ref with JWK, kty=>'oct')
525            A256KW              string (raw octects) 32 bytes (or perl HASH ref with JWK, kty=>'oct')
526            A128GCMKW           string (raw octects) 16 bytes (or perl HASH ref with JWK, kty=>'oct')
527            A192GCMKW           string (raw octects) 24 bytes (or perl HASH ref with JWK, kty=>'oct')
528            A256GCMKW           string (raw octects) 32 bytes (or perl HASH ref with JWK, kty=>'oct')
529            PBES2-HS256+A128KW  string (raw octects) of any length (or perl HASH ref with JWK, kty=>'oct')
530            PBES2-HS384+A192KW  string (raw octects) of any length (or perl HASH ref with JWK, kty=>'oct')
531            PBES2-HS512+A256KW  string (raw octects) of any length (or perl HASH ref with JWK, kty=>'oct')
532            RSA-OAEP            public RSA key, perl HASH ref with JWK key structure,
533                                a reference to SCALAR string with PEM or DER or JSON/JWK data,
534                                an instance of Crypt::PK::RSA or Crypt::OpenSSL::RSA
535            RSA-OAEP-256        public RSA key, see RSA-OAEP
536            RSA1_5              public RSA key, see RSA-OAEP
537            ECDH-ES             public ECC or X25519 key, perl HASH ref with JWK key structure,
538                                a reference to SCALAR string with PEM or DER or JSON/JWK data,
539                                an instance of Crypt::PK::ECC
540            ECDH-ES+A128KW      public ECC or X25519 key, see ECDH-ES
541            ECDH-ES+A192KW      public ECC or X25519 key, see ECDH-ES
542            ECDH-ES+A256KW      public ECC or X25519 key, see ECDH-ES
543
544       keypass
545           When 'key' parameter is an encrypted private RSA or ECC key this
546           optional parameter may contain a password for private key
547           decryption.
548
549       allow_none
550           1 - allow JWS with "none" 'alg' header value (which means that
551           token has no signature), BEWARE: DANGEROUS, UNSECURE!!!
552
553           0 (default) - do not allow JWS with "none" 'alg' header value
554
555       extra_headers
556           This optional parameter may contain a HASH ref with items that will
557           be added to JWT header.
558
559           If you want to use PBES2-based 'alg' like "PBES2-HS512+A256KW" you
560           can set PBES2 salt len (p2s) in bytes and iteration count (p2c) via
561           "extra_headers" like this:
562
563            my $token = encode_jwt(payload=>$p, key=>$k, alg=>'PBES2-HS512+A256KW', extra_headers=>{p2c=8000, p2s=>32});
564            #NOTE: handling of p2s header is a special case, in the end it is replaced with the generated salt
565
566           You can also use this to specify a kid value (see "kid_keys")
567
568            my $token = encode_jwt(payload=>$p, key=>$k, alg => 'RS256', extra_headers=>{kid=>'key1'});
569
570       unprotected_headers
571           A hash with additional integrity unprotected headers - JWS and JWE
572           (not available for "compact" serialization);
573
574       shared_unprotected_headers
575           A hash with additional integrity unprotected headers - JWE only
576           (not available for "compact" serialization);
577
578       aad Additional Authenticated Data - scalar value with any (even raw
579           octects) data - JWE only (not available for "compact"
580           serialization);
581
582       serialization
583           Specify serialization method: "compat" (= default) for Compact
584           JWS/JWE serialization or "flattened" for Flattened JWS/JWE JSON
585           serialization.
586
587           General JSON serialization is not supported yet.
588
589       zip Compression method, currently 'deflate' is the only one supported.
590           "undef" (default) means no compression.
591
592            my $token = encode_jwt(payload=>$p, key=>$k, alg=>'HS256', zip=>'deflate');
593            #or define compression level
594            my $token = encode_jwt(payload=>$p, key=>$k, alg=>'HS256', zip=>['deflate', 9]);
595
596       auto_iat
597           1 - set 'iat' (Issued At) claim to current time (epoch seconds
598           since 1970) at the moment of token encoding
599
600           0 (default) - do not set 'iat' claim
601
602           NOTE: claims are part of the payload and can be used only if the
603           payload is a HASH ref!
604
605       relative_exp
606           Set 'exp' claim (Expiration Time) to current time + "relative_exp"
607           value (in seconds).
608
609           NOTE: claims are part of the payload and can be used only if the
610           payload is a HASH ref!
611
612       relative_nbf
613           Set 'nbf' claim (Not Before) to current time + "relative_nbf" value
614           (in seconds).
615
616           NOTE: claims are part of the payload and can be used only if the
617           payload is a HASH ref!
618

LICENSE

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

COPYRIGHT

628       Copyright (c) 2015-2023 DCIT, a.s. <https://www.dcit.cz> / Karel Miko
629
630
631
632perl v5.36.1                      2023-11-21                     Crypt::JWT(3)