Internet-Draft Fully-Specified Algorithms July 2024
Jones & Steele Expires 9 January 2025 [Page]
Workgroup:
JOSE Working Group
Internet-Draft:
draft-ietf-jose-fully-specified-algorithms-03
Updates:
7518, 8037, 8152, 9053 (if approved)
Published:
Intended Status:
Standards Track
Expires:
Authors:
M.B. Jones
Self-Issued Consulting
O. Steele
Transmute

Fully-Specified Algorithms for JOSE and COSE

Abstract

This specification refers to cryptographic algorithm identifiers that fully specify the cryptographic operations to be performed, including any curve, key derivation function (KDF), hash functions, etc., as being "fully specified". Whereas, it refers to cryptographic algorithm identifiers that require additional information beyond the algorithm identifier to determine the cryptographic operations to be performed as being "polymorphic". This specification creates fully-specified algorithm identifiers for registered JOSE and COSE polymorphic algorithm identifiers, enabling applications to use only fully-specified algorithm identifiers.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on 9 January 2025.

▲

Table of Contents

1. Introduction

The IANA algorithm registries for JOSE [IANA.JOSE] and COSE [IANA.COSE] contain two kinds of algorithm identifiers:

Fully Specified
Those that fully determine the cryptographic operations to be performed, including any curve, key derivation function (KDF), hash functions, etc. Examples are RS256 and ES256K in both JOSE and COSE and ES256 in JOSE.
Polymorphic
Those requiring information beyond the algorithm identifier to determine the cryptographic operations to be performed. Such additional information could include the actual key value and a curve that it uses. Examples are EdDSA in both JOSE and COSE and ES256 in COSE.

This matters because many protocols negotiate supported operations using only algorithm identifiers. For instance, OAuth Authorization Server Metadata [RFC8414] uses negotiation parameters like these (from an example in the specification):

  "token_endpoint_auth_signing_alg_values_supported":
    ["RS256", "ES256"]

OpenID Connect Discovery [OpenID.Discovery] likewise negotiates supported algorithms using alg and enc values. W3C Web Authentication [WebAuthn] and FIDO Client to Authenticator Protocol (CTAP) [FIDO2] negotiate using COSE alg numbers.

This does not work for polymorphic algorithms. For instance, with EdDSA, you do not know which of the curves Ed25519 and/or Ed448 are supported! This causes real problems in practice.

WebAuthn contains this de-facto algorithm definition to work around this problem:

  -8 (EdDSA), where crv is 6 (Ed25519)

This redefines the COSE EdDSA algorithm identifier for the purposes of WebAuthn to restrict it to using the Ed25519 curve - making it non-polymorphic so that algorithm negotiation can succeed, but also effectively eliminating the possibility of using Ed448. Other similar workarounds for polymorphic algorithm identifiers are used in practice.

This specification creates fully-specified algorithm identifiers for registered polymorphic JOSE and COSE algorithms and their parameters, enabling applications to use only fully-specified algorithm identifiers. It furthermore deprecates the practice of registering polymorphic algorithm identifiers.

1.1. Requirements Notation and Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

2. Fully-Specified Digital Signature Algorithm Identifiers

This section creates fully-specified digital signature algorithm identifiers for all registered polymorphic JOSE and COSE algorithms and their parameters.

2.1. Elliptic Curve Digital Signature Algorithm (ECDSA)

[RFC9053] defines the current use of the Elliptic Curve Digital Signature Algorithm (ECDSA) by COSE. The COSE algorithm registrations for ECDSA are polymorphic, since they do not specify the curve used. For instance, ES256 is defined as "ECDSA w/ SHA-256" in Section 2.1 of [RFC9053]. (The corresponding JOSE registrations in [RFC7518] are full-specified.)

The following fully-specified COSE ECDSA algorithms are defined:

Table 1: ECDSA Algorithm Values
Name COSE Value Description COSE Recommended
ESP256 TBD (requested assignment -9) ECDSA using P-256 curve and SHA-256 Yes
ESP384 TBD (requested assignment -48) ECDSA using P-384 curve and SHA-384 Yes
ESP512 TBD (requested assignment -49) ECDSA using P-521 curve and SHA-512 Yes
ESB256 TBD (requested assignment -261) ECDSA using BrainpoolP256r1 curve and SHA-256 No
ESB320 TBD (requested assignment -262) ECDSA using BrainpoolP320r1 curve and SHA-384 No
ESB384 TBD (requested assignment -263) ECDSA using BrainpoolP384r1 curve and SHA-384 No
ESB512 TBD (requested assignment -264) ECDSA using BrainpoolP512r1 curve and SHA-512 No

2.2. Edwards-Curve Digital Signature Algorithm (EdDSA)

[RFC8037] defines the current use of the Edwards-Curve Digital Signature Algorithm (EdDSA) by JOSE and [RFC9053] defines its current use by COSE. Both register polymorphic EdDSA algorithm identifiers.

The following fully-specified JOSE and COSE EdDSA algorithms are defined:

Table 2: EdDSA Algorithm Values
Name COSE Value Description JOSE Implementation Requirements COSE Recommended
Ed25519 TBD (requested assignment -50) EdDSA using Ed25519 curve Optional Yes
Ed448 TBD (requested assignment -51) EdDSA using Ed448 curve Optional Yes

