7. Key Object Parameters
- Key Object Parameters
The COSE_Key object defines a way to hold a single key object. It is still required that the members of individual key types be defined. This section of the document is where we define an initial set of members for specific key types.
For each of the key types, we define both public and private members. The public members are what is transmitted to others for their usage. Private members allow individuals to archive keys. However, there are some circumstances in which private keys may be distributed to entities in a protocol. Examples include: entities that have poor random number generation, centralized key creation for multicast-type operations, and protocols in which a shared secret is used as a bearer token for authorization purposes.
Key types are identified by the "kty" member of the COSE_Key object. In this document, we define four values for the member:
+===========+=======+==========================+
| Name | Value | Description |
+===========+=======+==========================+
| OKP | 1 | Octet Key Pair |
+-----------+-------+--------------------------+
| EC2 | 2 | Elliptic Curve Keys w/ |
| | | x- and y-coordinate pair |
+-----------+-------+--------------------------+
| Symmetric | 4 | Symmetric Keys |
+-----------+-------+--------------------------+
| Reserved | 0 | This value is reserved |
+-----------+-------+--------------------------+
Table 17: Key Type Values
7.1. Elliptic Curve Keys
Two different key structures are defined for elliptic curve keys. One version uses both an x-coordinate and a y-coordinate, potentially with point compression ("EC2"). This is the conventional elliptic curve (EC) point representation that is used in [RFC5480]. The other version uses only the x-coordinate, as the y-coordinate is either to be recomputed or not needed for the key agreement operation ("OKP").
Applications MUST check that the curve and the key type are consistent and reject a key if they are not.
+=========+=======+==========+=====================================+ | Name | Value | Key Type | Description | +=========+=======+==========+=====================================+ | P-256 | 1 | EC2 | NIST P-256, also known as secp256r1 | +---------+-------+----------+-------------------------------------+ | P-384 | 2 | EC2 | NIST P-384, also known as secp384r1 | +---------+-------+----------+-------------------------------------+ | P-521 | 3 | EC2 | NIST P-521, also known as secp521r1 | +---------+-------+----------+-------------------------------------+ | X25519 | 4 | OKP | X25519 for use w/ ECDH only | +---------+-------+----------+-------------------------------------+ | X448 | 5 | OKP | X448 for use w/ ECDH only | +---------+-------+----------+-------------------------------------+ | Ed25519 | 6 | OKP | Ed25519 for use w/ EdDSA only | +---------+-------+----------+-------------------------------------+ | Ed448 | 7 | OKP | Ed448 for use w/ EdDSA only | +---------+-------+----------+-------------------------------------+
Table 18: Elliptic Curves
7.1.1. Double Coordinate Curves
Generally, protocols transmit elliptic-curve points as either the x-coordinate and y-coordinate or the x-coordinate and a sign bit for the y-coordinate. The latter encoding has not been recommended by the IETF due to potential IPR issues. However, for operations in constrained environments, the ability to shrink a message by not sending the y-coordinate is potentially useful.
For EC keys with both coordinates, the "kty" member is set to 2 (EC2). The key parameters defined in this section are summarized in Table 19. The members that are defined for this key type are:
crv: This contains an identifier of the curve to be used with the key. The curves defined in this document for this key type can be found in Table 18. Other curves may be registered in the future, and private curves can be used as well.
x: This contains the x-coordinate for the EC point. The integer is converted to a byte string as defined in [SEC1]. Leading- zero octets MUST be preserved.
y: This contains either the sign bit or the value of the y-coordinate for the EC point. When encoding the value y, the integer is converted to a byte string (as defined in [SEC1]) and encoded as a CBOR bstr. Leading-zero octets MUST be preserved. Compressed point encoding is also supported. Compute the sign bit as laid out in the Elliptic-Curve-Point- to-Octet-String Conversion function of [SEC1]. If the sign bit is zero, then encode y as a CBOR false value; otherwise, encode y as a CBOR true value. The encoding of the infinity point is not supported.
d: This contains the private key.
For public keys, it is REQUIRED that "crv", "x", and "y" be present in the structure. For private keys, it is REQUIRED that "crv" and "d" be present in the structure. For private keys, it is RECOMMENDED that "x" and "y" also be present, but they can be recomputed from the required elements, and omitting them saves on space.
+======+======+=======+========+=================================+
| Key | Name | Label | CBOR | Description |
| Type | | | Type | |
+======+======+=======+========+=================================+
| 2 | crv | -1 | int / | EC identifier -- Taken from the |
| | | | tstr | "COSE Elliptic Curves" registry |
+------+------+-------+--------+---------------------------------+
| 2 | x | -2 | bstr | x-coordinate |
+------+------+-------+--------+---------------------------------+
| 2 | y | -3 | bstr / | y-coordinate |
| | | | bool | |
+------+------+-------+--------+---------------------------------+
| 2 | d | -4 | bstr | Private key |
+------+------+-------+--------+---------------------------------+
Table 19: EC Key Parameters
7.2. Octet Key Pair
A new key type is defined for Octet Key Pairs (OKPs). Do not assume that keys using this type are elliptic curves. This key type could be used for other curve types (for example, mathematics based on hyper-elliptic surfaces).
The key parameters defined in this section are summarized in Table 20. The members that are defined for this key type are:
crv: This contains an identifier of the curve to be used with the key. The curves defined in this document for this key type can be found in Table 18. Other curves may be registered in the future, and private curves can be used as well.
x: This contains the public key. The byte string contains the public key as defined by the algorithm. (For X25519, internally it is a little-endian integer.)
d: This contains the private key.
For public keys, it is REQUIRED that "crv" and "x" be present in the structure. For private keys, it is REQUIRED that "crv" and "d" be present in the structure. For private keys, it is RECOMMENDED that "x" also be present, but it can be recomputed from the required elements, and omitting it saves on space.
+======+==========+=======+=======+=================================+ | Name | Key | Label | Type | Description | | | Type | | | | +======+==========+=======+=======+=================================+ | crv | 1 | -1 | int / | EC identifier -- Taken from the | | | | | tstr | "COSE Elliptic Curves" registry | +------+----------+-------+-------+---------------------------------+ | x | 1 | -2 | bstr | Public Key | +------+----------+-------+-------+---------------------------------+ | d | 1 | -4 | bstr | Private key | +------+----------+-------+-------+---------------------------------+
Table 20: Octet Key Pair Parameters
7.3. Symmetric Keys
Occasionally, it is required that a symmetric key be transported between entities. This key structure allows for that to happen.
For symmetric keys, the "kty" member is set to 4 ("Symmetric"). The member that is defined for this key type is:
k: This contains the value of the key.
This key structure does not have a form that contains only public members. As it is expected that this key structure is going to be transmitted, care must be taken that it is never transmitted accidentally or insecurely. For symmetric keys, it is REQUIRED that "k" be present in the structure.
+======+==========+=======+======+=============+
| Name | Key Type | Label | Type | Description |
+======+==========+=======+======+=============+
| k | 4 | -1 | bstr | Key Value |
+------+----------+-------+------+-------------+
Table 21: Symmetric Key Parameters