To perform cryptographic operations (signature/verification and encryption/decryption), you will need keys. The keys can be grouped in key sets.

The JWK and JWKSet objects are part of the web-token/jwt-core component:

composer require web-token/jwt-core

JWK

A JWK object represents a key. It contains all parameters needed by the algorithm and also information parameters.

This framework is able to create private and public keys easily. It can also generate those keys from external resources.

Read this section to know how to create your keys.

JWKSet

A JWKSet object represents a key set. It can contain several keys.

We recommend you to avoid mixing public, private or shared keys in the same key set.

Please refer to this page to know how to create and use the key sets.

You can create a JWKSet object using three static methods:

• JWKSet::createFromKeys(array $keys): creates a JWKSet using a list of JWK objects.

• JWKSet::createFromJson(string $json): creates a JWKSet using a JSON object.

• JWKSet::createFromKeyData(array $values): creates a JWKSet using a decoded JSON object.

Hereafter all methods available for a JWKSet object. The variable $jwkset is a valid JWKSet object.

Please note a JWKSet object is an immutable object

<?php
// Returns all keys
$jwkset->all();

// Check if the key set has the key with the key ID 'KEY ID'.
$jwkset->has('KEY ID');

// Retreive the key with the key ID 'KEY ID'.
$jwkset->get('KEY ID');

// Counts the keys in the key set.
$jwkset->count(); // The method count($jwkset) has the same behaviour.

// Adds a key to the key set.
// /!\ As the JWKSet object is immutable, this method will create a new key set. The previous key set is unchanged.
$new_jwkset = $jwkset->with($jwk);

// Removes a key to the key set.
// /!\ As the JWKSet object is immutable, this method will create a new key set. The previous key set is unchanged.
$new_jwkset = $jwkset->without('KEY ID');

// Selects a key according to the requirements.
// The first argument is the key usage ("sig" of "enc")
// The second argument is the algorithm to be used (optional)
// The third argument is an associative array this constraints (optional)
$key = $jwkset->selectKey('sig', $algorithm, ['kid' => 'KEY ID']);

// You can iterate on a key set
foreach($jwkset as $kid => $jwk) {
    // Action with the key done here
}

// The JWKSet object can be serialized into JSON
json_encode($jwkset);

We recommend you to avoid mixing public, private or shared keys in the same key set.

The algorithm management is part of the web-token/jwt-core component:

composer require web-token/jwt-core

Algorithm Manager

For each cryptographic operation you will perform, you will need at least one algorithm.

The available algorithms depend on the cypher operation to be performed. Please refer to the Signed tokens or the Encrypted tokens to know more.

These algorithms are managed by an Algorithm Manager. In the following example, we will create an algorithm manager that will handle two algorithms: PS256 and ES512

<?php

use Jose\Component\Core\AlgorithmManager;
use Jose\Component\Signature\Algorithm\PS256;
use Jose\Component\Signature\Algorithm\ES512;

$algorithm_manager = AlgorithmManager::create([
    new PS256(),
    new ES512(),
]);

It is not possible to set the same algorithm twice in the same algorithm manager.

Algorithm Manager Factory

Your application may need several algorithm managers for several use cases. Let say:

• Your application issues signed events,

• Your application issues authentication tokens for registered users or a resource server.

To avoid mixing algorithms in one algorithm manager or instantiate several times the algorithms for several algorithm managers, this framework provides an Algorithm Manager Factory.

This factory will create algorithm managers on demand. It also allows the same algorithm to be instantiated multiple times but with different configuration options.

Each algorithm is identified using an alias.

<?php

use Jose\Component\Core\AlgorithmManagerFactory;
use Jose\Component\Signature\Algorithm\PS256;
use Jose\Component\Encryption\Algorithm\KeyEncryption\PBES2HS512A256KW;
use Jose\Component\Encryption\Algorithm\ContentEncryption\A128CBCHS256;

$algorithm_manager_factory = new AlgorithmManagerFactory();
$algorithm_manager_factory
    ->add('PS256', new PS256())
    ->add('A128CBC-HS256', new A128CBCHS256())
    ->add('PBES2-HS512+A256KW', new PBES2HS512A256KW())
    ->add('PBES2-HS512+A256KW with custom configuration', new PBES2HS512A256KW(128, 8192))
;

The first argument of the method add is the alias for the algorithm. It must be unique. In general, this alias corresponds to the algorithm name.

As you can see in the example, we added the algorithm PBES2-HS512+A256KW twice: with the default configuration and with custom arguments.

Now our algorithm manager factory is ready. We can create several algorithm managers by passing a list of aliases to the method create:

<?php