3. Fully-Specified Encryption

This section describes the construction of fully-specified encryption algorithm identifiers in the context of existing the JOSE and COSE encryption schemes JSON Web Encryption (JWE) as described in [RFC7516] and COSE Encrypt as described in [RFC9052].

3.1. Fully-Specified Computations Using Multiple Algorithms

Both JOSE and COSE have operations that take multiple algorithms as parameters. Encrypted objects in JOSE [RFC7516] use two algorithm identifiers: the first in the alg (Algorithm) Header Parameter, which specifies how to determine the content encryption key, and the second in the enc (Encryption Algorithm) Header Parameter, which specifies the content encryption algorithm. Likewise, encrypted COSE objects can use multiple algorithms for corresponding purposes.

Each of these multiple algorithms must be independently fully specified. The operations performed by each of them MUST NOT vary when used alongside other algorithms. So for instance, for JOSE, alg values and enc values MUST each be fully specified, and their behaviors MUST NOT depend upon one another.

3.2. Analysis of Modes of Encryption

JOSE and COSE support several modes of encryption. Although the terminology sometimes differs between JOSE and COSE, both support these encryption modes:

  • Direct Encryption - A symmetric cryptographic operation.

  • Key Establishment with Direct Encryption - An asymmetric cryptographic operation to derive a shared secret, key derivation and then a symmetric cryptographic operation.

  • Two-Layer Encryption - A content encryption key is protected (multiple possible ways), then content encryption or decryption is performed using the protected content encryption key.

Mode complexity creates the following risks:

  • The combination of chosen algorithms might not be implemented by the receiver.

  • The combination of chosen algorithms might not be aligned in terms of strength.

  • Underspecified or implicit parameters could lead to exploitable faults in implementations, for example, cross curve ECDH between P-256 and P-384 or X25519.

  • Alternative algorithms at a component layer, such as symmetric key encryption, might provide different security properties, for example, "A128GCM" vs. "A128CBC-HS256".

While this specification provides a definition of what fully-specified encryption algorithm identifiers are for both JOSE and COSE, including examples, it does not deprecate any polymorphic algorithms, since complete replacements for them are not provided. It does register a small set of new fully-specified encryption algorithms, so that polymorphic encryption algorithms need not be used.

The following sections describe what fully specified means for each mode. They also register at least one fully-specified algorithm for each mode, when one was not already available.

3.2.1. Direct Encryption

Symmetric encryption algorithms generally satisfy the following interface:

secret_key = key_generation(algorithm_identifier)
ciphertext = encrypt(plaintext, secret_key)
plaintext  = decrypt(ciphertext, secret_key)

Depending on the algorithm, additional parameters such as additional authenticated data (AAD) or initialization vector (IV) might be required.

In the special case where the plaintext is a content encryption key, to be used with a subsequent symmetric encryption algorithm, such a symmetric encryption algorithm is referred to as a key wrapping algorithm and the secret_key is referred to as a key wrapping key.

An example of a fully-specified symmetric encryption algorithm is "A128GCM" (AES GCM using 128-bit key).

An example of a fully-specified key wrapping algorithm is "A128KW" (AES Key Wrap using 128-bit key).

A symmetric encryption algorithm is fully specified when it satisfies the interface above, and depends only on the parameters to the encrypt and decrypt operations.

Direct Encryption and Key Wrapping algorithms encode the primary symmetric key parameter (key length) in the algorithm identifier. Key Wrapping algorithms impose additional implicit constraints on AAD and IV.

In JOSE and COSE, all currently registered Direct Encryption and Key Wrapping algorithms are fully specified.

Example of a decoded JWE Protected Header, for Direct Encryption:

{
  "alg": "dir",
  "enc": "A128GCM",
  ...
}

Example of a decoded JWE Protected Header, for Key Wrapping:

{
  "alg": "A128KW",
  "enc": "A128GCM",
  ...
}

3.2.2. Key Establishment with Direct Encryption

Key establishment with direct encryption algorithms generally satisfy the following interface:

private_key, public_key = key_generation(algorithm_identifier)
ciphertext = encrypt(plaintext, public_key)
plaintext  = decrypt(ciphertext, private_key)

Depending on the symmetric algorithm, additional parameters such as additional authenticated data (AAD) or initialization vector (IV) might be required.

Although JOSE and COSE encode this type of encryption differently, both rely on a symmetric key derived from an asymmetric key. An algorithm called a key derivation function (KDF) is applied between key establishment and symmetric encryption.

Key establishment algorithms often rely on an asymmetric cryptographic operation whereby a public and a private key are used to produce a shared secret, which can be combined with a KDF to produce a symmetric key. The process of producing a shared secret is key type specific, and is different for elliptic curves, RSA, and lattice-based algorithms.

Elliptic Curve Diffie-Hellman (ECDH) is used to produce a shared secret with elliptic curve-based keys as follows:

private_key1, public_key1 = key_generation(algorithm_identifier)
private_key2, public_key2 = key_generation(algorithm_identifier)
shared_secret = derive_shared_secret(public_key1, private_key2)
shared_secret = derive_shared_secret(public_key2, private_key1)

