tech-invite   World Map     

3GPP     Specs     Glossaries     Architecture     IMS     UICC       IETF     RFCs     Groups     SIP     ABNFs       Search

RFC 8152

 
 
 

CBOR Object Signing and Encryption (COSE)

Part 4 of 6, p. 51 to 72
Prev Section       Next Section

 


prevText      Top      ToC       Page 51 
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.

Top      Up      ToC       Page 52 
   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.

Top      Up      ToC       Page 53 
      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

Top      Up      ToC       Page 54 
   +------+-------+------+-------------------------------+-------------+
   | 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 Parameters

11.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.

Top      Up      ToC       Page 55 
   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.

Top      Up      ToC       Page 56 
   +----------+-------+------+---------------------------+-------------+
   | 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 |             |

Top      Up      ToC       Page 57 
   | 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

Top      Up      ToC       Page 58 
   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.

Top      Up      ToC       Page 59 
         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.

Top      Up      ToC       Page 60 
   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.

Top      Up      ToC       Page 61 
   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 Key

12.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

Top      Up      ToC       Page 62 
   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

Top      Up      ToC       Page 63 
   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.

Top      Up      ToC       Page 64 
   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

Top      Up      ToC       Page 65 
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.

Top      Up      ToC       Page 66 
      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.

Top      Up      ToC       Page 67 
   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.

Top      Up      ToC       Page 68 
   +-----------+-------+---------+------------+--------+---------------+
   | 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

Top      Up      ToC       Page 69 
   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)

Top      Up      ToC       Page 70 
   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.

Top      Up      ToC       Page 71 
   +-----------+-------+---------+------------+--------+---------------+
   | 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

Top      Up      ToC       Page 72 
   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)

Next Section