CFRG Elliptic Curve Diffie-Hellman (ECDH) and Signatures in JSON Object Signing and Encryption (JOSE)
updated by
- rfc-9864 — Fully-Specified Algorithms for JSON Object Signing and Encryption (JOSE) and CBOR Object Signing and Encryption (COSE)
Extracted elements (20)
Despite the existence of "crv" and "x" parameters in the OKP key type, implementations must not assume there is an underlying elliptic curve. This key type could be extended to represent DH algorithms based on hyperelliptic surfaces or other constructions.
The CFRG curves (X25519, X448, Ed25519, Ed448) are exposed through higher-level algorithm interfaces rather than directly exposing the underlying isogenous elliptic curve pairs, because the algorithms on top are sufficient for JOSE purposes and much easier to use correctly.
All inputs to and outputs from the ECDH and signature functions defined in this document are octet strings, with the sole exception of verification function outputs which are booleans. This uniform octet-string interface simplifies JOSE integration.
Ed25519 and Ed448 key subtypes MUST NOT be used for Elliptic Curve Diffie-Hellman Ephemeral Static (ECDH-ES). Similarly, X25519 and X448 subtypes MUST NOT be used for signing.
The parameter "d" MUST be present for private keys and contain the private key encoded using base64url encoding. This parameter MUST NOT be present for public keys.
The parameter "kty" MUST be "OKP" for Octet Key Pair keys. The parameter "crv" MUST be present and contain the subtype of the key from the "JSON Web Elliptic Curve" registry. The parameter "x" MUST be present and contain the public key encoded using base64url.
Using 256-bit symmetric encryption (especially key wrapping and encryption) with X448 is RECOMMENDED, given X448's nominal security strength of ~223 bits.
A new key type (kty) value "OKP" (Octet Key Pair) is defined for public key algorithms that use octet strings as private and public keys. It has parameters "kty" (must be "OKP"), "crv" (subtype of key), "x" (public key, base64url-encoded), and optionally "d" (private key, base64url-encoded).
EdDSA signing is performed by applying the RFC 8032 signing algorithm to the private key, public key, and JWS Signing Input (as message). The resulting signature is the JWS Signature. All inputs and outputs are octet strings.
EdDSA verification is performed by applying the RFC 8032 verification algorithm to the public key, the JWS Signing Input (as message), and the JWS Signature (as signature). If the algorithm accepts, the signature is valid; otherwise it is invalid.
For ECDH-ES, the "x" parameter of the "epk" field is set by applying the ECDH function to the ephemeral private key (as scalar input) and the standard base point (as u-coordinate input), then base64url-encoding the output. The Z value is computed by applying ECDH to the ephemeral private key and the receiver public key.
Key subtypes X25519 and X448 are defined for ECDH-ES ("Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static"), using the ECDH functions from RFC 7748. The key type used is "OKP".
The algorithm "EdDSA" is defined for use as the value of the "alg" parameter in JSON Web Signature (JWS). It supports two key subtypes: "Ed25519" (using Ed25519 variant) and "Ed448" (using Ed448 variant), both with key type "OKP".
This document adds "EdDSA" to the "JSON Web Signature and Encryption Algorithms" registry (alg usage, Optional) and adds "Ed25519", "Ed448", "X25519", and "X448" curves to the "JSON Web Key Elliptic Curve" registry (all Optional).
This document adds the "OKP" key type to the "JSON Web Key Types" registry, with JOSE Implementation Requirements of Optional, and adds parameters "crv" (public), "d" (private), and "x" (public) to the "JSON Web Key Parameters" registry for use with "OKP" keys.
Although Ed25519 and Ed448 signatures bind the key used for signing, implementations should not assume this property holds for other signature algorithms. If key-binding is desired, include the signing key inside the JWS protected header or the data to sign.
If key generation or batch signature verification is performed, a well-seeded cryptographic random number generator is REQUIRED. Signing and non-batch signature verification are deterministic and do not need random numbers.
Key material must not be separated from information about which key subtype it is for. When using keys, implementations must check that the algorithm is compatible with the key subtype to prevent attacks via algorithm mixing. Mixing signature and MAC algorithms is particularly dangerous.
The JWA ECDH-ES KDF construction does not mix keys into the final shared secret. Problems require either a maliciously chosen receiver public key or a malicious sender; in either case all security evaporates. The nominal security strengths of X25519 and X448 are ~126 and ~223 bits respectively.
OKP public keys are encoded as base64url strings in the "x" parameter. Private keys are encoded as base64url strings in the "d" parameter. For JWK Thumbprint canonicalization, the three public key fields ("crv", "kty", "x") are included in lexicographic order.