1 of 13

Advanced Topics

Serialization
Nested Tokens
Custom Algorithm
Signed tokens and
Encrypted tokens and

Nested Tokens

JWT can be signed or encrypted and both. A nested token is a signed token enclosed in an encrypted one. This order is very important: signed then encrypted.

The NestedTokenLoader and NestedTokenBuilder classes will help you to create nested tokens with ease. They are provided by the web-token/jwt-encryption component. However, you must also install the following component to use it:

web-token/jwt-checker
web-token/jwt-signature

Nested Token Loading

To instantiate the NestedTokenLoader, you need a JWSLoader and a JWELoader.

Its use is very straightforward, you just have to call the method load using the token, the encryption and signature key sets.

The last argument ($signature in the following example) will represents the signature index of the verified signature. This is only useful when multiple signature support is used.

Nested Token Building

To instantiate the NestedTokenBuilderder, you will need the following components:

a JWSBuilder,
a JWEBuilder,
a JWESerializerManager

Its use is a bit more complicated than the loading as the nested token may be designed for several recipients or may have several signatures.

As a reminder, if one of the following parameter is set, the compact serialization mode cannot be used:

signature unprotected header,
JWE shared unprotected header,
recipient unprotected header,

Symfony Bundle

Configuration

Hereafter an example of a Symfony application configuration:

This configuration will create two public services:

jose.nested_token_loader.loader_1
jose.nested_token_builder.builder_1

These services can be called from the container (unless private) or injected in your services.

Configuration Helper

As any other services, you can create a nested token loader or builder from another bundle extension. The following bundle extension class will create the same configuration and services as above.

Serialization

The (JWS) and (JWE) introduce several serialization modes.

Compact
JSON Flattened

Custom Algorithm

This framework provides dozens of signature or encryption algorithms. If your application uses a custom algorithm or if another algorithm has been recently approved in the JWT context, it may be interesting to use it with this framework.

Hopefully, this is very easy. In the following example, we will create a class to use the ChaCha20 + Poly 1305 (IETF variant) encryption algorithm as a Key Encryption Algorithm.

Signed tokens and

Unprotected Header

You may want to set data in a token header that are not important for your application (e.g. general information). The integrity protection of the data is therefore not needed at all.

The RFC7515 introduces an unprotected header. This header is supported by this framework.

With the example below, we will create a signed token with some unprotected header parameters:

$jws = $jwsBuilder
    ->create()
    ->withPayload('...')
    ->addSignature($jwk, ['alg' => 'HS256'], ['description' => 'Small description here', 'author' => 'John Doe'])
    ->build();

The variable $jws will be a valid JWS object with one signature and both headers.

Note: when an unprotected header is set, the Compact Serialization mode is not available.

Multiple Signatures

When you need to sign the same payload for several audiences, you may want to do it at once. The JWS Builder supports multiple signatures.

With the example below, we will create three signatures using three different algorithms (and signature keys):

The variable $jws will be a valid JWS object with all computed signatures. Next step is the serialization of these signatures.

Detached Payload

As per the ,the payload of a JWS may be detached. This framework supports this feature.

JWS Creation

There is not much difference between the creation of a JWS with or without detached payload. The following example comes from the . There is only one argument that will change during the call of withPayload.

And voilà! When you will serialize this token, the payload will not be present.

Unencoded Payload

The RFC7797 allows the use of an unencoded payload for the signed tokens. This behaviour is interesting when your tokens have a detached payload and may reduce the token computation.

Please note that when the Compact Serialization mode is used, the characters of the payload must be limited to the following ASCII ranges:

From 0x20 to 0x2d
From 0x2f to 0x7e

This feature is built in the framework and is enabled when the b64 header parameter is set to false. As per the RFC, this header MUST be protected and also listed as a critical (crit) header parameter.

Example:

As a remainder, both b64 and crit parameters MUST be in the protected header.

Encrypted tokens and

Unprotected Headers

As well as the signed tokens, the encrypted tokens also have unprotected header. But with one difference: there are two unprotected headers:

Shared unprotected header applicable to all recipients.
Per-recipient unprotected header.

With the example below, we will create an encrypted token for two recipient and some unprotected header parameters:

