jwtlited 1.0.0

jwtlited

Fast and lightweight dlang library to handle JWT tokens.

It's splitted to multiple submodules to fulfill the needs without forcing unused dependencies.

Some of these should be supported in betterC, but this is a WIP.

It doesn't force any JSON parser/serializer dependency, but tries to do least operations possible on itself.

For example if one needs to just validate the signature, it decodes and checks algorithm in the header, decodes the signature and check it. It doesn't touch the payload part.

When decoding, payload is still optional to be base64 decoded (based on the provided sink).

Currently payload content is not checked at all (ie for exp claim). One needs to call decode with payload sink and check it's contents manualy in a desired way and using whatever JSON parser.

I'd like to add payload validator for known claims too, but again it's a WIP.

Similarly when encoding, currently it's needed that raw, already json serialized payload, is passed to encode function.

Main API consists of just these methods:

bool decode(V, T, HS, PS)(auto ref V validator, T token, auto ref HS headSink, auto ref PS payloadSink);
bool decode(V, T, S)(auto ref V validator, T token, auto ref S payloadSink);
bool validate(V, T)(auto ref V validator, T token);
int encode(S, O, P)(auto ref S signer, auto ref O output, P payload);

So basically one just initialize required algorithm with a secret key and then passes it to these functions with possible sinks to store results. This way, one can provide his own algorithms handlers.

To use the library, just add for example this to your dub.sdl:

dependency "jwtlited:openssl" version=">=1.0.0"

Subpackages

:base

Base definitions and generic JWT operations. On itself supportd only JWTAlgorithm.none, anything else has to be provided in a custom handler.

Sample usage:

import jwtlited;
import std.stdio;

NoneHandler handler;
char[512] token;
enum payload = `{"foo":42}`;
immutable len = handler.encode(token[], payload);
assert(len > 0);
writeln("NONE: ", token[0..len]);

assert(handler.validate(token[0..len]));
char[32] pay;
assert(handler.decode(token[0..len], pay[]));
assert(pay[0..payload.length] == payload);

:phobos

Adds HS256, HS384 and HS512 handlers.

Sample usage:

import jwtlited.phobos;
import std.stdio;

HS256Handler handler;
enum payload = `{"foo":42}`;
bool ret = handler.loadKey("foo bar baz");
assert(ret);
char[512] tok;
immutable len = handler.encode(tok[], payload);
assert(len > 0);
writeln("HS256: ", tok[0..len]);

assert(handler.validate(tok[0..len]));
char[32] hdr, pay;
assert(handler.decode(tok[0..len], hdr[], pay[]));
assert(pay[0..payload.length] == payload);

:openssl

Adds HMAC, RSA and ECDSA algorithms using openssl library as a dependency.

Sample usage:

import jwtlited.openssl;
import std.stdio;

enum EC_PRIVKEY = `-----BEGIN EC PRIVATE KEY-----
MHcCAQEEILvM6E7mLOdndALDyFc3sOgUTb6iVjgwRBtBwYZngSuwoAoGCCqGSM49
AwEHoUQDQgAEMlFGAIxe+/zLanxz4bOxTI6daFBkNGyQ+P4bc/RmNEq1NpsogiMB
5eXC7jUcD/XqxP9HCIhdRBcQHx7aOo3ayQ==
-----END EC PRIVATE KEY-----`;

ES256Handler handler;
enum payload = `{"foo":42}`;
auto ret = handler.loadPKey(EC_PRIVKEY);
assert(ret);
char[512] tok;
immutable len = handler.encode(tok[], payload);
assert(len > 0);
writeln("ES256: ", tok[0..len]);

enum EC_PUBKEY = `-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEMlFGAIxe+/zLanxz4bOxTI6daFBk
NGyQ+P4bc/RmNEq1NpsogiMB5eXC7jUcD/XqxP9HCIhdRBcQHx7aOo3ayQ==
-----END PUBLIC KEY-----`;

ret = handler.loadKey(EC_PUBKEY);
assert(ret);
assert(handler.validate(tok[0..len]));
char[32] pay;
assert(handler.decode(tok[0..len], pay[]));
assert(pay[0..payload.length] == payload);

Performance

For example with HS256:

For more results see benchmarks