An algorithm called a Key Encapsulation Mechanism, can be used to provide a common interface for deriving shared secrets, regardless of key type.

Key encapsulation algorithms generally satisfy the following interface:

private_key, public_key = key_generation(algorithm_identifier)
ciphertext, shared_secret = encapsulate(public_key)
shared_secret = deencapsulate(ciphertext, private_key)

When using Key Establishment with Direct Encryption, the ciphertext is not only the output of symmetric encryption, but also includes all parameters necessary for the recipient to decrypt the ciphertext. Encrypted content encryption keys are not produced by fully-specified Key Establishment with Direct Encryption algorithms.

In JOSE, the KDF algorithm is "Concat KDF" and is an implicit parameter of the key establishment algorithm. In JOSE and COSE, key establishment algorithms have historically been generic to a key type including all its mandatory parameters. For example, "ECDH-ES" establishes a shared secret, and then through the use of a KDF, a content encryption key, for keys based on elliptic curves. However, the mandatory parameters of the public_key and private_key need be the same in the context of the key type.

For example, when using ECDH-ES with secp256r1 (P-256) to establish a shared secret, the ECDH algorithm is a function of an ephemeral and a static key, which need to be of the same key type, and having the same parameters, in this case, the curve parameter.

To successfully encrypt to a recipient, a sender needs to possess the recipient's key (which contains the curve parameter) and know the recipients supported algorithms.

In JOSE and COSE, key representations can support communicating the algorithm which a recipient supports for a given key. It is considered a best practice to only support one algorithm during the lifetime of a key.

Example of a decoded JWE Protected Header, for Key Establishment with Direct Encryption:

{
  "alg":"ECDH-ES",
  "enc":"A128GCM",
  ...
}

Despite containing both the key establishment algorithm (with an implicit KDF) and the symmetric encryption algorithm, the example above is not fully specified.

To make a Key Establishment with Direct Encryption algorithm fully specified, all essential parameters need to be encoded in the algorithm identifier. In the context of the example above, the missing explicit parameters are curve name and KDF name. If the KDF requires additional parameters, they need to be present.

To convey a fully-specified Key Establishment with Direct Encryption algorithm in JOSE, the "alg" value MUST be "dir", and the "enc" value MUST be fully specified, specifying all essential parameters for both key establishment and symmetric encryption. For example: "ECDH-ES using P-256 and Concat-KDF with A128GCM" or "ECDH-ES using X25519 and Concat-KDF with A256GCM".

To convey a fully-specified Key Establishment with Direct Encryption algorithm in COSE, the "alg" value MUST specify all essential parameters for both key establishment and symmetric encryption. For example: "ECDH-ES using P-256 and HKDF SHA-256 with A128GCM" or "ECDH-ES using X25519 HKDF SHA-512 wit A256GCM".

Fully-specified Key Establishment with Direct Encryption algorithms enable the sender and receiver to agree on all algorithms needed to encrypt and decrypt a message using a single algorithm identifier.

3.2.3. Two-Layer Encryption

This section describes Two-Layer Encryption in both JOSE and COSE. Each defines multiple ways that a content encryption key can be produced and protected, then later used to decrypt or encrypt content.

This specification uses the term "Two-Layer Encryption" to refer to what JOSE describes as "Key Encryption" and "Key Agreement with Key Wrapping", and what COSE describes as "Key Transport" and "Key Agreement with Key Wrap".

A distinguishing characteristic of Two-Layer Encryption schemes is that multiple recipients can perform decryptions, using a wide range of algorithms, and that encrypted content encryption keys are always present.

In RSA-OAEP the encrypted content encryption key is generated through an asymmetric cryptographic operation.

When Key Wrapping without any key establishment is used, the content encryption key is encrypted using a symmetric cryptographic operation (key wrap). How the content encryption key was generated is out of scope when considering this scheme.

Key wrapping algorithms generally satisfy the following interface:

key_encryption_key = \
key_generation(algorithm_identifier)

encrypted_content_encryption_key = \
encrypt(content_encryption_key, key_encryption_key)

content_encryption_key  = \
decrypt(encrypted_content_encryption_key, key_encryption_key)

When Key Establishment with Key Wrapping is used, the content encryption key is protected with Key Wrapping, where the Key Encryption Key is derived from an asymmetric cryptographic operation and a key derivation function.

Key Establishment with Key Wrapping algorithms generally satisfy the following interface:

private_key, public_key = key_generation(algorithm_identifier)
# ignoring ephemeral/static vs. static/static, etc.

key_encryption_key = \
key_establishment(public_key, private_key)

encrypted_content_encryption_key = \
encrypt(content_encryption_key, key_encryption_key)

content_encryption_key = \
decrypt(encrypted_content_encryption_key, key_encryption_key)

The interface above is consistent with Key Establishment with Direct Encryption. The process of deriving a shared secret and content encryption key is specific to the asymmetric key type used. The difference is that instead of using the derived content encryption key directly, two-layer encryption always derives a key encryption key, and wraps the content encryption key.

Regardless of how a Two-Layer Encryption scheme protects a content encryption key, content encryption algorithms generally satisfy the following interface:

