JWT NaCl

A JSON Web Token (JWT) implementation using NaCl cryptography

Description

A Ruby JSON Web Token implementation using Edwards-curve Digital Signature Algorithm (EdDSA) curve Ed25519 digital signatures from the state-of-the-art NaCl Networking and Cryptography library by Daniel J. Bernstein.

Installation

Add this line to your application's Gemfile:

gem 'jwt_nacl'

And then execute:

$ bundle

Or install it directly as:

$ gem install jwt_nacl

Philosophy & Design Goals

Convention over configuration
Use of state-of-the-art cryptography, including EdDSA Curve25519 elliptic curves
Minimal API surface area
Thorough test coverage
Modularity for comprehension and extensibility

Why NaCl?

Cryptography typically exposes a high degree of complexity, due to many possible configuration decisions. One poor choice could result in an insecure system.

NaCl is different. NaCl provides an expertly-assembled, high-level cryptographic API with the correct configuration already built-in. See RbNaCl for more rationale.

For a more conventional JWT implementation, please refer to the related json_web_token gem.

Usage

JWT.sign(claims, private_key)

Returns a 3 element hash that includes:

a JSON Web Token
the private key
the public key

claims (required) hash (non-empty)

private_key (optional) string, 32 random byte signing key

Example

require 'jwt_nacl'

claims = {iss: "mike", exp: 1300819380, :"http://example.com/is_root" => false}

private_hex = "d2c5c54bc205266f12a8a21809aa2989536959f666a5d68710e6fab94674041a"
private_key = [private_hex].pack("H*")

public_hex = "1e10af4b79b8d005c8b4237161f1350844b2e6c1a8d6aa4817151c04a2751731"
public_key = [public_hex].pack("H*")

# Sign with an elliptical curve Ed25519 digital signature
jwt = JWT.sign(claims, private_key)
#=> {
  jwt: "eyJhbGciOiJFZDI1NTE5IiwidHlwIjoiSldUIn0.eyJpc3MiOiJtaWtlIiwiZXhwIjoxMzAwODE5MzgwLCJodHRwOi8vZXhhbXBsZS5jb20vaXNfcm9vdCI6ZmFsc2V9.f2y6Sax9eK9M3JiFCt4ZfzzOL56SWNhydHpPPIoVkm21D3_bJq5DmFLgH8ee2OlzSlZMoq009jLSg6AC0mn4DA",
  private_key: private_key,
  public_key: public_key
}

JWT.verify(jwt, public_key)

Returns a hash:

{claims: < JWT claims set >}, if the digital signature is verified
{error: "invalid"}, otherwise

jwt (required) is a JSON web token string

public_key (required) string, 32 byte verifying key

Example

require 'jwt_nacl'

jwt = "eyJhbGciOiJFZDI1NTE5IiwidHlwIjoiSldUIn0.eyJpc3MiOiJtaWtlIiwiZXhwIjoxMzAwODE5MzgwLCJodHRwOi8vZXhhbXBsZS5jb20vaXNfcm9vdCI6ZmFsc2V9.f2y6Sax9eK9M3JiFCt4ZfzzOL56SWNhydHpPPIoVkm21D3_bJq5DmFLgH8ee2OlzSlZMoq009jLSg6AC0mn4DA"

hex = "1e10af4b79b8d005c8b4237161f1350844b2e6c1a8d6aa4817151c04a2751731"
public_key = [hex].pack("H*")

# Verify with an elliptical curve Ed25519 public key
JWT.verify(jwt, public_key)
#=> {
  claims: {iss: "mike", exp: 1300819380, :"http://example.com/is_root" => false}
}

Supported encryption algorithm

Ed25519, Edwards-curve Digital Signature Algorithm (EdDSA) using Curve25519

Supported Ruby versions

Ruby 2.2.6 and up

jwt_nacl

Development

Runtime