Tech-invite3GPPspaceIETF RFCsSIP
93929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 8613

Object Security for Constrained RESTful Environments (OSCORE)

Pages: 94
Proposed Standard
Updates:  7252
Part 2 of 6 – Pages 15 to 35
First   Prev   Next

Top   ToC   RFC8613 - Page 15   prevText

4. Protected Message Fields

OSCORE transforms a CoAP message (which may have been generated from an HTTP message) into an OSCORE message, and vice versa. OSCORE protects as much of the original message as possible while still allowing certain proxy operations (see Sections 10 and 11). This section defines how OSCORE protects the message fields and transfers them end-to-end between client and server (in any direction). The remainder of this section and later sections focus on the behavior in terms of CoAP messages. If HTTP is used for a particular hop in the end-to-end path, then this section applies to the conceptual CoAP message that is mappable to/from the original HTTP message as discussed in Section 11. That is, an HTTP message is conceptually transformed to a CoAP message and then to an OSCORE message, and similarly in the reverse direction. An actual implementation might translate directly from HTTP to OSCORE without the intervening CoAP representation. Protection of signaling messages (Section 5 of [RFC8323]) is specified in Section 4.3. The other parts of this section target request/response messages. Message fields of the CoAP message may be protected end-to-end between CoAP client and CoAP server in different ways: o Class E: encrypted and integrity protected, o Class I: integrity protected only, or o Class U: unprotected. The sending endpoint SHALL transfer Class E message fields in the ciphertext of the COSE object in the OSCORE message. The sending endpoint SHALL include Class I message fields in the AAD of the AEAD algorithm, allowing the receiving endpoint to detect if the value has changed in transfer. Class U message fields SHALL NOT be protected in transfer. Class I and Class U message field values are transferred in the header or options part of the OSCORE message, which is visible to proxies. Message fields not visible to proxies, i.e., transported in the ciphertext of the COSE object, are called "Inner" (Class E). Message fields transferred in the header or options part of the OSCORE message, which is visible to proxies, are called "Outer" (Class I or Class U). There are currently no Class I options defined.
Top   ToC   RFC8613 - Page 16
   An OSCORE message may contain both an Inner and an Outer instance of
   a certain CoAP message field.  Inner message fields are intended for
   the receiving endpoint, whereas Outer message fields are used to
   enable proxy operations.

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

4.1.1. Inner Options

Inner option message fields (Class E) are used to communicate directly with the other endpoint. The sending endpoint SHALL write the Inner option message fields present in the original CoAP message into the plaintext of the COSE object (Section 5.3) and then remove the Inner option message fields from the OSCORE message. The processing of Inner option message fields by the receiving endpoint is specified in Sections 8.2 and 8.4.
Top   ToC   RFC8613 - Page 17
                   +------+-----------------+---+---+
                   | 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 |   |
                   |   9  | 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)

                   Figure 5: Protection of CoAP Options

4.1.2. Outer Options

Outer option message fields (Class U or I) are used to support proxy operations, see Appendix D.2. The sending endpoint SHALL include the Outer option message field present in the original message in the options part of the OSCORE message. All Outer option message fields, including the OSCORE option, SHALL be encoded as described in Section 3.1 of [RFC7252], where the delta is the difference from the previously included instance of Outer option message field. The processing of Outer options by the receiving endpoint is specified in Sections 8.2 and 8.4.
Top   ToC   RFC8613 - Page 18
   A procedure for integrity-protection-only of Class I option message
   fields is specified in Section 5.4.  Specifications that introduce
   repeatable Class I options MUST specify that proxies MUST NOT change
   the order of the instances of such an option in the CoAP message.

   Note: There are currently no Class I option message fields defined.

4.1.3. Special Options