content_encryption_key = \
unwrap or establish and unwrap or key transport...

ciphertext = encrypt(plaintext, content_encryption_key)
plaintext  = decrypt(ciphertext, content_encryption_key)

Depending on the content encryption algorithm, additional parameters such as additional authenticated data (AAD) or initialization vector (IV) might be required.

Although JOSE and COSE encode Two-Layer Encryptions differently, both rely on an encrypted content encryption key. The content encryption key is encrypted either using Key Wrapping directly, or through Key Establishment and then Key Wrapping or Key Transport or Key Encryption. When Key Establishment is used, a KDF is usually applied during the production of the key encryption key, to ensure that the content encryption algorithm that will be used with the encrypted content encryption key is known and agreed to by both sender and recipient.

When using Two-Layer Encryption, the ciphertext is not only the output of symmetric encryption, but also includes all parameters necessary for the recipient to decrypt the ciphertext, including parameters for use with the key establishment algorithm, such as ephemeral or encapsulated keys, any required key derivation functions and their parameters and the key wrapping algorithm. Encrypted content encryption keys are always present when Two-Layer Encryption algorithms are used. Two-Layer Encryption is often used for encrypting the same plaintext to multiple recipients, in contrast with other modes which can only be used to encrypt to a single recipient.

Example of a decoded JWE Protected Header, for Key Encryption using RSA-OAEP with AES-GCM:

{
  "alg": "RSA-OAEP",
  "enc": "A256GCM",
  ...
}

Example of a decoded JWE Protected Header, for Key Encryption using ECDH-ES and AES-KeyWrap with AES-GCM:

{
  "alg": "ECDH-ES+A128KW",
  "enc": "A128GCM",
  ...
}

Despite containing both the key establishment algorithm, with either an implicit KDF, or a Key Transport algorithm and a symmetric encryption algorithm, the examples above are not fully specified.

To make a Two-Layer Encryption algorithm fully specified, all security relevant details need to be encoded in the algorithm identifiers. In the context of the examples above, the missing explicit parameters are the curve name, KDF and required parameters, and content encryption algorithm to use with the decrypted content encryption key.

To convey a fully-specified Two-Layer Encryption algorithm in JOSE, the "alg" value MUST specify all essential parameters for key establishment and key wrapping. For example: "ECDH-ES using Concat KDF and P-256" or "ECDH-ES using Concat KDF and P-256 and "A128KW" wrapping".

To convey a fully-specified Two-Layer Encryption algorithm in COSE, the "alg" value MUST specify all essential parameters for key establishment and key wrapping. For example: "ECDH-ES using P-256 w/ HKDF" or "ECDH-ES using P-256 w/ HKDF and AES Key Wrap w/ 128-bit key".

The symmetric encryption algorithm that will be used with the content encryption key after it is decrypted is required to prevent cross mode attacks, such as those described in [RFC9459].

Fully-specified Two-Layer Encryption algorithms enable the sender and receiver to agree on all mandatory security parameters. They also enable a protocol to specify an allow list of algorithm combinations that does not include polymorphic combinations, such as cross curve key establishment, cross mode symmetric encryption, or mismatched KDF size to symmetric key scenarios.

3.3. Fully-Specified Encryption Algorithm Identifiers

3.3.1. Elliptic Curve Diffie-Hellman (ECDH)

[RFC7518] defines the current use of Elliptic Curve Diffie-Hellman (ECDH) by JOSE. Likewise, [RFC9053] defines the current use of Elliptic Curve Diffie-Hellman (ECDH) by COSE. As described in Appendix A, both sets of registered ECDH algorithms are polymorphic.

The following fully-specified JOSE ECDH algorithms are defined:

Table 3: JOSE ECDH Algorithm Values
Name Description Implementation Requirements
ECDH-ES-P-256 ECDH-ES using Concat KDF and P-256 Recommended
ECDH-ES-P-256+A128KW ECDH-ES using Concat KDF and P-256 and "A128KW" wrapping Recommended

The following fully-specified COSE ECDH algorithms are defined:

Table 4: COSE ECDH Algorithm Values
Name COSE Value Description Recommended
ECDH-ES-P-256 + HKDF-256 TBD (requested assignment -52) ECDH ES using P-256 w/ HKDF -- generate key directly Yes
ECDH-SS-P-256 + HKDF-256 TBD (requested assignment -53) ECDH-SS using P-256 w/ HKDF -- generate key directly Yes
ECDH-ES-P-256 + HKDF-256 + A128KW TBD (requested assignment -54) ECDH ES using P-256 w/ HKDF and AES Key Wrap w/ 128-bit key Yes
ECDH-SS-P-256 + HKDF-256 + A128KW TBD (requested assignment -55) ECDH-SS using P-256 w/ HKDF and AES Key Wrap w/ 128-bit key Yes

Should additional fully-specified ECDH algorithms be required, future specifications can register them, using the descriptions in the tables in Appendix A, when applicable.

4. IANA Considerations

4.1. JOSE Algorithms Registrations

This section registers the following values in the IANA "JSON Web Signature and Encryption Algorithms" registry [IANA.JOSE] established by [RFC7515].