$signature_algorithm_manager = $algorithm_manager_factory->create(['PS256']);
$encryption_algorithm_manager = $algorithm_manager_factory->create(['A128CBC-HS256', 'PBES2-HS512+A256KW']);
$encryption_algorithm_manager_for_paranoid = $algorithm_manager_factory->create(['A128CBC-HS256', 'PBES2-HS512+A256KW with custom configuration']);

This framework provides several components that will help you to use JWS (signed tokens) and JWE (encrypted tokens). It also provides other nice features to create and manage keys.

Before to start creating your first tokens, we have to create an algorithm manager and keys or key sets.

• Algorithm Management

• Header Checker and Claim Checker

• Keys and key sets

When your algorithm manager, your keys and your checkers are ready, you will be able to create or load your first tokens.

• Signed tokens

• Encrypted tokens

When you receive a JWT (JWS or JWE), it is important to check its headers before any other action. In case something went wrong, the token has to be rejected.

To use the header checker, install the corresponding component:

composer require web-token/jwt-checker

The header parameters are checked by a Header Checker Manager. This manager can contain several header checkers.

Please note that:

• the header parameter crit (critical) is always checked.

• even if the JWS and JWE Loaders will check the alg/enc header parameters, it is interesting to check them through this manager.

Header Checker Manager

To create a header checker manager, you will need to add header checkers and at least one token type. You will find token type classes for the JWS and JWE tokens in the web-token/jwt-signature and web-token/jwt-encryption components respectively.

In the following example, we want to check the alg header parameter for the signed tokens (JWS) received by our application.

<?php

use Jose\Component\Checker\HeaderCheckerManager;
use Jose\Component\Checker\AlgorithmChecker;
use Jose\Component\Signature\JWSTokenSupport;

$headerCheckerManager = HeaderCheckerManager::create(
    [
        new AlgorithmChecker(['HS256']), // We check the header "alg" (algorithm)
    ],
    [
        new JWSTokenSupport(), // Adds JWS token type support
    ]
);

The usage of this class is pretty easy you just have to call the check method. The first parameter is the JWT to check, the second one is the index of the signature/recipient.

$headerCheckerManager->check($jwt, 0);

In some cases, it could be interesting to reject tokens that do not contain some mandatory header parameters. A list of mandatory parameters can be set as third argument. If one of those parameters is missing an exception is thrown, even if that header parameter have not been checked.

In the following example, an exception will be thrown if the alg, enc or crit parameters is missing.

$headerCheckerManager->check($jwt, 0, ['alg', 'enc', 'crit']);

Header Checker Manager Factory

The Header Checker Manager Factory will help you to create as many Header Checker Manager as you want to fit on your application requirements.

<?php

use Jose\Component\Checker\HeaderCheckerManagerFactory;
use Jose\Component\Checker\AlgorithmChecker;
use Jose\Component\Encryption\JWETokenSupport;
use Jose\Component\Signature\JWSTokenSupport;

$headerCheckerManagerFactory = new HeaderCheckerManagerFactory();
$headerCheckerManagerFactory
    ->add('signature_alg', new AlgorithmChecker(['HS256']))
    ->add('key_encryption_alg', new AlgorithmChecker(['RSA1_5']))
    ->addTokenTypeSupport(new JWSTokenSupport())
    ->addTokenTypeSupport(new JWETokenSupport());

$headerCheckerManagerForSignatures = $headerCheckerManagerFactory->create(['signature_alg']);
$headerCheckerManagerForEncryption = $headerCheckerManagerFactory->create(['key_encryption_alg']);

Custom Header Checker

with the previous examples, we will only check the alg (algorithm) header parameter. But your application may use other header parameters e.g. cty, typ...

The following header checkers are provided:

• AlgorithmChecker: checks the alg header parameter.

• AudienceChecker: checks the aud header parameter. This is a replicated claim as per the RFC7516 section 5.3

• UnencodedPayloadChecker: checks the b64 header parameter. See unencoded payload for more information.

If you need, you can create you own header checker. It must implement the interface Jose\Component\Checker\HeaderChecker. In the following example, we will check that the protected header parameter custom is an array with value foo or bar.

<?php

namespace Acme\Checker;

use Jose\Component\Checker\HeaderChecker;
use Jose\Component\Checker\InvalidHeaderException;

/**
 * Class CustomChecker.
 */
final class CustomChecker implements HeaderChecker
{
    public function checkHeader($value)
    {
        if (!is_array($value) || !in_array($value, ['foo', 'bar'])) {
            throw new InvalidHeaderException('Invalid header "custom".', 'custom', $value);
        }
    }

    // This header parameter name.
    public function supportedHeader(): string
    {
        return 'custom';
    }

    // This method indicates if this parameter must be in the protected header or not.
    public function protectedHeaderOnly(): bool
    {
        return true;
    }
}

You can create a JWK object using two static methods:

• JWK::create(array $values): creates a JWK using direct values.

• JWK::createFromJson(string $json): creates a JWK using a JSON object.

