PASETO (Platform-Agnostic Security Tokens) for Lua

Paseto (Platform-Agnostic SEcurity TOkens) is a specification and reference implementation for secure stateless tokens.

"Paseto is everything you love about JOSE (JWT, JWE, JWS) without any of the many design deficits that plague the JOSE standards."

— paragonie/paseto

Feature Support

v1.local	v1.public	v2.local	v2.public
❌	❌	✔️	✔️

This implementation doesn't support the v1 protocol. Please note that v1 should only be used by legacy systems that cannot use modern cryptography.

Roadmap

• v2 local authentication (Blake2b and XChaCha20-Poly1305)
• v2 public authentication (Ed25519 signatures)
• JSON payload and footer processing
• Registered claims validation
• Custom claims validation
• High-level token builder API
• Integrated key ID (kid) support
• API documentation

Installation

Sodium Crypto Library

This Lua module depends on the Sodium crypto library (libsodium). The following is a convenient way to install libsodium via LuaRocks. Alternatively, see libsodium's documentation for full installation instructions.

luarocks install libsodium

Lua CJSON

This module also has a dependency on lua-cjson. Due to an issue with the latest version you might need to specify an earlier stable version. If you let luarocks install this dependency for you when installing PASETO you might experience problems. Additionally, if using Lua 5.3 you need to build Lua with a compatibility flag for Lua 5.1.

Lua	Lua CJSON install	Lua compatibility flags
5.1	luarocks install lua-cjson 2.1.0
5.2	luarocks install lua-cjson 2.1.0
5.3	luarocks install lua-cjson 2.1.0	-DLUA_COMPAT_5_1
Lua JIT 2.0	luarocks install lua-cjson 2.1.0
Lua JIT 2.1	luarocks install lua-cjson 2.1.0.6

See .travis.yml for build configurations.

PASETO

Finally, install PASETO:

luarocks install paseto

Usage

v2.local :

localpaseto=require"paseto.v2"localkey, payload_claims, token, footer_claims, claim_ruleslocalextracted_footer_claims, extracted_footer, decrypted_claims, enforced_claimspayload_claims= {
iss="paragonie.com",
jti="87IFSGFgPNtQNNuw0AtuLttP",
aud="some-audience.com",
sub="test",
iat="2018-01-01T00:00:00+00:00",
nbf="2018-01-01T00:00:00+00:00",
exp="2099-01-01T00:00:00+00:00",
data="this is a secret message",
myclaim="required value"
}
footer_claims= { kid="MDlCMUIwNzU4RTA2QzZFMDQ4" }
claim_rules= {
claim_1= { claim="IssuedBy", value="paragonie.com" },
claim_2= { claim="IdentifiedBy", value="87IFSGFgPNtQNNuw0AtuLttP" },
claim_3= { claim="ForAudience", value="some-audience.com" },
claim_4= { claim="Subject", value="test" },
claim_5= { claim="NotExpired", value="" },
claim_6= { claim="ValidAt", value="" },
claim_7= { claim="ContainsClaim", value="data" },
claim_8= { claim="myclaim", value="required value" }
}
-- generate symmetric keykey=paseto.generate_symmetric_key()
-- encrypt/decrypt without footer and without enforcing claim rulestoken=paseto.encrypt(key, payload_claims)
decrypted_claims=paseto.decrypt(key, token)
-- encrypt with footertoken=paseto.encrypt(key, payload_claims, footer_claims)
-- extract footer claims (e.g. to determine public key from kid claim)extracted_footer_claims, extracted_footer=paseto.extract_footer_claims(token)
-- decrypt without enforcing claim rulesdecrypted_claims=paseto.decrypt(key, token, nil, extracted_footer)
-- decrypt and enforce claim rulesenforced_claims=paseto.decrypt(key, token, claim_rules, extracted_footer)

v2.public :

localpaseto=require"paseto.v2"localsecret_key, public_key, payload_claims, token, footer_claims, claim_ruleslocalextracted_footer_claims, extracted_footer, verified_claims, enforced_claimspayload_claims= {
iss="paragonie.com",
jti="87IFSGFgPNtQNNuw0AtuLttP",
aud="some-audience.com",
sub="test",
iat="2018-01-01T00:00:00+00:00",
nbf="2018-01-01T00:00:00+00:00",
exp="2099-01-01T00:00:00+00:00",
data="this is a signed message",
myclaim="required value"
}
footer_claims= { kid="MDlCMUIwNzU4RTA2QzZFMDQ4" }
claim_rules= {
claim_1= { claim="IssuedBy", value="paragonie.com" },
claim_2= { claim="IdentifiedBy", value="87IFSGFgPNtQNNuw0AtuLttP" },
claim_3= { claim="ForAudience", value="some-audience.com" },
claim_4= { claim="Subject", value="test" },
claim_5= { claim="NotExpired", value="" },
claim_6= { claim="ValidAt", value="" },
claim_7= { claim="ContainsClaim", value="data" },
claim_8= { claim="myclaim", value="required value" }
}
-- generate key pairsecret_key, public_key=paseto.generate_asymmetric_secret_key()
-- sign/verify without footer and without enforcing claim rulestoken=paseto.sign(secret_key, payload_claims)
verified_claims=paseto.verify(public_key, token)
-- sign with footertoken=paseto.sign(secret_key, payload_claims, footer_claims)
-- extract footer claims (e.g. to determine public key from kid claim)extracted_footer_claims, extracted_footer=paseto.extract_footer_claims(token)
-- verify without enforcing claim rulesverified_claims=paseto.verify(public_key, token, nil, extracted_footer)
-- verify and enforce claim rulesenforced_claims=paseto.verify(public_key, token, claim_rules, extracted_footer)

Core API

This low-level API should only be used when you cannot use JSON for payload claims and footer claims.

v2.local :

localpaseto=require"paseto.v2.core"localkey, message, token, footer, extracted_footer, decryptedmessage="my secret message"footer="my footer"-- generate symmetric keykey=paseto.generate_symmetric_key()
-- encrypt/decrypt without footertoken=paseto.encrypt(key, message)
decrypted=paseto.decrypt(key, token)
-- encrypt/decrypt with footertoken=paseto.encrypt(key, message, footer)
extracted_footer=paseto.extract_footer(token)
decrypted=paseto.decrypt(key, token, extracted_footer)

v2.public :

localpaseto=require"paseto.v2.core"localsecret_key, public_key, message, token, footer, extracted_footer, verifiedmessage="my signed message"footer="my footer"-- generate key pairsecret_key, public_key=paseto.generate_asymmetric_secret_key()
-- sign/verify without footertoken=paseto.sign(secret_key, message)
verified=paseto.verify(public_key, token)
-- sign/verify with footertoken=paseto.sign(secret_key, message, footer)
extracted_footer=paseto.extract_footer(token)
verified=paseto.verify(public_key, token, extracted_footer)

License

MIT License - see the LICENSE file for details