Algorithm Key Requirements

[panva]

See also Algorithm Selection Guide.

What are the key/secret requirements for JOSE algorithms

JWS "alg"

The following table describes the requirements for a key/secret for the supported JWS Algorithms ("alg").

With asymmetric algorithms, the private key is used for signing, the public key is used for verification.

Note that JWK parameters such as "use", "alg", or "key_ops" may further restrict the use of a given key.

JWS Algorithms	requirement	allowed key argument types
EdDSA	Ed25519 or Ed448 key	KeyObject, CryptoKey, JSON Web Key
ES256	NIST P-256 elliptic curve key	KeyObject, CryptoKey, JSON Web Key
ES256K	secp256k1 elliptic curve key	KeyObject, JSON Web Key
ES384	NIST P-384 elliptic curve key	KeyObject, CryptoKey, JSON Web Key
ES512	NIST P-521 elliptic curve key	KeyObject, CryptoKey, JSON Web Key
HS256	256 bit (32 byte) secret	Uint8Array, KeyObject, CryptoKey, JSON Web Key
HS384	384 bit (48 byte) secret	Uint8Array, KeyObject, CryptoKey, JSON Web Key
HS512	512 bit (64 byte) secret	Uint8Array, KeyObject, CryptoKey, JSON Web Key
PS256 PS384 PS512	RSA key of at least 2048 bit modulus length	KeyObject, CryptoKey, JSON Web Key
RS256 RS384 RS512	RSA key of at least 2048 bit modulus length	KeyObject, CryptoKey, JSON Web Key

JWE "alg"

The following table describes the requirements for a key/secret for the supported JWE Key Management Algorithms ("alg")

With asymmetric algorithms, the recipient's public key is used for encryption, the private key is used for decryption.

Note that JWK parameters such as "use", "alg", or "key_ops" may further restrict the use of a given key.

JWE Key Management Algorithms	requirement	allowed key argument types
A128KW A128GCMKW	128 bit (16 byte) secret	Uint8Array, KeyObject, CryptoKey
A192KW A192GCMKW	192 bit (24 byte) secret	Uint8Array, KeyObject, CryptoKey
A256KW A256GCMKW	256 bit (32 byte) secret	Uint8Array, KeyObject, CryptoKey
dir	see JWE "enc" table below
ECDH-ES ECDH-ES+A128KW ECDH-ES+A192KW ECDH-ES+A256KW	NIST P-256, P-384, or P-521 elliptic curve, X25519, or X448 key	KeyObject, CryptoKey
PBES2-HS256+A128KW PBES2-HS384+A192KW PBES2-HS512+A256KW	secret/password of any length	Uint8Array, KeyObject, CryptoKey
RSA-OAEP RSA-OAEP-256 RSA-OAEP-384 RSA-OAEP-512	RSA key with modulus length at least 2048 bits	KeyObject, CryptoKey

JWE "enc"

The following table describes the requirements for a secret for the supported JWE Content Encryption Algorithms ("enc") used in Direct Encryption Mode ("alg": "dir")

Note that JWK parameters such as "use", "alg", or "key_ops" may further restrict the use of a given key.

JWE Content Encryption Algorithms	requirement	allowed key argument types
A128GCM	128 bit (16 byte) secret	Uint8Array, KeyObject, CryptoKey
A192GCM	192 bit (24 byte) secret	Uint8Array, KeyObject, CryptoKey
A256GCM	256 bit (32 byte) secret	Uint8Array, KeyObject, CryptoKey
A128CBC-HS256	256 bit (32 byte) secret	Uint8Array, KeyObject
A192CBC-HS384	384 bit (48 byte) secret	Uint8Array, KeyObject
A256CBC-HS512	512 bit (64 byte) secret	Uint8Array, KeyObject

Key argument type notes

• KeyObject is a representation of a key/secret available in the Node.js runtime.
• CryptoKey is a representation of a key/secret available in the Browser and Web-interoperable runtimes.
• Uint8Array is a typed array representing an array of 8-bit unsigned integers.
• JSON Web Key is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. It is defined in RFC7517
• In Node.js the Buffer class is a subclass of Uint8Array and so Buffer can be provided for secrets as well.
• Key Import Functions can be used to import PEM or JWK formatted asymmetric keys and certificates to the runtime-specific representations.

Supported Runtimes

Not all algorithms are available in all runtimes, see the issues linked below for details.

• Bun
• Browsers
• Cloudflare Workers
• Deno
• Electron
• Node.js
• Vercel's Edge Runtime