Hereafter all methods available for a JWK object. The variable $jwk is a valid JWK object.

<?php
// Check if the key has a parameter.
$jwk->has('kty');

// Retrieve the key parameter.
$jwk->get('kty');

// Retrieve all key parameters.
$jwk->all();

// Calculate the thumbprint of the key. Acceptable hash algorithms are those returned by the PHP function "hash_algos".
$jwk->thumbprint('sha256');

// If the key is a private key (RSA, EC, OKP), it can be converted into public:
$public_key = $jwk->toPublic();

// The JWK object can be serialized into JSON
json_encode($jwk);

Please note a JWK object is an immutable object

Generate A New Key

This framework is able to create private and public keys easily using the JWKFactory. It is available in the web-token/jwt-key-mgmt component.

composer require web-token/jwt-key-mgmt

4 types of keys are supported:

• Symmetric Key:

  • oct: octet string

• Asymmetric Key:

  • RSA: RSA key pair

  • EC : Elliptic Curve key pair

  • OKP: Octet key pair

Note: for the none algorithm, the framework needs a key of type none. This is a specific key type that must only be used with this algorithm.

Octet String

The following example will show you how to create an oct key.

Additional parameters will be set to limit the scope of this key (e.g. signature/verification only with the HS256 algorithm).

<?php

use Jose\Component\KeyManagement\JWKFactory;

$key = JWKFactory::createOctKey(
    1024, // Size in bits of the key. We recommend at least 128 bits.
    [
        'alg' => 'HS256', // This key must only be used with the HS256 algorithm
        'use' => 'sig'    // This key is used for signature/verification operations only
    ]
);

The following feature was introduced in version 1.1.

If you already have a shared secret, you can use it to create an oct key:

<?php

use Jose\Component\KeyManagement\JWKFactory;

$jwk = JWKFactory::createFromSecret(
    'My Secret Key',       // The shared secret
    [                      // Optional additional members
        'alg' => 'HS256',
        'use' => 'sig'
    ]
);

RSA Key Pair

The following example will show you how to create a RSA key.

The key size must be of 384 bits at least.

<?php

use Jose\Component\KeyManagement\JWKFactory;

$private_key = JWKFactory::createRSAKey(
    4096, // Size in bits of the key. We recommend at least 2048 bits.
    [
        'alg' => 'RSA-OAEP-256', // This key must only be used with the RSA-OAEP-256 algorithm
        'use' => 'enc'    // This key is used for encryption/decryption operations only
    ]);

Elliptic Curve Key Pair

The following example will show you how to create a EC key.

<?php

use Jose\Component\KeyManagement\JWKFactory;

$key = JWKFactory::createECKey('P-256');

The supported curves are:

• P-256

• P-384

• P-521 (note that this is 521 and not 512)

Octet Key Pair

The following example will show you how to create a OKP key.

<?php

use Jose\Component\KeyManagement\JWKFactory;

$key = JWKFactory::createOKPKey('X25519');

The supported curves are:

• Ed25519 for signature/verification only

• X25519 for encryption/decryption only

None Key

The none key type is a special type used only for the none algorithm.

<?php

use Jose\Component\KeyManagement\JWKFactory;

$key = JWKFactory::createNoneKey();

Create Key From External Sources

From Values

In case you already have key values, you can create a key by passing those values as an argument:

<?php

use Jose\Component\KeyManagement\JWKFactory;

$key = JWKFactory::createFromValues([
    'kid' => '71ee230371d19630bc17fb90ccf20ae632ad8cf8',
    'kty' => 'RSA',
    'alg' => 'RS256',
    'use' => 'sig',
    'n' => 'vnMTRCMvsS04M1yaKR112aB8RxOkWHFixZO68wCRlVLxK4ugckXVD_Ebcq-kms1T2XpoWntVfBuX40r2GvcD9UsTFt_MZlgd1xyGwGV6U_tfQUll5mKxCPjr60h83LXKJ_zmLXIqkV8tAoIg78a5VRWoms_0Bn09DKT3-RBWFjk=',
    'e' => 'AQAB',
]);

From A Key File

You can convert a PKCS#1 or PKCS#8 key file into a JWK. The following method supports PEM and DER formats. Encrypted keys are also supported.

<?php

use Jose\Component\KeyManagement\JWKFactory;

$key = JWKFactory::createFromKeyFile(
    '/path/to/my/key/file.pem', // The filename
    'Secret',                   // Secret if the key is encrypted
    [
        'use' => 'sig',         // Additional parameters
    ]
);

From A PKCS#12 Certificate

You can convert a PKCS#12 Certificate into a JWK. Encrypted certificates are also supported.

<?php

use Jose\Component\KeyManagement\JWKFactory;