Some options require special processing as specified in this section.
4.1.3.1. Max-Age
An Inner Max-Age message field is used to indicate the maximum time a response may be cached by the client (as defined in [RFC7252]), end- to-end from the server to the client, taking into account that the option is not accessible to proxies. The Inner Max-Age SHALL be processed by OSCORE as a normal Inner option, specified in Section 4.1.1. An Outer Max-Age message field is used to avoid unnecessary caching of error responses caused by OSCORE processing at OSCORE-unaware intermediary nodes. A server MAY set a Class U Max-Age message field with value zero to such error responses, described in Sections 7.4, 8.2, and 8.4, since these error responses are cacheable, but subsequent OSCORE requests would never create a hit in the intermediary node caching it. Setting the Outer Max-Age to zero relieves the intermediary from uselessly caching responses. Successful OSCORE responses do not need to include an Outer Max-Age option. Except when the Observe option (see Section 4.1.3.5) is used, responses appear to the OSCORE-unaware intermediary as 2.04 (Changed) responses, which are non-cacheable (see Section 4.2). For Observe responses, which are cacheable, an Outer Max-Age option with value 0 may be used to avoid unnecessary proxy caching. The Outer Max-Age message field is processed according to Section 4.1.2.
4.1.3.2. Uri-Host and Uri-Port
When the Uri-Host and Uri-Port are set to their default values (see Section 5.10.1 [RFC7252]), they are omitted from the message (Section 5.4.4 of [RFC7252]), which is favorable both for overhead and privacy. In order to support forward proxy operations, Proxy-Scheme, Uri-Host, and Uri-Port need to be Class U. For the use of Proxy-Uri, see Section 4.1.3.3.
Top   ToC   RFC8613 - Page 19
   Manipulation of unprotected message fields (including Uri-Host, Uri-
   Port, destination IP/port or request scheme) MUST NOT lead to an
   OSCORE message becoming verified by an unintended server.  Different
   servers SHALL have different security contexts.

4.1.3.3. Proxy-Uri
When Proxy-Uri is present, the client SHALL first decompose the Proxy-Uri value of the original CoAP message into the Proxy-Scheme, Uri-Host, Uri-Port, Uri-Path, and Uri-Query options according to Section 6.4 of [RFC7252]. Uri-Path and Uri-Query are Class E options and SHALL be protected and processed as Inner options (Section 4.1.1). The Proxy-Uri option of the OSCORE message SHALL be set to the composition of Proxy-Scheme, Uri-Host, and Uri-Port options as specified in Section 6.5 of [RFC7252] and processed as an Outer option of Class U (Section 4.1.2). Note that replacing the Proxy-Uri value with the Proxy-Scheme and Uri-* options works by design for all CoAP URIs (see Section 6 of [RFC7252]). OSCORE-aware HTTP servers should not use the userinfo component of the HTTP URI (as defined in Section 3.2.1 of [RFC3986]), so that this type of replacement is possible in the presence of CoAP- to-HTTP proxies (see Section 11.2). In future specifications of cross-protocol proxying behavior using different URI structures, it is expected that the authors will create Uri-* options that allow decomposing the Proxy-Uri, and specifying the OSCORE processing. An example of how Proxy-Uri is processed is given here. Assume that the original CoAP message contains: o Proxy-Uri = "coap://example.com/resource?q=1" During OSCORE processing, Proxy-Uri is split into: o Proxy-Scheme = "coap" o Uri-Host = "example.com" o Uri-Port = "5683" (default) o Uri-Path = "resource" o Uri-Query = "q=1"
Top   ToC   RFC8613 - Page 20
   Uri-Path and Uri-Query follow the processing defined in
   Section 4.1.1; thus, they are encrypted and transported in the COSE
   object:

   o  Uri-Path = "resource"

   o  Uri-Query = "q=1"

   The remaining options are composed into the Proxy-Uri included in the
   options part of the OSCORE message, which has value:

   o  Proxy-Uri = "coap://example.com"

   See Sections 6.1 and 12.6 of [RFC7252] for more details.

4.1.3.4. The Block Options
Block-wise [RFC7959] is an optional feature. An implementation MAY support CoAP [RFC7252] and the OSCORE option without supporting block-wise transfers. The Block options (Block1, Block2, Size1, Size2), when Inner message fields, provide secure message segmentation such that each segment can be verified. The Block options, when Outer message fields, enable hop-by-hop fragmentation of the OSCORE message. Inner and Outer block processing may have different performance properties depending on the underlying transport. The end-to-end integrity of the message can be verified both in case of Inner and Outer Block-wise transfers, provided all blocks are received.
4.1.3.4.1. Inner Block Options
The sending CoAP endpoint MAY fragment a CoAP message as defined in [RFC7959] before the message is processed by OSCORE. In this case, the Block options SHALL be processed by OSCORE as normal Inner options (Section 4.1.1). The receiving CoAP endpoint SHALL process the OSCORE message before processing Block-wise as defined in [RFC7959].
4.1.3.4.2. Outer Block Options
Proxies MAY fragment an OSCORE message using [RFC7959] by introducing Block option message fields that are Outer (Section 4.1.2). Note that the Outer Block options are neither encrypted nor integrity protected. As a consequence, a proxy can maliciously inject block fragments indefinitely, since the receiving endpoint needs to receive the last block (see [RFC7959]) to be able to compose the OSCORE message and verify its integrity. Therefore, applications supporting OSCORE and [RFC7959] MUST specify a security policy defining a
Top   ToC   RFC8613 - Page 21
   maximum unfragmented message size (MAX_UNFRAGMENTED_SIZE) considering
   the maximum size of message that can be handled by the endpoints.
   Messages exceeding this size SHOULD be fragmented by the sending
   endpoint using Inner Block options (Section 4.1.3.4.1).

   An endpoint receiving an OSCORE message with an Outer Block option
   SHALL first process this option according to [RFC7959], until all
   blocks of the OSCORE message have been received or the cumulated
   message size of the blocks exceeds MAX_UNFRAGMENTED_SIZE.  In the
   former case, the processing of the OSCORE message continues as
   defined in this document.  In the latter case, the message SHALL be
   discarded.

   Because of encryption of Uri-Path and Uri-Query, messages to the same
   server may, from the point of view of a proxy, look like they also
   target the same resource.  A proxy SHOULD mitigate a potential mix-up
   of blocks from concurrent requests to the same server, for example,
   using the Request-Tag processing specified in Section 3.3.2 of
   [CoAP-ECHO-REQ-TAG].

4.1.3.5. Observe
Observe [RFC7641] is an optional feature. An implementation MAY support CoAP [RFC7252] and the OSCORE option without supporting [RFC7641], in which case the Observe-related processing can be omitted. The support for Observe [RFC7641] with OSCORE targets the requirements on forwarding of Section 2.2.1 of [CoAP-E2E-Sec], i.e., that observations go through intermediary nodes, as illustrated in Figure 8 of [RFC7641]. Inner Observe SHALL be used to protect the value of the Observe option between the endpoints. Outer Observe SHALL be used to support forwarding by intermediary nodes. The server SHALL include a new Partial IV (see Section 5) in responses (with or without the Observe option) to Observe registrations, except for the first response where Partial IV MAY be omitted. For cancellations, Section 3.6 of [RFC7641] specifies that all options MUST be identical to those in the registration request except for the Observe option and the set of ETag options. For OSCORE messages, this matching is to be done to the options in the decrypted message.
Top   ToC   RFC8613 - Page 22
   [RFC7252] does not specify how the server should act upon receiving
   the same Token in different requests.  When using OSCORE, the server
   SHOULD NOT remove an active observation just because it receives a
   request with the same Token.

   Since POST with the Observe option is not defined, for messages with
   the Observe option, the Outer Code MUST be set to 0.05 (FETCH) for
   requests and to 2.05 (Content) for responses (see Section 4.2).

4.1.3.5.1. Registrations and Cancellations
The Inner and Outer Observe options in the request MUST contain the Observe value of the original CoAP request; 0 (registration) or 1 (cancellation). Every time a client issues a new request with the Observe option, a new Partial IV MUST be used (see Section 5), and so the payload and OSCORE option are changed. The server uses the Partial IV of the new request as the 'request_piv' of all associated notifications (see Section 5.4). Intermediaries are not assumed to have access to the OSCORE security context used by the endpoints; thus, they cannot make requests or transform responses with the OSCORE option that pass verification (at the receiving endpoint) as having come from the other endpoint. This has the following consequences and limitations for Observe operations. o An intermediary node removing the Outer Observe 0 option does not change the registration request to a request without the Observe option (see Section 2 of [RFC7641]). Instead other means for cancellation may be used as described in Section 3.6 of [RFC7641]. o An intermediary node is not able to transform a normal response into an OSCORE-protected Observe notification (see Figure 7 of [RFC7641]) that verifies as coming from the server. o An intermediary node is not able to initiate an OSCORE protected Observe registration (Observe option with value 0) that verifies as coming from the client. An OSCORE-aware intermediary SHALL NOT initiate registrations of observations (see Section 10). If an OSCORE-unaware proxy resends an old registration message from a client, the replay protection mechanism in the server will be triggered. To prevent this from resulting in the OSCORE-unaware proxy canceling the registration, a server MAY respond to a replayed registration request with a replay of a cached notification. Alternatively, the server MAY send a new notification.
Top   ToC   RFC8613 - Page 23
   o  An intermediary node is not able to initiate an OSCORE-protected
      Observe cancellation (Observe option with value 1) that verifies
      as coming from the client.  An application MAY decide to allow
      intermediaries to cancel Observe registrations, e.g., to send the
      Observe option with value 1 (see Section 3.6 of [RFC7641]);
      however, that can also be done with other methods, e.g., by
      sending a RST message.  This is out of scope for this
      specification.

4.1.3.5.2. Notifications
If the server accepts an Observe registration, a Partial IV MUST be included in all notifications (both successful and error), except for the first one where the Partial IV MAY be omitted. To protect against replay, the client SHALL maintain a Notification Number for each Observation it registers. The Notification Number is a non- negative integer containing the largest Partial IV of the received notifications for the associated Observe registration. Further details of replay protection of notifications are specified in Section 7.4.1. For notifications, the Inner Observe option value MUST be empty (see Section 3.2 of [RFC7252]). The Outer Observe option in a notification is needed for intermediary nodes to allow multiple responses to one request, and it MAY be set to the value of the Observe option in the original CoAP message. The client performs ordering of notifications and replay protection by comparing their Partial IVs and SHALL ignore the Outer Observe option value. If the client receives a response to an Observe request without an Inner Observe option, then it verifies the response as a non-Observe response, as specified in Section 8.4. If the client receives a response to a non-Observe request with an Inner Observe option, then it stops processing the message, as specified in Section 8.4. A client MUST consider the notification with the highest Partial IV as the freshest, regardless of the order of arrival. In order to support existing Observe implementations, the OSCORE client implementation MAY set the Observe option value to the three least significant bytes of the Partial IV. Implementations need to make sure that the notification without Partial IV is considered the oldest.
Top   ToC   RFC8613 - Page 24
4.1.3.6. No-Response
No-Response [RFC7967] is an optional feature used by the client to communicate its disinterest in certain classes of responses to a particular request. An implementation MAY support [RFC7252] and the OSCORE option without supporting [RFC7967]. If used, No-Response MUST be Inner. The Inner No-Response SHALL be processed by OSCORE as specified in Section 4.1.1. The Outer option SHOULD NOT be present. The server SHALL ignore the Outer No-Response option. The client MAY set the Outer No-Response value to 26 (suppress all known codes) if the Inner value is set to 26. The client MUST be prepared to receive and discard 5.04 (Gateway Timeout) error messages from intermediaries potentially resulting from destination time out due to no response.
4.1.3.7. OSCORE
The OSCORE option is only defined to be present in OSCORE messages as an indication that OSCORE processing has been performed. The content in the OSCORE option is neither encrypted nor integrity protected as a whole, but some part of the content of this option is protected (see Section 5.4). Nested use of OSCORE is not supported: If OSCORE processing detects an OSCORE option in the original CoAP message, then processing SHALL be stopped.

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). +------------------+---+---+ | 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) Figure 6: Protection of CoAP Header Fields and Payload
Top   ToC   RFC8613 - Page 25
   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; thus,
   they cannot, in general, be protected end-to-end from one endpoint to
   the other.  As mentioned in Section 1, OSCORE protects the CoAP
   request/response layer only and not the CoAP 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 it (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; thus, it is 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 it
   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: o To comply with [RFC8323], an initial empty Capabilities and Settings Message (CSM) SHALL be sent. The subsequent signaling message SHALL be protected.
Top   ToC   RFC8613 - Page 26
   o  Signaling messages SHALL be protected as CoAP request messages,
      except in the case in which the signaling message is a response to
      a previous signaling message; then 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.

   o  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).

   o  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. The COSE Object

This section defines how to use COSE [RFC8152] to wrap and protect data in the original message. OSCORE uses the untagged COSE_Encrypt0 structure (see Section 5.2 of [RFC8152]) with an AEAD algorithm. The AEAD key lengths, AEAD nonce length, and maximum Sender Sequence Number are algorithm dependent. The AEAD algorithm AES-CCM-16-64-128 defined in Section 10.2 of [RFC8152] is mandatory to implement. For AES-CCM-16-64-128, the length of Sender Key and Recipient Key is 128 bits; the length of AEAD nonce and Common IV is 13 bytes. The maximum Sender Sequence Number is specified in Section 12. As specified in [RFC5116], plaintext denotes the data that is to be encrypted and integrity protected, and Additional Authenticated Data (AAD) denotes the data that is to be integrity protected only. The COSE object SHALL be a COSE_Encrypt0 object with fields defined as follows: o The 'protected' field is empty. o The 'unprotected' field includes: * The 'Partial IV' parameter. The value is set to the Sender Sequence Number. All leading bytes of value zero SHALL be removed when encoding the Partial IV, except in the case of Partial IV value 0, which is encoded to the byte string 0x00.
Top   ToC   RFC8613 - Page 27
         This parameter SHALL be present in requests and will not
         typically be present in responses (for two exceptions, see
         Observe notifications (Section 4.1.3.5.2) and Replay Window
         synchronization (Appendix B.1.2)).

      *  The 'kid' parameter.  The value is set to the Sender ID.  This
         parameter SHALL be present in requests and will not typically
         be present in responses.  An example where the Sender ID is
         included in a response is the extension of OSCORE to group
         communication [Group-OSCORE].

      *  Optionally, a 'kid context' parameter (see Section 5.1).  This
         parameter MAY be present in requests and, if so, MUST contain
         an ID Context (see Section 3.1).  This parameter SHOULD NOT be
         present in responses: an example of how 'kid context' can be
         used in responses is given in Appendix B.2.  If 'kid context'
         is present in the request, then the server SHALL use a security
         context with that ID Context when verifying the request.

   o  The 'ciphertext' field is computed from the secret key (Sender Key
      or Recipient Key), AEAD nonce (see Section 5.2), plaintext (see
      Section 5.3), and the AAD (see Section 5.4) following Section 5.2
      of [RFC8152].

   The encryption process is described in Section 5.3 of [RFC8152].

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: o If the client has a unique identifier in some namespace, then that identifier can be used as ID Context. o The ID Context may be used to add randomness into new Sender and Recipient Contexts, see Appendix B.2. o In the case of group communication [Group-OSCORE], 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).
Top   ToC   RFC8613 - Page 28
   While 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    |    10  | bstr       |                | Identifies the  |
   | context  |        |            |                | context for the |
   |          |        |            |                | key identifier  |
   +----------+--------+------------+----------------+-----------------+

    Figure 7: Common Header Parameter 'kid context' for the COSE Object

   If ID Context is non-empty and the client sends a request without
   'kid context' resulting 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 [IV-GEN]. The detailed construction of the AEAD nonce is presented here (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
Top   ToC   RFC8613 - Page 29
   properties, see Section 7.4 and Appendix D.4.  Another non-Observe
   scenario where a Partial IV is 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                      |<---+
         +------------------------------------------------+

                      Figure 8: AEAD Nonce Formation

5.3. Plaintext

The plaintext is formatted as a CoAP message with a subset of the header (see Figure 9) consisting of: o the Code of the original CoAP message as defined in Section 3 of [RFC7252]; and o 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 from the previously included instance of Class E option; and o 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.
Top   ToC   RFC8613 - Page 30
      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)

                            Figure 9: Plaintext

5.4. Additional Authenticated Data

The external_aad SHALL be a CBOR array wrapped in a bstr object as defined below, following the notation of [RFC8610] as summarized in Appendix E: 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: o oscore_version: contains the OSCORE version number. Implementations of this specification MUST set this field to 1. Other values are reserved for future versions. o algorithms: contains (for extensibility) an array of algorithms, according to this specification only containing alg_aead. o alg_aead: contains the AEAD Algorithm from the security context used for the exchange (see Section 3.1). o request_kid: contains the value of the 'kid' in the COSE object of the request (see Section 5). o request_piv: contains the value of the 'Partial IV' in the COSE object of the request (see Section 5).
Top   ToC   RFC8613 - Page 31
   o  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 from the
      previously included instance of class I option.

   The oscore_version and algorithms parameters are established out-of-
   band; thus, they are not 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 AAD is composed from the external_aad as described in Section 5.3
   of [RFC8152] (the notation follows [RFC8610] as summarized in
   Appendix E):

      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:

   o  oscore_version: 0x01 (1 byte)

   o  algorithms: 0x810a (2 bytes)

   o  request_kid: 0x00 (1 byte)

   o  request_piv: 0x25 (1 byte)

   o  options: 0x (0 bytes)

   o  aad_array: 0x8501810a4100412540 (9 bytes)

   o  external_aad: 0x498501810a4100412540 (10 bytes)

   o  AAD: 0x8368456e63727970743040498501810a4100412540 (21 bytes)

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

6. OSCORE Header Compression

The Concise Binary Object Representation (CBOR) [RFC7049] combines very small message sizes with extensibility. The CBOR Object Signing and Encryption (COSE) [RFC8152] uses CBOR to create compact encoding of signed and encrypted data. However, COSE is constructed to
Top   ToC   RFC8613 - Page 32
   support a large number of different stateless use cases and is not
   fully optimized for use as a stateful security protocol, leading to a
   larger than necessary message expansion.  In this section, we define
   a stateless header compression mechanism, simply removing redundant
   information from the COSE objects, which significantly reduces the
   per-packet overhead.  The result of applying this mechanism to a COSE
   object is called the "compressed COSE object".

   The COSE_Encrypt0 object used in OSCORE is transported in the OSCORE
   option and in the Payload.  The Payload contains the ciphertext of
   the COSE object.  The headers of the COSE object are compactly
   encoded as described in the next section.

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) ... | +------------+----------------------+------------------+ Figure 10: The OSCORE Option Value o 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 '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).
Top   ToC   RFC8613 - Page 33
      *  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.

   o  The following n bytes encode the value of the Partial IV, if the
      Partial IV is present (n > 0).

   o  The following 1 byte encodes the length s of the 'kid context'
      (Section 5.1), if the 'kid context' flag is set (h = 1).

   o  The following s bytes encode the 'kid context', if the 'kid
      context' flag is set (h = 1).

   o  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 the case in which 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 additional parameters, as
   defined in the future documents registering those parameters.

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: the OSCORE option and payload.
Top   ToC   RFC8613 - Page 34
   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', 10:h'44616c656b' },
           h'aea0155667924dff8a24e4cb35b9',
         ]
Top   ToC   RFC8613 - Page 35
       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)


(next page on part 3)

Next Section