Algorithms

All available algorithms for JWS, JWE, JWK, and JWT.

---

This documentation describes the algorithms to be used with JSON Web Signature (JWS), JSON Web Encryption (JWE), and JSON Web Key (JWK).

JSON Web Key

The JSON Web Key (JWK) algorithms contains:

• OctKey : accepts key size in bits, which means the key_size MUST be dividable by 8.

• RSAKey : accepts key size in bits, key_size MUST >=512 and dividable by 8.

• ECKey : accepts crv with P-256, P-384, P-521, and secp256k1.

• OKPKey : accepts crv with Ed25519, Ed448, X25519, and X448.

JSON Web Signature

joserfc.jws module supports algorithms from RFC7518, RFC8037, and RFC8812. You MUST specify the correct key type for each algorithm.

Algorithm name	Key Type	Recommended
none	OctKey	No
HS256	OctKey	Yes
HS384	OctKey	No
HS512	OctKey	No
RS256	RSAKey	Yes
RS384	RSAKey	No
RS512	RSAKey	No
ES256	ECKey	Yes
ES384	ECKey	No
ES512	ECKey	No
PS256	RSAKey	No
PS384	RSAKey	No
PS512	RSAKey	No
EdDSA	OKPKey	No
ES256K	ECKey	No

Note

EdDSA algorithm only accepts OKPKey with “crv” of “Ed25519” and “Ed448”.

JSON Web Encryption

joserfc.jwe module supports algorithms from RFC7518, and drafts of ECDH-1PU. You MUST specify the correct key type for each algorithm.

Algorithm name	Key Type	Recommended
dir	OctKey	Yes
A128KW	OctKey	Yes
A192KW	OctKey	No
A256KW	OctKey	Yes
RSA1_5	RSAKey	No
RSA-OAEP	RSAKey	Yes
RSA-OAEP-256	RSAKey	No
ECDH-ES	ECKey	Yes
ECDH-ES+A128KW	ECKey	Yes
ECDH-ES+A192KW	ECKey	No
ECDH-ES+A256KW	ECKey	Yes
A128GCMKW	OctKey	No
A192GCMKW	OctKey	No
A256GCMKW	OctKey	No
PBES2-HS256+A128KW	RSAKey	No
PBES2-HS384+A192KW	RSAKey	No
PBES2-HS512+A256KW	RSAKey	No

All algorithms defined in RFC7518 for “enc” value are recommended, which including:

• A128CBC-HS256

• A192CBC-HS384

• A256CBC-HS512

• A128GCM

• A192GCM

• A256GCM

A DEF algorithm for the “zip” (compression) header parameter is also defined in RFC7518, which is recommended.

There are also additional algorithms for “alg” and “enc” in draft versions. Please refer to the following sections for more information.

OKPKey

You can use OKPKey with the “crv” (curve) parameter set to X25519 or X448 for the following algorithms:

• ECDH-ES

• ECDH-ES+A128KW

• ECDH-ES+A192KW

• ECDH-ES+A256KW

This allows you to utilize these elliptic curve algorithms with OKPKey for your cryptographic operations.

C20P and XC20P

C20P and XC20P algorithms are still in drafts, they are not registered by default. To use C20P and XC20P, developers have to install the PyCryptodome module.

pip install pycryptodome

This is caused by cryptography package does only support “ChaCha20” cipher, not XChaCha20, while pycryptodome supports both “ChaCha20” and “XChaCha20” ciphers.

Register ciphers

The default Registry doesn’t contain draft ciphers, developers MUST register C20P and XC20P at first:

from joserfc.drafts.jwe_chacha20 import register_chaha20_poly1305

register_chaha20_poly1305()

Use custom registry

Use a custom registry in encrypt_compact(), decrypt_compact(), encrypt_json(), and decrypt_json().

from joserfc import jwe
from joserfc.jwk import OctKey

registry = jwe.JWERegistry(
    # add more "alg" and "enc" if you want
    algorithms=["A128KW", "C20P"]
)

key = OctKey.generate_key(128)  # A128KW requires 128 bits key
protected = {"alg": "A128KW", "enc": "C20P"}
encrypted_text = jwe.encrypt_compact(
    protected,
    b"hello",
    public_key=key,
    registry=registry,
)

ECDH-1PU algorithms

Key Agreement with Elliptic Curve Diffie-Hellman One-Pass Unified Model (ECDH-1PU) are still in drafts, they are not registered by default. To use ECDH-1PU related algorithms, developers MUST register them manually:

from joserfc.drafts.jwe_ecdh_1pu import register_ecdh_1pu

register_ecdh_1pu()

Then use a custom registry with the required ECDH-1PU algorithms. For instance:

from joserfc import jwe
from joserfc.jwk import ECKey

registry = jwe.JWERegistry(
    algorithms=["ECDH-1PU+A128KW", "A128CBC-HS256"]
)
protected = {"alg": "ECDH-1PU+A128KW", "enc": "A128CBC-HS256"}
recipient_key = ECKey.import_key("your-ec-public-key.json")
sender_key = ECKey.import_key("your-ec-sender-key.json")  # this SHOULD be a private key
encrypted_text = jwe.encrypt_compact(
    protected,
    b"hello",
    public_key=recipient_key,
    registry=registry,
    sender_key=sender_key,
)

Important

The ECDH-1PU algorithms require a sender key, which MUST be a private key when calling encrypt_compact() and encrypt_json() methods.

The sender_key can be a KeySet, and JWE will find the correct key according to skid header value.