$key = JWKFactory::createFromPKCS12CertificateFile(
    '/path/to/my/key/file.p12', // The filename
    'Secret',                   // Secret if the key is encrypted
    [
        'use' => 'sig',         // Additional parameters
    ]
);

From A X.509 Certificate

You can convert a X.509 Certificate into a JWK.

<?php

use Jose\Component\KeyManagement\JWKFactory;

$key = JWKFactory::createFromCertificateFile(
    '/path/to/my/key/file.crt', // The filename
    [
        'use' => 'sig',         // Additional parameters
    ]
);

Please note that X.509 certificates only contains public keys.

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

Supported Key Types (JWK)

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

Supported Key Encryption Algorithms

Supported Content Encryption Algorithms

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.

This framework comes with several signature algorithms. These algorithms are in the following namespace: Jose\Component\Signature\Algorithm.

From v1.2, the algorithms have their own sub-packages. To avoid BC breaks, these packages are automatically installed for all v1.x of the framework. Starting at v2.0, you will have to explicitly install the algorithm packages you need.

• HMAC with SHA-2 Functions. Package web-token/jwt-signature-algorithm-hmac

  • HS256

  • HS384

  • HS512

• Elliptic Curve Digital Signature Algorithm (ECDSA). Package web-token/jwt-signature-algorithm-ecdsa

  • ES256

  • ES384

  • ES512

• RSASSA-PKCS1 v1_5. Package web-token/jwt-signature-algorithm-rsa

  • RS256

  • RS384

  • RS512

• RSASSA-PSS. Package web-token/jwt-signature-algorithm-rsa

  • PS256

  • PS384

  • PS512

• Edwards-curve Digital Signature Algorithm (EdDSA) Package web-token/jwt-signature-algorithm-eddsa

  • EdDSA (only with the Ed25519 curve)

• Unsecured algorithm Package web-token/jwt-signature-algorithm-none

  • none

The following signature algorithms are experimental and must not be used in production unless you know what you are doing. They are proposed for testing purpose only.

They are all part of the package web-token/jwt-signature-algorithm-experimental

• RS1: RSASSA-PKCS1 v1_5 with SHA-1 hashing function.

• HS1: HMAC with SHA-1 hashing function.

How To Use

Example:

To use the encrypted tokens (JWE), you have to install the .

This component provides lot of encryption algorithms and classes to load and create encrypted tokens.

Please refer to to know what algorithms are available.

Then, you will find an and another incoming tokens.

Now that you have an algorithm manager and a key, it is time to create your first signed token.

The computation is done by the JWSBuilder object. This object requires the algorithm manager and a JSON converter. In the following example, we will use the standard converter provided by the framework.

Now let's create our first JWS object.

Great! If everything is fine you will get a JWS object with one signature. We want to send it to the audience. Before that, it must be serialized.

We will use the compact serialization mode. This is the most common mode as it is URL safe and very compact. Perfect for a use in a web context!

All good! The variable $token now contains a string that should be something like this:

Other serialization modes exist. We will see them in the Advanced Topics section.

Signed tokens are loaded by a serializer or the serializer manager and verified by the JWSVerifier object. This JWSVerifier object just requires an algorithm manager.

Serializer And Verifier

In the following example, we will try to load a signed token. We will only use the HS256 algorithm.

Now we can deserialize the input we receive and check the signature using our key. We will continue with the data we got in the JWS creation section.

Note: we do not check header parameters here, but it is very important to do it. This step is described in the Header Checker section.

The method verifyWithKey returns a boolean. If true, then your token signature is valid. You can then check the claims (if any) using the claim checker manager.

JWSLoader Object

To avoid duplication of code lines, you can create a JWSLoader object. This object contains a serializer, a verifier and an optional header checker (highly recommended).

In the following example, the JWSLoader object will try to unserialize the token $token, check the header parameters and verify the signature with the key $jwk. The variable $payload corresponds to the detached payload (null by default).

If the verification succeeded, the variable $signature will be set with the signature index and should be in case of multiple signatures. The method returns the JWS object.

In case you use a key set, you can use the method loadAndVerifyWithKeySet.

JWSLoaderFactory Object

This feature was introduced in version 1.1.

The JWSLoaderFactory object is able to create JWSLoader objects on demand. It requires the following factories:

• JWSSerializerManagerFactory

• JWSVerifierFactory

• HeaderCheckerManagerFactory (optional)

JSON Web Tokens can be used to transport any kind of data. They are mainly used to transport claims. When you receive a tokens that contains claims, it is important to check the values of these claims.

The Claim Checker Manager is responsible of this task. To use it, install the corresponding component:

Claim Checker Manager

In the following example, we will create a manager able to check the aud (Audience), iat (Issued At), nbf (Not Before) and exp (Expiration) claims.

When instantiated, call the method check to check the claims of a JWT object. This method only accept an array. You have to retrieve this array by converting the JWT payload.

