JWT verification for openresty

JWT verification library for OpenResty.

The project's goal is to be a modern and slimmer replacement of the venerable lua-resty-jwt.

This project does not provide JWT manipulation or creation features: you can only verify/decrypt tokens.

Status

Ready for testing: looking for more people to take it for a spin and provide feedback.

Supported features

• JWS verification: with symmetric or asymmetric keys.
• JWE decryption: with symmetric or asymmetric keys.
• Asymmetric keys format supported:
  • PEM
  • DER
  • JWK
• JWT claim validation.

JWS Verification

Claims	Implemented
alg	✅
jku	❌
jwk	❌
kid	❌
x5u	❌
x5c	❌
x5t	❌
x5t#S256	❌
typ	✅
cty	❌
crit	✅

Alg	Implemented
HS256	✅
HS384	✅
HS512	✅
RS256	✅
RS384	✅
RS512	✅
ES256	✅
ES384	✅
ES512	✅
PS256	✅
PS384	✅
PS512	✅
none	❌

JWE Decryption

Claims	Implemented
alg	✅
enc	✅
zip	❌
jku	❌
jwk	❌
kid	❌
x5u	❌
x5c	❌
x5t	❌
x5t#S256	❌
typ	✅
cty	❌
crit	✅

Alg	Implemented	Requirements
RSA1_5	❌
RSA-OAEP	❌
RSA-OAEP-256	❌
A128KW	✅	OpenSSL 3.0+
A192KW	✅	OpenSSL 3.0+
A256KW	✅	OpenSSL 3.0+
dir	✅
ECDH-ES	❌
A128GCMKW	❌
A192GCMKW	❌
A256GCMKW	❌
PBES2-HS256+A128KW	❌
PBES2-HS384+A192KW	❌
PBES2-HS512+A256KW	❌

Enc	Implemented
A128CBC-HS256	✅
A192CBC-HS384	✅
A256CBC-HS512	✅
A128GCM	✅
A192GCM	✅
A256GCM	✅

Library non-goals

• JWT creation/modification
• Feature complete for the sake of RFCs completeness
• Senseless and unsafe RFCs features (e.g. alg none) won't be implemented.

Dependencies

luarocks install lua-cjson
luarocks install lua-resty-openssl
luarocks install lua-resty-http

Differences from lua-resty-jwt

Main differences are:

• No JWT manipulation of any kind (you can only decrypt/verify them)
• Simpler internal structure reliant on more recent lua-resty-openssl and OpenSSL versions.
• Supports different JWE algorithms (see tables above).

If any of the points above are a problem, or you need compatibility with older OpenResty version, I recommend sticking with lua-resty-jwt.

Missing features

• Nested JWT (i.e. JWT in JWE).
• JWKS workflow:
  • Key retrieval via HTTP with lua-resty-http.
  • Automatic and configurable keys rotation.
  • Investigate keys caching (?).

RFCs used as reference

• RFC 7515 JSON Web Signature (JWS)
• RFC 7516 JSON Web Encryption (JWE)
• RFC 7517 JSON Web Key (JWK)
• RFC 7518 JSON Web Algorithms (JWA)
• RFC 7519 JSON Web Token (JWT)
• RFC 7520 Examples of Protecting Content Using JSON Object Signing and Encryption (JOSE)

Run tests

Setup

Install test suit:

sudo cpan Test::Nginx

Install openresty: see https://openresty.org/en/linux-packages.html

Run

export PATH=/usr/local/openresty/nginx/sbin:$PATH
prove -r t