4.1.1. Fully-Specified JOSE Algorithm Registrations

  • Algorithm Name: Ed25519

  • Algorithm Description: EdDSA using Ed25519 curve

  • Algorithm Usage Locations: alg

  • JOSE Implementation Requirements: Optional

  • Change Controller: IETF

  • Reference: Section 2.2 of [[ this specification ]]

  • Algorithm Analysis Document(s): [RFC8032]

  • Algorithm Name: Ed448

  • Algorithm Description: EdDSA using Ed448 curve

  • Algorithm Usage Locations: alg

  • JOSE Implementation Requirements: Optional

  • Change Controller: IETF

  • Reference: Section 2.2 of [[ this specification ]]

  • Algorithm Analysis Document(s): [RFC8032]

  • Algorithm Name: ECDH-ES-P-256

  • Algorithm Description: ECDH-ES using Concat KDF and P-256

  • Algorithm Usage Locations: alg

  • JOSE Implementation Requirements: Recommended

  • Change Controller: IETF

  • Reference: Section 3.3.1 of [[ this specification ]]

  • Algorithm Analysis Document(s): [RFC8032]

  • Algorithm Name: ECDH-ES-P-256+A128KW

  • Algorithm Description: ECDH-ES using Concat KDF and P-256 and "A128KW" wrapping

  • Algorithm Usage Locations: alg

  • JOSE Implementation Requirements: Recommended

  • Change Controller: IETF

  • Reference: Section 3.3.1 of [[ this specification ]]

  • Algorithm Analysis Document(s): [RFC8032]

4.1.2. Deprecated Polymorphic JOSE Algorithm Registrations

The following registration is updated to change its status to Deprecated.

  • Algorithm Name: EdDSA

  • Algorithm Description: EdDSA signature algorithms

  • Algorithm Usage Locations: alg

  • JOSE Implementation Requirements: Deprecated

  • Change Controller: IETF

  • Reference: Section 3.1 of RFC8037

  • Algorithm Analysis Document(s): [RFC8032]

4.2. COSE Algorithms Registrations

This section registers the following values in the IANA "COSE Algorithms" registry [IANA.COSE].

4.2.1. Fully-Specified COSE Algorithm Registrations

  • Name: ESP256

  • Value: TBD (requested assignment -9)

  • Description: ECDSA using P-256 curve and SHA-256

  • Reference: Section 2.1 of [[ this specification ]]

  • Recommended: Yes

  • Name: ESP384

  • Value: TBD (requested assignment -48)

  • Description: ECDSA using P-384 curve and SHA-384

  • Reference: Section 2.1 of [[ this specification ]]

  • Recommended: Yes

  • Name: ESP512

  • Value: TBD (requested assignment -49)

  • Description: ECDSA using P-521 curve and SHA-512

  • Reference: Section 2.1 of [[ this specification ]]

  • Recommended: Yes

  • Name: ESB256

  • Value: TBD (requested assignment -261)

  • Description: ECDSA using BrainpoolP256r1 curve and SHA-256

  • Reference: Section 2.1 of [[ this specification ]]

  • Recommended: No

  • Name: ESB320

  • Value: TBD (requested assignment -262)

  • Description: ECDSA using BrainpoolP320r1 curve and SHA-384

  • Reference: Section 2.1 of [[ this specification ]]

  • Recommended: No

  • Name: ESB384

  • Value: TBD (requested assignment -263)

  • Description: ECDSA using BrainpoolP384r1 curve and SHA-384

  • Reference: Section 2.1 of [[ this specification ]]

  • Recommended: No

  • Name: ESB512

  • Value: TBD (requested assignment -264)

  • Description: ECDSA using BrainpoolP512r1 curve and SHA-512

  • Reference: Section 2.1 of [[ this specification ]]

  • Recommended: No

  • Name: Ed25519

  • Value: TBD (requested assignment -50)

  • Description: EdDSA using Ed25519 curve

  • Reference: Section 2.2 of [[ this specification ]]

  • Recommended: Yes

  • Name: Ed448

  • Value: TBD (requested assignment -51)

  • Description: EdDSA using Ed448 curve

  • Reference: Section 2.2 of [[ this specification ]]

  • Recommended: Yes

  • Name: ECDH-ES-P-256 + HKDF-256

  • Value: TBD (requested assignment -52)

  • Description: ECDH-ES using P-256 w/ HKDF -- generate key directly

  • Reference: Section 3.3.1 of [[ this specification ]]

  • Recommended: Yes

  • Name: ECDH-SS-P-256 + HKDF-256

  • Value: TBD (requested assignment -53)

  • Description: ECDH-SS using P-256 w/ HKDF -- generate key directly

  • Reference: Section 3.3.1 of [[ this specification ]]

  • Recommended: Yes

  • Name: ECDH-ES-P-256 + HKDF-256 + A128KW

  • Value: TBD (requested assignment -54)

  • Description: ECDH-ES using P-256 w/ HKDF and AES Key Wrap w/ 128-bit key

  • Reference: Section 3.3.1 of [[ this specification ]]

  • Recommended: Yes

  • Name: ECDH-SS-P-256 + HKDF-256 + A128KW

  • Value: TBD (requested assignment -55)

  • Description: ECDH-SS using P-256 w/ HKDF and AES Key Wrap w/ 128-bit key

  • Reference: Section 3.3.1 of [[ this specification ]]

  • Recommended: Yes