In some cases, it could be interesting to reject tokens that do not contain some mandatory claims. A list of mandatory claims can be set as second argument. If one of those claims is missing an exception is thrown, even if the claim have not been checked.

In the following example, an exception will be thrown if the iss, sub or aud claim is missing.

Custom Claim Checker

Your application may use other claims that you will have to check therefore custom claim checkers have to be created.

In this example, we will create a class that will check the claim foo. The claim accept only a string with the value bar or bat. All claim checker have to implement the interface Jose\Component\Checker\ClaimChecker;

All done! Now you can instantiate your class and add it to your Claim Checker Manager.

Replicating Claims as Header Parameters

Have a look at the IssuedAtChecker or the NotBeforeChecker classes. These checkers can be used for claim and header checks.

Claim Checker Manager Factory

Your application may use JSON Web Tokens in different contexts and thus the meaning of a claim may be different. You will need several Claim Checker Managers with dedicated claim checkers.

This framework provides an Claim Checker Manager Factory. This factory is able to accept as many claim checkers as you need. Each claim checker you add to this factory is associated to an alias. You will then be able to create a claim checker manager using those aliases.

To use the signed tokens (JWS), you have to install the .

This component provides lot of signature algorithms and classes to load and create signed tokens.

Please refer to to know what algorithms are available.

Then, you will find an and another incoming tokens.

This framework comes with several encryption algorithms. These algorithms are in the following namespaces:

• Jose\Component\Encryption\Algorithm\KeyEncryption: key encryption algorithms

• Jose\Component\Encryption\Algorithm\ContentEncryption: content encryption algorithms

  From v1.2, the algorithms have their own sub-packages. To avoid BC breaks, these packages are automatically installed for all v1.x of the framework. Starting at v2.0, you will have to explicitly install the algorithm packages you need.

• Key Encryption

  • Package web-token/jwt-encryption-algorithm-aeskw

    • A128KW

    • A192KW

    • A256KW

  • Package web-token/jwt-encryption-algorithm-aesgcmkw

    • A128GCMKW

    • A192GCMKW

    • A256GCMKW

  • Package web-token/jwt-encryption-algorithm-dir

    • dir (class Dir)

  • Package web-token/jwt-encryption-algorithm-ecdh-es

    • ECDH-ES (class ECDHES) READ THE NOTE BELOW

    • ECDH-ES+A128KW (class ECDHESA128KW) READ THE NOTE BELOW

    • ECDH-ES+A192KW (class ECDHESA192KW) READ THE NOTE BELOW

    • ECDH-ES+A256KW (class ECDHESA256KW) READ THE NOTE BELOW

  • Package web-token/jwt-encryption-algorithm-pbes2

    • PBES2-HS256+A128KW (class PBES2HS256A128KW)

    • PBES2-HS384+A192KW (class PBES2HS384A192KW)

    • PBES2-HS512+A259KW (class PBES2HS512A1256KW)

  • Package web-token/jwt-encryption-algorithm-rsa

    • RSA1_5 (class RSA15) READ THE NOTE BELOW

    • RSA-OAEP (class RSAOAEP)

    • RSA-OAEP-256 (class RSAOAEP256)

• Content Encryption

  • Package web-token/jwt-encryption-algorithm-aesgcm

    • A128GCM

    • A192GCM

    • A256GCM

  • Package web-token/jwt-encryption-algorithm-aescbc

    • A128CBC-HS256 (class A128CBCHS256)

    • A192CBC-HS384 (class A192CBCHS384)

    • A256CBC-HS512 (class A256CBCHS512)

IMPORTANT NOTE:

• The algorithm RSA1_5 is deprecated due to known security vulnerability.

• The algorithms ECDH-ES* are not recommended unless used with the OKP key type.

The following signature algorithms are experimental and must not be used in production unless you know what you are doing. They are proposed for testing purpose only.

They are all part of the package web-token/jwt-encryption-algorithm-experimental

• Key Encryption

  • A128CTR, A192CTR and A256CTR: AES CTR based encryption.

  • Chacha20+Poly1305 : Please note that this algorithm requires OpenSSL 1.1

  • RSA-OAEP-384 and RSA-OAEP-512: Same algorithm as RSA-OAEP-256 but with SHA-384 and SHA-512 hashing functions.

• Content Encryption

  • AxxxCCM-16-128, AxxxCCM-16-64, AxxxCCM-64-128, AxxxCCM-64-64: AES-CCM based aalgorithms. xxx can be 128 or 256.

How To Use

These algorithms have to be used with the Algorithm Manager. They do not need any arguments.

Example:

<?php

