RFC 8152
CBOR Object Signing and Encryption (COSE)
11. Key Derivation Functions (KDFs)
KDFs are used to take some secret value and generate a different one. The secret value comes in three flavors: o Secrets that are uniformly random: This is the type of secret that is created by a good random number generator. o Secrets that are not uniformly random: This is type of secret that is created by operations like key agreement. o Secrets that are not random: This is the type of secret that people generate for things like passwords.
General KDFs work well with the first type of secret, can do reasonably well with the second type of secret, and generally do poorly with the last type of secret. None of the KDFs in this section are designed to deal with the type of secrets that are used for passwords. Functions like PBES2 [RFC8018] need to be used for that type of secret. The same KDF can be set up to deal with the first two types of secrets in a different way. The KDF defined in Section 11.1 is such a function. This is reflected in the set of algorithms defined for the HMAC-based Extract-and-Expand Key Derivation Function (HKDF). When using KDFs, one component that is included is context information. Context information is used to allow for different keying information to be derived from the same secret. The use of context-based keying material is considered to be a good security practice. This document defines a single context structure and a single KDF. These elements are used for all of the recipient algorithms defined in this document that require a KDF process. These algorithms are defined in Sections 12.1.2, 12.4.1, and 12.5.1.11.1. HMAC-Based Extract-and-Expand Key Derivation Function (HKDF)
The HKDF key derivation algorithm is defined in [RFC5869]. The HKDF algorithm takes these inputs: secret -- a shared value that is secret. Secrets may be either previously shared or derived from operations like a Diffie-Hellman (DH) key agreement. salt -- an optional value that is used to change the generation process. The salt value can be either public or private. If the salt is public and carried in the message, then the 'salt' algorithm header parameter defined in Table 13 is used. While [RFC5869] suggests that the length of the salt be the same as the length of the underlying hash value, any amount of salt will improve the security as different key values will be generated. This parameter is protected by being included in the key computation and does not need to be separately authenticated. The salt value does not need to be unique for every message sent. length -- the number of bytes of output that need to be generated.
context information -- Information that describes the context in
which the resulting value will be used. Making this information
specific to the context in which the material is going to be used
ensures that the resulting material will always be tied to that
usage. The context structure defined in Section 11.2 is used by
the KDFs in this document.
PRF -- The underlying pseudorandom function to be used in the HKDF
algorithm. The PRF is encoded into the HKDF algorithm selection.
HKDF is defined to use HMAC as the underlying PRF. However, it is
possible to use other functions in the same construct to provide a
different KDF that is more appropriate in the constrained world.
Specifically, one can use AES-CBC-MAC as the PRF for the expand step,
but not for the extract step. When using a good random shared secret
of the correct length, the extract step can be skipped. For the AES
algorithm versions, the extract step is always skipped.
The extract step cannot be skipped if the secret is not uniformly
random, for example, if it is the result of an ECDH key agreement
step. This implies that the AES HKDF version cannot be used with
ECDH. If the extract step is skipped, the 'salt' value is not used
as part of the HKDF functionality.
The algorithms defined in this document are found in Table 12.
+---------------+-----------------+---------------------------------+
| Name | PRF | Description |
+---------------+-----------------+---------------------------------+
| HKDF SHA-256 | HMAC with | HKDF using HMAC SHA-256 as the |
| | SHA-256 | PRF |
| HKDF SHA-512 | HMAC with | HKDF using HMAC SHA-512 as the |
| | SHA-512 | PRF |
| HKDF AES- | AES-CBC-MAC-128 | HKDF using AES-MAC as the PRF |
| MAC-128 | | w/ 128-bit key |
| HKDF AES- | AES-CBC-MAC-256 | HKDF using AES-MAC as the PRF |
| MAC-256 | | w/ 256-bit key |
+---------------+-----------------+---------------------------------+
Table 12: HKDF Algorithms
+------+-------+------+-------------------------------+-------------+ | Name | Label | Type | Algorithm | Description | +------+-------+------+-------------------------------+-------------+ | salt | -20 | bstr | direct+HKDF-SHA-256, direct | Random salt | | | | | +HKDF-SHA-512, direct+HKDF- | | | | | | AES-128, direct+HKDF-AES-256, | | | | | | ECDH-ES+HKDF-256, ECDH- | | | | | | ES+HKDF-512, ECDH- | | | | | | SS+HKDF-256, ECDH- | | | | | | SS+HKDF-512, ECDH-ES+A128KW, | | | | | | ECDH-ES+A192KW, ECDH- | | | | | | ES+A256KW, ECDH-SS+A128KW, | | | | | | ECDH-SS+A192KW, ECDH- | | | | | | SS+A256KW | | +------+-------+------+-------------------------------+-------------+ Table 13: HKDF Algorithm Parameters11.2. Context Information Structure
The context information structure is used to ensure that the derived keying material is "bound" to the context of the transaction. The context information structure used here is based on that defined in [SP800-56A]. By using CBOR for the encoding of the context information structure, we automatically get the same type and length separation of fields that is obtained by the use of ASN.1. This means that there is no need to encode the lengths for the base elements, as it is done by the encoding used in JOSE (Section 4.6.2 of [RFC7518]). The context information structure refers to PartyU and PartyV as the two parties that are doing the key derivation. Unless the application protocol defines differently, we assign PartyU to the entity that is creating the message and PartyV to the entity that is receiving the message. By doing this association, different keys will be derived for each direction as the context information is different in each direction. The context structure is built from information that is known to both entities. This information can be obtained from a variety of sources: o Fields can be defined by the application. This is commonly used to assign fixed names to parties, but it can be used for other items such as nonces. o Fields can be defined by usage of the output. Examples of this are the algorithm and key size that are being generated.
o Fields can be defined by parameters from the message. We define a
set of parameters in Table 14 that can be used to carry the values
associated with the context structure. Examples of this are
identities and nonce values. These parameters are designed to be
placed in the unprotected bucket of the recipient structure; they
do not need to be in the protected bucket since they already are
included in the cryptographic computation by virtue of being
included in the context structure.
+----------+-------+------+---------------------------+-------------+
| Name | Label | Type | Algorithm | Description |
+----------+-------+------+---------------------------+-------------+
| PartyU | -21 | bstr | direct+HKDF-SHA-256, | Party U |
| identity | | | direct+HKDF-SHA-512, | identity |
| | | | direct+HKDF-AES-128, | information |
| | | | direct+HKDF-AES-256, | |
| | | | ECDH-ES+HKDF-256, ECDH- | |
| | | | ES+HKDF-512, ECDH- | |
| | | | SS+HKDF-256, ECDH- | |
| | | | SS+HKDF-512, ECDH- | |
| | | | ES+A128KW, ECDH- | |
| | | | ES+A192KW, ECDH- | |
| | | | ES+A256KW, ECDH- | |
| | | | SS+A128KW, ECDH- | |
| | | | SS+A192KW, ECDH-SS+A256KW | |
| | | | | |
| PartyU | -22 | bstr | direct+HKDF-SHA-256, | Party U |
| nonce | | / | direct+HKDF-SHA-512, | provided |
| | | int | direct+HKDF-AES-128, | nonce |
| | | | direct+HKDF-AES-256, | |
| | | | ECDH-ES+HKDF-256, ECDH- | |
| | | | ES+HKDF-512, ECDH- | |
| | | | SS+HKDF-256, ECDH- | |
| | | | SS+HKDF-512, ECDH- | |
| | | | ES+A128KW, ECDH- | |
| | | | ES+A192KW, ECDH- | |
| | | | ES+A256KW, ECDH- | |
| | | | SS+A128KW, ECDH- | |
| | | | SS+A192KW, ECDH-SS+A256KW | |
| | | | | |
| PartyU | -23 | bstr | direct+HKDF-SHA-256, | Party U |
| other | | | direct+HKDF-SHA-512, | other |
| | | | direct+HKDF-AES-128, | provided |
| | | | direct+HKDF-AES-256, | information |
| | | | ECDH-ES+HKDF-256, ECDH- | |
| | | | ES+HKDF-512, ECDH- | |
| | | | SS+HKDF-256, ECDH- | |
| | | | SS+HKDF-512, ECDH- | |
| | | | ES+A128KW, ECDH- | |
| | | | ES+A192KW, ECDH- | |
| | | | ES+A256KW, ECDH- | |
| | | | SS+A128KW, ECDH- | |
| | | | SS+A192KW, ECDH-SS+A256KW | |
| PartyV | -24 | bstr | direct+HKDF-SHA-256, | Party V | | identity | | | direct+HKDF-SHA-512, | identity | | | | | direct+HKDF-AES-128, | information | | | | | direct+HKDF-AES-256, | | | | | | ECDH-ES+HKDF-256, ECDH- | | | | | | ES+HKDF-512, ECDH- | | | | | | SS+HKDF-256, ECDH- | | | | | | SS+HKDF-512, ECDH- | | | | | | ES+A128KW, ECDH- | | | | | | ES+A192KW, ECDH- | | | | | | ES+A256KW, ECDH- | | | | | | SS+A128KW, ECDH- | | | | | | SS+A192KW, ECDH-SS+A256KW | | | | | | | | | PartyV | -25 | bstr | direct+HKDF-SHA-256, | Party V | | nonce | | / | direct+HKDF-SHA-512, | provided | | | | int | direct+HKDF-AES-128, | nonce | | | | | direct+HKDF-AES-256, | | | | | | ECDH-ES+HKDF-256, ECDH- | | | | | | ES+HKDF-512, ECDH- | | | | | | SS+HKDF-256, ECDH- | | | | | | SS+HKDF-512, ECDH- | | | | | | ES+A128KW, ECDH- | | | | | | ES+A192KW, ECDH- | | | | | | ES+A256KW, ECDH- | | | | | | SS+A128KW, ECDH- | | | | | | SS+A192KW, ECDH-SS+A256KW | | | | | | | | | PartyV | -26 | bstr | direct+HKDF-SHA-256, | Party V | | other | | | direct+HKDF-SHA-512, | other | | | | | direct+HKDF-AES-128, | provided | | | | | direct+HKDF-AES-256, | information | | | | | ECDH-ES+HKDF-256, ECDH- | | | | | | ES+HKDF-512, ECDH- | | | | | | SS+HKDF-256, ECDH- | | | | | | SS+HKDF-512, ECDH- | | | | | | ES+A128KW, ECDH- | | | | | | ES+A192KW, ECDH- | | | | | | ES+A256KW, ECDH- | | | | | | SS+A128KW, ECDH- | | | | | | SS+A192KW, ECDH-SS+A256KW | | +----------+-------+------+---------------------------+-------------+ Table 14: Context Algorithm Parameters
We define a CBOR object to hold the context information. This object
is referred to as COSE_KDF_Context. The object is based on a CBOR
array type. The fields in the array are:
AlgorithmID: This field indicates the algorithm for which the key
material will be used. This normally is either a key wrap
algorithm identifier or a content encryption algorithm identifier.
The values are from the "COSE Algorithms" registry. This field is
required to be present. The field exists in the context
information so that if the same environment is used for different
algorithms, then completely different keys will be generated for
each of those algorithms. This practice means if algorithm A is
broken and thus is easier to find, the key derived for algorithm B
will not be the same as the key derived for algorithm A.
PartyUInfo: This field holds information about party U. The
PartyUInfo is encoded as a CBOR array. The elements of PartyUInfo
are encoded in the order presented. The elements of the
PartyUInfo array are:
identity: This contains the identity information for party U.
The identities can be assigned in one of two manners. First, a
protocol can assign identities based on roles. For example,
the roles of "client" and "server" may be assigned to different
entities in the protocol. Each entity would then use the
correct label for the data they send or receive. The second
way for a protocol to assign identities is to use a name based
on a naming system (i.e., DNS, X.509 names).
We define an algorithm parameter 'PartyU identity' that can be
used to carry identity information in the message. However,
identity information is often known as part of the protocol and
can thus be inferred rather than made explicit. If identity
information is carried in the message, applications SHOULD have
a way of validating the supplied identity information. The
identity information does not need to be specified and is set
to nil in that case.
nonce: This contains a nonce value. The nonce can either be
implicit from the protocol or be carried as a value in the
unprotected headers.
We define an algorithm parameter 'PartyU nonce' that can be
used to carry this value in the message; however, the nonce
value could be determined by the application and the value
determined from elsewhere.
This option does not need to be specified and is set to nil in
that case.
other: This contains other information that is defined by the
protocol. This option does not need to be specified and is set
to nil in that case.
PartyVInfo: This field holds information about party V. The content
of the structure is the same as for the PartyUInfo but for party
V.
SuppPubInfo: This field contains public information that is mutually
known to both parties.
keyDataLength: This is set to the number of bits of the desired
output value. This practice means if algorithm A can use two
different key lengths, the key derived for longer key size will
not contain the key for shorter key size as a prefix.
protected: This field contains the protected parameter field. If
there are no elements in the protected field, then use a zero-
length bstr.
other: This field is for free form data defined by the
application. An example is that an application could define
two different strings to be placed here to generate different
keys for a data stream versus a control stream. This field is
optional and will only be present if the application defines a
structure for this information. Applications that define this
SHOULD use CBOR to encode the data so that types and lengths
are correctly included.
SuppPrivInfo: This field contains private information that is
mutually known private information. An example of this
information would be a preexisting shared secret. (This could,
for example, be used in combination with an ECDH key agreement to
provide a secondary proof of identity.) The field is optional and
will only be present if the application defines a structure for
this information. Applications that define this SHOULD use CBOR
to encode the data so that types and lengths are correctly
included.
The following CDDL fragment corresponds to the text above.
PartyInfo = (
identity : bstr / nil,
nonce : bstr / int / nil,
other : bstr / nil
)
COSE_KDF_Context = [
AlgorithmID : int / tstr,
PartyUInfo : [ PartyInfo ],
PartyVInfo : [ PartyInfo ],
SuppPubInfo : [
keyDataLength : uint,
protected : empty_or_serialized_map,
? other : bstr
],
? SuppPrivInfo : bstr
]
12. Content Key Distribution Methods
Content key distribution methods (recipient algorithms) can be
defined into a number of different classes. COSE has the ability to
support many classes of recipient algorithms. In this section, a
number of classes are listed, and then a set of algorithms are
specified for each of the classes. The names of the recipient
algorithm classes used here are the same as those defined in
[RFC7516]. Other specifications use different terms for the
recipient algorithm classes or do not support some of the recipient
algorithm classes.
12.1. Direct Encryption
The direct encryption class algorithms share a secret between the
sender and the recipient that is used either directly or after
manipulation as the CEK. When direct encryption mode is used, it
MUST be the only mode used on the message.
The COSE_Recipient structure for the recipient is organized as
follows:
o The 'protected' field MUST be a zero-length item unless it is used
in the computation of the content key.
o The 'alg' parameter MUST be present.
o A parameter identifying the shared secret SHOULD be present.
o The 'ciphertext' field MUST be a zero-length item. o The 'recipients' field MUST be absent.12.1.1. Direct Key
This recipient algorithm is the simplest; the identified key is directly used as the key for the next layer down in the message. There are no algorithm parameters defined for this algorithm. The algorithm identifier value is assigned in Table 15. When this algorithm is used, the protected field MUST be zero length. The key type MUST be 'Symmetric'. +--------+-------+-------------------+ | Name | Value | Description | +--------+-------+-------------------+ | direct | -6 | Direct use of CEK | +--------+-------+-------------------+ Table 15: Direct Key12.1.1.1. Security Considerations
This recipient algorithm has several potential problems that need to be considered: o These keys need to have some method to be regularly updated over time. All of the content encryption algorithms specified in this document have limits on how many times a key can be used without significant loss of security. o These keys need to be dedicated to a single algorithm. There have been a number of attacks developed over time when a single key is used for multiple different algorithms. One example of this is the use of a single key for both the CBC encryption mode and the CBC-MAC authentication mode. o Breaking one message means all messages are broken. If an adversary succeeds in determining the key for a single message, then the key for all messages is also determined.12.1.2. Direct Key with KDF
These recipient algorithms take a common shared secret between the two parties and applies the HKDF function (Section 11.1), using the context structure defined in Section 11.2 to transform the shared
secret into the CEK. The 'protected' field can be of non-zero length. Either the 'salt' parameter of HKDF or the 'PartyU nonce' parameter of the context structure MUST be present. The salt/nonce parameter can be generated either randomly or deterministically. The requirement is that it be a unique value for the shared secret in question. If the salt/nonce value is generated randomly, then it is suggested that the length of the random value be the same length as the hash function underlying HKDF. While there is no way to guarantee that it will be unique, there is a high probability that it will be unique. If the salt/nonce value is generated deterministically, it can be guaranteed to be unique, and thus there is no length requirement. A new IV must be used for each message if the same key is used. The IV can be modified in a predictable manner, a random manner, or an unpredictable manner (i.e., encrypting a counter). The IV used for a key can also be generated from the same HKDF functionality as the key is generated. If HKDF is used for generating the IV, the algorithm identifier is set to "IV- GENERATION". When these algorithms are used, the key type MUST be 'symmetric'. The set of algorithms defined in this document can be found in Table 16. +---------------------+-------+-------------+-----------------------+ | Name | Value | KDF | Description | +---------------------+-------+-------------+-----------------------+ | direct+HKDF-SHA-256 | -10 | HKDF | Shared secret w/ HKDF | | | | SHA-256 | and SHA-256 | | direct+HKDF-SHA-512 | -11 | HKDF | Shared secret w/ HKDF | | | | SHA-512 | and SHA-512 | | direct+HKDF-AES-128 | -12 | HKDF AES- | Shared secret w/ AES- | | | | MAC-128 | MAC 128-bit key | | direct+HKDF-AES-256 | -13 | HKDF AES- | Shared secret w/ AES- | | | | MAC-256 | MAC 256-bit key | +---------------------+-------+-------------+-----------------------+ Table 16: Direct Key with KDF
When using a COSE key for this algorithm, the following checks are
made:
o The 'kty' field MUST be present, and it MUST be 'Symmetric'.
o If the 'alg' field is present, it MUST match the algorithm being
used.
o If the 'key_ops' field is present, it MUST include 'deriveKey' or
'deriveBits'.
12.1.2.1. Security Considerations
The shared secret needs to have some method to be regularly updated
over time. The shared secret forms the basis of trust. Although not
used directly, it should still be subject to scheduled rotation.
While these methods do not provide for perfect forward secrecy, as
the same shared secret is used for all of the keys generated, if the
key for any single message is discovered, only the message (or series
of messages) using that derived key are compromised. A new key
derivation step will generate a new key that requires the same amount
of work to get the key.
12.2. Key Wrap
In key wrap mode, the CEK is randomly generated and that key is then
encrypted by a shared secret between the sender and the recipient.
All of the currently defined key wrap algorithms for COSE are AE
algorithms. Key wrap mode is considered to be superior to direct
encryption if the system has any capability for doing random key
generation. This is because the shared key is used to wrap random
data rather than data that has some degree of organization and may in
fact be repeating the same content. The use of key wrap loses the
weak data origination that is provided by the direct encryption
algorithms.
The COSE_Encrypt structure for the recipient is organized as follows:
o The 'protected' field MUST be absent if the key wrap algorithm is
an AE algorithm.
o The 'recipients' field is normally absent, but can be used.
Applications MUST deal with a recipient field being present, not
being able to decrypt that recipient is an acceptable way of
dealing with it. Failing to process the message is not an
acceptable way of dealing with it.
o The plaintext to be encrypted is the key from next layer down
(usually the content layer).
o At a minimum, the 'unprotected' field MUST contain the 'alg'
parameter and SHOULD contain a parameter identifying the shared
secret.
12.2.1. AES Key Wrap
The AES Key Wrap algorithm is defined in [RFC3394]. This algorithm
uses an AES key to wrap a value that is a multiple of 64 bits. As
such, it can be used to wrap a key for any of the content encryption
algorithms defined in this document. The algorithm requires a single
fixed parameter, the initial value. This is fixed to the value
specified in Section 2.2.3.1 of [RFC3394]. There are no public
parameters that vary on a per-invocation basis. The protected header
field MUST be empty.
Keys may be obtained either from a key structure or from a recipient
structure. Implementations encrypting and decrypting MUST validate
that the key type, key length, and algorithm are correct and
appropriate for the entities involved.
When using a COSE key for this algorithm, the following checks are
made:
o The 'kty' field MUST be present, and it MUST be 'Symmetric'.
o If the 'alg' field is present, it MUST match the AES Key Wrap
algorithm being used.
o If the 'key_ops' field is present, it MUST include 'encrypt' or
'wrap key' when encrypting.
o If the 'key_ops' field is present, it MUST include 'decrypt' or
'unwrap key' when decrypting.
+--------+-------+----------+-----------------------------+
| Name | Value | Key Size | Description |
+--------+-------+----------+-----------------------------+
| A128KW | -3 | 128 | AES Key Wrap w/ 128-bit key |
| A192KW | -4 | 192 | AES Key Wrap w/ 192-bit key |
| A256KW | -5 | 256 | AES Key Wrap w/ 256-bit key |
+--------+-------+----------+-----------------------------+
Table 17: AES Key Wrap Algorithm Values
12.2.1.1. Security Considerations for AES-KW
The shared secret needs to have some method to be regularly updated over time. The shared secret is the basis of trust.12.3. Key Transport
Key transport mode is also called key encryption mode in some standards. Key transport mode differs from key wrap mode in that it uses an asymmetric encryption algorithm rather than a symmetric encryption algorithm to protect the key. This document does not define any key transport mode algorithms. When using a key transport algorithm, the COSE_Encrypt structure for the recipient is organized as follows: o The 'protected' field MUST be absent. o The plaintext to be encrypted is the key from the next layer down (usually the content layer). o At a minimum, the 'unprotected' field MUST contain the 'alg' parameter and SHOULD contain a parameter identifying the asymmetric key.12.4. Direct Key Agreement
The 'direct key agreement' class of recipient algorithms uses a key agreement method to create a shared secret. A KDF is then applied to the shared secret to derive a key to be used in protecting the data. This key is normally used as a CEK or MAC key, but could be used for other purposes if more than two layers are in use (see Appendix B). The most commonly used key agreement algorithm is Diffie-Hellman, but other variants exist. Since COSE is designed for a store and forward environment rather than an online environment, many of the DH variants cannot be used as the receiver of the message cannot provide any dynamic key material. One side effect of this is that perfect forward secrecy (see [RFC4949]) is not achievable. A static key will always be used for the receiver of the COSE object. Two variants of DH that are supported are: Ephemeral-Static (ES) DH: where the sender of the message creates a one-time DH key and uses a static key for the recipient. The use of the ephemeral sender key means that no additional random input is needed as this is randomly generated for each message.
Static-Static DH: where a static key is used for both the sender
and the recipient. The use of static keys allows for the
recipient to get a weak version of data origination for the
message. When static-static key agreement is used, then some
piece of unique data for the KDF is required to ensure that a
different key is created for each message.
When direct key agreement mode is used, there MUST be only one
recipient in the message. This method creates the key directly, and
that makes it difficult to mix with additional recipients. If
multiple recipients are needed, then the version with key wrap needs
to be used.
The COSE_Encrypt structure for the recipient is organized as follows:
o At a minimum, headers MUST contain the 'alg' parameter and SHOULD
contain a parameter identifying the recipient's asymmetric key.
o The headers SHOULD identify the sender's key for the static-static
versions and MUST contain the sender's ephemeral key for the
ephemeral-static versions.
12.4.1. ECDH
The mathematics for ECDH can be found in [RFC6090]. In this
document, the algorithm is extended to be used with the two curves
defined in [RFC7748].
ECDH is parameterized by the following:
o Curve Type/Curve: The curve selected controls not only the size of
the shared secret, but the mathematics for computing the shared
secret. The curve selected also controls how a point in the curve
is represented and what happens for the identity points on the
curve. In this specification, we allow for a number of different
curves to be used. A set of curves are defined in Table 22.
The math used to obtain the computed secret is based on the curve
selected and not on the ECDH algorithm. For this reason, a new
algorithm does not need to be defined for each of the curves.
o Computed Secret to Shared Secret: Once the computed secret is
known, the resulting value needs to be converted to a byte string
to run the KDF. The x-coordinate is used for all of the curves
defined in this document. For curves X25519 and X448, the
resulting value is used directly as it is a byte string of a known
length. For the P-256, P-384, and P-521 curves, the x-coordinate
is run through the I2OSP function defined in [RFC8017], using the
same computation for n as is defined in Section 8.1.
o Ephemeral-Static or Static-Static: The key agreement process may
be done using either a static or an ephemeral key for the sender's
side. When using ephemeral keys, the sender MUST generate a new
ephemeral key for every key agreement operation. The ephemeral
key is placed in the 'ephemeral key' parameter and MUST be present
for all algorithm identifiers that use ephemeral keys. When using
static keys, the sender MUST either generate a new random value or
create a unique value. For the KDFs used, this means either the
'salt' parameter for HKDF (Table 13) or the 'PartyU nonce'
parameter for the context structure (Table 14) MUST be present
(both can be present if desired). The value in the parameter MUST
be unique for the pair of keys being used. It is acceptable to
use a global counter that is incremented for every static-static
operation and use the resulting value. When using static keys,
the static key should be identified to the recipient. The static
key can be identified either by providing the key ('static key')
or by providing a key identifier for the static key ('static key
id'). Both of these parameters are defined in Table 19.
o Key Derivation Algorithm: The result of an ECDH key agreement
process does not provide a uniformly random secret. As such, it
needs to be run through a KDF in order to produce a usable key.
Processing the secret through a KDF also allows for the
introduction of context material: how the key is going to be used
and one-time material for static-static key agreement. All of the
algorithms defined in this document use one of the HKDF algorithms
defined in Section 11.1 with the context structure defined in
Section 11.2.
o Key Wrap Algorithm: No key wrap algorithm is used. This is
represented in Table 18 as 'none'. The key size for the context
structure is the content layer encryption algorithm size.
The set of direct ECDH algorithms defined in this document are found
in Table 18.
+-----------+-------+---------+------------+--------+---------------+ | Name | Value | KDF | Ephemeral- | Key | Description | | | | | Static | Wrap | | +-----------+-------+---------+------------+--------+---------------+ | ECDH-ES + | -25 | HKDF - | yes | none | ECDH ES w/ | | HKDF-256 | | SHA-256 | | | HKDF - | | | | | | | generate key | | | | | | | directly | | ECDH-ES + | -26 | HKDF - | yes | none | ECDH ES w/ | | HKDF-512 | | SHA-512 | | | HKDF - | | | | | | | generate key | | | | | | | directly | | ECDH-SS + | -27 | HKDF - | no | none | ECDH SS w/ | | HKDF-256 | | SHA-256 | | | HKDF - | | | | | | | generate key | | | | | | | directly | | ECDH-SS + | -28 | HKDF - | no | none | ECDH SS w/ | | HKDF-512 | | SHA-512 | | | HKDF - | | | | | | | generate key | | | | | | | directly | +-----------+-------+---------+------------+--------+---------------+ Table 18: ECDH Algorithm Values +-----------+-------+----------+---------------------+--------------+ | Name | Label | Type | Algorithm | Description | +-----------+-------+----------+---------------------+--------------+ | ephemeral | -1 | COSE_Key | ECDH-ES+HKDF-256, | Ephemeral | | key | | | ECDH-ES+HKDF-512, | public key | | | | | ECDH-ES+A128KW, | for the | | | | | ECDH-ES+A192KW, | sender | | | | | ECDH-ES+A256KW | | | static | -2 | COSE_Key | ECDH-SS+HKDF-256, | Static | | key | | | ECDH-SS+HKDF-512, | public key | | | | | ECDH-SS+A128KW, | for the | | | | | ECDH-SS+A192KW, | sender | | | | | ECDH-SS+A256KW | | | static | -3 | bstr | ECDH-SS+HKDF-256, | Static | | key id | | | ECDH-SS+HKDF-512, | public key | | | | | ECDH-SS+A128KW, | identifier | | | | | ECDH-SS+A192KW, | for the | | | | | ECDH-SS+A256KW | sender | +-----------+-------+----------+---------------------+--------------+ Table 19: ECDH Algorithm Parameters
This document defines these algorithms to be used with the curves
P-256, P-384, P-521, X25519, and X448. Implementations MUST verify
that the key type and curve are correct. Different curves are
restricted to different key types. Implementations MUST verify that
the curve and algorithm are appropriate for the entities involved.
When using a COSE key for this algorithm, the following checks are
made:
o The 'kty' field MUST be present, and it MUST be 'EC2' or 'OKP'.
o If the 'alg' field is present, it MUST match the key agreement
algorithm being used.
o If the 'key_ops' field is present, it MUST include 'derive key' or
'derive bits' for the private key.
o If the 'key_ops' field is present, it MUST be empty for the public
key.
12.4.2. Security Considerations
There is a method of checking that points provided from external
entities are valid. For the 'EC2' key format, this can be done by
checking that the x and y values form a point on the curve. For the
'OKP' format, there is no simple way to do point validation.
Consideration was given to requiring that the public keys of both
entities be provided as part of the key derivation process (as
recommended in Section 6.1 of [RFC7748]). This was not done as COSE
is used in a store and forward format rather than in online key
exchange. In order for this to be a problem, either the receiver
public key has to be chosen maliciously or the sender has to be
malicious. In either case, all security evaporates anyway.
A proof of possession of the private key associated with the public
key is recommended when a key is moved from untrusted to trusted
(either by the end user or by the entity that is responsible for
making trust statements on keys).
12.5. Key Agreement with Key Wrap
Key Agreement with Key Wrap uses a randomly generated CEK. The CEK
is then encrypted using a key wrap algorithm and a key derived from
the shared secret computed by the key agreement algorithm. The
function for this would be:
encryptedKey = KeyWrap(KDF(DH-Shared, context), CEK)
The COSE_Encrypt structure for the recipient is organized as follows:
o The 'protected' field is fed into the KDF context structure.
o The plaintext to be encrypted is the key from the next layer down
(usually the content layer).
o The 'alg' parameter MUST be present in the layer.
o A parameter identifying the recipient's key SHOULD be present. A
parameter identifying the sender's key SHOULD be present.
12.5.1. ECDH
These algorithms are defined in Table 20.
ECDH with Key Agreement is parameterized by the same parameters as
for ECDH; see Section 12.4.1, with the following modifications:
o Key Wrap Algorithm: Any of the key wrap algorithms defined in
Section 12.2.1 are supported. The size of the key used for the
key wrap algorithm is fed into the KDF. The set of identifiers
are found in Table 20.
+-----------+-------+---------+------------+--------+---------------+ | Name | Value | KDF | Ephemeral- | Key | Description | | | | | Static | Wrap | | +-----------+-------+---------+------------+--------+---------------+ | ECDH-ES + | -29 | HKDF - | yes | A128KW | ECDH ES w/ | | A128KW | | SHA-256 | | | Concat KDF | | | | | | | and AES Key | | | | | | | Wrap w/ | | | | | | | 128-bit key | | | | | | | | | ECDH-ES + | -30 | HKDF - | yes | A192KW | ECDH ES w/ | | A192KW | | SHA-256 | | | Concat KDF | | | | | | | and AES Key | | | | | | | Wrap w/ | | | | | | | 192-bit key | | | | | | | | | ECDH-ES + | -31 | HKDF - | yes | A256KW | ECDH ES w/ | | A256KW | | SHA-256 | | | Concat KDF | | | | | | | and AES Key | | | | | | | Wrap w/ | | | | | | | 256-bit key | | | | | | | | | ECDH-SS + | -32 | HKDF - | no | A128KW | ECDH SS w/ | | A128KW | | SHA-256 | | | Concat KDF | | | | | | | and AES Key | | | | | | | Wrap w/ | | | | | | | 128-bit key | | | | | | | | | ECDH-SS + | -33 | HKDF - | no | A192KW | ECDH SS w/ | | A192KW | | SHA-256 | | | Concat KDF | | | | | | | and AES Key | | | | | | | Wrap w/ | | | | | | | 192-bit key | | | | | | | | | ECDH-SS + | -34 | HKDF - | no | A256KW | ECDH SS w/ | | A256KW | | SHA-256 | | | Concat KDF | | | | | | | and AES Key | | | | | | | Wrap w/ | | | | | | | 256-bit key | +-----------+-------+---------+------------+--------+---------------+ Table 20: ECDH Algorithm Values with Key Wrap
When using a COSE key for this algorithm, the following checks are
made:
o The 'kty' field MUST be present, and it MUST be 'EC2' or 'OKP'.
o If the 'alg' field is present, it MUST match the key agreement
algorithm being used.
o If the 'key_ops' field is present, it MUST include 'derive key' or
'derive bits' for the private key.
o If the 'key_ops' field is present, it MUST be empty for the public
key.
(page 72 continued on part 5)