4.2.2. Deprecated Polymorphic COSE Algorithm Registrations

The following registrations are updated to change their status to Deprecated.

  • Name: ES256

  • Value: -7

  • Description: ECDSA w/ SHA-256

  • Reference: RFC 9053

  • Recommended: Deprecated

  • Name: ES384

  • Value: -35

  • Description: ECDSA w/ SHA-384

  • Reference: RFC 9053

  • Recommended: Deprecated

  • Name: ES512

  • Value: -36

  • Description: ECDSA w/ SHA-512

  • Reference: RFC 9053

  • Recommended: Deprecated

  • Name: EdDSA

  • Value: -8

  • Description: EdDSA

  • Reference: RFC 9053

  • Recommended: Deprecated

4.3. Updated Review Instructions for Designated Experts

4.3.1. JSON Web Signature and Encryption Algorithms

IANA is directed to preserve the current reference to RFC 7518, and to add a reference to this section of this specification.

The review instructions for the designated experts for the IANA "JSON Web Signature and Encryption Algorithms" registry [IANA.JOSE] in Section 7.1 of [RFC7518] have been updated to include an additional review criterion:

  • Only fully-specified algorithm identifiers may be registered. Polymorphic algorithm identifiers must not be registered.

4.3.2. COSE Algorithms

IANA is directed to preserve the current references to RFC 9053 and RFC 9054, and to add a reference to this section of this specification.

The review instructions for the designated experts for the IANA "COSE Algorithms" registry [IANA.COSE] in Section 10.4 of [RFC9053] have been updated to include an additional review criterion:

  • Only fully-specified algorithm identifiers may be registered. Polymorphic algorithm identifiers must not be registered.

4.4. Defining Deprecated and Prohibited

The terms "Deprecated" and "Prohibited" as used by JOSE and COSE registrations are currently undefined. Furthermore, while in [RFC7518] JOSE specifies that both "Deprecated" and "Prohibited" can be used, in [RFC8152] COSE specifies the use of "Deprecated" but not "Prohibited". (Note that [RFC9053] did not carry the definitions of the "Recommended" registry columns forward, so [RFC8152] remains definitive in this regard.) This section defines these terms for use by both JOSE and COSE IANA registrations in a consistent manner, eliminating this potentially confusing inconsistency.

For purposes of use in the "JOSE Implementation Requirements" columns in the IANA JOSE registries [IANA.JOSE] and in the "Recommended" columns in the IANA COSE registries [IANA.COSE], these terms are defined as follows:

Deprecated
There is a preferred mechanism to achieve similar functionality to that referenced by the identifier; this replacement functionality SHOULD be utilized in new deployments in preference to the deprecated identifier.
Prohibited
The identifier and the functionality that it references MUST NOT be used. (Identifiers MAY be designated as "Prohibited" due to security flaws, for instance.)

Note that the terms "Deprecated" and "Prohibited" have been used with a multiplicity of different meanings in various specifications, sometimes without actually being defined in those specifications. For instance, the term "Deprecated" is used in the title of [RFC8996], but the actual specification text uses the terminology "MUST NOT be used".

The definitions above were chosen because they are consistent with all existing registrations in both JOSE and COSE; none will need to change. Furthermore, they are consistent with their existing usage in JOSE. The only net change is to enable a clear distinction between "Deprecated" and "Prohibited" in future COSE registrations.

5. Key Representations

The key representations for the new fully-specified algorithms defined by this specification are the same as those for the polymorphic algorithms that they replace, other than the alg value, if included. For instance, the representation for a key used with the Ed25519 algorithm is the same as that specified in [RFC8037], except that the alg value would be Ed25519 rather than EdDSA, if included.

6. Notes on Algorithms Not Updated

The working group has discussed some existing algorithms that are not updated by this specification. This section discusses why they have not been updated.

6.1. Algorithms for Signing with RSASSA-PKCS1-v1_5

The working group has discussed whether the RS256, RS384, and RS512 algorithms should be considered fully-specified or not, because they can operate on keys of different sizes. For instance, they can use both 2048- and 4096-bit keys. The same is true of the PS* algorithms.

This is not a problem in practice, because RSA libraries accommodate keys of different sizes without having to use different code. Therefore, for example, there are not known cases in the wild where it would be useful to have different algorithm identifiers for RSASSA-PKCS1-v1_5 with SHA-256 and 2048-bit keys versus 4096-bit keys or 8192-bit keys. Therefore, the RSA signature algorithms are not replaced by this specification.

That said, should it be useful at some point to have RSA algorithm identifiers that are specific to the key size, a future specification could always register them.

7. Security Considerations

Using fully-specified algorithm identifiers reduces the attack surface relative to using polymorphic algorithm identifiers, since it reduces the opportunity for attackers to choose insecure or unexpected combinations of algorithms.

The security considerations for ECDSA in [RFC7518], for EdDSA in [RFC8037], and for ECDSA and EdDSA in [RFC9053] apply.

8. References

8.1. Normative References

