Object Security for Constrained RESTful Environments (OSCORE)

1.1. Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

Readers are expected to be familiar with the terms and concepts described in CoAP [RFC7252], Observe [RFC7641], Block-wise [RFC7959], COSE [RFC8152], CBOR [RFC7049], CDDL [I-D.ietf-cbor-cddl] as summarized in Appendix E, and constrained environments [RFC7228].¶

The term "hop" is used to denote a particular leg in the end-to-end path. The concept "hop-by-hop" (as in "hop-by-hop encryption" or "hop-by-hop fragmentation") opposed to "end-to-end", is used in this document to indicate that the messages are processed accordingly in the intermediaries, rather than just forwarded to the next node.¶

The term "stop processing" is used throughout the document to denote that the message is not passed up to the CoAP Request/Response Layer (see Figure 1).¶

The terms Common/Sender/Recipient Context, Master Secret/Salt, Sender ID/Key, Recipient ID/Key, ID Context, and Common IV are defined in Section 3.1.¶

3.1. Security Context Definition

The security context is the set of information elements necessary to carry out the cryptographic operations in OSCORE. For each endpoint, the security context is composed of a "Common Context", a "Sender Context", and a "Recipient Context".¶

The endpoints protect messages to send using the Sender Context and verify messages received using the Recipient Context, both contexts being derived from the Common Context and other data. Clients and servers need to be able to retrieve the correct security context to use.¶

An endpoint uses its Sender ID (SID) to derive its Sender Context, and the other endpoint uses the same ID, now called Recipient ID (RID), to derive its Recipient Context. In communication between two endpoints, the Sender Context of one endpoint matches the Recipient Context of the other endpoint, and vice versa. Thus, the two security contexts identified by the same IDs in the two endpoints are not the same, but they are partly mirrored. Retrieval and use of the security context are shown in Figure 4.¶

          .-----------------------------------------------.
          |                Common Context                 |
          +---------------------.---.---------------------+
          |    Sender Context   | = |  Recipient Context  |
          +---------------------+   +---------------------+
          |  Recipient Context  | = |    Sender Context   |
          '---------------------'   '---------------------'
                   Client                   Server
                      |                       |
Retrieve context for  | OSCORE request:       |
 target resource      |   Token = Token1,     |
Protect request with  |   kid = SID, ...      |
  Sender Context      +---------------------->| Retrieve context with
                      |                       |  RID = kid
                      |                       | Verify request with
                      |                       |  Recipient Context
                      | OSCORE response:      | Protect response with
                      |   Token = Token1, ... |  Sender Context
Retrieve context with |<----------------------+
 Token = Token1       |                       |
Verify request with   |                       |
 Recipient Context    |                       |

The Common Context contains the following parameters:¶

• AEAD Algorithm. The COSE AEAD algorithm to use for encryption.¶
• HKDF Algorithm. An HMAC-based key derivation function HKDF [RFC5869] used to derive Sender Key, Recipient Key, and Common IV.¶
• Master Secret. Variable length, random byte string (see Section 12.3) used to derive AEAD keys and Common IV.¶
• Master Salt. Optional variable length byte string containing the salt used to derive AEAD keys and Common IV.¶
• ID Context. Optional variable length byte string providing additional information to identify the Common Context and to derive AEAD keys and Common IV. The use of ID Context is described in Section 5.1.¶
• Common IV. Byte string derived from Master Secret, Master Salt, and ID Context. Used to generate the AEAD Nonce (see Section 5.2). Same length as the nonce of the AEAD Algorithm.¶

The Sender Context contains the following parameters:¶

• Sender ID. Byte string used to identify the Sender Context, to derive AEAD keys and Common IV, and to assure unique AEAD nonces. Maximum length is determined by the AEAD Algorithm.¶
• Sender Key. Byte string containing the symmetric AEAD key to protect messages to send. Derived from Common Context and Sender ID. Length is determined by the AEAD Algorithm.¶
• Sender Sequence Number. Non-negative integer used by the sender to enumerate requests and certain responses, e.g. Observe notifications. Used as 'Partial IV' [RFC8152] to generate unique AEAD nonces. Maximum value is determined by the AEAD Algorithm. Initialization is described in Section 3.2.2.¶

The Recipient Context contains the following parameters:¶

• Recipient ID. Byte string used to identify the Recipient Context, to derive AEAD keys and Common IV, and to assure unique AEAD nonces. Maximum length is determined by the AEAD Algorithm.¶
• Recipient Key. Byte string containing the symmetric AEAD key to verify messages received. Derived from Common Context and Recipient ID. Length is determined by the AEAD Algorithm.¶
• Replay Window (Server only). The replay window to verify requests received. Replay protection is described in Section 7.4 and Section 3.2.2.¶

All parameters except Sender Sequence Number and Replay Window are immutable once the security context is established. An endpoint may free up memory by not storing the Common IV, Sender Key, and Recipient Key, deriving them when needed. Alternatively, an endpoint may free up memory by not storing the Master Secret and Master Salt after the other parameters have been derived.¶

Endpoints MAY operate as both client and server and use the same security context for those roles. Independent of being client or server, the endpoint protects messages to send using its Sender Context, and verifies messages received using its Recipient Context. The endpoints MUST NOT change the Sender/Recipient ID when changing roles. In other words, changing the roles does not change the set of AEAD keys to be used.¶

3.2. Establishment of Security Context Parameters

Each endpoint derives the parameters in the security context from a small set of input parameters. The following input parameters SHALL be pre-established:¶

• Master Secret¶
• Sender ID¶
• Recipient ID¶

The following input parameters MAY be pre-established. In case any of these parameters is not pre-established, the default value indicated below is used:¶

• AEAD Algorithm¶

  • Default is AES-CCM-16-64-128 (COSE algorithm encoding: 10)¶

• Master Salt¶

  • Default is the empty byte string¶

• HKDF Algorithm¶

  • Default is HKDF SHA-256¶

• Replay Window¶

  • Default is DTLS-type replay protection with a window size of 32 [RFC6347]¶

All input parameters need to be known to and agreed on by both endpoints, but the replay window may be different in the two endpoints. The way the input parameters are pre-established, is application specific. Considerations of security context establishment are given in Section 12.2 and examples of deploying OSCORE in Appendix B.¶

   output parameter = HKDF(salt, IKM, info, L)

   info = [
     id : bstr,
     id_context : bstr / nil,
     alg_aead : int / tstr,
     type : tstr,
     L : uint,
   ]

   PRK = HMAC-SHA-256(Master Salt, Master Secret)

   output parameter = HMAC-SHA-256(PRK, info || 0x01)

3.3. Requirements on the Security Context Parameters

To ensure unique Sender Keys, the quartet (Master Secret, Master Salt, ID Context, Sender ID) MUST be unique, i.e. the pair (ID Context, Sender ID) SHALL be unique in the set of all security contexts using the same Master Secret and Master Salt. This means that Sender ID SHALL be unique in the set of all security contexts using the same Master Secret, Master Salt, and ID Context; such a requirement guarantees unique (key, nonce) pairs for the AEAD.¶

Different methods can be used to assign Sender IDs: a protocol that allows the parties to negotiate locally unique identifiers, a trusted third party (e.g., [I-D.ietf-ace-oauth-authz]), or the identifiers can be assigned out-of-band. The Sender IDs can be very short (note that the empty string is a legitimate value). The maximum length of Sender ID in bytes equals the length of AEAD nonce minus 6, see Section 5.2. For AES-CCM-16-64-128 the maximum length of Sender ID is 7 bytes.¶

To simplify retrieval of the right Recipient Context, the Recipient ID SHOULD be unique in the sets of all Recipient Contexts used by an endpoint. If an endpoint has the same Recipient ID with different Recipient Contexts, i.e. the Recipient Contexts are derived from different Common Contexts, then the endpoint may need to try multiple times before verifying the right security context associated to the Recipient ID.¶

The ID Context is used to distinguish between security contexts. The methods used for assigning Sender ID can also be used for assigning the ID Context. Additionally, the ID Context can be used to introduce randomness into new Sender and Recipient Contexts (see Appendix B.2). ID Context can be arbitrarily long.¶

4.1. CoAP Options

A summary of how options are protected is shown in Figure 5. Note that some options may have both Inner and Outer message fields which are protected accordingly. Certain options require special processing as is described in Section 4.1.3.¶

Options that are unknown or for which OSCORE processing is not defined SHALL be processed as class E (and no special processing). Specifications of new CoAP options SHOULD define how they are processed with OSCORE. A new COAP option SHOULD be of class E unless it requires proxy processing. If a new CoAP option is of class U, the potential issues with the option being unprotected SHOULD be documented (see Appendix D.5).¶

  +------+-----------------+---+---+
  | No.  | Name            | E | U |
  +------+-----------------+---+---+
  |   1  | If-Match        | x |   |
  |   3  | Uri-Host        |   | x |
  |   4  | ETag            | x |   |
  |   5  | If-None-Match   | x |   |
  |   6  | Observe         | x | x |
  |   7  | Uri-Port        |   | x |
  |   8  | Location-Path   | x |   |
  | TBD1 | OSCORE          |   | x |
  |  11  | Uri-Path        | x |   |
  |  12  | Content-Format  | x |   |
  |  14  | Max-Age         | x | x |
  |  15  | Uri-Query       | x |   |
  |  17  | Accept          | x |   |
  |  20  | Location-Query  | x |   |
  |  23  | Block2          | x | x |
  |  27  | Block1          | x | x |
  |  28  | Size2           | x | x |
  |  35  | Proxy-Uri       |   | x |
  |  39  | Proxy-Scheme    |   | x |
  |  60  | Size1           | x | x |
  | 258  | No-Response     | x | x |
  +------+-----------------+---+---+

E = Encrypt and Integrity Protect (Inner)
U = Unprotected (Outer)

      +------------------+---+---+
      | Field            | E | U |
      +------------------+---+---+
      | Version (UDP)    |   | x |
      | Type (UDP)       |   | x |
      | Length (TCP)     |   | x |
      | Token Length     |   | x |
      | Code             | x |   |
      | Message ID (UDP) |   | x |
      | Token            |   | x |
      | Payload          | x |   |
      +------------------+---+---+

E = Encrypt and Integrity Protect (Inner)
U = Unprotected (Outer)

4.2. CoAP Header Fields and Payload

A summary of how the CoAP header fields and payload are protected is shown in Figure 6, including fields specific to CoAP over UDP and CoAP over TCP (marked accordingly in the table).¶

