jose-jwt

Ultimate Javascript Object Signing and Encryption (JOSE), JSON Web Token (JWT), JSON Web Encryption (JWE) and JSON Web Keys (JWK) Implementation for .NET and .NET Core

Minimallistic zero-dependency library for generating, decoding and encryption JSON Web Tokens. Supports full suite of JSON Web Algorithms and Json Web Keys. JSON parsing agnostic, can plug any desired JSON processing library. Extensively tested for compatibility with jose.4.j, Nimbus-JOSE-JWT and json-jwt libraries. JWE JSON Serialization cross-tested with JWCrypto.

FIPS compliance

Library is fully FIPS compliant since v2.1

Which version?

• v5.3.0 Extended public SDK to allow custom algorithms implementations. New Elliptic Curve key utils to simplify conversion between P1363 and DER ASN.1 encodings.

• v5.2.0 Maintenence release, added .net6 target to remove dependencies on external outdated packages

• v5.1.1 Maintenence release, improved memory allocation for deflated tokens (see https://github.com/dvsekhvalnov/jose-jwt/issues/258, https://github.com/dvsekhvalnov/jose-jwt/issues/257)

• v5.1 support for experimental algorithms RSA-OAEP-384, RSA-OAEP-512 and forced strict AES-GCM to avoid trancated tags (see https://github.com/dotnet/runtime/issues/71366)

• v5.0 brings Linux, OSX and FreeBSD compatibility for ECDH encryption as long as managed ECDsa keys support. Fixes cross compatibility issues with encryption over NIST P-384, P-521 curves. And introduces new security fixes and controls.

• v4.1 added additional capabilities to manage runtime avaliable alg suite, see Customizing library for security. And also introduced default max limits for PBKDF2 (PBES2-*) max iterations according to OWASP PBKDF2 Recomendations.

• v4.0 introduced Json Web Key (JWK), RFC 7517 support. Latest stable. All new features will most likely appear based on given version.

• v3.2 dropped Newtonsoft.Json support in favor of System.Text.Json on netstandard2.1

• v3.1 introduced JWE JSON Serialization defined in RFC 7516

• v3.0 and above additionally targets netstandard2.1 to leverage better .net crypto support on *nix systems and enable more supported algorithms.

• v2.1 and above added extra features support for .NET461+ and coming with 3 version of binaries (NET4, NET461 and netstandard1.4).

• v2.0 and above is .NET Core compatible and aimed to support both .NET framework (NET40) and .NET Core (netstandard1.4) runtimes.

• v1.9 is built against .NET framework only and should be compatible with NET40 and above. The version is not actively maintained anymore except critical bug fixes.

• WinRT compatible version (Windows 8.1 and Windows Phone 8.1) is avaliable as standalone project here: jose-rt.

• PCLCrypto based experimental project living up here: jose-pcl.

Important upgrade notes

:warning: v4 -> v5:

• JWK EC keys now bridges to ECDsa by default instead of CngKey on .net 4.7.2+ and netstandard2.1+
• Jwk.ToJson() / Jwk.FromJson() now defaults to JWT.DefaultSettings.JsonMapper if not provided explicitly.
• Deflate decompression is limited to 250Kb by default. Check out customization section if need more.

:warning: v3.0 -> v3.1 stricter argument validation extraHeaders argument

In 3.1 and above an attempt to override enc or alg header values in extraHeaders will throw ArgumentException.

:warning: v2 -> v3 update public sdk changes

Moved:

• Security.Cryptography.EccKey to Jose.keys.EccKey
• Security.Cryptography.RsaKey to Jose.keys.RsaKey

OS cross compatibility

.Net version	Windows	Linux	Mac OS	FreeBSD v14
netcoreapp2.1	✅	✅
netcoreapp3.1	✅	✅	✅
net 8.0	✅	✅	✅	✅
net 5.0	✅	✅	✅
net 4.7	✅
net 4.6	✅
net 4.0	✅

Foreword

Originally forked from https://github.com/johnsheehan/jwt . Almost re-written from scratch to support JWT encryption capabilities and unified interface for encoding/decoding/encryption and other features. Moved to separate project in February 2014.

AES Key Wrap implementation ideas and test data from http://www.cryptofreak.org/projects/rfc3394/ by Jay Miller

Supported JWA algorithms

CLR

Signing

• HMAC signatures with HS256, HS384 and HS512.
• ECDSA signatures with ES256, ES384 and ES512.
• RSASSA-PKCS1-V1_5 signatures with RS256, RS384 and RS512.
• RSASSA-PSS signatures (probabilistic signature scheme with appendix) with PS256, PS384 and PS512.
• NONE (unprotected) plain text algorithm without integrity protection

Encryption

• RSAES OAEP 256, 384, 512 (using SHA-256, 384, 512 and MGF1 with SHA-256, 384, 512) encryption with A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM, A256GCM
• RSAES OAEP (using SHA-1 and MGF1 with SHA-1) encryption with A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM, A256GCM
• RSAES-PKCS1-V1_5 encryption with A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM, A256GCM
• Direct symmetric key encryption with pre-shared key A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM and A256GCM
• A128KW, A192KW, A256KW encryption with A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM, A256GCM
• A128GCMKW, A192GCMKW, A256GCMKW encryption with A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM, A256GCM
• ECDH-ES* with A128CBC-HS256, A128GCM, A192GCM, A256GCM
• ECDH-ES+A128KW*, ECDH-ES+A192KW*, ECDH-ES+A256KW* with A128CBC-HS256, A128GCM, A192GCM, A256GCM
• PBES2-HS256+A128KW, PBES2-HS384+A192KW, PBES2-HS512+A256KW with A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM, A256GCM

Compression

• DEFLATE compression

CORECLR

Signing

• HMAC signatures with HS256, HS384 and HS512.
• ECDSA signatures with ES256, ES384 and ES512.
• RSASSA-PKCS1-V1_5 signatures with RS256, RS384 and RS512.
• NONE (unprotected) plain text algorithm without integrity protection

Encryption

• RSAES OAEP 256, 384, 512 (using SHA-256, 384, 512 and MGF1 with SHA-256, 384, 512) encryption with A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM, A256GCM
• RSAES OAEP (using SHA-1 and MGF1 with SHA-1) encryption with A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM, A256GCM
• RSAES-PKCS1-V1_5 encryption with A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM, A256GCM
• Direct symmetric key encryption with pre-shared key A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM and A256GCM
• A128KW, A192KW, A256KW encryption with A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM, A256GCM
• A128GCMKW, A192GCMKW, A256GCMKW encryption with A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM, A256GCM
• PBES2-HS256+A128KW, PBES2-HS384+A192KW, PBES2-HS512+A256KW with A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM, A256GCM
• ECDH-ES* with A128CBC-HS256, A128GCM, A192GCM, A256GCM
• ECDH-ES+A128KW*, ECDH-ES+A192KW*, ECDH-ES+A256KW* with A128CBC-HS256, A128GCM, A192GCM, A256GCM

Compression

• DEFLATE compression

Json Web Key (JWK)

• RSA, EC, Oct keys
• X509 Chains, SHA1 & SHA2 thumbprints

Notes:

• Types returned by crytographic methods MAY be different on Windows and Linux. e.g. GetRSAPrivateKey() on X509Certificate2 on Windows returns RsaCng and OpenSslRsa on *nix.
• It appears that Microsoft CNG implementation of BCryptSecretAgreement/NCryptSecretAgreement contains a bug for calculating Elliptic Curve Diffie-Hellman secret agreement on keys higher than 256 bit (P-384 and P-521 NIST curves correspondingly). At least produced secret agreements do not match any other implementation in different languages. Starting version 5 we not recommending usage of CngKey keys with ECDH-ES family due to cross compatibility with other libraries. Please switch to use ECDsa, ECDiffieHellman or JWK instead, which are cross compatible on all curves and operating systems.

Installation

NuGet

https://www.nuget.org/packages/jose-jwt/

Install-Package jose-jwt

Manual

Grab source and compile yourself:

1. dotnet restore
2. dotnet pack -c Release

Usage

Creating Plaintext (unprotected) Tokens

var payload = new Dictionary()
{
    { "sub", "[email protected]" },
    { "exp", 1300819380 }
};

string token = Jose.JWT.Encode(payload, null, JwsAlgorithm.none);

// or starting v5.3.0 can also:
string token = Jose.JWT.Encode(payload, null, "none");

Warning: When using a class as the data structure of the payload, always use nullable data types for its properties. details

Creating signed Tokens

HS-* family

HS256, HS384, HS512 signatures require byte[] array key or Jwk key of type oct of corresponding length

var payload = new Dictionary()
{
    { "sub", "[email protected]" },
    { "exp", 1300819380 }
};

var secretKey = new byte[]{164,60,194,0,161,189,41,38,130,89,141,164,45,170,159,209,69,137,243,216,191,131,47,250,32,107,231,117,37,158,225,234};

string token=Jose.JWT.Encode(payload, secretKey, JwsAlgorithm.HS256);

// or starting v5.3.0 can also:
string token=Jose.JWT.Encode(payload, secretKey, "HS256");

var payload = new Dictionary()
{
    { "sub", "[email protected]" },
    { "exp", 1300819380 }
};

Jwk key = new Jwk(new byte[]{164,60,194,0,161,189,41,38,130,89,141,164,45,170,159,209,69,137,243,216,191,131,47,250,32,107,231,117,37,158,225,234});

string token=Jose.JWT.Encode(payload, key, JwsAlgorithm.HS256);

RS-* and PS-* family

NET40-NET45:

RS256, RS384, RS512 and PS256, PS384, PS512 signatures require RSACryptoServiceProvider (usually private) key of corresponding length. CSP need to be forced to use Microsoft Enhanced RSA and AES Cryptographic Provider. Which usually can be done be re-importing RSAParameters. See http://clrsecurity.codeplex.com/discussions/243156 for details.

var payload = new Dictionary()
{
    { "sub", "[email protected]" },
    { "exp", 1300819380 }
};

var privateKey=new X509Certificate2("my-key.p12", "password", X509KeyStorageFlags.Exportable | X509KeyStorageFlags.MachineKeySet).PrivateKey as RSACryptoServiceProvider;

string token=Jose.JWT.Encode(payload, privateKey, JwsAlgorithm.RS256);

// or starting v5.3.0 can also:
string token=Jose.JWT.Encode(payload, privateKey, "RS256");

NETCORE: RS256, RS384, RS512 and PS256, PS384, PS512 signatures require RSA (usually private) or Jwk key of type RSA of corresponding length.

var payload = new Dictionary()
{
    { "sub", "[email protected]" },
    { "exp", 1300819380 }
};

var privateKey=new X509Certificate2("my-key.p12", "password").GetRSAPrivateKey();

string token=Jose.JWT.Encode(payload, privateKey, JwsAlgorithm.RS256);

…

NET461 and above: Accepts RSACryptoServiceProvider, RSA or Jwk types of keys (see above).

ES-* family

NET40-NET45: ES256, ES384, ES512 ECDSA signatures requires CngKey (usually private) elliptic curve key of correspondin