use Jose\Component\Core\AlgorithmManager;
use Jose\Component\Encryption\Algorithm\KeyEncryption\A128KW;
use Jose\Component\Encryption\Algorithm\KeyEncryption\PBES2HS256A128KW;
use Jose\Component\Encryption\Algorithm\ContentEncryption\A128CBCHS256;

$algorithmManager = AlgorithmManager::create([
    new A128KW(),
    new PBES2HS256A128KW(),
    new A128CBCHS256(),
]);

By default, PBES2* algorithms use the following parameter values:

• Salt size: 64 bytes (512 bits)

• Count: 4096

You may need to use other values. This can be done during the instantiation of the algorithm:

Example with 16 bytes (128 bits) salt and 1024 counts:

<?php

use Jose\Component\Core\AlgorithmManager;
use Jose\Component\Encryption\Algorithm\KeyEncryption\PBES2HS256A128KW;

$algorithmManager = AlgorithmManager::create([
    new PBES2HS256A128KW(16, 1024),
]);

The JWK and JWKSet objects are provided by the web-token/jwt-core component. We recommend you to load these objects through environment variables.

With Symfony 3.4 or 4.0+, an environment variables processor is provided:

parameters:
    my_private_key: '%env(jwk:MY_PRIVATE_KEY)%'
    my_public_keyset: '%env(jwkset:MY_PUBLIC_KEYSET)%'

With the previous configuration, the environment variables MY_PRIVATE_KEY and MY_PUBLIC_KEYSET will be processed by Symfony and the container will contain the my_private_key and my_public_keyset with JWK and JWKSet objects respectively.

But it may not be sufficient for your project. You may need to load keys or key sets from other sources (e.g. key file) You may also want to use your keys as a container services you inject to other services.

This behaviour is possible by installing the web-token/jwt-key-mgmt component. To install it, just execute the following command line:

composer require web-token/jwt-key-mgmt

• Key Management (JWK)

• Key Set Management (JWKSet)

Encrypted tokens are loaded by a serializer or the serializer manager and decrypted by the JWEDecrypter object. This JWEDecrypter object requires several services for the process:

• an algorithm manager with key encryption algorithms

• an algorithm manager with content encryption algorithms

• a compression method manager. No compression method is needed if you do not intent to compress the payload.

In the following example, we will use the same assumptions as the ones used during the JWE Creation process.

<?php

use Jose\Component\Core\AlgorithmManager;
use Jose\Component\Encryption\Algorithm\KeyEncryption\A256KW;
use Jose\Component\Encryption\Algorithm\ContentEncryption\A256CBCHS512;
use Jose\Component\Encryption\Compression\CompressionMethodManager;
use Jose\Component\Encryption\Compression\Deflate;
use Jose\Component\Encryption\JWEDecrypter;

// The key encryption algorithm manager with the A256KW algorithm.
$keyEncryptionAlgorithmManager = AlgorithmManager::create([
    new A256KW(),
]);

// The content encryption algorithm manager with the A256CBC-HS256 algorithm.
$contentEncryptionAlgorithmManager = AlgorithmManager::create([
    new A256CBCHS512(),
]);

// The compression method manager with the DEF (Deflate) method.
$compressionMethodManager = CompressionMethodManager::create([
    new Deflate(),
]);

// We instantiate our JWE Decrypter.
$jweDecrypter = new JWEDecrypter(
    $keyEncryptionAlgorithmManager,
    $contentEncryptionAlgorithmManager,
    $compressionMethodManager
);

Now we can try to deserialize and decrypt the input we receive. We will continue with the result we got during the JWE creation section.

Note: we do not check header parameters here, but it is very important to do it. This step is described in the Header Checker section.

<?php

use Jose\Component\Core\Converter\StandardConverter;
use Jose\Component\Core\JWK;
use Jose\Component\Encryption\Serializer\JWESerializerManager;
use Jose\Component\Encryption\Serializer\CompactSerializer;

// Our key.
$jwk = JWK::create([
    'kty' => 'oct',
    'k' => 'dzI6nbW4OcNF-AtfxGAmuyz7IpHRudBI0WgGjZWgaRJt6prBn3DARXgUR8NVwKhfL43QBIU2Un3AvCGCHRgY4TbEqhOi8-i98xxmCggNjde4oaW6wkJ2NgM3Ss9SOX9zS3lcVzdCMdum-RwVJ301kbin4UtGztuzJBeg5oVN00MGxjC2xWwyI0tgXVs-zJs5WlafCuGfX1HrVkIf5bvpE0MQCSjdJpSeVao6-RSTYDajZf7T88a2eVjeW31mMAg-jzAWfUrii61T_bYPJFOXW8kkRWoa1InLRdG6bKB9wQs9-VdXZP60Q4Yuj_WZ-lO7qV9AEFrUkkjpaDgZT86w2g',
]);

// The JSON Converter.
$jsonConverter = new StandardConverter();

