RFC 8613
Object Security for Constrained RESTful Environments (OSCORE)
7. Message Binding, Sequence Numbers, Freshness, and Replay Protection
7.1. Message Binding
In order to prevent response delay and mismatch attacks [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. Therefore, the server 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.2.1. Maximum Sequence Number
The maximum Sender Sequence Number is algorithm dependent (see Section 12) and SHALL be less than 2^40. If the Sender Sequence Number exceeds the maximum, the endpoint MUST NOT process any more messages with the given Sender Context. If necessary, the endpoint SHOULD acquire a new security context before this happens. The latter is out of scope of this document.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 [CoAP-ECHO-REQ-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 a 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 the Sender Sequence Number received in the 'Partial IV' parameter of the COSE object (see Section 6.1) has not been received before. If this verification fails, the server SHALL stop processing the message, and it 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 string "Replay detected". 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 equal the last received Partial IV + 1. However, in the 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 may 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. In this case the Partial IV is not used for replay protection of responses. The operation of validating the Partial IV and updating the replay protection MUST be atomic.7.4.1. Replay Protection of Notifications
The following applies additionally when the Observe option is supported. The Notification Number (see Section 4.1.3.5.2) is initialized to the Partial IV of the first successfully verified notification in response to the registration request. A client MUST only accept at most one Observe notification without Partial IV, and treat it as the oldest notification received. A client receiving a notification containing a Partial IV SHALL compare the Partial IV with the Notification Number associated to that Observe registration. The client MUST stop processing notifications with a Partial IV that has
been previously received. Applications MAY decide that a client only processes notifications that have a greater Partial IV than the Notification Number. If the verification of the response succeeds, and the received Partial IV was greater than the Notification Number, then the client SHALL overwrite the corresponding Notification Number with the received Partial IV.7.5. Losing Part of the Context State
To prevent reuse of an AEAD nonce with the same AEAD key or the acceptance of 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 a fresh security context after loss of mutable security context data. Examples are given based on careful use of nonvolatile memory, see Appendix B.1.1 and the use of the Echo option, see Appendix B.1.2. If an endpoint makes use of a partial security context stored in nonvolatile 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 [OSCORE-PROFILE]. This requires the execution of a 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. Processing
This section describes the OSCORE message processing. Additional processing for Observe or Block-wise are described in subsections. Note that, analogously to [RFC7252] where the Token and source/ destination pair are used to match a response with a request, both endpoints MUST keep the association (Token, {Security Context, Partial IV of the request}), in order to be able to find the Security Context and compute the AAD to protect or verify the response. The association MAY be forgotten after it has been used to successfully protect or verify the response, with the exception of Observe processing, where the association MUST be kept as long as the Observation is active. The processing of the Sender Sequence Number follows the procedure described in Section 3 of [IV-GEN].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 AAD 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. Note that the Recipient Context MAY be retrieved by deriving a new security context, e.g. as described in Appendix B.2. 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 AAD, as described in Section 5.4. 5. Compute the AEAD nonce from the Recipient ID, Common IV, and the Partial IV, received in the COSE object.
6. Decrypt the COSE object using the Recipient Key, as per
Section 5.3 of [RFC8152]. (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 string
"Decryption failed".
* 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.2.1. Supporting Block-wise
If Block-wise is supported, insert the following step before any
other:
A. If Block-wise is present in the request, then process the Outer
Block options according to [RFC7959], until all blocks of the request
have been received (see Section 4.1.3.4).
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 AAD 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.3.1. Supporting Observe
If Observe is supported, insert the following step between steps 2
and 3 of Section 8.3:
A. If the response is an Observe notification:
o If the response is the first notification:
* 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.
Then, go to 4.
o If the response is not the first notification:
* 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, then go to 4.
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 AAD, 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, received in the COSE object. 5. Decrypt the COSE object using the Recipient Key, as per Section 5.3 of [RFC8152]. (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.8.4.1. Supporting Block-wise
If Block-wise is supported, insert the following step before any other: A. If Block-wise is present in the response, then process the Outer Block options according to [RFC7959], until all blocks of the response have been received (see Section 4.1.3.4).
8.4.2. Supporting Observe
If Observe is supported: Insert the following step between step 5 and step 6: A. If the request was an Observe registration, then: o If the Partial IV is not present in the response, and the Inner Observe option is present, and the AEAD nonce from the request was already used once, then go to 8. o If the Partial IV is present in the response and the Inner Observe option is present, then follow the processing described in Section 4.1.3.5.2 and Section 7.4.1, then: * initialize the Notification Number (if first successfully verified notification), or * overwrite the Notification Number (if the received Partial IV was greater than the Notification Number). Replace step 8 of Section 8.4 with: B. In case any of the previous erroneous conditions apply: the client SHALL stop processing the response. An error condition occurring while processing a response to an observation request does not cancel the observation. A client MUST NOT react to failure by re-registering the observation immediately.9. Web Linking
The use of OSCORE MAY be indicated by a target "osc" attribute in a web link [RFC8288] to a resource, e.g., using a link-format document [RFC6690] if the resource is accessible over CoAP. The "osc" attribute is a hint indicating that the destination of that link is only accessible using OSCORE, and unprotected access to it is not supported. Note that this is simply a hint, it does not include any security context material or any other information required to run OSCORE. A value MUST NOT be given for the "osc" attribute; any present value MUST be ignored by parsers. The "osc" attribute MUST NOT appear more than once in a given link-value; occurrences after the first MUST be ignored by parsers.
The example in Figure 11 shows a use of the "osc" attribute: the client does resource discovery on a server and gets back a list of resources, one of which includes the "osc" attribute indicating that the resource is protected with OSCORE. The link-format notation (see Section 5 of [RFC6690]) is used. REQ: GET /.well-known/core RES: 2.05 Content </sensors/temp>;osc, </sensors/light>;if="sensor" Figure 11: The Web Link10. CoAP-to-CoAP Forwarding Proxy
CoAP is designed for proxy operations (see Section 5.7 of [RFC7252]). OSCORE is designed to work with OSCORE-unaware CoAP proxies. Security requirements for forwarding are listed in Section 2.2.1 of [CoAP-E2E-Sec]. Proxy processing of the (Outer) Proxy-Uri option works as defined in [RFC7252]. Proxy processing of the (Outer) Block options works as defined in [RFC7959]. However, not all CoAP proxy operations are useful: o Since a CoAP response is only applicable to the original CoAP request, caching is in general not useful. In support of existing proxies, OSCORE uses the Outer Max-Age option, see Section 4.1.3.1. o Proxy processing of the (Outer) Observe option as defined in [RFC7641] is specified in Section 4.1.3.5. Optionally, a CoAP proxy MAY detect OSCORE and act accordingly. An OSCORE-aware CoAP proxy: o SHALL bypass caching for the request if the OSCORE option is present. o SHOULD avoid caching responses to requests with an OSCORE option. In the case of Observe (see Section 4.1.3.5), the OSCORE-aware CoAP proxy: o SHALL NOT initiate an Observe registration.
o MAY verify the order of notifications using Partial IV rather than
the Observe option.
11. HTTP Operations
The CoAP request/response model may be mapped to HTTP and vice versa
as described in Section 10 of [RFC7252]. The HTTP-CoAP mapping is
further detailed in [RFC8075]. This section defines the components
needed to map and transport OSCORE messages over HTTP hops. By
mapping between HTTP and CoAP and by using cross-protocol proxies,
OSCORE may be used end-to-end between, e.g., an HTTP client and a
CoAP server. Examples are provided in Sections 11.5 and 11.6.
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
responses with HTTP Status Code 200 (OK). 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 are 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]).
In general, intermediaries are not allowed to insert, delete, or modify the OSCORE header. In general, changes to the HTTP OSCORE header field will violate the integrity of the OSCORE message resulting in an error. For the same reason the HTTP OSCORE header field is generally 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 redirects, such conditions include: o the CoAP-to-HTTP proxy follows the redirect, instead of the CoAP client as in the HTTP case. o the CoAP-to-HTTP proxy copies the HTTP OSCORE header field and body to the new request. o the target of the redirect has the necessary OSCORE security context required to decrypt and verify the message. Since OSCORE requires the HTTP body to be preserved across redirects, the HTTP server is RECOMMENDED to reply with 307 (Temporary Redirect) or 308 (Permanent Redirect) instead of 301 (Moved Permanently) or 302 (Found). For the case of HTTP-client-to-CoAP-server redirects, 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 as follows: o 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]. o 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 as follows. o 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]. o 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 gives an example of what 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 (OK) in the next-to-last message is the mapping of CoAP Code 2.04 (Changed), whereas the HTTP Status Code 200 (OK) 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 gives an example of what 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 (OK), 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.
(page 51 continued on part 4)