$jwe = $jweBuilder
    ->create()
    ->withPayload('...')
    ->withSharedProtectedHeader(['enc' => 'A256GCM', 'alg' => 'A256KW'])
    ->withSharedHeader(['author' => 'John Doe'])
    ->addRecipient($recipient_public_key_1, ['message' => 'Hello World!'])
    ->addRecipient($recipient_public_key_2, ['description' => 'Nice song for you'])
    ->build();

The variable $jwe will be a valid JWE object built for two recipients. The unprotected header parameter author is applicable to the whole token while message and description are available only for the first and second recipient respectively.

Note: when an unprotected header is set, the Compact Serialization mode is not available.

Multiple Recipients

When you need to encrypt the same payload for several audiences, you may want to do it at once. The JWE Builder supports multiple recipients.

With the example below, we will create an encrypted token for three different recipients using three different key encryption algorithms.

Important notes:

The content encryption algorithm MUST be the same for all recipients.
The Key Management Modes of the key encryption algorithms MUST be compatible (see table below).

Note: when an unprotected header is set, the Compact Serialization mode is not available.

Key Management Modes

Each Key Encryption Algorithm has its own Key Management Mode.

Key Encryption Algorithms And Associated Key Management Mode.

Compatibility table between Key Management Modes:

Additional Authentication Data (AAD)

The Additional Authenticated Data (AAD) is an input to an Authenticated Encryption operation. The AAD is integrity protected but not encrypted.

Its value can be any string you want that is needed by your application. With the example below, we will add a dummy AAD:

Note: when the AAD is set, the Compact Serialization mode is not available.

Nested Tokens

JWT can be signed or encrypted and both. A nested token is a signed token enclosed in an encrypted one. This order is very important: signed then encrypted.

web-token/jwt-checker
web-token/jwt-signature

Nested Token Loading

To instantiate the NestedTokenLoader, you need a JWSLoader and a JWELoader.

Its use is very straightforward, you just have to call the method load using the token, the encryption and signature key sets.

The last argument ($signature in the following example) will represents the signature index of the verified signature. This is only useful when multiple signature support is used.

Nested Token Building

To instantiate the NestedTokenBuilderder, you will need the following components:

a JWSBuilder,
a JWEBuilder,
a JWESerializerManager

Its use is a bit more complicated than the loading as the nested token may be designed for several recipients or may have several signatures.

As a reminder, if one of the following parameter is set, the compact serialization mode cannot be used:

signature unprotected header,
JWE shared unprotected header,
recipient unprotected header,

Symfony Bundle

Configuration

Hereafter an example of a Symfony application configuration:

This configuration will create two public services:

jose.nested_token_loader.loader_1
jose.nested_token_builder.builder_1

These services can be called from the container (unless private) or injected in your services.

Configuration Helper

As any other services, you can create a nested token loader or builder from another bundle extension. The following bundle extension class will create the same configuration and services as above.

Custom Algorithm

Hopefully, this is very easy. In the following example, we will create a class to use the ChaCha20 + Poly 1305 (IETF variant) encryption algorithm as a Key Encryption Algorithm.

<?php

declare(strict_types=1);

namespace Acme\Algorithm;

use Base64Url\Base64Url;
use Jose\Component\Core\JWK;
use const Sodium\CRYPTO_AEAD_CHACHA20POLY1305_IETF_NPUBBYTES;

/**
 * This algorithm is a custom algorithm that use the ChaCha20 + Poly 1305 with a 192 bits nonce (IETF variant).
 */
final class ChaCha20Poly1305IETF implements KeyEncryption //The algorithm acts as a Key Encryption algorithm
{
    /**
     * {@inheritdoc}
     */
    public function name(): string
    {
        return 'ChaCha20+Poly1305+IETF'; // The name of our algorithm. This name will be used in our JWE headers
    }

    /**
     * {@inheritdoc}
     */
    public function allowedKeyTypes(): array
    {
        return ['oct']; // Key types for this algorithm are octet keys
    }

    /**
     * {@inheritdoc}
     */
    public function encryptKey(JWK $key, string $cek, array $completeHeader, array &$additionalHeader): string
    {
        $this->checkKey($key); // We check the key
        $kek = Base64Url::decode($key->get('k')); // We retrieve the secret
        $nonce = random_bytes(CRYPTO_AEAD_CHACHA20POLY1305_IETF_NPUBBYTES); // We create a nonce
        $additionalHeader['nonce'] = Base64Url::encode($nonce); // We add the nonce to the header

        return sodium_crypto_aead_chacha20poly1305_ietf_encrypt($cek, '', $nonce, $kek); // We return the encrypted CEK
    }