// The serializer manager. We only use the JWE Compact Serialization Mode.
$serializerManager = JWESerializerManager::create([
    new CompactSerializer($jsonConverter),
]);

// The input we want to decrypt
$token = 'eyJhbGciOiJBMjU2S1ciLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwiemlwIjoiREVGIn0.9RLpf3Gauf05QPNCMzPcH4XNBLmH0s3e-YWwOe57MTG844gnc-g2ywfXt_R0Q9qsR6WhkmQEhdLk2CBvfqr4ob4jFlvJK0yW.CCvfoTKO9tQlzCvbAuFAJg.PxrDlsbSRcxC5SuEJ84i9E9_R3tCyDQsEPTIllSCVxVcHiPOC2EdDlvUwYvznirYP6KMTdKMgLqxB4BwI3CWtys0fceSNxrEIu_uv1WhzJg.4DnyeLEAfB4I8Eq0UobnP8ymlX1UIfSSADaJCXr3RlU';

// We try to load the token.
$jwe = $serializerManager->unserialize($token);

// We decrypt the token. This method does NOT check the header.
$jwe = $jweDecrypter->decryptUsingKey($jwe, $jwk);

OK so if not exception is thrown, then your token is loaded and the payload correctly decrypted.

JWELoader Object

To avoid duplication of code lines, you can create a JWELoader object. This object contains a serializer, a decrypter and an optional header checker (highly recommended).

In the following example, the JWELoader object will try to unserialize the token $token, check the header parameters and decrypt with the key $key.

If the decryption succeeded, the variable $recipient will be set with the recipient index and should be in case of multiple recipients. The method returns the JWE object.

<?php

use Jose\Component\Encryption\JWELoader;

$jweLoader = new JWELoader(
    $serializerManager,
    $jweDecrypter,
    $headerCheckerManager
);

$jwe = $jweLoader->loadAndDecryptWithKey($token, $key, $recipient);

In case you use a key set, you can use the method loadAndDecryptWithKeySet.

JWELoaderFactory Object

This feature was introduced in version 1.1.

The JWELoaderFactory object is able to create JWELoader objects on demand. It requires the following factories:

• JWESerializerManagerFactory

• JWEDecrypterFactory

• HeaderCheckerManagerFactory (optional)

<?php

use Jose\Component\Encryption\JWELoaderFactory;

$jweLoaderFactory = new JWELoaderFactory(
    $jweSerializerManagerFactory,
    $jweDecrypterFactory,
    $headerCheckerManagerFactory
);

$jweLoader = $jweLoaderFactory->create(
    ['jwe_compact'], // List of serializer aliases
    ['A128KW'],      // List of key encryption algorithm aliases
    ['A128KW'],      // List of content encryption algorithm aliases
    ['DEF'],         // List of compression method aliases
    ['alg', 'enc']   // Optional list of header checker aliases
);

Algorithm Manager Factory Service

The Symfony Bundle provides an Algorithm Manager Factory service. The available algorithms depends on the components installed on your application.

<?php

use Jose\Component\Core\AlgorithmManagerFactory;

$algorithmManagerFactory = $container->get(AlgorithmManagerFactory::class);
$algorithmManager = $algorithmManagerFactory->create(['RS256', 'HS512']);

Custom Algorithm

This factory handles all algorithms services tagged with jose.algorithm.

Example:

services:
    Acme\Bundle\Algorithm\FooAlgorihtm:
        tags:
            - {'name': 'jose.algorithm', 'alias': 'FOO'}

Your algorithm will be available through the algorithm manager factory service and the alias FOO.

PBES2-* Algorithms

When installed, the PBES2-* algorithms available throught the algorithm manager factory. They have the default configuration i.e. salt size = 62 bits and count = 4096. If these values does not fit on your needs, you can create a new algorithm service with your own values:

services:
    Jose\Component\Encryption\Algorithm\KeyEncryption\PBES2HS256A128KW:
        arguments:
            - 128   # salt size
            - 10240 # counts
        tags:
            - {'name': 'jose.algorithm', 'alias': 'Ultra-Secured PBES2-HS256+A128KW'}

You can now use your custom alias:

$algorithmManager = $algorithmManagerFactory->create(['Ultra-Secured PBES2-HS256+A128KW']);

This framework provides a Symfony bundle that will help you to use the components within your Symfony application. The bundle is available

• when you just install the bundle (composer require web-token/jwt-bundle)

• when you install the whole framework (composer require web-token/jwt-framework)

If you just install the bundle on an application with Symfony Flex support, then there is nothing to do. Otherwise, you have to register the bundle:

/**
 * {@inheritdoc}
 */
public function registerBundles()
{
    $bundles = [
        ...
        new Jose\Bundle\JoseFramework\JoseFrameworkBundle(),
    ];

    return $bundles;
}

