Introduction

This document is available online at https://web-token.spomky-labs.com.

JWT Framework

This framework provides an implementation of:

• JWS JSON Web Signature (RFC 7515),
• JWT JSON Web Token (RFC 7519),
• JWE JSON Web Encryption (RFC 7516),
• JWA JSON Web Algorithms (RFC 7518).
• JWK JSON Web Key (RFC 7517).
• JSON Web Key Thumbprint (RFC 7638).
• Unencoded Payload Option RFC7797.

This framework is not just a library, it also contains a Symfony bundle for easy integration into your application. It also provides a standalone console command that will help you to manage your keys and key sets.

Provided Features

Supported Input Types:

JWS or JWE objects support every input that can be encoded into JSON:

• string, array, integer, float...
• Objects that implement the \JsonSerializable interface such as JWK or JWKSet

The detached payload is supported.

Supported Serialization Modes

• Compact JSON Serialization Syntax for JWS and JWE
• Flattened JSON Serialization Syntax for JWS and JWE
• General JSON Serialization Syntax for JWS and JWE

Supported Compression Methods

Compression Method	Supported	Comment
Deflate (DEF)	YES
GZip (GZ)	YES	This compression method is not described in the specification
ZLib (ZLIB)	YES	This compression method is not described in the specification

Supported Key Types (JWK)

Key Type	Supported	Comment
oct	YES	Symmetric keys
RSA	YES	RSA based asymmetric keys
EC	YES	Elliptic Curves based asymmetric keys
OKP	YES	Octet Key Pair based asymmetric keys

JWK objects support JSON Web Key Thumbprint (RFC 7638).

Note: we use a none key type for the none algorithm only.

Key Sets (JWKSet)

JWKSet is fully supported.

Supported Signature Algorithms

Signature Algorithm	Supported	Comment
HS256, HS384 and HS512	YES
ES256, ES384 and ES512	YES
RS256, RS384 and RS512	YES
PS256, PS384 and PS512	YES
none	YES	Please note that this is not a secured algorithm. USE IT WITH CAUTION!
EdDSA with Ed25519 curve	YES	With PHP 7.1, third party extension highly recommended
EdDSA with Ed448 curve	NO	No extension or built-in implementation available
HS1	YES	From v1.2. Experimental. Not recommended ; for testing purpose or compatibility with old systems only.
RS1	YES	From v1.2. Experimental. Not recommended ; for testing purpose or compatibility with old systems only.
HS256/64	YES	From v1.2. Experimental. Not recommended ; for testing purpose or compatibility with old systems only.

Supported Key Encryption Algorithms

Key Encryption Algorithm	Supported	Comment
dir	YES
RSA1_5, RSA-OAEP and RSA-OAEP-256	YES	The algorithms RSA1_5 and RSA-OAEP are now deprecated. Please use with caution.
ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW and ECDH-ES+A256KW	YES
A128KW, A192KW and A256KW	YES
PBES2-HS256+A128KW, PBES2-HS384+A192KW and PBES2-HS512+A256KW	YES
A128GCMKW, A192GCMKW and A256GCMKW	YES
ECDH-ES with X25519 curve	YES	With PHP 7.1, third party extension highly recommended
ECDH-ES with X448 curve	NO	No extension or built-in implementation available
RSA-OEAP-384 and RSA-OAEP-512	YES	From v1.2. Experimental. For testing purpose only.
ChaCha20-Poly1305	YES	From v1.2. Experimental. For testing purpose only.

Supported Content Encryption Algorithms

Content Encryption Algorithm	Supported	Comment
A128CBC+HS256, A192CBC+HS384 and A256CBC+HS512	YES
A128GCM, A192GCM and A256GCM	YES
A128CTR, A192CTR and A256CTR	YES	From v1.2. Not recommended. For testing purpose only.

Prerequisites

This framework needs at least:

• ,
• GMP extension.
• MBString extension.

Depending on the algorithms you using, other PHP extensions may be required (e.g. OpenSSL).

Please also consider the following optional requirements:

• If you intent to use EdDSA or ECDH-ES algorithm with Ed25519/X25519 curves on PHP 7.1, please install this third party extension

Continuous Integration

It has been successfully tested using PHP 7.1, PHP 7.2 and nightly with all algorithms.

Tests vectors from the RFC 7520 are fully implemented and all tests pass. Other test vector sources may be used (e.g. new algorithm specifications).

We also track bugs and code quality using Scrutinizer-CI and Sensio Insight.

Coding Standards are verified by StyleCI.

Code coverage is analyzed by Coveralls.io.

How to use

• The components
• The bundles
• The console commands

Security Recommendations

To avoid security issues on your application, please follow these Security Recommendations carefully.

Performances

Please read the performance page to know how to test the algorithms of the framework.

You can also see the last benchmarks made with our development environment.

Contributing

Requests for new features, bug fixed and all other ideas to make this framework useful are welcome. If you feel comfortable writing code, you could try to fix opened issues where help is wanted or those that are easy to fix.

Do not forget to follow these best practices.

If you think you have found a security issue, DO NOT open an issue. You MUST submit your issue here.

Licence

This project is release under MIT licence.