PHP JOSE Library

This library aims to provide 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).

It also implements the following specifications:

• Tests vectors from RFC 7520 (fully implemented and all test pass).
• JSON Web Key Thumbprint (RFC 7638).
• Unencoded Payload Option RFC7797.

Provided Features

Supported Input Types:

JWS or JWE objects support every input that can be serialized:

• String
• Any variable of object that can be encoded/decoded into JSON:
  • Primitives: integer, float...
  • Array
  • Objects that implement the \JsonSerializable interface such as:
    • jwk+json content type (JWKInterface object)
    • jwkset+json content type (JWKSetInterface object)

The detached content is also supported.

Unencoded payload is supported. This means you can sign and verify payload without base64 encoding operation. As per the RFC7797, the b64 header MUST be protected. When b64 header is set, the crit protected header with value b64 in its array of values is mandatory.

Supported Serialization Modes

• Compact JSON Serialization Syntax (JWS/JWE creation and loading)
• Flattened JSON Serialization Syntax (JWS/JWE creation and loading)
• General JSON Serialization Syntax (JWS/JWE creation and loading)

Supported Compression Methods

• Deflate —DEF—
• GZip —GZ— (this compression method is not described in the specification)
• ZLib —ZLIB— (this compression method is not described in the specification)

Supported Key Types (JWK)

• None keys (none)
• Symmetric keys (oct)
• Asymmetric keys based on RSA keys (RSA)
• Asymmetric keys based on Elliptic Curves (EC)
• Asymmetric keys based on Octet Key Pair (OKP)

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

Key Sets (JWKSet)

JWKSet is fully supported.

Supported Signature Algorithms

• HS256, HS384, HS512
• ES256, ES384, ES512
• RS256, RS384, RS512
• PS256, PS384, PS512
• none (Please note that this is not a secured algorithm. DO NOT USE IT PRODUCTION!)
• Ed25519 (third party extension required)
• Ed448

Please note that the EdDSA signature algorithm specification is not not yet approved. Support for algorithms Ed25518 and Ed448 may change. Use with caution.

Supported Key Encryption Algorithms

• dir
• RSA1_5
• RSA-OAEP
• RSA-OAEP-256
• ECDH-ES
• ECDH-ES+A128KW
• ECDH-ES+A192KW
• ECDH-ES+A256KW
• A128KW
• A192KW
• A256KW
• PBES2-HS256+A128KW
• PBES2-HS384+A192KW
• PBES2-HS512+A256KW
• A128GCMKW (for performance, this third party extension is highly recommended)
• A192GCMKW (for performance, this third party extension is highly recommended)
• A256GCMKW (for performance, this third party extension is highly recommended)
• X25519 (third party extension required)
• X448

Please note that the EdDSA encryption algorithm specification is not not yet approved. Support for algorithms X25518 and X448 may change. Use with caution.

Supported Content Encryption Algorithms

• A128CBC-HS256
• A192CBC-HS384
• A256CBC-HS512
• A128GCM (for performance, this third party extension is highly recommended)
• A192GCM (for performance, this third party extension is highly recommended)
• A256GCM (for performance, this third party extension is highly recommended)

The Release Process

The release process is described here.

Prerequisites

This library needs at least:

• ,
• OpenSSL extension.

Please consider the following optional requirements:

• For AES-GCM based algorithms (AxxxGCM and AxxxGCMKW): PHP Crypto Extension (at least v0.2.1) is highly recommended as encryption/decryption is faster than the pure PHP implementation.
• For Ed25519 algorithm: php-ed25519-ext required
• For X25519 algorithm: php-curve25519-ext required

Please read performance test results below concerning the ECC based algorithms. As the time needed to perform operation is long compared to the other algorithms, we do not recommend their use.

Continuous Integration

It has been successfully tested using PHP 5.6, PHP 7.0, PHP 7.1 and HHVM with all algorithms.

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.

Installation

The preferred way to install this library is to rely on Composer:

composer require spomky-labs/jose

How to use

Have a look at How to use to know how to load your JWT and discover all possibilities provided by this library.

Performances

Please read the performance page to know how fast are the algorithms supported by this library.

Contributing

Requests for new features, bug fixed and all other ideas to make this library useful are welcome. Please follow these best practices.

Licence

This software is release under MIT licence.