7. Key Objects
- Key Objects
A COSE Key structure is built on a CBOR map. The set of common parameters that can appear in a COSE Key can be found in the IANA "COSE Key Common Parameters" registry [COSE.KeyParameters] (see Section 11.2). Additional parameters defined for specific key types can be found in the IANA "COSE Key Type Parameters" registry [COSE.KeyTypes].
A COSE Key Set uses a CBOR array object as its underlying type. The values of the array elements are COSE Keys. A COSE Key Set MUST have at least one element in the array. Examples of COSE Key Sets can be found in Appendix C.7.
Each element in a COSE Key Set MUST be processed independently. If one element in a COSE Key Set is either malformed or uses a key that is not understood by an application, that key is ignored, and the other keys are processed normally.
The element "kty" is a required element in a COSE_Key map.
The CDDL grammar describing COSE_Key and COSE_KeySet is:
COSE_Key = {
1 => tstr / int, ; kty
? 2 => bstr, ; kid
? 3 => tstr / int, ; alg
? 4 => [+ (tstr / int) ], ; key_ops
? 5 => bstr, ; Base IV
* label => values
}
COSE_KeySet = [+COSE_Key]
7.1. COSE Key Common Parameters
This document defines a set of common parameters for a COSE Key object. Table 4 provides a summary of the parameters defined in this section. There are also parameters that are defined for specific key types. Key-type-specific parameters can be found in [RFC9053].
+=========+=======+========+============+====================+
| Name | Label | CBOR | Value | Description |
| | | Type | Registry | |
+=========+=======+========+============+====================+
| kty | 1 | tstr / | COSE Key | Identification of |
| | | int | Types | the key type |
+---------+-------+--------+------------+--------------------+
| kid | 2 | bstr | | Key identification |
| | | | | value -- match to |
| | | | | "kid" in message |
+---------+-------+--------+------------+--------------------+
| alg | 3 | tstr / | COSE | Key usage |
| | | int | Algorithms | restriction to |
| | | | | this algorithm |
+---------+-------+--------+------------+--------------------+
| key_ops | 4 | [+ | | Restrict set of |
| | | (tstr/ | | permissible |
| | | int)] | | operations |
+---------+-------+--------+------------+--------------------+
| Base IV | 5 | bstr | | Base IV to be xor- |
| | | | | ed with Partial |
| | | | | IVs |
+---------+-------+--------+------------+--------------------+
Table 4: Key Map Labels
kty: This parameter is used to identify the family of keys for this structure and, thus, the set of key-type-specific parameters to be found. The set of values defined in this document can be found in [COSE.KeyTypes]. This parameter MUST be present in a key object. Implementations MUST verify that the key type is appropriate for the algorithm being processed. The key type MUST be included as part of the trust-decision process.
alg: This parameter is used to restrict the algorithm that is used with the key. If this parameter is present in the key structure, the application MUST verify that this algorithm matches the algorithm for which the key is being used. If the algorithms do not match, then this key object MUST NOT be used to perform the cryptographic operation. Note that the same key can be in a different key structure with a different or no algorithm specified; however, this is considered to be a poor security practice.
kid: This parameter is used to give an identifier for a key. The identifier is not structured and can be anything from a user- provided byte string to a value computed on the public portion of the key. This field is intended for matching against a "kid" parameter in a message in order to filter down the set of keys that need to be checked. The value of the identifier is not a unique value and can occur in other key objects, even for different keys.
key_ops: This parameter is defined to restrict the set of operations that a key is to be used for. The value of the field is an array of values from Table 5. Algorithms define the values of key ops that are permitted to appear and are required for specific operations. The set of values matches that in [RFC7517] and [W3C.WebCrypto].
Base IV: This parameter is defined to carry the base portion of an IV. It is designed to be used with the Partial IV header parameter defined in Section 3.1. This field provides the ability to associate a Base IV with a key that is then modified on a per- message basis with the Partial IV.
Extreme care needs to be taken when using a Base IV in an
application. Many encryption algorithms lose security if the same
IV is used twice.
If different keys are derived for each sender, starting at the
same Base IV is likely to satisfy this condition. If the same key
is used for multiple senders, then the application needs to
provide for a method of dividing the IV space up between the
senders. This could be done by providing a different base point
to start from or a different Partial IV to start with and
restricting the number of messages to be sent before rekeying.
+=========+=======+==============================================+
| Name | Value | Description |
+=========+=======+==============================================+
| sign | 1 | The key is used to create signatures. |
| | | Requires private key fields. |
+---------+-------+----------------------------------------------+
| verify | 2 | The key is used for verification of |
| | | signatures. |
+---------+-------+----------------------------------------------+
| encrypt | 3 | The key is used for key transport |
| | | encryption. |
+---------+-------+----------------------------------------------+
| decrypt | 4 | The key is used for key transport |
| | | decryption. Requires private key fields. |
+---------+-------+----------------------------------------------+
| wrap | 5 | The key is used for key wrap encryption. |
| key | | |
+---------+-------+----------------------------------------------+
| unwrap | 6 | The key is used for key wrap decryption. |
| key | | Requires private key fields. |
+---------+-------+----------------------------------------------+
| derive | 7 | The key is used for deriving keys. Requires |
| key | | private key fields. |
+---------+-------+----------------------------------------------+
| derive | 8 | The key is used for deriving bits not to be |
| bits | | used as a key. Requires private key fields. |
+---------+-------+----------------------------------------------+
| MAC | 9 | The key is used for creating MACs. |
| create | | |
+---------+-------+----------------------------------------------+
| MAC | 10 | The key is used for validating MACs. |
| verify | | |
+---------+-------+----------------------------------------------+
Table 5: Key Operation Values