Skip to content

Encryption algorithms

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

Main algorithms

Key encryption

Info

spomky-labs/aes-key-wrap is required for *KW algorithms

Algorithm Additional header parameter
A128KW
A192KW
A256KW		 No
A128GCMKW
A192GCMKW
A256GCMKW		 iv: (initialization vector) this value is the base64url-encoded representation of the 96-bit IV value used for the key encryption operation.
tag: (authentication tag) the value is the base64url-encoded representation of the 128-bit Authentication Tag value resulting from the key encryption operation.
dir No
ECDH-ES
ECDH-ES+A128KW
ECDH-ES+A192KW
ECDH-ES+A256KW		 epk: (ephemeral public key) value created by the originator.
ECDH-SS
ECDH-SS+A128KW
ECDH-SS+A192KW
ECDH-SS+A256KW		 No
PBES2-HS256+A128KW
PBES2-HS384+A192KW
PBES2-HS512+A256KW		 p2s: (PBES2 salt input) encodes a Salt Input value, which is used as part of the PBKDF2 salt value.
p2c: (PBES2 count) contains the PBKDF2 iteration count, represented as a positive JSON integer.
RSA1_5
RSA-OAEP
RSA-OAEP-256

Warning

Please note that the additional header parameters MUST be present and MUST be understood. Depending on the algorithm you use, you may be required to check headers BEFORE the decryption operation. Please create a custom Header Checker for theses parameters.

Content encryption

Algorithm Namespace
A128GCM
A192GCM
A256GCM		 Jose\Component\Encryption\Algorithm\ContentEncryption
A128CBC-HS256
A192CBC-HS384
A256CBC-HS512		 Jose\Component\Encryption\Algorithm\ContentEncryption

Danger

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 RSA1_5 algorithm

Since 4.3, RSA1_5 lives in its own package, so that enabling an algorithm whose padding is vulnerable to the Bleichenbacher adaptive chosen-ciphertext attack is an explicit and auditable decision:

composer require web-token/jwt-rsa15

<?php

use Jose\Rsa15\KeyEncryption\RSA15;

Warning

Jose\Component\Encryption\Algorithm\KeyEncryption\RSA15 still works — it is an empty subclass of the new class — but it is deprecated since 4.3 and removed in 5.0. In the Symfony Bundle, the configuration alias is unchanged: RSA1_5 still names the algorithm.

Curves supported by the key agreement algorithms

The ECDH-ES* and ECDH-SS* algorithms accept:

  • EC keys using the P-256, P-384, P-521, secp256k1, BP-256, BP-384 or BP-512 curve,
  • OKP keys using the X25519 curve (SODIUM extension, or OpenSSL on PHP 8.4+) or the X448 curve (PHP 8.4+ is required, OpenSSL; since 4.3).

The BP-* curves are the Brainpool curves. They are part of the core library and do not require the experimental package. Please read the warning about their interoperability before using them.

Experimental algorithms

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

Key encryption

Algorithm Description
A128CTR
A192CTR
A256CTR		 AES CTR based encryption
Chacha20+Poly1305 Please note that this algorithm requires OpenSSL 1.1
RSA-OAEP-384
RSA-OAEP-512		 Same algorithm as RSA-OAEP-256 but with SHA-384 and SHA-512 hashing functions

Content encryption

Algorithm Description
A128CCM-16-128
A128CCM-16-64
A128CCM-64-128
A128CCM-64-64
A256CCM-16-128
A256CCM-16-64
A256CCM-64-128
A256CCM-64-64		 AES-CCM based algorithms

How to use

These algorithms have to be used with the Algorithm Manager.

<?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 = new AlgorithmManager([
    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 = new AlgorithmManager([
    new PBES2HS256A128KW(16, 1024),
]);