A very large number of key and content encryption algorithms is provided by the library. Please refer to this encryption algorithm table to know what algorithms are available.
Then, you will find an example to create an encrypted token here and another example to load and decrypt incoming tokens.
The computation of a JWE is done by the JWEBuilder
object. This object requires the following services:
an algorithm manager with key encryption algorithms
an algorithm manager with content encryption algorithms
Compression is not recommended. Please avoid its use. See RFC8725 for more information.
Now let's create our first JWE object.
Great! If everything is fine you will get a JWE object with one recipient. 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 that:
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.
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.
We do not check header parameters here, but it is very important to do it. This step is described in the Header Checker section.
OK so if not exception is thrown, then your token is loaded and the payload correctly decrypted.
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.
In case you use a key set, you can use the method loadAndDecryptWithKeySet
.
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)
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
spomky-labs/aes-key-wrap
is required for *KW algorithms
Algorithm | Additional header parameter |
---|---|
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.
Algorithm | Package |
---|---|
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 algorithms are experimental and must not be used in production unless you know what you are doing. They are proposed for testing purpose only.
These algorithms have to be used with the Algorithm Manager.
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:
Algorithm | Description |
---|---|
Algorithm | Description |
---|---|
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
A128GCM
A192GCM
A256GCM
web-token/jwt-encryption-algorithm-aesgcm
A128CBC-HS256
A192CBC-HS384
A256CBC-HS512
web-token/jwt-encryption-algorithm-aescbc
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
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