[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC7515]
Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, , <https://www.rfc-editor.org/info/rfc7515>.
[RFC7516]
Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", RFC 7516, DOI 10.17487/RFC7516, , <https://www.rfc-editor.org/info/rfc7516>.
[RFC8037]
Liusvaara, I., "CFRG Elliptic Curve Diffie-Hellman (ECDH) and Signatures in JSON Object Signing and Encryption (JOSE)", RFC 8037, DOI 10.17487/RFC8037, , <https://www.rfc-editor.org/info/rfc8037>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/info/rfc8174>.
[RFC9052]
Schaad, J., "CBOR Object Signing and Encryption (COSE): Structures and Process", STD 96, RFC 9052, DOI 10.17487/RFC9052, , <https://www.rfc-editor.org/info/rfc9052>.
[RFC9053]
Schaad, J., "CBOR Object Signing and Encryption (COSE): Initial Algorithms", RFC 9053, DOI 10.17487/RFC9053, , <https://www.rfc-editor.org/info/rfc9053>.

8.2. Informative References

[FIDO2]
Bradley, J., Hodges, J., Jones, M., Kumar, A., and J. Johan, "Client to Authenticator Protocol (CTAP)", FIDO Alliance Proposed Standard, , <https://fidoalliance.org/specs/fido-v2.1-ps-20210615/fido-client-to-authenticator-protocol-v2.1-ps-20210615.html>.
[IANA.COSE]
IANA, "CBOR Object Signing and Encryption (COSE)", <https://www.iana.org/assignments/cose/>.
[IANA.JOSE]
IANA, "JSON Object Signing and Encryption (JOSE)", <https://www.iana.org/assignments/jose/>.
[OpenID.Discovery]
Sakimura, N., Bradley, J., Jones, M.B., and E. Jay, "OpenID Connect Discovery 1.0", , <https://openid.net/specs/openid-connect-discovery-1_0.html>.
[RFC7518]
Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, DOI 10.17487/RFC7518, , <https://www.rfc-editor.org/info/rfc7518>.
[RFC8032]
Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital Signature Algorithm (EdDSA)", RFC 8032, DOI 10.17487/RFC8032, , <https://www.rfc-editor.org/info/rfc8032>.
[RFC8152]
Schaad, J., "CBOR Object Signing and Encryption (COSE)", RFC 8152, DOI 10.17487/RFC8152, , <https://www.rfc-editor.org/info/rfc8152>.
[RFC8414]
Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, , <https://www.rfc-editor.org/info/rfc8414>.
[RFC8996]
Moriarty, K. and S. Farrell, "Deprecating TLS 1.0 and TLS 1.1", BCP 195, RFC 8996, DOI 10.17487/RFC8996, , <https://www.rfc-editor.org/info/rfc8996>.
[RFC9459]
Housley, R. and H. Tschofenig, "CBOR Object Signing and Encryption (COSE): AES-CTR and AES-CBC", RFC 9459, DOI 10.17487/RFC9459, , <https://www.rfc-editor.org/info/rfc9459>.
[WebAuthn]
Hodges, J., Jones, J.C., Jones, M., Kumar, A., and E. Lundberg, "Web Authentication: An API for accessing Public Key Credentials - Level 2", World Wide Web Consortium (W3C) Recommendation, , <https://www.w3.org/TR/2021/REC-webauthn-2-20210408/>.

Appendix A. Inventory of Polymorphic ECDH Algorithms

The working group assembled the following inventory of registered polymorphic Elliptic Curve Diffie-Hellman (ECDH) JOSE and COSE algorithms with the goal of understanding what registering fully-specified ECDH algorithms to replace them would entail. While there was not an appetite in the working group to register the full set of replacement algorithms at this time, this inventory documents how to do so, should others wish to register some or all of the replacements in the future.

Nonetheless, because working group members did document that not having fully-specified algorithms is a problem for some use cases, The engineering compromise employed in this specification is registering a single fully-specified ECDH algorithm for each kind of operation so that it becomes possible to rely on fully-specified ECDH algorithms for JOSE and COSE. These registrations are performed in Section 3.3.1.

A.1. Polymorphic ECDH JOSE Algorithms

These registered JOSE algorithms are polymorphic, because they do not include the curve name in the algorithm to be used with the ephemeral key:

Table 5: Polymorphic ECDH JOSE Algorithms
Name Description
ECDH-ES ECDH-ES using Concat KDF
ECDH-ES+A128KW ECDH-ES using Concat KDF and "A128KW" wrapping
ECDH-ES+A192KW ECDH-ES using Concat KDF and "A192KW" wrapping
ECDH-ES+A256KW ECDH-ES using Concat KDF and "A256KW" wrapping

Fully-specified JOSE versions of these algorithms using combinations that make sense, as discussed by the working group, would be:

