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 :

local paseto = require "paseto.v2"

local key, payload_claims, token, footer_claims, claim_rules
local extracted_footer_claims, extracted_footer, decrypted_claims, enforced_claims
payload_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 key
key = paseto.generate_symmetric_key()

-- encrypt/decrypt without footer and without enforcing claim rules
token = paseto.encrypt(key, payload_claims)
decrypted_claims = paseto.decrypt(key, token)

-- encrypt with footer
token = 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 rules
decrypted_claims = paseto.decrypt(key, token, nil, extracted_footer)

-- decrypt and enforce claim rules
enforced_claims = paseto.decrypt(key, token, claim_rules, extracted_footer)

v2.public :

local paseto = require "paseto.v2"

local secret_key, public_key, payload_claims, token, footer_claims, claim_rules
local extracted_footer_claims, extracted_footer, verified_claims, enforced_claims
payload_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 pair
secret_key, public_key = paseto.generate_asymmetric_secret_key()

-- sign/verify without footer and without enforcing claim rules
token = paseto.sign(secret_key, payload_claims)
verified_claims = paseto.verify(public_key, token)

-- sign with footer
token = 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 rules
verified_claims = paseto.verify(public_key, token, nil, extracted_footer)

-- verify and enforce claim rules
enforced_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 :

local paseto = require "paseto.v2.core"

local key, message, token, footer, extracted_footer, decrypted
message = "my secret message"
footer = "my footer"

-- generate symmetric key
key = paseto.generate_symmetric_key()

-- encrypt/decrypt without footer
token = paseto.encrypt(key, message)
decrypted = paseto.decrypt(key, token)

-- encrypt/decrypt with footer
token = paseto.encrypt(key, message, footer)
extracted_footer = paseto.extract_footer(token)
decrypted = paseto.decrypt(key, token, extracted_footer)

v2.public :

local paseto = require "paseto.v2.core"

local secret_key, public_key, message, token, footer, extracted_footer, verified
message = "my signed message"
footer = "my footer"

-- generate key pair
secret_key, public_key = paseto.generate_asymmetric_secret_key()

-- sign/verify without footer
token = paseto.sign(secret_key, message)
verified = paseto.verify(public_key, token)

-- sign/verify with footer
token = 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