draft-ietf-core-object-security-07.txt   draft-ietf-core-object-security-08.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: May 24, 2018 Ericsson AB Expires: July 26, 2018 Ericsson AB
L. Seitz L. Seitz
SICS Swedish ICT RISE SICS
November 20, 2017 January 22, 2018
Object Security for Constrained RESTful Environments (OSCORE) Object Security for Constrained RESTful Environments (OSCORE)
draft-ietf-core-object-security-07 draft-ietf-core-object-security-08
Abstract Abstract
This document defines Object Security for Constrained RESTful This document defines Object Security for Constrained RESTful
Environments (OSCORE), a method for application-layer protection of Environments (OSCORE), a method for application-layer protection of
the Constrained Application Protocol (CoAP), using CBOR Object the Constrained Application Protocol (CoAP), using CBOR Object
Signing and Encryption (COSE). OSCORE provides end-to-end Signing and Encryption (COSE). OSCORE provides end-to-end protection
encryption, integrity and replay protection, as well as a secure between endpoints communicating using CoAP or CoAP-mappable HTTP.
message binding. OSCORE is designed for constrained nodes and OSCORE is designed for constrained nodes and networks supporting a
networks and can be used whereever CoAP can be used, and also with range of proxy operations, including translation between different
HTTP. OSCORE may be used to protect group communications as is transport protocols.
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 https://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 May 24, 2018. This Internet-Draft will expire on July 26, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2017 IETF Trust and the persons identified as the Copyright (c) 2018 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
(https://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 . . . . . . . . . . . . . . . . . . . . . . . 5 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6
2. The CoAP Object-Security Option . . . . . . . . . . . . . . . 5 2. The CoAP Object-Security Option . . . . . . . . . . . . . . . 6
3. The Security Context . . . . . . . . . . . . . . . . . . . . 6 3. The Security Context . . . . . . . . . . . . . . . . . . . . 7
3.1. Security Context Definition . . . . . . . . . . . . . . . 6 3.1. Security Context Definition . . . . . . . . . . . . . . . 7
3.2. Establishment of Security Context Parameters . . . . . . 9 3.2. Establishment of Security Context Parameters . . . . . . 9
3.3. Requirements on the Security Context Parameters . . . . . 11 3.3. Requirements on the Security Context Parameters . . . . . 11
4. Protected Message Fields . . . . . . . . . . . . . . . . . . 11 4. Protected Message Fields . . . . . . . . . . . . . . . . . . 12
4.1. CoAP Payload . . . . . . . . . . . . . . . . . . . . . . 12 4.1. CoAP Payload . . . . . . . . . . . . . . . . . . . . . . 13
4.2. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 13 4.2. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 14
4.3. CoAP Header . . . . . . . . . . . . . . . . . . . . . . . 18 4.3. CoAP Header . . . . . . . . . . . . . . . . . . . . . . . 20
5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 19 4.4. Signaling Messages . . . . . . . . . . . . . . . . . . . 21
5.1. Kid Context . . . . . . . . . . . . . . . . . . . . . . . 20 5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 22
5.2. Nonce . . . . . . . . . . . . . . . . . . . . . . . . . . 21 5.1. Kid Context . . . . . . . . . . . . . . . . . . . . . . . 23
5.3. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 22 5.2. Nonce . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.4. Additional Authenticated Data . . . . . . . . . . . . . . 23 5.3. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 24
6. Sequence Numbers, Replay, Message Binding, and Freshness . . 23 5.4. Additional Authenticated Data . . . . . . . . . . . . . . 25
6.1. Message Binding . . . . . . . . . . . . . . . . . . . . . 23 6. OSCORE Compression . . . . . . . . . . . . . . . . . . . . . 26
6.2. AEAD Nonce Uniqueness . . . . . . . . . . . . . . . . . . 24 6.1. Encoding of the Object-Security Value . . . . . . . . . . 26
6.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 24 6.2. Encoding of the OSCORE Payload . . . . . . . . . . . . . 27
6.4. Replay Protection . . . . . . . . . . . . . . . . . . . . 24 6.3. Examples of Compressed COSE Objects . . . . . . . . . . . 28
6.5. Losing Part of the Context State . . . . . . . . . . . . 25 7. Sequence Numbers, Replay, Message Binding, and Freshness . . 29
7. Processing . . . . . . . . . . . . . . . . . . . . . . . . . 26 7.1. Message Binding . . . . . . . . . . . . . . . . . . . . . 29
7.1. Protecting the Request . . . . . . . . . . . . . . . . . 26 7.2. AEAD Nonce Uniqueness . . . . . . . . . . . . . . . . . . 29
7.2. Verifying the Request . . . . . . . . . . . . . . . . . . 27 7.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 30
7.3. Protecting the Response . . . . . . . . . . . . . . . . . 28 7.4. Replay Protection . . . . . . . . . . . . . . . . . . . . 30
7.4. Verifying the Response . . . . . . . . . . . . . . . . . 29 7.5. Losing Part of the Context State . . . . . . . . . . . . 31
8. OSCORE Compression . . . . . . . . . . . . . . . . . . . . . 30 8. Processing . . . . . . . . . . . . . . . . . . . . . . . . . 32
8.1. Encoding of the Object-Security Value . . . . . . . . . . 30 8.1. Protecting the Request . . . . . . . . . . . . . . . . . 32
8.2. Encoding of the OSCORE Payload . . . . . . . . . . . . . 32 8.2. Verifying the Request . . . . . . . . . . . . . . . . . . 33
8.3. Examples of Compressed COSE Objects . . . . . . . . . . . 32 8.3. Protecting the Response . . . . . . . . . . . . . . . . . 34
9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 33 8.4. Verifying the Response . . . . . . . . . . . . . . . . . 35
10. Proxy Operations . . . . . . . . . . . . . . . . . . . . . . 34 9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 36
10.1. CoAP-to-CoAP Forwarding Proxy . . . . . . . . . . . . . 34 10. Proxy and HTTP Operations . . . . . . . . . . . . . . . . . . 36
10.2. HTTP-to-CoAP Translation Proxy . . . . . . . . . . . . . 34 10.1. CoAP-to-CoAP Forwarding Proxy . . . . . . . . . . . . . 37
10.3. CoAP-to-HTTP Translation Proxy . . . . . . . . . . . . . 36 10.2. HTTP Processing . . . . . . . . . . . . . . . . . . . . 37
11. Security Considerations . . . . . . . . . . . . . . . . . . . 37 10.3. HTTP-to-CoAP Translation Proxy . . . . . . . . . . . . . 38
12. Privacy Considerations . . . . . . . . . . . . . . . . . . . 38 10.4. CoAP-to-HTTP Translation Proxy . . . . . . . . . . . . . 40
13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39 11. Security Considerations . . . . . . . . . . . . . . . . . . . 41
13.1. COSE Header Parameters Registry . . . . . . . . . . . . 39 11.1. End-to-end protection . . . . . . . . . . . . . . . . . 41
13.2. CoAP Option Numbers Registry . . . . . . . . . . . . . . 39 11.2. Security Context Establishment . . . . . . . . . . . . . 42
13.3. Header Field Registrations . . . . . . . . . . . . . . . 40 11.3. Replay Protection . . . . . . . . . . . . . . . . . . . 42
14. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 40 11.4. Cryptographic Considerations . . . . . . . . . . . . . . 42
15. References . . . . . . . . . . . . . . . . . . . . . . . . . 40 11.5. Message Fragmentation . . . . . . . . . . . . . . . . . 43
15.1. Normative References . . . . . . . . . . . . . . . . . . 40 11.6. Privacy Considerations . . . . . . . . . . . . . . . . . 43
15.2. Informative References . . . . . . . . . . . . . . . . . 41 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 44
Appendix A. Test Vectors . . . . . . . . . . . . . . . . . . . . 43 12.1. COSE Header Parameters Registry . . . . . . . . . . . . 44
Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 43 12.2. CoAP Option Numbers Registry . . . . . . . . . . . . . . 44
B.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 43 12.3. CoAP Signaling Option Numbers Registry . . . . . . . . . 45
B.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 44 12.4. Header Field Registrations . . . . . . . . . . . . . . . 45
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 46 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 45
13.1. Normative References . . . . . . . . . . . . . . . . . . 45
13.2. Informative References . . . . . . . . . . . . . . . . . 46
Appendix A. Scenario examples . . . . . . . . . . . . . . . . . 48
A.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 48
A.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 49
Appendix B. Deployment examples . . . . . . . . . . . . . . . . 51
B.1. Master Secret Used Once . . . . . . . . . . . . . . . . . 51
B.2. Master Secret Used Multiple Times . . . . . . . . . . . . 51
B.3. Client Aliveness . . . . . . . . . . . . . . . . . . . . 51
Appendix C. Test Vectors . . . . . . . . . . . . . . . . . . . . 52
C.1. Test Vector 1: Key Derivation with Master Salt . . . . . 52
C.2. Test Vector 2: Key Derivation without Master Salt . . . . 53
C.3. Test Vector 3: OSCORE Request, Client . . . . . . . . . . 54
C.4. Test Vector 4: OSCORE Request, Client . . . . . . . . . . 55
C.5. Test Vector 5: OSCORE Response, Server . . . . . . . . . 57
C.6. Test Vector 6: OSCORE Response with Partial IV, Server . 58
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 59
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 59
1. Introduction 1. Introduction
The Constrained Application Protocol (CoAP) is a web application The Constrained Application Protocol (CoAP) [RFC7252] is a web
protocol, designed for constrained nodes and networks [RFC7228]. application protocol, designed for constrained nodes and networks
CoAP specifies the use of proxies for scalability and efficiency, and [RFC7228], and may be mapped from HTTP [RFC8075]. CoAP specifies the
a mapping to HTTP is also specified [RFC8075]. CoAP [RFC7252] use of proxies for scalability and efficiency and references DTLS
references DTLS [RFC6347] for security. CoAP and HTTP proxies ([RFC6347]) for security. CoAP and HTTP proxies require (D)TLS to be
require (D)TLS to be terminated at the proxy. The proxy therefore terminated at the proxy. The proxy therefore not only has access to
not only has access to the data required for performing the intended the data required for performing the intended proxy functionality,
proxy functionality, but is also able to eavesdrop on, or manipulate but is also able to eavesdrop on, or manipulate any part of the
any part of the message payload and metadata, in transit between the message payload and metadata, in transit between the endpoints. The
endpoints. The proxy can also inject, delete, or reorder packets proxy can also inject, delete, or reorder packets since they are no
since they are no longer protected by (D)TLS. longer protected by (D)TLS.
This document defines the Object Security for Constrained RESTful This document defines the Object Security for Constrained RESTful
Environments (OSCORE) security protocol, protecting CoAP and CoAP- Environments (OSCORE) security protocol, protecting CoAP and CoAP-
mappable HTTP requests and responses end-to-end across intermediary mappable HTTP requests and responses end-to-end across intermediary
nodes such as CoAP forward proxies and cross-protocol translators nodes such as CoAP forward proxies and cross-protocol translators
including HTTP-to-CoAP proxies [RFC8075]. In addition to the core including HTTP-to-CoAP proxies [RFC8075]. In addition to the core
CoAP features defined in [RFC7252], OSCORE supports Observe CoAP features defined in [RFC7252], OSCORE supports Observe
[RFC7641], Blockwise [RFC7959], PATCH and FETCH [RFC8132]. An [RFC7641], Blockwise [RFC7959], No-Response [RFC7967], and PATCH and
analysis of end-to-end security for CoAP messages through some types FETCH [RFC8132]. An analysis of end-to-end security for CoAP
of intermediary nodes is performed in messages through some types of intermediary nodes is performed in
[I-D.hartke-core-e2e-security-reqs]. OSCORE protects the Request/ [I-D.hartke-core-e2e-security-reqs]. OSCORE essentially protects the
Response layer only, and not the CoAP Messaging Layer (Section 2 of RESTful interactions; the request method, the requested resource, the
[RFC7252]). Therefore, any Messaging Layer processing follows message payload, etc. (see Section 4). OSCORE does neither protect
the CoAP Messaging Layer nor the CoAP Token which may change between
the endpoints, and those are therefore processed as defined in
[RFC7252]. Additionally, since the message formats for CoAP over [RFC7252]. Additionally, since the message formats for CoAP over
unreliable transport [RFC7252] and for CoAP over reliable transport unreliable transport [RFC7252] and for CoAP over reliable transport
[I-D.ietf-core-coap-tcp-tls] differ only in terms of Messaging Layer, [I-D.ietf-core-coap-tcp-tls] differ only in terms of CoAP Messaging
OSCORE can be applied to both unreliable and reliable transports. Layer, OSCORE can be applied to both unreliable and reliable
transports (see Figure 1).
OSCORE is designed for constrained nodes and networks and provides an +-----------------------------------+
in-layer security protocol that does not depend on underlying layers. | Application |
OSCORE can be used anywhere where CoAP or HTTP can be used, including +-----------------------------------+
non-IP transports (e.g., [I-D.bormann-6lo-coap-802-15-ie]). An +-----------------------------------+ \
extension of OSCORE may also be used to protect group communication | Requests / Responses / Signaling | |
for CoAP [I-D.tiloca-core-multicast-oscoap]. The use of OSCORE does |-----------------------------------| |
not affect the URI scheme and OSCORE can therefore be used with any | OSCORE | | CoAP
URI scheme defined for CoAP or HTTP. The application decides the |-----------------------------------| |
conditions for which OSCORE is required. | Messaging Layer / Message Framing | |
+-----------------------------------+ /
+-----------------------------------+
| UDP / TCP / ... |
+-----------------------------------+
OSCORE builds on CBOR Object Signing and Encryption (COSE) [RFC8152], Figure 1: Abstract Layering of CoAP with OSCORE
providing end-to-end encryption, integrity, replay protection, and
secure the binding of response to request. A compressed version of OSCORE works in very constrained nodes and networks, thanks to its
COSE is used, as discussed in Section 8. The use of OSCORE is small message size and the restricted code and memory requirements in
signaled with the Object-Security CoAP option or HTTP header, defined addition to what is required by CoAP. Examples of the use of OSCORE
in Section 2 and Section 10.2. OSCORE is designed to protect as much are given in Appendix A. OSCORE does not depend on underlying
information as possible, while still allowing proxy operations layers, and can be used anywhere where CoAP or HTTP can be used,
(Section 10). OSCORE provides protection of message payload, almost including non-IP transports (e.g., [I-D.bormann-6lo-coap-802-15-ie]).
all CoAP options, and the RESTful method. The solution transforms a OSCORE may be used together with (D)TLS over one or more hops in the
message into an "OSCORE message" before sending, and vice versa after end-to-end path, e.g. with HTTPs in one hop and with plain CoAP in
receiving. The OSCORE message is related to the original message in another hop.
the following way: the original message is translated to CoAP (if not
already in CoAP) and the resulting message payload (if present), An extension of OSCORE may also be used to protect group
options not processed by a proxy, and the request/response method communication for CoAP [I-D.tiloca-core-multicast-oscoap]. The use
(CoAP Code) are protected in a COSE object. The message fields of of OSCORE does not affect the URI scheme and OSCORE can therefore be
the original message that are encrypted are transported in the used with any URI scheme defined for CoAP or HTTP. The application
payload of the OSCORE message, and the Object-Security option is decides the conditions for which OSCORE is required.
included, see Figure 1.
OSCORE uses pre-shared keys which may have been established out-of-
band or with a key establishment protocol (see Section 3.2). The
technical solution builds on CBOR Object Signing and Encryption
(COSE) [RFC8152], providing end-to-end encryption, integrity, replay
protection, and secure binding of response to request. A compressed
version of COSE is used, as specified in Section 6. The use of
OSCORE is signaled with the new Object-Security CoAP option or HTTP
header field, defined in Section 2 and Section 10.3. The solution
transforms a CoAP/HTTP message into an "OSCORE message" before
sending, and vice versa after receiving. The OSCORE message is a
CoAP/HTTP message related to the original message in the following
way: the original CoAP/HTTP message is translated to CoAP (if not
already in CoAP) and protected in a COSE object. The encrypted
message fields of this COSE object are transported in the CoAP
payload/HTTP body of the OSCORE message, and the Object-Security
option/header field is included in the message. A sketch of an
OSCORE message exchange in the case of the original message being
CoAP is provided in Figure 2).
Client Server Client Server
| OSCORE request - POST example.com: | | OSCORE request - POST example.com: |
| Header, Token, | | Header, Token, |
| Options: {Object-Security, ...}, | | Options: {Object-Security, ...}, |
| Payload: COSE ciphertext | | Payload: COSE ciphertext |
+--------------------------------------------->| +--------------------------------------------->|
| | | |
|<---------------------------------------------+ |<---------------------------------------------+
| OSCORE response - 2.04 (Changed): | | OSCORE response - 2.04 (Changed): |
| Header, Token, | | Header, Token, |
| Options: {Object-Security, ...}, | | Options: {Object-Security, ...}, |
| Payload: COSE ciphertext | | Payload: COSE ciphertext |
| | | |
Figure 1: Sketch of CoAP with OSCORE Figure 2: Sketch of CoAP with OSCORE
OSCORE may be used in very constrained settings, thanks to its small
message size and the restricted code and memory requirements in
addition to what is required by CoAP. OSCORE can be combined with
transport layer security such as DTLS or TLS, thereby enabling end-
to-end security of e.g. CoAP Payload, Options and Code, in
combination with hop-by-hop protection of the Messaging Layer, during
transport between end-point and intermediary node. Examples of the
use of OSCORE are given in Appendix B.
An implementation supporting this specification MAY only implement An implementation supporting this specification MAY only implement
the client part, MAY only implement the server part, or MAY only the client part, MAY only implement the server part, or MAY only
implement one of the proxy parts. OSCORE is designed to work with implement one of the proxy parts. OSCORE is designed to protect as
legacy CoAP-to-CoAP forward proxies [RFC7252], but an OSCORE-aware much information as possible while still allowing proxy operations
proxy will be more efficient. HTTP-to-CoAP proxies [RFC8075] and (Section 10). It works with legacy CoAP-to-CoAP forward proxies
CoAP-to-HTTP proxies need to implement respective parts of this [RFC7252], but an OSCORE-aware proxy will be more efficient. HTTP-
specification to work with OSCORE (see Section 10). to-CoAP proxies [RFC8075] and CoAP-to-HTTP proxies can also be used
with OSCORE, as specified in 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 [RFC8152], CBOR [RFC7049], CDDL [I-D.ietf-cbor-cddl], and COSE [RFC8152], CBOR [RFC7049], CDDL [I-D.ietf-cbor-cddl], and
constrained environments [RFC7228]. constrained environments [RFC7228].
The term "hop" is used to denote a particular leg in the end-to-end
path. The concept "hop-by-hop" (as in "hop-by-hop encryption" or
"hop-by-hop fragmentation") opposed to "end-to-end", is used in this
document to indicate that the messages are processed accordingly in
the intermediaries, rather than just forwarded to the next node.
The term "stop processing" is used throughout the document to denote
that the message is not passed up to the CoAP Request/Response layer
(see Figure 1).
The terms Common/Sender/Recipient Context, Master Secret/Salt, Sender The terms Common/Sender/Recipient Context, Master Secret/Salt, Sender
ID/Key, Recipient ID/Key, and Common IV are defined in Section 3.1. ID/Key, Recipient ID/Key, and Common IV are defined in Section 3.1.
2. The CoAP Object-Security Option 2. The CoAP Object-Security Option
The CoAP Object-Security option (see Figure 2) indicates that the The CoAP Object-Security option (see Figure 3) indicates that the
CoAP message is an OSCORE message and that it contains a compressed CoAP message is an OSCORE message and that it contains a compressed
COSE object (see Section 5 and Section 8). The Object-Security COSE object (see Section 5 and Section 6). The Object-Security
option is critical, safe to forward, part of the cache key, and not option is critical, safe to forward, part of the cache key, and not
repeatable. repeatable.
+-----+---+---+---+---+-----------------+--------+--------+---------+ +-----+---+---+---+---+-----------------+--------+--------+---------+
| No. | C | U | N | R | Name | Format | Length | Default | | No. | C | U | N | R | Name | Format | Length | Default |
+-----+---+---+---+---+-----------------+--------+--------+---------+ +-----+---+---+---+---+-----------------+--------+--------+---------+
| TBD | x | | | | Object-Security | (*) | 0-255 | (none) | | TBD | x | | | | Object-Security | (*) | 0-255 | (none) |
+-----+---+---+---+---+-----------------+--------+--------+---------+ +-----+---+---+---+---+-----------------+--------+--------+---------+
C = Critical, U = Unsafe, N = NoCacheKey, R = Repeatable C = Critical, U = Unsafe, N = NoCacheKey, R = Repeatable
(*) See below. (*) See below.
Figure 2: The Object-Security Option Figure 3: The Object-Security Option
The Object-Security option includes the OSCORE flag byte (Section 8), The Object-Security option includes the OSCORE flag bits (Section 6),
the Sender Sequence Number and the Sender ID when present the Sender Sequence Number and the Sender ID when present
(Section 3). The detailed format is specified in Section 8). If the (Section 3). The detailed format and length is specified in
OSCORE flag byte is all zero (0x00) the Option value SHALL be empty Section 6. If the OSCORE flag bits is all zero (0x00) the Option
(Option Length = 0). An endpoint receiving a CoAP message without value SHALL be empty (Option Length = 0). An endpoint receiving a
payload, that also contains an Object-Security option SHALL treat it CoAP message without payload, that also contains an Object-Security
as malformed and reject it. option SHALL treat it as malformed and reject it.
A successful response to a request with the Object-Security option A successful response to a request with the Object-Security option
SHALL contain the Object-Security option. Whether error responses SHALL contain the Object-Security option. Whether error responses
contain the Object-Security option depends on the error type (see contain the Object-Security option depends on the error type (see
Section 7). Section 8).
Since the payload and most options are encrypted Section 4, and the
corresponding plain text message fields of the original are not
included in the OSCORE message, the processing of these fields does
not expand the total message size.
A CoAP proxy SHOULD NOT cache a response to a request with an Object- A CoAP proxy SHOULD NOT cache a response to a request with an Object-
Security option, since the response is only applicable to the Security option, since the response is only applicable to the
original client's request, see Section 10.1. As the compressed COSE original request (see Section 10.1). As the compressed COSE Object
Object is included in the cache key, messages with the Object- is included in the cache key, messages with the Object-Security
Security option will never generate cache hits. For Max-Age option will never generate cache hits. For Max-Age processing (see
processing, see Section 4.2.3.1. Section 4.2.3.1).
3. The Security Context 3. The Security Context
OSCORE requires that client and server establish a shared security OSCORE requires that client and server establish a shared security
context used to process the COSE objects. OSCORE uses COSE with an context used to process the COSE objects. OSCORE uses COSE with an
Authenticated Encryption with Additional Data (AEAD) algorithm for Authenticated Encryption with Additional Data (AEAD) algorithm for
protecting message data between a client and a server. In this protecting message data between a client and a server. In this
section, we define the security context and how it is derived in section, we define the security context and how it is derived in
client and server based on a common shared master secret and a key client and server based on a shared secret and a key derivation
derivation function (KDF). 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 OSCORE. 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 and being derived from the Common Context and other data. Clients and
Servers need to be able to retrieve the correct security context to servers need to be able to retrieve the correct security context to
use. 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 Context of the other endpoint, and vice versa. Thus, the two
security contexts identified by the same IDs in the two endpoints are security contexts identified by the same IDs in the two endpoints are
not the same, but they are partly mirrored. Retrieval and use of the 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 4.
.-------------. .-------------. .-------------. .-------------.
| Common, | | Common, | | Common, | | Common, |
| Sender, | | Recipient, | | Sender, | | Recipient, |
| Recipient | | Sender | | Recipient | | Sender |
'-------------' '-------------' '-------------' '-------------'
Client Server Client Server
| | | |
Retrieve context for | OSCORE request: | Retrieve context for | OSCORE request: |
target resource | Token = Token1, | target resource | Token = Token1, |
skipping to change at page 7, line 31 skipping to change at page 8, line 26
| | RID = kid | | RID = kid
| | Verify request with | | Verify request with
| | Recipient Context | | Recipient Context
| OSCORE 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 4: Retrieval and use of the Security Context
The Common Context contains the following parameters: The Common Context contains the following parameters:
o AEAD Algorithm (alg). The COSE AEAD algorithm to use for o AEAD Algorithm. The COSE AEAD algorithm to use for encryption.
encryption. Its value is immutable once the security context is Its value is immutable once the security context is established.
established.
o Key Derivation Function. The HMAC based HKDF [RFC5869] used to o Key Derivation Function. The HMAC based HKDF [RFC5869] used to
derive Sender Key, Recipient Key, and Common IV. 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. Variable length byte string containing the salt used
the salt used to derive traffic keys and IVs. Its value is to derive traffic keys and IVs. Its value is immutable once the
immutable once the security context is established. security context is established.
o Common IV. Byte string derived from Master Secret and Master o Common IV. Byte string derived from Master Secret and Master
Salt. Length is determined by the AEAD Algorithm. Its value is Salt. Length is determined by the AEAD Algorithm. Its value is
immutable once the security context is established. immutable once the security context is established.
The Sender Context contains the following parameters: The Sender Context contains the following parameters:
o Sender ID. Byte string used to identify the Sender Context and to o Sender ID. Byte string used to identify the Sender Context and to
assure unique nonces. Maximum length is determined by the AEAD assure unique AEAD nonces. Maximum length is determined by the
Algorithm. Its value is immutable once the security context is AEAD Algorithm. Its value is immutable once the security context
established. 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 the AEAD Algorithm. Its value is Length is determined by the AEAD Algorithm. Its value is
immutable once the security context is established. immutable once the security context is established.
o Sender Sequence Number. Non-negative integer used by the sender o Sender Sequence Number. Non-negative integer used by the sender
to protect requests and Observe notifications. Used as "Partial to protect requests and Observe notifications. Used as 'Partial
IV" [RFC8152] to generate unique nonces for the AEAD. Maximum IV' [RFC8152] to generate unique nonces for the AEAD. Maximum
value is determined by the AEAD 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. Byte string used to identify the Recipient Context o Recipient ID. Byte string used to identify the Recipient Context
and to assure unique nonces. Maximum length is determined by the and to assure unique AEAD nonces. Maximum length is determined by
AEAD Algorithm. Its value is immutable once the security context the AEAD Algorithm. Its value is immutable once the security
is established. 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 AEAD Algorithm. Its value is Length is determined by the AEAD Algorithm. Its value is
immutable once the security context is established. immutable once the security context is established.
o Replay Window (Server only). The replay window to verify requests o Replay Window (Server only). The replay window to verify requests
received. received.
An endpoint may free up memory by not storing the Common IV, Sender An endpoint may free up memory by not storing the Common IV, Sender
Key, and Recipient Key, deriving them from the Master Key and Master Key, and Recipient Key, deriving them from the Master Key and Master
Salt when needed. Alternatively, an endpoint may free up memory by Salt when needed. Alternatively, an endpoint may free up memory 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.
Endpoints MAY operate in either or both roles as client and server Endpoints MAY operate as both client and server and use the same
and use the same security context for those roles. Independent of security context for those roles. Independent of being client or
being client or server, the endpoint protects messages to send using server, the endpoint protects messages to send using its Sender
its Sender Context, and verifies messages received using its Context, and verifies messages received using its Recipient Context.
Recipient Context. The endpoints MUST NOT change the Sender/ The endpoints MUST NOT change the Sender/Recipient ID when changing
Recipient ID when changing roles. In other words, changing the roles roles. In other words, changing the roles does not change the set of
does not change the set of keys to be used. keys to be used.
3.2. Establishment 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
* Default is AES-CCM-16-64-128 (COSE algorithm encoding: 10) * 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]) ([RFC6347])
All input parameters need to be known to and agreed on by both All input parameters need to be known to and agreed on by both
endpoints, but the replay window may be different in the two endpoints, but the replay window may be different in the two
endpoints. The replay window type and size is used by the client in endpoints. How the input parameters are pre-established, is
the processing of the Request-Tag [I-D.ietf-core-echo-request-tag]. application specific. The OSCORE profile of the ACE framework may be
How the input parameters are pre-established, is application used to establish the necessary input parameters
specific. The ACE framework may be used to establish the necessary ([I-D.ietf-ace-oscore-profile]), or a key exchange protocol such as
input parameters [I-D.ietf-ace-oauth-authz]. the TLS/DTLS handshake ([I-D.mattsson-ace-tls-oscore]) providing
forward secrecy. Other examples of deploying OSCORE are given in
Appendix B.
3.2.1. Derivation of Sender Key, Recipient Key, and Common 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, Recipient Key, and Common IV security context parameters Sender Key, Recipient Key, and Common IV
SHALL be derived from the input parameters using the HKDF, which SHALL be derived from the input parameters using the HKDF, which
consists 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]):
skipping to change at page 10, line 25 skipping to change at page 11, line 14
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 as defined above o IKM is the Master Secret as defined above
o info is a CBOR array consisting of: o info is a CBOR array consisting of:
info = [ info = [
id : bstr / nil, id : bstr,
alg : int / tstr, alg_aead : int / tstr,
type : tstr, type : tstr,
L : uint L : uint
] ]
where: where:
o id is the Sender ID or Recipient ID when deriving keys and nil o id is the Sender ID or Recipient ID when deriving keys and the
when deriving the Common IV. The encoding is described in empty string when deriving the Common IV. The encoding is
Section 5 described in Section 5.
o type is "Key" or "IV" o alg_aead is the AEAD Algorithm, encoded as defined in [RFC8152].
o L is the size of the key/IV for the AEAD algorithm used, in octets o type is "Key" or "IV". The label is an ASCII string, and does not
include a trailing NUL byte.
o L is the size of the key/IV for the AEAD algorithm used, in bytes.
For example, if the algorithm AES-CCM-16-64-128 (see Section 10.2 in 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 [RFC8152]) is used, the integer value for alg_aead is 10, the value
Common IV. 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 Sender Sequence Number is initialized to 0. The supported types The Sender Sequence Number is initialized to 0. The supported types
of 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. The default is DTLS-type replay and depends on how OSCORE is transported, see Section 7.4. The
protection with a window size of 32 initiated as described in default is DTLS-type replay protection with a window size of 32
Section 4.1.2.6 of [RFC6347]. initiated as described in 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 and Master Salt. When a contexts using the same Master Secret and Master Salt. When a
trusted third party assigns identifiers (e.g., using trusted third party assigns identifiers (e.g., using
[I-D.ietf-ace-oauth-authz]) or by using a protocol that allows the [I-D.ietf-ace-oauth-authz]) or by using a protocol that allows the
parties to negotiate locally unique identifiers in each endpoint, the parties to negotiate locally unique identifiers in each endpoint, the
Sender IDs can be very short. The maximum length of Sender ID is Sender IDs can be very short. The maximum length of Sender ID in
length of nonce subtracted by 6 bytes. For AES-CCM-16-64-128 the bytes equals the length of AEAD nonce minus 6. For AES-CCM-16-64-128
maximum length of Sender ID is 7 bytes. If Sender ID uniqueness the maximum length of Sender ID is 7 bytes. Sender IDs MAY be
cannot be guaranteed by construction, Sender IDs MUST be long uniformly random distributed byte strings if the probability of
uniformly random distributed byte strings such that the probability collisions is negligible.
of collisions is negligible.
If Sender ID uniqueness cannot be guaranteed by construction, Sender
IDs MUST be long uniformly random distributed byte strings such 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. The Client MAY provide a "kid context" parameter endpoint. The Client MAY provide a 'kid context' parameter
Section 5.1 to help the Server find the right context. (Section 5.1) to help the Server find the right context.
While the triple (Master Secret, Master Salt, Sender ID) MUST be While the triple (Master Secret, Master Salt, Sender ID) MUST be
unique, the same Master Salt MAY be used with several Master Secrets unique, the same Master Salt MAY be used with several Master Secrets
and the same Master Secret MAY be used with several Master Salts. and the same Master Secret MAY be used with several Master Salts.
4. Protected Message Fields 4. Protected Message Fields
OSCORE transforms a CoAP message (which may have been generated from OSCORE transforms a CoAP message (which may have been generated from
an HTTP message) into an OSCORE message, and vice versa. OSCORE an HTTP message) into an OSCORE message, and vice versa. OSCORE
protects as much of the original message as possible while still protects as much of the original message as possible while still
allowing certain proxy operations (see Section 10). This section allowing certain proxy operations (see Section 10). This section
defines how OSCORE protects the message fields and transfers them defines how OSCORE protects the message fields and transfers them
end-to-end between client and server (in any direction). end-to-end between client and server (in any direction).
The remainder of this section and later sections discuss the behavior The remainder of this section and later sections discuss the behavior
in terms of CoAP messages. If HTTP is used for a particular leg in in terms of CoAP messages. If HTTP is used for a particular hop in
the end-to-end path, then this section applies to the conceptual CoAP the end-to-end path, then this section applies to the conceptual CoAP
message that is mappable to/from the original HTTP message as message that is mappable to/from the original HTTP message as
discussed in Section 10. That is, an HTTP message is conceptually discussed in Section 10. That is, an HTTP message is conceptually
transformed to a CoAP message and then to an OSCORE message, and transformed to a CoAP message and then to an OSCORE message, and
similarly in the reverse direction. An actual implementation might similarly in the reverse direction. An actual implementation might
translate directly from HTTP to OSCORE without the intervening CoAP translate directly from HTTP to OSCORE without the intervening CoAP
representation. representation.
Protection of Signaling messages (Section 5 of
[I-D.ietf-core-coap-tcp-tls]) is specified in Section 4.4. The other
parts of this section target Request/Response messages.
Message fields of the CoAP message may be protected end-to-end Message fields of the CoAP message may be protected end-to-end
between CoAP client and CoAP server in different ways: 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.
The sending endpoint SHALL transfer Class E message fields in the The sending endpoint SHALL transfer Class E message fields in the
ciphertext of the COSE object in the OSCORE message. The sending ciphertext of the COSE object in the OSCORE message. The sending
endpoint SHALL include Class I message fields in the Additional endpoint SHALL include Class I message fields in the Additional
Authenticated Data (AAD) of the AEAD algorithm, allowing the Authenticated Data (AAD) of the AEAD algorithm, allowing the
receiving endpoint to detect if the value has changed in transfer. receiving endpoint to detect if the value has changed in transfer.
Class U message fields SHALL NOT be protected in transfer. Class I Class U message fields SHALL NOT be protected in transfer. Class I
and Class U message field values are transferred in the header or and Class U message field values are transferred in the header or
options part of the OSCORE message, which is visible to proxies. options part of the OSCORE message, which is visible to proxies.
Message fields not visible to proxies, i.e., transported in the Message fields not visible to proxies, i.e., transported in the
ciphertext of the COSE object, are called "Inner" (Class E). Message ciphertext of the COSE object, are called "Inner" (Class E). Message
fields transferred in the header or options part of the OSCORE fields transferred in the header or options part of the OSCORE
message, which is visible to proxies, are called "Outer" (Class I or message, which is visible to proxies, are called "Outer" (Class I or
U). There are currently no Class I options defined. U). There are currently no Class I options defined.
An OSCORE message may contain both an Inner and an Outer instance of An OSCORE message may contain both an Inner and an Outer instance of
a certain CoAP message field. Inner message fields are intended for a certain CoAP message field. Inner message fields are intended for
the receiving endpoint, whereas Outer message fields are intended for the receiving endpoint, whereas Outer message fields are used to
a proxy. Inner and Outer message fields are processed independently. support proxy operations. Inner and Outer message fields are
processed independently.
4.1. CoAP Payload 4.1. CoAP Payload
The CoAP Payload, if present in the original CoAP message, SHALL be The CoAP Payload, if present in the original CoAP message, SHALL be
encrypted and integrity protected and is thus an Inner message field. encrypted and integrity protected and is thus an Inner message field.
See Figure 4. See Figure 5.
+------------------+---+---+ +------------------+---+---+
| Field | E | U | | Field | E | U |
+------------------+---+---+ +------------------+---+---+
| Payload | x | | | Payload | x | |
+------------------+---+---+ +------------------+---+---+
E = Encrypt and Integrity Protect (Inner) E = Encrypt and Integrity Protect (Inner)
U = Unprotected (Outer) U = Unprotected (Outer)
Figure 4: Protection of CoAP Payload Figure 5: Protection of CoAP Payload
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 (Section 5.3) input to the COSE object. The into the plaintext (Section 5.3) input to the COSE object. The
receiving endpoint verifies and decrypts the COSE object, and 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 Options 4.2. CoAP Options
A summary of how options are protected is shown in Figure 5. Note A summary of how options are protected is shown in Figure 6. Note
that some options may have both Inner and Outer message fields which that some options may have both Inner and Outer message fields which
are protected accordingly. The options which require special are protected accordingly. The options which require special
processing are labelled with asterisks. processing are labelled with asterisks.
+-----+-----------------+---+---+ +-----+-----------------+---+---+
| No. | Name | E | U | | No. | Name | E | U |
+-----+-----------------+---+---+ +-----+-----------------+---+---+
| 1 | If-Match | x | | | 1 | If-Match | x | |
| 3 | Uri-Host | | x | | 3 | Uri-Host | | x |
| 4 | ETag | x | | | 4 | ETag | x | |
| 5 | If-None-Match | x | | | 5 | If-None-Match | x | |
| 6 | Observe | | * | | 6 | Observe | | * |
| 7 | Uri-Port | | x | | 7 | Uri-Port | | x |
| 8 | Location-Path | x | | | 8 | Location-Path | x | |
| TBD | Object-Security | | * | | TBD | Object-Security | | * |
| 11 | Uri-Path | x | | | 11 | Uri-Path | x | |
| 12 | Content-Format | x | | | 12 | Content-Format | x | |
| 14 | Max-Age | * | * | | 14 | Max-Age | * | * |
| 15 | Uri-Query | x | | | 15 | Uri-Query | x | |
| 17 | Accept | x | | | 17 | Accept | x | |
| 20 | Location-Query | x | | | 20 | Location-Query | x | |
| 23 | Block2 | * | * | | 23 | Block2 | * | * |
| 27 | Block1 | * | * | | 27 | Block1 | * | * |
| 28 | Size2 | * | * | | 28 | Size2 | * | * |
| 35 | Proxy-Uri | | * | | 35 | Proxy-Uri | | * |
| 39 | Proxy-Scheme | | x | | 39 | Proxy-Scheme | | x |
| 60 | Size1 | x | x | | 60 | Size1 | * | * |
+-----+-----------------+---+---+ | 258 | No-Response | * | * |
+-----+-----------------+---+---+
E = Encrypt and Integrity Protect (Inner) E = Encrypt and Integrity Protect (Inner)
U = Unprotected (Outer) U = Unprotected (Outer)
* = Special * = Special
Figure 5: Protection of CoAP Options Figure 6: Protection of CoAP Options
Options that are unknown or for which OSCORE processing is not Options that are unknown or for which OSCORE processing is not
defined SHALL be processed as class E (and no special processing). defined SHALL be processed as class E (and no special processing).
Specifications of new CoAP options SHOULD define how they are Specifications of new CoAP options SHOULD define how they are
processed with OSCORE. A new COAP option SHOULD be of class E unless processed with OSCORE. A new COAP option SHOULD be of class E unless
it requires proxy processing. it requires proxy processing.
4.2.1. Inner Options 4.2.1. Inner Options
Inner option message fields (class E) are used in a way analogous to Inner option message fields (class E) are used to communicate
communicating in a protected manner directly with the other endpoint. directly with the other endpoint.
The sending endpoint SHALL write the Inner option message fields The sending endpoint SHALL write the Inner option message fields
present in the original CoAP message into the plaintext of the COSE present in the original CoAP message into the plaintext of the COSE
object Section 5.3, and then remove the Inner option message fields object (Section 5.3), and then remove the Inner option message fields
from the OSCORE message. from the OSCORE message.
The processing of Inner option message fields by the receiving The processing of Inner option message fields by the receiving
endpoint is specified in Section 7.2 and Section 7.4. endpoint is specified in Section 8.2 and Section 8.4.
4.2.2. Outer Options 4.2.2. Outer Options
Outer option message fields (Class U or I) are used to support proxy Outer option message fields (Class U or I) are used to support proxy
operations. operations.
The sending endpoint SHALL include the Outer option message field The sending endpoint SHALL include the Outer option message field
present in the original message in the options part of the OSCORE present in the original message in the options part of the OSCORE
message. All Outer option message fields, including Object-Security, message. All Outer option message fields, including Object-Security,
SHALL be encoded as described in Section 3.1 of [RFC7252], where the SHALL be encoded as described in Section 3.1 of [RFC7252], where the
delta is the difference to the previously included Outer option delta is the difference to the previously included Outer option
message field. message field.
The processing of Outer options by the receiving endpoint is The processing of Outer options by the receiving endpoint is
specified in Section 7.2 and Section 7.4. specified in Section 8.2 and Section 8.4.
A procedure for integrity-protection-only of Class I option message A procedure for integrity-protection-only of Class I option message
fields is specified in Section 5.4. New CoAP options which are fields is specified in Section 5.4. New CoAP options which are
repeatable and of class I MUST specify that proxies MUST NOT change repeatable and of class I MUST specify that proxies MUST NOT change
the order of the option's occurrences. the order of the option's occurrences.
Note: There are currently no Class I option message fields defined. Note: There are currently no Class I option message fields defined.
4.2.3. Special Options 4.2.3. Special Options
Some options require special processing, marked with an asterisk '*' Some options require special processing, marked with an asterisk '*'
in Figure 5; the processing is specified in this section. in Figure 6; the processing is specified in this section.
4.2.3.1. Max-Age 4.2.3.1. Max-Age
An Inner Max-Age message field is used to specify the freshness (as An Inner Max-Age message field is used to indicate the maximum time a
defined in [RFC7252]) of the resource, end-to-end from the server to response may be cached by the client (as defined in [RFC7252]), end-
the client, taking into account that the option is not accessible to to-end from the server to the client, taking into account that the
proxies. The Inner Max-Age SHALL be processed by OSCORE as specified option is not accessible to proxies. The Inner Max-Age SHALL be
in Section 4.2.1. processed by OSCORE as specified in Section 4.2.1.
An Outer Max-Age message field is used to avoid unnecessary caching An Outer Max-Age message field is used to avoid unnecessary caching
of OSCORE error responses at OSCORE unaware intermediary nodes. A of OSCORE error responses at OSCORE unaware intermediary nodes. A
server MAY set a Class U Max-Age message field with value zero to server MAY set a Class U Max-Age message field with value zero to
OSCORE error responses described in Section 6.4, Section 7.2 and OSCORE error responses described in Section 7.4, Section 8.2 and
Section 7.4, which is then processed according to Section 4.2.2. Section 8.4, which is then processed according to Section 4.2.2.
Non-error OSCORE responses do not need to include a Max-Age option Successful OSCORE responses do not need to include an Outer Max-Age
since the responses are non-cacheable by construction (see option since the responses are non-cacheable by construction (see
Section 4.3). Section 4.3).
4.2.3.2. The Block Options 4.2.3.2. The Block Options
Blockwise [RFC7959] is an optional feature. An implementation MAY Blockwise [RFC7959] is an optional feature. An implementation MAY
support [RFC7252] and the Object-Security option without supporting support [RFC7252] and the Object-Security option without supporting
[RFC7959]. The Block options (Block1, Block2, Size1, Size2), when Blockwise. The Block options (Block1, Block2, Size1, Size2), when
Inner message fields, provide secure message fragmentation such that Inner message fields, provide secure message fragmentation such that
each fragment can be verified. The Block options, when Outer message each fragment can be verified. The Block options, when Outer message
fields, enables hop-by-hop fragmentation of the OSCORE message. fields, enables hop-by-hop fragmentation of the OSCORE message.
Inner and Outer block processing may have different performance Inner and Outer block processing may have different performance
properties depending on the underlying transport. The end-to-end properties depending on the underlying transport. The end-to-end
integrity of the message can be verified both in case of Inner and integrity of the message can be verified both in case of Inner and
Outer Blockwise provided all blocks are received (see Outer Blockwise provided all blocks are received.
Section 4.2.3.2.2).
4.2.3.2.1. Inner Block Options 4.2.3.2.1. Inner Block Options
The sending CoAP endpoint MAY fragment a CoAP message as defined in The sending CoAP endpoint MAY fragment a CoAP message as defined in
[RFC7959] before the message is processed by OSCORE. In this case [RFC7959] before the message is processed by OSCORE. In this case
the Block options SHALL be processed by OSCORE as Inner options the Block options SHALL be processed by OSCORE as Inner options
(Section 4.2.1). The receiving CoAP endpoint SHALL process the (Section 4.2.1). The receiving CoAP endpoint SHALL process the
OSCORE message according to Section 4.2.1 before processing blockwise OSCORE message according to Section 4.2.1 before processing Blockwise
as defined in [RFC7959]. as defined in [RFC7959].
For concurrent blockwise operations the sending endpoint MUST ensure For concurrent Blockwise operations the sending endpoint MUST ensure
that the receiving endpoint can distinguish between blocks from that the receiving endpoint can distinguish between blocks from
different operations. One mechanism enabling this is specified in different operations. One mechanism enabling this is specified in
[I-D.ietf-core-echo-request-tag]. [I-D.ietf-core-echo-request-tag].
4.2.3.2.2. Outer Block Options 4.2.3.2.2. Outer Block Options
Proxies MAY fragment an OSCORE message using [RFC7959], by Proxies MAY fragment an OSCORE message using [RFC7959], by
introducing Block option message fields that are Outer Section 4.2.2 introducing Block option message fields that are Outer
and not generated by the sending endpoint. Note that the Outer Block (Section 4.2.2) and not generated by the sending endpoint. Note that
options are neither encrypted nor integrity protected. As a the Outer Block options are neither encrypted nor integrity
consequence, a proxy can maliciously inject block fragments protected. As a consequence, a proxy can maliciously inject block
indefinitely, since the receiving endpoint needs to receive the last fragments indefinitely, since the receiving endpoint needs to receive
block (see [RFC7959]) to be able to compose the OSCORE message and the last block (see [RFC7959]) to be able to compose the OSCORE
verify its integrity. Therefore, applications supporting OSCORE and message and verify its integrity. Therefore, applications supporting
OSCORE and [RFC7959] MUST specify a security policy defining a
[RFC7959] MUST specify a security policy defining a maximum maximum unfragmented message size (MAX_UNFRAGMENTED_SIZE) considering
unfragmented message size (MAX_UNFRAGMENTED_SIZE) considering the the maximum size of message which can be handled by the endpoints.
maximum size of message which can be handled by the endpoints.
Messages exceeding this size SHOULD be fragmented by the sending Messages exceeding this size SHOULD be fragmented by the sending
endpoint using Inner Block options (Section 4.2.3.2.1). endpoint using Inner Block options (Section 4.2.3.2.1).
An endpoint receiving an OSCORE 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 OSCORE message have been received, or the cumulated blocks of the OSCORE message have been received, or the cumulated
message size of the blocks exceeds MAX_UNFRAGMENTED_SIZE. In the message size of the blocks exceeds MAX_UNFRAGMENTED_SIZE. In the
former case, the processing of the OSCORE message continues as former case, the processing of the OSCORE message continues as
defined in this document. In the latter case the message SHALL be defined in this document. In the latter case the message SHALL be
discarded. discarded.
To allow multiple concurrent request operations to the same server Because of encryption of Uri-Path and Uri-Query, messages to the same
(not only same resource), a CoAP proxy SHOULD follow the Request-Tag server may, from the point of view of a proxy, look like they also
processing specified in section 3.3.2 of target the same resource. A proxy SHOULD mitigate a potential mix-up
of blocks from concurrent requests to the same server, for example
using the Request-Tag processing specified in Section 3.3.2 of
[I-D.ietf-core-echo-request-tag]. [I-D.ietf-core-echo-request-tag].
4.2.3.3. Proxy-Uri 4.2.3.3. Proxy-Uri
Proxy-Uri, when present, is split by OSCORE 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 SHALL be protected and Uri-Path and Uri-Query are class E options and SHALL be protected and
processed as Inner options (Section 4.2.1). processed as Inner options (Section 4.2.1).
The Proxy-Uri option of the OSCORE message SHALL be set to the The Proxy-Uri option of the OSCORE message SHALL be set to the
composition of Proxy-Scheme, Uri-Host and Uri-Port options (if composition of Proxy-Scheme, Uri-Host, and Uri-Port options (if
present) as specified in section 6.5 of [RFC7252], and processed as present) as specified in Section 6.5 of [RFC7252], and processed as
an Outer option of Class U (Section 4.2.2). an Outer option of Class U (Section 4.2.2).
Note that replacing the Proxy-Uri value with the Proxy-Scheme and 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 Uri-* options works by design for all CoAP URIs (see Section 6 of
[RFC7252]. OSCORE-aware HTTP servers should not use the userinfo [RFC7252]). OSCORE-aware HTTP servers should not use the userinfo
component of the HTTP URI (as defined in section 3.2.1 of [RFC3986]), 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- so that this type of replacement is possible in the presence of CoAP-
to-HTTP proxies. In other documents specifying cross-protocol to-HTTP proxies. In future documents specifying cross-protocol
proxying behavior using different URI structures, it is expected that proxying behavior using different URI structures, it is expected that
the authors will create Uri-* options that allow decomposing the the authors will create Uri-* options that allow decomposing the
Proxy-Uri, and specify in which OSCORE class they belong. 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 OSCORE processing, Proxy-Uri is split into:
skipping to change at page 17, line 29 skipping to change at page 18, line 29
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.2.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 OSCORE 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"
See Section 6.1 and 12.6 of [RFC7252] for more information. See Sections 6.1 and 12.6 of [RFC7252] for more information.
4.2.3.4. Observe 4.2.3.4. Observe
Observe [RFC7641] is an optional feature. An implementation MAY Observe [RFC7641] is an optional feature. An implementation MAY
support [RFC7252] and the Object-Security option without supporting support [RFC7252] and the Object-Security option without supporting
[RFC7641]. The Observe option as used here targets the requirements [RFC7641]. The Observe option as used here targets the requirements
on forwarding of [I-D.hartke-core-e2e-security-reqs] on forwarding of [I-D.hartke-core-e2e-security-reqs] (Section 2.2.1).
(Section 2.2.1.2).
In order for an OSCORE-unaware proxy to support forwarding of Observe In order for an OSCORE-unaware proxy to support forwarding of Observe
messages ([RFC7641]), there SHALL be an Outer Observe option, i.e., messages ([RFC7641]), there SHALL be an Outer Observe option, i.e.,
present in the options part of the OSCORE message. The processing of present in the options part of the OSCORE message. The processing of
the CoAP Code for Observe messages is described in Section 4.3. the CoAP Code for Observe messages is described in Section 4.3.
To secure the order of notifications, the client SHALL maintain a To secure the order of notifications, the client SHALL maintain a
Notification Number for each Observation it registers. The Notification Number for each Observation it registers. The
Notification Number is a non-negative integer containing the largest Notification Number is a non-negative integer containing the largest
Partial IV of the successfully received notifications for the Partial IV of the successfully received notifications for the
associated Observe registration, see Section 6.4. The Notification associated Observe registration (see Section 7.4). The Notification
Number is initialized to the Partial IV of the first successfully Number is initialized to the Partial IV of the first successfully
received notification response to the registration request. In received notification response to the registration request. In
contrast to [RFC7641], the received Partial IV MUST always be contrast to [RFC7641], the received Partial IV MUST always be
compared with the Notification Number, which thus MUST NOT be compared with the Notification Number, which thus MUST NOT be
forgotten after 128 seconds. forgotten after 128 seconds. The client MAY ignore the Observe
option value.
If the verification fails, the client SHALL stop processing the If the verification fails, the client SHALL stop processing the
response. The client MAY ignore the Observe option value. response.
The Observe option in the CoAP request may be legitimately removed by The Observe option in the CoAP request may be legitimately removed by
a proxy. If the Observe option is removed from a CoAP request by a 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 proxy, then the server can still verify the request (as a non-Observe
request), and produce a non-Observe response. If the OSCORE client request), and produce a non-Observe response. If the OSCORE client
receives a response to an Observe request without an outer Observe receives a response to an Observe request without an Outer Observe
value, then it MUST verify the response as a non-Observe response. value, then it MUST verify the response as a non-Observe response.
(The reverse case is covered in the verification of the response, see If the OSCORE client receives a response to a non-Observe request
Section 7.) with an Outer Observe value, it stops processing the message, as
specified in Section 8.4.
4.2.3.5. Object-Security Clients can re-register observations to ensure that the observation
is still active and establish freshness again ([RFC7641]
Section 3.3.1). When an OSCORE observation is refreshed, not only
the ETags, but also the partial IV (and thus the payload and Object-
Security option) change. The server uses the new request's Partial
IV as the 'request_piv' of new responses.
4.2.3.5. No-Response
No-Response is defined in [RFC7967]. Clients using No-Response MUST
set both an Inner (Class E) and an Outer (Class U) No-Response
option, with same value.
The Inner No-Response option is used to communicate to the server the
client's disinterest in certain classes of responses to a particular
request. The Inner No-Response SHALL be processed by OSCORE as
specified in Section 4.2.1.
The Outer No-Response option is used to support proxy functionality,
specifically to avoid error transmissions from proxies to clients,
and to avoid bandwidth reduction to servers by proxies applying
congestion control when not receiving responses. The Outer No-
Response option is processed according to Section 4.2.2.
In particular, step 8 of Section 8.4 is applied to No-Response.
Applications should consider that a proxy may remove the Outer No-
Response option from the request. Applications using No-Response can
specify policies to deal with cases where servers receive an Inner
No-Response option only, which may be the result of the request
having traversed a No-Response unaware proxy, and update the
processing in Section 8.4 accordingly. This avoids unnecessary error
responses to clients and bandwidth reductions to servers, due to No-
Response unaware proxies.
4.2.3.6. Object-Security
The Object-Security option is only defined to be present in OSCORE The Object-Security option is only defined to be present in OSCORE
messages, as an indication that OSCORE processing have been messages, as an indication that OSCORE processing have been
performed. The content in the Object-Security option is neither performed. The content in the Object-Security option is neither
encrypted nor inegrity protected as a whole but some part of the encrypted nor integrity protected as a whole but some part of the
content of this option is protected, see Section 5.4. "OSCORE over content of this option is protected (see Section 5.4). "OSCORE
OSCORE" is not supported: If OSCORE processing detects an OSCORE within OSCORE" is not supported: If OSCORE processing detects an
option in the original CoAP message, then processing SHALL be Object-Security option in the original CoAP message, then processing
stopped. SHALL be stopped.
4.3. CoAP Header 4.3. CoAP Header
A summary of how the CoAP Header fields are protected is shown in A summary of how the CoAP Header fields are protected is shown in
Figure 6. Figure 7, including fields specific to CoAP over UDP and CoAP over
TCP (marked accordingly in the table).
+------------------+---+---+ +------------------+---+---+
| Field | E | U | | Field | E | U |
+------------------+---+---+ +------------------+---+---+
| Version (UDP) | | x | | Version (UDP) | | x |
| Type (UDP) | | x | | Type (UDP) | | x |
| Length (TCP) | | x | | Length (TCP) | | x |
| Token Length | | x | | Token Length | | x |
| Code | x | | | Code | x | |
| Message ID (UDP) | | x | | Message ID (UDP) | | x |
| Token | | x | | Token | | x |
+------------------+---+---+ +------------------+---+---+
E = Encrypt and Integrity Protect (Inner) E = Encrypt and Integrity Protect (Inner)
U = Unprotected (Outer) U = Unprotected (Outer)
Figure 6: Protection of CoAP Header Fields Figure 7: Protection of CoAP Header Fields
Most CoAP Header fields (i.e. the message fields in the fixed 4-byte Most CoAP Header fields (i.e. the message fields in the fixed 4-byte
header) are required to be read and/or changed by CoAP proxies and header) are required to be read and/or changed by CoAP proxies and
thus cannot in general be protected end-to-end between the endpoints. thus cannot in general be protected end-to-end between the endpoints.
As mentioned in Section 1, OSCORE protects the CoAP Request/Response As mentioned in Section 1, OSCORE protects the CoAP Request/Response
layer only, and not the Messaging Layer (Section 2 of [RFC7252]), so layer only, and not the Messaging Layer (Section 2 of [RFC7252]), so
fields such as Type and Message ID are not protected with OSCORE. fields such as Type and Message ID are not protected with OSCORE.
The CoAP Header field Code is protected by OSCORE. Code SHALL be The CoAP Header field Code is protected by OSCORE. Code SHALL be
encrypted and integrity protected (Class E) to prevent an encrypted and integrity protected (Class E) to prevent an
intermediary from eavesdropping or manipulating the Code (e.g., intermediary from eavesdropping or manipulating the Code (e.g.,
changing from GET to DELETE). changing from GET to DELETE).
The sending endpoint SHALL write the Code of the original CoAP The sending endpoint SHALL write the Code of the original CoAP
message into the plaintext of the COSE object Section 5.3. After message into the plaintext of the COSE object (see Section 5.3).
that, the Outer Code of the OSCORE message SHALL be set to 0.02 After that, the Outer Code of the OSCORE message SHALL be set to 0.02
(POST) for requests without Observe option, to 0.05 (FETCH) for (POST) for requests without Observe option, to 0.05 (FETCH) for
requests with Observe option, and to 2.04 (Changed) for responses. requests with Observe option, and to 2.04 (Changed) for responses.
Using FETCH with Observe allows OSCORE to be compliant with the Using FETCH with Observe allows OSCORE to be compliant with the
Observe processing in OSCORE-unaware proxies. The choice of POST and Observe processing in OSCORE-unaware proxies. The choice of POST and
FETCH ([RFC8132]) allows all OSCORE messages to have payload. FETCH ([RFC8132]) allows all OSCORE messages to have payload.
The receiving endpoint SHALL discard the Code in the OSCORE message The receiving endpoint SHALL discard the Code in the OSCORE message
and write the Code of the Plaintext in the COSE object (Section 5.3) and write the Code of the plaintext in the COSE object (Section 5.3)
into the decrypted CoAP message. into the decrypted CoAP message.
The other CoAP Header fields are Unprotected (Class U). The sending The other CoAP Header fields are Unprotected (Class U). The sending
endpoint SHALL write all other header fields of the original message endpoint SHALL write all other header fields of the original message
into the header of the OSCORE message. The receiving endpoint SHALL into the header of the OSCORE message. The receiving endpoint SHALL
write the header fields from the received OSCORE message into the write the header fields from the received OSCORE message into the
header of the decrypted CoAP message. header of the decrypted CoAP message.
4.4. Signaling Messages
Signaling messages (CoAP Code 7.00-7.31) were introduced to exchange
information related to an underlying transport connection in the
specific case of CoAP over reliable transports
([I-D.ietf-core-coap-tcp-tls]). The use of OSCORE for protecting
Signaling is application dependent.
OSCORE MAY be used to protect Signaling if the endpoints for OSCORE
coincide with the endpoints for the connection. If OSCORE is used to
protect Signaling then:
o Signaling messages SHALL be protected as CoAP Request messages,
except in the case the Signaling message is a response to a
previous Signaling message, in which case it SHALL be protected as
a CoAP Response message. For example, 7.02 (Ping) is protected as
a CoAP Request and 7.03 (Pong) as a CoAP response.
o The Outer Code for Signaling messages SHALL be set to 0.02 (POST),
unless it is a response to a previous Signaling message, in which
case it SHALL be set to 2.04 (Changed).
o All Signaling options, except the Object-Security option, SHALL be
Inner (Class E).
NOTE: Option numbers for Signaling messages are specific to the CoAP
Code (see Section 5.2 of [I-D.ietf-core-coap-tcp-tls]).
If OSCORE is not used to protect Signaling, Signaling messages SHALL
be unaltered by OSCORE.
5. The COSE Object 5. The COSE Object
This section defines how to use COSE [RFC8152] to wrap and protect This section defines how to use COSE [RFC8152] to wrap and protect
data in the original message. OSCORE uses the untagged COSE_Encrypt0 data in the original message. OSCORE uses the untagged COSE_Encrypt0
structure with an Authenticated Encryption with Additional Data structure with an Authenticated Encryption with Additional Data
(AEAD) algorithm. The key lengths, IV length, nonce length, and (AEAD) algorithm. The key lengths, IV length, nonce length, and
maximum Sender Sequence Number are algorithm dependent. maximum Sender Sequence Number are algorithm dependent.
The AEAD algorithm AES-CCM-16-64-128 defined in Section 10.2 of 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 [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 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 nonce and Common IV is 13 bytes. The maximum Sender Sequence Number
is specified in Section 11. is specified in Section 11.
We denote by Plaintext the data that is encrypted and integrity As specified in [RFC5116], plaintext denotes the data that is
protected, and by Additional Authenticated Data (AAD) the data that encrypted and integrity protected, and Additional Authenticated Data
is integrity protected only. (AAD) denotes the data that 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 Sender * The 'Partial IV' parameter. The value is set to the Sender
Sequence Number. All leading zeroes SHALL be removed when Sequence Number. All leading zeroes SHALL be removed when
encoding the Partial IV. The value 0 encodes to the byte encoding the Partial IV. The value 0 encodes to the byte
string 0x00. This parameter SHALL be present in requests. In string 0x00. This parameter SHALL be present in requests. In
case of Observe (Section 4.2.3.4) the Partial IV SHALL be case of Observe (Section 4.2.3.4) the Partial IV SHALL be
present in responses, and otherwise the Partial IV SHOULD NOT present in responses, and otherwise the Partial IV SHOULD NOT
be present in responses. (A non-Observe example where the be present in responses. (A non-Observe example where the
Partial IV is included in a response is provided in Partial IV is included in a response is provided in
Section 6.5.2.) Section 7.5.2.)
* The "kid" parameter. The value is set to the Sender ID. This * The 'kid' parameter. The value is set to the Sender ID. This
parameter SHALL be present in requests and SHOULD NOT be parameter SHALL be present in requests and SHOULD NOT be
present in responses. (An example where the Sender ID is present in responses. An example where the Sender ID is
included in a response is the extension of OSCORE to group included in a response is the extension of OSCORE to group
communication [I-D.tiloca-core-multicast-oscoap].) communication [I-D.tiloca-core-multicast-oscoap].
* Optionally, a "kid context" parameter as defined in * Optionally, a 'kid context' parameter as defined in
Section 5.1. This parameter MAY be present in requests and Section 5.1. This parameter MAY be present in requests and
SHALL NOT be present in responses. SHALL NOT be present in responses.
o The "ciphertext" field is computed from the secret key (Sender Key o The 'ciphertext' field is computed from the secret key (Sender Key
or Recipient Key), Nonce (see Section 5.2), Plaintext (see or Recipient Key), AEAD nonce (see Section 5.2), plaintext (see
Section 5.3), and the Additional Authenticated Data (AAD) (see Section 5.3), and the Additional Authenticated Data (AAD) (see
Section 5.4) following Section 5.2 of [RFC8152]. Section 5.4) following Section 5.2 of [RFC8152].
The encryption process is described in Section 5.3 of [RFC8152]. The encryption process is described in Section 5.3 of [RFC8152].
5.1. Kid Context 5.1. Kid Context
For certain use cases, e.g. deployments where the same "kid" is used For certain use cases, e.g. deployments where the same 'kid' is used
with multiple contexts, it is necessary or favorable for the sender with multiple contexts, it is necessary or favorable for the sender
to provide an additional identifier of the security material to use, to provide an additional identifier of the security material to use,
in order for the receiver to retrieve or establish the correct key. in order for the receiver to retrieve or establish the correct key.
The "kid context" parameter is used to provide such additional input. The 'kid context' parameter is used to provide such additional input.
The "kid context" is implicitly integrity protected, as manipulation The 'kid context' is implicitly integrity protected, as manipulation
that leads to the wrong key (or no key) being retrieved which results that leads to the wrong key (or no key) being retrieved which results
in an error, as described in Section 7.2. in an error, as described in Section 8.2.
A summary of the COSE header parameter "kid context" defined above A summary of the COSE header parameter 'kid context' defined above
can be found in Figure 7. can be found in Figure 8.
Some examples of relevant uses of kid context are the following: Some examples of relevant uses of kid context are the following:
o If the client has an identifier in some other namespace which can o If the client has an identifier in some other namespace which can
be used by the server to retrieve or establish the security be used by the server to retrieve or establish the security
context, then that identifier can be used as kid context. The kid context, then that identifier can be used as kid context. The kid
context may be used as Master Salt Section 3.1 for additional context may be used as Master Salt (Section 3.1) for additional
entropy of the security contexts, see for example entropy of the security contexts (see for example
[I-D.ietf-6tisch-minimal-security]. [I-D.ietf-6tisch-minimal-security]).
o In case of a group communication scenario o In case of a group communication scenario
[I-D.tiloca-core-multicast-oscoap], if the server belongs to [I-D.tiloca-core-multicast-oscoap], if the server belongs to
multiple groups, then a group identifier can be used as kid multiple groups, then a group identifier can be used as kid
context to enable the server to find the right security context. context to enable the server to find the right security context.
+----------+--------+------------+----------------+-----------------+ +----------+--------+------------+----------------+-----------------+
| name | label | value type | value registry | description | | name | label | value type | value registry | description |
+----------+--------+------------+----------------+-----------------+ +----------+--------+------------+----------------+-----------------+
| kid | kidctx | bstr | | Identifies the | | kid | kidctx | bstr | | Identifies the |
| context | | | | kid context | | context | | | | kid context |
+----------+--------+------------+----------------+-----------------+ +----------+--------+------------+----------------+-----------------+
Figure 7: Additional common header parameter for the COSE object Figure 8: Additional common header parameter for the COSE object
5.2. Nonce 5.2. Nonce
The nonce is constructed in the following way (see Figure 8): The AEAD nonce is constructed in the following way (see Figure 9):
1. left-padding the Partial IV (in network byte order) with zeroes 1. left-padding the Partial IV (in network byte order) with zeroes
to exactly 5 bytes, to exactly 5 bytes,
2. left-padding the (Sender) ID of the endpoint that generated the 2. left-padding the (Sender) ID of the endpoint that generated the
Partial IV (in network byte order) with zeroes to exactly nonce Partial IV (in network byte order) with zeroes to exactly nonce
length - 6 bytes, length - 6 bytes,
3. concatenating the size of the ID (S) with the padded ID and the 3. concatenating the size of the ID (S) with the padded ID and the
padded Partial IV, padded Partial IV,
4. and then XORing with the Common IV. 4. and then XORing with the Common IV.
Note that in this specification only algorithms that use nonces equal Note that in this specification only algorithms that use nonces equal
or greater than 7 bytes are supported. or greater than 7 bytes are supported. The nonce construction with
S, ID of PIV generator, and Partial IV together with endpoint unique
IDs and encryption keys make it easy to verify that the nonces used
with a specific key will be unique.
When observe is not used, the request and the response may use the When Observe is not used, the request and the response may use the
same nonce. In this way, the Partial IV does not have to be sent in same nonce. In this way, the Partial IV does not have to be sent in
responses, which reduces the size. For processing instructions, see responses, which reduces the size. For processing instructions (see
Section 7. Section 8).
+---+-----------------------+--+--+--+--+--+ +---+-----------------------+--+--+--+--+--+
| S | ID of PIV generator | Partial IV |----+ | S | ID of PIV generator | Partial IV |----+
+---+-----------------------+--+--+--+--+--+ | +---+-----------------------+--+--+--+--+--+ |
| |
+------------------------------------------+ | +------------------------------------------+ |
| Common IV |->(XOR) | Common IV |->(XOR)
+------------------------------------------+ | +------------------------------------------+ |
| |
+------------------------------------------+ | +------------------------------------------+ |
| Nonce |<---+ | Nonce |<---+
+------------------------------------------+ +------------------------------------------+
Figure 8: AEAD Nonce Formation Figure 9: AEAD Nonce Formation
5.3. Plaintext 5.3. Plaintext
The Plaintext is formatted as a CoAP message without Header (see The plaintext is formatted as a CoAP message without Header (see
Figure 9) consisting of: Figure 10) consisting of:
o the Code of the original CoAP message as defined in Section 3 of o the Code of the original CoAP message as defined in Section 3 of
[RFC7252]; and [RFC7252]; and
o all Inner option message fields (see Section 4.2.1) present in 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 original CoAP message (see Section 4.2). The options are encoded
as described in Section 3.1 of [RFC7252], where the delta is the 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
skipping to change at page 22, line 45 skipping to change at page 25, line 23
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Code | 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 9: Plaintext Figure 10: Plaintext
NOTE: The Plaintext contains all CoAP data that needs to be encrypted NOTE: The plaintext contains all CoAP data that needs to be encrypted
end-to-end between the endpoints. end-to-end between the endpoints.
5.4. Additional Authenticated Data 5.4. 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 = [
version : uint, oscore_version : uint,
alg : int / tstr, [alg_aead : int / tstr],
request_kid : bstr, request_kid : bstr,
request_piv : bstr, request_piv : bstr,
options : bstr options : bstr
] ]
where: where:
o version: contains the OSCORE version number. Implementations of o oscore_version: contains the OSCORE version number.
this specification MUST set this field to 1. Other values are Implementations of this specification MUST set this field to 1.
reserved for future versions. Other values are reserved for future versions.
o alg: contains the AEAD Algorithm from the security context used o alg_aead: contains the AEAD Algorithm from the security context
for the exchange (see Section 3.1). used 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_piv: 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 Class I options (see Section 4.2.2) present o options: contains the Class I options (see Section 4.2.2) present
in the original CoAP message encoded as described in Section 3.1 in the original CoAP message encoded as described in Section 3.1
of [RFC7252], where the delta is the difference to the previously of [RFC7252], where the delta is the difference to the previously
included class I option. included class I option.
NOTE: The format of the external_aad is for simplicity the same for NOTE: The format of the external_aad is for simplicity the same for
requests and responses, although some parameters, e.g. request_kid requests and responses, although some parameters, e.g. request_kid
need not be integrity protected in the requests. need not be integrity protected in the requests.
6. Sequence Numbers, Replay, Message Binding, and Freshness 6. OSCORE Compression
6.1. Message Binding The Concise Binary Object Representation (CBOR) [RFC7049] combines
very small message sizes with extensibility. The CBOR Object Signing
and Encryption (COSE) [RFC8152] uses CBOR to create compact encoding
of signed and encrypted data. COSE is however constructed to support
a large number of different stateless use cases, and is not fully
optimized for use as a stateful security protocol, leading to a
larger than necessary message expansion. In this section, we define
a stateless compression mechanism, simply removing redundant
information from the COSE objects, which significantly reduces the
per-packet overhead. The result of applying this mechanism to a COSE
object is called the "compressed COSE object".
6.1. Encoding of the Object-Security Value
The value of the Object-Security option SHALL contain the OSCORE flag
bits, the Partial IV parameter, the kid context parameter (length and
value), and the kid parameter as follows:
0 1 2 3 4 5 6 7 <--------- n bytes ------------->
+-+-+-+-+-+-+-+-+---------------------------------
|0 0 0|h|k| n | Partial IV (if any) ...
+-+-+-+-+-+-+-+-+---------------------------------
<- 1 byte -> <------ s bytes ----->
+------------+----------------------+------------------+
| s (if any) | kid context (if any) | kid (if any) ... |
+------------+----------------------+------------------+
Figure 11: Object-Security Value
o The first byte of flag bits encodes the following set of flags and
the length of the Partial IV parameter:
* The three least significant bits encode the Partial IV length
n. If n = 0 then the Partial IV is not present in the
compressed COSE object. The values n = 6 and n = 7 are
reserved.
* The fourth least significant bit is the kid flag, k: it is set
to 1 if the kid is present in the compressed COSE object.
* The fifth least significant bit is the kid context flag, h: it
is set to 1 if the compressed COSE object contains a kid
context (see Section 5.1).
* The sixth to eighth least significant bits are reserved for
future use. These bits SHALL be set to zero when not in use.
According to this specification, if any of these bits are set
to 1 the message is considered to be malformed and
decompression fails as specified in item 3 of Section 8.2.
o The following n bytes encode the value of the Partial IV, if the
Partial IV is present (n > 0).
o The following 1 byte encode the length of the kid context
(Section 5.1) s, if the kid context flag is set (h = 1).
o The following s bytes encode the kid context, if the kid context
flag is set (h = 1).
o The remaining bytes encode the value of the kid, if the kid is
present (k = 1).
Note that the kid MUST be the last field of the object-security
value, even in case reserved bits are used and additional fields are
added to it.
The length of the Object-Security option thus depends on the presence
and length of Partial IV, kid context, kid, as specified in this
section, and on the presence and length of the other parameters, as
defined in the separate documents.
6.2. Encoding of the OSCORE Payload
The payload of the OSCORE message SHALL encode the ciphertext of the
COSE object.
6.3. Examples of Compressed COSE Objects
6.3.1. Examples: Requests
1. Request with kid = 25 and Partial IV = 5
Before compression (24 bytes):
[
h'',
{ 4:h'25', 6:h'05' },
h'aea0155667924dff8a24e4cb35b9'
]
After compression (17 bytes):
Flag byte: 0b00001001 = 0x09
Option Value: 09 05 25 (3 bytes)
Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes)
1. Request with kid = empty string and Partial IV = 0
After compression (16 bytes):
Flag byte: 0b00001001 = 0x09
Option Value: 09 00 (2 bytes)
Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes)
1. Request with kid = empty string, Partial IV = 5, and kid context
= 0x44616c656b
After compression (22 bytes):
Flag byte: 0b00011001 = 0x19
Option Value: 19 05 05 44 61 6c 65 6b (8 bytes)
Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes)
6.3.2. Example: Response (without Observe)
Before compression (18 bytes):
[
h'',
{},
h'aea0155667924dff8a24e4cb35b9'
]
After compression (14 bytes):
Flag byte: 0b00000000 = 0x00
Option Value: (0 bytes)
Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes)
6.3.3. Example: Response (with Observe)
Before compression (21 bytes):
[
h'',
{ 6:h'07' },
h'aea0155667924dff8a24e4cb35b9'
]
After compression (16 bytes):
Flag byte: 0b00000001 = 0x01
Option Value: 01 07 (2 bytes)
Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes)
7. Sequence Numbers, Replay, Message Binding, and Freshness
7.1. Message Binding
In order to prevent response delay and mismatch attacks In order to prevent response delay and mismatch attacks
[I-D.mattsson-core-coap-actuators] from on-path attackers and [I-D.mattsson-core-coap-actuators] from on-path attackers and
compromised proxies, OSCORE binds responses to the requests by compromised proxies, OSCORE binds responses to the requests by
including the kid and Partial IV of the request in the AAD of the including the kid and Partial IV of the request in the AAD of the
response. The server therefore needs to store the kid and Partial IV response. The server therefore needs to store the kid and Partial IV
of the request until all responses have been sent. of the request until all responses have been sent.
6.2. AEAD Nonce Uniqueness 7.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 Sender to assure unique nonces, each Sender Context contains a Sender
Sequence Number used to protect requests, and - in case of Observe - Sequence Number used to protect requests, and - in case of Observe -
responses. If messages are processed concurrently, the operation of responses. If messages are processed concurrently, the operation of
reading and increasing the Sender Sequence Number MUST be atomic. reading and increasing the Sender Sequence Number MUST be atomic.
The maximum Sender Sequence Number is algorithm dependent, see The maximum Sender Sequence Number is algorithm dependent (see
Section 11, and no greater than 2^40 - 1. If the Sender Sequence Section 11), and no greater than 2^40 - 1. If the Sender Sequence
Number exceeds the maximum, the endpoint MUST NOT process any more Number exceeds the maximum, the endpoint MUST NOT process any more
messages with the given Sender Context. The endpoint SHOULD acquire messages with the given Sender Context. The endpoint SHOULD acquire
a new security context (and consequently inform the other endpoint) a new security context (and consequently inform the other endpoint)
before this happens. The latter is out of scope of this document. before this happens. The latter is out of scope of this document.
6.3. Freshness 7.3. Freshness
For requests, OSCORE provides weak absolute freshness as the only For requests, OSCORE provides weak absolute freshness as the only
guarantee is that the request is not older than the security context. guarantee is that the request is not older than the security context.
For applications having stronger demands on request freshness (e.g., For applications having stronger demands on request freshness (e.g.,
control of actuators), OSCORE needs to be augmented with mechanisms control of actuators), OSCORE needs to be augmented with mechanisms
providing freshness, for example as specified in providing freshness, for example as specified in
[I-D.ietf-core-echo-request-tag]. [I-D.ietf-core-echo-request-tag].
For responses, the message binding guarantees that a response is not For responses, the message binding guarantees that a response is not
older than its request. For responses without Observe, this gives older than its request. For responses without Observe, this gives
strong absolute freshness. For responses with Observe, the absolute strong absolute freshness. For responses with Observe, the absolute
freshness gets weaker with time, and it is RECOMMENDED that the freshness gets weaker with time, and it is RECOMMENDED that the
client regularly restart the observation. client regularly re-register the observation.
For requests, and responses with Observe, OSCORE also provides For requests, and responses with Observe, OSCORE also provides
relative freshness in the sense that the received Partial IV allows a relative freshness in the sense that the received Partial IV allows a
recipient to determine the relative order of responses. recipient to determine the relative order of responses.
6.4. Replay Protection 7.4. Replay Protection
In order to protect from replay of requests, the server's Recipient In order to protect from replay of requests, the server's Recipient
Context includes a Replay Window. A server SHALL verify that a Context includes a Replay Window. A server SHALL verify that a
Partial IV received in the COSE object has not been received before. Partial IV received in the COSE object has not been received before.
If this verification fails the server SHALL stop processing the If this verification fails the server SHALL stop processing the
message and, MAY optionally respond with a 4.01 Unauthorized error message, and MAY optionally respond with a 4.01 Unauthorized error
message. The server MAY set an Outer Max-Age option with value zero. message. Also, the server MAY set an Outer Max-Age option with value
The diagnostic payload MAY contain the "Replay protection failed" zero. The diagnostic payload MAY contain the "Replay protection
string. The size and type of the Replay Window depends on the use failed" string. The size and type of the Replay Window depends on
case and lower protocol layers. In case of reliable and ordered the use case and the protocol with which the OSCORE message is
transport from endpoint to endpoint, the server MAY just store the transported. In case of reliable and ordered transport from endpoint
last received Partial IV and require that newly received Partial IVs to endpoint, e.g. TCP, the server MAY just store the last received
equals the last received Partial IV + 1. Partial IV and require that newly received Partial IVs equals the
last received Partial IV + 1. However, in case of mixed reliable and
unreliable transports and where messages may be lost, such a replay
mechanism may be too restrictive and the default replay window be
more suitable (see Section 3.2.2).
Responses to non-Observe requests are protected against replay as Responses to non-Observe requests are protected against replay as
they are cryptographically bound to the request. they are cryptographically bound to the request.
In the case of Observe, a client receiving a notification SHALL In the case of Observe, a client receiving a notification SHALL
verify that the Partial IV of a received notification is greater than verify that the Partial IV of a received notification is greater than
the Notification Number bound to that Observe registration. If the the Notification Number bound to that Observe registration. If the
verification fails, the client SHALL stop processing the response. verification fails, the client SHALL stop processing the response.
If the verification succeeds, the client SHALL overwrite the If the verification succeeds, the client SHALL overwrite the
corresponding Notification Number with the received Partial IV. corresponding Notification Number with the received Partial IV.
If messages are processed concurrently, the Partial IV needs to be If messages are processed concurrently, the Partial IV needs to be
validated a second time after decryption and before updating the validated a second time after decryption and before updating the
replay protection data. The operation of validating the Partial IV replay protection data. The operation of validating the Partial IV
and updating the replay protection data MUST be atomic. and updating the replay protection data MUST be atomic.
6.5. Losing Part of the Context State 7.5. Losing Part of the Context State
To prevent reuse of the Nonce with the same key, or from accepting To prevent reuse of the AEAD nonce with the same key, or from
replayed messages, a node needs to handle the situation of losing accepting replayed messages, an endpoint needs to handle the
rapidly changing parts of the context, such as the request Token, situation of losing rapidly changing parts of the context, such as
Sender Sequence Number, Replay Window, and Notififcation Numbers. the request Token, Sender Sequence Number, Replay Window, and
These are typically stored in RAM and therefore lost in the case of Notification Numbers. These are typically stored in RAM and
an unplanned reboot. therefore lost in the case of an unplanned reboot.
After boot, a node MAY reject to use existing security contexts from After boot, an endpoint MAY reject to use existing security contexts
before it booted and MAY establish a new security context with each from before it booted and MAY establish a new security context with
party it communicates. However, establishing a fresh security each party it communicates. However, establishing a fresh security
context may have a non-negligible cost in terms of, e.g., power context may have a non-negligible cost in terms of, e.g., power
consumption. consumption.
After boot, a node MAY use a partly persistently stored security After boot, an endpoint MAY use a partly persistently stored security
context, but then the node MUST NOT reuse a previous Sender Sequence context, but then the endpoint MUST NOT reuse a previous Sender
Number and MUST NOT accept previously accepted messages. Some ways Sequence Number and MUST NOT accept previously accepted messages.
to achieve this is described below: Some ways to achieve this is described below:
6.5.1. Sequence Number 7.5.1. Sequence Number
To prevent reuse of Sender Sequence Numbers, a node MAY perform the To prevent reuse of Sender Sequence Numbers, an endpoint MAY perform
following procedure during normal operations: the following procedure during normal operations:
o Each time the Sender Sequence Number is evenly divisible by K, o Each time the Sender Sequence Number is evenly divisible by K,
where K is a positive integer, store the Sender Sequence Number in where K is a positive integer, store the Sender Sequence Number in
persistent memory. After boot, the node initiates the Sender persistent memory. After boot, the endpoint initiates the Sender
Sequence Number to the value stored in persistent memory + K - 1. Sequence Number to the value stored in persistent memory + K - 1.
Storing to persistent memory can be costly. The value K gives a Storing to persistent memory can be costly. The value K gives a
trade-off between the number of storage operations and efficient trade-off between the number of storage operations and efficient
use of Sender Sequence Numbers. use of Sender Sequence Numbers.
6.5.2. Replay Window 7.5.2. Replay Window
To prevent accepting replay of previously received requests, the To prevent accepting replay of previously received requests, the
server MAY perform the following procedure after boot: server MAY perform the following procedure after boot:
o For each stored security context, the first time after boot the o For each stored security context, the first time after boot the
server receives an OSCORE request, the server responds with the server receives an OSCORE request, the server responds with the
Echo option [I-D.ietf-core-echo-request-tag] to get a request with Echo option [I-D.ietf-core-echo-request-tag] to get a request with
verifiable freshness. The server MUST use its Partial IV when verifiable freshness. The server MUST use its Partial IV when
generating the nonce and MUST include the Partial IV in the generating the AEAD nonce and MUST include the Partial IV in the
response. response.
If the server using the Echo option can verify a second request as If the server using the Echo option can verify a second request as
fresh, then the Partial IV of the second request is set as the lower fresh, then the Partial IV of the second request is set as the lower
limit of the replay window. limit of the replay window.
6.5.3. Replay Protection of Observe Notifications 7.5.3. Replay Protection of Observe Notifications
To prevent accepting replay of previously received notification To prevent accepting replay of previously received notification
responses, the client MAY perform the following procedure after boot: responses, the client MAY perform the following procedure after boot:
o The client rejects notifications bound to the earlier o The client rejects notifications bound to the earlier
registration, removes all Notification Numbers and re-register registration, removes all Notification Numbers and re-registers
using Observe. using Observe.
7. Processing 8. Processing
This section describes the OSCORE message processing. This section describes the OSCORE message processing.
7.1. Protecting the Request 8.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 OSCORE 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 and the Plaintext, as 2. Compose the Additional Authenticated Data and the plaintext, as
described in Section 5.4 and Section 5.3. described in Section 5.4 and Section 5.3.
3. Compute the AEAD nonce from the Sender ID, Common IV, and Partial 3. Compute the AEAD nonce from the Sender ID, Common IV, and Partial
IV (Sender Sequence Number in network byte order) as described in IV (Sender Sequence Number in network byte order) as described in
Section 5.2. Then (in one atomic operation, see Section 6.2) Section 5.2 and (in one atomic operation, see Section 7.2)
increment the Sender Sequence Number by one. 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 6.
5. Format the OSCORE 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.2.2. 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.2. Verifying the Request 8.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.2.3.2. blocks of the request have been received (see Section 4.2.3.2).
2. Discard the message Code and all non-special Inner option 2. Discard the message Code and all non-special Inner option
message fields (marked with 'x' in column E of Figure 5) present message fields (marked with 'x' in column E of Figure 6) present
in the received message. For example, an If-Match Outer option in the received message. For example, an If-Match Outer option
is discarded, but an Uri-Host Outer option is not discarded. is discarded, but an Uri-Host Outer option is not discarded.
3. Decompress the COSE Object (Section 8) and retrieve the 3. Decompress the COSE Object (Section 6) and retrieve the
Recipient Context associated with the Recipient ID in the 'kid' Recipient Context associated with the Recipient ID in the 'kid'
parameter. If either the decompression or the COSE message parameter. If either the decompression or the COSE message
fails to decode, or the server fails to retrieve a Recipient fails to decode, or the server fails to retrieve a Recipient
Context with Recipient ID corresponding to the 'kid' parameter Context with Recipient ID corresponding to the 'kid' parameter
received, then the server SHALL stop processing the request. received, then the server SHALL stop processing the request.
If: If:
* either the decompression or the COSE message fails to decode, * either the decompression or the COSE message fails to decode,
the server MAY respond with a 4.02 Bad Option error message. the server MAY respond with a 4.02 Bad Option error message.
The server MAY set an Outer Max-Age option with value zero. The server MAY set an Outer Max-Age option with value zero.
skipping to change at page 27, line 47 skipping to change at page 33, line 47
decode COSE". decode COSE".
* the server fails to retrieve a Recipient Context with * the server fails to retrieve a Recipient Context with
Recipient ID corresponding to the 'kid' parameter received, Recipient ID corresponding to the 'kid' parameter received,
the server MAY respond with a 4.01 Unauthorized error the server MAY respond with a 4.01 Unauthorized error
message. The server MAY set an Outer Max-Age option with message. The server MAY set an Outer Max-Age option with
value zero. The diagnostic payload SHOULD contain the string value zero. The diagnostic payload SHOULD contain the string
"Security context not found". "Security context not found".
4. Verify the 'Partial IV' parameter using the Replay Window, as 4. Verify the 'Partial IV' parameter using the Replay Window, as
described in Section 6. described in Section 7.4.
5. Compose the Additional Authenticated Data, as described in 5. Compose the Additional Authenticated Data, as described in
Section 5. Section 5.4.
6. Compute the AEAD nonce from the Recipient ID, Common IV, and the 6. Compute the AEAD nonce from the Recipient ID, Common IV, and the
'Partial IV' parameter, received in the COSE Object. 'Partial IV' parameter, received in the COSE Object.
7. 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 MAY respond with a 4.00 Bad Request error request and MAY respond with a 4.00 Bad Request error
message. The server MAY set an Outer Max-Age option with message. The server MAY set an Outer Max-Age option with
value zero. The diagnostic payload SHOULD contain the value zero. The diagnostic payload SHOULD contain the
"Decryption failed" string. "Decryption failed" string.
* If decryption succeeds, update the Replay Window, as * If decryption succeeds, update the Replay Window, as
described in Section 6. described in Section 7.
8. For each decrypted option, check if the option is also present 8. For each decrypted option, check if the option is also present
as an Outer option: if it is, discard the Outer. For example: 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 message contains a Max-Age Inner and a Max-Age Outer option.
The Outer Max-Age is discarded. The Outer Max-Age is discarded.
9. Add decrypted code, options and payload to the decrypted 9. Add decrypted code, options and payload to the decrypted
request. The Object-Security option is removed. request. The Object-Security option is removed.
10. The decrypted CoAP request is processed according to [RFC7252] 10. The decrypted CoAP request is processed according to [RFC7252]
7.3. Protecting the Response 8.3. Protecting the Response
Given a CoAP response, the server SHALL perform the following steps If a CoAP response is generated in response to an OSCORE request, the
to create an OSCORE response. Note that CoAP error responses derived server SHALL perform the following steps to create an OSCORE
from CoAP processing (point 10. in Section 7.2) are protected, as response. Note that CoAP error responses derived from CoAP
well as successful CoAP responses, while the OSCORE errors (point 3, processing (point 10. in Section 8.2) are protected, as well as
4, and 7 in Section 7.2) do not follow the processing below, but are successful CoAP responses, while the OSCORE errors (point 3, 4, and 7
sent as simple CoAP responses, without OSCORE processing. in Section 8.2) do not follow the processing below, but are sent as
simple CoAP responses, without OSCORE processing.
1. Retrieve the Sender Context in the Security Context 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 and the Plaintext, as 2. Compose the Additional Authenticated Data and the plaintext, as
described in Section 5.4 and Section 5.3. described in Section 5.4 and Section 5.3.
3. Compute the AEAD nonce 3. Compute the AEAD nonce
* If Observe is used, Compute the AEAD nonce from the Sender ID, * If Observe is used, compute the nonce from the Sender ID,
Common IV, and Partial IV (Sender Sequence Number in network Common IV, and Partial IV (Sender Sequence Number in network
byte order). Then (in one atomic operation, see Section 6.2) byte order). Then (in one atomic operation, see Section 7.2)
increment the Sender Sequence Number by one. increment the Sender Sequence Number by one.
* If Observe is not used, either the nonce from the request is * If Observe is not used, either the nonce from the request is
used or a new Partial IV is used. used or a new Partial IV is used.
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. If the nonce was constructed Object as specified in Section 6. If the AEAD nonce was
from a new Partial IV, this Partial IV MUST be included in the constructed from a new Partial IV, this Partial IV MUST be
message. If the nonce from the request was used, the Partial IV included in the message. If the AEAD nonce from the request was
MUST NOT be included in the message. used, the Partial IV MUST NOT be included in the message.
5. Format the OSCORE 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.2.2. Security option is added (see Section 4.2.2).
7.4. Verifying the Response 8.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 OSCORE message have been received, see blocks of the OSCORE message have been received (see
Section 4.2.3.2. Section 4.2.3.2).
2. Discard the message Code and all non-special Class E options 2. Discard the message Code and all non-special Class E options
from the message. For example, ETag Outer option is discarded, from the message. For example, ETag Outer option is discarded,
Max-Age Outer option is not discarded. Max-Age Outer option is not discarded.
3. Retrieve the Recipient Context associated with the Token. 3. Retrieve the Recipient Context associated with the Token.
Decompress the COSE Object (Section 8). If either the Decompress the COSE Object (Section 6). If either the
decompression or the COSE message fails to decode, then go to decompression or the COSE message fails to decode, then go to
11. 11.
4. For Observe notifications, verify the received 'Partial IV' 4. For Observe notifications, verify the received 'Partial IV'
parameter against the corresponding Notification Number as parameter against the corresponding Notification Number as
described in Section 6. If the client receives a notification described in Section 7.4. If the client receives a notification
for which no Observe request was sent, then go to 11. for which no Observe request was sent, then go to 11.
5. Compose the Additional Authenticated Data, as described in 5. Compose the Additional Authenticated Data, as described in
Section 5. Section 5.4.
6. Compute the AEAD nonce 6. Compute the AEAD nonce
1. If the Observe option and the Partial IV are not present in 1. If the Observe option and the Partial IV are not present in
the response, the nonce from the request is used. the response, the nonce from the request is used.
2. If the Observe option is present in the response, and the 2. If the Observe option is present in the response, and the
Partial IV is not present in the response, then go to 11. Partial IV is not present in the response, then go to 11.
3. If the Partial IV is present in the response, compute the 3. If the Partial IV is present in the response, compute the
AEAD nonce from the Recipient ID, Common IV, and the nonce from the Recipient ID, Common IV, and the 'Partial IV'
'Partial IV' parameter, received in the COSE Object. parameter, received in the COSE Object.
7. Decrypt the COSE object using the Recipient Key. 7. Decrypt the COSE object using the Recipient Key.
* If decryption fails, then go to 11. * If decryption fails, then go to 11.
* If decryption succeeds and Observe is used, update the * If decryption succeeds and Observe is used, update the
corresponding Notification Number, as described in Section 6. corresponding Notification Number, as described in Section 7.
8. For each decrypted option, check if the option is also present 8. For each decrypted option, check if the option is also present
as an Outer option: if it is, discard the Outer. For example: 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 message contains a Max-Age Inner and a Max-Age Outer option.
The Outer Max-Age is discarded. The Outer Max-Age is discarded.
9. Add decrypted code, options and payload to the decrypted 9. Add decrypted code, options and payload to the decrypted
request. The Object-Security option is removed. request. The Object-Security option is removed.
10. The decrypted CoAP response is processed according to [RFC7252] 10. The decrypted CoAP response is processed according to [RFC7252]
11. (Optional) In case any of the previous erroneous conditions 11. (Optional) In case any of the previous erroneous conditions
apply: the client SHALL stop processing the response. apply: the client SHALL stop processing the response.
8. OSCORE Compression An error condition occurring while processing a response in an
observation does not cancel the observation. A client MUST NOT react
The Concise Binary Object Representation (CBOR) [RFC7049] combines to failure in step 7 by re-registering the observation immediately.
very small message sizes with extensibility. The CBOR Object Signing
and Encryption (COSE) [RFC8152] uses CBOR to create compact encoding
of signed and encrypted data. COSE is however constructed to support
a large number of different stateless use cases, and is not fully
optimized for use as a stateful security protocol, leading to a
larger than necessary message expansion. In this section, we define
a simple stateless compression mechanism for OSCORE called the
"compressed COSE object", which significantly reduces the per-packet
overhead.
8.1. Encoding of the Object-Security Value
The value of the Object-Security option SHALL contain the OSCORE flag
byte, the Partial IV parameter, the kid context parameter (length and
value), and the kid parameter as follows:
0 1 2 3 4 5 6 7 <--------- n bytes ------------->
+-+-+-+-+-+-+-+-+---------------------------------
|0 0 0|h|k| n | Partial IV (if any)
+-+-+-+-+-+-+-+-+---------------------------------
<-- 1 byte --><------ s bytes ------>
+------------+----------------------+------------------+
| s (if any) | kid context (if any) | kid (if any) ... |
+------------+----------------------+------------------+
Figure 10: Object-Security Value
o The first byte (= the OSCORE flag byte) encodes a set of flags and
the length of the Partial IV parameter.
* The three least significant bits encode the Partial IV length
n. If n = 0 then the Partial IV is not present in the
compressed COSE object. The values n = 6 and n = 7 is
reserved.
* The fourth least significant bit is the kid flag, k: it is set
to 1 if the kid is present in the compressed COSE object.
* The fifth least significant bit is the kid context flag, h: it
is set to 1 if the compressed COSE object contains a kid
context, see Section 5.1.
* The sixth least significant bit is reserved for indicating the
presence of a signature. This needs to be specified in a
separate document. The bit SHALL be set to zero when not in
use.
* The seventh least significant bit is reserved to expand the
flag byte. This needs to be specified in a separate document.
The bit SHALL be set to zero when not in use.
* The eighth least significant bit is reserved for indicating if
a non-compressed COSE object is used. This needs to be
specified in a separate document. The bit SHALL be set to zero
when not in use.
o The following n bytes encode the value of the Partial IV, if the
Partial IV is present (n > 0).
o The following 1 byte encode the length of the kid context
(Section 5.1) s, if the kid context flag is set (h = 1).
o The following s bytes encode the kid context, if the kid context
flag is set (h = 1).
o The remaining bytes encode the value of the kid, if the kid is
present (k = 1)
Note that the kid MUST be the last field of the object-security
value, even in case reserved bits are used and additional fields are
added to it.
8.2. Encoding of the OSCORE Payload
The payload of the OSCORE message SHALL encode the ciphertext of the
COSE object.
8.3. Examples of Compressed COSE Objects
8.3.1. Example: Requests
Request with kid = 25 and Partial IV = 5
Before compression (24 bytes):
[
h'',
{ 4:h'25', 6:h'05' },
h'aea0155667924dff8a24e4cb35b9'
]
After compression (17 bytes):
Flag byte: 0b00001001 = 0x09
Option Value: 09 05 25 (3 bytes)
Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes)
Request with kid = empty string and Partial IV = 0
After compression (16 bytes):
Flag byte: 0b00001001 = 0x09
Option Value: 09 00 (2 bytes)
Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes)
Request with kid = empty string, Partial IV = 5, and kid context =
0x44616c656b
After compression (22 bytes):
Flag byte: 0b00011001 = 0x19
Option Value: 19 05 05 44 61 6c 65 6b (8 bytes)
Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes)
8.3.2. Example: Response (without Observe)
Before compression (18 bytes):
[
h'',
{},
h'aea0155667924dff8a24e4cb35b9'
]
After compression (14 bytes):
Flag byte: 0b00000000 = 0x00
Option Value: (0 bytes)
Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes)
8.3.3. Example: Response (with Observe)
Before compression (21 bytes):
[
h'',
{ 6:h'07' },
h'aea0155667924dff8a24e4cb35b9'
]
After compression (16 bytes):
Flag byte: 0b00000001 = 0x01
Option Value: 01 07 (2 bytes)
Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes)
9. Web Linking 9. Web Linking
The use of OSCORE 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 [RFC8288] to a resource. This attribute is a hint web link [RFC8288] 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
OSCORE. 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
OSCORE. 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. Proxy Operations 10. Proxy and HTTP Operations
RFC 7252 defines operations for a CoAP-to-CoAP proxy (see Section 5.7 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 of [RFC7252]) and for proxying between CoAP and HTTP (Section 10 of
[RFC7252]). A more detailed description of the HTTP-to-CoAP mapping [RFC7252]). A more detailed description of the HTTP-to-CoAP mapping
is provided by [RFC8075]. This section describes the operations of is provided by [RFC8075]. This section describes the operations of
OSCORE-aware proxies. OSCORE-aware proxies.
10.1. CoAP-to-CoAP Forwarding Proxy 10.1. CoAP-to-CoAP Forwarding Proxy
OSCORE is designed to work with legacy CoAP-to-CoAP forward proxies OSCORE is designed to work with legacy CoAP-to-CoAP forward proxies
[RFC7252], but OSCORE-aware proxies MAY provide certain [RFC7252], but OSCORE-aware proxies MAY provide certain
simplifications as specified in this section. simplifications as specified in this section.
The targeted proxy operations are specified in Section 2.2.1 of Security requirements for forwarding are presented in Section 2.2.1
[I-D.hartke-core-e2e-security-reqs]. In particular caching is of [I-D.hartke-core-e2e-security-reqs]. OSCORE complies with the
disabled since the CoAP response is only applicable to the original extended security requirements also addressing Blockwise ([RFC7959])
client's CoAP request. An OSCORE-aware proxy SHALL NOT cache a and CoAP-mappable HTTP. In particular caching is disabled since the
response to a request with an Object-Security option. As a CoAP response is only applicable to the original CoAP request. An
consequence, the search for cache hits and CoAP freshness/Max-Age OSCORE-aware proxy SHALL NOT cache a response to a request with an
processing can be omitted. 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 Proxy processing of the (Outer) Proxy-Uri option is as defined in
[RFC7252]. [RFC7252].
Proxy processing of the (Outer) Block options is as defined in Proxy processing of the (Outer) Block options is as defined in
[RFC7959] and [I-D.ietf-core-echo-request-tag]. [RFC7959] and [I-D.ietf-core-echo-request-tag].
Proxy processing of the (Outer) Observe option is as defined in Proxy processing of the (Outer) Observe option is as defined in
[RFC7641]. OSCORE-aware proxies MAY look at the Partial IV value [RFC7641]. OSCORE-aware proxies MAY look at the Partial IV value
instead of the Outer Observe option. instead of the Outer Observe option.
10.2. HTTP-to-CoAP Translation Proxy 10.2. HTTP Processing
In order to use OSCORE with HTTP, an endpoint needs to be able to map
HTTP messages to CoAP messages (see [RFC8075]), and to apply OSCORE
to CoAP messages (as defined in this document).
A sending endpoint uses [RFC8075] to translate an HTTP message into a
CoAP message. It then protects the message with OSCORE processing,
and add the Object-Security option (as defined in this document).
Then, the endpoint maps the resulting CoAP message to an HTTP message
that includes an HTTP header field named Object-Security, whose value
is:
o "" (empty string) if the CoAP Object-Security option is empty, or
o the value of the CoAP Object-Security option (Section 6.1) in
base64url encoding (Section 5 of [RFC4648]) without padding (see
[RFC7515] Appendix C for implementation notes for this encoding).
Note that the value of the HTTP body is the CoAP payload, i.e. the
OSCORE payload (Section 6.2).
The resulting message is an OSCORE message that uses HTTP.
A receiving endpoint uses [RFC8075] to translate an HTTP message into
a CoAP message, with the following addition. The HTTP message
includes the Object-Security header field, which is mapped to the
CoAP Object-Security option in the following way. The CoAP Object-
Security option value is:
o empty if the value of the HTTP Object-Security header field is ""
(empty string)
o the value of the HTTP Object-Security header field decoded from
base64url (Section 5 of [RFC4648]) without padding (see [RFC7515]
Appendix C for implementation notes for this decoding).
Note that the value of the CoAP payload is the HTTP body, i.e. the
OSCORE payload (Section 6.2).
The resulting message is an OSCORE message that uses CoAP.
The endpoint can then verify the message according to the OSCORE
processing and get a verified CoAP message. It can then translate
the verified CoAP message into a verified HTTP message.
10.3. HTTP-to-CoAP Translation Proxy
Section 10.2 of [RFC7252] and [RFC8075] specify the behavior of an Section 10.2 of [RFC7252] and [RFC8075] specify the behavior of an
HTTP-to-CoAP proxy. As requested in Section 1 of [RFC8075], this HTTP-to-CoAP proxy. As requested in Section 1 of [RFC8075], this
section describes the HTTP mapping for the OSCORE protocol extension section describes the HTTP mapping for the OSCORE protocol extension
of CoAP. of CoAP.
The presence of the Object-Security option, both in requests and The presence of the Object-Security option, both in requests and
responses, is expressed in an HTTP header field named Object-Security responses, is expressed in an HTTP header field named Object-Security
in the mapped request or response. The value of the field is: in the mapped request or response. The value of the field is:
o "" (empty string) if the CoAP Object-Security option is empty, or o "" (empty string) if the CoAP Object-Security option is empty, or
o the value of the CoAP Object-Security option Section 8.1 in
o the value of the CoAP Object-Security option (Section 6.1) in
base64url encoding (Section 5 of [RFC4648]) without padding (see base64url encoding (Section 5 of [RFC4648]) without padding (see
[RFC7515] Appendix C for implementation notes for this encoding). [RFC7515] Appendix C for implementation notes for this encoding).
The value of the body is the OSCORE payload Section 8.2. The value of the body is the OSCORE payload (Section 6.2).
Example: Example:
Mapping and notation here is based on "Simple Form" (Section 5.4.1.1 Mapping and notation here is based on "Simple Form" (Section 5.4.1.1
of [RFC8075]). of [RFC8075]).
[HTTP request -- Before object security processing] [HTTP request -- Before client object security processing]
GET http://proxy.url/hc/?target_uri=coap://server.url/orders HTTP/1.1 GET http://proxy.url/hc/?target_uri=coap://server.url/orders HTTP/1.1
[HTTP request -- HTTP Client to Proxy] [HTTP request -- HTTP Client to Proxy]
POST http://proxy.url/hc/?target_uri=coap://server.url/ HTTP/1.1 POST http://proxy.url/hc/?target_uri=coap://server.url/ HTTP/1.1
Object-Security: 09 25 Object-Security: 09 25
Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary]
[CoAP request -- Proxy to CoAP Server] [CoAP request -- Proxy to CoAP Server]
POST coap://server.url/ POST coap://server.url/
Object-Security: 09 25 Object-Security: 09 25
Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary]
[CoAP response -- CoAP Server to Proxy] [CoAP request -- After server object security processing]
2.04 Changed GET coap://server.url/orders
Object-Security: [empty]
Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary]
[HTTP response -- Proxy to HTTP Client] [CoAP response -- Before server object security processing]
HTTP/1.1 200 OK 2.05 Content
Object-Security: "" (empty string) Content-Format: 0
Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] Payload: Exterminate! Exterminate!
[HTTP response -- After object security processing] [CoAP response -- CoAP Server to Proxy]
HTTP/1.1 200 OK 2.04 Changed
Body: Exterminate! Exterminate! 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 string)
Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary]
[HTTP response -- After client object security processing]
HTTP/1.1 200 OK
Content-Type: text/plain
Body: Exterminate! Exterminate!
Note that the HTTP Status Code 200 in the next-to-last message is the 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 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), 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 which was encrypted within the compressed COSE object carried in the
Body of the HTTP response. Body of the HTTP response.
10.3. CoAP-to-HTTP Translation Proxy 10.4. CoAP-to-HTTP Translation Proxy
Section 10.1 of [RFC7252] describes the behavior of a CoAP-to-HTTP 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 proxy. RFC 8075 [RFC8075] does not cover this direction in any more
detail and so an example instantiation of Section 10.1 of [RFC7252] detail and so an example instantiation of Section 10.1 of [RFC7252]
is used below. is used below.
Example: Example:
[CoAP request -- Before object security processing] [CoAP request -- Before client object security processing]
GET coap://proxy.url/ GET coap://proxy.url/
Proxy-Uri=http://server.url/orders Proxy-Uri=http://server.url/orders
[CoAP request -- CoAP Client to Proxy] [CoAP request -- CoAP Client to Proxy]
POST coap://proxy.url/ POST coap://proxy.url/
Proxy-Uri=http://server.url/ Proxy-Uri=http://server.url/
Object-Security: 09 25 Object-Security: 09 25
Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary]
[HTTP request -- Proxy to HTTP Server] [HTTP request -- Proxy to HTTP Server]
POST http://server.url/ HTTP/1.1 POST http://server.url/ HTTP/1.1
Object-Security: 09 25 Object-Security: 09 25
Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary]
[HTTP request -- After server object security processing]
GET http://server.url/orders HTTP/1.1
[HTTP response -- Before server object security processing]
HTTP/1.1 200 OK
Content-Type: text/plain
Body: Exterminate! Exterminate!
[HTTP response -- HTTP Server to Proxy] [HTTP response -- HTTP Server to Proxy]
HTTP/1.1 200 OK HTTP/1.1 200 OK
Object-Security: "" (empty string) Object-Security: "" (empty string)
Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary]
[CoAP response -- CoAP Server to Proxy] [CoAP response - Proxy to CoAP Client]
2.04 Changed 2.04 Changed
Object-Security: [empty] Object-Security: [empty]
Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary]
[CoAP response -- After object security processing] [CoAP response -- After client object security processing]
2.05 Content 2.05 Content
Content-Format: 0
Payload: Exterminate! Exterminate! Payload: Exterminate! Exterminate!
Note that the HTTP Code 2.04 (Changed) in the next-to-last message is 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 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 (Content) in the last message is the value that was encrypted within
the compressed COSE object carried in the Body of the HTTP response. the compressed COSE object carried in the Body of the HTTP response.
11. Security Considerations 11. Security Considerations
In scenarios with intermediary nodes such as proxies or brokers, 11.1. End-to-end protection
In scenarios with intermediary nodes such as proxies or gateways,
transport layer security such as (D)TLS only protects data hop-by- transport layer security such as (D)TLS only protects data hop-by-
hop. 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 intermediary 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.
(D)TLS protects hop-by-hop the entire message, including header, (D)TLS protects hop-by-hop the entire message. OSCORE protects end-
options, and payload. OSCORE protects end-to-end the payload, and to-end all information that is not required for proxy operations (see
all information in the options and header, that is not required for Section 4). (D)TLS and OSCORE can be combined, thereby enabling end-
proxy operations (see Section 4). (D)TLS and OSCORE can be combined, to-end security of the message payload, in combination with hop-by-
thereby enabling end-to-end security of the message payload, in hop protection of the entire message, during transport between end-
combination with hop-by-hop protection of the entire message, during point and intermediary node. The CoAP messaging layer, including
transport between end-point and intermediary node. The message header fields such as Type and Message ID, as well as CoAP message
layer, however, cannot be protected end-to-end through intermediary fields Token and Token Length may be changed by a proxy and thus
devices since, even if the protocol itself isn't translated, the cannot be protected end-to-end. Error messages occurring during CoAP
parameters Type, Message ID, Token, and Token Length may be changed processing are protected end-to-end. Error messages occurring during
by a proxy. OSCORE processing are not always possible to protect, e.g. if the
receiving endpoint cannot locate the right security context. It may
still be favorable to send an unprotected error message, e.g. to
prevent extensive retransmissions, so unprotected error messages are
allowed as specified. Similar to error messages, signaling messages
are not always possible to protect as they may be intended for an
intermediary. Hop-by-hop protection of signaling messages can be
achieved with (D)TLS. Applications using unprotected error and
signaling messages need to consider the threat that these messages
may be spoofed.
11.2. Security Context Establishment
The use of COSE to protect messages as specified in this document The use of COSE to protect messages as specified in this document
requires an established security context. The method to establish requires an established security context. The method to establish
the security context described in Section 3.2 is based on a common the security context described in Section 3.2 is based on a common
shared secret material in client and server, which may be obtained, shared secret material in client and server, which may be obtained,
e.g., by using the ACE framework [I-D.ietf-ace-oauth-authz]. An 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]. OSCORE profile of ACE is described in [I-D.ietf-ace-oscore-profile].
11.3. Replay Protection
Most AEAD algorithms require a unique nonce for each message, for Most AEAD algorithms require a unique nonce for each message, for
which the sender sequence numbers in the COSE message field "Partial which the sender sequence numbers in the COSE message field 'Partial
IV" is used. If the recipient accepts any sequence number larger IV' is used. If the recipient accepts any sequence number larger
than the 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.
11.4. Cryptographic Considerations
The maximum sender sequence number is dependent on the AEAD The maximum sender sequence number is dependent on the AEAD
algorithm. The maximum sender sequence number SHALL be 2^40 - 1, or algorithm. The maximum sender sequence number SHALL be 2^40 - 1, or
any algorithm specific lower limit, after which a new security any algorithm specific lower limit, after which a new security
context must be generated. The mechanism to build the nonce context must be generated. The mechanism to build the nonce
(Section 5.2) assumes that the nonce is at least 56 bit-long, and the (Section 5.2) assumes that the nonce is at least 56 bit-long, and the
Partial IV is at most 40 bit-long. The mandatory-to-implement AEAD Partial IV is at most 40 bit-long. The mandatory-to-implement AEAD
algorithm AES-CCM-16-64-128 is selected for compatibility with CCM*. algorithm AES-CCM-16-64-128 is selected for compatibility with CCM*.
The inner block options enable the sender to split large messages The security level of a system with m Masters Keys of length k used
into OSCORE-protected blocks such that the receiving node can verify together with Master Salts with entropy n is k + n - log2(m).
blocks before having received the complete message. The outer block Similarly, the security level of a system with m AEAD keys of length
options allow for arbitrary proxy fragmentation operations that k used together with AEAD nonces of length n is k + n - log2(m).
Security level here means that an attacker can recover one of the m
keys with complexity 2^(k + n) / m. Protection against such attacks
can be provided by increasing the size of the keys or the entropy of
the Master Salt. The complexity of recovering a specific key is
still 2^k (assuming the Master Salt/AEAD nonce is public). The
Master Secret, Sender Key, and Recipient Key MUST be secret, the rest
of the parameters MAY be public. The Master Secret MUST be uniformly
random.
11.5. Message Fragmentation
The Inner Block options enable the sender to split large messages
into OSCORE-protected blocks such that the receiving endpoint can
verify blocks before having received the complete message. The Outer
Block options allow for arbitrary proxy fragmentation operations that
cannot be verified by the endpoints, but can by policy be restricted 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 Inner Block options allow for secure fragmentation
very large messages. A maximum message size (above which the sending of very large messages. A maximum message size (above which the
endpoint fragments the message and the receiving endpoint discards sending endpoint fragments the message and the receiving endpoint
the message, if complying to the policy) may be obtained as part of discards the message, if complying to the policy) may be obtained as
normal resource discovery. part of normal resource discovery.
12. Privacy Considerations 11.6. Privacy Considerations
Privacy threats executed through intermediate nodes are considerably Privacy threats executed through intermediary nodes are considerably
reduced by means of OSCORE. End-to-end integrity protection and reduced by means of OSCORE. End-to-end integrity protection and
encryption of the message payload and all options that are not used encryption of the message payload and all options that are not used
for proxy operations, provide mitigation against attacks on sensor for proxy operations, provide mitigation against attacks on sensor
and actuator communication, which may have a direct impact on the and actuator communication, which may have a direct impact on the
personal sphere. personal sphere.
The unprotected options (Figure 5) may reveal privacy sensitive The unprotected options (Figure 6) 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 ACK (CoAP Message Identifier), matching
CoAP headers sent in plaintext allow for example matching of CON and of request and responses (Token) and traffic analysis.
ACK (CoAP Message Identifier), matching of request and responses
(Token) and traffic analysis.
Using the mechanisms described in Section 6.5 may reveal when a Unprotected error messages reveal information about the security
device goes through a reboot. This can be mitigated by the device state in the communication between the endpoints. Unprotected
storing the precise state of sender sequence number and replay window signalling messages reveal information about the reliable transport
on a clean shutdown. used on a leg of the path. Using the mechanisms described in
Section 7.5 may reveal when a device goes through a reboot. This can
be mitigated by the device storing the precise state of sender
sequence number and replay window on a clean shutdown.
The length of message fields can reveal information about the The length of message fields can reveal information about the
message. Applications may use a padding scheme to protect against message. Applications may use a padding scheme to protect against
traffic analysis. As an example, the strings "YES" and "NO" even if traffic analysis. As an example, the strings "YES" and "NO" even if
encrypted can be distinguished from each other as there is no padding encrypted can be distinguished from each other as there is no padding
supplied by the current set of encryption algorithms. Some supplied by the current set of encryption algorithms. Some
information can be determined even from looking at boundary information can be determined even from looking at boundary
conditions. An example of this would be returning an integer between 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 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 where in the range things are. Three different methods to deal with
this are: 1) ensure that all messages are the same length. For 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 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 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 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 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 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 style of padding means that all values need to be padded. Similar
arguments apply to other message fields such as resource names. arguments apply to other message fields such as resource names.
13. IANA Considerations 12. 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.
13.1. COSE Header Parameters Registry Note to IANA: Please note all occurrences of "TBD" in this
specification should be assigned the same number.
The 'kid context' paramter is added to the "COSE Header Parameters 12.1. COSE Header Parameters Registry
The 'kid context' parameter is added to the "COSE Header Parameters
Registry": Registry":
o Name: kid context o Name: kid context
o Label: kidctx o Label: kidctx
o Value Type: bstr o Value Type: bstr
o Value Registry: o Value Registry:
o Description: kid context o Description: kid context
o Reference: Section 5.1 of this document o Reference: Section 5.1 of this document
13.2. CoAP Option Numbers Registry 12.2. 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]] |
+--------+-----------------+-------------------+ +--------+-----------------+-------------------+
13.3. Header Field Registrations 12.3. CoAP Signaling Option Numbers Registry
The Object-Security option is added to the CoAP Signaling Option
Numbers registry:
+------------+--------+---------------------+-------------------+
| Applies to | Number | Name | Reference |
+------------+--------+---------------------+-------------------+
| 7.xx | TBD | Object-Security | [[this document]] |
+------------+--------+---------------------+-------------------+
12.4. Header Field Registrations
The HTTP header field Object-Security is added to the Message Headers The HTTP header field Object-Security is added to the Message Headers
registry: registry:
+-------------------+----------+----------+-------------------+ +-------------------+----------+----------+-------------------+
| Header Field Name | Protocol | Status | Reference | | Header Field Name | Protocol | Status | Reference |
+-------------------+----------+----------+-------------------+ +-------------------+----------+----------+-------------------+
| Object-Security | http | standard | [[this document]] | | Object-Security | http | standard | [[this document]] |
+-------------------+----------+----------+-------------------+ +-------------------+----------+----------+-------------------+
14. Acknowledgments 13. References
The following individuals provided input to this document: Christian
Amsuess, Tobias Andersson, Carsten Bormann, Joakim Brorsson, Thomas
Fossati, Martin Gunnarsson, Klaus Hartke, Jim Schaad, Dave Thaler,
Marco Tiloca, and Malisa Vu&#269;ini&#263;.
Ludwig Seitz and Goeran Selander worked on this document as part of
the CelticPlus project CyberWI, with funding from Vinnova.
15. References
15.1. Normative References 13.1. Normative References
[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,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
<https://www.rfc-editor.org/info/rfc4648>. <https://www.rfc-editor.org/info/rfc4648>.
skipping to change at page 41, line 34 skipping to change at page 46, line 34
<https://www.rfc-editor.org/info/rfc8132>. <https://www.rfc-editor.org/info/rfc8132>.
[RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)",
RFC 8152, DOI 10.17487/RFC8152, July 2017, RFC 8152, DOI 10.17487/RFC8152, July 2017,
<https://www.rfc-editor.org/info/rfc8152>. <https://www.rfc-editor.org/info/rfc8152>.
[RFC8288] Nottingham, M., "Web Linking", RFC 8288, [RFC8288] Nottingham, M., "Web Linking", RFC 8288,
DOI 10.17487/RFC8288, October 2017, DOI 10.17487/RFC8288, October 2017,
<https://www.rfc-editor.org/info/rfc8288>. <https://www.rfc-editor.org/info/rfc8288>.
15.2. Informative References 13.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.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-
skipping to change at page 42, line 11 skipping to change at page 47, line 11
"Minimal Security Framework for 6TiSCH", draft-ietf- "Minimal Security Framework for 6TiSCH", draft-ietf-
6tisch-minimal-security-04 (work in progress), October 6tisch-minimal-security-04 (work in progress), October
2017. 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-09 (work in progress), November 2017. authz-09 (work in progress), November 2017.
[I-D.ietf-ace-oscore-profile]
Seitz, L., Palombini, F., and M. Gunnarsson, "OSCORE
profile of the Authentication and Authorization for
Constrained Environments Framework", draft-ietf-ace-
oscore-profile-00 (work in progress), December 2017.
[I-D.ietf-cbor-cddl] [I-D.ietf-cbor-cddl]
Birkholz, H., Vigano, C., and C. Bormann, "Concise 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-ietf-cbor-cddl-00 express CBOR data structures", draft-ietf-cbor-cddl-00
(work in progress), July 2017. (work in progress), July 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-10 (work in progress), draft-ietf-core-coap-tcp-tls-11 (work in progress),
October 2017. December 2017.
[I-D.ietf-core-echo-request-tag] [I-D.ietf-core-echo-request-tag]
Amsuess, C., Mattsson, J., and G. Selander, "Echo and Amsuess, C., Mattsson, J., and G. Selander, "Echo and
Request-Tag", draft-ietf-core-echo-request-tag-00 (work in Request-Tag", draft-ietf-core-echo-request-tag-00 (work in
progress), October 2017. progress), October 2017.
[I-D.mattsson-ace-tls-oscore]
Mattsson, J., "Using Transport Layer Security (TLS) to
Secure OSCORE", draft-mattsson-ace-tls-oscore-00 (work in
progress), October 2017.
[I-D.mattsson-core-coap-actuators] [I-D.mattsson-core-coap-actuators]
Mattsson, J., Fornehed, J., Selander, G., Palombini, F., Mattsson, J., Fornehed, J., Selander, G., Palombini, F.,
and C. Amsuess, "Controlling Actuators with CoAP", draft- and C. Amsuess, "Controlling Actuators with CoAP", draft-
mattsson-core-coap-actuators-03 (work in progress), mattsson-core-coap-actuators-03 (work in progress),
October 2017. October 2017.
[I-D.seitz-ace-oscoap-profile]
Seitz, L., Palombini, F., and M. Gunnarsson, "OSCORE
profile of the Authentication and Authorization for
Constrained Environments Framework", draft-seitz-ace-
oscoap-profile-06 (work in progress), October 2017.
[I-D.tiloca-core-multicast-oscoap] [I-D.tiloca-core-multicast-oscoap]
Tiloca, M., Selander, G., Palombini, F., and J. Park, Tiloca, M., Selander, G., Palombini, F., and J. Park,
"Secure group communication for CoAP", draft-tiloca-core- "Secure group communication for CoAP", draft-tiloca-core-
multicast-oscoap-04 (work in progress), October 2017. multicast-oscoap-04 (work in progress), October 2017.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005, RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>. <https://www.rfc-editor.org/info/rfc3986>.
[RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated
Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008,
<https://www.rfc-editor.org/info/rfc5116>.
[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,
<https://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,
<https://www.rfc-editor.org/info/rfc7228>. <https://www.rfc-editor.org/info/rfc7228>.
[RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
2015, <https://www.rfc-editor.org/info/rfc7515>. 2015, <https://www.rfc-editor.org/info/rfc7515>.
Appendix A. Test Vectors [RFC7967] Bhattacharyya, A., Bandyopadhyay, S., Pal, A., and T.
Bose, "Constrained Application Protocol (CoAP) Option for
TODO: This section needs to be updated. No Server Response", RFC 7967, DOI 10.17487/RFC7967,
August 2016, <https://www.rfc-editor.org/info/rfc7967>.
Appendix B. Examples Appendix A. Scenario examples
This section gives examples of OSCORE. The message exchanges are This section gives examples of OSCORE, targeting scenarios in
made, based on the assumption that there is a security context Section 2.2.1.1 of [I-D.hartke-core-e2e-security-reqs]. The message
established between client and server. For simplicity, these exchanges are made, based on the assumption that there is a security
context 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 (compressed) COSE message format. detail of the (compressed) COSE message format.
B.1. Secure Access to Sensor A.1. Secure Access to Sensor
This example targets the scenario in Section 3.1 of This example illustrates a client requesting the alarm status from a
[I-D.hartke-core-e2e-security-reqs] and illustrates a client server.
requesting the alarm status from a server.
Client Proxy Server Client Proxy Server
| | | | | |
+------>| | Code: 0.02 (POST) +------>| | Code: 0.02 (POST)
| POST | | Token: 0x8c | POST | | Token: 0x8c
| | | Object-Security: [kid:5f,Partial IV:42] | | | Object-Security: [kid:5f,Partial IV:42]
| | | Payload: {Code:0.01, | | | Payload: {Code:0.01,
| | | Uri-Path:"alarm_status"} | | | Uri-Path:"alarm_status"}
| | | | | |
| +------>| Code: 0.02 (POST) | +------>| Code: 0.02 (POST)
skipping to change at page 44, line 30 skipping to change at page 49, line 30
| | 2.04 | Token: 0x7b | | 2.04 | Token: 0x7b
| | | Object-Security: - | | | Object-Security: -
| | | Payload: {Code:2.05, "OFF"} | | | Payload: {Code:2.05, "OFF"}
| | | | | |
|<------+ | Code: 2.04 (Changed) |<------+ | Code: 2.04 (Changed)
| 2.04 | | Token: 0x8c | 2.04 | | Token: 0x8c
| | | Object-Security: - | | | Object-Security: -
| | | Payload: {Code:2.05, "OFF"} | | | Payload: {Code:2.05, "OFF"}
| | | | | |
Figure 11: Secure Access to Sensor. Square brackets [ ... ] indicate Figure 12: Secure Access to Sensor. Square brackets [ ... ] indicate
content of compressed COSE object. Curly brackets { ... } indicate content of compressed COSE object. Curly brackets { ... } indicate
encrypted data. encrypted data.
The request/response Codes are encrypted by OSCORE and only dummy The request/response Codes are encrypted by OSCORE and only dummy
Codes (POST/Changed) are visible in the header of the OSCORE message. Codes (POST/Changed) are visible in the header of the OSCORE message.
The option Uri-Path ("alarm_status") and payload ("OFF") are The option Uri-Path ("alarm_status") and payload ("OFF") are
encrypted. 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 Partial IV (42). a Partial IV (42).
The server verifies that the Partial IV has not been received before. The server verifies that the Partial IV has not been received before.
The client verifies that the response is bound to the request. The client verifies that the response is bound to the request.
B.2. Secure Subscribe to Sensor A.2. Secure Subscribe to Sensor
This example targets the scenario in Section 3.2 of This example illustrates a client requesting subscription to a blood
[I-D.hartke-core-e2e-security-reqs] and illustrates a client sugar measurement resource (GET /glucose), first receiving the value
requesting subscription to a blood sugar measurement resource (GET 220 mg/dl and then a second value 180 mg/dl.
/glucose), first receiving the value 220 mg/dl and then a second
value 180 mg/dl.
Client Proxy Server Client Proxy Server
| | | | | |
+------>| | Code: 0.05 (FETCH) +------>| | Code: 0.05 (FETCH)
| FETCH | | Token: 0x83 | FETCH | | Token: 0x83
| | | Observe: 0 | | | Observe: 0
| | | Object-Security: [kid:ca,Partial IV:15] | | | Object-Security: [kid:ca,Partial IV:15]
| | | Payload: {Code:0.01, | | | Payload: {Code:0.01,
| | | Uri-Path:"glucose"} | | | Uri-Path:"glucose"}
| | | | | |
skipping to change at page 46, line 5 skipping to change at page 50, line 49
| | | Content-Format:0, "180"} | | | Content-Format:0, "180"}
| | | | | |
|<------+ | Code: 2.04 (Changed) |<------+ | Code: 2.04 (Changed)
| 2.04 | | Token: 0x83 | 2.04 | | Token: 0x83
| | | Observe: 8 | | | Observe: 8
| | | Object-Security: [Partial IV:36] | | | Object-Security: [Partial IV:36]
| | | Payload: {Code:2.05, | | | Payload: {Code:2.05,
| | | Content-Format:0, "180"} | | | Content-Format:0, "180"}
| | | | | |
Figure 12: Secure Subscribe to Sensor. Square brackets [ ... ] Figure 13: Secure Subscribe to Sensor. Square brackets [ ... ]
indicate content of compressed COSE header. Curly brackets { ... } indicate content of compressed COSE object header. Curly brackets {
indicate encrypted data. ... } indicate encrypted data.
The request/response Codes are encrypted by OSCORE and only dummy The request/response Codes are encrypted by OSCORE and only dummy
Codes (FETCH/Changed) are visible in the header of the OSCORE Codes (FETCH/Changed) are visible in the header of the OSCORE
message. The options Content-Format (0) and the payload ("220" and message. The options Content-Format (0) and the payload ("220" and
"180"), are encrypted. "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
Partial IV (15). The COSE headers of the responses contains Partial Partial IV (15). The COSE headers of the responses contains Partial
IVs (32 and 36). IVs (32 and 36).
The server verifies that the Partial IV has not been received before. The server verifies that the Partial IV has not been received before.
The client verifies that the responses are bound to the request and The client verifies that the responses are bound to the request and
that the Partial IVs are greater than any Partial IV previously that the Partial IVs are greater than any Partial IV previously
received in a response bound to the request. received in a response bound to the request.
Appendix B. Deployment examples
OSCORE may be deployed in a variety of settings, a few examples are
given in this section.
B.1. Master Secret Used Once
For settings where the Master Secret is only used during deployment,
the uniqueness of AEAD nonce may be assured by persistent storage of
the security context as described in this specification (see
Section 7.5). For many IoT deployments, a 128 bit uniformly random
Master Key is sufficient for encrypting all data exchanged with the
IoT device throughout its lifetime.
B.2. Master Secret Used Multiple Times
In cases where the Master Secret is used to derive security context
multiple times, e.g. during recommissioning or where the security
context is not persistently stored, the reuse of AEAD nonce may be
prevented by providing a sufficiently long uniformly random byte
string as Master Salt, such that the probability of Master Salt re-
use is negligible. The Master Salt may be transported in the Kid
Context parameter of the request (see Section 5.1)
B.3. Client Aliveness
The use of a single OSCORE request and response enables the client to
verify that the server's identity and aliveness through actual
communications. While a verified OSCORE request enables the server
to verify the identity of the entity who generated the message, it
does not verify that the client is currently involved in the
communication, since the message may be a delayed delivery of a
previously generated request which now reaches the server. To verify
the aliveness of the client the server may initiate an OSCORE
protected message exchange with the client, e.g. by switching the
roles of client and server as described in Section 3.1, or by using
the Echo option in the response to a request from the client
[I-D.ietf-core-echo-request-tag].
Appendix C. Test Vectors
This appendix includes the test vectors for different examples of
CoAP messages using OSCORE.
C.1. Test Vector 1: Key Derivation with Master Salt
Given a set of inputs, OSCORE defines how to set up the Security
Context in both the client and the server. The default values are
used for AEAD Algorithm and KDF.
C.1.1. Client
Inputs:
o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes)
o Master Salt: 0x9e7ca92223786340 (8 bytes)
o Sender ID: 0x (0 byte)
o Recipient ID: 0x01 (1 byte)
From the previous parameters,
o info (for Sender Key): 0x84400A634b657910 (8 bytes)
o info (for Recipient Key): 0x8441010A634b657910 (9 bytes)
o info (for Common IV): 0x84400a6249560d (7 bytes)
Outputs:
o Sender Key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes)
o Recipient Key: 0xe534a26a64aa3982e988e31f1e401e65 (16 bytes)
o Common IV: 0x01727733ab49ead385b18f7d91 (13 bytes)
C.1.2. Server
Inputs:
o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes)
o Master Salt: 0x9e7ca92223786340 (64 bytes)
o Sender ID: 0x01 (1 byte)
o Recipient ID: 0x (0 byte)
From the previous parameters,
o info (for Sender Key): 0x8441010A634b657910 (9 bytes)
o info (for Recipient Key): 0x84400A634b657910 (8 bytes)
o info (for Common IV): 0x84400a6249560d (7 bytes)
Outputs:
o Sender Key: 0xe534a26a64aa3982e988e31f1e401e65 (16 bytes)
o Recipient Key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes)
o Common IV: 0x01727733ab49ead385b18f7d91 (13 bytes)
C.2. Test Vector 2: Key Derivation without Master Salt
Given a set of inputs, OSCORE defines how to set up the Security
Context in both the client and the server. The default values are
used for AEAD Algorithm, KDF, and Master Salt.
C.2.1. Client
Inputs:
o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes)
o Sender ID: 0x00 (1 byte)
o Recipient ID: 0x01 (1 byte)
From the previous parameters,
o info (for Sender Key): 0x8441000A634b657910 (9 bytes)
o info (for Recipient Key): 0x8441010A634b657910 (9 bytes)
o info (for Common IV): 0x84400a6249560d (7 bytes)
Outputs:
o Sender Key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes)
o Recipient Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes)
o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes)
C.2.2. Server
Inputs:
o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes)
o Sender ID: 0x01 (1 byte)
o Recipient ID: 0x00 (1 byte)
From the previous parameters,
o info (for Sender Key): 0x8441010A634b657910 (9 bytes)
o info (for Recipient Key): 0x8441000A634b657910 (9 bytes)
o info (for Common IV): 0x84400a6249560d (7 bytes)
Outputs:
o Sender Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes)
o Recipient Key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes)
o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes)
C.3. Test Vector 3: OSCORE Request, Client
This section contains a test vector for a OSCORE protected CoAP GET
request using the security context derived in Appendix C.1. The
unprotected request only contains the Uri-Path option.
Unprotected CoAP request:
0x440149c60000f2a7396c6f63616c686f737483747631 (22 bytes)
Common Context:
o AEAD Algorithm: 10 (AES-CCM-16-64-128)
o Key Derivation Function: HKDF SHA-256
o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes)
Sender Context:
o Sender ID: 0x00 (1 byte)
o Sender Key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes)
o Sender Sequence Number: 20
The following COSE and cryptographic parameters are derived:
o Partial IV: 0x14 (1 byte)
o kid: 0x00 (1 byte)
o external_aad: 0x8501810a4100411440 (9 bytes)
o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes)
o plaintext: 0x01b3747631 (5 bytes)
o encryption key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes)
o nonce: 0xd0a1949aa253278f34c528d2d8 (13 bytes)
From the previous parameter, the following is derived:
o Object-Security value: 0x091400 (3 bytes)
o ciphertext: 0x55b3710d47c611cd3924838a44 (13 bytes)
From there:
o Protected CoAP request (OSCORE message): 0x44026dd30000acc5396c6f6
3616c686f7374d305091400ff55b3710d47c611cd3924838a44 (37 bytes)
C.4. Test Vector 4: OSCORE Request, Client
This section contains a test vector for a OSCORE protected CoAP GET
request using the security context derived in Appendix C.2. The
unprotected request only contains the Uri-Path option.
Unprotected CoAP request:
0x440149c60000f2a7396c6f63616c686f737483747631 (22 bytes)
Common Context:
o AEAD Algorithm: 10 (AES-CCM-16-64-128)
o Key Derivation Function: HKDF SHA-256
o Common IV: 0x01727733ab49ead385b18f7d91 (13 bytes)
Sender Context:
o Sender ID: 0x (0 bytes)
o Sender Key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes)
o Sender Sequence Number: 20
The following COSE and cryptographic parameters are derived:
o Partial IV: 0x14 (1 byte)
o kid: 0x (0 byte)
o external_aad: 0x8501810a40411440 (8 bytes)
o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes)
o plaintext: 0x01b3747631 (5 bytes)
o encryption key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes)
o nonce: 0x01727733ab49ead385b18f7d85 (13 bytes)
From the previous parameter, the following is derived:
o Object-Security value: 0x0914 (2 bytes)
o ciphertext: 0x6be9214aad448260ff1be1f594 (13 bytes)
From there:
o Protected CoAP request (OSCORE message): 0x44023bfc000066ef396c6f6
3616c686f7374d2050914ff6be9214aad448260ff1be1f594 (36 bytes)
C.5. Test Vector 5: OSCORE Response, Server
This section contains a test vector for a OSCORE protected 2.05
Content response to the request in Appendix C.3. The unprotected
response has payload "Hello World!" and no options. The protected
response does not contain a kid nor a Partial IV.
Unprotected CoAP response:
0x644549c60000f2a7ff48656c6c6f20576f726c6421 (21 bytes)
Common Context:
o AEAD Algorithm: 10 (AES-CCM-16-64-128)
o Key Derivation Function: HKDF SHA-256
o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes)
Sender Context:
o Sender ID: 0x01 (1 byte)
o Sender Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes)
o Sender Sequence Number: 0
The following COSE and cryptographic parameters are derived:
o external_aad: 0x8501810a4100411440 (9 bytes)
o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes)
o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes)
o encryption key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes)
o nonce: 0xd0a1949aa253278f34c528d2d8 (13 bytes)
From the previous parameter, the following is derived:
o Object-Security value: 0x (0 bytes)
o ciphertext: e4e8c28c41c8f31ca56eec24f6c71d94eacbcdffdc6d (22
bytes)
From there:
o Protected CoAP response (OSCORE message): 0x64446dd30000acc5d008ff
e4e8c28c41c8f31ca56eec24f6c71d94eacbcdffdc6d (33 bytes)
C.6. Test Vector 6: OSCORE Response with Partial IV, Server
This section contains a test vector for a OSCORE protected 2.05
Content response to the request in Appendix C.3. The unprotected
response has payload "Hello World!" and no options. The protected
response does not contain a kid, but contains a Partial IV.
Unprotected CoAP response:
0x644549c60000f2a7ff48656c6c6f20576f726c6421 (21 bytes)
Common Context:
o AEAD Algorithm: 10 (AES-CCM-16-64-128)
o Key Derivation Function: HKDF SHA-256
o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes)
Sender Context:
o Sender ID: 0x01 (1 byte)
o Sender Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes)
o Sender Sequence Number: 0
The following COSE and cryptographic parameters are derived:
o Partial IV: 0x00 (1 byte)
o external_aad: 0x8501810a4100411440 (9 bytes)
o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes)
o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes)
o encryption key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes)
o nonce: 0xd0a1949aa253278e34c528d2cc (13 bytes)
From the previous parameter, the following is derived:
o Object-Security value: 0x0100 (2 bytes)
o ciphertext: 0xa7e3ca27f221f453c0ba68c350bf652ea096b328a1bf (22
bytes)
From there:
o Protected CoAP response (OSCORE message): 0x64442b130000b29ed20801
00ffa7e3ca27f221f453c0ba68c350bf652ea096b328a1bf (35 bytes)
Acknowledgments
The following individuals provided input to this document: Christian
Amsuess, Tobias Andersson, Carsten Bormann, Joakim Brorsson, Esko
Dijk, Thomas Fossati, Martin Gunnarsson, Klaus Hartke, Jim Schaad,
Peter van der Stok, Dave Thaler, Marco Tiloca, and Malisa Vucinic.
Ludwig Seitz and Goeran Selander worked on this document as part of
the CelticPlus project CyberWI, with funding from Vinnova.
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 RISE SICS
Email: ludwig@sics.se Email: ludwig.seitz@ri.se
 End of changes. 224 change blocks. 
700 lines changed or deleted 1323 lines changed or added

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