Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Algorithm Key Requirements #210

Closed
panva opened this issue Jun 10, 2021 · 0 comments
Closed

Algorithm Key Requirements #210

panva opened this issue Jun 10, 2021 · 0 comments

Comments

@panva
Copy link
Owner

panva commented Jun 10, 2021

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.

Repository owner locked and limited conversation to collaborators Jun 10, 2021
@panva panva closed this as completed Jun 10, 2021
@panva panva pinned this issue Jun 10, 2021
@panva panva added v4.x and removed v3.x labels Oct 15, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

1 participant