draft-ietf-core-object-security-09.txt   draft-ietf-core-object-security-10.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: September 6, 2018 Ericsson AB Expires: September 15, 2018 Ericsson AB
L. Seitz L. Seitz
RISE SICS RISE SICS
March 05, 2018 March 14, 2018
Object Security for Constrained RESTful Environments (OSCORE) Object Security for Constrained RESTful Environments (OSCORE)
draft-ietf-core-object-security-09 draft-ietf-core-object-security-10
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 protection Signing and Encryption (COSE). OSCORE provides end-to-end protection
between endpoints communicating using CoAP or CoAP-mappable HTTP. between endpoints communicating using CoAP or CoAP-mappable HTTP.
OSCORE is designed for constrained nodes and networks supporting a OSCORE is designed for constrained nodes and networks supporting a
range of proxy operations, including translation between different range of proxy operations, including translation between different
transport protocols. transport protocols.
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 http://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 September 6, 2018. This Internet-Draft will expire on September 15, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2018 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 (http://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 . . . . . . . . . . . . . . . . . . . . . . . 6 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6
2. The CoAP Object-Security Option . . . . . . . . . . . . . . . 6 2. The CoAP Object-Security Option . . . . . . . . . . . . . . . 6
3. The Security Context . . . . . . . . . . . . . . . . . . . . 7 3. The Security Context . . . . . . . . . . . . . . . . . . . . 7
3.1. Security Context Definition . . . . . . . . . . . . . . . 7 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 . . . . . . . . . . . . . . . . . . 12 4. Protected Message Fields . . . . . . . . . . . . . . . . . . 12
4.1. CoAP Payload . . . . . . . . . . . . . . . . . . . . . . 13 4.1. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 13
4.2. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 14 4.2. CoAP Header Fields and Payload . . . . . . . . . . . . . 20
4.3. CoAP Header . . . . . . . . . . . . . . . . . . . . . . . 20 4.3. Signaling Messages . . . . . . . . . . . . . . . . . . . 21
4.4. Signaling Messages . . . . . . . . . . . . . . . . . . . 21 5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 21
5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 22
5.1. Kid Context . . . . . . . . . . . . . . . . . . . . . . . 23 5.1. Kid Context . . . . . . . . . . . . . . . . . . . . . . . 23
5.2. Nonce . . . . . . . . . . . . . . . . . . . . . . . . . . 24 5.2. Nonce . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.3. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 24 5.3. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 24
5.4. Additional Authenticated Data . . . . . . . . . . . . . . 25 5.4. Additional Authenticated Data . . . . . . . . . . . . . . 25
6. OSCORE Header Compression . . . . . . . . . . . . . . . . . . 26 6. OSCORE Header Compression . . . . . . . . . . . . . . . . . . 26
6.1. Encoding of the Object-Security Value . . . . . . . . . . 26 6.1. Encoding of the Object-Security Value . . . . . . . . . . 26
6.2. Encoding of the OSCORE Payload . . . . . . . . . . . . . 27 6.2. Encoding of the OSCORE Payload . . . . . . . . . . . . . 27
6.3. Examples of Compressed COSE Objects . . . . . . . . . . . 28 6.3. Examples of Compressed COSE Objects . . . . . . . . . . . 28
7. Sequence Numbers, Replay, Message Binding, and Freshness . . 29 7. Sequence Numbers, Replay, Message Binding, and Freshness . . 29
7.1. Message Binding . . . . . . . . . . . . . . . . . . . . . 29 7.1. Message Binding . . . . . . . . . . . . . . . . . . . . . 29
7.2. AEAD Nonce Uniqueness . . . . . . . . . . . . . . . . . . 29 7.2. AEAD Nonce Uniqueness . . . . . . . . . . . . . . . . . . 29
7.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 30 7.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 30
skipping to change at page 3, line 5 skipping to change at page 3, line 4
8.3. Protecting the Response . . . . . . . . . . . . . . . . . 34 8.3. Protecting the Response . . . . . . . . . . . . . . . . . 34
8.4. Verifying the Response . . . . . . . . . . . . . . . . . 35 8.4. Verifying the Response . . . . . . . . . . . . . . . . . 35
9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 36 9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 36
10. Proxy and HTTP Operations . . . . . . . . . . . . . . . . . . 37 10. Proxy and HTTP Operations . . . . . . . . . . . . . . . . . . 37
10.1. CoAP-to-CoAP Forwarding Proxy . . . . . . . . . . . . . 37 10.1. CoAP-to-CoAP Forwarding Proxy . . . . . . . . . . . . . 37
10.2. HTTP Processing . . . . . . . . . . . . . . . . . . . . 37 10.2. HTTP Processing . . . . . . . . . . . . . . . . . . . . 37
10.3. HTTP-to-CoAP Translation Proxy . . . . . . . . . . . . . 39 10.3. HTTP-to-CoAP Translation Proxy . . . . . . . . . . . . . 39
10.4. CoAP-to-HTTP Translation Proxy . . . . . . . . . . . . . 40 10.4. CoAP-to-HTTP Translation Proxy . . . . . . . . . . . . . 40
11. Security Considerations . . . . . . . . . . . . . . . . . . . 42 11. Security Considerations . . . . . . . . . . . . . . . . . . . 42
11.1. End-to-end protection . . . . . . . . . . . . . . . . . 42 11.1. End-to-end protection . . . . . . . . . . . . . . . . . 42
11.2. Security Context Establishment . . . . . . . . . . . . . 42 11.2. Security Context Establishment . . . . . . . . . . . . . 43
11.3. Replay Protection . . . . . . . . . . . . . . . . . . . 43 11.3. Replay Protection . . . . . . . . . . . . . . . . . . . 43
11.4. Cryptographic Considerations . . . . . . . . . . . . . . 43 11.4. Cryptographic Considerations . . . . . . . . . . . . . . 43
11.5. Message Fragmentation . . . . . . . . . . . . . . . . . 43 11.5. Message Fragmentation . . . . . . . . . . . . . . . . . 44
11.6. Privacy Considerations . . . . . . . . . . . . . . . . . 44 11.6. Privacy Considerations . . . . . . . . . . . . . . . . . 44
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 45 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 45
12.1. COSE Header Parameters Registry . . . . . . . . . . . . 45 12.1. COSE Header Parameters Registry . . . . . . . . . . . . 45
12.2. CoAP Option Numbers Registry . . . . . . . . . . . . . . 45 12.2. CoAP Option Numbers Registry . . . . . . . . . . . . . . 45
12.3. CoAP Signaling Option Numbers Registry . . . . . . . . . 45 12.3. CoAP Signaling Option Numbers Registry . . . . . . . . . 46
12.4. Header Field Registrations . . . . . . . . . . . . . . . 46 12.4. Header Field Registrations . . . . . . . . . . . . . . . 46
12.5. Media Type Registrations . . . . . . . . . . . . . . . . 46 12.5. Media Type Registrations . . . . . . . . . . . . . . . . 46
13. References . . . . . . . . . . . . . . . . . . . . . . . . . 48 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 48
13.1. Normative References . . . . . . . . . . . . . . . . . . 48 13.1. Normative References . . . . . . . . . . . . . . . . . . 48
13.2. Informative References . . . . . . . . . . . . . . . . . 49 13.2. Informative References . . . . . . . . . . . . . . . . . 49
Appendix A. Scenario examples . . . . . . . . . . . . . . . . . 51 Appendix A. Scenario Examples . . . . . . . . . . . . . . . . . 51
A.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 51 A.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 51
A.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 52 A.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 52
Appendix B. Deployment examples . . . . . . . . . . . . . . . . 54 Appendix B. Deployment examples . . . . . . . . . . . . . . . . 54
B.1. Master Secret Used Once . . . . . . . . . . . . . . . . . 54 B.1. Master Secret Used Once . . . . . . . . . . . . . . . . . 54
B.2. Master Secret Used Multiple Times . . . . . . . . . . . . 54 B.2. Master Secret Used Multiple Times . . . . . . . . . . . . 54
B.3. Client Aliveness . . . . . . . . . . . . . . . . . . . . 55 B.3. Client Aliveness . . . . . . . . . . . . . . . . . . . . 55
Appendix C. Test Vectors . . . . . . . . . . . . . . . . . . . . 56 Appendix C. Test Vectors . . . . . . . . . . . . . . . . . . . . 56
C.1. Test Vector 1: Key Derivation with Master Salt . . . . . 56 C.1. Test Vector 1: Key Derivation with Master Salt . . . . . 56
C.2. Test Vector 2: Key Derivation without Master Salt . . . . 57 C.2. Test Vector 2: Key Derivation without Master Salt . . . . 57
C.3. Test Vector 3: OSCORE Request, Client . . . . . . . . . . 58 C.3. Test Vector 3: OSCORE Request, Client . . . . . . . . . . 58
C.4. Test Vector 4: OSCORE Request, Client . . . . . . . . . . 59 C.4. Test Vector 4: OSCORE Request, Client . . . . . . . . . . 59
C.5. Test Vector 5: OSCORE Response, Server . . . . . . . . . 60 C.5. Test Vector 5: OSCORE Response, Server . . . . . . . . . 60
C.6. Test Vector 6: OSCORE Response with Partial IV, Server . 61 C.6. Test Vector 6: OSCORE Response with Partial IV, Server . 61
Appendix D. CDDL Summary . . . . . . . . . . . . . . . . . . . . 63 Appendix D. Security properties . . . . . . . . . . . . . . . . 63
Appendix E. CDDL Summary . . . . . . . . . . . . . . . . . . . . 63
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 63 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 63
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 64 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 64
1. Introduction 1. Introduction
The Constrained Application Protocol (CoAP) [RFC7252] is a web The Constrained Application Protocol (CoAP) [RFC7252] is a web
application protocol, designed for constrained nodes and networks application protocol, designed for constrained nodes and networks
[RFC7228], and may be mapped from HTTP [RFC8075]. CoAP specifies the [RFC7228], and may be mapped from HTTP [RFC8075]. CoAP specifies the
use of proxies for scalability and efficiency and references DTLS use of proxies for scalability and efficiency and references DTLS
([RFC6347]) for security. CoAP and HTTP proxies require (D)TLS to be ([RFC6347]) for security. CoAP-to-CoAP, HTTP-to-CoAP, and CoAP-to-
terminated at the proxy. The proxy therefore not only has access to HTTP proxies require (D)TLS to be terminated at the proxy. The proxy
the data required for performing the intended proxy functionality, therefore not only has access to the data required for performing the
but is also able to eavesdrop on, or manipulate any part of the intended proxy functionality, but is also able to eavesdrop on, or
message payload and metadata, in transit between the endpoints. The manipulate any part of, the message payload and metadata in transit
proxy can also inject, delete, or reorder packets since they are no between the endpoints. The proxy can also inject, delete, or reorder
longer protected by (D)TLS. packets since they are no 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], No-Response [RFC7967], and PATCH and [RFC7641], Blockwise [RFC7959], No-Response [RFC7967], and PATCH and
FETCH [RFC8132]. An analysis of end-to-end security for CoAP FETCH [RFC8132]. An analysis of end-to-end security for CoAP
messages through some types of intermediary nodes is performed in messages through some types of intermediary nodes is performed in
[I-D.hartke-core-e2e-security-reqs]. OSCORE essentially protects the [I-D.hartke-core-e2e-security-reqs]. OSCORE essentially protects the
RESTful interactions; the request method, the requested resource, the RESTful interactions; the request method, the requested resource, the
message payload, etc. (see Section 4). OSCORE does neither protect message payload, etc. (see Section 4). OSCORE protects neither the
the CoAP Messaging Layer nor the CoAP Token which may change between CoAP Messaging Layer nor the CoAP Token which may change between the
the endpoints, and those are therefore processed as defined in endpoints, and those are therefore processed as defined in [RFC7252].
[RFC7252]. Additionally, since the message formats for CoAP over Additionally, since the message formats for CoAP over unreliable
unreliable transport [RFC7252] and for CoAP over reliable transport transport [RFC7252] and for CoAP over reliable transport [RFC8323]
[RFC8323] differ only in terms of CoAP Messaging Layer, OSCORE can be differ only in terms of CoAP Messaging Layer, OSCORE can be applied
applied to both unreliable and reliable transports (see Figure 1). to both unreliable and reliable transports (see Figure 1).
+-----------------------------------+ +-----------------------------------+
| Application | | Application |
+-----------------------------------+ +-----------------------------------+
+-----------------------------------+ \ +-----------------------------------+ \
| Requests / Responses / Signaling | | | Requests / Responses / Signaling | |
|-----------------------------------| | |-----------------------------------| |
| OSCORE | | CoAP | OSCORE | | CoAP
|-----------------------------------| | |-----------------------------------| |
| Messaging Layer / Message Framing | | | Messaging Layer / Message Framing | |
skipping to change at page 4, line 50 skipping to change at page 4, line 50
OSCORE works in very constrained nodes and networks, thanks to its OSCORE works in very constrained nodes and networks, thanks to its
small message size and the restricted code and memory requirements in small message size and the restricted code and memory requirements in
addition to what is required by CoAP. Examples of the use of OSCORE addition to what is required by CoAP. Examples of the use of OSCORE
are given in Appendix A. OSCORE does not depend on underlying are given in Appendix A. OSCORE does not depend on underlying
layers, and can be used anywhere where CoAP or HTTP can be used, layers, and 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]). including non-IP transports (e.g., [I-D.bormann-6lo-coap-802-15-ie]).
OSCORE may be used together with (D)TLS over one or more hops in the OSCORE may be used together with (D)TLS over one or more hops in the
end-to-end path, e.g. with HTTPs in one hop and with plain CoAP in end-to-end path, e.g. with HTTPs in one hop and with plain CoAP in
another hop. another hop.
An extension of OSCORE may also be used to protect group The use of OSCORE does not affect the URI scheme and OSCORE can
communication for CoAP [I-D.tiloca-core-multicast-oscoap]. The use therefore be used with any URI scheme defined for CoAP or HTTP. The
of OSCORE does not affect the URI scheme and OSCORE can therefore be application decides the conditions for which OSCORE is required.
used with any URI scheme defined for CoAP or HTTP. The application
decides the conditions for which OSCORE is required.
OSCORE uses pre-shared keys which may have been established out-of- OSCORE uses pre-shared keys which may have been established out-of-
band or with a key establishment protocol (see Section 3.2). The band or with a key establishment protocol (see Section 3.2). The
technical solution builds on CBOR Object Signing and Encryption technical solution builds on CBOR Object Signing and Encryption
(COSE) [RFC8152], providing end-to-end encryption, integrity, replay (COSE) [RFC8152], providing end-to-end encryption, integrity, replay
protection, and secure binding of response to request. A compressed protection, and secure binding of response to request. A compressed
version of COSE is used, as specified in Section 6. The use of 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 OSCORE is signaled with the new Object-Security CoAP option or HTTP
header field, defined in Section 2 and Section 10.3. The solution header field, defined in Section 2 and Section 10.3. The solution
transforms a CoAP/HTTP message into an "OSCORE message" before transforms a CoAP/HTTP message into an "OSCORE message" before
skipping to change at page 5, line 42 skipping to change at page 5, line 40
| | | |
|<---------------------------------------------+ |<---------------------------------------------+
| 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 2: Sketch of CoAP with OSCORE Figure 2: Sketch of CoAP with OSCORE
An implementation supporting this specification MAY only implement An implementation supporting this specification MAY implement only
the client part, MAY only implement the server part, or MAY only the client part, MAY implement only the server part, or MAY implement
implement one of the proxy parts. OSCORE is designed to protect as only one of the proxy parts. OSCORE is designed to protect as much
much information as possible while still allowing proxy operations information as possible while still allowing proxy operations
(Section 10). It works with legacy CoAP-to-CoAP forward proxies (Section 10). It works with legacy CoAP-to-CoAP forward proxies
[RFC7252], but an OSCORE-aware proxy will be more efficient. HTTP- [RFC7252], but an OSCORE-aware proxy will be more efficient. HTTP-
to-CoAP proxies [RFC8075] and CoAP-to-HTTP proxies can also be used to-CoAP proxies [RFC8075] and CoAP-to-HTTP proxies can also be used
with OSCORE, as specified in Section 10. 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", "NOT RECOMMENDED", "MAY", and
document are to be interpreted as described in [RFC2119]. These "OPTIONAL" in this document are to be interpreted as described in BCP
words may also appear in this document in lowercase, absent their 14 [RFC2119] [RFC8174] when, and only when, they appear in all
normative meanings. capitals, as shown here.
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] as COSE [RFC8152], CBOR [RFC7049], CDDL [I-D.ietf-cbor-cddl] as
summarized in Appendix D, and constrained environments [RFC7228]. summarized in Appendix E, and constrained environments [RFC7228].
The term "hop" is used to denote a particular leg in the end-to-end 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 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 "hop-by-hop fragmentation") opposed to "end-to-end", is used in this
document to indicate that the messages are processed accordingly in document to indicate that the messages are processed accordingly in
the intermediaries, rather than just forwarded to the next node. the intermediaries, rather than just forwarded to the next node.
The term "stop processing" is used throughout the document to denote The term "stop processing" is used throughout the document to denote
that the message is not passed up to the CoAP Request/Response layer that the message is not passed up to the CoAP Request/Response layer
(see Figure 1). (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 3) indicates that the The CoAP Object-Security option (see Figure 3, which extends Table 4
CoAP message is an OSCORE message and that it contains a compressed of [RFC7252]) indicates that the CoAP message is an OSCORE message
COSE object (see Section 5 and Section 6). The Object-Security and that it contains a compressed COSE object (see Section 5 and
option is critical, safe to forward, part of the cache key, and not Section 6). The Object-Security option is critical, safe to forward,
repeatable. part of the cache key, and not 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 3: The Object-Security Option Figure 3: The Object-Security Option
skipping to change at page 7, line 18 skipping to change at page 7, line 18
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 8). Section 8).
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 request (see Section 10.1). As the compressed COSE Object original request (see Section 10.1). As the compressed COSE Object
is included in the cache key, messages with the Object-Security is included in the cache key, messages with the Object-Security
option will never generate cache hits. For Max-Age processing (see option will never generate cache hits. For Max-Age processing (see
Section 4.2.3.1). Section 4.1.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, [RFC5116]) Authenticated Encryption with Additional Data (AEAD, [RFC5116])
algorithm for protecting message data between a client and a server. algorithm for protecting message data between a client and a server.
In this section, we define the security context and how it is derived In this section, we define the security context and how it is derived
in client and server based on a shared secret and a key derivation in client and server based on a shared secret and a key derivation
function (KDF). function (KDF).
skipping to change at page 8, line 31 skipping to change at page 8, line 31
Retrieve context with |<----------------------+ Retrieve context with |<----------------------+
Token = Token1 | | Token = Token1 | |
Verify request with | | Verify request with | |
Recipient Context | | Recipient Context | |
Figure 4: 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. The COSE AEAD algorithm to use for encryption. o AEAD Algorithm. The COSE AEAD algorithm to use for encryption.
Its value is immutable once the security context is 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.
is immutable once the security context is established.
o Master Salt. Variable length byte string containing the salt used o Master Salt. Variable length byte string containing the salt used
to derive traffic keys and IVs. Its value is immutable once the to derive traffic keys and IVs.
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.
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 AEAD nonces. Maximum length is determined by the assure unique AEAD nonces. Maximum length is determined by the
AEAD Algorithm. Its value is immutable once the security context AEAD Algorithm.
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.
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 AEAD nonces. Maximum length is determined by and to assure unique AEAD nonces. Maximum length is determined by
the AEAD Algorithm. Its value is immutable once the security the AEAD Algorithm.
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.
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 All parameters except Sender Sequence Number and Replay Window are
Key, and Recipient Key, deriving them from the Master Key and Master immutable once the security context is established. An endpoint may
Salt when needed. Alternatively, an endpoint may free up memory by free up memory by not storing the Common IV, Sender Key, and
not storing the Master Secret and Master Salt after the other Recipient Key, deriving them from the Master Key and Master Salt when
parameters have been derived. needed. Alternatively, an endpoint may free up memory by not storing
the Master Secret and Master Salt after the other parameters have
been derived.
Endpoints MAY operate as both client and server and use the same Endpoints MAY operate as both client and server and use the same
security context for those roles. Independent of being client or security context for those roles. Independent of being client or
server, the endpoint protects messages to send using its Sender server, the endpoint protects messages to send using its Sender
Context, and verifies messages received using its Recipient Context. Context, and verifies messages received using its Recipient Context.
The endpoints MUST NOT change the Sender/Recipient ID when changing The endpoints MUST NOT change the Sender/Recipient ID when changing
roles. In other words, changing the roles does not change the set of roles. In other words, changing the roles 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
skipping to change at page 12, line 47 skipping to change at page 12, line 42
in terms of CoAP messages. If HTTP is used for a particular hop 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 [RFC8323]) is Protection of Signaling messages (Section 5 of [RFC8323]) is
specified in Section 4.4. The other parts of this section target specified in Section 4.3. The other parts of this section target
Request/Response messages. 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.
skipping to change at page 13, line 32 skipping to change at page 13, line 26
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 used to the receiving endpoint, whereas Outer message fields are used to
support proxy operations. Inner and Outer message fields are support proxy operations. Inner and Outer message fields are
processed independently. processed independently.
4.1. CoAP Payload 4.1. CoAP Options
The CoAP Payload, if present in the original CoAP message, SHALL be
encrypted and integrity protected and is thus an Inner message field.
See Figure 5.
+------------------+---+---+
| Field | E | U |
+------------------+---+---+
| Payload | x | |
+------------------+---+---+
E = Encrypt and Integrity Protect (Inner)
U = Unprotected (Outer)
Figure 5: Protection of CoAP Payload
The sending endpoint writes the payload of the original CoAP message
into the plaintext (Section 5.3) input to the COSE object. The
receiving endpoint verifies and decrypts the COSE object, and
recreates the payload of the original CoAP message.
4.2. CoAP Options
A summary of how options are protected is shown in Figure 6. Note A summary of how options are protected is shown in Figure 5. Note
that some options may have both Inner and Outer message fields which 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 | * | * | | 60 | Size1 | * | * |
| 258 | No-Response | * | * | | 258 | No-Response | * | * |
+-----+-----------------+---+---+ +-----+-----------------+---+---+
E = Encrypt and Integrity Protect (Inner) E = Encrypt and Integrity Protect (Inner)
U = Unprotected (Outer) U = Unprotected (Outer)
* = Special * = Special
Figure 6: Protection of CoAP Options Figure 5: 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.1.1. Inner Options
Inner option message fields (class E) are used to communicate Inner option message fields (class E) are used to communicate
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 8.2 and Section 8.4. endpoint is specified in Section 8.2 and Section 8.4.
4.2.2. Outer Options 4.1.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 instance of Outer
message field. option 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 8.2 and Section 8.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. Proxies MUST NOT change the
repeatable and of class I MUST specify that proxies MUST NOT change order of option's occurrences, for options repeatable and of class I.
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.1.3. Special Options
Some options require special processing, marked with an asterisk '*' Some options require special processing, marked with an asterisk '*'
in Figure 6; the processing is specified in this section. in Figure 5; the processing is specified in this section.
4.2.3.1. Max-Age 4.1.3.1. Max-Age
An Inner Max-Age message field is used to indicate the maximum time a An Inner Max-Age message field is used to indicate the maximum time a
response may be cached by the client (as defined in [RFC7252]), end- response may be cached by the client (as defined in [RFC7252]), end-
to-end from the server to the client, taking into account that the to-end from the server to the client, taking into account that the
option is not accessible to proxies. The Inner Max-Age SHALL be option is not accessible to proxies. The Inner Max-Age SHALL be
processed by OSCORE as specified in Section 4.2.1. processed by OSCORE as specified in Section 4.1.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 7.4, Section 8.2 and OSCORE error responses, which are described in Section 7.4,
Section 8.4, which is then processed according to Section 4.2.2. Section 8.2 and Section 8.4. Such message field is then processed
according to Section 4.1.2.
Successful OSCORE responses do not need to include an Outer Max-Age Successful OSCORE responses do not need to include an Outer Max-Age
option since the responses are non-cacheable by construction (see option since the responses are non-cacheable by construction (see
Section 4.3). Section 4.2).
4.2.3.2. The Block Options 4.1.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
Blockwise. 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. Outer Blockwise provided all blocks are received.
4.2.3.2.1. Inner Block Options 4.1.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.1.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.1.1 before processing Blockwise
as defined in [RFC7959]. as defined in [RFC7959].
For concurrent Blockwise operations the sending endpoint MUST ensure 4.1.3.2.2. Outer Block Options
that the receiving endpoint can distinguish between blocks from
different operations. One mechanism enabling this is specified in
[I-D.ietf-core-echo-request-tag].
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 introducing Block option message fields that are Outer
(Section 4.2.2) and not generated by the sending endpoint. Note that (Section 4.1.2) and not generated by the sending endpoint. Note that
the Outer Block options are neither encrypted nor integrity the Outer Block options are neither encrypted nor integrity
protected. As a consequence, a proxy can maliciously inject block protected. As a consequence, a proxy can maliciously inject block
fragments indefinitely, since the receiving endpoint needs to receive fragments indefinitely, since the receiving endpoint needs to receive
the last block (see [RFC7959]) to be able to compose the OSCORE the last block (see [RFC7959]) to be able to compose the OSCORE
message and verify its integrity. Therefore, applications supporting message and verify its integrity. Therefore, applications supporting
OSCORE and [RFC7959] MUST specify a security policy defining a OSCORE and [RFC7959] MUST specify a security policy defining a
maximum unfragmented message size (MAX_UNFRAGMENTED_SIZE) considering maximum unfragmented message size (MAX_UNFRAGMENTED_SIZE) considering
the maximum size of message which can be handled by the endpoints. the 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.1.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.
Because of encryption of Uri-Path and Uri-Query, messages to the same Because of encryption of Uri-Path and Uri-Query, messages to the same
server may, from the point of view of a proxy, look like they also server may, from the point of view of a proxy, look like they also
target the same resource. A proxy SHOULD mitigate a potential mix-up target the same resource. A proxy SHOULD mitigate a potential mix-up
of blocks from concurrent requests to the same server, for example of blocks from concurrent requests to the same server, for example
using the Request-Tag processing specified in Section 3.3.2 of 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.1.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.1.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.1.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 future 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.
skipping to change at page 18, line 19 skipping to change at page 18, line 4
During OSCORE processing, Proxy-Uri is split into: During OSCORE processing, Proxy-Uri is split into:
o Proxy-Scheme = "coap" o Proxy-Scheme = "coap"
o Uri-Host = "example.com" o Uri-Host = "example.com"
o Uri-Port = "5683" o Uri-Port = "5683"
o Uri-Path = "resource" o Uri-Path = "resource"
o Uri-Query = "q=1" o Uri-Query = "q=1"
Uri-Path and Uri-Query follow the processing defined in Uri-Path and Uri-Query follow the processing defined in
Section 4.2.1, and are thus encrypted and transported in the COSE Section 4.1.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 Sections 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.1.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] (Section 2.2.1). on forwarding of [I-D.hartke-core-e2e-security-reqs] (Section 2.2.1).
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.2.
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 7.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
skipping to change at page 19, line 27 skipping to change at page 19, line 12
with an Outer Observe value, it stops processing the message, as with an Outer Observe value, it stops processing the message, as
specified in Section 8.4. specified in Section 8.4.
Clients can re-register observations to ensure that the observation Clients can re-register observations to ensure that the observation
is still active and establish freshness again ([RFC7641] is still active and establish freshness again ([RFC7641]
Section 3.3.1). When an OSCORE observation is refreshed, not only 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- the ETags, but also the partial IV (and thus the payload and Object-
Security option) change. The server uses the new request's Partial Security option) change. The server uses the new request's Partial
IV as the 'request_piv' of new responses. IV as the 'request_piv' of new responses.
4.2.3.5. No-Response 4.1.3.5. No-Response
No-Response is defined in [RFC7967]. Clients using No-Response MUST No-Response is defined in [RFC7967]. Clients using No-Response MUST
set both an Inner (Class E) and an Outer (Class U) No-Response set both an Inner (Class E) and an Outer (Class U) No-Response
option, with same value. option, with same value.
The Inner No-Response option is used to communicate to the server the The Inner No-Response option is used to communicate to the server the
client's disinterest in certain classes of responses to a particular client's disinterest in certain classes of responses to a particular
request. The Inner No-Response SHALL be processed by OSCORE as request. The Inner No-Response SHALL be processed by OSCORE as
specified in Section 4.2.1. specified in Section 4.1.1.
The Outer No-Response option is used to support proxy functionality, The Outer No-Response option is used to support proxy functionality,
specifically to avoid error transmissions from proxies to clients, specifically to avoid error transmissions from proxies to clients,
and to avoid bandwidth reduction to servers by proxies applying and to avoid bandwidth reduction to servers by proxies applying
congestion control when not receiving responses. The Outer No- congestion control when not receiving responses. The Outer No-
Response option is processed according to Section 4.2.2. Response option is processed according to Section 4.1.2.
In particular, step 8 of Section 8.4 is applied to No-Response. In particular, step 8 of Section 8.4 is applied to No-Response.
Applications should consider that a proxy may remove the Outer No- Applications should consider that a proxy may remove the Outer No-
Response option from the request. Applications using No-Response can Response option from the request. Applications using No-Response can
specify policies to deal with cases where servers receive an Inner specify policies to deal with cases where servers receive an Inner
No-Response option only, which may be the result of the request No-Response option only, which may be the result of the request
having traversed a No-Response unaware proxy, and update the having traversed a No-Response unaware proxy, and update the
processing in Section 8.4 accordingly. This avoids unnecessary error processing in Section 8.4 accordingly. This avoids unnecessary error
responses to clients and bandwidth reductions to servers, due to No- responses to clients and bandwidth reductions to servers, due to No-
Response unaware proxies. Response unaware proxies.
4.2.3.6. Object-Security 4.1.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 integrity 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 content of this option is protected (see Section 5.4). "OSCORE
within OSCORE" is not supported: If OSCORE processing detects an within OSCORE" is not supported: If OSCORE processing detects an
Object-Security option in the original CoAP message, then processing Object-Security option in the original CoAP message, then processing
SHALL be stopped. SHALL be stopped.
4.3. CoAP Header 4.2. CoAP Header Fields and Payload
A summary of how the CoAP Header fields are protected is shown in A summary of how the CoAP header fields and payload are protected is
Figure 7, including fields specific to CoAP over UDP and CoAP over shown in Figure 6, including fields specific to CoAP over UDP and
TCP (marked accordingly in the table). 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 |
| Payload | x | |
+------------------+---+---+ +------------------+---+---+
E = Encrypt and Integrity Protect (Inner) E = Encrypt and Integrity Protect (Inner)
U = Unprotected (Outer) U = Unprotected (Outer)
Figure 7: Protection of CoAP Header Fields Figure 6: Protection of CoAP Header Fields and Payload
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
skipping to change at page 21, line 18 skipping to change at page 21, line 5
(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 currently defined CoAP Header fields are Unprotected (Class
endpoint SHALL write all other header fields of the original message U). The sending endpoint SHALL write all other header fields of the
into the header of the OSCORE message. The receiving endpoint SHALL original message into the header of the OSCORE message. The
write the header fields from the received OSCORE message into the receiving endpoint SHALL write the header fields from the received
header of the decrypted CoAP message. OSCORE message into the header of the decrypted CoAP message.
4.4. Signaling Messages The CoAP Payload, if present in the original CoAP message, SHALL be
encrypted and integrity protected and is thus an Inner message field.
The sending endpoint writes the payload of the original CoAP message
into the plaintext (Section 5.3) input to the COSE object. The
receiving endpoint verifies and decrypts the COSE object, and
recreates the payload of the original CoAP message.
4.3. Signaling Messages
Signaling messages (CoAP Code 7.00-7.31) were introduced to exchange Signaling messages (CoAP Code 7.00-7.31) were introduced to exchange
information related to an underlying transport connection in the information related to an underlying transport connection in the
specific case of CoAP over reliable transports ([RFC8323]). The use specific case of CoAP over reliable transports ([RFC8323]). The use
of OSCORE for protecting Signaling is application dependent. of OSCORE for protecting Signaling is application dependent.
OSCORE MAY be used to protect Signaling if the endpoints for OSCORE OSCORE MAY be used to protect Signaling if the endpoints for OSCORE
coincide with the endpoints for the connection. If OSCORE is used to coincide with the endpoints for the connection. If OSCORE is used to
protect Signaling then: protect Signaling then:
skipping to change at page 22, line 19 skipping to change at page 22, line 13
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.
As specified in [RFC5116], plaintext denotes the data that is As specified in [RFC5116], plaintext denotes the data that is to be
encrypted and integrity protected, and Additional Authenticated Data encrypted and integrity protected, and Additional Authenticated Data
(AAD) denotes the data that is integrity protected only. (AAD) denotes the data that is to be 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.1.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 will not
be present in responses. (A non-Observe example where the typically be present in responses. (A non-Observe example
Partial IV is included in a response is provided in where the Partial IV is included in a response is provided in
Section 7.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 will not typically
present in responses. An example where the Sender ID is be 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.ietf-core-oscore-groupcomm].
* 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), AEAD 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].
skipping to change at page 23, line 25 skipping to change at page 23, line 21
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 and kid are used to determine the security context, The kid context and kid are used to determine the security context,
or to establish the necessary input parameters to derive the security or to establish the necessary input parameters to derive the security
context (see Section 3.2). The application defines how this is done. context (see Section 3.2). The application defines how this is done.
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 8.2. in an error, as described in Section 8.2.
A summary of the COSE header parameter kid context defined above can A summary of the COSE header parameter kid context defined above can
be found in Figure 8. be found in Figure 7.
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 Appendix B.2 or entropy of the security contexts (see for example Appendix B.2 or
[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.ietf-core-oscore-groupcomm], 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 8: Additional common header parameter for the COSE object Figure 7: Additional common header parameter for the COSE object
5.2. Nonce 5.2. Nonce
The AEAD nonce is constructed in the following way (see Figure 9): The AEAD nonce is constructed in the following way (see Figure 8):
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,
skipping to change at page 24, line 29 skipping to change at page 24, line 22
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. The nonce construction with or greater than 7 bytes are supported. The nonce construction with
S, ID of PIV generator, and Partial IV together with endpoint unique 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 IDs and encryption keys make it easy to verify that the nonces used
with a specific key will be unique. 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 8). 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 9: AEAD Nonce Formation Figure 8: 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 10) consisting of: Figure 9) 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.1.1) present in the
original CoAP message (see Section 4.2). The options are encoded original CoAP message (see Section 4.1). 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 instance of Class E option;
and
o the Payload of original CoAP message, if present, and in that case o the Payload of original CoAP message, if present, and in that case
prefixed by the one-byte Payload Marker (0xFF). prefixed by the one-byte Payload Marker (0xFF).
0 1 2 3 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 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 10: Plaintext Figure 9: 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 = [
oscore_version : uint, oscore_version : uint,
skipping to change at page 26, line 8 skipping to change at page 25, line 50
o alg_aead: contains the AEAD Algorithm from the security context o alg_aead: contains the AEAD Algorithm from the security context
used 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.1.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 instance of 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. OSCORE Header Compression 6. OSCORE Header Compression
The Concise Binary Object Representation (CBOR) [RFC7049] combines The Concise Binary Object Representation (CBOR) [RFC7049] combines
very small message sizes with extensibility. The CBOR Object Signing very small message sizes with extensibility. The CBOR Object Signing
and Encryption (COSE) [RFC8152] uses CBOR to create compact encoding and Encryption (COSE) [RFC8152] uses CBOR to create compact encoding
skipping to change at page 26, line 52 skipping to change at page 26, line 46
0 1 2 3 4 5 6 7 <--------- n bytes -------------> 0 1 2 3 4 5 6 7 <--------- n bytes ------------->
+-+-+-+-+-+-+-+-+--------------------------------- +-+-+-+-+-+-+-+-+---------------------------------
|0 0 0|h|k| n | Partial IV (if any) ... |0 0 0|h|k| n | Partial IV (if any) ...
+-+-+-+-+-+-+-+-+--------------------------------- +-+-+-+-+-+-+-+-+---------------------------------
<- 1 byte -> <------ s bytes -----> <- 1 byte -> <------ s bytes ----->
+------------+----------------------+------------------+ +------------+----------------------+------------------+
| s (if any) | kid context (if any) | kid (if any) ... | | s (if any) | kid context (if any) | kid (if any) ... |
+------------+----------------------+------------------+ +------------+----------------------+------------------+
Figure 11: Object-Security Value Figure 10: Object-Security Value
o The first byte of flag bits encodes the following set of flags and o The first byte of flag bits encodes the following set of flags and
the length of the Partial IV parameter: the length of the Partial IV parameter:
* The three least significant bits encode the Partial IV length * The three least significant bits encode the Partial IV length
n. If n = 0 then the Partial IV is not present in the n. If n = 0 then the Partial IV is not present in the
compressed COSE object. The values n = 6 and n = 7 are compressed COSE object. The values n = 6 and n = 7 are
reserved. reserved.
* The fourth least significant bit is the kid flag, k: it is set * The fourth least significant bit is the kid flag, k: it is set
skipping to change at page 28, line 9 skipping to change at page 28, line 9
6.2. Encoding of the OSCORE Payload 6.2. Encoding of the OSCORE Payload
The payload of the OSCORE message SHALL encode the ciphertext of the The payload of the OSCORE message SHALL encode the ciphertext of the
COSE object. COSE object.
6.3. Examples of Compressed COSE Objects 6.3. Examples of Compressed COSE Objects
6.3.1. Examples: Requests 6.3.1. Examples: Requests
1. Request with kid = 25 and Partial IV = 5 1. Request with kid = 0x25 and Partial IV = 0x05
Before compression (24 bytes): Before compression (24 bytes):
[ [
h'', h'',
{ 4:h'25', 6:h'05' }, { 4:h'25', 6:h'05' },
h'aea0155667924dff8a24e4cb35b9' h'aea0155667924dff8a24e4cb35b9'
] ]
After compression (17 bytes): After compression (17 bytes):
Flag byte: 0b00001001 = 0x09 Flag byte: 0b00001001 = 0x09
Option Value: 09 05 25 (3 bytes) Option Value: 09 05 25 (3 bytes)
Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 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 2. Request with kid = empty string and Partial IV = 0x00
After compression (16 bytes): After compression (16 bytes):
Flag byte: 0b00001001 = 0x09 Flag byte: 0b00001001 = 0x09
Option Value: 09 00 (2 bytes) Option Value: 09 00 (2 bytes)
Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 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 3. Request with kid = empty string, Partial IV = 0x05, and kid
= 0x44616c656b context = 0x44616c656b
After compression (22 bytes): After compression (22 bytes):
Flag byte: 0b00011001 = 0x19 Flag byte: 0b00011001 = 0x19
Option Value: 19 05 05 44 61 6c 65 6b (8 bytes) 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) Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes)
6.3.2. Example: Response (without Observe) 6.3.2. Example: Response (without Observe)
skipping to change at page 30, line 16 skipping to change at page 30, line 16
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.
7.3. Freshness 7.3. Freshness
For requests, OSCORE provides weak absolute freshness as the only For requests, OSCORE provides only the guarantee that the request is
guarantee is that the request is not older than the security context. not older than the security context. For applications having
For applications having stronger demands on request freshness (e.g., stronger demands on request freshness (e.g., control of actuators),
control of actuators), OSCORE needs to be augmented with mechanisms OSCORE needs to be augmented with mechanisms providing freshness, for
providing freshness, for example as specified in 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 re-register 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.
skipping to change at page 31, line 29 skipping to change at page 31, line 29
7.5. Losing Part of the Context State 7.5. Losing Part of the Context State
To prevent reuse of the AEAD nonce with the same key, or from To prevent reuse of the AEAD nonce with the same key, or from
accepting replayed messages, an endpoint needs to handle the accepting replayed messages, an endpoint needs to handle the
situation of losing rapidly changing parts of the context, such as situation of losing rapidly changing parts of the context, such as
the request Token, Sender Sequence Number, Replay Window, and the request Token, Sender Sequence Number, Replay Window, and
Notification Numbers. These are typically stored in RAM and Notification Numbers. These are typically stored in RAM and
therefore lost in the case of an unplanned reboot. therefore lost in the case of an unplanned reboot.
After boot, an endpoint MAY reject to use existing security contexts After boot, an endpoint MAY reject to use pre-existing security
from before it booted and MAY establish a new security context with contexts, and MAY establish a new security context with each endpoint
each party it communicates. However, establishing a fresh security it communicates with. However, establishing a fresh security context
context may have a non-negligible cost in terms of, e.g., power may have a non-negligible cost in terms of, e.g., power consumption.
consumption.
After boot, an endpoint MAY use a partly persistently stored security After boot, an endpoint MAY use a partly persistently stored security
context, but then the endpoint MUST NOT reuse a previous Sender context, but then the endpoint MUST NOT reuse a previous Sender
Sequence Number and MUST NOT accept previously accepted messages. Sequence Number and MUST NOT accept previously accepted messages.
Some ways to achieve this is described below: Some ways to achieve this are described in the following sections.
7.5.1. Sequence Number 7.5.1. Sequence Number
To prevent reuse of Sender Sequence Numbers, an endpoint MAY perform To prevent reuse of Sender Sequence Numbers, an endpoint MAY perform
the 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 endpoint 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.
skipping to change at page 33, line 6 skipping to change at page 33, line 6
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 and (in one atomic operation, see Section 7.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 6. 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.1.2).
6. Store the association Token - Security Context. The client SHALL 6. Store the association Token - Security Context, in order to be
be able to find the Recipient Context from the Token in the able to find the Recipient Context from the Token in the
response. response.
8.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.1.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 6) present message fields (marked with 'x' in column E of Figure 5) 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 6) 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:
skipping to change at page 35, line 16 skipping to change at page 35, line 16
used or a new Partial IV is used (see bullet on 'Partial IV' used or a new Partial IV is used (see bullet on 'Partial IV'
in Section 5). in Section 5).
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 6. If the AEAD nonce was Object as specified in Section 6. If the AEAD nonce was
constructed from a new Partial IV, this Partial IV MUST be constructed from a new Partial IV, this Partial IV MUST be
included in the message. If the AEAD nonce from the request was included in the message. If the AEAD nonce from the request was
used, the Partial IV 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.1.2).
8.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.1.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 6). 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.
skipping to change at page 37, line 40 skipping to change at page 37, line 40
Proxy processing of the (Outer) Block options is as defined in Proxy processing of the (Outer) Block options is as defined in
[RFC7959]. [RFC7959].
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 Processing 10.2. HTTP Processing
OSCORE was initially designed to work between CoAP endpoints only,
but the interest in use cases with one endpoint being an HTTP
endpoint has driven the extension specified here. OSCORE is intended
to be used with at least one endpoint being a CoAP endpoint.
In order to use OSCORE with HTTP, an endpoint needs to be able to map 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 HTTP messages to CoAP messages (see [RFC8075]), and to apply OSCORE
to CoAP messages (as defined in this document). to CoAP messages (as defined in this document).
For this purpose, this specification defines a new HTTP header field For this purpose, this specification defines a new HTTP header field
named CoAP-Object-Security, see Section 12.4. The CoAP-Object- named CoAP-Object-Security, see Section 12.4. The CoAP-Object-
Security header field is only used in POST requests and 200 (OK) Security header field is only used in POST requests and 200 (OK)
responses. All field semantics is given within the CoAP-Object- responses. All field semantics is given within the CoAP-Object-
Security header field. The header field is neither appropriate to Security header field. The header field is neither appropriate to
list in the Connection header field (see Section 6.1 of [RFC7230]), list in the Connection header field (see Section 6.1 of [RFC7230]),
skipping to change at page 38, line 15 skipping to change at page 38, line 18
Intermediaries are not allowed to insert, delete, or modify the Intermediaries are not allowed to insert, delete, or modify the
field's value. The header field is not preserved across redirects. field's value. The header field is not preserved across redirects.
A sending endpoint uses [RFC8075] to translate an HTTP message into a A sending endpoint uses [RFC8075] to translate an HTTP message into a
CoAP message. It then protects the message with OSCORE processing, CoAP message. It then protects the message with OSCORE processing,
and add the Object-Security option (as defined in this document). and add the Object-Security option (as defined in this document).
Then, the endpoint maps the resulting CoAP message to an HTTP message Then, the endpoint maps the resulting CoAP message to an HTTP message
that includes the HTTP header field CoAP-Object-Security, whose value that includes the HTTP header field CoAP-Object-Security, whose value
is: is:
o "" (empty string) if the CoAP Object-Security option is empty, or o "" if the CoAP Object-Security option is empty, or
o the value of the CoAP Object-Security option (Section 6.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).
Note that the value of the HTTP body is the CoAP payload, i.e. the Note that the value of the HTTP body is the CoAP payload, i.e. the
OSCORE payload (Section 6.2). OSCORE payload (Section 6.2).
The HTTP header field Content-Type is set to 'application/oscore' The HTTP header field Content-Type is set to 'application/oscore'
(see Section 12.5). (see Section 12.5).
The resulting message is an OSCORE message that uses HTTP. The resulting message is an OSCORE message that uses HTTP.
A receiving endpoint uses [RFC8075] to translate an HTTP message into A receiving endpoint uses [RFC8075] to translate an HTTP message into
a CoAP message, with the following addition. The HTTP message a CoAP message, with the following addition. The HTTP message
includes the CoAP-Object-Security header field, which is mapped to includes the CoAP-Object-Security header field, which is mapped to
the CoAP Object-Security option in the following way. The CoAP the CoAP Object-Security option in the following way. The CoAP
Object-Security option value is: Object-Security option value is:
o empty if the value of the HTTP CoAP-Object-Security header field o empty if the value of the HTTP CoAP-Object-Security header field
is "" (empty string) is ""
o the value of the HTTP CoAP-Object-Security header field decoded o the value of the HTTP CoAP-Object-Security header field decoded
from base64url (Section 5 of [RFC4648]) without padding (see from base64url (Section 5 of [RFC4648]) without padding (see
[RFC7515] Appendix C for implementation notes for this decoding). [RFC7515] Appendix C for implementation notes for this decoding).
Note that the value of the CoAP payload is the HTTP body, i.e. the Note that the value of the CoAP payload is the HTTP body, i.e. the
OSCORE payload (Section 6.2). OSCORE payload (Section 6.2).
The resulting message is an OSCORE message that uses CoAP. The resulting message is an OSCORE message that uses CoAP.
skipping to change at page 39, line 17 skipping to change at page 39, line 21
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 CoAP-Object- responses, is expressed in an HTTP header field named CoAP-Object-
Security in the mapped request or response. The value of the field Security in the mapped request or response. The value of the field
is: is:
o "" (empty string) if the CoAP Object-Security option is empty, or o "" if the CoAP Object-Security option is empty, or
o the value of the CoAP Object-Security option (Section 6.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 header field Content-Type 'application/oscore' (see Section 12.5) The header field Content-Type 'application/oscore' (see Section 12.5)
is used for OSCORE messages transported in HTTP. The CoAP Content- is used for OSCORE messages transported in HTTP. The CoAP Content-
Format option is omitted for OSCORE messages transported in CoAP. Format option is omitted for OSCORE messages transported in CoAP.
The value of the body is the OSCORE payload (Section 6.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 client 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
Content-Type: application/oscore Content-Type: application/oscore
CoAP-Object-Security: 09 25 CoAP-Object-Security: CSU
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 request -- After server object security processing] [CoAP request -- After server object security processing]
skipping to change at page 40, line 25 skipping to change at page 40, line 31
[CoAP response -- CoAP Server to Proxy] [CoAP response -- CoAP Server to Proxy]
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]
[HTTP response -- Proxy to HTTP Client] [HTTP response -- Proxy to HTTP Client]
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/oscore Content-Type: application/oscore
CoAP-Object-Security: "" (empty string) CoAP-Object-Security: ""
Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary]
[HTTP response -- After client object security processing] [HTTP response -- After client object security processing]
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: text/plain Content-Type: text/plain
Body: Exterminate! Exterminate! 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
skipping to change at page 41, line 16 skipping to change at page 41, line 23
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
Content-Type: application/oscore Content-Type: application/oscore
CoAP-Object-Security: 09 25 CoAP-Object-Security: CSU
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] [HTTP request -- After server object security processing]
GET http://server.url/orders HTTP/1.1 GET http://server.url/orders HTTP/1.1
[HTTP response -- Before server object security processing] [HTTP response -- Before server object security processing]
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: text/plain Content-Type: text/plain
Body: Exterminate! Exterminate! 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
Content-Type: application/oscore Content-Type: application/oscore
CoAP-Object-Security: "" (empty string) CoAP-Object-Security: ""
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 - Proxy to CoAP Client] [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 client object security processing] [CoAP response -- After client object security processing]
skipping to change at page 44, line 16 skipping to change at page 44, line 27
11.6. Privacy Considerations 11.6. Privacy Considerations
Privacy threats executed through intermediary 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 6) may reveal privacy sensitive The unprotected options (Figure 5) may reveal privacy sensitive
information. In particular Uri-Host SHOULD NOT contain privacy information. In particular Uri-Host SHOULD NOT contain privacy
sensitive information. CoAP headers sent in plaintext allow, for sensitive information. CoAP headers sent in plaintext allow, for
example, matching of CON and ACK (CoAP Message Identifier), matching example, matching of CON and ACK (CoAP Message Identifier), matching
of request and responses (Token) and traffic analysis. OSCORE does of request and responses (Token) and traffic analysis. OSCORE does
not provide protection for HTTP header fields which are not CoAP- not provide protection for HTTP header fields which are not CoAP-
mappable. mappable.
Unprotected error messages reveal information about the security Unprotected error messages reveal information about the security
state in the communication between the endpoints. Unprotected state in the communication between the endpoints. Unprotected
signalling messages reveal information about the reliable transport signalling messages reveal information about the reliable transport
skipping to change at page 45, line 20 skipping to change at page 45, line 27
Note to IANA: Please note all occurrences of "TBD" in this Note to IANA: Please note all occurrences of "TBD" in this
specification should be assigned the same number. specification should be assigned the same number.
12.1. COSE Header Parameters Registry 12.1. COSE Header Parameters Registry
The 'kid context' parameter is added to the "COSE Header Parameters 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: TBD1 (Integer value between 1 and 255)
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
12.2. CoAP Option Numbers Registry 12.2. CoAP Option Numbers Registry
skipping to change at page 48, line 11 skipping to change at page 48, line 11
Change Controller: IESG Change Controller: IESG
Provisional registration? No Provisional registration? No
13. References 13. References
13.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-
<https://www.rfc-editor.org/info/rfc2119>. 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>.
[RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer
Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347,
January 2012, <https://www.rfc-editor.org/info/rfc6347>. January 2012, <https://www.rfc-editor.org/info/rfc6347>.
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
October 2013, <https://www.rfc-editor.org/info/rfc7049>. October 2013, <https://www.rfc-editor.org/info/rfc7049>.
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Message Syntax and Routing", Protocol (HTTP/1.1): Message Syntax and Routing",
RFC 7230, DOI 10.17487/RFC7230, June 2014, RFC 7230, DOI 10.17487/RFC7230, June 2014,
<https://www.rfc-editor.org/info/rfc7230>. <https://www.rfc-editor.org/info/rfc7230>.
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Semantics and Content", RFC 7231, Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
DOI 10.17487/RFC7231, June 2014, DOI 10.17487/RFC7231, June 2014, <https://www.rfc-
<https://www.rfc-editor.org/info/rfc7231>. editor.org/info/rfc7231>.
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252, Application Protocol (CoAP)", RFC 7252,
DOI 10.17487/RFC7252, June 2014, DOI 10.17487/RFC7252, June 2014, <https://www.rfc-
<https://www.rfc-editor.org/info/rfc7252>. editor.org/info/rfc7252>.
[RFC7641] Hartke, K., "Observing Resources in the Constrained [RFC7641] Hartke, K., "Observing Resources in the Constrained
Application Protocol (CoAP)", RFC 7641, Application Protocol (CoAP)", RFC 7641,
DOI 10.17487/RFC7641, September 2015, DOI 10.17487/RFC7641, September 2015, <https://www.rfc-
<https://www.rfc-editor.org/info/rfc7641>. editor.org/info/rfc7641>.
[RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in
the Constrained Application Protocol (CoAP)", RFC 7959, the Constrained Application Protocol (CoAP)", RFC 7959,
DOI 10.17487/RFC7959, August 2016, DOI 10.17487/RFC7959, August 2016, <https://www.rfc-
<https://www.rfc-editor.org/info/rfc7959>. editor.org/info/rfc7959>.
[RFC8075] Castellani, A., Loreto, S., Rahman, A., Fossati, T., and [RFC8075] Castellani, A., Loreto, S., Rahman, A., Fossati, T., and
E. Dijk, "Guidelines for Mapping Implementations: HTTP to E. Dijk, "Guidelines for Mapping Implementations: HTTP to
the Constrained Application Protocol (CoAP)", RFC 8075, the Constrained Application Protocol (CoAP)", RFC 8075,
DOI 10.17487/RFC8075, February 2017, DOI 10.17487/RFC8075, February 2017, <https://www.rfc-
<https://www.rfc-editor.org/info/rfc8075>. editor.org/info/rfc8075>.
[RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and
FETCH Methods for the Constrained Application Protocol FETCH Methods for the Constrained Application Protocol
(CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017,
<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>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[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-
<https://www.rfc-editor.org/info/rfc8288>. editor.org/info/rfc8288>.
[RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K.,
Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained
Application Protocol) over TCP, TLS, and WebSockets", Application Protocol) over TCP, TLS, and WebSockets",
RFC 8323, DOI 10.17487/RFC8323, February 2018, RFC 8323, DOI 10.17487/RFC8323, February 2018,
<https://www.rfc-editor.org/info/rfc8323>. <https://www.rfc-editor.org/info/rfc8323>.
13.2. Informative References 13.2. Informative References
[I-D.bormann-6lo-coap-802-15-ie] [I-D.bormann-6lo-coap-802-15-ie]
skipping to change at page 49, line 46 skipping to change at page 49, line 50
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-
security-reqs-03 (work in progress), July 2017. security-reqs-03 (work in progress), July 2017.
[I-D.ietf-6tisch-minimal-security] [I-D.ietf-6tisch-minimal-security]
Vucinic, M., Simon, J., Pister, K., and M. Richardson, Vucinic, M., Simon, J., Pister, K., and M. Richardson,
"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-05 (work in progress), March 2018.
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-10 (work in progress), February 2018. authz-10 (work in progress), February 2018.
[I-D.ietf-ace-oscore-profile] [I-D.ietf-ace-oscore-profile]
Seitz, L., Palombini, F., and M. Gunnarsson, "OSCORE Seitz, L., Palombini, F., and M. Gunnarsson, "OSCORE
profile of the Authentication and Authorization for profile of the Authentication and Authorization for
skipping to change at page 50, line 28 skipping to change at page 50, line 28
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-02 express CBOR data structures", draft-ietf-cbor-cddl-02
(work in progress), February 2018. (work in progress), February 2018.
[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.ietf-core-oscore-groupcomm]
Tiloca, M., Selander, G., Palombini, F., and J. Park,
"Secure group communication for CoAP", draft-ietf-core-
oscore-groupcomm-01 (work in progress), March 2018.
[I-D.mattsson-ace-tls-oscore] [I-D.mattsson-ace-tls-oscore]
Mattsson, J., "Using Transport Layer Security (TLS) to Mattsson, J., "Using Transport Layer Security (TLS) to
Secure OSCORE", draft-mattsson-ace-tls-oscore-00 (work in Secure OSCORE", draft-mattsson-ace-tls-oscore-00 (work in
progress), October 2017. 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-04 (work in progress), March
October 2017. 2018.
[I-D.selander-ace-cose-ecdhe] [I-D.selander-ace-cose-ecdhe]
Selander, G., Mattsson, J., and F. Palombini, "Ephemeral Selander, G., Mattsson, J., and F. Palombini, "Ephemeral
Diffie-Hellman Over COSE (EDHOC)", draft-selander-ace- Diffie-Hellman Over COSE (EDHOC)", draft-selander-ace-
cose-ecdhe-07 (work in progress), July 2017. cose-ecdhe-07 (work in progress), July 2017.
[I-D.tiloca-core-multicast-oscoap]
Tiloca, M., Selander, G., Palombini, F., and J. Park,
"Secure group communication for CoAP", draft-tiloca-core-
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 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated
Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008,
<https://www.rfc-editor.org/info/rfc5116>. <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-
<https://www.rfc-editor.org/info/rfc5869>. 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-
<https://www.rfc-editor.org/info/rfc7228>. 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>.
[RFC7967] Bhattacharyya, A., Bandyopadhyay, S., Pal, A., and T. [RFC7967] Bhattacharyya, A., Bandyopadhyay, S., Pal, A., and T.
Bose, "Constrained Application Protocol (CoAP) Option for Bose, "Constrained Application Protocol (CoAP) Option for
No Server Response", RFC 7967, DOI 10.17487/RFC7967, No Server Response", RFC 7967, DOI 10.17487/RFC7967,
August 2016, <https://www.rfc-editor.org/info/rfc7967>. August 2016, <https://www.rfc-editor.org/info/rfc7967>.
Appendix A. Scenario examples Appendix A. Scenario Examples
This section gives examples of OSCORE, targeting scenarios in This section gives examples of OSCORE, targeting scenarios in
Section 2.2.1.1 of [I-D.hartke-core-e2e-security-reqs]. The message Section 2.2.1.1 of [I-D.hartke-core-e2e-security-reqs]. The message
exchanges are made, based on the assumption that there is a security exchanges are made, based on the assumption that there is a security
context established between client and server. For simplicity, these 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.
A.1. Secure Access to Sensor A.1. Secure Access to Sensor
skipping to change at page 52, line 30 skipping to change at page 52, 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 12: Secure Access to Sensor. Square brackets [ ... ] indicate Figure 11: 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 the request as specified in Section 8.2. The
The client verifies that the response is bound to the request. client verifies the response as specified in Section 8.4.
A.2. Secure Subscribe to Sensor A.2. Secure Subscribe to Sensor
This example illustrates a client requesting subscription to a blood This example illustrates a client requesting subscription to a blood
sugar measurement resource (GET /glucose), first receiving the value sugar measurement resource (GET /glucose), first receiving the value
220 mg/dl and then a second value 180 mg/dl. 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)
skipping to change at page 53, line 49 skipping to change at page 53, 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 13: Secure Subscribe to Sensor. Square brackets [ ... ] Figure 12: Secure Subscribe to Sensor. Square brackets [ ... ]
indicate content of compressed COSE object 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
skipping to change at page 63, line 5 skipping to change at page 63, line 5
o Object-Security value: 0x0100 (2 bytes) o Object-Security value: 0x0100 (2 bytes)
o ciphertext: 0xa7e3ca27f221f453c0ba68c350bf652ea096b328a1bf (22 o ciphertext: 0xa7e3ca27f221f453c0ba68c350bf652ea096b328a1bf (22
bytes) bytes)
From there: From there:
o Protected CoAP response (OSCORE message): 0x64442b130000b29ed20801 o Protected CoAP response (OSCORE message): 0x64442b130000b29ed20801
00ffa7e3ca27f221f453c0ba68c350bf652ea096b328a1bf (35 bytes) 00ffa7e3ca27f221f453c0ba68c350bf652ea096b328a1bf (35 bytes)
Appendix D. CDDL Summary Appendix D. Security properties
This appendix discusses security properties of OSCORE.
TODO
Appendix E. CDDL Summary
Data structure definitions in the present specification employ the Data structure definitions in the present specification employ the
CDDL language for conciseness and precision. CDDL is defined in CDDL language for conciseness and precision. CDDL is defined in
[I-D.ietf-cbor-cddl], which at the time of writing this appendix is [I-D.ietf-cbor-cddl], which at the time of writing this appendix is
in the process of completion. As the document is not yet available in the process of completion. As the document is not yet available
for a normative reference, the present appendix defines the small for a normative reference, the present appendix defines the small
subset of CDDL that is being used in the present specification. subset of CDDL that is being used in the present specification.
Within the subset being used here, a CDDL rule is of the form "name = Within the subset being used here, a CDDL rule is of the form "name =
type", where "name" is the name given to the "type". A "type" can be type", where "name" is the name given to the "type". A "type" can be
 End of changes. 129 change blocks. 
261 lines changed or deleted 247 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/