Cysharp / LitJWT

Lightweight, Fast JWT(JSON Web Token) implementation for .NET.

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

GitHub Actions Releases

LitJWT

Lightweight, Fast JWT(JSON Web Token) implementation for .NET. This library mainly focus on performance, 5 times faster encoding/decoding and very low allocation.

image

NuGet: LitJWT

Supported platform is netstandard 2.1, net5.0 or greater.

Install-Package LitJWT

Table of Contents

How to use

// using LitJWT;
// using LitJWT.Algorithms;

// Get recommended-size random key.
var key = HS256Algorithm.GenerateRandomRecommendedKey();

// Create encoder, JwtEncoder is thread-safe and recommend to store static/singleton.
var encoder = new JwtEncoder(new HS256Algorithm(key));

// Encode with payload, expire, and use specify payload serializer.
var token = encoder.Encode(new { foo = "pay", bar = "load" }, TimeSpan.FromMinutes(30));
// Create decoder, JwtDecoder is also thread-safe so recommend to store static/singleton.
var decoder = new JwtDecoder(encoder.SignAlgorithm);

// Decode and verify, you can check the result.
var result = decoder.TryDecode(token, out var payload);
if (result == DecodeResult.Success)
{
    Console.WriteLine((payload.foo, payload.bar));
}

Custom Serializer

In default. LitJWT is using System.Text.Json.JsonSerializer. If you want to use custom JsonSerializerOptions, JwtEncoder and JwtDecoder have JsonSerializerOptions serializerOptions constructor overload.

If you want to use another serializer, encode method receives Action<T, JwtWriter> payloadWriter. You have to invoke writer.Write(ReadOnlySpan<byte> payload) method to serialize. ReadOnlySpan<byte> must be Utf8 binary.

Here is the sample of use JSON.NET, this have encoding overhead.

var token = encoder.Encode(new PayloadSample { foo = "pay", bar = "load" }, TimeSpan.FromMinutes(30),
    (x, writer) => writer.Write(Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(x))));

Decode method receives delegate T PayloadParser<T>(ReadOnlySpan<byte> payload). ReadOnlySpan<byte> is utf8 json. Yes, utf8 based serializer is best but you can also use JSON.NET(but have encoding penalty).

var result = decoder.TryDecode(token, x => JsonConvert.DeserializeObject<PayloadSample>(Encoding.UTF8.GetString(x)), out var payload);

AlgorithmResolver

Decoding algorithm is whitelist, you should add algorithms when create JwtDecoder.

var resolver = new JwtAlgorithmResolver(
    new HS256Algorithm(),
    new HS384Algorithm(),
    new HS512Algorithm(),
    new RS256Algorithm(),
    new RS384Algorithm(),
    new RS512Algorithm());
var decoder = new JwtDecoder(resolver);

JwtAlgorithmResolver and JwtDecoder are both thread-safe.

Details of Performance

  • Directly encode/decode Base64Url(don't use string replace)
  • Parsing JSON on Utf8 binary(decoded Base64Url result) directly
  • ReadOnlySpan<byte> key custom dictionary
  • Uses Span<T> API for encrypt
  • Uses stackalloc byte[] and ArrayPool<byte>

For example, standard implementation of Base64Url encoding is like here.

Convert.ToBase64String(input).TrimEnd('=').Replace('+', '-').Replace('/', '_')

It has three unnecessary allocations(trim, replace, replace) and searching. I've implemented Base64Url converter and it has Span<T> based APIs to achive zero allocation.

ReadOnlySpan<byte> can not become dictionary key but decoding JWT requires alg, exp, nbf match to avoid extra decoding. I've implement custom Utf8String Dictionary it store data on initialize and match by bool TryGetValue(ReadOnlySpan<byte> key, out TValue value).

Encode

Method Mean Error Ratio Gen 0 Gen 1 Gen 2 Allocated
LitJwt 1.560 us NA 1.00 0.0477 - - 320 B
JwtDotNet 8.164 us NA 5.23 0.9613 - - 6216 B
MicrosoftIdentityModelJwt 12.673 us NA 8.12 1.8311 - - 11665 B

Decode

Method Mean Error Ratio Gen 0 Gen 1 Gen 2 Allocated
LitJwt 2.245 us NA 1.00 0.0229 - - 192 B
JwtDotNet 12.788 us NA 5.70 2.2583 0.0153 - 14385 B
MicrosoftIdentityModelJwt 13.099 us NA 5.83 2.2125 - - 14113 B

LitJWT is completely working on Utf8 so Encode method has three overloads.

  • string Encode<T>(...)
  • byte[] EncodeAsUtf8Bytes<T>(...)
  • void Encode<T>(IBufferWriter<byte> writer, ...)

IBufferWriter is fastest if you can write directly to I/O pipelines. byte[] is better than string because it can avoid utf8-string encoding cost.

For example gRPC C# or MagicOnion can set binary header. It has better performance than use string value.

// gRPC Header
var metadata = new Metadata();
metadata.Add("auth-token-bin", encoder.EncodeAsUtf8Bytes());

HMACSHA or RSA

If you don't need asymmetric encryption, HMACSHA is better.

Encode

Method Mean Error Gen 0 Gen 1 Gen 2 Allocated
HS256 1.928 us NA 0.1335 - - 888 B
HS384 1.787 us NA 0.1373 - - 888 B
HS512 1.714 us NA 0.1373 - - 888 B
RS256 618.728 us NA - - - 1008 B
RS384 629.516 us NA - - - 1008 B
RS512 639.434 us NA - - - 1008 B

Decode

Method Mean Error Gen 0 Gen 1 Gen 2 Allocated
HS256 1.876 us NA - - - -
HS384 1.677 us NA - - - -
HS512 1.735 us NA - - - -
RS256 56.549 us NA - - - 120 B
RS384 55.625 us NA - - - 120 B
RS512 55.746 us NA - - - 120 B

For example, use session key(to browser, unity client, etc...), client don't decode and only to store.

License

This library is under the MIT License.

About

Lightweight, Fast JWT(JSON Web Token) implementation for .NET.

License:MIT License


Languages

Language:C# 100.0%