Most CoAP Header fields (i.e. the message fields in the fixed 4-byte header) are required to be read and/or changed by CoAP proxies and thus cannot in general be protected end-to-end between the endpoints. As mentioned in Section 1, OSCORE protects the CoAP Request/Response Layer only, and not the Messaging Layer (Section 2 of [RFC7252]), so fields such as Type and Message ID are not protected with OSCORE.¶

The CoAP Header field Code is protected by OSCORE. Code SHALL be encrypted and integrity protected (Class E) to prevent an intermediary from eavesdropping on or manipulating the Code (e.g., changing from GET to DELETE).¶

The sending endpoint SHALL write the Code of the original CoAP message into the plaintext of the COSE object (see Section 5.3). After that, the sending endpoint writes an Outer Code to the OSCORE message. With one exception (see Section 4.1.3.5) the Outer Code SHALL be set to 0.02 (POST) for requests and to 2.04 (Changed) for responses. The receiving endpoint SHALL discard the Outer Code in the OSCORE message and write the Code of the COSE object plaintext (Section 5.3) into the decrypted CoAP message.¶

The other currently defined CoAP Header fields are Unprotected (Class U). The sending endpoint SHALL write all other header fields of the original message into the header of the OSCORE message. The receiving endpoint SHALL write the header fields from the received OSCORE message into the header of the decrypted CoAP message.¶

The CoAP Payload, if present in the original CoAP message, SHALL be encrypted and integrity protected and is thus an Inner message field. The sending endpoint writes the payload of the original CoAP message into the plaintext (Section 5.3) input to the COSE object. The receiving endpoint verifies and decrypts the COSE object, and recreates the payload of the original CoAP message.¶

4.3. Signaling Messages

Signaling messages (CoAP Code 7.00-7.31) were introduced to exchange information related to an underlying transport connection in the specific case of CoAP over reliable transports [RFC8323].¶

OSCORE MAY be used to protect Signaling if the endpoints for OSCORE coincide with the endpoints for the signaling message. If OSCORE is used to protect Signaling then:¶

• To comply with [RFC8323], an initial empty CSM message SHALL be sent. The subsequent signaling message SHALL be protected.¶
• Signaling messages SHALL be protected as CoAP Request messages, except in the case the Signaling message is a response to a previous Signaling message, in which case it SHALL be protected as a CoAP Response message. For example, 7.02 (Ping) is protected as a CoAP Request and 7.03 (Pong) as a CoAP response.¶
• The Outer Code for Signaling messages SHALL be set to 0.02 (POST), unless it is a response to a previous Signaling message, in which case it SHALL be set to 2.04 (Changed).¶
• All Signaling options, except the OSCORE option, SHALL be Inner (Class E).¶

NOTE: Option numbers for Signaling messages are specific to the CoAP Code (see Section 5.2 of [RFC8323]).¶

If OSCORE is not used to protect Signaling, Signaling messages SHALL be unaltered by OSCORE.¶

5.1. ID Context and 'kid context'

For certain use cases, e.g. deployments where the same Sender ID is used with multiple contexts, it is possible (and sometimes necessary, see Section 3.3) for the client to use an ID Context to distinguish the security contexts (see Section 3.1). For example:¶

• If the client has a unique identifier in some namespace then that identifier can be used as ID Context.¶
• The ID Context may be used to add randomness into new Sender and Recipient Contexts, see Appendix B.2.¶
• In case of group communication [I-D.ietf-core-oscore-groupcomm], a group identifier is used as ID Context to enable different security contexts for a server belonging to multiple groups.¶

The Sender ID and ID Context are used to establish the necessary input parameters and in the derivation of the security context (see Section 3.2).¶

Whereas the 'kid' parameter is used to transport the Sender ID, the new COSE header parameter 'kid context' is used to transport the ID Context in requests, see Figure 7.¶

+----------+--------+------------+----------------+-----------------+
|   name   |  label | value type | value registry |   description   |
+----------+--------+------------+----------------+-----------------+
|   kid    |  TBD2  | bstr       |                | Identifies the  |
| context  |        |            |                | context for kid |
+----------+--------+------------+----------------+-----------------+

If ID Context is non-empty and the client sends a request without 'kid context' which results in an error indicating that the server could not find the security context, then the client could include the ID Context in the 'kid context' when making another request. Note that since the error is unprotected it may have been spoofed and the real response blocked by an on-path attacker.¶

5.2. AEAD Nonce

The high level design of the AEAD nonce follows Section 4.4 of [I-D.mcgrew-iv-gen], here follows the detailed construction (see Figure 8):¶

1. left-pad the Partial IV (PIV) with zeroes to exactly 5 bytes,¶
2. left-pad the Sender ID of the endpoint that generated the Partial IV (ID_PIV) with zeroes to exactly nonce length minus 6 bytes,¶
3. concatenate the size of the ID_PIV (a single byte S) with the padded ID_PIV and the padded PIV,¶
4. and then XOR with the Common IV.¶

Note that in this specification only AEAD algorithms that use nonces equal or greater than 7 bytes are supported. The nonce construction with S, ID_PIV, and PIV together with endpoint unique IDs and encryption keys makes it easy to verify that the nonces used with a specific key will be unique, see Appendix D.4.¶

If the Partial IV is not present in a response, the nonce from the request is used. For responses that are not notifications (i.e. when there is a single response to a request), the request and the response should typically use the same nonce to reduce message overhead. Both alternatives provide all the required security properties, see Section 7.4 and Appendix D.4. The only non-Observe scenario where a Partial IV must be included in a response is when the server is unable to perform replay protection, see Appendix B.1.2. For processing instructions see Section 8.¶

     <- nonce length minus 6 B -> <-- 5 bytes -->
+---+-------------------+--------+---------+-----+
| S |      padding      | ID_PIV | padding | PIV |----+
+---+-------------------+--------+---------+-----+    |
                                                      |
 <---------------- nonce length ---------------->     |
+------------------------------------------------+    |
|                   Common IV                    |->(XOR)
+------------------------------------------------+    |
                                                      |
 <---------------- nonce length ---------------->     |
+------------------------------------------------+    |
|                     Nonce                      |<---+
+------------------------------------------------+

5.3. Plaintext

The plaintext is formatted as a CoAP message without Header (see Figure 9) consisting of:¶

• the Code of the original CoAP message as defined in Section 3 of [RFC7252]; and¶
• all Inner option message fields (see Section 4.1.1) present in the original CoAP message (see Section 4.1). The options are encoded as described in Section 3.1 of [RFC7252], where the delta is the difference to the previously included instance of Class E option; and¶
• the Payload of original CoAP message, if present, and in that case prefixed by the one-byte Payload Marker (0xff).¶