Table 6: Fully-Specified ECDH JOSE Algorithms
Name Description
ECDH-ES-P-256 ECDH-ES using Concat KDF and P-256
ECDH-ES-P-384 ECDH-ES using Concat KDF and P-384
ECDH-ES-P-521 ECDH-ES using Concat KDF and P-521
ECDH-ES-X25519 ECDH-ES using Concat KDF and X25519
ECDH-ES-X448 ECDH-ES using Concat KDF and X448
ECDH-ES-P-256+A128KW ECDH-ES using Concat KDF and P-256 and "A128KW" wrapping
ECDH-ES-X25519+A128KW ECDH-ES using Concat KDF and X25519 and "A128KW" wrapping
ECDH-ES-P-384+A192KW ECDH-ES using Concat KDF and P-384 and "A192KW" wrapping
ECDH-ES-P-521+A256KW ECDH-ES using Concat KDF and P-521 and "A256KW" wrapping
ECDH-ES-X448+A256KW ECDH-ES using Concat KDF and X448 and "A256KW" wrapping

A.2. Polymorphic ECDH COSE Algorithms

These registered COSE algorithms are likewise polymorphic, because they do not include the curve name in the algorithm to be used with the ephemeral key or the static key:

Table 7: Polymorphic ECDH COSE Algorithms
Name Description
ECDH-ES + HKDF-256 ECDH-ES w/ HKDF -- generate key directly
ECDH-ES + HKDF-512 ECDH-ES w/ HKDF -- generate key directly
ECDH-SS + HKDF-256 ECDH-SS w/ HKDF -- generate key directly
ECDH-SS + HKDF-512 ECDH-SS w/ HKDF -- generate key directly
ECDH-ES + A128KW ECDH-ES w/ HKDF and AES Key Wrap w/ 128-bit key
ECDH-ES + A192KW ECDH-ES w/ HKDF and AES Key Wrap w/ 192-bit key
ECDH-ES + A256KW ECDH-ES w/ HKDF and AES Key Wrap w/ 256-bit key
ECDH-SS + A128KW ECDH-SS w/ HKDF and AES Key Wrap w/ 128-bit key
ECDH-SS + A192KW ECDH-SS w/ HKDF and AES Key Wrap w/ 192-bit key
ECDH-SS + A256KW ECDH-SS w/ HKDF and AES Key Wrap w/ 256-bit key

Fully-specified COSE versions of these algorithms using combinations that make sense, as discussed by the working group, would be:

Table 8: Fully-Specified ECDH COSE Algorithms
Name Description
ECDH-ES-P-256 + HKDF-256 ECDH-ES using P-256 w/ HKDF -- generate key directly
ECDH-ES-X25519 + HKDF-256 ECDH-ES using X25519 w/ HKDF -- generate key directly
ECDH-ES-P-521 + HKDF-512 ECDH-ES using P-521 w/ HKDF -- generate key directly
ECDH-ES-X448 + HKDF-512 ECDH-ES using X448 w/ HKDF -- generate key directly
ECDH-SS-P-256 + HKDF-256 ECDH-SS using P-256 w/ HKDF -- generate key directly
ECDH-SS-X25519 + HKDF-256 ECDH-SS using X25519 w/ HKDF -- generate key directly
ECDH-SS-P-521 + HKDF-512 ECDH-SS using P-521 w/ HKDF -- generate key directly
ECDH-SS-X448 + HKDF-512 ECDH-SS using X448 w/ HKDF -- generate key directly
ECDH-ES-P-256 + HKDF-256 + A128KW ECDH-ES using P-256 w/ HKDF and AES Key Wrap w/ 128-bit key
ECDH-ES-X25519 + HKDF-256 + A128KW ECDH-ES using X25519 w/ HKDF and AES Key Wrap w/ 128-bit key
ECDH-ES-P-384 + HKDF-384 + A192KW ECDH-ES using P-384 w/ HKDF and AES Key Wrap w/ 192-bit key
ECDH-ES-P-521 + HKDF-512 + A256KW ECDH-ES using P-521 w/ HKDF and AES Key Wrap w/ 256-bit key
ECDH-ES-X448 + HKDF-512 + A256KW ECDH-ES using X448 w/ HKDF and AES Key Wrap w/ 256-bit key
ECDH-SS-P-256 + HKDF-256 + A128KW ECDH-SS using P-256 w/ HKDF and AES Key Wrap w/ 128-bit key
ECDH-SS-X25519 + HKDF-256 + A128KW ECDH-SS using X25519 w/ HKDF and AES Key Wrap w/ 128-bit key
ECDH-SS-P-384 + HKDF-384 + A192KW ECDH-SS using P-384 w/ HKDF and AES Key Wrap w/ 192-bit key
ECDH-SS-P-521 + HKDF-512 + A256KW ECDH-SS using P-521 w/ HKDF and AES Key Wrap w/ 256-bit key
ECDH-SS-X448 + HKDF-512 + A256KW ECDH-SS using X448 w/ HKDF and AES Key Wrap w/ 256-bit key

Appendix B. Document History

[[ to be removed by the RFC Editor before publication as an RFC ]]

-03

-02

-01

-00

Acknowledgements

The authors thank Carsten Bormann, John Bradley, Tim Bray, Brian Campbell, Stephen Farrell, Ilari Liusvaara, Tobias Looker, Neil Madden, John Mattsson, Jeremy O'Donoghue, Anders Rundgren, Göran Selander, Filip Skokan, Oliver Terbu, and David Waite for their contributions to this specification.

Authors' Addresses

Michael B. Jones
Self-Issued Consulting
URI: https://self-issued.info/
Orie Steele
Transmute