The bundle capabilities will depend on the components installed in your application. The core component is always available.

• Algorithm Management

• Header and Claim Checkers

• Keys and key sets

• Signed tokens

• Encrypted tokens

Checker Manager Factory Services

The Symfony Bundle provides Header and Claim Checker Manager Factory services. These services are available when the web-token/jwt-checker component is installed:

Checker Manager Services

You can create Header and Claim Checker Managers using the bundle configuration.

With the previous configuration, the bundle will create public Header and Claim Checker Managers named jose.header_checker.checker1 and jose.claim_checker.checker1 with selected checkers.

Custom Header Or Claim Checker

Some claim or header checkers are provided by this framework, but it is important to create custom checkers that fit on your application requirements.

In the following example, we will assume that the class exist and implement either Jose\Component\Checker\HeaderChecker or Jose\Component\Checker\ClaimChecker.

These checkers will be loaded by the factories and you will be able to create a header or a claim checker manager using the aliases foo or bar.

Custom Tags

This feature was introduced in version 1.1.

You can add custom tags and attributes to the header and claim checker managers.

Key Management (JWK)

Keys As Services

When the component is installed, you will be able to define your keys in your application configuration and load your keys from several sources or formats. All these methods have the following option:

• is_public: set the service public or private.

The key configuration will look like as follow:

The key will be available as a container service with the ID jose.key.key_name where key_name is the unique name of your key. Each key service will be an instance of the Jose\Component\Core\JWK class.

As any other configuration values, you can use environment variables.

From A Shared Secret

This feature was introduced in version 1.1.

This method will directly get a shared secret.

From A JWK Object

This method will directly load a JWK object.

From A X509 Certificate File

This method will load a X509 Certificate file.

From A X509 Certificate

This method will load a key from a X509 Certificate.

From A PKCS#1/PKCS#8 Key File

This method will load a key from a PKCS#1 or PKCS#8 key file.

From A Key In A Key Set

This method will retrieve a key from a JWKSet service.

Custom Tags

This feature was introduced in version 1.1.

You can add custom tags and attributes to the services you create.

To use the signed tokens (JWS), you have to install the .

When this component is installed, signature algorithms are automatically handles by the Algorithm Manager Factory.

• ,

• ,

• .

JWS Serializer Manager Factory Service

A JWSSerializerManagerFactory is available as a service in your application container:

With this factory, you will be able to create the JWSSerializerManager you need:

You can now use the JWSSerializerManager as explained in the JWS Creation/Loading section.

Available JWS serialization modes are:

• jws_compact

• jws_json_general

• jws_json_flattened

JWS Serializer Manager As Service

There is also another way to create a JWSSerializerManager object: using the bundle configuration.

With the previous configuration, the bundle will create a public JWS Serializer Manager service named jose.jws_serializer.serializer1 with selected serialization modes.

Custom Tags

This feature was introduced in version 1.1.

You can add custom tags and attributes to the services you create.

JWS Builder Factory Service

A JWSBuilderFactory is available as a service in your application container:

With this factory, you will be able to create the JWSBuilder you need:

You can now use the JWSBuilder as explained in the JWS Creation section.

JWS Builder As Service

There is also another way to create a JWSBuilder object: using the bundle configuration.

With the previous configuration, the bundle will create a public JWS Builder service named jose.jws_builder.builder1 with selected signature algorithms.

Custom Tags

This feature was introduced in version 1.1.

You can add custom tags and attributes to the services you create.

Key Set Management (JWKSet)

Key Sets As Services

All these methods have the following common option:

• is_public: set the service public or private.

The key set configuration will look like as follow:

The key set will be available as a container service with the ID jose.key_set.keyset_name where keyset_name is the unique name of your key set. Each key set service will be an instance of the Jose\Component\Core\JWKSet class.

As any other configuration values, you can use environment variables.

From A JWKSet Object

This method will directly get a JWKSet object.

Distant Key Sets

When done, you have to create a client and enable the JKU Factory service by indicating the request factory service to use:

Important recommendations:

• It is highly recommended to use a cache plugin for your HTTP client and thus avoid unnecessary calls to the key set endpoint.

• The connection must be secured and certificate verification should not be disabled.

From A JKU (JWK Url)

The following example will allow you tu load a key set from a distant URI. The key set must be a JWKSet object.

From A X5U (X509 Certificates Url)

The following example will allow you tu load a key set from a distant URI. The key set must be a list of X509 certificates.

Shared Ket Sets

It can be interesting to share your key sets through an Url. This can easily achieved by adding a dedicated controller. This controller is automatically created by the bundle.

You must add the following configuration to your routing file.

Then you can share your key set.

Now went you go to the URL http://128.0.0.1:8000/certs, you will get your key set.

Custom Tags

This feature was introduced in version 1.1.

You can add custom tags and attributes to the services you create.