NOTE: The plaintext contains all CoAP data that needs to be encrypted end-to-end between the endpoints.¶

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     Code      |    Class E options (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 1 1 1 1 1 1 1|    Payload (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 (only if there
   is payload)

5.4. Additional Authenticated Data

The external_aad SHALL be a CBOR array wrapped in a bstr object as defined below:¶

external_aad = bstr .cbor aad_array

aad_array = [
  oscore_version : uint,
  algorithms : [ alg_aead : int / tstr ],
  request_kid : bstr,
  request_piv : bstr,
  options : bstr,
]

where:¶

• oscore_version: contains the OSCORE version number. Implementations of this specification MUST set this field to 1. Other values are reserved for future versions.¶
• algorithms: contains (for extensibility) an array of algorithms, according to this specification only containing alg_aead.¶
• alg_aead: contains the AEAD Algorithm from the security context used for the exchange (see Section 3.1).¶
• request_kid: contains the value of the 'kid' in the COSE object of the request (see Section 5).¶
• request_piv: contains the value of the 'Partial IV' in the COSE object of the request (see Section 5).¶
• options: contains the Class I options (see Section 4.1.2) present in the original CoAP message encoded as described in Section 3.1 of [RFC7252], where the delta is the difference to the previously included instance of class I option.¶

The oscore_version and algorithms parameters are established out-of-band and are thus never transported in OSCORE, but the external_aad allows to verify that they are the same in both endpoints.¶

NOTE: The format of the external_aad is for simplicity the same for requests and responses, although some parameters, e.g. request_kid, need not be integrity protected in all requests.¶

The Additional Authenticated Data (AAD) is composed from the external_aad as described in Section 5.3 of [RFC8152]:¶

   AAD = Enc_structure = [ "Encrypt0", h'', external_aad ]

The following is an example of AAD constructed using AEAD Algorithm = AES-CCM-16-64-128 (10), request_kid = 0x00, request_piv = 0x25 and no Class I options:¶

• oscore_version: 0x01 (1 byte)¶
• algorithms: 0x810a (2 bytes)¶
• request_kid: 0x00 (1 byte)¶
• request_piv: 0x25 (1 byte)¶
• options: 0x (0 bytes)¶
• aad_array: 0x8501810a4100412540 (9 bytes)¶
• external_aad: 0x498501810a4100412540 (10 bytes)¶
• AAD: 0x8368456e63727970743040498501810a4100412540 (21 bytes)¶

Note that the AAD consists of a fixed string of 11 bytes concatenated with the external_aad.¶

6.1. Encoding of the OSCORE Option Value

The value of the OSCORE option SHALL contain the OSCORE flag bits, the Partial IV parameter, the 'kid context' parameter (length and value), and the 'kid' parameter as follows:¶

 0 1 2 3 4 5 6 7 <------------- n bytes -------------->
+-+-+-+-+-+-+-+-+--------------------------------------
|0 0 0|h|k|  n  |       Partial IV (if any) ...
+-+-+-+-+-+-+-+-+--------------------------------------

 <- 1 byte -> <----- s bytes ------>
+------------+----------------------+------------------+
| s (if any) | kid context (if any) | kid (if any) ... |
+------------+----------------------+------------------+

• The first byte, containing the OSCORE flag bits, encodes the following set of bits and the length of the Partial IV parameter:¶

  • The three least significant bits encode the Partial IV length n. If n = 0 then the Partial IV is not present in the compressed COSE object. The values n = 6 and n = 7 are reserved.¶
  • The fourth least significant bit is the 'kid' flag, k: it is set to 1 if the kid is present in the compressed COSE object.¶
  • The fifth least significant bit is the 'kid context' flag, h: it is set to 1 if the compressed COSE object contains a 'kid context (see Section 5.1).¶
  • The sixth to eighth least significant bits are reserved for future use. These bits SHALL be set to zero when not in use. According to this specification, if any of these bits are set to 1 the message is considered to be malformed and decompression fails as specified in item 2 of Section 8.2.¶

The flag bits are registered in the OSCORE Flag Bits registry specified in Section 13.7.¶

• The following n bytes encode the value of the Partial IV, if the Partial IV is present (n > 0).¶
• The following 1 byte encode the length of the 'kid context' (Section 5.1) s, if the 'kid context' flag is set (h = 1).¶
• The following s bytes encode the 'kid context', if the 'kid context' flag is set (h = 1).¶
• The remaining bytes encode the value of the 'kid', if the 'kid' is present (k = 1).¶

Note that the 'kid' MUST be the last field of the OSCORE option value, even in case reserved bits are used and additional fields are added to it.¶

The length of the OSCORE option thus depends on the presence and length of Partial IV, 'kid context', 'kid', as specified in this section, and on the presence and length of the other parameters, as defined in the separate documents.¶

6.2. Encoding of the OSCORE Payload

The payload of the OSCORE message SHALL encode the ciphertext of the COSE object.¶

6.3. Examples of Compressed COSE Objects

This section covers a list of OSCORE Header Compression examples for requests and responses. The examples assume the COSE_Encrypt0 object is set (which means the CoAP message and cryptographic material is known). Note that the full CoAP unprotected message, as well as the full security context, is not reported in the examples, but only the input necessary to the compression mechanism, i.e. the COSE_Encrypt0 object. The output is the compressed COSE object as defined in Section 6, divided into two parts, since the object is transported in two CoAP fields: OSCORE option and payload.¶

1.

Request with ciphertext = 0xaea0155667924dff8a24e4cb35b9, kid = 0x25, and Partial IV = 0x05¶

    Before compression (24 bytes):

      [
        h'',
        { 4:h'25', 6:h'05' },
        h'aea0155667924dff8a24e4cb35b9',
      ]

    After compression (17 bytes):

      Flag byte: 0b00001001 = 0x09 (1 byte)

      Option Value: 0x090525 (3 bytes)

      Payload: 0xaea0155667924dff8a24e4cb35b9 (14 bytes)

2.

Request with ciphertext = 0xaea0155667924dff8a24e4cb35b9, kid = empty string, and Partial IV = 0x00¶

    Before compression (23 bytes):

      [
        h'',
        { 4:h'', 6:h'00' },
        h'aea0155667924dff8a24e4cb35b9',
      ]

    After compression (16 bytes):

      Flag byte: 0b00001001 = 0x09 (1 byte)

      Option Value: 0x0900 (2 bytes)

      Payload: 0xaea0155667924dff8a24e4cb35b9 (14 bytes)

3.

Request with ciphertext = 0xaea0155667924dff8a24e4cb35b9, kid = empty string, Partial IV = 0x05, and kid context = 0x44616c656b¶

    Before compression (30 bytes):

      [
        h'',
        { 4:h'', 6:h'05', 8:h'44616c656b' },
        h'aea0155667924dff8a24e4cb35b9',
      ]

    After compression (22  bytes):

      Flag byte: 0b00011001 = 0x19 (1 byte)

      Option Value: 0x19050544616c656b (8 bytes)

      Payload: 0xae a0155667924dff8a24e4cb35b9 (14 bytes)

4.

Response with ciphertext = 0xaea0155667924dff8a24e4cb35b9 and no Partial IV¶

    Before compression (18 bytes):

      [
        h'',
        {},
        h'aea0155667924dff8a24e4cb35b9',
      ]

    After compression (14 bytes):

      Flag byte: 0b00000000 = 0x00 (1 byte)

      Option Value: 0x (0 bytes)

      Payload: 0xaea0155667924dff8a24e4cb35b9 (14 bytes)

5.

Response with ciphertext = 0xaea0155667924dff8a24e4cb35b9 and Partial IV = 0x07¶

    Before compression (21 bytes):

      [
        h'',
        { 6:h'07' },
        h'aea0155667924dff8a24e4cb35b9',
      ]

    After compression (16 bytes):

      Flag byte: 0b00000001 = 0x01 (1 byte)

      Option Value: 0x0107 (2 bytes)

      Payload: 0xaea0155667924dff8a24e4cb35b9 (14 bytes)

7.1. Message Binding

In order to prevent response delay and mismatch attacks [I-D.mattsson-core-coap-actuators] from on-path attackers and compromised intermediaries, OSCORE binds responses to the requests by including the 'kid' and Partial IV of the request in the AAD of the response. The server therefore needs to store the 'kid' and Partial IV of the request until all responses have been sent.¶

7.2. Sequence Numbers

An AEAD nonce MUST NOT be used more than once per AEAD key. The uniqueness of (key, nonce) pairs is shown in Appendix D.4, and in particular depends on a correct usage of Partial IVs (which encode the Sender Sequence Numbers, see Section 5). If messages are processed concurrently, the operation of reading and increasing the Sender Sequence Number MUST be atomic.¶

7.3. Freshness

For requests, OSCORE provides only the guarantee that the request is not older than the security context. For applications having stronger demands on request freshness (e.g., control of actuators), OSCORE needs to be augmented with mechanisms providing freshness, for example as specified in [I-D.ietf-core-echo-request-tag].¶

Assuming an honest server (see Appendix D), the message binding guarantees that a response is not older than its request. For responses that are not notifications (i.e. when there is a single response to a request), this gives absolute freshness. For notifications, the absolute freshness gets weaker with time, and it is RECOMMENDED that the client regularly re-register the observation. Note that the message binding does not guarantee that misbehaving server created the response before receiving the request, i.e. it does not verify server aliveness.¶

For requests and notifications, OSCORE also provides relative freshness in the sense that the received Partial IV allows a recipient to determine the relative order of requests or responses.¶

7.4. Replay Protection

In order to protect from replay of requests, the server's Recipient Context includes a Replay Window. A server SHALL verify that a Partial IV = Sender Sequence Number received in the COSE object has not been received before. If this verification fails, the server SHALL stop processing the message, and MAY optionally respond with a 4.01 (Unauthorized) error message. Also, the server MAY set an Outer Max-Age option with value zero, to inform any intermediary that the response is not to be cached. The diagnostic payload MAY contain the "Replay detected" string. The size and type of the Replay Window depends on the use case and the protocol with which the OSCORE message is transported. In case of reliable and ordered transport from endpoint to endpoint, e.g. TCP, the server MAY just store the last received Partial IV and require that newly received Partial IVs equals the last received Partial IV + 1. However, in case of mixed reliable and unreliable transports and where messages may be lost, such a replay mechanism may be too restrictive and the default replay window be more suitable (see Section 3.2.2).¶

Responses (with or without Partial IV) are protected against replay as they are bound to the request and the fact that only a single response is accepted. Note that the Partial IV is not used for replay protection in this case.¶

The operation of validating the Partial IV and updating the replay protection MUST be atomic.¶

7.5. Losing Part of the Context State

To prevent reuse of an AEAD nonce with the same AEAD key, or from accepting replayed messages, an endpoint needs to handle the situation of losing rapidly changing parts of the context, such as the Sender Sequence Number, and Replay Window. These are typically stored in RAM and therefore lost in the case of e.g. an unplanned reboot. There are different alternatives to recover, for example:¶

1. The endpoints can reuse an existing Security Context after updating the mutable parts of the security context (Sender Sequence Number, and Replay Window). This requires that the mutable parts of the security context are available throughout the lifetime of the device, or that the device can establish safe security context after loss of mutable security context data. Examples is given based on careful use of non-volatile memory, see Appendix B.1.1, and additionally the use of the Echo option, see Appendix B.1.2. If an endpoint makes use of a partial security context stored in non-volatile memory, it MUST NOT reuse a previous Sender Sequence Number and MUST NOT accept previously received messages.¶
2. The endpoints can reuse an existing shared Master Secret and derive new Sender and Recipient Contexts, see Appendix B.2 for an example. This typically requires a good source of randomness.¶
3. The endpoints can use a trusted-third party assisted key establishment protocol such as [I-D.ietf-ace-oscore-profile]. This requires the execution of three-party protocol and may require a good source of randomness.¶
4. The endpoints can run a key exchange protocol providing forward secrecy resulting in a fresh Master Secret, from which an entirely new Security Context is derived. This requires a good source of randomness, and additionally, the transmission and processing of the protocol may have a non-negligible cost, e.g. in terms of power consumption.¶

The endpoints need to be configured with information about which method is used. The choice of method may depend on capabilities of the devices deployed and the solution architecture. Using a key exchange protocol is necessary for deployments that require forward secrecy.¶

8.1. Protecting the Request

Given a CoAP request, the client SHALL perform the following steps to create an OSCORE request:¶

1. Retrieve the Sender Context associated with the target resource.¶
2. Compose the Additional Authenticated Data and the plaintext, as described in Sections 5.3 and 5.4.¶
3. Encode the Partial IV (Sender Sequence Number in network byte order) and increment the Sender Sequence Number by one. Compute the AEAD nonce from the Sender ID, Common IV, and Partial IV as described in Section 5.2.¶
4. Encrypt the COSE object using the Sender Key. Compress the COSE Object as specified in Section 6.¶
5. Format the OSCORE message according to Section 4. The OSCORE option is added (see Section 4.1.2).¶

8.2. Verifying the Request

A server receiving a request containing the OSCORE option SHALL perform the following steps:¶

1. Discard Code and all class E options (marked in Figure 5 with 'x' in column E) present in the received message. For example, an If-Match Outer option is discarded, but an Uri-Host Outer option is not discarded.¶

2. Decompress the COSE Object (Section 6) and retrieve the Recipient Context associated with the Recipient ID in the 'kid' parameter, additionally using the 'kid context', if present. If either the decompression or the COSE message fails to decode, or the server fails to retrieve a Recipient Context with Recipient ID corresponding to the 'kid' parameter received, then the server SHALL stop processing the request.¶

   • If either the decompression or the COSE message fails to decode, the server MAY respond with a 4.02 (Bad Option) error message. The server MAY set an Outer Max-Age option with value zero. The diagnostic payload MAY contain the string "Failed to decode COSE".¶
   • If the server fails to retrieve a Recipient Context with Recipient ID corresponding to the 'kid' parameter received, the server MAY respond with a 4.01 (Unauthorized) error message. The server MAY set an Outer Max-Age option with value zero. The diagnostic payload MAY contain the string "Security context not found".¶
3. Verify that the 'Partial IV' has not been received before using the Replay Window, as described in Section 7.4.¶
4. Compose the Additional Authenticated Data, as described in Section 5.4.¶
5. Compute the AEAD nonce from the Recipient ID, Common IV, and the 'Partial IV' parameter, received in the COSE Object.¶

6. Decrypt the COSE object using the Recipient Key, as per [RFC8152] Section 5.3. (The decrypt operation includes the verification of the integrity.)¶

   • If decryption fails, the server MUST stop processing the request and MAY respond with a 4.00 (Bad Request) error message. The server MAY set an Outer Max-Age option with value zero. The diagnostic payload MAY contain the "Decryption failed" string.¶
   • If decryption succeeds, update the Replay Window, as described in Section 7.¶
7. Add decrypted Code, options, and payload to the decrypted request. The OSCORE option is removed.¶
8. The decrypted CoAP request is processed according to [RFC7252].¶

8.3. Protecting the Response

If a CoAP response is generated in response to an OSCORE request, the server SHALL perform the following steps to create an OSCORE response. Note that CoAP error responses derived from CoAP processing (step 8 in Section 8.2) are protected, as well as successful CoAP responses, while the OSCORE errors (steps 2, 3, and 6 in Section 8.2) do not follow the processing below, but are sent as simple CoAP responses, without OSCORE processing.¶

1. Retrieve the Sender Context in the Security Context associated with the Token.¶
2. Compose the Additional Authenticated Data and the plaintext, as described in Sections 5.3 and 5.4.¶

3. Compute the AEAD nonce as described in Section 5.2:¶

   • Either use the AEAD nonce from the request, or¶
   • Encode the Partial IV (Sender Sequence Number in network byte order) and increment the Sender Sequence Number by one. Compute the AEAD nonce from the Sender ID, Common IV, and Partial IV.¶
4. Encrypt the COSE object using the Sender Key. Compress the COSE Object as specified in Section 6. If the AEAD nonce was constructed from a new Partial IV, this Partial IV MUST be included in the message. If the AEAD nonce from the request was used, the Partial IV MUST NOT be included in the message.¶
5. Format the OSCORE message according to Section 4. The OSCORE option is added (see Section 4.1.2).¶

8.4. Verifying the Response

A client receiving a response containing the OSCORE option SHALL perform the following steps:¶

1. Discard Code and all class E options (marked in Figure 5 with 'x' in column E) present in the received message. For example, ETag Outer option is discarded, as well as Max-Age Outer option.¶
2. Retrieve the Recipient Context in the Security Context associated with the Token. Decompress the COSE Object (Section 6). If either the decompression or the COSE message fails to decode, then go to 8.¶
3. Compose the Additional Authenticated Data, as described in Section 5.4.¶

4. Compute the AEAD nonce¶

   • If the Partial IV is not present in the response, the AEAD nonce from the request is used.¶
   • If the Partial IV is present in the response, compute the AEAD nonce from the Recipient ID, Common IV, and the 'Partial IV' parameter, received in the COSE Object.¶
5. Decrypt the COSE object using the Recipient Key, as per [RFC8152] Section 5.3. (The decrypt operation includes the verification of the integrity.) If decryption fails, then go to 8.¶
6. Add decrypted Code, options and payload to the decrypted request. The OSCORE option is removed.¶
7. The decrypted CoAP response is processed according to [RFC7252].¶
8. In case any of the previous erroneous conditions apply: the client SHALL stop processing the response.¶

11.1. The HTTP OSCORE Header Field

The HTTP OSCORE Header Field (see Section 13.4) is used for carrying the content of the CoAP OSCORE option when transporting OSCORE messages over HTTP hops.¶

The HTTP OSCORE header field is only used in POST requests and 200 (OK) responses. When used, the HTTP header field Content-Type is set to 'application/oscore' (see Section 13.5) indicating that the HTTP body of this message contains the OSCORE payload (see Section 6.2). No additional semantics is provided by other message fields.¶

Using the Augmented Backus-Naur Form (ABNF) notation of [RFC5234], including the following core ABNF syntax rules defined by that specification: ALPHA (letters) and DIGIT (decimal digits), the HTTP OSCORE header field value is as follows.¶

base64url-char = ALPHA / DIGIT / "-" / "_"

OSCORE = 2*base64url-char

The HTTP OSCORE header field is not appropriate to list in the Connection header field (see Section 6.1 of [RFC7230]) since it is not hop-by-hop. OSCORE messages are generally not useful when served from cache (i.e., they will generally be marked Cache-Control: no-cache) and so interaction with Vary is not relevant (Section 7.1.4 of [RFC7231]). Since the HTTP OSCORE header field is critical for message processing, moving it from headers to trailers renders the message unusable in case trailers are ignored (see Section 4.1 of [RFC7230]).¶

Intermediaries are in general not allowed to insert, delete, or modify the OSCORE header. Changes to the HTTP OSCORE header field will in general violate the integrity of the OSCORE message resulting in an error. For the same reason the HTTP OSCORE header field is in general not preserved across redirects.¶

Since redirects are not defined in the mappings between HTTP and CoAP [RFC8075][RFC7252], a number of conditions need to be fulfilled for redirects to work. For CoAP client to HTTP server, such conditions include:¶

• the CoAP-to-HTTP proxy follows the redirect, instead of the CoAP client as in the HTTP case¶
• the CoAP-to-HTTP proxy copies the HTTP OSCORE header field and body to the new request¶
• the target of the redirect has the necessary OSCORE security context required to decrypt and verify the message¶

Since OSCORE requires HTTP body to be preserved across redirects, the HTTP server is RECOMMENDED to reply with 307 or 308 instead of 301 or 302.¶

For the case of HTTP client to CoAP server, although redirect is not defined for CoAP servers [RFC7252], an HTTP client receiving a redirect should generate a new OSCORE request for the server it was redirected to.¶

11.2. CoAP-to-HTTP Mapping

Section 10.1 of [RFC7252] describes the fundamentals of the CoAP-to-HTTP cross-protocol mapping process. The additional rules for OSCORE messages are:¶

• The HTTP OSCORE header field value is set to¶

  • AA if the CoAP OSCORE option is empty, otherwise¶
  • the value of the CoAP OSCORE option (Section 6.1) in base64url (Section 5 of [RFC4648]) encoding without padding. Implementation notes for this encoding are given in Appendix C of [RFC7515].¶
• The HTTP Content-Type is set to 'application/oscore' (see Section 13.5), independent of CoAP Content-Format.¶

11.3. HTTP-to-CoAP Mapping

Section 10.2 of [RFC7252] and [RFC8075] specify the behavior of an HTTP-to-CoAP proxy. The additional rules for HTTP messages with the OSCORE header field are:¶

• The CoAP OSCORE option is set as follows:¶

  • empty if the value of the HTTP OSCORE header field is a single zero byte (0x00) represented by AA, otherwise¶
  • the value of the HTTP OSCORE header field decoded from base64url (Section 5 of [RFC4648]) without padding. Implementation notes for this encoding are given in Appendix C of [RFC7515].¶
• The CoAP Content-Format option is omitted, the content format for OSCORE (Section 13.6) MUST NOT be used.¶

11.4. HTTP Endpoints

Restricted to subsets of HTTP and CoAP supporting a bijective mapping, OSCORE can be originated or terminated in HTTP endpoints.¶

The sending HTTP endpoint uses [RFC8075] to translate the HTTP message into a CoAP message. The CoAP message is then processed with OSCORE as defined in this document. The OSCORE message is then mapped to HTTP as described in Section 11.2 and sent in compliance with the rules in Section 11.1.¶

The receiving HTTP endpoint maps the HTTP message to a CoAP message using [RFC8075] and Section 11.3. The resulting OSCORE message is processed as defined in this document. If successful, the plaintext CoAP message is translated to HTTP for normal processing in the endpoint.¶

11.5. Example: HTTP Client and CoAP Server

This section is giving an example of how a request and a response between an HTTP client and a CoAP server could look like. The example is not a test vector but intended as an illustration of how the message fields are translated in the different steps.¶

Mapping and notation here is based on "Simple Form" (Section 5.4.1 of [RFC8075]).¶

[HTTP request -- Before client object security processing]

  GET http://proxy.url/hc/?target_uri=coap://server.url/orders
   HTTP/1.1

[HTTP request -- HTTP Client to Proxy]

  POST http://proxy.url/hc/?target_uri=coap://server.url/ HTTP/1.1
  Content-Type: application/oscore
  OSCORE: CSU
  Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary]

[CoAP request -- Proxy to CoAP Server]

  POST coap://server.url/
  OSCORE: 09 25
  Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary]

