Skip to main content

8. COSE Capabilities

  1. COSE Capabilities

The capabilities of an algorithm or key type need to be specified in some situations. This has a counterpart in the S/MIME specifications, where SMIMECapabilities is defined in Section 2.5.2 of [RFC8551]. This document defines the same concept for COSE.

The algorithm identifier is not included in the capabilities data, as it should be encoded elsewhere in the message. The key type identifier is included in the capabilities data, as it is not expected to be encoded elsewhere.

Two different types of capabilities are defined: capabilities for algorithms and capabilities for key type. Once defined by registration with IANA, the list of capabilities for an algorithm or key type is immutable. If it is later found that a new capability is needed for a key type or algorithm, it will require that a new code point be assigned to deal with that. As a general rule, the capabilities are going to map to algorithm-specific header parameters or key parameters, but they do not need to do so. An example of this is the HSS-LMS key type capabilities defined below, where the hash algorithm used is included.

The capability structure is an array of values; the values included in the structure are dependent on a specific algorithm or key type. For algorithm capabilities, the first element should always be a key type value if applicable, but the items that are specific to a key (for example, a curve) should not be included in the algorithm capabilities. This means that if one wishes to enumerate all of the capabilities for a device that implements ECDH, it requires that all of the combinations of algorithms and key pairs be specified. The last example of Section 8.3 provides a case where this is done by allowing for a cross product to be specified between an array of algorithm capabilities and key type capabilities (see the ECDH- ES+A25KW element). For a key, the first element should be the key type value. While this means that the key type value will be duplicated if both an algorithm and key capability are used, the key type is needed in order to understand the rest of the values.

8.1. Assignments for Existing Algorithms

For the current set of algorithms in the registry other than IV- GENERATION (those in this document as well as those in [RFC8230], [RFC8778], and [RFC9021]), the capabilities list is an array with one element, the key type (from the "COSE Key Types" Registry). It is expected that future registered algorithms could have zero, one, or multiple elements.

8.2. Assignments for Existing Key Types

There are a number of pre-existing key types; the following deals with creating the capability definition for those structures:

  • OKP, EC2: The list of capabilities is:

    • The key type value. (1 for OKP or 2 for EC2.)

    • One curve for that key type from the "COSE Elliptic Curves" registry.

  • RSA: The list of capabilities is:

    • The key type value (3).

  • Symmetric: The list of capabilities is:

    • The key type value (4).

  • HSS-LMS: The list of capabilities is:

    • The key type value (5).

    • Algorithm identifier for the underlying hash function from the "COSE Algorithms" registry.

  • WalnutDSA: The list of capabilities is:

    • The key type value (6).

    • The N value (group and matrix size) for the key, a uint.

    • The q value (finite field order) for the key, a uint.

8.3. Examples

Capabilities can be used in a key derivation process to make sure that both sides are using the same parameters. The three examples below show different ways that one might utilize parameters in specifying an application protocol:

  • Only an algorithm capability: This is useful if the protocol wants to require a specific algorithm, such as ES256, but it is agnostic about which curve is being used. This requires that the algorithm identifier be specified in the protocol. See the first example.

  • Only a key type capability: This is useful if the protocol wants to require a specific key type and curve, such as P-256, but will accept any algorithm using that curve (e.g., both ECDSA and ECDH). See the second example.

  • Both algorithm and key type capabilities: This is used if the protocol needs to nail down all of the options surrounding an algorithm -- e.g., EdDSA with the curve Ed25519. As with the first example, the algorithm identifier needs to be specified in the protocol. See the third example, which just concatenates the two capabilities together.

Algorithm ES256

0x8102 / [2 \ EC2 \ ] /

Key type EC2 with P-256 curve:

0x820201 / [2 \ EC2 , 1 \ P-256 ] /

ECDH-ES + A256KW with an X25519 curve:

0x8101820104 / [1 \ OKP ],[1 \ OKP , 4 \ X25519 ] /

The capabilities can also be used by an entity to advertise what it is capable of doing. The decoded example below is one of many encodings that could be used for that purpose. Each array element includes three fields: the algorithm identifier, one or more algorithm capabilities, and one or more key type capabilities.

[ [-8 / EdDSA /, [1 / OKP key type /], [ [1 / OKP /, 6 / Ed25519 / ], [1 /OKP/, 7 /Ed448 /] ] ], [-7 / ECDSA with SHA-256/, [2 /EC2 key type/], [ [2 /EC2/, 1 /P-256/], [2 /EC2/, 3 /P-521/] ] ], [ -31 / ECDH-ES+A256KW/, [ [ 2 /EC2/], [1 /OKP/ ] ], [ [2 /EC2/, 1 /P-256/], [1 /OKP/, 4 / X25519/ ] ] ], [ 1 / A128GCM /, [ 4 / Symmetric / ], [ 4 / Symmetric /] ] ]

Examining the above:

  • The first element indicates that the entity supports EdDSA with curves Ed25519 and Ed448.

  • The second element indicates that the entity supports ECDSA with SHA-256 with curves P-256 and P-521.

  • The third element indicates that the entity supports Ephemeral- Static ECDH using AES256 key wrap. The entity can support the P-256 curve with an EC2 key type and the X25519 curve with an OKP key type.

  • The last element indicates that the entity supports AES-GCM of 128 bits for content encryption.

The entity does not advertise that it supports any MAC algorithms.

Last updated on