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	Requirements
none	OctKey	Deprecated
HS256	OctKey	Recommended
HS384	OctKey	Optional
HS512	OctKey	Optional
RS256	RSAKey	Recommended
RS384	RSAKey	Optional
RS512	RSAKey	Optional
ES256	ECKey	Recommended
ES384	ECKey	Optional
ES512	ECKey	Optional
PS256	RSAKey	Optional
PS384	RSAKey	Optional
PS512	RSAKey	Optional
EdDSA	OKPKey	Optional
ES256K	ECKey	Optional

Note

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

By default, JWS serialize and deserialize methods will ONLY allow recommended algorithms. To use non-recommended algorithms, developers MUST explicitly specify the algorithms either by the algorithms parameter, or registry parameter.

from joserfc import jws
from joserfc.jwk import OctKey

key = OctKey.import_key("secret")
# HS384 is a non-recommended algorithm
jws.serialize_compact({"alg": "HS384"}, b"payload", key, algorithms=["HS384"])

# or with a custom registry
registry = jws.JWSRegistry(algorithms=["HS384"])
jws.serialize_compact({"alg": "HS384"}, b"payload", key, registry=registry)

Warning

none algorithm is deprecated via https://datatracker.ietf.org/doc/draft-ietf-jose-deprecate-none-rsa15/

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	Requirements
dir	OctKey	Recommended
A128KW	OctKey	Recommended
A192KW	OctKey	Optional
A256KW	OctKey	Recommended
RSA1_5	RSAKey	Deprecated
RSA-OAEP	RSAKey	Recommended
RSA-OAEP-256	RSAKey	Optional
ECDH-ES	ECKey	Recommended
ECDH-ES+A128KW	ECKey	Recommended
ECDH-ES+A192KW	ECKey	Optional
ECDH-ES+A256KW	ECKey	Recommended
A128GCMKW	OctKey	Optional
A192GCMKW	OctKey	Optional
A256GCMKW	OctKey	Optional
PBES2-HS256+A128KW	RSAKey	Optional
PBES2-HS384+A192KW	RSAKey	Optional
PBES2-HS512+A256KW	RSAKey	Optional

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

• A128CBC-HS256

• A192CBC-HS384

• A256CBC-HS512

• A128GCM

• A192GCM

• A256GCM

Warning

RSA1_5 algorithm is deprecated via https://datatracker.ietf.org/doc/draft-ietf-jose-deprecate-none-rsa15/

There is also a DEF algorithm for the “zip” (compression) header parameter, using of DEF is optional.

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_chacha20_poly1305

register_chacha20_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.