[CoAP request -- After server object security processing]

  GET coap://server.url/orders

[CoAP response -- Before server object security processing]

  2.05 Content
  Content-Format: 0
  Payload: Exterminate! Exterminate!

[CoAP response -- CoAP Server to Proxy]

  2.04 Changed
  OSCORE: [empty]
  Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary]

[HTTP response -- Proxy to HTTP Client]

  HTTP/1.1 200 OK
  Content-Type: application/oscore
  OSCORE: AA
  Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary]

[HTTP response -- After client object security processing]

  HTTP/1.1 200 OK
  Content-Type: text/plain
  Body: Exterminate! Exterminate!

Note that the HTTP Status Code 200 in the next-to-last message is the mapping of CoAP Code 2.04 (Changed), whereas the HTTP Status Code 200 in the last message is the mapping of the CoAP Code 2.05 (Content), which was encrypted within the compressed COSE object carried in the Body of the HTTP response.¶

11.6. Example: CoAP Client and HTTP Server

This section is giving an example of how a request and a response between a CoAP client and an HTTP server could look like. The example is not a test vector but intended as an illustration of how the message fields are translated in the different steps¶

[CoAP request -- Before client object security processing]

  GET coap://proxy.url/
  Proxy-Uri=http://server.url/orders

[CoAP request -- CoAP Client to Proxy]

  POST coap://proxy.url/
  Proxy-Uri=http://server.url/
  OSCORE: 09 25
  Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary]

[HTTP request -- Proxy to HTTP Server]

  POST http://server.url/ HTTP/1.1
  Content-Type: application/oscore
  OSCORE: CSU
  Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary]

[HTTP request -- After server object security processing]

  GET http://server.url/orders HTTP/1.1

[HTTP response -- Before server object security processing]

  HTTP/1.1 200 OK
  Content-Type: text/plain
  Body: Exterminate! Exterminate!

[HTTP response -- HTTP Server to Proxy]

  HTTP/1.1 200 OK
  Content-Type: application/oscore
  OSCORE: AA
  Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary]

[CoAP response -- Proxy to CoAP Client]

  2.04 Changed
  OSCORE: [empty]
  Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary]

[CoAP response -- After client object security processing]

  2.05 Content
  Content-Format: 0
  Payload: Exterminate! Exterminate!

Note that the HTTP Code 2.04 (Changed) in the next-to-last message is the mapping of HTTP Status Code 200, whereas the CoAP Code 2.05 (Content) in the last message is the value that was encrypted within the compressed COSE object carried in the Body of the HTTP response.¶

12.1. End-to-end Protection

In scenarios with intermediary nodes such as proxies or gateways, transport layer security such as (D)TLS only protects data hop-by-hop. As a consequence, the intermediary nodes can read and modify any information. The trust model where all intermediary nodes are considered trustworthy is problematic, not only from a privacy perspective, but also from a security perspective, as the intermediaries are free to delete resources on sensors and falsify commands to actuators (such as "unlock door", "start fire alarm", "raise bridge"). Even in the rare cases where all the owners of the intermediary nodes are fully trusted, attacks and data breaches make such an architecture brittle.¶

(D)TLS protects hop-by-hop the entire message. OSCORE protects end-to-end all information that is not required for proxy operations (see Section 4). (D)TLS and OSCORE can be combined, thereby enabling end-to-end security of the message payload, in combination with hop-by-hop protection of the entire message, during transport between end-point and intermediary node. In particular when OSCORE is used with HTTP, the additional TLS protection of HTTP hops is RECOMMENDED, e.g. between an HTTP endpoint and a proxy translating between HTTP and CoAP.¶

Applications need to consider that certain message fields and messages types are not protected end-to-end and may be spoofed or manipulated. The consequences of unprotected message fields are analyzed in Appendix D.5.¶

12.2. Security Context Establishment

The use of COSE_Encrypt0 and AEAD to protect messages as specified in this document requires an established security context. The method to establish the security context described in Section 3.2 is based on a common Master Secret and unique Sender IDs. The necessary input parameters may be pre-established or obtained using a key establishment protocol augmented with establishment of Sender/Recipient ID, such as a key exchange protocol or the OSCORE profile of the ACE framework [I-D.ietf-ace-oscore-profile]. Such a procedure must ensure that the requirements of the security context parameters for the intended use are complied with (see Section 3.3) and also in error situations. While recipient IDs are allowed to coincide between different security contexts (see Section 3.3), this may cause a server to process multiple verifications before finding the right security context or rejecting a message. Considerations for deploying OSCORE with a fixed Master Secret are given in Appendix B.¶

12.3. Master Secret

OSCORE uses HKDF [RFC5869] and the established input parameters to derive the security context. The required properties of the security context parameters are discussed in Section 3.3, in this section we focus on the Master Secret. HKDF denotes in this specification the composition of the expand and extract functions as defined in [RFC5869] and the Master Secret is used as Input Key Material (IKM).¶

Informally, HKDF takes as source an IKM containing some good amount of randomness but not necessarily distributed uniformly (or for which an attacker has some partial knowledge) and derive from it one or more cryptographically strong secret keys [RFC5869].¶

Therefore, the main requirement for the OSCORE Master Secret, in addition to being secret, is that it is has a good amount of randomness. The selected key establishment schemes must ensure that the necessary properties for the Master Secret are fulfilled. For pre-shared key deployments and key transport solutions such as [I-D.ietf-ace-oscore-profile], the Master Secret can be generated offline using a good random number generator. Randomness requirements for security are described in [RFC4086].¶

12.4. Replay Protection

Replay attacks need to be considered in different parts of the implementation. Most AEAD algorithms require a unique nonce for each message, for which the sender sequence numbers in the COSE message field 'Partial IV' is used. If the recipient accepts any sequence number larger than the one previously received, then the problem of sequence number synchronization is avoided. With reliable transport, it may be defined that only messages with sequence number which are equal to previous sequence number + 1 are accepted. An adversary may try to induce a device reboot for the purpose of replaying a message (see Section 7.5).¶

Note that sharing a security context between servers may open up for replay attacks, for example if the replay windows are not synchronized.¶

12.5. Client Aliveness

A verified OSCORE request enables the server to verify the identity of the entity who generated the message. However, it does not verify that the client is currently involved in the communication, since the message may be a delayed delivery of a previously generated request which now reaches the server. To verify the aliveness of the client the server may use the Echo option in the response to a request from the client (see [I-D.ietf-core-echo-request-tag]).¶

12.6. Cryptographic Considerations

The maximum sender sequence number is dependent on the AEAD algorithm. The maximum sender sequence number is 2^40 - 1, or any algorithm specific lower limit, after which a new security context must be generated. The mechanism to build the AEAD nonce (Section 5.2) assumes that the nonce is at least 56 bits, and the Partial IV is at most 40 bits. The mandatory-to-implement AEAD algorithm AES-CCM-16-64-128 is selected for compatibility with CCM*. AEAD algorithms that require unpredictable nonces are not supported.¶

In order to prevent cryptanalysis when the same plaintext is repeatedly encrypted by many different users with distinct AEAD keys, the AEAD nonce is formed by mixing the sequence number with a secret per-context initialization vector (Common IV) derived along with the keys (see Section 3.1 of [RFC8152]), and by using a Master Salt in the key derivation (see [MF00] for an overview). The Master Secret, Sender Key, Recipient Key, and Common IV must be secret, the rest of the parameters may be public. The Master Secret must have a good amount of randomness (see Section 12.3).¶

The ID Context, Sender ID, and Partial IV are always at least implicitly integrity protected, as manipulation leads to the wrong nonce or key being used and therefore results in decryption failure.¶

12.7. Message Segmentation

The Inner Block options enable the sender to split large messages into OSCORE-protected blocks such that the receiving endpoint can verify blocks before having received the complete message. The Outer Block options allow for arbitrary proxy fragmentation operations that cannot be verified by the endpoints, but can by policy be restricted in size since the Inner Block options allow for secure fragmentation of very large messages. A maximum message size (above which the sending endpoint fragments the message and the receiving endpoint discards the message, if complying to the policy) may be obtained as part of normal resource discovery.¶

12.8. Privacy Considerations

Privacy threats executed through intermediary nodes are considerably reduced by means of OSCORE. End-to-end integrity protection and encryption of the message payload and all options that are not used for proxy operations, provide mitigation against attacks on sensor and actuator communication, which may have a direct impact on the personal sphere.¶

The unprotected options (Figure 5) may reveal privacy sensitive information, see Appendix D.5. CoAP headers sent in plaintext allow, for example, matching of CON and ACK (CoAP Message Identifier), matching of request and responses (Token) and traffic analysis. OSCORE does not provide protection for HTTP header fields which are not both CoAP-mappable and class E. The HTTP message fields which are visible to on-path entity are only used for the purpose of transporting the OSCORE message, whereas the application layer message is encoded in CoAP and encrypted.¶

COSE message fields, i.e. the OSCORE option, may reveal information about the communicating endpoints. E.g. 'kid' and 'kid context', which are intended to help the server find the right context, may reveal information about the client. Tracking 'kid' and 'kid context' to one server may be used for correlating requests from one client.¶

Unprotected error messages reveal information about the security state in the communication between the endpoints. Unprotected signaling messages reveal information about the reliable transport used on a leg of the path. Using the mechanisms described in Section 7.5 may reveal when a device goes through a reboot. This can be mitigated by the device storing the precise state of sender sequence number and replay window on a clean shutdown.¶

The length of message fields can reveal information about the message. Applications may use a padding scheme to protect against traffic analysis.¶

13.1. COSE Header Parameters Registry

The 'kid context' parameter is added to the "COSE Header Parameters Registry":¶

• Name: kid context¶
• Label: TBD2¶
• Value Type: bstr¶
• Value Registry:¶
• Description: Identifies the context for 'kid'¶
• Reference: Section 5.1 of this document¶

Note to IANA: Label assignment in (Integer value between 1 and 255) is requested. (RFC Editor: Delete this note after IANA assignment)¶

13.2. CoAP Option Numbers Registry

The OSCORE option is added to the CoAP Option Numbers registry:¶

+--------+-----------------+-------------------+
| Number | Name            | Reference         |
+--------+-----------------+-------------------+
|  TBD1  | OSCORE          | [[this document]] |
+--------+-----------------+-------------------+

Note to IANA: Label assignment in (Integer value between 0 and 12) is requested. We also request Expert review if possible, to make sure a correct number for the option is selected (RFC Editor: Delete this note after IANA assignment)¶

Furthermore, the following existing entries in the CoAP Option Numbers registry are updated with a reference to the document specifying OSCORE processing of that option:¶

+--------+-----------------+---------------------------------------+
| Number | Name            |          Reference                    |
+--------+-----------------+---------------------------------------+
|   1    | If-Match        | [RFC7252] [[this document]]           |
|   3    | Uri-Host        | [RFC7252] [[this document]]           |
|   4    | ETag            | [RFC7252] [[this document]]           |
|   5    | If-None-Match   | [RFC7252] [[this document]]           |
|   6    | Observe         | [RFC7641] [[this document]]           |
|   7    | Uri-Port        | [RFC7252] [[this document]]           |
|   8    | Location-Path   | [RFC7252] [[this document]]           |
|  11    | Uri-Path        | [RFC7252] [[this document]]           |
|  12    | Content-Format  | [RFC7252] [[this document]]           |
|  14    | Max-Age         | [RFC7252] [[this document]]           |
|  15    | Uri-Query       | [RFC7252] [[this document]]           |
|  17    | Accept          | [RFC7252] [[this document]]           |
|  20    | Location-Query  | [RFC7252] [[this document]]           |
|  23    | Block2          | [RFC7959] [RFC8323] [[this document]] |
|  27    | Block1          | [RFC7959] [RFC8323] [[this document]] |
|  28    | Size2           | [RFC7959] [[this document]]           |
|  35    | Proxy-Uri       | [RFC7252] [[this document]]           |
|  39    | Proxy-Scheme    | [RFC7252] [[this document]]           |
|  60    | Size1           | [RFC7252] [[this document]]           |
| 258    | No-Response     | [RFC7967] [[this document]]           |
+--------+-----------------+---------------------------------------+

Future additions to the CoAP Option Numbers registry need to provide a reference to the document where the OSCORE processing of that CoAP Option is defined.¶

13.3. CoAP Signaling Option Numbers Registry

The OSCORE option is added to the CoAP Signaling Option Numbers registry:¶

+------------+--------+---------------------+-------------------+
| Applies to | Number | Name                | Reference         |
+------------+--------+---------------------+-------------------+
| 7.xx (all) |  TBD1  | OSCORE              | [[this document]] |
+------------+--------+---------------------+-------------------+

Note to IANA: The value in the "Number" field is the same value that's being assigned to the new Option Number. Please make sure TBD1 is not the same as any value in Numbers for any existing entry in the CoAP Signaling Option Numbers registry (at the time of writing this, that means make sure TBD1 is not 2 or 4)(RFC Editor: Delete this note after IANA assignment)¶

13.4. Header Field Registrations

The HTTP OSCORE header field is added to the Message Headers registry:¶

+-------------------+----------+----------+---------------------+
| Header Field Name | Protocol | Status   | Reference           |
+-------------------+----------+----------+---------------------+
| OSCORE            | http     | standard | [[this document]],  |
|                   |          |          | Section 11.1        |
+-------------------+----------+----------+---------------------+

13.5. Media Type Registrations

This section registers the 'application/oscore' media type in the "Media Types" registry. These media types are used to indicate that the content is an OSCORE message. The OSCORE body cannot be understood without the OSCORE header field value and the security context.¶

  Type name: application

  Subtype name: oscore

  Required parameters: N/A

  Optional parameters: N/A

  Encoding considerations: binary

  Security considerations: See the Security Considerations section
  of [[This document]].

  Interoperability considerations: N/A

  Published specification: [[This document]]

  Applications that use this media type: IoT applications sending
  security content over HTTP(S) transports.

  Fragment identifier considerations: N/A

  Additional information:

  *  Deprecated alias names for this type: N/A

  *  Magic number(s): N/A

  *  File extension(s): N/A

  *  Macintosh file type code(s): N/A

  Person & email address to contact for further information:
  iesg@ietf.org

  Intended usage: COMMON

  Restrictions on usage: N/A

  Author: Göran Selander, goran.selander@ericsson.com

  Change Controller: IESG

  Provisional registration?  No

13.6. CoAP Content-Formats Registry

Note to IANA: ID assignment in the 10000-64999 range is requested. (RFC Editor: Delete this note after IANA assignment)¶

This section registers the media type 'application/oscore' media type in the "CoAP Content-Formats" registry. This Content-Format for the OSCORE payload is defined for potential future use cases and SHALL NOT be used in the OSCORE message. The OSCORE payload cannot be understood without the OSCORE option value and the security context.¶

+----------------------+----------+----------+-------------------+
| Media Type           | Encoding |   ID     |     Reference     |
+----------------------+----------+----------+-------------------+
| application/oscore   |          |   TBD3   | [[this document]] |
+----------------------+----------+----------+-------------------+

13.7. OSCORE Flag Bits Registry

This document defines a sub-registry for the OSCORE flag bits within the "CoRE Parameters" registry. The name of the sub-registry is "OSCORE Flag Bits". The registry should be created with the Expert Review policy. Guidelines for the experts are provided in Section 13.8.¶

The columns of the registry are:¶

• bit position: This indicates the position of the bit in the set of OSCORE flag bits, starting at 0 for the most significant bit. The bit position must be an integer or a range of integers, in the range 0 to 63.¶
• name: The name is present to make it easier to refer to and discuss the registration entry. The value is not used in the protocol. Names are to be unique in the table.¶
• description: This contains a brief description of the use of the bit.¶
• specification: This contains a pointer to the specification defining the entry.¶

The initial contents of the registry can be found in the table below. The specification column for all rows in that table should be this document. The entries with Bit Position of 0 and 1 are to be marked as 'Reserved'. The entry with Bit Position of 1 is going to be specified in a future document, and will be used to expand the space for the OSCORE flag bits in Section 6.1, so that entries 8-63 of the registry are defined.¶

+--------------+-------------+---------------------+-------------------+
| Bit Position |     Name    |     Description     |   Specification   |
+--------------+-------------+---------------------+-------------------+
|       0      | Reserved    |                     |                   |
+--------------+-------------+---------------------+-------------------+
|       1      | Reserved    |                     |                   |
+--------------+-------------+---------------------+-------------------+
|       2      | Unassigned  |                     |                   |
+--------------+-------------+---------------------+-------------------+
|       3      | Kid Context | Set to 1 if 'kid    | [[this document]] |
|              | Flag        | context' is present |                   |
|              |             | in the compressed   |                   |
|              |             | COSE object         |                   |
+--------------+-------------+---------------------+-------------------+
|       4      | Kid Flag    | Set to 1 if kid is  | [[this document]] |
|              |             | present in the com- |                   |
|              |             | pressed COSE object |                   |
+--------------+-------------+---------------------+-------------------+
|     5-7      | Partial IV  | Encodes the Partial | [[this document]] |
|              | Length      | IV length; can have |                   |
|              |             | value 0 to 5        |                   |
+--------------+-------------+---------------------+-------------------+
|    8-63      | Unassigned  |                     |                   |
+--------------+-------------+---------------------+-------------------+

13.8. Expert Review Instructions

The expert reviewers for the registry defined in this document are expected to ensure that the usage solves a valid use case that could not be solved better in a different way, that it is not going to duplicate one that is already registered, and that the registered point is likely to be used in deployments. They are furthermore expected to check the clarity of purpose and use of the requested code points. Experts should take into account the expected usage of entries when approving point assignment, and the length of the encoded value should be weighed against the number of code points left that encode to that size and the size of device it will be used on. Experts should block registration for entries 8-63 until these points are defined (i.e. until the mechanism for the OSCORE flag bits expansion via bit 1 is specified).¶

A.1. Secure Access to Sensor

This example illustrates a client requesting the alarm status from a server.¶

Client  Proxy  Server
  |       |       |
  +------>|       |            Code: 0.02 (POST)
  | POST  |       |           Token: 0x8c
  |       |       |          OSCORE: [kid:5f, Partial IV:42]
  |       |       |         Payload: {Code:0.01,
  |       |       |                   Uri-Path:"alarm_status"}
  |       |       |
  |       +------>|            Code: 0.02 (POST)
  |       | POST  |           Token: 0x7b
  |       |       |          OSCORE: [kid:5f, Partial IV:42]
  |       |       |         Payload: {Code:0.01,
  |       |       |                   Uri-Path:"alarm_status"}
  |       |       |
  |       |<------+            Code: 2.04 (Changed)
  |       |  2.04 |           Token: 0x7b
  |       |       |          OSCORE: -
  |       |       |         Payload: {Code:2.05, "0"}
  |       |       |
  |<------+       |            Code: 2.04 (Changed)
  |  2.04 |       |           Token: 0x8c
  |       |       |          OSCORE: -
  |       |       |         Payload: {Code:2.05, "0"}
  |       |       |

The request/response Codes are encrypted by OSCORE and only dummy Codes (POST/Changed) are visible in the header of the OSCORE message. The option Uri-Path ("alarm_status") and payload ("0") are encrypted.¶

The COSE header of the request contains an identifier (5f), indicating which security context was used to protect the message and a Partial IV (42).¶

The server verifies the request as specified in Section 8.2. The client verifies the response as specified in Section 8.4.¶

A.2. Secure Subscribe to Sensor

This example illustrates a client requesting subscription to a blood sugar measurement resource (GET /glucose), first receiving the value 220 mg/dl and then a second value 180 mg/dl.¶

Client  Proxy  Server
  |       |       |
  +------>|       |            Code: 0.05 (FETCH)
  | FETCH |       |           Token: 0x83
  |       |       |         Observe: 0
  |       |       |          OSCORE: [kid:ca, Partial IV:15]
  |       |       |         Payload: {Code:0.01,
  |       |       |                   Uri-Path:"glucose"}
  |       |       |
  |       +------>|            Code: 0.05 (FETCH)
  |       | FETCH |           Token: 0xbe
  |       |       |         Observe: 0
  |       |       |          OSCORE: [kid:ca, Partial IV:15]
  |       |       |         Payload: {Code:0.01,
  |       |       |                   Uri-Path:"glucose"}
  |       |       |
  |       |<------+            Code: 2.05 (Content)
  |       |  2.05 |           Token: 0xbe
  |       |       |         Observe: 7
  |       |       |          OSCORE: [Partial IV:32]
  |       |       |         Payload: {Code:2.05,
  |       |       |                   Content-Format:0, "220"}
  |       |       |
  |<------+       |            Code: 2.05 (Content)
  |  2.05 |       |           Token: 0x83
  |       |       |         Observe: 7
  |       |       |          OSCORE: [Partial IV:32]
  |       |       |         Payload: {Code:2.05,
  |       |       |                   Content-Format:0, "220"}
 ...     ...     ...
  |       |       |
  |       |<------+            Code: 2.05 (Content)
  |       |  2.05 |           Token: 0xbe
  |       |       |         Observe: 8
  |       |       |          OSCORE: [Partial IV:36]
  |       |       |         Payload: {Code:2.05,
  |       |       |                   Content-Format:0, "180"}
  |       |       |
  |<------+       |            Code: 2.05 (Content)
  |  2.05 |       |           Token: 0x83
  |       |       |         Observe: 8
  |       |       |          OSCORE: [Partial IV:36]
  |       |       |         Payload: {Code:2.05,
  |       |       |                   Content-Format:0, "180"}
  |       |       |

The dummy Codes (FETCH/Content) are used to allow forwarding of Observe messages. The options Content-Format (0) and the payload ("220" and "180"), are encrypted.¶

The COSE header of the request contains an identifier (ca), indicating the security context used to protect the message and a Partial IV (15). The COSE headers of the responses contains Partial IVs (32 and 36).¶

The server verifies that the Partial IV has not been received before. The client verifies that the responses are bound to the request and that the Partial IVs are greater than any Partial IV previously received in a response bound to the request.¶

B.1. Security Context Derived Once

An application that only derives the security context once needs to handle the loss of mutable security context parameters, e.g. due to reboot.¶

B.2. Security Context Derived Multiple Times

An application which does not require forward secrecy may allow multiple security contexts to be derived from one Master Secret. The requirements on the security context parameters MUST be fulfilled (Section 3.3) even if the client or server is rebooted, recommissioned or in error cases.¶

This section gives an example of a protocol which adds randomness to the ID Context parameter and uses that together with input parameters pre-established between client and server, in particular Master Secret, Master Salt, and Sender/Recipient ID (see Section 3.2), to derive new security contexts. The random input is transported between client and server in the 'kid context' parameter. This protocol MUST NOT be used unless both endpoints have good sources of randomness.¶

During normal requests the ID Context of an established security context may be sent in the 'kid context' which, together with 'kid', facilitates for the server to locate a security context. Alternatively, the 'kid context' may be omitted since the ID Context is expected to be known to both client and server, see Section 5.1.¶

The protocol described in this section may only be needed when the mutable part of security context is lost in the client or server, e.g. when the endpoint has rebooted. The protocol may additionally be used whenever the client and server need to derive a new security context. For example, if a device is provisioned with one fixed set of input parameters (including Master Secret, Sender and Recipient Identifiers) then a randomized ID Context ensures that the security context is different for each deployment.¶

The protocol is described below with reference to Figure 14. The client or the server may initiate the protocol, in the latter case step 1 is omitted.¶

                      Client                Server
                        |                      |
1. Protect with         |      request #1      |
   ID Context = ID1     |--------------------->| 2. Verify with
                        |  kid_context = ID1   |    ID Context = ID1
                        |                      |
                        |      response #1     |    Protect with
3. Verify with          |<---------------------|    ID Context = R2||ID1
   ID Context = R2||ID1 |   kid_context = R2   |
                        |                      |
   Protect with         |      request #2      |
   ID Context = R2||R3  |--------------------->| 4. Verify with
                        | kid_context = R2||R3 |    ID Context = R2||R3
                        |                      |
                        |      response #2     |    Protect with
5. Verify with          |<---------------------|    ID Context = R2||R3
   ID Context = R2||R3  |                      |

1. (Optional) If the client does not have a valid security context with the server, e.g. because of reboot or because this is the first time it contacts the server, then it generates a random string R1, and uses this as ID Context together with the input parameters shared with the server to derive a first security context. The client sends an OSCORE request to the server protected with the first security context, containing R1 wrapped in a CBOR bstr as 'kid context'. The request may target a special resource used for updating security contexts.¶
2. The server receives an OSCORE request for which it does not have a valid security context, either because the client has generated a new security context ID1 = R1, or because the server has lost part of its security context, e.g. ID Context, Sender Sequence Number or replay window. If the server is able to verify the request (see Section 8.2) with the new derived first security context using the received ID1 (transported in 'kid context') as ID Context and the input parameters associated to the received 'kid', then the server generates a random string R2, and derives a second security context with ID Context = ID2 = R2 || ID1. The server sends a 4.01 (Unauthorized) response protected with the second security context, containing R2 wrapped in a CBOR bstr as 'kid context', and caches R2. R2 MUST NOT be reused as that may lead to reuse of key and nonce in reponse #1. Note that the server may receive several requests #1 associated with one security context, leading to multiple parallel protocol runs. Multiple instances of R2 may need to be cached until one of the protocol runs is completed, see Appendix B.2.1.¶
3. The client receives a response with 'kid context' containing a CBOR bstr wrapping R2 to an OSCORE request it made with ID Context = ID1. The client derives a second security context using ID Context = ID2 = R2 || ID1. If the client can verify the response (see Section 8.4) using the second security context, then the client makes a request protected with a third security context derived from ID Context = ID3 = R2 || R3, where R3 is a random byte string generated by the client. The request includes R2 || R3 wrapped in a CBOR bstr as 'kid context'.¶
4. If the server receives a request with 'kid context' containing a CBOR bstr wrapping ID3, where the first part of ID3 is identical to an R2 sent in a previous response #1 which it has not received before, then the server derives a third security context with ID Context = ID3. The server MUST NOT accept replayed request #2 messages. If the server can verify the request (see Section 8.2) with the third security context, then the server marks the third security context to be used with this client and removes all instances of R2 associated to this security context from the cache. This security context replaces the previous security context with the client, and the first and the second security contexts are deleted. The server responds using the same security context as in the request.¶
5. If the client receives a response to the request with the third security context and the response verifies (see Section 8.4), then the client marks the third security context to be used with this server. This security context replaces the previous security context with the server, and the first and second security contexts are deleted.¶

If verification fails in any step, the endpoint stops processing that message.¶

The length of the nonces R1, R2, and R3 is application specific. The application needs to set the length of each nonce such the probability of its value being repeated is negligible; typically, at least 8 bytes long. Since R2 may be generated as the result of a replayed request #1, the probability for collision of R2s is impacted by the birthday paradox. For example, setting the length of R2 to 8 bytes results in an average collision after 2^32 response #1 messages, which should not be an issue for a constrained server handling on the order of one request per second.¶

Request #2 can be an ordinary request. The server performs the action of the request and sends response #2 after having successfully completed the security context related operations in step 4. The client acts on response #2 after having successfully completed step 5.¶

When sending request #2, the client is assured that the Sender Key (derived with the random value R3) has never been used before. When receiving response #2, the client is assured that the response (protected with a key derived from the random value R3 and the Master Secret) was created by the server in response to request #2.¶

Similarly, when receiving request #2, the server is assured that the request (protected with a key derived from the random value R2 and the Master Secret) was created by the client in response to response #1. When sending response #2, the server is assured that the Sender Key (derived with the random value R2) has never been used before.¶

Implementation and denial-of-service considerations are made in Appendix B.2.1 and Appendix B.2.2.¶

C.1. Test Vector 1: Key Derivation with Master Salt

In this test vector, a Master Salt of 8 bytes is used. The default values are used for AEAD Algorithm and HKDF.¶

C.2. Test Vector 2: Key Derivation without Master Salt

In this test vector, the default values are used for AEAD Algorithm, HKDF, and Master Salt.¶

C.3. Test Vector 3: Key Derivation with ID Context

In this test vector, a Master Salt of 8 bytes and a ID Context of 8 bytes are used. The default values are used for AEAD Algorithm and HKDF.¶

C.4. Test Vector 4: OSCORE Request, Client

This section contains a test vector for an OSCORE protected CoAP GET request using the security context derived in Appendix C.1. The unprotected request only contains the Uri-Path and Uri-Host options.¶

Unprotected CoAP request: 0x44015d1f00003974396c6f63616c686f737483747631 (22 bytes)¶

Common Context:¶

• AEAD Algorithm: 10 (AES-CCM-16-64-128)¶
• Key Derivation Function: HKDF SHA-256¶
• Common IV: 0x4622d4dd6d944168eefb54987c (13 bytes)¶

Sender Context:¶

• Sender ID: 0x (0 byte)¶
• Sender Key: 0xf0910ed7295e6ad4b54fc793154302ff (16 bytes)¶
• Sender Sequence Number: 20¶

The following COSE and cryptographic parameters are derived:¶

• Partial IV: 0x14 (1 byte)¶
• kid: 0x (0 byte)¶
• external_aad: 0x8501810a40411440 (8 bytes)¶
• AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes)¶
• plaintext: 0x01b3747631 (5 bytes)¶
• encryption key: 0xf0910ed7295e6ad4b54fc793154302ff (16 bytes)¶
• nonce: 0x4622d4dd6d944168eefb549868 (13 bytes)¶

From the previous parameter, the following is derived:¶

• OSCORE option value: 0x0914 (2 bytes)¶
• ciphertext: 0x612f1092f1776f1c1668b3825e (13 bytes)¶

From there:¶

• Protected CoAP request (OSCORE message): 0x44025d1f00003974396c6f63616c686f7374620914ff612f1092f1776f1c1668b3825e (35 bytes)¶

C.5. Test Vector 5: OSCORE Request, Client

This section contains a test vector for an OSCORE protected CoAP GET request using the security context derived in Appendix C.2. The unprotected request only contains the Uri-Path and Uri-Host options.¶

Unprotected CoAP request: 0x440171c30000b932396c6f63616c686f737483747631 (22 bytes)¶

Common Context:¶

• AEAD Algorithm: 10 (AES-CCM-16-64-128)¶
• Key Derivation Function: HKDF SHA-256¶
• Common IV: 0xbe35ae297d2dace910c52e99f9 (13 bytes)¶

Sender Context:¶

• Sender ID: 0x00 (1 bytes)¶
• Sender Key: 0x321b26943253c7ffb6003b0b64d74041 (16 bytes)¶
• Sender Sequence Number: 20¶

The following COSE and cryptographic parameters are derived:¶

• Partial IV: 0x14 (1 byte)¶
• kid: 0x00 (1 byte)¶
• external_aad: 0x8501810a4100411440 (9 bytes)¶
• AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes)¶
• plaintext: 0x01b3747631 (5 bytes)¶
• encryption key: 0x321b26943253c7ffb6003b0b64d74041 (16 bytes)¶
• nonce: 0xbf35ae297d2dace910c52e99ed (13 bytes)¶

From the previous parameter, the following is derived:¶

• OSCORE option value: 0x091400 (3 bytes)¶
• ciphertext: 0x4ed339a5a379b0b8bc731fffb0 (13 bytes)¶

From there:¶

• Protected CoAP request (OSCORE message): 0x440271c30000b932396c6f63616c686f737463091400ff4ed339a5a379b0b8bc731fffb0 (36 bytes)¶

C.6. Test Vector 6: OSCORE Request, Client

This section contains a test vector for an OSCORE protected CoAP GET request for an application that sets the ID Context and requires it to be sent in the request, so 'kid context' is present in the protected message. This test vector uses the security context derived in Appendix C.3. The unprotected request only contains the Uri-Path and Uri-Host options.¶

Unprotected CoAP request: 0x44012f8eef9bbf7a396c6f63616c686f737483747631 (22 bytes)¶

Common Context:¶

• AEAD Algorithm: 10 (AES-CCM-16-64-128)¶
• Key Derivation Function: HKDF SHA-256¶
• Common IV: 0x2ca58fb85ff1b81c0b7181b85e (13 bytes)¶
• ID Context: 0x37cbf3210017a2d3 (8 bytes)¶

Sender Context:¶

• Sender ID: 0x (0 bytes)¶
• Sender Key: 0xaf2a1300a5e95788b356336eeecd2b92 (16 bytes)¶
• Sender Sequence Number: 20¶

The following COSE and cryptographic parameters are derived:¶

• Partial IV: 0x14 (1 byte)¶
• kid: 0x (0 byte)¶
• kid context: 0x37cbf3210017a2d3 (8 bytes)¶
• external_aad: 0x8501810a40411440 (8 bytes)¶
• AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes)¶
• plaintext: 0x01b3747631 (5 bytes)¶
• encryption key: 0xaf2a1300a5e95788b356336eeecd2b92 (16 bytes)¶
• nonce: 0x2ca58fb85ff1b81c0b7181b84a (13 bytes)¶

From the previous parameter, the following is derived:¶

• OSCORE option value: 0x19140837cbf3210017a2d3 (11 bytes)¶
• ciphertext: 0x72cd7273fd331ac45cffbe55c3 (13 bytes)¶

From there:¶

• Protected CoAP request (OSCORE message): 0x44022f8eef9bbf7a396c6f63616c686f73746b19140837cbf3210017a2d3ff 72cd7273fd331ac45cffbe55c3 (44 bytes)¶

C.7. Test Vector 7: OSCORE Response, Server

This section contains a test vector for an OSCORE protected 2.05 (Content) response to the request in Appendix C.4. The unprotected response has payload "Hello World!" and no options. The protected response does not contain a 'kid' nor a Partial IV. Note that some parameters are derived from the request.¶

Unprotected CoAP response: 0x64455d1f00003974ff48656c6c6f20576f726c6421 (21 bytes)¶

Common Context:¶

• AEAD Algorithm: 10 (AES-CCM-16-64-128)¶
• Key Derivation Function: HKDF SHA-256¶
• Common IV: 0x4622d4dd6d944168eefb54987c (13 bytes)¶

Sender Context:¶

• Sender ID: 0x01 (1 byte)¶
• Sender Key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes)¶
• Sender Sequence Number: 0¶

The following COSE and cryptographic parameters are derived:¶

• external_aad: 0x8501810a40411440 (8 bytes)¶
• AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes)¶
• plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes)¶
• encryption key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes)¶
• nonce: 0x4622d4dd6d944168eefb549868 (13 bytes)¶

From the previous parameter, the following is derived:¶

• OSCORE option value: 0x (0 bytes)¶
• ciphertext: 0xdbaad1e9a7e7b2a813d3c31524378303cdafae119106 (22 bytes)¶

From there:¶

• Protected CoAP response (OSCORE message): 0x64445d1f0000397490ffdbaad1e9a7e7b2a813d3c31524378303cdafae119106 (32 bytes)¶

C.8. Test Vector 8: OSCORE Response with Partial IV, Server

This section contains a test vector for an OSCORE protected 2.05 (Content) response to the request in Appendix C.4. The unprotected response has payload "Hello World!" and no options. The protected response does not contain a 'kid', but contains a Partial IV. Note that some parameters are derived from the request.¶

Unprotected CoAP response: 0x64455d1f00003974ff48656c6c6f20576f726c6421 (21 bytes)¶

Common Context:¶

• AEAD Algorithm: 10 (AES-CCM-16-64-128)¶
• Key Derivation Function: HKDF SHA-256¶
• Common IV: 0x4622d4dd6d944168eefb54987c (13 bytes)¶

Sender Context:¶

• Sender ID: 0x01 (1 byte)¶
• Sender Key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes)¶
• Sender Sequence Number: 0¶

The following COSE and cryptographic parameters are derived:¶

• Partial IV: 0x00 (1 byte)¶
• external_aad: 0x8501810a40411440 (8 bytes)¶
• AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes)¶
• plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes)¶
• encryption key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes)¶
• nonce: 0x4722d4dd6d944169eefb54987c (13 bytes)¶

From the previous parameter, the following is derived:¶

• OSCORE option value: 0x0100 (2 bytes)¶
• ciphertext: 0x4d4c13669384b67354b2b6175ff4b8658c666a6cf88e (22 bytes)¶

From there:¶

• Protected CoAP response (OSCORE message): 0x64445d1f00003974920100ff4d4c13669384b67354b2b6175ff4b8658c666a6cf88e (34 bytes)¶

D.1. Threat Model

This section describes the threat model using the terms of [RFC3552].¶

It is assumed that the endpoints running OSCORE have not themselves been compromised. The attacker is assumed to have control of the CoAP channel over which the endpoints communicate, including intermediary nodes. The attacker is capable of launching any passive or active, on-path or off-path attacks; including eavesdropping, traffic analysis, spoofing, insertion, modification, deletion, delay, replay, man-in-the-middle, and denial-of-service attacks. This means that the attacker can read any CoAP message on the network and undetectably remove, change, or inject forged messages onto the wire.¶

OSCORE targets the protection of the CoAP request/response layer (Section 2 of [RFC7252]) between the endpoints, including the CoAP Payload, Code, Uri-Path/Uri-Query, and the other Class E option instances (Section 4.1).¶

OSCORE does not protect the CoAP messaging layer (Section 2 of [RFC7252]) or other lower layers involved in routing and transporting the CoAP requests and responses.¶

Additionally, OSCORE does not protect Class U option instances (Section 4.1), as these are used to support CoAP forward proxy operations (see Section 5.7.2 of [RFC7252]). The supported proxies (forwarding, cross-protocol e.g. CoAP to CoAP-mappable protocols such as HTTP) must be able to change certain Class U options (by instruction from the Client), resulting in the CoAP request being redirected to the server. Changes caused by the proxy may result in the request not reaching the server or reaching the wrong server. For cross-protocol proxies, mappings are done on the Outer part of the message so these protocols are essentially used as transport. Manipulation of these options may thus impact whether the protected message reaches or does not reach the destination endpoint.¶

Attacks on unprotected CoAP message fields generally causes denial-of-service attacks which are out of scope of this document, more details are given in Appendix D.5.¶

Attacks against the CoAP request-response layer are in scope. OSCORE is intended to protect against eavesdropping, spoofing, insertion, modification, deletion, replay, and man-in-the middle attacks.¶

OSCORE is susceptible to traffic analysis as discussed later in Appendix D.¶

D.2. Supporting Proxy Operations

CoAP is designed to work with intermediaries reading and/or changing CoAP message fields to perform supporting operations in constrained environments, e.g. forwarding and cross-protocol translations.¶

Securing CoAP on transport layer protects the entire message between the endpoints in which case CoAP proxy operations are not possible. In order to enable proxy operations, security on transport layer needs to be terminated at the proxy in which case the CoAP message in its entirety is unprotected in the proxy.¶

Requirements for CoAP end-to-end security are specified in [I-D.hartke-core-e2e-security-reqs], in particular forwarding is detailed in Section 2.2.1. The client and server are assumed to be honest, while proxies and gateways are only trusted to perform their intended operations.¶

By working at the CoAP layer, OSCORE enables different CoAP message fields to be protected differently, which allows message fields required for proxy operations to be available to the proxy while message fields intended for the other endpoint remain protected. In the remainder of this section we analyze how OSCORE protects the protected message fields and the consequences of message fields intended for proxy operation being unprotected.¶

D.3. Protected Message Fields

Protected message fields are included in the Plaintext (Section 5.3) and the Additional Authenticated Data (Section 5.4) of the COSE_Encrypt0 object and encrypted using an AEAD algorithm.¶

OSCORE depends on a pre-established random Master Secret (Section 12.3) used to derive encryption keys, and a construction for making (key, nonce) pairs unique (Appendix D.4). Assuming this is true, and the keys are used for no more data than indicated in Section 7.2.1, OSCORE should provide the following guarantees:¶

• Confidentiality: An attacker should not be able to determine the plaintext contents of a given OSCORE message or determine that different plaintexts are related (Section 5.3).¶
• Integrity: An attacker should not be able to craft a new OSCORE message with protected message fields different from an existing OSCORE message which will be accepted by the receiver.¶
• Request-response binding: An attacker should not be able to make a client match a response to the wrong request.¶
• Non-replayability: An attacker should not be able to cause the receiver to accept a message which it has previously received and accepted.¶

In the above, the attacker is anyone except the endpoints, e.g. a compromised intermediary. Informally, OSCORE provides these properties by AEAD-protecting the plaintext with a strong key and uniqueness of (key, nonce) pairs. AEAD encryption [RFC5116] provides confidentiality and integrity for the data. Response-request binding is provided by including the 'kid' and Partial IV of the request in the AAD of the response. Non-replayability of requests and notifications is provided by using unique (key, nonce) pairs and a replay protection mechanism (application dependent, see Section 7.4).¶

OSCORE is susceptible to a variety of traffic analysis attacks based on observing the length and timing of encrypted packets. OSCORE does not provide any specific defenses against this form of attack but the application may use a padding mechanism to prevent an attacker from directly determine the length of the padding. However, information about padding may still be revealed by side-channel attacks observing differences in timing.¶

D.4. Uniqueness of (key, nonce)

In this section we show that (key, nonce) pairs are unique as long as the requirements in Sections 3.3 and 7.2.1 are followed.¶

Fix a Common Context (Section 3.1) and an endpoint, called the encrypting endpoint. An endpoint may alternate between client and server roles, but each endpoint always encrypts with the Sender Key of its Sender Context. Sender Keys are (stochastically) unique since they are derived with HKDF using unique Sender IDs, so messages encrypted by different endpoints use different keys. It remains to prove that the nonces used by the fixed endpoint are unique.¶

Since the Common IV is fixed, the nonces are determined by a Partial IV (PIV) and the Sender ID of the endpoint generating that Partial IV (ID_PIV). The nonce construction (Section 5.2) with the size of the ID_PIV (S) creates unique nonces for different (ID_PIV, PIV) pairs. There are two cases:¶

A. For requests, and responses with Partial IV (e.g. Observe notifications):¶

• ID_PIV = Sender ID of the encrypting endpoint¶
• PIV = current Partial IV of the encrypting endpoint¶

Since the encrypting endpoint steps the Partial IV for each use, the nonces used in case A are all unique as long as the number of encrypted messages is kept within the required range (Section 7.2.1).¶

B. For responses without Partial IV (e.g. single response to a request):¶

• ID_PIV = Sender ID of the endpoint generating the request¶
• PIV = Partial IV of the request¶

Since the Sender IDs are unique, ID_PIV is different from the Sender ID of the encrypting endpoint. Therefore, the nonces in case B are different compared to nonces in case A, where the encrypting endpoint generated the Partial IV. Since the Partial IV of the request is verified for replay (Section 7.4) associated to this Recipient Context, PIV is unique for this ID_PIV, which makes all nonces in case B distinct.¶

D.5. Unprotected Message Fields

This sections analyses attacks on message fields which are not protected by OSCORE according to the threat model Appendix D.1.¶