    /**
     * {@inheritdoc}
     */
    public function decryptKey(JWK $key, string $encrypted_cek, array $header): string
    {
        $this->checkKey($key); // We check the key
        $this->checkAdditionalParameters($header); // We verify the nonce is in the headers
        $nonce = Base64Url::decode($header['nonce']); // We retrieve the nonce
        $kek = Base64Url::decode($key->get('k')); // an the secret

        $decrypted = sodium_crypto_aead_chacha20poly1305_ietf_decrypt($encrypted_cek, '', $nonce, $kek); // We try to decrypt the CEK
        if (false === $decrypted) { // If it fails we throw an exception
            throw new \RuntimeException('Unable to decrypt.');
        }

        return $decrypted; // Otherwise we return the decrypted CEK
    }

    /**
     * @param JWK $key
     */
    protected function checkKey(JWK $key)
    {
        if (!in_array($key->get('kty'), $this->allowedKeyTypes())) {
            throw new \InvalidArgumentException('Wrong key type.');
        }
        if (!$key->has('k')) {
            throw new \InvalidArgumentException('The key parameter "k" is missing.');
        }
    }

    /**
     * @param array $header
     */
    protected function checkAdditionalParameters(array $header)
    {
        foreach (['nonce'] as $k) {
            if (!array_key_exists($k, $header)) {
                throw new \InvalidArgumentException(sprintf('Parameter "%s" is missing.', $k));
            }
        }
    }

    /**
     * {@inheritdoc}
     */
    public function getKeyManagementMode(): string
    {
        return self::MODE_ENCRYPT; //Key Management Mode is 'enc'.
    }
}

Advanced Topics

Nested Tokens

hashtagNested Token Loading

hashtagNested Token Building

hashtagSymfony Bundle

hashtagConfiguration

hashtagConfiguration Helper

Serialization

Custom Algorithm

Signed tokens and

Unprotected Header

Multiple Signatures

Detached Payload

hashtagJWS Creation

Unencoded Payload

Encrypted tokens and

Unprotected Headers

Multiple Recipients

hashtagKey Management Modes

hashtagKey Encryption Algorithms And Associated Key Management Mode.

hashtagCompatibility table between Key Management Modes:

Additional Authentication Data (AAD)

Advanced Topics

Unencoded Payload

Multiple Signatures

Nested Tokens

hashtagNested Token Loading

hashtagNested Token Building

hashtagSymfony Bundle

hashtagConfiguration

hashtagConfiguration Helper

Signed tokens and

Unprotected Header

Detached Payload

hashtagJWS Creation

Additional Authentication Data (AAD)

Encrypted tokens and

Unprotected Headers

hashtagJWS Loading

Serialization

hashtagJWS Serialization

hashtagJWS Compact

hashtagJWS JSON Flattened

hashtagJWS JSON General

hashtagJWS Serializer Manager

hashtagJWE Serialization

hashtagJWE Compact

hashtagJWE JSON Flattened

hashtagJWE JSON General

hashtagJWE Serializer Manager

Custom Algorithm

Multiple Recipients

hashtagKey Management Modes

hashtagKey Encryption Algorithms And Associated Key Management Mode.

hashtagCompatibility table between Key Management Modes:

Nested Token Loading

Nested Token Building

Symfony Bundle

Configuration

Configuration Helper

JWS Creation

Key Management Modes

Key Encryption Algorithms And Associated Key Management Mode.

Compatibility table between Key Management Modes:

Nested Token Loading

Nested Token Building

Symfony Bundle

Configuration

Configuration Helper

JWS Creation

JWS Loading

JWS Serialization

JWS Compact

JWS JSON Flattened

JWS JSON General

JWS Serializer Manager

JWE Serialization

JWE Compact

JWE JSON Flattened

JWE JSON General

JWE Serializer Manager

Key Management Modes

Key Encryption Algorithms And Associated Key Management Mode.

Compatibility table between Key Management Modes: