draft-ietf-core-object-security-04.txt   draft-ietf-core-object-security-05.txt 
CoRE Working Group G. Selander CoRE Working Group G. Selander
Internet-Draft J. Mattsson Internet-Draft J. Mattsson
Intended status: Standards Track F. Palombini Intended status: Standards Track F. Palombini
Expires: January 2, 2018 Ericsson AB Expires: April 2, 2018 Ericsson AB
L. Seitz L. Seitz
SICS Swedish ICT SICS Swedish ICT
July 01, 2017 September 29, 2017
Object Security of CoAP (OSCOAP) Object Security for Constrained RESTful Environments (OSCORE)
draft-ietf-core-object-security-04 draft-ietf-core-object-security-05
Abstract Abstract
This document defines Object Security of CoAP (OSCOAP), a method for This document defines Object Security for Constrained RESTful
application layer protection of the Constrained Application Protocol Environments (OSCORE), a method for application-layer protection of
(CoAP), using the CBOR Object Signing and Encryption (COSE). OSCOAP the Constrained Application Protocol (CoAP), using CBOR Object
provides end-to-end encryption, integrity and replay protection to Signing and Encryption (COSE). OSCORE provides end-to-end
CoAP payload, options, and header fields, as well as a secure message encryption, integrity and replay protection, as well as a secure
binding. OSCOAP is designed for constrained nodes and networks and message binding. OSCORE is designed for constrained nodes and
can be used across intermediaries and over any layer. The use of networks and can be used over any layer and across intermediaries,
OSCOAP is signaled with the CoAP option Object-Security, also defined and also with HTTP. OSCORE may be used to protect group
in this document. communications as is specified in a separate draft.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 2, 2018. This Internet-Draft will expire on April 2, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2017 IETF Trust and the persons identified as the Copyright (c) 2017 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5
2. The Object-Security Option . . . . . . . . . . . . . . . . . 5 2. The CoAP Object-Security Option . . . . . . . . . . . . . . . 5
3. The Security Context . . . . . . . . . . . . . . . . . . . . 6 3. The Security Context . . . . . . . . . . . . . . . . . . . . 6
3.1. Security Context Definition . . . . . . . . . . . . . . . 6 3.1. Security Context Definition . . . . . . . . . . . . . . . 6
3.2. Derivation of Security Context Parameters . . . . . . . . 9 3.2. Establishment of Security Context Parameters . . . . . . 8
3.3. Requirements on the Security Context Parameters . . . . . 10 3.3. Requirements on the Security Context Parameters . . . . . 10
4. Protected CoAP Message Fields . . . . . . . . . . . . . . . . 11 4. Protected Message Fields . . . . . . . . . . . . . . . . . . 11
4.1. CoAP Payload . . . . . . . . . . . . . . . . . . . . . . 12 4.1. CoAP Payload . . . . . . . . . . . . . . . . . . . . . . 12
4.2. CoAP Header . . . . . . . . . . . . . . . . . . . . . . . 12 4.2. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 12
4.3. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 12 4.3. CoAP Header . . . . . . . . . . . . . . . . . . . . . . . 18
5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 18 5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 19
5.1. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 19 5.1. Nonce . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.2. Additional Authenticated Data . . . . . . . . . . . . . . 19 5.2. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 20
6. Sequence Numbers, Replay, Message Binding, and Freshness . . 20 5.3. Additional Authenticated Data . . . . . . . . . . . . . . 21
6.1. AEAD Nonce Uniqueness . . . . . . . . . . . . . . . . . . 20 6. Sequence Numbers, Replay, Message Binding, and Freshness . . 22
6.2. Replay Protection . . . . . . . . . . . . . . . . . . . . 21 6.1. Message Binding . . . . . . . . . . . . . . . . . . . . . 22
6.3. Sequence Number and Replay Window State . . . . . . . . . 21 6.2. AEAD Nonce Uniqueness . . . . . . . . . . . . . . . . . . 22
6.4. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 23 6.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 22
6.5. Delay and Mismatch Attacks . . . . . . . . . . . . . . . 23 6.4. Replay Protection . . . . . . . . . . . . . . . . . . . . 23
7. Processing . . . . . . . . . . . . . . . . . . . . . . . . . 23 6.5. Losing Part of the Context State . . . . . . . . . . . . 23
7.1. Protecting the Request . . . . . . . . . . . . . . . . . 23 7. Processing . . . . . . . . . . . . . . . . . . . . . . . . . 24
7.2. Verifying the Request . . . . . . . . . . . . . . . . . . 24 7.1. Protecting the Request . . . . . . . . . . . . . . . . . 24
7.3. Protecting the Response . . . . . . . . . . . . . . . . . 25 7.2. Verifying the Request . . . . . . . . . . . . . . . . . . 25
7.4. Verifying the Response . . . . . . . . . . . . . . . . . 26 7.3. Protecting the Response . . . . . . . . . . . . . . . . . 26
8. OSCOAP Compression . . . . . . . . . . . . . . . . . . . . . 27 7.4. Verifying the Response . . . . . . . . . . . . . . . . . 27
8.1. Encoding of the Object-Security Option . . . . . . . . . 27 8. OSCORE Compression . . . . . . . . . . . . . . . . . . . . . 28
8.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . 28 8.1. Encoding of the Object-Security Value . . . . . . . . . . 28
9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 29 8.2. Encoding of the OSCORE Payload . . . . . . . . . . . . . 29
10. Security Considerations . . . . . . . . . . . . . . . . . . . 30 8.3. Context Hint . . . . . . . . . . . . . . . . . . . . . . 30
11. Privacy Considerations . . . . . . . . . . . . . . . . . . . 32 8.4. Compression Examples . . . . . . . . . . . . . . . . . . 30
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 32
12.1. CoAP Option Numbers Registry . . . . . . . . . . . . . . 32 10. Proxy Operations . . . . . . . . . . . . . . . . . . . . . . 32
12.2. Media Type Registrations . . . . . . . . . . . . . . . . 32 10.1. CoAP-to-CoAP Forwarding Proxy . . . . . . . . . . . . . 33
12.3. CoAP Content Format Registration . . . . . . . . . . . . 33 10.2. HTTP-to-CoAP Translation Proxy . . . . . . . . . . . . . 33
13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 34 10.3. CoAP-to-HTTP Translation Proxy . . . . . . . . . . . . . 34
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 34 11. Security Considerations . . . . . . . . . . . . . . . . . . . 35
14.1. Normative References . . . . . . . . . . . . . . . . . . 34 12. Privacy Considerations . . . . . . . . . . . . . . . . . . . 37
14.2. Informative References . . . . . . . . . . . . . . . . . 35 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38
Appendix A. Test Vectors . . . . . . . . . . . . . . . . . . . . 36 13.1. CoAP Option Numbers Registry . . . . . . . . . . . . . . 38
Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 36 13.2. Header Field Registrations . . . . . . . . . . . . . . . 38
B.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 36 14. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 38
B.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 37 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 38
Appendix C. Object Security of Content (OSCON) . . . . . . . . . 39 15.1. Normative References . . . . . . . . . . . . . . . . . . 38
C.1. Overhead OSCON . . . . . . . . . . . . . . . . . . . . . 40 15.2. Informative References . . . . . . . . . . . . . . . . . 40
C.2. MAC Only . . . . . . . . . . . . . . . . . . . . . . . . 41 Appendix A. Test Vectors . . . . . . . . . . . . . . . . . . . . 41
C.3. Signature Only . . . . . . . . . . . . . . . . . . . . . 41 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 41
C.4. Authenticated Encryption with Additional Data (AEAD) . . 42 B.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 41
C.5. Symmetric Encryption with Asymmetric Signature (SEAS) . . 43 B.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 42
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 43 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 44
1. Introduction 1. Introduction
The Constrained Application Protocol (CoAP) is a web application The Constrained Application Protocol (CoAP) is a web application
protocol, designed for constrained nodes and networks [RFC7228]. protocol, designed for constrained nodes and networks [RFC7228].
CoAP specifies the use of proxies for scalability and efficiency. At CoAP specifies the use of proxies for scalability and efficiency, and
the same time CoAP [RFC7252] references DTLS [RFC6347] for security. a mapping to HTTP is also specified [RFC8075]. CoAP [RFC7252]
Proxy operations on CoAP messages require DTLS to be terminated at references DTLS [RFC6347] for security. CoAP and HTTP proxies
the proxy. The proxy therefore not only has access to the data require (D)TLS to be terminated at the proxy. The proxy therefore
required for performing the intended proxy functionality, but is also not only has access to the data required for performing the intended
able to eavesdrop on, or manipulate any part of the CoAP payload and proxy functionality, but is also able to eavesdrop on, or manipulate
metadata, in transit between client and server. The proxy can also any part of the message payload and metadata, in transit between the
inject, delete, or reorder packages since they are no longer endpoints. The proxy can also inject, delete, or reorder packets
protected by DTLS. since they are no longer protected by (D)TLS.
This document defines Object Security of CoAP (OSCOAP), a data object This document defines the Object Security for Constrained RESTful
based security protocol, protecting CoAP message exchanges end-to- Environments (OSCORE) security protocol, protecting CoAP and CoAP-
end, across intermediary nodes. An analysis of end-to-end security mappable HTTP requests and responses end-to-end across intermediary
for CoAP messages through intermediary nodes is performed in nodes such as CoAP forward proxies and cross-protocol translators
[I-D.hartke-core-e2e-security-reqs], this specification addresses the including HTTP-to-CoAP proxies [RFC8075]. In addition to the core
forwarding case. In addition to the core features defined in CoAP features defined in [RFC7252], OSCORE supports Observe [RFC7641]
[RFC7252], OSCOAP supports Observe [RFC7641] and Blockwise [RFC7959]. and Blockwise [RFC7959]. An analysis of end-to-end security for CoAP
messages through some types of intermediary nodes is performed in
[I-D.hartke-core-e2e-security-reqs]. OSCORE protects the Request/
Response layer only, and not the CoAP Messaging Layer (Section 2 of
[RFC7252]). Therefore, all the CoAP messages mentioned in this
document refer to non-empty CON, NON, and ACK messages.
Additionally, since the message formats for CoAP over unreliable
transport [RFC7252] and for CoAP over reliable transport
[I-D.ietf-core-coap-tcp-tls] differ only in terms of Messaging Layer,
OSCORE can be applied to both unreliable and reliable transports.
OSCOAP is designed for constrained nodes and networks and provides an OSCORE is designed for constrained nodes and networks and provides an
in-layer security protocol for CoAP which does not depend on in-layer security protocol that does not depend on underlying layers.
underlying layers. OSCOAP can be used anywhere that CoAP can be OSCORE can be used anywhere where CoAP or HTTP can be used, including
used, including unreliable transport [RFC7228], reliable transport non-IP transports (e.g., [I-D.bormann-6lo-coap-802-15-ie]). An
[I-D.ietf-core-coap-tcp-tls], and non-IP transport extension of OSCORE may also be used to protect group communication
[I-D.bormann-6lo-coap-802-15-ie]. OSCOAP may also be used to protect for CoAP [I-D.tiloca-core-multicast-oscoap]. The use of OSCORE does
group communication for CoAP [I-D.tiloca-core-multicast-oscoap]. The not affect the URI scheme and OSCORE can therefore be used with any
use of OSCOAP does not affect the URI scheme and OSCOAP can therefore URI scheme defined for CoAP or HTTP. The application decides the
be used with any URI scheme defined for CoAP. The application conditions for which OSCORE is required.
decides the conditions for which OSCOAP is required.
OSCOAP builds on CBOR Object Signing and Encryption (COSE) OSCORE builds on CBOR Object Signing and Encryption (COSE) [RFC8152],
[I-D.ietf-cose-msg], providing end-to-end encryption, integrity, providing end-to-end encryption, integrity, replay protection, and
replay protection, and secure message binding. A compressed version secure message binding. A compressed version of COSE is used, as
of COSE is used, see Section 8. The use of OSCOAP is signaled with discussed in Section 8. The use of OSCORE is signaled with the
the CoAP option Object-Security, defined in Section 2. OSCOAP Object-Security CoAP option or HTTP header, defined in Section 2 and
provides protection of CoAP payload, certain options, and header Section 10.2. OSCORE is designed to protect as much information as
fields. The solution transforms a CoAP message into an "OSCOAP possible, while still allowing proxy operations (Section 10). OSCORE
message" before sending, and vice versa after receiving. The OSCOAP provides protection of message payload, almost all CoAP options, and
message is a CoAP message related to the original CoAP message in the the RESTful method. The solution transforms a message into an
following way: the original CoAP message is protected by including "OSCORE message" before sending, and vice versa after receiving. The
payload (if present), certain options, and header fields in a COSE OSCORE message is related to the original message in the following
object. The message fields that have been encrypted are removed from way: the original message is translated to CoAP (if not already in
the message whereas the Object-Security option and the compressed CoAP) and the resulting message payload (if present), options not
COSE object are added, see Figure 1. processed by a proxy, and the request/response method (CoAP Code) are
protected in a COSE object. The message fields of the original
messages that are encrypted are not present in the OSCORE message,
and instead the Object-Security option/header and the compressed COSE
object are included, see Figure 1.
Client Server Client Server
| OSCOAP request: | | OSCORE request - POST example.com: |
| GET example.com | | Header, Token, |
| [Header, Token, Options:{..., | | Options: {Object-Security, ...}, |
| Object-Security:COSE object}] | | Payload: Compressed COSE object |
+---------------------------------------------->| +--------------------------------------------->|
| OSCOAP response: | | OSCORE response - 2.04 (Changed): |
| 2.05 (Content) | | Header, Token, |
| [Header, Token, Options:{..., | | Options: {Object-Security, ...}, |
| Object-Security:-}, Payload:COSE object] | | Payload: Compressed COSE object |
|<----------------------------------------------+ |<---------------------------------------------+
| | | |
Figure 1: Sketch of OSCOAP Figure 1: Sketch of OSCORE with CoAP
OSCOAP may be used in very constrained settings, thanks to its small OSCORE may be used in very constrained settings, thanks to its small
message size, its restricted code and memory requirements, and is message size and the restricted code and memory requirements in
independent of underlying layer below CoAP. OSCOAP can be combined addition to what is required by CoAP. OSCORE can be combined with
with DTLS, thereby enabling end-to-end security of e.g. CoAP payload transport layer security such as DTLS or TLS, thereby enabling end-
and options, in combination with hop-by-hop protection of the entire to-end security of e.g. CoAP Payload, Options and Code, in
CoAP message, during transport between end-point and intermediary combination with hop-by-hop protection of the Messaging Layer, during
node. Examples of the use of OSCOAP are given in Appendix B. transport between end-point and intermediary node. Examples of the
use of OSCORE are given in Appendix B.
The message protection provided by OSCOAP can alternatively be An implementation supporting this specification MAY only implement
applied only to the payload of individual messages. We call this the client part, MAY only implement the server part, or MAY only
object security of content (OSCON), which is defined in Appendix C. implement one of the proxy parts. OSCORE is designed to work with
legacy CoAP-to-CoAP forward proxies [RFC7252], but an OSCORE-aware
proxy will be more efficient. HTTP-to-CoAP proxies [RFC8075] and
CoAP-to-HTTP proxies need to implement respective parts of this
specification to work with OSCORE (see Section 10).
1.1. Terminology 1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. These document are to be interpreted as described in [RFC2119]. These
words may also appear in this document in lowercase, absent their words may also appear in this document in lowercase, absent their
normative meanings. normative meanings.
Readers are expected to be familiar with the terms and concepts Readers are expected to be familiar with the terms and concepts
described in CoAP [RFC7252], Observe [RFC7641], Blockwise [RFC7959], described in CoAP [RFC7252], Observe [RFC7641], Blockwise [RFC7959],
COSE [I-D.ietf-cose-msg], CBOR [RFC7049], CDDL COSE [RFC8152], CBOR [RFC7049], CDDL
[I-D.greevenbosch-appsawg-cbor-cddl], and constrained environments [I-D.greevenbosch-appsawg-cbor-cddl], and constrained environments
[RFC7228]. [RFC7228].
The terms Common/Sender/Recipient Context, Master Secret/Salt, Sender The terms Common/Sender/Recipient Context, Master Secret/Salt, Sender
ID/Key/IV, Recepient ID/Key/IV and Context IV are defined in ID/Key, Recipient ID/Key, and Common IV are defined in Section 3.1.
Section 3.1.
2. The Object-Security Option 2. The CoAP Object-Security Option
The Object-Security option (see Figure 2) indicates that OSCOAP is The CoAP Object-Security option (see Figure 2) indicates that the
used to protect the CoAP message exchange. The Object-Security CoAP message is an OSCORE message and that it contains a compressed
option is critical, safe to forward, part of the cache key, not COSE object (see Section 5 and Section 8). The Object-Security
repeatable, and opaque. option is critical, safe to forward, part of the cache key, and not
repeatable.
+-----+---+---+---+---+-----------------+--------+--------+ +-----+---+---+---+---+-----------------+-----------+--------+---------+
| No. | C | U | N | R | Name | Format | Length | | No. | C | U | N | R | Name | Format | Length | Default |
+-----+---+---+---+---+-----------------+--------+--------| +-----+---+---+---+---+-----------------+-----------+--------+---------+
| TBD | x | | | | Object-Security | opaque | 0- | | TBD | x | | | | Object-Security | see below | 0-255 | (none) |
+-----+---+---+---+---+-----------------+--------+--------+ +-----+---+---+---+---+-----------------+-----------+--------+---------+
C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable C = Critical, U = Unsafe, N = NoCacheKey, R = Repeatable
Figure 2: The Object-Security Option Figure 2: The Object-Security Option
A successful response to a request with the Object-Security option The Object-Security option contains the OSCORE flag byte and for
SHALL contain the Object-Security option. A CoAP endpoint SHOULD NOT requests, the Sender ID (see Section 8). If the flag byte is all
cache a response to a request with an Object-Security option, since zero (0x00) the Option value SHALL be empty (Option Length = 0). An
the response is only applicable to the original client's request. endpoint receiving a CoAP message without payload, that also contains
The Object-Security option is included in the cache key for backward an Object-Security option SHALL treat it as malformed and reject it.
compatibility with proxies not recognizing the Object-Security
option. The effect is that messages with the Object-Security option
will never generate cache hits. For Max-Age processing, see
Section 4.3.1.1.
The protection is achieved by means of a COSE object (see Section 5),
which is compressed and then included in the OSCOAP message. The
placement of the COSE object depends on whether the method/response
code allows payload (see [RFC7252]):
o If the method/response code allows payload, then the compressed A successful response to a request with the Object-Security option
COSE object Section 8 is the payload of the OSCOAP message, and SHALL contain the Object-Security option. Whether error responses
the Object-Security option has length zero. An endpoint receiving contain the Object-Security option depends on the error type (see
a CoAP message with payload, that also contains a non-empty Section 7).
Object-Security option SHALL treat it as malformed and reject it.
o If the method/response code does not allow payload, then the Since the payload and most options are encrypted Section 4, and the
compressed COSE object Section 8 is the value of the Object- corresponding plain text message fields of the original are not
Security option and the length of the Object-Security option is included in the OSCORE message, the processing of these fields does
equal to the size of the compressed COSE object. An endpoint not expand the total message size.
receiving a CoAP message without payload, that also contains an
empty Object-Security option SHALL treat it as malformed and
reject it.
The size of the COSE object depends on whether the method/response A CoAP proxy SHOULD NOT cache a response to a request with an Object-
code allows payload, if the message is a request or response, on the Security option, since the response is only applicable to the
set of options that are included in the original message, the AEAD original client's request, see Section 10.1. As the compressed COSE
algorithm, the length of the information identifying the security Object is included in the cache key, messages with the Object-
context, and the length of the sequence number. Security option will never generate cache hits. For Max-Age
processing, see Section 4.2.3.1.
3. The Security Context 3. The Security Context
OSCOAP uses COSE with an Authenticated Encryption with Additional OSCORE requires that client and server establish a shared security
Data (AEAD) algorithm between a CoAP client and a CoAP server. An context used to process the COSE objects. OSCORE uses COSE with an
implementation supporting this specification MAY only implement the Authenticated Encryption with Additional Data (AEAD) algorithm for
client part or MAY only implement the server part. protecting message data between a client and a server. In this
section, we define the security context and how it is derived in
This specification requires that client and server establish a client and server based on a common shared master secret and a key
security context to apply to the COSE objects protecting the CoAP derivation function (KDF).
messages. In this section we define the security context, and also
specify how to derive the initial security contexts in client and
server based on common shared secret and a key derivation function
(KDF).
3.1. Security Context Definition 3.1. Security Context Definition
The security context is the set of information elements necessary to The security context is the set of information elements necessary to
carry out the cryptographic operations in OSCOAP. For each endpoint, carry out the cryptographic operations in OSCORE. For each endpoint,
the security context is composed of a "Common Context", a "Sender the security context is composed of a "Common Context", a "Sender
Context", and a "Recipient Context". Context", and a "Recipient Context".
The endpoints protect messages to send using the Sender Context and The endpoints protect messages to send using the Sender Context and
verify messages received using the Recipient Context, both contexts verify messages received using the Recipient Context, both contexts
being derived from the Common Context and other data. Clients need being derived from the Common Context and other data. Clients and
to be able to retrieve the correct security context to use. 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, An endpoint uses its Sender ID (SID) to derive its Sender Context,
and the other endpoint uses the same ID, now called Recipient ID and the other endpoint uses the same ID, now called Recipient ID
(RID), to derive its Recipient Context. In communication between two (RID), to derive its Recipient Context. In communication between two
endpoints, the Sender Context of one endpoint matches the Recipient endpoints, the Sender Context of one endpoint matches the Recipient
Context of the other endpoint, and vice versa. Thus the two security Context of the other endpoint, and vice versa. Thus, the two
contexts identified by the same IDs in the two endpoints are not the security contexts identified by the same IDs in the two endpoints are
same, but they are partly mirrored. Retrieval and use of the not the same, but they are partly mirrored. Retrieval and use of the
security context are shown in Figure 3. security context are shown in Figure 3.
.------------. .------------. .-------------. .-------------.
| Common, | | Common, | | Common, | | Common, |
| Sender, | | Recipient,| | Sender, | | Recipient, |
| Recipient | | Sender | | Recipient | | Sender |
'------------' '------------' '-------------' '-------------'
Client Server Client Server
| | | |
Retrieve context for | OSCOAP request: | Retrieve context for | OSCORE request: |
target resource | [Token = Token1, | target resource | Token = Token1, |
Protect request with | kid = SID, ...] | Protect request with | kid = SID, ... |
Sender Context +---------------------->| Retrieve context with Sender Context +---------------------->| Retrieve context with
| | RID = kid | | RID = kid
| | Verify request with | | Verify request with
| | Recipient Context | | Recipient Context
| OSCOAP response: | Protect response with | OSCORE response: | Protect response with
| [Token = Token1, ...] | Sender Context | Token = Token1, ... | Sender Context
Retrieve context with |<----------------------+ Retrieve context with |<----------------------+
Token = Token1 | | Token = Token1 | |
Verify request with | | Verify request with | |
Recipient Context | | Recipient Context | |
Figure 3: Retrieval and use of the Security Context Figure 3: Retrieval and use of the Security Context
The Common Context contains the following parameters: The Common Context contains the following parameters:
o Algorithm (Alg). Value that identifies the COSE AEAD algorithm to o AEAD Algorithm (alg). The COSE AEAD algorithm to use for
use for encryption. Its value is immutable once the security encryption. Its value is immutable once the security context is
context is established. established.
o Key Derivation Function. The HMAC based HKDF [RFC5869] used to
derive Sender Key, Recipient Key, and Common IV.
o Master Secret. Variable length, uniformly random byte string o Master Secret. Variable length, uniformly random byte string
containing the key used to derive traffic keys and IVs. Its value containing the key used to derive traffic keys and IVs. Its value
is immutable once the security context is established. is immutable once the security context is established.
o Master Salt (OPTIONAL). Variable length byte string containing o Master Salt (OPTIONAL). Variable length byte string containing
the salt used to derive traffic keys and IVs. Its value is the salt used to derive traffic keys and IVs. Its value is
immutable once the security context is established. immutable once the security context is established.
o Common IV. Byte string derived from Master Secret and Master
Salt. Length is determined by the AEAD Algorithm. Its value is
immutable once the security context is established.
The Sender Context contains the following parameters: The Sender Context contains the following parameters:
o Sender ID. Variable length byte string identifying the Sender o Sender ID. Non-negative integer used to identify the Sender
Context. Its value is immutable once the security context is Context and to assure unique nonces. Length is determined by the
established. AEAD Algorithm. Its value is immutable once the security context
is established.
o Sender Key. Byte string containing the symmetric key to protect o Sender Key. Byte string containing the symmetric key to protect
messages to send. Derived from Common Context and Sender ID. messages to send. Derived from Common Context and Sender ID.
Length is determined by Algorithm. Its value is immutable once Length is determined by the AEAD Algorithm. Its value is
the security context is established. immutable once the security context is established.
o Sender IV. Byte string containing the IV to protect messages to
send. Derived from Common Context and Sender ID. Length is
determined by Algorithm. Its value is immutable once the security
context is established.
o Sequence Number. Non-negative integer used to protect requests o Sender Sequence Number. Non-negative integer used by the sender
and observe responses to send. Used as partial IV to protect requests and Observe notifications. Used as "Partial
[I-D.ietf-cose-msg] to generate unique nonces for the AEAD. IV" [RFC8152] to generate unique nonces for the AEAD. Maximum
Maximum value is determined by Algorithm. value is determined by the AEAD Algorithm.
The Recipient Context contains the following parameters: The Recipient Context contains the following parameters:
o Recipient ID. Variable length byte string identifying the o Recipient ID. Non-negative integer used to identify the Recipient
Recipient Context. Its value is immutable once the security Context and to assure unique nonces. Length is determined by the
context is established. AEAD Algorithm. Its value is immutable once the security context
is established.
o Recipient Key. Byte string containing the symmetric key to verify o Recipient Key. Byte string containing the symmetric key to verify
messages received. Derived from Common Context and Recipient ID. messages received. Derived from Common Context and Recipient ID.
Length is determined by the Algorithm. Its value is immutable Length is determined by the AEAD Algorithm. Its value is
once the security context is established. immutable once the security context is established.
o Recipient IV. Byte string containing the IV to verify messages
received. Derived from Common Context and Recipient ID. Length
is determined by Algorithm. Its value is immutable once the
security context is established.
o Replay Window. The replay window to verify requests and observe
responses received.
When it is understood which context is referred to (Sender Context or o Replay Window (Server only). The replay window to verify requests
Recipient Context), the term "Context IV" is used to denote the IV received.
currently used with this context.
An endpoint may free up memory by not storing the Sender Key, Sender An endpoint may free up memory by not storing the Common IV, Sender
IV, Recipient Key, and Recipient IV, deriving them from the Common Key, and Recipient Key, deriving them from the Master Key and Master
Context when needed. Alternatively, an endpoint may free up memory Salt when needed. Alternatively, an endpoint may free up memory by
by not storing the Master Secret and Master Salt after the other not storing the Master Secret and Master Salt after the other
parameters have been derived. parameters have been derived.
The endpoints MAY interchange the client and server roles while The endpoints MAY interchange the client and server roles while
maintaining the same security context. When this happens, the former maintaining the same security context. When this happens, the former
server still protects messages to send using its Sender Context, and server still protects messages to send using its Sender Context, and
verifies messages received using its Recipient Context. The same is verifies messages received using its Recipient Context. The same is
also true for the former client. The endpoints MUST NOT change the also true for the former client. The endpoints MUST NOT change the
Sender/Recipient ID. In other words, changing the roles does not Sender/Recipient ID when changing roles. In other words, changing
change the set of keys to be used. the roles does not change the set of keys to be used.
3.2. Derivation of Security Context Parameters 3.2. Establishment of Security Context Parameters
The parameters in the security context are derived from a small set The parameters in the security context are derived from a small set
of input parameters. The following input parameters SHALL be pre- of input parameters. The following input parameters SHALL be pre-
established: established:
o Master Secret o Master Secret
o Sender ID o Sender ID
o Recipient ID o Recipient ID
The following input parameters MAY be pre-established. In case any The following input parameters MAY be pre-established. In case any
of these parameters is not pre-established, the default value of these parameters is not pre-established, the default value
indicated below is used: indicated below is used:
o AEAD Algorithm (Alg) o AEAD Algorithm (alg)
* Default is AES-CCM-64-64-128 (COSE abbreviation: 12) * Default is AES-CCM-16-64-128 (COSE algorithm encoding: 10)
o Master Salt o Master Salt
* Default is the empty string * Default is the empty string
o Key Derivation Function (KDF) o Key Derivation Function (KDF)
* Default is HKDF SHA-256 * Default is HKDF SHA-256
o Replay Window Type and Size o Replay Window Type and Size
* Default is DTLS-type replay protection with a window size of 32 * Default is DTLS-type replay protection with a window size of 32
([RFC6347])
How the input parameters are pre-established, is application All input parameters need to be known to and agreed on by both
specific. The EDHOC protocol [I-D.selander-ace-cose-ecdhe] enables endpoints, but the replay window may be different in the two
the establishment of input parameters with the property of forward endpoints. The replay window type and size is used by the client in
secrecy and negotiation of KDF and AEAD, it thus provides all the processing of the Request-Tag
necessary pre-requisite steps for using OSCOAP as defined here. [I-D.amsuess-core-repeat-request-tag]. How the input parameters are
pre-established, is application specific. The ACE framework may be
used to establish the necessary input parameters
[I-D.ietf-ace-oauth-authz].
3.2.1. Derivation of Sender Key/IV, Recipient Key/IV 3.2.1. Derivation of Sender Key, Recipient Key, and Common IV
The KDF MUST be one of the HMAC based HKDF [RFC5869] algorithms The KDF MUST be one of the HMAC based HKDF [RFC5869] algorithms
defined in COSE. HKDF SHA-256 is mandatory to implement. The defined in COSE. HKDF SHA-256 is mandatory to implement. The
security context parameters Sender Key/IV and Recipient Key/IV SHALL security context parameters Sender Key, Recipient Key, and Common IV
be derived from the input parameters using the HKDF, which consists SHALL be derived from the input parameters using the HKDF, which
of the composition of the HKDF-Extract and HKDF-Expand steps consists of the composition of the HKDF-Extract and HKDF-Expand steps
([RFC5869]): ([RFC5869]):
output parameter = HKDF(salt, IKM, info, L) output parameter = HKDF(salt, IKM, info, L)
where: where:
o salt is the Master Salt as defined above o salt is the Master Salt as defined above
o IKM is the Master Secret is defined above o IKM is the Master Secret is defined above
o info is a CBOR array consisting of: o info is a CBOR array consisting of:
info = [ info = [
id : bstr, id : bstr / nil,
alg : int, alg : int,
type : tstr, type : tstr,
L : int L : uint
] ]
* id is the Sender ID or Recipient ID where:
* type is "Key" or "IV" o id is the Sender ID or Recipient ID when deriving keys and nil
when deriving the Common IV. Sender ID and Recipient ID are
encoded as described in Section 5
o L is the size of the key/IV for the AEAD algorithm used, in o type is "Key" or "IV"
octets.
For example, if the algorithm AES-CCM-64-64-128 (see Section 10.2 in o L is the size of the key/IV for the AEAD algorithm used, in octets
[I-D.ietf-cose-msg]) is used, the value for L is 16 for keys and 7
for IVs. For example, if the algorithm AES-CCM-16-64-128 (see Section 10.2 in
[RFC8152]) is used, the value for L is 16 for keys and 13 for the
Common IV.
3.2.2. Initial Sequence Numbers and Replay Window 3.2.2. Initial Sequence Numbers and Replay Window
The Sequence Number is initialized to 0. The supported types of The Sender Sequence Number is initialized to 0. The supported types
replay protection and replay window length is application specific of replay protection and replay window length is application specific
and depends on the lower layers. Default is DTLS-type replay and depends on the lower layers. The default is DTLS-type replay
protection with a window size of 32 initiated as described in protection with a window size of 32 initiated as described in
Section 4.1.2.6 of [RFC6347]. Section 4.1.2.6 of [RFC6347].
3.3. Requirements on the Security Context Parameters 3.3. Requirements on the Security Context Parameters
As collisions may lead to the loss of both confidentiality and As collisions may lead to the loss of both confidentiality and
integrity, Sender ID SHALL be unique in the set of all security integrity, Sender ID SHALL be unique in the set of all security
contexts using the same Master Secret. Normally (e.g. when using contexts using the same Master Secret and Master Salt. When a
EDHOC [I-D.selander-ace-cose-ecdhe]) Sender IDs can be very short. trusted third party assigns identifiers (e.g., using
Note that Sender IDs of different lengths can be used with the same [I-D.ietf-ace-oauth-authz]) or by using a protocol that allows the
Master Secret. E.g. the SID with value 0x00 is different from the parties to negotiate locally unique identifiers in each endpoint, the
SID with the value 0x0000. If Sender ID uniqueness cannot be Sender IDs can be very short. The maximum Sender ID is 2^(nonce
guaranteed, random Sender IDs MUST be used. Random Sender IDs MUST length in bits - 40) - 1, For AES-CCM-16-64-128 the maximum Sender ID
be long enough so that the probability of collisions is negligible. is 2^64 - 1. If Sender ID uniqueness cannot be guaranteed, random
Sender IDs MUST be used. Random Sender IDs MUST be long enough so
that the probability of collisions is negligible.
To enable retrieval of the right Recipient Context, the Recipient ID To enable retrieval of the right Recipient Context, the Recipient ID
SHOULD be unique in the sets of all Recipient Contexts used by an SHOULD be unique in the sets of all Recipient Contexts used by an
endpoint. endpoint. The Client MAY provide a Context Hint Section 8.3 to help
the Server find the right context.
The same Master Salt MAY be used with several Master Secrets. While the triple (Master Secret, Master Salt, Sender ID) MUST be
unique, the same Master Salt MAY be used with several Master Secrets
and the same Master Secret MAY be used with several Master Salts.
4. Protected CoAP Message Fields 4. Protected Message Fields
OSCOAP transforms a CoAP message into an OSCOAP message, and vice OSCORE transforms a CoAP message (which may have been generated from
versa. This section defines how the CoAP message fields are an HTTP message) into an OSCORE message, and vice versa. OSCORE
protected. Note that OSCOAP protects messages from the CoAP protects as much of the original message as possible while still
Requests/Responses layer only, and not from the Messaging layer allowing certain proxy operations (see Section 10). This section
(Section 2 of [RFC7252]): this means that RST and ACK empty messages defines how OSCORE protects the message fields and transfers them
are not protected, while ACK with piggybacked responses are protected end-to-end between client and server (in any direction).
using the process defined in this document. All the messages
mentioned in this document refer to CON, NON and non-empty ACK
messages.
OSCOAP protects as much of the original CoAP message as possible, The remainder of this section and later sections discuss the behavior
while still allowing forward proxy operations in terms of CoAP messages. If HTTP is used for a particular leg in
[I-D.hartke-core-e2e-security-reqs]. Message fields may either be 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 10. 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.
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 E: encrypted and integrity protected,
o Class I: integrity protected only, or o Class I: integrity protected only, or
o Class U: unprotected. o Class U: unprotected.
This section also outlines how the message fields are transferred, a The sending endpoint SHALL transfer Class E message fields in the
detailed description of the processing is provided in Section 7. ciphertext of the COSE object in the OSCORE message. The sending
Message fields of the original CoAP message are either transferred in endpoint SHALL include Class I message fields in the Additional
the header/options part of the OSCOAP message, or in the plaintext of Authenticated Data (AAD) of the AEAD algorithm, allowing the
the COSE object. Depending on which, the location of the message receiving endpoint to detect if the value has changed in transfer.
field in the OSCOAP message is called "outer" or "inner": Class U message fields SHALL NOT be protected in transfer. Class I
and Class U message field values are transferred in the header or
o Inner message field: message field included in the plaintext of options part of the OSCORE message which is visible to proxies.
the COSE object of the OSCOAP message (see Section 5.1). The
inner message fields are by definition encrypted and integrity
protected by the COSE object (Class E).
o Outer message field: message field included in the header or Message fields not visible to proxies, i.e., transported in the
options part of the OSCOAP message. The outer message fields are ciphertext of the COSE object, are called "Inner" (Class E). Message
not encrypted and thus visible to an intermediary, but may be fields transferred in the header or options part of the OSCORE
integrity protected by including the message field values in the message, which is visible to proxies, are called "Outer" (Class I or
Additional Authenticated Data (AAD) of the COSE object (see U).
Section 5.2). I.e. outer message fields may be Class I or Class
U.
Note that, even though the message formats are slightly different, CoAP message fields are either Inner or Outer: Inner if the value is
OSCOAP complies with CoAP over unreliable transport [RFC7252] as well intended for the destination endpoint, Outer if the value is intended
as CoAP over reliable transport [I-D.ietf-core-coap-tcp-tls]. for a proxy. An OSCORE message may contain both an Inner and an
Outer message field of certain CoAP message fields. Inner and Outer
message fields are processed independently.
4.1. CoAP Payload 4.1. CoAP Payload
The CoAP Payload SHALL be encrypted and integrity protected (Class The CoAP Payload, if present in the original CoAP message, SHALL be
E), and thus is an inner message field. encrypted and integrity protected and is thus an Inner message field.
The sending endpoint writes the payload of the original CoAP message The sending endpoint writes the payload of the original CoAP message
into the plaintext of the COSE object. into the plaintext (Section 5.2) input to the COSE object. The
receiving endpoint verifies and decrypts the COSE object, and
The receiving endpoint verifies and decrypts the COSE object, and
recreates the payload of the original CoAP message. recreates the payload of the original CoAP message.
4.2. CoAP Header 4.2. CoAP Options
Many CoAP header fields are required to be read and changed during a
normal message exchange or when traversing a proxy and thus cannot in
general be protected between the endpoints, e.g. CoAP message layer
fields such as Message ID.
The CoAP header field Code MUST be sent in plaintext to support A summary of how options are protected is shown in Figure 4. Options
RESTful processing, but MUST be integrity protected (Class I) to which require special processing, in particular those which may have
prevent an intermediary from changing, e.g. from GET to DELETE. The both Inner and Outer message fields, are labelled with asterisks.
CoAP version number MUST be integrity protected to prevent potential
future version-based attacks (Class I). Note that while the version
number is not sent in each CoAP message over reliable transport
[I-D.ietf-core-coap-tcp-tls], its value is known to client and
server.
The other CoAP header fields SHALL neither be integrity protected nor +----+----------------+---+---+---+
encrypted (Class U). All CoAP header fields are thus outer message | No.| Name | E | I | U |
fields. +----+----------------+---+---+---+
| 1 | If-Match | x | | |
| 3 | Uri-Host | | | x |
| 4 | ETag | x | | |
| 5 | If-None-Match | x | | |
| 6 | Observe | | | * |
| 7 | Uri-Port | | | x |
| 8 | Location-Path | x | | |
| 11 | Uri-Path | x | | |
| 12 | Content-Format | x | | |
| 14 | Max-Age | * | | * |
| 15 | Uri-Query | x | | |
| 17 | Accept | x | | |
| 20 | Location-Query | x | | |
| 23 | Block2 | * | | * |
| 27 | Block1 | * | | * |
| 28 | Size2 | * | | * |
| 35 | Proxy-Uri | * | | * |
| 39 | Proxy-Scheme | | | x |
| 60 | Size1 | * | | * |
+----+----------------+---+---+---+
The sending endpoint SHALL copy the header fields from the original E = Encrypt and Integrity Protect (Inner)
CoAP message to the header of the OSCOAP message. The receiving I = Integrity Protect only (Outer)
endpoint SHALL copy the header fields from the OSCOAP message to the U = Unprotected (Outer)
header of the decrypted CoAP message. Both sender and receiver * = Special
include the CoAP version number and header field Code in the AAD of
the COSE object (see Section 5.2).
4.3. CoAP Options Figure 4: Protection of CoAP Options
Most options are encrypted and integrity protected (Class E), and Unknown CoAP options SHALL be processed as class E (and no special
thus inner message fields. But to allow certain proxy operations, processing). Specifications of new CoAP options SHOULD define how
some options have outer values, i.e. are present as options in the they are processed with OSCORE. A new COAP option SHOULD be of class
OSCOAP message. Certain options may have both an inner value and a E unless it requires proxy processing.
potentially different outer value, where the inner value is intended
for the destination endpoint and the outer value is intended for a
proxy.
A summary of how options are protected and processed is shown in 4.2.1. Inner Options
Figure 4. Options within each class are protected and processed in a
similar way, but certain options which require special processing as
indicated by a * in Figure 4 and described in the processing of the
respective option.
+----+----------------+---+---+---+ When using OSCORE, Inner option message fields (marked in column E of
| No.| Name | E | I | U | Figure 4) are sent in a way analogous to communicating in a protected
+----+----------------+---+---+---+ manner directly with the other endpoint.
| 1 | If-Match | x | | |
| 3 | Uri-Host | | | x |
| 4 | ETag | x | | |
| 5 | If-None-Match | x | | |
| 6 | Observe | | * | |
| 7 | Uri-Port | | | x |
| 8 | Location-Path | x | | |
| 11 | Uri-Path | x | | |
| 12 | Content-Format | x | | |
| 14 | Max-Age | * | | |
| 15 | Uri-Query | x | | |
| 17 | Accept | x | | |
| 20 | Location-Query | x | | |
| 23 | Block2 | * | | |
| 27 | Block1 | * | | |
| 28 | Size2 | * | | |
| 35 | Proxy-Uri | | | * |
| 39 | Proxy-Scheme | | | x |
| 60 | Size1 | * | | |
+----+----------------+---+---+---+
E=Encrypt and Integrity Protect, I=Integrity Protect only, The sending endpoint SHALL write the Inner option message fields
U=Unprotected, *=Special present in the original CoAP message into the plaintext of the COSE
object Section 5.2, and then remove the Inner option message fields
from the OSCORE message.
Figure 4: Protection of CoAP Options The processing of Inner option message fields by the receiving
endpoint is specified in Section 7.2 and Section 7.4.
Unless specified otherwise, CoAP options not listed in Figure 4 SHALL 4.2.2. Outer Options
be encrypted and integrity protected and processed as class E
options.
Specifications of new CoAP options SHOULD define how they are Outer option message fields (marked in column U or I of Figure 4) are
processed with OSCOAP. New COAP options SHOULD be of class E and used to support proxy operations.
SHOULD NOT have outer values unless a forwarding proxy needs to read
that option value. If a certain option has both inner and outer
values, the two values SHOULD NOT be the same.
4.3.1. Class E Options 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 Object-Security,
SHALL be encoded as described in Section 3.1 of [RFC7252], where the
delta is the difference to the previously included Outer option
message field.
For options in class E (see Figure 4) the option value in the The processing of Outer options by the receiving endpoint is
original CoAP message, if present, SHALL be encrypted and integrity specified in Section 7.2 and Section 7.4.
protected between the endpoints. Hence the actions resulting from
the use of such options is analogous to communicating in a protected
manner directly with the endpoint. For example, a client using an
If-Match option will not be served by a proxy.
The sending endpoint SHALL write the class E option from the original A procedure for integrity-protection-only of Class I option message
CoAP message into the plaintext of the COSE object. fields is specified in Section 5.3.
Except for the special options (* in Figure 4), the sending endpoint Note: There are currently no Class I option message fields defined.
SHALL NOT use the outer options of class E. However, note that an
intermediary may, legitimately or not, add, change or remove the
value of an outer option.
Except for the special options, the receiving endpoint SHALL discard 4.2.3. Special Options
any outer options of class E from the OSCOAP message and SHALL write
the Class E options present in the plaintext of the COSE object into
the decrypted CoAP message.
4.3.1.1. Max-Age Some options require special processing, marked with an asterisk '*'
in Figure 4. An asterisk in the columns E and U indicate that the
option may be added as an Inner and/or Outer message by the sending
endpoint; the processing is specified in this section.
An inner Max-Age option, like other class E options, is used as 4.2.3.1. Max-Age
defined in [RFC7252] taking into account that it is not accessible to
proxies.
Since OSCOAP binds CoAP responses to requests, a cached response The Inner Max-Age option is used to specify the freshness (as defined
would not be possible to use for any other request. To avoid in [RFC7252]) of the resource, end-to-end from the server to the
unnecessary caching, a server MAY add an outer Max-Age option with client, taking into account that the option is not accessible to
value zero to OSCOAP responses (see Section 5.6.1 of [RFC7252]). The proxies. The Inner Max-Age SHALL be processed by OSCORE as specified
outer Max-Age option is not integrity protected. in Section 4.2.1.
4.3.1.2. The Block Options The Outer Max-Age option is used to avoid unnecessary caching of
OSCORE responses at OSCORE unaware intermediary nodes. A server MAY
set a Class U Max-Age option with value zero to Observe responses
(see Section 5.6.1 of [RFC7252]) which is then processed according to
Section 4.2.2. The Outer Max-Age option value SHALL be discarded by
the OSCORE client.
Blockwise [RFC7959] is an optional feature. An implementation MAY Non-Observe OSCORE responses do not need to include a Max-Age option
comply with [RFC7252] and the Object-Security option without since the responses are non-cacheable by construction (see
implementing [RFC7959]. Section 4.3).
The Block options (Block1, Block2, Size1 and Size2) MAY be either 4.2.3.2. The Block Options
only inner options, only outer options or both inner and outer
options. The inner and outer options are processed independently.
4.3.1.2.1. Inner Block Options Blockwise [RFC7959] is an optional feature. An implementation MAY
support [RFC7252] and the Object-Security option without supporting
[RFC7959]. The Block options are used to secure message
fragmentation end-to-end (Inner options) or for proxies to fragment
the OSCORE message for the next hop (Outer options). Inner and Outer
block processing may have different performance properties depending
on the underlying transport. The integrity of the message can be
verified end-to-end both in case of Inner and Outer Blockwise
provided all blocks are received (see Section 4.2.3.2.2).
The inner Block options are used for endpoint-to-endpoint secure 4.2.3.2.1. Inner Block Options
fragmentation of payload into blocks and protection of information
about the fragmentation (block number, block size, last block). In
this case, the sending CoAP endpoint fragments the CoAP message as
defined in [RFC7959] before the message is processed by OSCOAP. The
receiving CoAP endpoint first processes the OSCOAP message before
processing blockwise as defined in [RFC7959].
Applications using OSCOAP with inner Block options MUST specify a The sending CoAP endpoint MAY fragment a CoAP message as defined in
security policy defining a maximum unfragmented message size for [RFC7959] before the message is processed by OSCORE. In this case
inner Block options such that messages exceeding this size SHALL be the Block options SHALL be processed by OSCORE as Inner options
fragmented by the sending endpoint. (Section 4.2.1). The receiving CoAP endpoint SHALL process the
OSCORE message according to Section 4.2.1 before processing blockwise
as defined in [RFC7959].
For blockwise request operations (using Block1) the client MUST use For blockwise request operations using Block1, an endpoint MUST
and process the Request-Tag as defined in Section 3 of comply with the Request-Tag processing defined in Section 3 of
[I-D.amsuess-core-repeat-request-tag]. In particular, the rules in [I-D.amsuess-core-repeat-request-tag]. In particular, the rules in
section 3.3.1 of [I-D.amsuess-core-repeat-request-tag] MUST be section 3.3.1 of [I-D.amsuess-core-repeat-request-tag] MUST be
followed, which guarantee that a specific request body is assembled followed, which guarantee that a specific request body is assembled
only from the corresponding request blocks. only from the corresponding request blocks.
For blockwise response operations (using Block2) the server MUST use For blockwise response operations using Block2, an endpoint MUST
and process the ETag as defined in Section 4 of comply with the ETag processing defined in Section 4 of
[I-D.amsuess-core-repeat-request-tag]. [I-D.amsuess-core-repeat-request-tag].
4.3.1.2.2. Outer Block Options 4.2.3.2.2. Outer Block Options
A CoAP proxy may do block fragmentation on any CoAP message
(including OSCOAP messages) as defined in [RFC7959], and thereby
decompose it into multiple blocks using outer Block options. The
outer block options are thus neither encrypted nor integrity
protected.
To allow multiple concurrent request operations to the same server Proxies MAY fragment an OSCORE message using [RFC7959], which then
(not only same resource), a CoAP proxy should use and process the introduces Outer Block options not generated by the sending endpoint.
Request-Tag as specified in section 3.3.2 of Note that the Outer Block options are neither encrypted nor integrity
[I-D.amsuess-core-repeat-request-tag]; an OSCOAP server that supports protected. As a consequence, a proxy can maliciously inject block
outer Block options MUST support the Request-Tag option. 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
maximum unfragmented message size (MAX_UNFRAGMENTED_SIZE) considering
the maximum size of message which can be handled by the endpoints.
Messages exceeding this size SHOULD be fragmented by the sending
endpoint using Inner Block options (Section 4.2.3.2.1).
An endpoint receiving an OSCOAP message with an outer Block option An endpoint receiving an OSCORE message with an Outer Block option
SHALL first process this option according to [RFC7959], until all SHALL first process this option according to [RFC7959], until all
blocks of the OSCOAP message have been received, or the cumulated blocks of the OSCORE message have been received, or the cumulated
message size of the blocks exceeds the maximum unfragmented message message size of the blocks exceeds MAX_UNFRAGMENTED_SIZE. In the
size. In the latter case the message SHALL be discarded. In the former case, the processing of the OSCORE message continues as
former case, the processing of the OSCOAP message continues as defined in this document. In the latter case the message SHALL be
defined in this document. discarded.
4.3.2. Class I Options
A Class I option is an outer option and hence visible in the options
part of the OSCOAP message. Except for special options described in
the subsections, for options in Class I (see Figure 4) the option
value SHALL be integrity protected between the endpoints, see
(Section 5.2). Unless otherwise specified, the sending endpoint
SHALL encode the Class I options in the OSCOAP message as described
in Section 4.3.4.
4.3.2.1. Observe
Observe [RFC7641] is an optional feature. An implementation MAY
support [RFC7252] and the Object-Security option without supporting
[RFC7641]. The Observe option as used here targets the requirements
on forwarding of [I-D.hartke-core-e2e-security-reqs]
(Section 2.2.1.2).
In order for a proxy to support forwarding of Observe messages, there
must be an Observe option present in options part of the OSCOAP
message ([RFC7641]), so Observe must have an outer value:
o The Observe option of the original CoAP request SHALL be encoded
in the OSCOAP request as described in Section 4.3.4.
To secure the order of the notifications, responses with the Observe
option SHALL be integrity protected in the following way:
o The Observe option SHALL be included in the external_aad of the
response (see Section 5.2), with value set to the 3 least
significant bytes of the Sequence Number of the response.
The Observe option in the CoAP request SHALL NOT be integrity
protected, since it may be legitimately removed by a proxy.
If the Observe option is removed from a CoAP request by a proxy, then
the server can still verify the request (as a non-Observe request),
and produce a non-Observe response. If the OSCOAP client receives a
response to an Observe request without an outer Observe value, then
it MUST verify the response as a non-Observe response, i.e. not
include the Sequence Number of the response in the external_aad.
4.3.3. Class U Options
Options in Class U have outer values and are used to support forward
proxy operations. Unless otherwise specified, the sending endpoint
SHALL encode the Class U options in the options part of the OSCOAP
message as described in Section 4.3.4.
4.3.3.1. Uri-Host, Uri-Port, and Proxy-Scheme
The sending endpoint SHALL copy Uri-Host, Uri-Port, and Proxy-Scheme To allow multiple concurrent request operations to the same server
from the original CoAP message to the options part of the OSCOAP (not only same resource), a CoAP proxy SHOULD follow the Request-Tag
message. When Uri-Host, Uri-Port, or Proxy-Scheme options are processing specified in section 3.3.2 of
present, Proxy-Uri is not used [RFC7252]. [I-D.amsuess-core-repeat-request-tag].
4.3.3.2. Proxy-Uri 4.2.3.3. Proxy-Uri
Proxy-Uri, when present, is split by OSCOAP into class U options and Proxy-Uri, when present, is split by OSCORE into class U options and
class E options, which are processed accordingly. When Proxy-Uri is class E options, which are processed accordingly. When Proxy-Uri is
used in the original CoAP message, Uri-* are not present [RFC7252]. used in the original CoAP message, Uri-* are not present [RFC7252].
The sending endpoint SHALL first decompose the Proxy-Uri value of the The sending endpoint SHALL first decompose the Proxy-Uri value of the
original CoAP message into the Proxy-Scheme, Uri-Host, Uri-Port, Uri- original CoAP message into the Proxy-Scheme, Uri-Host, Uri-Port, Uri-
Path and Uri-Query options (if present) according to section 6.4 of Path, and Uri-Query options (if present) according to section 6.4 of
[RFC7252]. [RFC7252].
Uri-Path and Uri-Query are class E options and MUST be protected and Uri-Path and Uri-Query are class E options and SHALL be protected and
processed as if obtained from the original CoAP message, see processed as Inner options (Section 4.2.1).
Section 4.3.1.
The value of the Proxy-Uri option of the OSCOAP message MUST be The Proxy-Uri option of the OSCORE message SHALL be set to the
replaced with Proxy-Scheme, Uri-Host and Uri-Port options (if composition of Proxy-Scheme, Uri-Host and Uri-Port options (if
present) composed according to section 6.5 of [RFC7252] and MUST be present) as specified in section 6.5 of [RFC7252], and processed as
processed as a class U option, see Section 4.3.3. an Outer option of Class U (Section 4.2.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. In other documents specifying
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 specify in which OSCORE class they
belong.
An example of how Proxy-Uri is processed is given here. Assume that An example of how Proxy-Uri is processed is given here. Assume that
the original CoAP message contains: the original CoAP message contains:
o Proxy-Uri = "coap://example.com/resource?q=1" o Proxy-Uri = "coap://example.com/resource?q=1"
During OSCORE processing, Proxy-Uri is split into:
During OSCOAP processing, Proxy-Uri is split into:
o Proxy-Scheme = "coap" o Proxy-Scheme = "coap"
o Uri-Host = "example.com" o Uri-Host = "example.com"
o Uri-Port = "5863" o Uri-Port = "5683"
o Uri-Path = "resource" o Uri-Path = "resource"
o Uri-Query = "q=1" o Uri-Query = "q=1"
Uri-Path and Uri-Query follow the processing defined in Uri-Path and Uri-Query follow the processing defined in
Section 4.3.1, and are thus encrypted and transported in the COSE Section 4.2.1, and are thus encrypted and transported in the COSE
object. The remaining options are composed into the Proxy-Uri object. The remaining options are composed into the Proxy-Uri
included in the options part of the OSCOAP message, which has value: included in the options part of the OSCORE message, which has value:
o Proxy-Uri = "coap://example.com" o Proxy-Uri = "coap://example.com"
4.3.4. Outer Options in the OSCOAP Message See Section 6.1 and 12.6 of [RFC7252] for more information.
All options with outer values present in the OSCOAP message, 4.2.3.4. Observe
including the Object-Security option, SHALL be encoded as described
in Section 3.1 of [RFC7252], where the delta is the difference to the
previously included outer option value.
5. The COSE Object Observe [RFC7641] is an optional feature. An implementation MAY
support [RFC7252] and the Object-Security option without supporting
[RFC7641]. The Observe option as used here targets the requirements
on forwarding of [I-D.hartke-core-e2e-security-reqs]
(Section 2.2.1.2).
This section defines how to use COSE [I-D.ietf-cose-msg] to wrap and In order for an OSCORE-unaware proxy to support forwarding of Observe
protect data in the original CoAP message. OSCOAP uses the untagged messages ([RFC7641]), there SHALL be an Outer Observe option, i.e.,
COSE_Encrypt0 structure with an Authenticated Encryption with present in the options part of the OSCORE message. The processing of
Additional Data (AEAD) algorithm. The key lengths, IV lengths, and the CoAP Code for Observe messages is described in Section 4.3.
maximum sequence number are algorithm dependent.
The AEAD algorithm AES-CCM-64-64-128 defined in Section 10.2 of To secure the order of notifications, the client SHALL maintain a
[I-D.ietf-cose-msg] is mandatory to implement. For AES-CCM-64-64-128 Notification Number for each Observation it registers. The
the length of Sender Key and Recipient Key is 128 bits, the length of Notification Number is a non-negative integer containing the largest
nonce, Sender IV, and Recipient IV is 7 bytes. The maximum Sequence Partial IV of the successfully received notifications for the
Number is specified in Section 10. associated Observe registration, see Section 6.4. The Notification
Number is initialized to the Partial IV of the first successfully
received notification response to the registration request. In
contrast to [RFC7641], the received Partial IV MUST always be
compared with the Notification Number, which thus MUST NOT be
forgotten after 128 seconds.
The nonce is constructed as described in Section 3.1 of If the verification fails, the client SHALL stop processing the
[I-D.ietf-cose-msg], i.e. by padding the partial IV (Sequence Number response, and in the case of CON respond with an empty ACK. The
in network byte order) with zeroes and XORing it with the Context IV client MAY ignore the Observe option value.
(Sender IV or Recipient IV), with the following addition: The most
significant bit in the first byte of the Context IV SHALL be flipped The Observe option in the CoAP request may be legitimately removed by
for responses, in case there is a unique response (not Observe). In a proxy. If the Observe option is removed from a CoAP request by a
this way, the same sequence number can be reused for requests and proxy, then the server can still verify the request (as a non-Observe
corresponding responses, which reduces the size of the responses in request), and produce a non-Observe response. If the OSCORE client
the most common case. For detailed processing instructions, see receives a response to an Observe request without an outer Observe
Section 7. value, then it MUST verify the response as a non-Observe response.
(The reverse case is covered in the verification of the response, see
Section 7.)
4.3. CoAP Header
Most CoAP header fields 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 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 Section 5.2. After
that, the Outer Code of the OSCORE message SHALL be set to 0.02
(POST) for requests and to 2.04 (Changed) for responses, except for
Observe messages. For Observe messages, the Outer Code of the OSCORE
message SHALL be set to 0.05 (FETCH) for requests and to 2.05
(Content) for responses. This exception allows OSCORE to be
compliant with the Observe processing in OSCORE-unaware proxies. The
choice of POST and FETCH ([RFC8132]) allows all OSCORE messages to
have payload.
The receiving endpoint SHALL discard the Code in the OSCORE message
and write the Code of the Plaintext in the COSE object (Section 5.2)
into the decrypted CoAP message.
The other 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.
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 with an Authenticated Encryption with Additional Data
(AEAD) algorithm. The key lengths, IV length, 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
nonce and Common IV is 13 bytes. The maximum Sender Sequence Number
is specified in Section 11.
We denote by Plaintext the data that is encrypted and integrity We denote by Plaintext the data that is encrypted and integrity
protected, and by Additional Authenticated Data (AAD) the data that protected, and by Additional Authenticated Data (AAD) the data that
is integrity protected only. is integrity protected only.
The COSE Object SHALL be a COSE_Encrypt0 object with fields defined The COSE Object SHALL be a COSE_Encrypt0 object with fields defined
as follows as follows
o The "protected" field is empty. o The "protected" field is empty.
o The "unprotected" field includes: o The "unprotected" field includes:
* The "Partial IV" parameter. The value is set to the Sequence * The "Partial IV" parameter. The value is set to the Sender
Number. The Partial IV SHALL be of minimum length needed to Sequence Number. All leading zeroes SHALL be removed when
encode the sequence number. This parameter SHALL be present in encoding the Partial IV, i.e. the first byte (if any) SHALL
requests. In case of Observe (Section 4.3.2.1) the Partial IV never be zero. This parameter SHALL be present in requests.
SHALL be present in the response, and otherwise the Partial IV In case of Observe (Section 4.2.3.4) the Partial IV SHALL be
SHALL NOT be present in the response. present in responses, and otherwise the Partial IV SHALL NOT be
present in responses.
* The "kid" parameter. The value is set to the Sender ID (see * The "kid" parameter. The value is set to the Sender ID (see
Section 3). This parameter SHALL be present in requests and Section 3). All leading zeroes SHALL be removed when encoding
SHALL NOT be present in responses. the Partial IV, i.e. the first byte (if any) SHALL never be
zero. This parameter SHALL be present in requests and SHALL
NOT be present in responses.
o The "ciphertext" field is computed from the Plaintext (see o The "ciphertext" field is computed from the secret key (Sender Key
Section 5.1) and the Additional Authenticated Data (AAD) (see or Recipient Key), Nonce (see Section 5.1), Plaintext (see
Section 5.2) following Section 5.2 of [I-D.ietf-cose-msg]. Section 5.2), and the Additional Authenticated Data (AAD) (see
Section 5.3) following Section 5.2 of [RFC8152].
The encryption process is described in Section 5.3 of The encryption process is described in Section 5.3 of [RFC8152].
[I-D.ietf-cose-msg].
5.1. Plaintext 5.1. Nonce
The nonce is constructed by left-padding the Partial IV (in network
byte order) with zeroes to exactly 5 bytes, left-padding the Sender
ID of the endpoint that generated the Partial IV (in network byte
order) with zeroes to exactly nonce length - 5 bytes, concatenating
the padded Partial IV with the padded ID, and then XORing with the
Common IV.
When observe is not used, the request and the response uses the same
nonce. In this way, the Partial IV does not have to be sent in
responses, which reduces the size. For processing instructions, see
Section 7.
+--------------------------+--+--+--+--+--+
| ID of PIV generator | Partial IV |---+
+--------------------------+--+--+--+--+--+ |
|
+-----------------------------------------+ |
| Common IV |->(+)
+-----------------------------------------+ |
|
+-----------------------------------------+ |
| Nonce |<--+
+-----------------------------------------+
Figure 5: AEAD Nonce Formation
5.2. Plaintext
The Plaintext is formatted as a CoAP message without Header (see The Plaintext is formatted as a CoAP message without Header (see
Figure 5) consisting of: Figure 6) consisting of:
o all Class E option values Section 4.3.1 present in the original o the Code of the original CoAP message as defined in Section 3 of
CoAP message (see Section 4.3). The options are encoded as [RFC7252]; and
described in Section 3.1 of [RFC7252], where the delta is the
o all Inner option message fields (see Section 4.2.1) present in the
original CoAP message (see Section 4.2). The options are encoded
as described in Section 3.1 of [RFC7252], where the delta is the
difference to the previously included Class E option; and difference to the previously included Class E option; and
o the Payload of original CoAP message, if present, and in that case o the Payload of original CoAP message, if present, and in that case
prefixed by the one-byte Payload Marker (0xFF). prefixed by the one-byte Payload Marker (0xFF).
0 1 2 3 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 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Class E options (if any) ... | Code | Class E options (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 1 1 1 1 1 1 1| Payload (if any) ... |1 1 1 1 1 1 1 1| Payload (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(only if there (only if there
is payload) is payload)
Figure 5: Plaintext Figure 6: Plaintext
5.2. Additional Authenticated Data 5.3. Additional Authenticated Data
The external_aad SHALL be a CBOR array as defined below: The external_aad SHALL be a CBOR array as defined below:
external_aad = [ external_aad = [
ver : uint, version : uint,
code : uint,
options : bstr,
alg : int, alg : int,
request_kid : bstr, request_kid : bstr,
request_seq : bstr request_piv : bstr,
options : bstr
] ]
where: where:
o ver: contains the CoAP version number, as defined in Section 3 of o version: contains the OSCORE version number. Implementations of
[RFC7252]. this specification MUST set this field to 1. Other values are
reserved for future versions.
o code: contains is the CoAP Code of the original CoAP message, as
defined in Section 3 of [RFC7252].
o options: contains the Class I options Section 4.3.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 class I option
o alg: contains the Algorithm from the security context used for the o alg: contains the AEAD Algorithm from the security context used
exchange (see Section 3.1). for the exchange (see Section 3.1).
o request_kid: contains the value of the 'kid' in the COSE object of o request_kid: contains the value of the 'kid' in the COSE object of
the request (see Section 5). the request (see Section 5).
o request_seq: contains the value of the 'Partial IV' in the COSE o request_piv: contains the value of the 'Partial IV' in the COSE
object of the request (see Section 5). object of the request (see Section 5).
o options: contains the (non-special) Class I options (see
Section 4.2.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 class I option.
6. Sequence Numbers, Replay, Message Binding, and Freshness 6. Sequence Numbers, Replay, Message Binding, and Freshness
Sequence numbers and replay window are initialized as defined in 6.1. Message Binding
Section 3.2.2.
6.1. AEAD Nonce Uniqueness In order to prevent response delay and mismatch attacks
[I-D.mattsson-core-coap-actuators] from on-path attackers and
compromised proxies, OSCORE binds responses to the request by
including the request's ID (Sender ID or Recipient ID) and Partial IV
in the AAD of the response. The server therefore needs to store the
request's ID (Sender ID or Recipient ID) and Partial IV until all
responses have been sent.
6.2. AEAD Nonce Uniqueness
An AEAD nonce MUST NOT be used more than once per AEAD key. In order An AEAD nonce MUST NOT be used more than once per AEAD key. In order
to assure unique nonces, each Sender Context contains a Sequence to assure unique nonces, each Sender Context contains a Sender
Number used to protect requests, and - in case of Observe - Sequence Number used to protect requests, and - in case of Observe -
responses. The maximum sequence number is algorithm dependent, see responses. If messages are processed concurrently, the operation of
Section 10. If the Sequence Number exceeds the maximum sequence reading and increasing the Sender Sequence Number MUST be atomic.
number, the endpoint MUST NOT process any more messages with the
given Sender Context. The endpoint SHOULD acquire a new security
context (and consequently inform the other endpoint) before this
happens. The latter is out of scope of this document.
6.2. Replay Protection The maximum Sender Sequence Number is algorithm dependent, see
Section 11. If the Sender Sequence Number exceeds the maximum, the
endpoint MUST NOT process any more messages with the given Sender
Context. The endpoint SHOULD acquire a new security context (and
consequently inform the other endpoint) before this happens. The
latter is out of scope of this document.
In order to protect from replay of messages, each Recipient Context 6.3. Freshness
contains a Replay Window used to verify request, and - in case of
Observe - responses. A receiving endpoint SHALL verify that a
Sequence Number (Partial IV) received in the COSE object has not been
received before in the Recipient Context. For requests, if this
verification fails and the message received is a CON message, the
server SHALL respond with a 4.00 Bad Request error message. The
diagnostic payload MAY contain the "Replay protection failed" string.
For responses, if this verification fails and the message received is
a CON message, the client SHALL respond with an empty ACK and stop
processing the response.
The size and type of the Replay Window depends on the use case and For requests, OSCORE provides weak absolute freshness as the only
lower protocol layers. In case of reliable and ordered transport guarantee is that the request is not older than the security context.
from endpoint to endpoint, the recipient MAY just store the last For applications having stronger demands on request freshness (e.g.,
received sequence number and require that newly received Sequence control of actuators), OSCORE needs to be augmented with mechanisms
Numbers equals the last received Sequence Number + 1. providing freshness [I-D.amsuess-core-repeat-request-tag].
6.3. Sequence Number and Replay Window State For responses, the message binding guarantees that a response is not
older than its request. For responses without Observe, this gives
strong absolute freshness. For responses with Observe, the absolute
freshness gets weaker with time, and it is RECOMMENDED that the
client regularly restart the observation.
To prevent reuse of the Nonce/Sequence Number with the same key, or For requests, and responses with Observe, OSCORE also provides
from accepting replayed messages, a node needs to handle the relative freshness in the sense that the received Partial IV allows a
situation of suddenly losing sequence number and replay window state recipient to determine the relative order of responses.
in RAM, e.g. as a result of a reboot.
After boot, a node MAY reject to use existing security contexts from 6.4. Replay Protection
before it booted and MAY establish a new security context with each
party it communicates, e.g. using EDHOC
[I-D.selander-ace-cose-ecdhe]. However, establishing a fresh
security context may have a non-negligible cost in terms of e.g.
power consumption.
If a stored security context is to be used after reboot, then the In order to protect from replay of requests, the server's Recipient
node MUST NOT reuse a previous Sequence Number and MUST NOT accept Context includes a Replay Window. A server SHALL verify that a
previously accepted messages. Partial IV received in the COSE object has not been received before.
If this verification fails and the message received is a CON message,
the server SHALL respond with a 5.03 Service Unavailable error
message with the inner Max-Age option set to 0. The diagnostic
payload MAY contain the "Replay protection failed" string. The size
and type of the Replay Window depends on the use case and lower
protocol layers. In case of reliable and ordered transport from
endpoint to endpoint, the server MAY just store the last received
Partial IV and require that newly received Partial IVs equals the
last received Partial IV + 1.
6.3.1. The Basic Case Responses to non-Observe requests are protected against replay as
they are cryptographically bound to the request.
To prevent reuse of Sequence Number, the node MAY perform the In the case of Observe, a client receiving a notification SHALL
following procedure during normal operations: verify that the Partial IV of a received notification is greater than
the Notification Number bound to that Observe registration. If the
verification fails, the client SHALL stop processing the response,
and in the case of CON respond with an empty ACK. If the
verification succeeds, the client SHALL overwrite the corresponding
Notification Number with the received Partial IV.
o Before sending a message, the client stores in persistent memory a If messages are processed concurrently, the Partial IV needs to be
sequence number associated to the stored security context higher validated a second time after decryption and before updating the
than any sequence number which has been or are being sent using replay protection data. The operation of validating the Partial IV
this security context. After boot, the client does not use any and updating the replay protection data MUST be atomic.
lower sequence number in a request than what was persistently
stored with that security context.
* Storing to persistent memory can be costly. Instead of storing 6.5. Losing Part of the Context State
a sequence number for each request, the client may store Seq +
K to persistent memory every K requests, where Seq is the
current sequence number and K > 1. This is a trade-off between
the number of storage operations and efficient use of sequence
numbers.
To prevent accepting replay of previously received messages, the node To prevent reuse of the Nonce with the same key, or from accepting
MAY perform the following procedure: replayed messages, a node needs to handle the situation of losing
rapidly changing parts of the context, such as the request Token,
Sender Sequence Number, Replay Window, and Nofitifcation Numbers.
These are typically stored in RAM and therefore lost in the case of
an unplanned reboot.
o After boot, before verifying a message using a security context After boot, a node MAY reject to use existing security contexts from
stored before boot, the server synchronizes the replay window so before it booted and MAY establish a new security context with each
that no old messages are being accepted. The server uses the party it communicates. However, establishing a fresh security
Repeat option [I-D.amsuess-core-repeat-request-tag] for context may have a non-negligible cost in terms of, e.g., power
synchronizing the replay window: For each stored security context, consumption.
the first time after boot the server receives an OSCOAP request,
it generates a pseudo-random nonce and responds with the Repeat
option set to the nonce as described in
[I-D.amsuess-core-repeat-request-tag]. If the server receives a
repeated OSCOAP request containing the Repeat option and the same
nonce, and if the server can verify the request, then the sequence
number obtained in the repeated message is set as the lower limit
of the replay window.
6.3.2. The Observe Case After boot, a node MAY use a partly persistently stored security
context, but then the node MUST NOT reuse a previous Sender Sequence
Number and MUST NOT accept previously accepted messages. Some ways
to achieve this is described below:
To prevent reuse of Sequence Number in case of Observe, the node MAY 6.5.1. Sequence Number
perform the following procedure during normal operations:
o Before sending a notification, the server stores in persistent To prevent reuse of Sender Sequence Numbers, a node MAY perform the
memory a sequence number associated to the stored security context following procedure during normal operations:
higher than any sequence number for which a notification has been
or are being sent using this security context. After boot, the
server does not use any lower sequence number in an Observe
response than what was persistently stored with that security
context.
* Storing to persistent memory can be costly. Instead of storing o Each time the Sender Sequence Number is evenly divisible by K,
a sequence number for each notification, the server may store where K is a positive integer, store the Sender Sequence Number in
Seq + K to persistent memory every K requests, where Seq is the persistent memory. After boot, the node initiates the Sender
current sequence number and K > 1. This is a trade-off between Sequence Number to the value stored in persistent memory + K - 1.
the number of storage operations and efficient use of sequence Storing to persistent memory can be costly. The value K gives a
numbers. trade-off between the number of storage operations and efficient
use of Sender Sequence Numbers.
Note that a client MAY continue an ongoing observation after reboot 6.5.2. Replay Window
using a stored security context. With Observe, the client can only
verify the order of the notifications, as they may be delayed. If
the client wants to synchronize with a server resource it MAY restart
an observation.
6.4. Freshness To prevent accepting replay of previously received requests, the
server MAY perform the following procedure after boot:
For responses without Observe, OSCOAP provides absolute freshness. o For each stored security context, the first time after boot the
For requests, and responses with Observe, OSCOAP provides relative server receives an OSCORE request, the server uses the Repeat
freshness in the sense that the sequence numbers allows a recipient option [I-D.amsuess-core-repeat-request-tag] to get a request with
to determine the relative order of messages. verifiable freshness and uses that to synchronize the replay
window. If the server can verify the fresh request, the Partial
IV in the fresh request is set as the lower limit of the replay
window.
For applications having stronger demands on freshness (e.g. control 6.5.3. Replay Protection of Observe Notifications
of actuators), OSCOAP needs to be augmented with mechanisms providing
absolute freshness [I-D.mattsson-core-coap-actuators].
6.5. Delay and Mismatch Attacks To prevent accepting replay of previously received notification
responses, the client MAY perform the following procedure after boot:
In order to prevent response delay and mismatch attacks o The client rejects notifications bound to the earlier
[I-D.mattsson-core-coap-actuators] from on-path attackers and registration, removes all Notification Numbers and re-register
compromised proxies, OSCOAP binds responses to the request by using Observe.
including the request's ID (Sender ID or Recipient ID) and sequence
number in the AAD of the response. The server therefore needs to
store the request's ID (Sender ID or Recipient ID) and sequence
number until all responses have been sent.
7. Processing 7. Processing
This section describes the OSCORE message processing.
7.1. Protecting the Request 7.1. Protecting the Request
Given a CoAP request, the client SHALL perform the following steps to Given a CoAP request, the client SHALL perform the following steps to
create an OSCOAP request: create an OSCORE request:
1. Retrieve the Sender Context associated with the target resource. 1. Retrieve the Sender Context associated with the target resource.
2. Compose the Additional Authenticated Data, as described in 2. Compose the Additional Authenticated Data, as described in
Section 5. Section 5.
3. Compose the AEAD nonce by XORing the Context IV (Sender IV) with 3. Compute the AEAD nonce from the Sender ID, Common IV, and Partial
the partial IV (Sequence Number in network byte order). IV (Sender Sequence Number in network byte order). Then (in one
atomic operation, see Section 6.2) increment the Sender Sequence
Number by one.
4. Encrypt the COSE object using the Sender Key. Compress the COSE 4. Encrypt the COSE object using the Sender Key. Compress the COSE
Object as specified in Section 8. Object as specified in Section 8.
5. Format the OSCOAP message according to Section 4. The Object- 5. Format the OSCORE message according to Section 4. The Object-
Security option is added, see Section 4.3.4. Security option is added, see Section 4.2.2.
6. Store the association Token - Security Context. The client SHALL 6. Store the association Token - Security Context. The client SHALL
be able to find the Recipient Context from the Token in the be able to find the Recipient Context from the Token in the
response. response.
7. Increment the Sequence Number by one.
7.2. Verifying the Request 7.2. Verifying the Request
A server receiving a request containing the Object-Security option A server receiving a request containing the Object-Security option
SHALL perform the following steps: SHALL perform the following steps:
1. Process outer Block options according to [RFC7959], until all 1. Process outer Block options according to [RFC7959], until all
blocks of the request have been received, see Section 4.3.1.2. blocks of the request have been received, see Section 4.2.3.2.
2. Decompress the COSE Object (Section 8) and retrieve the Recipient 2. Discard the message Code and all non-special Inner option
Context associated with the Recipient ID in the 'kid' parameter. message fields (marked with 'x' in column E of Figure 4) present
If the request is a CON message, and: in the received message. For example, an If-Match Outer option
is discarded, but an Uri-Host Outer option is not discarded.
* either the decompression or the COSE message fails to decode, 3. Decompress the COSE Object (Section 8) and retrieve the
the server SHALL respond with a 4.02 Bad Option error message. Recipient Context associated with the Recipient ID in the 'kid'
The diagnostic payload SHOULD contain the string "Failed to parameter. If the request is a NON message and either the
decode COSE". 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 the request is a CON
message, and:
* the server fails to retrieve a Recipient Context with * either the decompression or the COSE message fails to decode,
Recipient ID corresponding to the 'kid' parameter received, the server SHALL respond with a 4.02 Bad Option error
the server SHALL respond with a 4.01 Unauthorized error message. The diagnostic payload SHOULD contain the string
message. The diagnostic payload MAY contain the string "Failed to decode COSE".
"Security context not found".
If the request is a NON message and either the decompression or the * the server fails to retrieve a Recipient Context with
COSE message fails to decode, or the server fails to retrieve a Recipient ID corresponding to the 'kid' parameter received,
Recipient Context with Recipient ID corresponding to the 'kid' the server SHALL respond with a 4.01 Unauthorized error
parameter received, then the server SHALL stop processing the message. The diagnostic payload MAY contain the string
request. "Security context not found".
1. Verify the Sequence Number in the 'Partial IV' parameter, as 4. Verify the 'Partial IV' parameter using the Replay Window, as
described in Section 6. described in Section 6.
2. Compose the Additional Authenticated Data, as described in 5. Compose the Additional Authenticated Data, as described in
Section 5. Section 5.
3. Compose the AEAD nonce by XORing the Context IV (Recipient IV) 6. Compute the AEAD nonce from the Recipient ID, Common IV, and the
with the padded 'Partial IV' parameter, received in the COSE 'Partial IV' parameter, received in the COSE Object.
Object.
4. Decrypt the COSE object using the Recipient Key. 7. Decrypt the COSE object using the Recipient Key.
* If decryption fails, the server MUST stop processing the * If decryption fails, the server MUST stop processing the
request and, if the request is a CON message, the server MUST request and, if the request is a CON message, the server MUST
respond with a 4.00 Bad Request error message. The diagnostic respond with a 4.00 Bad Request error message. The
payload MAY contain the "Decryption failed" string. diagnostic payload MAY contain the "Decryption failed"
string.
* If decryption succeeds, update the Recipient Replay Window, as * If decryption succeeds, update the Replay Window, as
described in Section 6. described in Section 6.
5. Add decrypted options and payload to the decrypted request, 8. For each decrypted option, check if the option is also present
processing the E options as described in (Section 4). The as an Outer option: if it is, discard the Outer. For example:
Object-Security option is removed. the message contains a Max-Age Inner and a Max-Age Outer option.
The Outer Max-Age is discarded.
6. The decrypted CoAP request is processed according to [RFC7252] 9. Add decrypted code, options and payload to the decrypted
request. The Object-Security option is removed.
10. The decrypted CoAP request is processed according to [RFC7252]
7.3. Protecting the Response 7.3. Protecting the Response
Given a CoAP response, the server SHALL perform the following steps Given a CoAP response, the server SHALL perform the following steps
to create an OSCOAP response: to create an OSCORE response. Note that CoAP error responses derived
from CoAP processing (point 10. in Section 7.2) are protected, as
well as successful CoAP responses, while the OSCORE errors (point 3.,
4., 7. in Section 7.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 used to 1. Retrieve the Sender Context in the Security Context used to
verify the request. verify the request.
2. Compose the Additional Authenticated Data, as described in 2. Compose the Additional Authenticated Data, as described in
Section 5. Section 5.
3. Compose the AEAD nonce 3. Compute the AEAD nonce
* If Observe is not used, compose the AEAD nonce by XORing the * If Observe is not used, the nonce from the request is used.
Context IV (Sender IV with the most significant bit in the
first byte flipped) with the padded Partial IV parameter from
the request.
* If Observe is used, compose the AEAD nonce by XORing the * If Observe is used, Compute the AEAD nonce from the Sender ID,
Context IV (Sender IV) with the Partial IV of the response Common IV, and Partial IV (Sender Sequence Number in network
(Sequence Number in network byte order). byte order). Then (in one atomic operation, see Section 6.2)
increment the Sender Sequence Number by one.
4. Encrypt the COSE object using the Sender Key. Compress the COSE 4. Encrypt the COSE object using the Sender Key. Compress the COSE
Object as specified in Section 8. Object as specified in Section 8.
5. Format the OSCOAP message according to Section 4. The Object- 5. Format the OSCORE message according to Section 4. The Object-
Security option is added, see Section 4.3.4. Security option is added, see Section 4.2.2.
6. If Observe is used, increment the Sequence Number by one.
7.4. Verifying the Response 7.4. Verifying the Response
A client receiving a response containing the Object-Security option A client receiving a response containing the Object-Security option
SHALL perform the following steps: SHALL perform the following steps:
1. Process outer Block options according to [RFC7959], until all 1. Process outer Block options according to [RFC7959], until all
blocks of the OSCOAP message have been received, see blocks of the OSCORE message have been received, see
Section 4.3.1.2. Section 4.2.3.2.
2. Retrieve the Recipient Context associated with the Token. 2. Discard the message Code and all non-special Class E options
Decompress the COSE Object (Section 8). If the response is a CON from the message. For example, ETag Outer option is discarded,
message and either the decompression or the COSE message fails to Max-Age Outer option is not discarded.
decode, then the client SHALL send an empty ACK back and stop
processing the response. If the response is a NON message and
any of the previous conditions appear, then the client SHALL
simply stop processing the response.
1. For Observe notifications, verify the Sequence Number in the 3. Retrieve the Recipient Context associated with the Token.
'Partial IV' parameter as described in Section 6. Decompress the COSE Object (Section 8). If either the
decompression or the COSE message fails to decode, then go to
11.
2. Compose the Additional Authenticated Data, as described in 4. For Observe notifications, verify the received 'Partial IV'
Section 5. parameter against the corresponding Notification Number as
described in Section 6. If the client receives a notification
for which no Observe request was sent, then go to 11.
3. Compose the AEAD nonce 5. Compose the Additional Authenticated Data, as described in
Section 5.
* If the Observe option is not present in the response, compose 6. Compute the AEAD nonce
the AEAD nonce by XORing the Context IV (Recipient IV with the
the most significant bit in the first byte flipped) with the
padded Partial IV parameter from the request.
* If the Observe option is present in the response, compose the * If the Observe option is not present in the response, the
AEAD nonce by XORing the Context IV (Recipient IV) with the nonce from the request is used.
padded Partial IV parameter from the response.
4. Decrypt the COSE object using the Recipient Key. * If the Observe option 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.
* If decryption fails, the client MUST stop processing the 7. Decrypt the COSE object using the Recipient Key.
response and, if the response is a CON message, the client
MUST respond with an empty ACK back.
* If decryption succeeds and Observe is used, update the * If decryption fails, then go to 11.
Recipient Replay Window, as described in Section 6.
5. Add decrypted options or payload to the decrypted response * If decryption succeeds and Observe is used, update the
overwriting any outer E options (see Section 4). The Object- corresponding Notification Number, as described in Section 6.
Security option is removed.
* If Observe is used, replace the Observe value with the 3 least 8. For each decrypted option, check if the option is also present
significant bytes in the sequence number. as an Outer option: if it is, discard the Outer. For example:
the message contains a Max-Age Inner and a Max-Age Outer option.
The Outer Max-Age is discarded.
6. The decrypted CoAP response is processed according to [RFC7252] 9. Add decrypted code, options and payload to the decrypted
request. The Object-Security option is removed.
8. OSCOAP Compression 10. The decrypted CoAP response is processed according to [RFC7252]
11. (Optional) In case any of the previous erroneous conditions
apply: if the response is a CON message, then the client SHALL
send an empty ACK back and stop processing the response; if the
response is a ACK or a NON message, then the client SHALL simply
stop processing the response.
8. OSCORE Compression
The Concise Binary Object Representation (CBOR) [RFC7049] combines The Concise Binary Object Representation (CBOR) [RFC7049] combines
very small message sizes with extensibility. The CBOR Object Signing very small message sizes with extensibility. The CBOR Object Signing
and Encryption (COSE) [I-D.ietf-cose-msg] uses CBOR to create compact and Encryption (COSE) [RFC8152] uses CBOR to create compact encoding
encoding of signed and encrypted data. COSE is however constructed of signed and encrypted data. COSE is however constructed to support
to support a large number of different stateless use cases, and is a large number of different stateless use cases, and is not fully
not fully optimized for use as a stateful security protocol, leading optimized for use as a stateful security protocol, leading to a
to a larger than necessary message expansion. In this section we larger than necessary message expansion. In this section, we define
define a simple stateless compression mechanism for OSCOAP, which a simple stateless compression mechanism for OSCORE called the
significantly reduces the per-packet overhead. "compressed COSE object", which significantly reduces the per-packet
overhead.
8.1. Encoding of the Object-Security Option 8.1. Encoding of the Object-Security Value
The value of the Object-Security option SHALL be encoded as follows: The value of the Object-Security option SHALL contain the OSCORE flag
byte and the kid parameter as follows:
o The first byte MUST encode a set of flags and the length of the 0 1 2 3
Partial IV parameter. 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|0 0 0|h|k| n | kid (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
* The three least significant bits encode the Partial IV size. Figure 7: Object-Security Value
If their value is 0, the Partial IV is not present in the
compressed message.
* The fourth least significant bit is set to 1 if the kid is o The first byte (= the OSCORE flag byte) encodes a set of flags and
present in the compressed message. the length of the Partial IV parameter.
* The fifth-eighth least significant bits (= most significant * The three least significant bits, n, encode the Partial IV
half-byte) are reserved and SHALL be set to zero when not in length + 1. If n = 0 then the Partial IV is not present in the
use. compressed COSE object. The value n = 7 is reserved.
o The following n bytes (n being the value of the Partial IV size in * The fourth least significant bit is the kid flag, k: it is set
the first byte) encode the value of the Partial IV, if the Partial to 1 if the kid is present in the compressed COSE object.
IV is present (size not 0).
o The following byte encodes the size of the kid parameter, if the * The fifth least significant bit is the Context Hint flag, h: it
kid is present (flag bit set to 1) is set to 1 if the compressed COSE object contains a Context
Hint, see Section 8.3.
o The following m bytes (m given by the previous byte) encode the * The sixth-eighth least significant bits are reserved and SHALL
value of the kid, if the kid is present (flag bit set to 1) be set to zero when not in use.
o The remainining bytes encode the ciphertext. o The remaining bytes encode the value of the kid, if the kid is
present (k = 1)
The presence of Partial IV and kid in requests and responses is The presence of Partial IV and kid in requests and responses is
specified in Section 5, and summarized in Figure 6. specified in Section 5, and summarized in Figure 8.
7 6 5 4 3 2 1 0 +--------------------------+-----+-----+
+-+-+-+-+-+-+-+-+ k: kid flag bit | | k | n |
|0 0 0 0|k|pivsz| pivsz: Partial IV size (3 bits) +--------------------------+-----+-----+
+-+-+-+-+-+-+-+-+ | Request | 1 | > 0 |
| Response without Observe | 0 | 0 |
| Response with Observe | 0 | > 0 |
+--------------------------+-----+-----+
+-------+---------+------------+-----------+ Figure 8: Presence of data fields in OSCORE flag byte
| | Request | Resp with- | Resp with |
| | | out observe| observe |
+-------+---------+------------+-----------+
| k | 1 | 0 | 0 |
| pivsz | > 0 | 0 | > 0 |
+-------+---------+------------+-----------+
Figure 6: Flag byte for OSCOAP compression 8.2. Encoding of the OSCORE Payload
8.2. Examples The payload of the OSCORE message SHALL be encoded as follows:
o The first n - 1 bytes encode the value of the Partial IV, if the
Partial IV is present (n > 0).
o The following 1 byte encode the length of the Context Hint
(Section 8.3), s, if the Context Hint flag is set (h = 1).
o The following s bytes encode the Context Hint, if the Context Hint
flag is set (h = 1).
o The remaining bytes encode the ciphertext.
8.3. Context Hint
For certain use cases, e.g. deployments where the same Recipient ID
is used with multiple contexts, it is necessary or favorable for the
sending endpoint to provide a Context Hint in order for the receiving
endpoint to retrieve the recipient context. The Context Hint is
implicitly integrity protected, as a manipulation leads to the wrong
or no context being retrieved resulting in a verification error.
Examples:
o If the sending endpoint has an identifier in some other namespace
which can be used by the recipient endpoint to retrieve or
establish the security context, then that identifier can be used
as Context Hint.
o In case of a group communication scenario
[I-D.tiloca-core-multicast-oscoap], if the recipient endpoint
belongs to multiple groups, involving the same endpoints, then a
group identifier can be used as Context Hint to enable the
receiving endpoint to find the right group security context.
8.4. Compression Examples
This section provides examples of COSE Objects before and after This section provides examples of COSE Objects before and after
OSCOAP compression. OSCORE compression.
8.2.1. Example: Request 8.4.1. Example: Request
Before compression: Before compression:
[ [
h'', h'',
{ 4:h'25', 6:h'05' }, { 4:h'25', 6:h'05' },
h'aea0155667924dff8a24e4cb35b9' h'aea0155667924dff8a24e4cb35b9'
] ]
0x83 40 a2 04 41 25 06 41 05 4e ae a0 15 56 67 92 0x83 40 a2 04 41 25 06 41 05 4e ae a0 15 56 67 92
4d ff 8a 24 e4 cb 35 b9 (24 bytes) 4d ff 8a 24 e4 cb 35 b9 (24 bytes)
After compression:
Flag byte: 0b00001010 = 0x0a
Option Value: 0a 25 (2 bytes)
Payload: 05 ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (15 bytes)
8.4.2. Example: Request 2
Before compression:
[
h'',
{ 4:h'00', 6:h'00' },
h'aea0155667924dff8a24e4cb35b9'
]
0x83 40 a2 04 41 00 06 41 00 4e ae a0 15 56 67 92
4d ff 8a 24 e4 cb 35 b9 (24 bytes)
After compression: After compression:
First byte: 0b00001001 = 0x09 Flag byte: 0b00001001 = 0x09
0x09 05 01 25 ae a0 15 56 67 92 4d ff 8a 24 e4 cb Option Value: 09 (1 bytes)
35 b9 (18 bytes)
8.2.2. Example: Response (without Observe) Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes)
8.4.3. Example: Response (without Observe)
Before compression: Before compression:
[ [
h'', h'',
{}, {},
h'aea0155667924dff8a24e4cb35b9' h'aea0155667924dff8a24e4cb35b9'
] ]
0x83 40 a0 4e ae a0 15 56 67 92 4d ff 8a 24 e4 cb 0x83 40 a0 4e ae a0 15 56 67 92 4d ff 8a 24 e4 cb
35 b9 (18 bytes) 35 b9 (18 bytes)
After compression: After compression:
First byte: 0b00000000 = 0x00 Flag byte: 0b00000000 = 0x00
0x00 ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 Option Value: (0 bytes)
(15 bytes)
8.2.3. Example: Response (with Observe) Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes)
8.4.4. Example: Response (with Observe)
Before compression: Before compression:
[ [
h'', h'',
{ 6:h'07' }, { 6:h'07' },
h'aea0155667924dff8a24e4cb35b9' h'aea0155667924dff8a24e4cb35b9'
] ]
0x83 40 a1 06 41 07 4e ae a0 15 56 67 92 4d ff 0x83 40 a1 06 41 07 4e ae a0 15 56 67 92 4d ff
8a 24 e4 cb 35 b9 (21 bytes) 8a 24 e4 cb 35 b9 (21 bytes)
After compression: After compression:
First byte: 0b00000001 = 0x01 Flag byte: 0b00000010 = 0x02
0x01 07 ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 Option Value: 02 (1 bytes)
(16 bytes)
Payload: 07 ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (15 bytes)
9. Web Linking 9. Web Linking
The use of OSCOAP MAY be indicated by a target attribute "osc" in a The use of OSCORE MAY be indicated by a target attribute "osc" in a
web link [RFC5988] to a CoAP resource. This attribute is a hint web link [RFC5988] to a resource. This attribute is a hint
indicating that the destination of that link is to be accessed using indicating that the destination of that link is to be accessed using
OSCOAP. Note that this is simply a hint, it does not include any OSCORE. Note that this is simply a hint, it does not include any
security context material or any other information required to run security context material or any other information required to run
OSCOAP. OSCORE.
A value MUST NOT be given for the "osc" attribute; any present value 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 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 than once in a given link-value; occurrences after the first MUST be
ignored by parsers. ignored by parsers.
10. Security Considerations 10. Proxy Operations
RFC 7252 defines operations for a CoAP-to-CoAP proxy (see Section 5.7
of [RFC7252]) and for proxying between CoAP and HTTP (Section 10 of
[RFC7252]). A more detailed description of the HTTP-to-CoAP mapping
is provided by [RFC8075]. This section describes the operations of
OSCORE-aware proxies.
10.1. CoAP-to-CoAP Forwarding Proxy
OSCORE is designed to work with legacy CoAP-to-CoAP forward proxies
[RFC7252], but OSCORE-aware proxies provide certain simplifications
as specified in this section.
The targeted proxy operations are specified in Section 2.2.1 of
[I-D.hartke-core-e2e-security-reqs]. In particular caching is
disabled since the CoAP response is only applicable to the original
client's CoAP request. An OSCORE-aware proxy SHALL NOT cache a
response to a request with an Object-Security option. As a
consequence, the search for cache hits and CoAP freshness/Max-Age
processing can be omitted.
Proxy processing of the (Outer) Proxy-Uri option is as defined in
[RFC7252].
Proxy processing of the (Outer) Block options is as defined in
[RFC7959] and [I-D.amsuess-core-repeat-request-tag].
Proxy processing of the (Outer) Observe option is as defined in
[RFC7641]. OSCORE-aware proxies MAY look at the Partial IV value
instead of the Outer Observe option.
10.2. HTTP-to-CoAP Translation Proxy
Section 10.2 of [RFC7252] and [RFC8075] specify the behavior of an
HTTP-to-CoAP proxy. As requested in Section 1 of [RFC8075], this
section describes the HTTP mapping for the OSCORE protocol extension
of CoAP.
The presence of the Object-Security option, both in requests and
responses, is expressed in an HTTP header field named Object-Security
in the mapped request or response. The value of the field is the
value of the Object-Security option Section 8.1 in base64url encoding
(Section 5 of [RFC4648]) without padding (see [RFC7515] Appendix C
for implementation notes for this encoding). The value of the
payload is the OSCORE payload Section 8.2, also base64url-encoded
without padding.
Example:
Mapping and notation here is based on "Simple Form" (Section 5.4.1.1
of [RFC8075]).
[HTTP request -- Before object security processing]
GET http://proxy.url/hc/?target_uri=coap://device.url/orders HTTP/1.1
[HTTP request -- HTTP Client to Proxy]
POST http://proxy.url/hc/?target_uri=coap://device.url/ HTTP/1.1
Object-Security: 0b 25
Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary]
[CoAP request -- Proxy to CoAP Server]
POST coap://device.url/
Object-Security: 0b 25
Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary]
[CoAP response -- CoAP Server to Proxy]
2.04 Changed
Object-Security: [empty]
Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary]
[HTTP response -- Proxy to HTTP Client]
HTTP/1.1 200 OK
Object-Security: [empty]
Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary]
[HTTP response -- After object security processing]
HTTP/1.1 200 OK
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.
10.3. CoAP-to-HTTP Translation Proxy
Section 10.1 of [RFC7252] describes the behavior of a CoAP-to-HTTP
proxy. RFC 8075 [RFC8075] does not cover this direction in any more
detail and so an example instantiation of Section 10.1 of [RFC7252]
is used below.
Example:
[CoAP request -- Before object security processing]
GET coap://proxy.url/
Proxy-Uri=http://device.url/orders
[CoAP request -- CoAP Client to Proxy]
POST coap://proxy.url/
Proxy-Uri=http://device.url/
Object-Security: 0b 25
Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary]
[HTTP request -- Proxy to HTTP Server]
POST http://device.url/ HTTP/1.1
Object-Security: 0b 25
Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary]
[HTTP response -- HTTP Server to Proxy]
HTTP/1.1 200 OK
Object-Security: [empty]
Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary]
[CoAP response -- CoAP Server to Proxy]
2.04 Changed
Object-Security: [empty]
Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary]
[CoAP response -- After object security processing]
2.05 Content
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.
11. Security Considerations
In scenarios with intermediary nodes such as proxies or brokers, In scenarios with intermediary nodes such as proxies or brokers,
transport layer security such as DTLS only protects data hop-by-hop. transport layer security such as (D)TLS only protects data hop-by-
As a consequence the intermediary nodes can read and modify hop. As a consequence, the intermediary nodes can read and modify
information. The trust model where all intermediate nodes are information. The trust model where all intermediate nodes are
considered trustworthy is problematic, not only from a privacy considered trustworthy is problematic, not only from a privacy
perspective, but also from a security perspective, as the perspective, but also from a security perspective, as the
intermediaries are free to delete resources on sensors and falsify intermediaries are free to delete resources on sensors and falsify
commands to actuators (such as "unlock door", "start fire alarm", commands to actuators (such as "unlock door", "start fire alarm",
"raise bridge"). Even in the rare cases, where all the owners of the "raise bridge"). Even in the rare cases, where all the owners of the
intermediary nodes are fully trusted, attacks and data breaches make intermediary nodes are fully trusted, attacks and data breaches make
such an architecture brittle. such an architecture brittle.
DTLS protects hop-by-hop the entire CoAP message, including header, (D)TLS protects hop-by-hop the entire message, including header,
options, and payload. OSCOAP protects end-to-end the payload, and options, and payload. OSCORE protects end-to-end the payload, and
all information in the options and header, that is not required for all information in the options and header, that is not required for
forwarding (see Section 4). DTLS and OSCOAP can be combined, thereby proxy operations (see Section 4). (D)TLS and OSCORE can be combined,
enabling end-to-end security of CoAP payload, in combination with thereby enabling end-to-end security of the message payload, in
hop-by-hop protection of the entire CoAP message, during transport combination with hop-by-hop protection of the entire message, during
between end-point and intermediary node. transport between end-point and intermediary node. The message
layer, however, cannot be protected end-to-end through intermediary
The CoAP message layer, however, cannot be protected end-to-end devices since, even if the protocol itself isn't translated, the
through intermediary devices since the parameters Type and Message parameters Type, Message ID, Token, and Token Length may be changed
ID, as well as Token and Token Length may be changed by a proxy. by a proxy.
Moreover, messages that are not possible to verify should for
security reasons not always be acknowledged but in some cases be
silently dropped. This would not comply with CoAP message layer, but
does not have an impact on the application layer security solution,
since message layer is excluded from that.
The use of COSE to protect CoAP 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 shared secret material in client and server, which may be
obtained e.g. by using EDHOC [I-D.selander-ace-cose-ecdhe] or the ACE
framework [I-D.ietf-ace-oauth-authz]. An OSCOAP profile of ACE is
described in [I-D.seitz-ace-oscoap-profile].
The mandatory-to-implement AEAD algorithm AES-CCM-64-64-128 is The use of COSE to protect messages as specified in this document
selected for broad applicability in terms of message size (2^64 requires an established security context. The method to establish
blocks) and maximum number of messages (2^56). Compatibility with the security context described in Section 3.2 is based on a common
CCM* is achieved by using the algorithm AES-CCM-16-64-128 shared secret material in client and server, which may be obtained,
[I-D.ietf-cose-msg]. e.g., by using the ACE framework [I-D.ietf-ace-oauth-authz]. An
OSCORE profile of ACE is described in [I-D.seitz-ace-oscoap-profile].
Most AEAD algorithms require a unique nonce for each message, for Most AEAD algorithms require a unique nonce for each message, for
which the sequence numbers in the COSE message field "Partial IV" is which the sender sequence numbers in the COSE message field "Partial
used. If the recipient accepts any sequence number larger than the IV" is used. If the recipient accepts any sequence number larger
one previously received, then the problem of sequence number than the one previously received, then the problem of sequence number
synchronization is avoided. With reliable transport it may be synchronization is avoided. With reliable transport, it may be
defined that only messages with sequence number which are equal to defined that only messages with sequence number which are equal to
previous sequence number + 1 are accepted. The alternatives to previous sequence number + 1 are accepted. The alternatives to
sequence numbers have their issues: very constrained devices may not sequence numbers have their issues: very constrained devices may not
be able to support accurate time, or to generate and store large be able to support accurate time, or to generate and store large
numbers of random nonces. The requirement to change key at counter numbers of random nonces. The requirement to change key at counter
wrap is a complication, but it also forces the user of this wrap is a complication, but it also forces the user of this
specification to think about implementing key renewal. specification to think about implementing key renewal.
The maximum sequence number to guarantee nonce uniqueness The maximum sender sequence number is dependent on the AEAD
(Section 6.1) is algorithm dependent. Using AES_CCM, with the algorithm. The maximum sender sequence number SHALL be 2^40 - 1, or
maximum sequence number SHALL be 2^(min(nonce length in bits, 56) - any algorithm specific lower limit. The compression mechanism
1) - 1. The "-1" in the exponent stems from the same partial IV and (Section 8) assumes that the Partial IV is 40 bits or less. The
flipped bit of IV (Section 5) is used in request and response. The mandatory-to-implement AEAD algorithm AES-CCM-16-64-128 is selected
compression algorithm (Section 8) assumes that the partial IV is 56 for compatibility with CCM*.
bits or less (which is the reason for min(,) in the exponent).
The inner block options enable the sender to split large messages The inner block options enable the sender to split large messages
into OSCOAP-protected blocks such that the receiving node can verify into OSCORE-protected blocks such that the receiving node can verify
blocks before having received the complete message. The outer block blocks before having received the complete message. The outer block
options allow for arbitrary proxy fragmentation operations that options allow for arbitrary proxy fragmentation operations that
cannot be verified by the endpoints, but can by policy be restricted cannot be verified by the endpoints, but can by policy be restricted
in size since the encrypted options allow for secure fragmentation of in size since the encrypted options allow for secure fragmentation of
very large messages. A maximum message size (above which the sending very large messages. A maximum message size (above which the sending
endpoint fragments the message and the receiving endpoint discards endpoint fragments the message and the receiving endpoint discards
the message, if complying to the policy) may be obtained as part of the message, if complying to the policy) may be obtained as part of
normal resource discovery. normal resource discovery.
Applications need to use a padding scheme if the content of a message 12. Privacy Considerations
can be determined solely from the length of the payload. As an
example, the strings "YES" and "NO" even if encrypted can be
distinguished from each other as there is no padding supplied by the
current set of encryption algorithms. Some information can be
determined even from looking at boundary conditions. An example of
this would be returning an integer between 0 and 100 where lengths of
1, 2 and 3 will provide information about where in the range things
are. Three different methods to deal with this are: 1) ensure that
all messages are the same length. For example using 0 and 1 instead
of 'yes' and 'no'. 2) Use a character which is not part of the
responses to pad to a fixed length. For example, pad with a space to
three characters. 3) Use the PKCS #7 style padding scheme where m
bytes are appended each having the value of m. For example,
appending a 0 to "YES" and two 1's to "NO". This style of padding
means that all values need to be padded.
11. Privacy Considerations
Privacy threats executed through intermediate nodes are considerably Privacy threats executed through intermediate nodes are considerably
reduced by means of OSCOAP. End-to-end integrity protection and reduced by means of OSCORE. End-to-end integrity protection and
encryption of CoAP payload and all options that are not used for encryption of the message payload and all options that are not used
forwarding, provide mitigation against attacks on sensor and actuator for proxy operations, provide mitigation against attacks on sensor
communication, which may have a direct impact on the personal sphere. and actuator communication, which may have a direct impact on the
personal sphere.
The unprotected options (Figure 4) may reveal privacy sensitive The unprotected options (Figure 4) may reveal privacy sensitive
information. In particular Uri-Host SHOULD NOT contain privacy information. In particular Uri-Host SHOULD NOT contain privacy
sensitive information. sensitive information.
CoAP headers sent in plaintext allow for example matching of CON and CoAP headers sent in plaintext allow for example matching of CON and
ACK (CoAP Message Identifier), matching of request and responses ACK (CoAP Message Identifier), matching of request and responses
(Token) and traffic analysis. (Token) and traffic analysis.
Using the mechanisms described in Section 6.3 reveals when a device Using the mechanisms described in Section 6.5 may reveal when a
goes through a reboot. This can be mitigated by the device storing device goes through a reboot. This can be mitigated by the device
the precise state of sender sequence number and recipient replay storing the precise state of sender sequence number and replay window
window on a clean shutdown. on a clean shutdown.
12. IANA Considerations The length of message fields can reveal information about the
message. Applications may use a padding scheme to protect against
traffic analysis. As an example, the strings "YES" and "NO" even if
encrypted can be distinguished from each other as there is no padding
supplied by the current set of encryption algorithms. Some
information can be determined even from looking at boundary
conditions. An example of this would be returning an integer between
0 and 100 where lengths of 1, 2 and 3 will provide information about
where in the range things are. Three different methods to deal with
this are: 1) ensure that all messages are the same length. For
example, using 0 and 1 instead of 'yes' and 'no'. 2) Use a character
which is not part of the responses to pad to a fixed length. For
example, pad with a space to three characters. 3) Use the PKCS #7
style padding scheme where m bytes are appended each having the value
of m. For example, appending a 0 to "YES" and two 1's to "NO". This
style of padding means that all values need to be padded. Similar
arguments apply to other message fields such as resource names.
13. IANA Considerations
Note to RFC Editor: Please replace all occurrences of "[[this Note to RFC Editor: Please replace all occurrences of "[[this
document]]" with the RFC number of this specification. document]]" with the RFC number of this specification.
12.1. CoAP Option Numbers Registry 13.1. CoAP Option Numbers Registry
The Object-Security option is added to the CoAP Option Numbers The Object-Security option is added to the CoAP Option Numbers
registry: registry:
+--------+-----------------+-------------------+ +--------+-----------------+-------------------+
| Number | Name | Reference | | Number | Name | Reference |
+--------+-----------------+-------------------+ +--------+-----------------+-------------------+
| TBD | Object-Security | [[this document]] | | TBD | Object-Security | [[this document]] |
+--------+-----------------+-------------------+ +--------+-----------------+-------------------+
12.2. Media Type Registrations 13.2. Header Field Registrations
The "application/oscon" media type is added to the Media Types The HTTP header field Object-Security is added to the Message Headers
registry: registry:
Type name: application +-------------------+----------+----------+-------------------+
| Header Field Name | Protocol | Status | Reference |
Subtype name: oscon +-------------------+----------+----------+-------------------+
| Object-Security | http | standard | [[this document]] |
Required parameters: N/A +-------------------+----------+----------+-------------------+
Optional parameters: N/A
Encoding considerations: binary
Security considerations: See Appendix C of this document.
Interoperability considerations: N/A
Published specification: [[this document]] (this document)
Applications that use this media type: To be identified
Fragment identifier considerations: N/A
Additional information:
* 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:
Goeran Selander <goran.selander@ericsson.com>
Intended usage: COMMON
Restrictions on usage: N/A
Author: Goeran Selander, goran.selander@ericsson.com
12.3. CoAP Content Format Registration
The "application/oscon" content format is added to the CoAP Content
Format registry:
+-------------------+----------+-----+-------------------+
| Media type | Encoding | ID | Reference |
+-------------------+----------+-----+-------------------+
| application/oscon | - | TBD | [[this document]] |
+-------------------+----------+-----+-------------------+
13. Acknowledgments 14. Acknowledgments
The following individuals provided input to this document: Christian The following individuals provided input to this document: Christian
Amsuess, Tobias Andersson, Carsten Bormann, Joakim Brorsson, Thomas Amsuess, Tobias Andersson, Carsten Bormann, Joakim Brorsson, Thomas
Fossati, Martin Gunnarsson, Klaus Hartke, Jim Schaad, Marco Tiloca, Fossati, Martin Gunnarsson, Klaus Hartke, Jim Schaad, Dave Thaler,
and Malisa Vu&#269;ini&#263;. Marco Tiloca, and Malisa Vu&#269;ini&#263;.
Ludwig Seitz and Goeran Selander worked on this document as part of Ludwig Seitz and Goeran Selander worked on this document as part of
the CelticPlus project CyberWI, with funding from Vinnova. the CelticPlus project CyberWI, with funding from Vinnova.
14. References 15. References
14.1. Normative References 15.1. Normative References
[I-D.amsuess-core-repeat-request-tag] [I-D.amsuess-core-repeat-request-tag]
Amsuess, C., Mattsson, J., and G. Selander, "Repeat And Amsuess, C., Mattsson, J., and G. Selander, "Repeat And
Request-Tag", draft-amsuess-core-repeat-request-tag-00 Request-Tag", draft-amsuess-core-repeat-request-tag-00
(work in progress), July 2017. (work in progress), July 2017.
[I-D.ietf-cose-msg]
Schaad, J., "CBOR Object Signing and Encryption (COSE)",
draft-ietf-cose-msg-24 (work in progress), November 2016.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
<https://www.rfc-editor.org/info/rfc4648>.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, [RFC5988] Nottingham, M., "Web Linking", RFC 5988,
DOI 10.17487/RFC5988, October 2010, DOI 10.17487/RFC5988, October 2010,
<http://www.rfc-editor.org/info/rfc5988>. <https://www.rfc-editor.org/info/rfc5988>.
[RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer
Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347,
January 2012, <http://www.rfc-editor.org/info/rfc6347>. January 2012, <https://www.rfc-editor.org/info/rfc6347>.
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
October 2013, <http://www.rfc-editor.org/info/rfc7049>. October 2013, <https://www.rfc-editor.org/info/rfc7049>.
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252, Application Protocol (CoAP)", RFC 7252,
DOI 10.17487/RFC7252, June 2014, DOI 10.17487/RFC7252, June 2014,
<http://www.rfc-editor.org/info/rfc7252>. <https://www.rfc-editor.org/info/rfc7252>.
[RFC7641] Hartke, K., "Observing Resources in the Constrained [RFC7641] Hartke, K., "Observing Resources in the Constrained
Application Protocol (CoAP)", RFC 7641, Application Protocol (CoAP)", RFC 7641,
DOI 10.17487/RFC7641, September 2015, DOI 10.17487/RFC7641, September 2015,
<http://www.rfc-editor.org/info/rfc7641>. <https://www.rfc-editor.org/info/rfc7641>.
[RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in
the Constrained Application Protocol (CoAP)", RFC 7959, the Constrained Application Protocol (CoAP)", RFC 7959,
DOI 10.17487/RFC7959, August 2016, DOI 10.17487/RFC7959, August 2016,
<http://www.rfc-editor.org/info/rfc7959>. <https://www.rfc-editor.org/info/rfc7959>.
14.2. Informative References [RFC8075] Castellani, A., Loreto, S., Rahman, A., Fossati, T., and
E. Dijk, "Guidelines for Mapping Implementations: HTTP to
the Constrained Application Protocol (CoAP)", RFC 8075,
DOI 10.17487/RFC8075, February 2017,
<https://www.rfc-editor.org/info/rfc8075>.
[RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and
FETCH Methods for the Constrained Application Protocol
(CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017,
<https://www.rfc-editor.org/info/rfc8132>.
[RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)",
RFC 8152, DOI 10.17487/RFC8152, July 2017,
<https://www.rfc-editor.org/info/rfc8152>.
15.2. Informative References
[I-D.bormann-6lo-coap-802-15-ie] [I-D.bormann-6lo-coap-802-15-ie]
Bormann, C., "Constrained Application Protocol (CoAP) over Bormann, C., "Constrained Application Protocol (CoAP) over
IEEE 802.15.4 Information Element for IETF", draft- IEEE 802.15.4 Information Element for IETF", draft-
bormann-6lo-coap-802-15-ie-00 (work in progress), April bormann-6lo-coap-802-15-ie-00 (work in progress), April
2016. 2016.
[I-D.greevenbosch-appsawg-cbor-cddl] [I-D.greevenbosch-appsawg-cbor-cddl]
Birkholz, H., Vigano, C., and C. Bormann, "CBOR data Birkholz, H., Vigano, C., and C. Bormann, "Concise data
definition language (CDDL): a notational convention to definition language (CDDL): a notational convention to
express CBOR data structures", draft-greevenbosch-appsawg- express CBOR data structures", draft-greevenbosch-appsawg-
cbor-cddl-10 (work in progress), March 2017. cbor-cddl-11 (work in progress), July 2017.
[I-D.hartke-core-e2e-security-reqs] [I-D.hartke-core-e2e-security-reqs]
Selander, G., Palombini, F., and K. Hartke, "Requirements Selander, G., Palombini, F., and K. Hartke, "Requirements
for CoAP End-To-End Security", draft-hartke-core-e2e- for CoAP End-To-End Security", draft-hartke-core-e2e-
security-reqs-02 (work in progress), January 2017. security-reqs-03 (work in progress), July 2017.
[I-D.ietf-ace-oauth-authz] [I-D.ietf-ace-oauth-authz]
Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and
H. Tschofenig, "Authentication and Authorization for H. Tschofenig, "Authentication and Authorization for
Constrained Environments (ACE)", draft-ietf-ace-oauth- Constrained Environments (ACE)", draft-ietf-ace-oauth-
authz-06 (work in progress), March 2017. authz-07 (work in progress), August 2017.
[I-D.ietf-core-coap-tcp-tls] [I-D.ietf-core-coap-tcp-tls]
Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., Bormann, C., Lemay, S., Tschofenig, H., Hartke, K.,
Silverajan, B., and B. Raymor, "CoAP (Constrained Silverajan, B., and B. Raymor, "CoAP (Constrained
Application Protocol) over TCP, TLS, and WebSockets", Application Protocol) over TCP, TLS, and WebSockets",
draft-ietf-core-coap-tcp-tls-09 (work in progress), May draft-ietf-core-coap-tcp-tls-09 (work in progress), May
2017. 2017.
[I-D.mattsson-core-coap-actuators] [I-D.mattsson-core-coap-actuators]
Mattsson, J., Fornehed, J., Selander, G., and F. Mattsson, J., Fornehed, J., Selander, G., and F.
Palombini, "Controlling Actuators with CoAP", draft- Palombini, "Controlling Actuators with CoAP", draft-
mattsson-core-coap-actuators-02 (work in progress), mattsson-core-coap-actuators-02 (work in progress),
November 2016. November 2016.
[I-D.seitz-ace-oscoap-profile] [I-D.seitz-ace-oscoap-profile]
Seitz, L., Gunnarsson, M., and F. Palombini, "OSCOAP Seitz, L., Palombini, F., and M. Gunnarsson, "OSCOAP
profile of ACE", draft-seitz-ace-oscoap-profile-03 (work profile of the Authentication and Authorization for
in progress), June 2017. Constrained Environments Framework", draft-seitz-ace-
oscoap-profile-04 (work in progress), July 2017.
[I-D.selander-ace-cose-ecdhe]
Selander, G., Mattsson, J., and F. Palombini, "Ephemeral
Diffie-Hellman Over COSE (EDHOC)", draft-selander-ace-
cose-ecdhe-06 (work in progress), April 2017.
[I-D.tiloca-core-multicast-oscoap] [I-D.tiloca-core-multicast-oscoap]
Tiloca, M., Selander, G., and F. Palombini, "Secure group Tiloca, M., Selander, G., and F. Palombini, "Secure group
communication for CoAP", draft-tiloca-core-multicast- communication for CoAP", draft-tiloca-core-multicast-
oscoap-01 (work in progress), March 2017. oscoap-03 (work in progress), July 2017.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>.
[RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand
Key Derivation Function (HKDF)", RFC 5869, Key Derivation Function (HKDF)", RFC 5869,
DOI 10.17487/RFC5869, May 2010, DOI 10.17487/RFC5869, May 2010,
<http://www.rfc-editor.org/info/rfc5869>. <https://www.rfc-editor.org/info/rfc5869>.
[RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for
Constrained-Node Networks", RFC 7228, Constrained-Node Networks", RFC 7228,
DOI 10.17487/RFC7228, May 2014, DOI 10.17487/RFC7228, May 2014,
<http://www.rfc-editor.org/info/rfc7228>. <https://www.rfc-editor.org/info/rfc7228>.
[RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
2015, <https://www.rfc-editor.org/info/rfc7515>.
Appendix A. Test Vectors Appendix A. Test Vectors
TODO: This section needs to be updated. TODO: This section needs to be updated.
Appendix B. Examples Appendix B. Examples
This section gives examples of OSCOAP. The message exchanges are This section gives examples of OSCORE. The message exchanges are
made, based on the assumption that there is a security context made, based on the assumption that there is a security context
established between client and server. For simplicity, these established between client and server. For simplicity, these
examples only indicate the content of the messages without going into examples only indicate the content of the messages without going into
detail of the COSE message format. detail of the COSE message format.
B.1. Secure Access to Sensor B.1. Secure Access to Sensor
This example targets the scenario in Section 3.1 of This example targets the scenario in Section 3.1 of
[I-D.hartke-core-e2e-security-reqs] and illustrates a client [I-D.hartke-core-e2e-security-reqs] and illustrates a client
requesting the alarm status from a server. requesting the alarm status from a server.
Client Proxy Server Client Proxy Server
| | | | | |
+----->| | Code: 0.01 (GET) +------>| | Code: 0.02 (POST)
| GET | | Token: 0x8c | POST | | Token: 0x8c
| | | Object-Security: [kid:5f, seq:42, | | | Object-Security: [kid:5f]
| | | {Uri-Path:"alarm_status"}] | | | Payload: [Partial IV:42,
| | | Payload: - | | | {Code:0.01,
| | | | | | Uri-Path:"alarm_status"}]
| +----->| Code: 0.01 (GET) | | |
| | GET | Token: 0x7b | +------>| Code: 0.02 (POST)
| | | Object-Security: [kid:5f, seq:42, | | POST | Token: 0x7b
| | | {Uri-Path:"alarm_status"}] | | | Object-Security: [kid:5f]
| | | Payload: - | | | Payload: [Partial IV:42,
| | | | | | {Code:0.01,
| |<-----+ Code: 2.05 (Content) | | | Uri-Path:"alarm_status"}]
| | 2.05 | Token: 0x7b | | |
| | | Object-Security: - | |<------+ Code: 2.04 (Changed)
| | | Payload: [{"OFF"}] | | 2.04 | Token: 0x7b
| | | | | | Object-Security: -
|<-----+ | Code: 2.05 (Content) | | | Payload: [{Code:2.05, "OFF"}]
| 2.05 | | Token: 0x8c | | |
| | | Object-Security: - |<------+ | Code: 2.04 (Changed)
| | | Payload: [{"OFF"}] | 2.04 | | Token: 0x8c
| | | | | | Object-Security: -
| | | Payload: [{Code:2.05, "OFF"}]
| | |
Figure 7: Secure Access to Sensor. Square brackets [ ... ] indicate Figure 9: Secure Access to Sensor. Square brackets [ ... ] indicate
a COSE object. Curly brackets { ... } indicate encrypted data. a COSE object. Curly brackets { ... } indicate encrypted data.
Since the method (GET) doesn't allow payload, the Object-Security The request/response Codes are encrypted by OSCORE and only dummy
option carries the COSE object as its value. Since the response code Codes (POST/Changed) are visible in the header of the OSCORE message.
(Content) allows payload, the COSE object is carried as the CoAP The option Uri-Path ("alarm_status") and payload ("OFF") are
payload. encrypted.
The COSE header of the request contains an identifier (5f), The COSE header of the request contains an identifier (5f),
indicating which security context was used to protect the message and indicating which security context was used to protect the message and
a sequence number (42). The option Uri-Path ("alarm_status") and a Partial IV (42).
payload ("OFF") are encrypted.
The server verifies that the sequence number has not been received The server verifies that the Partial IV has not been received before.
before. The client verifies that the response is bound to the The client verifies that the response is bound to the request.
request.
B.2. Secure Subscribe to Sensor B.2. Secure Subscribe to Sensor
This example targets the scenario in Section 3.2 of This example targets the scenario in Section 3.2 of
[I-D.hartke-core-e2e-security-reqs] and illustrates a client [I-D.hartke-core-e2e-security-reqs] and illustrates a client
requesting subscription to a blood sugar measurement resource (GET requesting subscription to a blood sugar measurement resource (GET
/glucose), first receiving the value 220 mg/dl and then a second /glucose), first receiving the value 220 mg/dl and then a second
value 180 mg/dl. value 180 mg/dl.
Client Proxy Server Client Proxy Server
| | | | | |
+----->| | Code: 0.01 (GET) +------>| | Code: 0.05 (FETCH)
| GET | | Token: 0x83 | FETCH | | Token: 0x83
| | | Observe: 0 | | | Observe: 0
| | | Object-Security: [kid:ca, seq:15, | | | Object-Security: [kid:ca]
| | | {Uri-Path:"glucose"}] | | | Payload: [Partial IV:15,
| | | Payload: - | | | {Code:0.01,
| | | | | | Uri-Path:"glucose"}]
| +----->| Code: 0.01 (GET) | | |
| | GET | Token: 0xbe | +------>| Code: 0.05 (FETCH)
| | | Observe: 0 | | FETCH | Token: 0xbe
| | | Object-Security: [kid:ca, seq:15, | | | Observe: 0
| | | {Uri-Path:"glucose"}] | | | Object-Security: [kid:ca]
| | | Payload: - | | | Payload: [Partial IV:15,
| | | | | | {Code:0.01,
| |<-----+ Code: 2.05 (Content) | | | Uri-Path:"glucose"}]
| | 2.05 | Token: 0xbe | | |
| | | Observe: 000032 | |<------+ Code: 2.05 (Content)
| | | Object-Security: - | | 2.05 | Token: 0xbe
| | | Payload: [seq:32, {Content-Format:0, "220"}] | | | Observe: 7
| | | | | | Object-Security: -
|<-----+ | Code: 2.05 (Content) | | | Payload: [Partial IV:32,
| 2.05 | | Token: 0x83 | | | {Code:2.05,
| | | Observe: 000032 | | | Content-Format:0, "220"}]
| | | Object-Security: - | | |
| | | Payload: [seq:32, {Content-Format:0, "220"}] |<------+ | Code: 2.05 (Content)
... ... ... | 2.05 | | Token: 0x83
| | | | | | Observe: 7
| |<-----+ Code: 2.05 (Content) | | | Object-Security: -
| | 2.05 | Token: 0xbe | | | Payload: [Partial IV:32,
| | | Observe: 000036 | | | {Code:2.05,
| | | Object-Security: - | | | Content-Format:0, "220"}]
| | | Payload: [seq:36, {Content-Format:0, "180"}] ... ... ...
| | | | | |
|<-----+ | Code: 2.05 (Content) | |<------+ Code: 2.05 (Content)
| 2.05 | | Token: 0x83 | | 2.05 | Token: 0xbe
| | | Observe: 000036 | | | Observe: 8
| | | Object-Security: - | | | Object-Security: -
| | | Payload: [seq:36, {Content-Format:0, "180"}] | | | Payload: [Partial IV:36,
| | | | | | {Code:2.05,
| | | Content-Format:0, "180"}]
| | |
|<------+ | Code: 2.05 (Content)
| 2.05 | | Token: 0x83
| | | Observe: 8
| | | Object-Security: -
| | | Payload: [Partial IV:36,
| | | {Code:2.05,
| | | Content-Format:0, "180"}]
| | |
Figure 8: Secure Subscribe to Sensor. Square brackets [ ... ] Figure 10: Secure Subscribe to Sensor. Square brackets [ ... ]
indicate a COSE object. Curly brackets { ... } indicate encrypted indicate a COSE object. Curly brackets { ... } indicate encrypted
data. data.
Since the method (GET) doesn't allow payload, the Object-Security The request/response Codes are encrypted by OSCORE and only dummy
option carries the COSE object as its value. Since the response code Codes (FETCH/Content) are visible in the header of the OSCORE
(Content) allows payload, the COSE object is carried as the CoAP message. The options Content-Format (0) and the payload ("220" and
payload. "180"), are encrypted.
The COSE header of the request contains an identifier (ca), The COSE header of the request contains an identifier (ca),
indicating the security context used to protect the message and a indicating the security context used to protect the message and a
Sequence Number (15). The COSE header of the responses contains Partial IV (15). The COSE headers of the responses contains Partial
sequence numbers (32 and 36). The options Content-Format (0) and the IVs (32 and 36).
payload ("220" and "180"), are encrypted. The Observe option is
integrity protected. The shown Observe values (000032 and 000036)
are the ones that the client will see after OSCOAP processing.
The server verifies that the sequence number has not been received
before. The client verifies that the sequence number has not been
received before and that the responses are bound to the request.
Appendix C. Object Security of Content (OSCON)
TODO: This section needs to be updated.
OSCOAP protects message exchanges end-to-end between a certain client
and a certain server, targeting the security requirements for forward
proxy of [I-D.hartke-core-e2e-security-reqs]. In contrast, many use
cases require one and the same message to be protected for, and
verified by, multiple endpoints, see caching proxy section of
[I-D.hartke-core-e2e-security-reqs]. Those security requirements can
be addressed by protecting essentially the payload/content of
individual messages using the COSE format ([I-D.ietf-cose-msg]),
rather than the entire request/response message exchange. This is
referred to as Object Security of Content (OSCON).
OSCON transforms a CoAP message into an "OSCON message" in the
following way: the payload of the original CoAP message is wrapped by
a COSE object, which replaces the payload and this then becomes the
OSCON message.
The original payload shall be the plaintext/payload of the COSE
object. The 'protected' field of the COSE object 'Headers' shall
include the context identifier, both for requests and responses. If
the original CoAP message includes a Content-Format option, then the
COSE object shall include a protected 'content type' field, whose
value is set to the original message Content-Format value. The
Content-Format option of the OSCOON message shall be replaced with
"application/oscon" (Section 12)
The COSE object shall be protected (encrypted) and verified
(decrypted) as described in ([I-D.ietf-cose-msg]).
Most AEAD algorithms require a unique nonce for each message.
Sequence numbers for partial IV as specified for OSCOAP may be used
for replay protection as described in Section 6. The use of time
stamps in the COSE header parameter 'operation time'
[I-D.ietf-cose-msg] for freshness may be used.
OSCON shall not be used in cases where CoAP header fields (such as
Code or Version) or CoAP options need to be integrity protected or
encrypted. OSCON shall not be used in cases which require a secure
binding between request and response.
The scenarios in Sections 3.3 - 3.5 of
[I-D.hartke-core-e2e-security-reqs] assume multiple recipients for a
particular content. In this case the use of symmetric keys does not
provide data origin authentication. Therefore the COSE object should
in general be protected with a digital signature.
C.1. Overhead OSCON
In general there are four different kinds of modes that need to be
supported: message authentication code, digital signature,
authenticated encryption, and symmetric encryption + digital
signature. The use of digital signature is necessary for
applications with many legitimate recipients of a given message, and
where data origin authentication is required.
To distinguish between these different cases, the tagged structures
of COSE are used (see Section 2 of [I-D.ietf-cose-msg]).
The sizes of COSE messages for selected algorithms are detailed in
this section.
The size of the header is shown separately from the size of the MAC/
signature. A 4-byte Context Identifier and a 1-byte Sequence Number
are used throughout all examples, with these values:
o Cid: 0xa1534e3c
o Seq: 0xa3
For each scheme, we indicate the fixed length of these two parameters
("Cid+Seq" column) and of the Tag ("MAC"/"SIG"/"TAG"). The "Message
OH" column shows the total expansions of the CoAP message size, while
the "COSE OH" column is calculated from the previous columns.
Overhead incurring from CBOR encoding is also included in the COSE
overhead count.
To make it easier to read, COSE objects are represented using CBOR's
diagnostic notation rather than a binary dump.
C.2. MAC Only
This example is based on HMAC-SHA256, with truncation to 8 bytes
(HMAC 256/64).
Since the key is implicitly known by the recipient, the
COSE_Mac0_Tagged structure is used (Section 6.2 of
[I-D.ietf-cose-msg]).
The object in COSE encoding gives:
996( # COSE_Mac0_Tagged
[
h'a20444a1534e3c0641a3', # protected:
{04:h'a1534e3c',
06:h'a3'}
{}, # unprotected
h'', # payload
MAC # truncated 8-byte MAC
]
)
This COSE object encodes to a total size of 26 bytes.
Figure 9 summarizes these results.
+------------------+-----+-----+---------+------------+
| Structure | Tid | MAC | COSE OH | Message OH |
+------------------+-----+-----+---------+------------+
| COSE_Mac0_Tagged | 5 B | 8 B | 13 B | 26 B |
+------------------+-----+-----+---------+------------+
Figure 9: Message overhead for a 5-byte Tid using HMAC 256/64
C.3. Signature Only
This example is based on ECDSA, with a signature of 64 bytes.
Since only one signature is used, the COSE_Sign1_Tagged structure is
used (Section 4.2 of [I-D.ietf-cose-msg]).
The object in COSE encoding gives:
997( # COSE_Sign1_Tagged
[
h'a20444a1534e3c0641a3', # protected:
{04:h'a1534e3c',
06:h'a3'}
{}, # unprotected
h'', # payload
SIG # 64-byte signature
]
)
This COSE object encodes to a total size of 83 bytes.
Figure 10 summarizes these results.
+-------------------+-----+------+---------+------------+
| Structure | Tid | SIG | COSE OH | Message OH |
+-------------------+-----+------+---------+------------+
| COSE_Sign1_Tagged | 5 B | 64 B | 14 B | 83 bytes |
+-------------------+-----+------+---------+------------+
Figure 10: Message overhead for a 5-byte Tid using 64 byte ECDSA
signature.
C.4. Authenticated Encryption with Additional Data (AEAD)
This example is based on AES-CCM with the Tag truncated to 8 bytes.
Since the key is implicitly known by the recipient, the
COSE_Encrypt0_Tagged structure is used (Section 5.2 of
[I-D.ietf-cose-msg]).
The object in COSE encoding gives:
993( # COSE_Encrypt0_Tagged
[
h'a20444a1534e3c0641a3', # protected:
{04:h'a1534e3c',
06:h'a3'}
{}, # unprotected
ciphertext # ciphertext including truncated 8-byte TAG
]
)
This COSE object encodes to a total size of 25 bytes.
Figure 11 summarizes these results.
+----------------------+-----+-----+---------+------------+
| Structure | Tid | TAG | COSE OH | Message OH |
+----------------------+-----+-----+---------+------------+
| COSE_Encrypt0_Tagged | 5 B | 8 B | 12 B | 25 bytes |
+----------------------+-----+-----+---------+------------+
Figure 11: Message overhead for a 5-byte Tid using AES_128_CCM_8.
C.5. Symmetric Encryption with Asymmetric Signature (SEAS)
This example is based on AES-CCM and ECDSA with 64 bytes signature.
The same assumption on the security context as in Appendix C.4. COSE
defines the field 'counter signature w/o headers' that is used here
to sign a COSE_Encrypt0_Tagged message (see Section 3 of
[I-D.ietf-cose-msg]).
The object in COSE encoding gives:
993( # COSE_Encrypt0_Tagged
[
h'a20444a1534e3c0641a3', # protected:
{04:h'a1534e3c',
06:h'a3'}
{9:SIG}, # unprotected:
09: 64 bytes signature
ciphertext # ciphertext including truncated 8-byte TAG
]
)
This COSE object encodes to a total size of 92 bytes.
Figure 12 summarizes these results.
+----------------------+-----+-----+------+---------+------------+
| Structure | Tid | TAG | SIG | COSE OH | Message OH |
+----------------------+-----+-----+------+---------+------------+
| COSE_Encrypt0_Tagged | 5 B | 8 B | 64 B | 15 B | 92 B |
+----------------------+-----+-----+------+---------+------------+
Figure 12: Message overhead for a 5-byte Tid using AES-CCM The server verifies that the Partial IV has not been received before.
countersigned with ECDSA. 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.
Authors' Addresses Authors' Addresses
Goeran Selander Goeran Selander
Ericsson AB Ericsson AB
Email: goran.selander@ericsson.com Email: goran.selander@ericsson.com
John Mattsson John Mattsson
Ericsson AB Ericsson AB
Email: john.mattsson@ericsson.com Email: john.mattsson@ericsson.com
Francesca Palombini Francesca Palombini
Ericsson AB Ericsson AB
Email: francesca.palombini@ericsson.com Email: francesca.palombini@ericsson.com
Ludwig Seitz Ludwig Seitz
SICS Swedish ICT SICS Swedish ICT
Email: ludwig@sics.se Email: ludwig@sics.se
 End of changes. 277 change blocks. 
1295 lines changed or deleted 1301 lines changed or added

This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/