draft-ietf-core-object-security-15.txt   draft-ietf-core-object-security-16.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 Updates: 7252 (if approved) F. Palombini
Expires: March 4, 2019 Ericsson AB Intended status: Standards Track Ericsson AB
L. Seitz Expires: September 7, 2019 L. Seitz
RISE SICS RISE SICS
August 31, 2018 March 06, 2019
Object Security for Constrained RESTful Environments (OSCORE) Object Security for Constrained RESTful Environments (OSCORE)
draft-ietf-core-object-security-15 draft-ietf-core-object-security-16
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.
Although being an optional functionality of CoAP, OSCORE alters CoAP
options processing and IANA registration. Therefore, this document
updates [RFC7252].
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on March 4, 2019. This Internet-Draft will expire on September 7, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6
2. The OSCORE Option . . . . . . . . . . . . . . . . . . . . . . 7 2. The OSCORE Option . . . . . . . . . . . . . . . . . . . . . . 7
3. The Security Context . . . . . . . . . . . . . . . . . . . . 7 3. The Security Context . . . . . . . . . . . . . . . . . . . . 7
3.1. Security Context Definition . . . . . . . . . . . . . . . 8 3.1. Security Context Definition . . . . . . . . . . . . . . . 8
3.2. Establishment of Security Context Parameters . . . . . . 10 3.2. Establishment of Security Context Parameters . . . . . . 10
3.3. Requirements on the Security Context Parameters . . . . . 13 3.3. Requirements on the Security Context Parameters . . . . . 12
4. Protected Message Fields . . . . . . . . . . . . . . . . . . 14 4. Protected Message Fields . . . . . . . . . . . . . . . . . . 13
4.1. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 15 4.1. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 14
4.2. CoAP Header Fields and Payload . . . . . . . . . . . . . 23 4.2. CoAP Header Fields and Payload . . . . . . . . . . . . . 23
4.3. Signaling Messages . . . . . . . . . . . . . . . . . . . 24 4.3. Signaling Messages . . . . . . . . . . . . . . . . . . . 23
5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 24 5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 24
5.1. Kid Context . . . . . . . . . . . . . . . . . . . . . . . 26 5.1. ID Context and 'kid context' . . . . . . . . . . . . . . 25
5.2. AEAD Nonce . . . . . . . . . . . . . . . . . . . . . . . 26 5.2. AEAD Nonce . . . . . . . . . . . . . . . . . . . . . . . 26
5.3. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 27 5.3. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 27
5.4. Additional Authenticated Data . . . . . . . . . . . . . . 28 5.4. Additional Authenticated Data . . . . . . . . . . . . . . 28
6. OSCORE Header Compression . . . . . . . . . . . . . . . . . . 29 6. OSCORE Header Compression . . . . . . . . . . . . . . . . . . 29
6.1. Encoding of the OSCORE Option Value . . . . . . . . . . . 30 6.1. Encoding of the OSCORE Option Value . . . . . . . . . . . 30
6.2. Encoding of the OSCORE Payload . . . . . . . . . . . . . 31 6.2. Encoding of the OSCORE Payload . . . . . . . . . . . . . 31
6.3. Examples of Compressed COSE Objects . . . . . . . . . . . 31 6.3. Examples of Compressed COSE Objects . . . . . . . . . . . 31
7. Message Binding, Sequence Numbers, Freshness and Replay 7. Message Binding, Sequence Numbers, Freshness, and Replay
Protection . . . . . . . . . . . . . . . . . . . . . . . . . 34 Protection . . . . . . . . . . . . . . . . . . . . . . . . . 34
7.1. Message Binding . . . . . . . . . . . . . . . . . . . . . 34 7.1. Message Binding . . . . . . . . . . . . . . . . . . . . . 34
7.2. Sequence Numbers . . . . . . . . . . . . . . . . . . . . 34 7.2. Sequence Numbers . . . . . . . . . . . . . . . . . . . . 34
7.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 34 7.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 34
7.4. Replay Protection . . . . . . . . . . . . . . . . . . . . 35 7.4. Replay Protection . . . . . . . . . . . . . . . . . . . . 35
7.5. Losing Part of the Context State . . . . . . . . . . . . 36 7.5. Losing Part of the Context State . . . . . . . . . . . . 36
8. Processing . . . . . . . . . . . . . . . . . . . . . . . . . 37 8. Processing . . . . . . . . . . . . . . . . . . . . . . . . . 37
8.1. Protecting the Request . . . . . . . . . . . . . . . . . 37 8.1. Protecting the Request . . . . . . . . . . . . . . . . . 37
8.2. Verifying the Request . . . . . . . . . . . . . . . . . . 38 8.2. Verifying the Request . . . . . . . . . . . . . . . . . . 37
8.3. Protecting the Response . . . . . . . . . . . . . . . . . 39 8.3. Protecting the Response . . . . . . . . . . . . . . . . . 39
8.4. Verifying the Response . . . . . . . . . . . . . . . . . 40 8.4. Verifying the Response . . . . . . . . . . . . . . . . . 40
9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 42 9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 42
10. CoAP-to-CoAP Forwarding Proxy . . . . . . . . . . . . . . . . 43 10. CoAP-to-CoAP Forwarding Proxy . . . . . . . . . . . . . . . . 42
11. HTTP Operations . . . . . . . . . . . . . . . . . . . . . . . 44 11. HTTP Operations . . . . . . . . . . . . . . . . . . . . . . . 43
11.1. The HTTP OSCORE Header Field . . . . . . . . . . . . . . 44 11.1. The HTTP OSCORE Header Field . . . . . . . . . . . . . . 43
11.2. CoAP-to-HTTP Mapping . . . . . . . . . . . . . . . . . . 45 11.2. CoAP-to-HTTP Mapping . . . . . . . . . . . . . . . . . . 44
11.3. HTTP-to-CoAP Mapping . . . . . . . . . . . . . . . . . . 45 11.3. HTTP-to-CoAP Mapping . . . . . . . . . . . . . . . . . . 45
11.4. HTTP Endpoints . . . . . . . . . . . . . . . . . . . . . 46 11.4. HTTP Endpoints . . . . . . . . . . . . . . . . . . . . . 45
11.5. Example: HTTP Client and CoAP Server . . . . . . . . . . 46 11.5. Example: HTTP Client and CoAP Server . . . . . . . . . . 46
11.6. Example: CoAP Client and HTTP Server . . . . . . . . . . 48 11.6. Example: CoAP Client and HTTP Server . . . . . . . . . . 47
12. Security Considerations . . . . . . . . . . . . . . . . . . . 49 12. Security Considerations . . . . . . . . . . . . . . . . . . . 48
12.1. End-to-end Protection . . . . . . . . . . . . . . . . . 49 12.1. End-to-end Protection . . . . . . . . . . . . . . . . . 48
12.2. Security Context Establishment . . . . . . . . . . . . . 50 12.2. Security Context Establishment . . . . . . . . . . . . . 49
12.3. Master Secret . . . . . . . . . . . . . . . . . . . . . 50 12.3. Master Secret . . . . . . . . . . . . . . . . . . . . . 49
12.4. Replay Protection . . . . . . . . . . . . . . . . . . . 50 12.4. Replay Protection . . . . . . . . . . . . . . . . . . . 50
12.5. Client Aliveness . . . . . . . . . . . . . . . . . . . . 51 12.5. Client Aliveness . . . . . . . . . . . . . . . . . . . . 50
12.6. Cryptographic Considerations . . . . . . . . . . . . . . 51 12.6. Cryptographic Considerations . . . . . . . . . . . . . . 50
12.7. Message Segmentation . . . . . . . . . . . . . . . . . . 51 12.7. Message Segmentation . . . . . . . . . . . . . . . . . . 51
12.8. Privacy Considerations . . . . . . . . . . . . . . . . . 52 12.8. Privacy Considerations . . . . . . . . . . . . . . . . . 51
13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 53 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 52
13.1. COSE Header Parameters Registry . . . . . . . . . . . . 53 13.1. COSE Header Parameters Registry . . . . . . . . . . . . 52
13.2. CoAP Option Numbers Registry . . . . . . . . . . . . . . 53 13.2. CoAP Option Numbers Registry . . . . . . . . . . . . . . 53
13.3. CoAP Signaling Option Numbers Registry . . . . . . . . . 54 13.3. CoAP Signaling Option Numbers Registry . . . . . . . . . 54
13.4. Header Field Registrations . . . . . . . . . . . . . . . 55 13.4. Header Field Registrations . . . . . . . . . . . . . . . 54
13.5. Media Type Registrations . . . . . . . . . . . . . . . . 55 13.5. Media Type Registrations . . . . . . . . . . . . . . . . 54
13.6. CoAP Content-Formats Registry . . . . . . . . . . . . . 57 13.6. CoAP Content-Formats Registry . . . . . . . . . . . . . 56
13.7. OSCORE Flag Bits Registry . . . . . . . . . . . . . . . 57 13.7. OSCORE Flag Bits Registry . . . . . . . . . . . . . . . 56
13.8. Expert Review Instructions . . . . . . . . . . . . . . . 58 13.8. Expert Review Instructions . . . . . . . . . . . . . . . 57
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 59 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 58
14.1. Normative References . . . . . . . . . . . . . . . . . . 59 14.1. Normative References . . . . . . . . . . . . . . . . . . 58
14.2. Informative References . . . . . . . . . . . . . . . . . 60 14.2. Informative References . . . . . . . . . . . . . . . . . 59
Appendix A. Scenario Examples . . . . . . . . . . . . . . . . . 62 Appendix A. Scenario Examples . . . . . . . . . . . . . . . . . 62
A.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 63 A.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 62
A.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 64 A.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 63
Appendix B. Deployment Examples . . . . . . . . . . . . . . . . 65 Appendix B. Deployment Examples . . . . . . . . . . . . . . . . 64
B.1. Master Secret Used Once . . . . . . . . . . . . . . . . . 65 B.1. Security Context Derived Once . . . . . . . . . . . . . . 64
B.2. Master Secret Used Multiple Times . . . . . . . . . . . . 65 B.2. Security Context Derived Multiple Times . . . . . . . . . 66
Appendix C. Test Vectors . . . . . . . . . . . . . . . . . . . . 66 Appendix C. Test Vectors . . . . . . . . . . . . . . . . . . . . 71
C.1. Test Vector 1: Key Derivation with Master Salt . . . . . 67 C.1. Test Vector 1: Key Derivation with Master Salt . . . . . 72
C.2. Test Vector 2: Key Derivation without Master Salt . . . . 68 C.2. Test Vector 2: Key Derivation without Master Salt . . . . 73
C.3. Test Vector 3: Key Derivation with ID Context . . . . . . 70 C.3. Test Vector 3: Key Derivation with ID Context . . . . . . 75
C.4. Test Vector 4: OSCORE Request, Client . . . . . . . . . . 71 C.4. Test Vector 4: OSCORE Request, Client . . . . . . . . . . 76
C.5. Test Vector 5: OSCORE Request, Client . . . . . . . . . . 73 C.5. Test Vector 5: OSCORE Request, Client . . . . . . . . . . 77
C.6. Test Vector 6: OSCORE Request, Client . . . . . . . . . . 74 C.6. Test Vector 6: OSCORE Request, Client . . . . . . . . . . 79
C.7. Test Vector 7: OSCORE Response, Server . . . . . . . . . 75 C.7. Test Vector 7: OSCORE Response, Server . . . . . . . . . 80
C.8. Test Vector 8: OSCORE Response with Partial IV, Server . 76 C.8. Test Vector 8: OSCORE Response with Partial IV, Server . 81
Appendix D. Overview of Security Properties . . . . . . . . . . 77 Appendix D. Overview of Security Properties . . . . . . . . . . 82
D.1. Supporting Proxy Operations . . . . . . . . . . . . . . . 77 D.1. Threat Model . . . . . . . . . . . . . . . . . . . . . . 82
D.2. Protected Message Fields . . . . . . . . . . . . . . . . 78 D.2. Supporting Proxy Operations . . . . . . . . . . . . . . . 83
D.3. Uniqueness of (key, nonce) . . . . . . . . . . . . . . . 79 D.3. Protected Message Fields . . . . . . . . . . . . . . . . 84
D.4. Unprotected Message Fields . . . . . . . . . . . . . . . 80 D.4. Uniqueness of (key, nonce) . . . . . . . . . . . . . . . 85
Appendix E. CDDL Summary . . . . . . . . . . . . . . . . . . . . 83 D.5. Unprotected Message Fields . . . . . . . . . . . . . . . 86
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 83 Appendix E. CDDL Summary . . . . . . . . . . . . . . . . . . . . 89
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 84 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 90
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 90
1. Introduction 1. Introduction
The Constrained Application Protocol (CoAP) [RFC7252] is a web The Constrained Application Protocol (CoAP) [RFC7252] is a web
transfer protocol, designed for constrained nodes and networks transfer 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-to-CoAP, HTTP-to-CoAP, and CoAP-to-HTTP [RFC6347] for security. CoAP-to-CoAP, HTTP-to-CoAP, and CoAP-to-HTTP
proxies require DTLS or TLS [RFC8446] to be terminated at the proxy. proxies require DTLS or TLS [RFC8446] to be terminated at the proxy.
The proxy therefore not only has access to the data required for The proxy therefore not only has access to the data required for
skipping to change at page 5, line 5 skipping to change at page 4, line 47
[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 protects neither the message payload, etc. (see Section 4). OSCORE protects neither the
CoAP Messaging Layer nor the CoAP Token which may change between the CoAP Messaging Layer nor the CoAP Token which may change between the
endpoints, and those are therefore processed as defined in [RFC7252]. endpoints, and those are therefore processed as defined in [RFC7252].
Additionally, since the message formats for CoAP over unreliable Additionally, since the message formats for CoAP over unreliable
transport [RFC7252] and for CoAP over reliable transport [RFC8323] transport [RFC7252] and for CoAP over reliable transport [RFC8323]
differ only in terms of CoAP Messaging Layer, OSCORE can be applied differ only in terms of CoAP Messaging Layer, OSCORE can be applied
to both unreliable and reliable transports (see Figure 1). to both unreliable and reliable transports (see Figure 1).
OSCORE works in very constrained nodes and networks, thanks to its
small message size and the restricted code and memory requirements in
addition to what is required by CoAP. Examples of the use of OSCORE
are given in Appendix A. OSCORE may be used over any underlying
layer, such as e.g. UDP or TCP, and with non-IP transports (e.g.,
[I-D.bormann-6lo-coap-802-15-ie]). OSCORE may also be used in
different ways with HTTP. OSCORE messages may be transported in
HTTP, and OSCORE may also be used to protect CoAP-mappable HTTP
messages, as described below.
+-----------------------------------+ +-----------------------------------+
| Application | | Application |
+-----------------------------------+ +-----------------------------------+
+-----------------------------------+ \ +-----------------------------------+ \
| Requests / Responses / Signaling | | | Requests / Responses / Signaling | |
|-----------------------------------| | |-----------------------------------| |
| OSCORE | | CoAP | OSCORE | | CoAP
|-----------------------------------| | |-----------------------------------| |
| Messaging Layer / Message Framing | | | Messaging Layer / Message Framing | |
+-----------------------------------+ / +-----------------------------------+ /
+-----------------------------------+ +-----------------------------------+
| UDP / TCP / ... | | UDP / TCP / ... |
+-----------------------------------+ +-----------------------------------+
Figure 1: Abstract Layering of CoAP with OSCORE Figure 1: Abstract Layering of CoAP with OSCORE
OSCORE works in very constrained nodes and networks, thanks to its
small message size and the restricted code and memory requirements in
addition to what is required by CoAP. Examples of the use of OSCORE
are given in Appendix A. OSCORE may be used over any underlying
layer, such as e.g. UDP or TCP, and with non-IP transports (e.g.,
[I-D.bormann-6lo-coap-802-15-ie]). OSCORE may also be used in
different ways with HTTP. OSCORE messages may be transported in
HTTP, and OSCORE may also be used to protect CoAP-mappable HTTP
messages, as described below.
OSCORE is designed to protect as much information as possible while OSCORE is designed to protect as much information as possible while
still allowing CoAP proxy operations (Section 10). It works with still allowing CoAP proxy operations (Section 10). It works with
existing CoAP-to-CoAP forward proxies [RFC7252], but an OSCORE-aware existing CoAP-to-CoAP forward proxies [RFC7252], but an OSCORE-aware
proxy will be more efficient. HTTP-to-CoAP proxies [RFC8075] and proxy will be more efficient. HTTP-to-CoAP proxies [RFC8075] and
CoAP-to-HTTP proxies can also be used with OSCORE, as specified in CoAP-to-HTTP proxies can also be used with OSCORE, as specified in
Section 11. OSCORE may be used together with TLS or DTLS over one or Section 11. OSCORE may be used together with TLS or DTLS over one or
more hops in the end-to-end path, e.g. transported with HTTPS in one more hops in the end-to-end path, e.g. transported with HTTPS in one
hop and with plain CoAP in another hop. The use of OSCORE does not hop and with plain CoAP in another hop. The use of OSCORE does not
affect the URI scheme and OSCORE can therefore be used with any URI affect the URI scheme and OSCORE can therefore be used with any URI
scheme defined for CoAP or HTTP. The application decides the scheme defined for CoAP or HTTP. The application decides the
skipping to change at page 7, line 6 skipping to change at page 6, line 49
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 E, 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, ID Context, and Common IV are defined in ID/Key, Recipient ID/Key, ID Context, and Common IV are defined in
Section 3.1. Section 3.1.
2. The OSCORE Option 2. The OSCORE Option
The OSCORE option defined in this section (see Figure 3, which The OSCORE option defined in this section (see Figure 3, which
extends Table 4: Options of [RFC7252]) indicates that the CoAP extends Table 4: Options of [RFC7252]) indicates that the CoAP
skipping to change at page 9, line 5 skipping to change at page 8, line 27
An endpoint uses its Sender ID (SID) to derive its Sender Context, An endpoint uses its Sender ID (SID) to derive its Sender Context,
and the other endpoint uses the same ID, now called Recipient ID and the other endpoint uses the same ID, now called Recipient ID
(RID), to derive its Recipient Context. In communication between two (RID), to derive its Recipient Context. In communication between two
endpoints, the Sender Context of one endpoint matches the Recipient endpoints, the Sender Context of one endpoint matches the Recipient
Context of the other endpoint, and vice versa. Thus, the two Context of the other endpoint, and vice versa. Thus, the two
security contexts identified by the same IDs in the two endpoints are security contexts identified by the same IDs in the two endpoints are
not the same, but they are partly mirrored. Retrieval and use of the not the same, but they are partly mirrored. Retrieval and use of the
security context are shown in Figure 4. security context are shown in Figure 4.
.------------------------------------------------. .-----------------------------------------------.
| Common Context | | Common Context |
+---------------------.----.---------------------+ +---------------------.---.---------------------+
| Sender Context | = | Recipient Context | | Sender Context | = | Recipient Context |
+---------------------+ +---------------------+ +---------------------+ +---------------------+
| Recipient Context | = | Sender Context | | Recipient Context | = | Sender Context |
'---------------------' '---------------------' '---------------------' '---------------------'
Client Server Client Server
| | | |
Retrieve context for | OSCORE request: | Retrieve context for | OSCORE request: |
target resource | Token = Token1, | target resource | Token = Token1, |
Protect request with | kid = SID, ... | Protect request with | kid = SID, ... |
Sender Context +---------------------->| Retrieve context with Sender Context +---------------------->| Retrieve context with
| | RID = kid | | RID = kid
| | Verify request with | | Verify request with
| | Recipient Context | | Recipient Context
| OSCORE response: | Protect response with | OSCORE response: | Protect response with
skipping to change at page 9, line 34 skipping to change at page 9, line 7
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.
o An HMAC-based key derivation function HKDF [RFC5869] used to o HKDF Algorithm. An HMAC-based key derivation function HKDF
derive Sender Key, Recipient Key, and Common IV. [RFC5869] used to derive Sender Key, Recipient Key, and Common IV.
o Master Secret. Variable length, random byte string (see o Master Secret. Variable length, random byte string (see
Section 12.3) used to derive AEAD keys and Common IV. Section 12.3) used to derive AEAD keys and Common IV.
o Master Salt. Optional variable length byte string containing the o Master Salt. Optional variable length byte string containing the
salt used to derive AEAD keys and Common IV. salt used to derive AEAD keys and Common IV.
o ID Context. Optional variable length byte string providing o ID Context. Optional variable length byte string providing
additional information to identify the Common Context and to additional information to identify the Common Context and to
derive AEAD keys and Common IV. The use of ID Context is derive AEAD keys and Common IV. The use of ID Context is
skipping to change at page 11, line 23 skipping to change at page 10, line 48
indicated below is used: indicated below is used:
o AEAD Algorithm o AEAD Algorithm
* Default is AES-CCM-16-64-128 (COSE algorithm encoding: 10) * Default is AES-CCM-16-64-128 (COSE algorithm encoding: 10)
o Master Salt o Master Salt
* Default is the empty byte string * Default is the empty byte string
o HMAC-based Key Derivation Function (HKDF) o HKDF Algorithm
* Default is HKDF SHA-256 * Default is HKDF SHA-256
o Replay Window o Replay Window
* Default is DTLS-type replay protection with a window size of 32 * Default is DTLS-type replay protection with a window size of 32
[RFC6347] [RFC6347]
All input parameters need to be known to and agreed on by both All input parameters need to be known to and agreed on by both
endpoints, but the replay window may be different in the two endpoints, but the replay window may be different in the two
endpoints. The way the input parameters are pre-established, is endpoints. The way the input parameters are pre-established, is
application specific. Considerations of security context application specific. Considerations of security context
establishment are given in Section 12.2 and examples of deploying establishment are given in Section 12.2 and examples of deploying
OSCORE in Appendix B. OSCORE in Appendix B.
skipping to change at page 12, line 4 skipping to change at page 11, line 28
The security context parameters Sender Key, Recipient Key, and Common The security context parameters Sender Key, Recipient Key, and Common
IV SHALL be derived from the input parameters using the HKDF, which IV SHALL be derived from the input parameters using the HKDF, which
consists of the composition of the HKDF-Extract and HKDF-Expand steps consists of the composition of the HKDF-Extract and HKDF-Expand steps
[RFC5869]: [RFC5869]:
output parameter = HKDF(salt, IKM, info, L) output parameter = HKDF(salt, IKM, info, L)
where: where:
o salt is the Master Salt as defined above o salt is the Master Salt as defined above
o IKM is the Master Secret as defined above o IKM is the Master Secret as defined above
o info is the serialization of a CBOR array consisting of (the o info is the serialization of a CBOR array consisting of (the
notation follows Appendix E): notation follows Appendix E):
info = [ info = [
id : bstr, id : bstr,
id_context : bstr / nil, id_context : bstr / nil,
alg_aead : int / tstr, alg_aead : int / tstr,
type : tstr, type : tstr,
L : uint L : uint,
] ]
where: where:
o id is the Sender ID or Recipient ID when deriving Sender Key and o id is the Sender ID or Recipient ID when deriving Sender Key and
Recipient Key, respectively, and the empty byte string when Recipient Key, respectively, and the empty byte string when
deriving the Common IV. deriving the Common IV.
o id_context is the ID Context, or nil if ID Context is not o id_context is the ID Context, or nil if ID Context is not
provided. provided.
skipping to change at page 12, line 40 skipping to change at page 12, line 17
o L is the size of the key/nonce for the AEAD algorithm used, in o L is the size of the key/nonce for the AEAD algorithm used, in
bytes. bytes.
For example, if the algorithm AES-CCM-16-64-128 (see Section 10.2 in For example, if the algorithm AES-CCM-16-64-128 (see Section 10.2 in
[RFC8152]) is used, the integer value for alg_aead is 10, the value [RFC8152]) is used, the integer value for alg_aead is 10, the value
for L is 16 for keys and 13 for the Common IV. Assuming use of the for L is 16 for keys and 13 for the Common IV. Assuming use of the
default algorithms HKDF SHA-256 and AES-CCM-16-64-128, the extract default algorithms HKDF SHA-256 and AES-CCM-16-64-128, the extract
phase of HKDF produces a pseudorandom key (PRK) as follows: phase of HKDF produces a pseudorandom key (PRK) as follows:
PRK = HMAC-SHA-256(Master Salt, Master Secret) PRK = HMAC-SHA-256(Master Salt, Master Secret)
and as L is smaller than the hash function output size, the expand and as L is smaller than the hash function output size, the expand
phase of HKDF consists of a single HMAC invocation, and the Sender phase of HKDF consists of a single HMAC invocation, and the Sender
Key, Recipient Key, and Common IV are therefore the first 16 or 13 Key, Recipient Key, and Common IV are therefore the first 16 or 13
bytes of bytes of
output parameter = HMAC-SHA-256(PRK, info | 0x01) output parameter = HMAC-SHA-256(PRK, info || 0x01)
where different info are used for each derived parameter and where | where different info are used for each derived parameter and where ||
denotes byte string concatenation. denotes byte string concatenation.
Note that [RFC5869] specifies that if the salt is not provided, it is Note that [RFC5869] specifies that if the salt is not provided, it is
set to a string of zeros. For implementation purposes, not providing set to a string of zeros. For implementation purposes, not providing
the salt is the same as setting the salt to the empty byte string. the salt is the same as setting the salt to the empty byte string.
OSCORE sets the salt default value to empty byte string, which is OSCORE sets the salt default value to empty byte string, which is
converted to a string of zeroes (see Section 2.2 of [RFC5869]). converted to a string of zeroes (see Section 2.2 of [RFC5869]).
3.2.2. Initial Sequence Numbers and Replay Window 3.2.2. Initial Sequence Numbers and Replay Window
The Sender Sequence Number is initialized to 0. The supported types The Sender Sequence Number is initialized to 0.
of replay protection and replay window length is application specific
and depends on how OSCORE is transported, see Section 7.4. The The supported types of replay protection and replay window length is
default is DTLS-type replay protection with a window size of 32 application specific and depends on how OSCORE is transported, see
initiated as described in Section 4.1.2.6 of [RFC6347]. Section 7.4. The default is DTLS-type replay protection with a
window size of 32 initiated as described in Section 4.1.2.6 of
[RFC6347].
3.3. Requirements on the Security Context Parameters 3.3. Requirements on the Security Context Parameters
To ensure unique Sender Keys, the quartet (Master Secret, Master To ensure unique Sender Keys, the quartet (Master Secret, Master
Salt, ID Context, Sender ID) MUST be unique, i.e. the pair (ID Salt, ID Context, Sender ID) MUST be unique, i.e. the pair (ID
Context, Sender ID) SHALL be unique in the set of all security Context, Sender ID) SHALL be unique in the set of all security
contexts using the same Master Secret and Master Salt. This means contexts using the same Master Secret and Master Salt. This means
that Sender ID SHALL be unique in the set of all security contexts that Sender ID SHALL be unique in the set of all security contexts
using the same Master Secret, Master Salt, and ID Context; such a using the same Master Secret, Master Salt, and ID Context; such a
requirement guarantees unique (key, nonce) pairs for the AEAD. requirement guarantees unique (key, nonce) pairs for the AEAD.
skipping to change at page 13, line 48 skipping to change at page 13, line 26
To simplify retrieval of the right Recipient Context, the Recipient To simplify retrieval of the right Recipient Context, the Recipient
ID SHOULD be unique in the sets of all Recipient Contexts used by an ID SHOULD be unique in the sets of all Recipient Contexts used by an
endpoint. If an endpoint has the same Recipient ID with different endpoint. If an endpoint has the same Recipient ID with different
Recipient Contexts, i.e. the Recipient Contexts are derived from Recipient Contexts, i.e. the Recipient Contexts are derived from
different Common Contexts, then the endpoint may need to try multiple different Common Contexts, then the endpoint may need to try multiple
times before verifying the right security context associated to the times before verifying the right security context associated to the
Recipient ID. Recipient ID.
The ID Context is used to distinguish between security contexts. The The ID Context is used to distinguish between security contexts. The
methods used for assigning Sender ID can also be used for assigning methods used for assigning Sender ID can also be used for assigning
the ID Context. Additionally, the ID Context can be generated by the the ID Context. Additionally, the ID Context can be used to
client (see Appendix B.2). ID Context can be arbitrarily long. introduce randomness into new Sender and Recipient Contexts (see
Appendix B.2). ID Context can be arbitrarily long.
4. Protected Message Fields 4. Protected Message Fields
OSCORE transforms a CoAP message (which may have been generated from OSCORE transforms a CoAP message (which may have been generated from
an HTTP message) into an OSCORE message, and vice versa. OSCORE an HTTP message) into an OSCORE message, and vice versa. OSCORE
protects as much of the original message as possible while still protects as much of the original message as possible while still
allowing certain proxy operations (see Sections 10 and 11). This allowing certain proxy operations (see Sections 10 and 11). This
section defines how OSCORE protects the message fields and transfers section defines how OSCORE protects the message fields and transfers
them end-to-end between client and server (in any direction). them end-to-end between client and server (in any direction).
skipping to change at page 15, line 17 skipping to change at page 14, line 41
the receiving endpoint, whereas Outer message fields are used to the receiving endpoint, whereas Outer message fields are used to
enable proxy operations. enable proxy operations.
4.1. CoAP Options 4.1. CoAP Options
A summary of how options are protected is shown in Figure 5. Note A summary of how options are protected is shown in Figure 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. Certain options require special are protected accordingly. Certain options require special
processing as is described in Section 4.1.3. processing as is described in Section 4.1.3.
Options that are unknown or for which OSCORE processing is not
defined SHALL be processed as class E (and no special processing).
Specifications of new CoAP options SHOULD define how they are
processed with OSCORE. A new COAP option SHOULD be of class E unless
it requires proxy processing. If a new CoAP option is of class U,
the potential issues with the option being unprotected SHOULD be
documented (see Appendix D.5).
4.1.1. Inner Options
Inner option message fields (class E) are used to communicate
directly with the other endpoint.
The sending endpoint SHALL write the Inner option message fields
present in the original CoAP message into the plaintext of the COSE
object (Section 5.3), and then remove the Inner option message fields
from the OSCORE message.
The processing of Inner option message fields by the receiving
endpoint is specified in Sections 8.2 and 8.4.
+------+-----------------+---+---+ +------+-----------------+---+---+
| 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 | x | x | | 6 | Observe | x | x |
| 7 | Uri-Port | | x | | 7 | Uri-Port | | x |
| 8 | Location-Path | x | | | 8 | Location-Path | x | |
skipping to change at page 15, line 48 skipping to change at page 16, line 5
| 39 | Proxy-Scheme | | x | | 39 | Proxy-Scheme | | x |
| 60 | Size1 | x | x | | 60 | Size1 | x | x |
| 258 | No-Response | x | x | | 258 | No-Response | x | x |
+------+-----------------+---+---+ +------+-----------------+---+---+
E = Encrypt and Integrity Protect (Inner) E = Encrypt and Integrity Protect (Inner)
U = Unprotected (Outer) U = Unprotected (Outer)
Figure 5: Protection of CoAP Options Figure 5: Protection of CoAP Options
Options that are unknown or for which OSCORE processing is not
defined SHALL be processed as class E (and no special processing).
Specifications of new CoAP options SHOULD define how they are
processed with OSCORE. A new COAP option SHOULD be of class E unless
it requires proxy processing. If a new CoAP option is of class U,
the potential issues with the option being unprotected SHOULD be
documented (see Appendix D.4).
4.1.1. Inner Options
Inner option message fields (class E) are used to communicate
directly with the other endpoint.
The sending endpoint SHALL write the Inner option message fields
present in the original CoAP message into the plaintext of the COSE
object (Section 5.3), and then remove the Inner option message fields
from the OSCORE message.
The processing of Inner option message fields by the receiving
endpoint is specified in Sections 8.2 and 8.4.
4.1.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, see Appendix D.1. operations, see Appendix D.2.
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 the OSCORE message. All Outer option message fields, including the OSCORE
option, SHALL be encoded as described in Section 3.1 of [RFC7252], option, SHALL be encoded as described in Section 3.1 of [RFC7252],
where the delta is the difference to the previously included instance where the delta is the difference to the previously included instance
of Outer option message field. of Outer 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 Sections 8.2 and 8.4. specified in Sections 8.2 and 8.4.
skipping to change at page 17, line 16 skipping to change at page 16, line 49
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 error responses caused by OSCORE processing at OSCORE-unaware of error responses caused by OSCORE processing at OSCORE-unaware
intermediary nodes. A server MAY set a Class U Max-Age message field intermediary nodes. A server MAY set a Class U Max-Age message field
with value zero to such error responses, described in Sections 7.4, with value zero to such error responses, described in Sections 7.4,
8.2, and 8.4, since these error responses are cacheable, but 8.2, and 8.4, since these error responses are cacheable, but
subsequent OSCORE requests would never create a hit in the subsequent OSCORE requests would never create a hit in the
intermediary caching it. Setting the Outer Max-Age to zero relieves intermediary caching it. Setting the Outer Max-Age to zero relieves
the intermediary from uselessly caching responses. Successful OSCORE the intermediary from uselessly caching responses. Successful OSCORE
responses do not need to include an Outer Max-Age option since the responses do not need to include an Outer Max-Age option since the
responses appear to the OSCORE-unaware intermediary as 2.04 Changed responses appear to the OSCORE-unaware intermediary as 2.04 (Changed)
responses, which are non-cacheable (see Section 4.2). responses, which are non-cacheable (see Section 4.2).
The Outer Max-Age message field is processed according to The Outer Max-Age message field is processed according to
Section 4.1.2. Section 4.1.2.
4.1.3.2. Uri-Host and Uri-Port 4.1.3.2. Uri-Host and Uri-Port
When the Uri-Host and Uri-Port are set to their default values (see When the Uri-Host and Uri-Port are set to their default values (see
Section 5.10.1 [RFC7252]), they are omitted from the message Section 5.10.1 [RFC7252]), they are omitted from the message
(Section 5.4.4 of [RFC7252]), which is favorable both for overhead (Section 5.4.4 of [RFC7252]), which is favorable both for overhead
and privacy. and privacy.
In order to support forward proxy operations, Proxy-Scheme, Uri-Host, In order to support forward proxy operations, Proxy-Scheme, Uri-Host,
and Uri-Port need to be Class U. For the use of Proxy-Uri, see and Uri-Port need to be Class U. For the use of Proxy-Uri, see
Section 4.1.3.3. Section 4.1.3.3.
Manipulation of unprotected message fields (including Uri-Host, Uri- Manipulation of unprotected message fields (including Uri-Host, Uri-
Port, destination IP/port or request scheme) MUST NOT lead to an Port, destination IP/port or request scheme) MUST NOT lead to an
OSCORE message becoming verified by an unintended server. Different OSCORE message becoming verified by an unintended server. Different
servers SHOULD have different security contexts. servers SHALL have different security contexts.
4.1.3.3. Proxy-Uri 4.1.3.3. Proxy-Uri
When Proxy-Uri is present, the client SHALL first decompose the When Proxy-Uri is present, the client SHALL first decompose the
Proxy-Uri value of the original CoAP message into the Proxy-Scheme, Proxy-Uri value of the original CoAP message into the Proxy-Scheme,
Uri-Host, Uri-Port, Uri-Path, and Uri-Query options according to Uri-Host, Uri-Port, Uri-Path, and Uri-Query options according to
Section 6.4 of [RFC7252]. Section 6.4 of [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.1.1). processed as Inner options (Section 4.1.1).
skipping to change at page 22, line 35 skipping to change at page 22, line 19
No-Response [RFC7967] is an optional feature used by the client to No-Response [RFC7967] is an optional feature used by the client to
communicate its disinterest in certain classes of responses to a communicate its disinterest in certain classes of responses to a
particular request. An implementation MAY support [RFC7252] and the particular request. An implementation MAY support [RFC7252] and the
OSCORE option without supporting [RFC7967]. OSCORE option without supporting [RFC7967].
If used, No-Response MUST be Inner. The Inner No-Response SHALL be If used, No-Response MUST be Inner. The Inner No-Response SHALL be
processed by OSCORE as specified in Section 4.1.1. The Outer option processed by OSCORE as specified in Section 4.1.1. The Outer option
SHOULD NOT be present. The server SHALL ignore the Outer No-Response SHOULD NOT be present. The server SHALL ignore the Outer No-Response
option. The client MAY set the Outer No-Response value to 26 option. The client MAY set the Outer No-Response value to 26
('suppress all known codes') if the Inner value is set to 26. The ('suppress all known codes') if the Inner value is set to 26. The
client MUST be prepared to receive and discard 5.04 Gateway Timeout client MUST be prepared to receive and discard 5.04 (Gateway Timeout)
error messages from intermediaries potentially resulting from error messages from intermediaries potentially resulting from
destination time out due to no response. destination time out due to no response.
4.1.3.7. OSCORE 4.1.3.7. OSCORE
The OSCORE option is only defined to be present in OSCORE messages, The OSCORE option is only defined to be present in OSCORE messages,
as an indication that OSCORE processing have been performed. The as an indication that OSCORE processing have been performed. The
content in the OSCORE option is neither encrypted nor integrity content in the OSCORE option is neither encrypted nor integrity
protected as a whole but some part of the content of this option is protected as a whole but some part of the content of this option is
protected (see Section 5.4). Nested use of OSCORE is not supported: protected (see Section 5.4). Nested use of OSCORE is not supported:
If OSCORE processing detects an OSCORE option in the original CoAP If OSCORE processing detects an OSCORE option in the original CoAP
message, then processing SHALL be stopped. message, then processing SHALL be stopped.
4.2. CoAP Header Fields and Payload
A summary of how the CoAP header fields and payload are protected is
shown in Figure 6, including fields specific to CoAP over UDP and
CoAP over TCP (marked accordingly in the table).
+------------------+---+---+ +------------------+---+---+
| Field | E | U | | 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 | | | Payload | x | |
+------------------+---+---+ +------------------+---+---+
E = Encrypt and Integrity Protect (Inner) E = Encrypt and Integrity Protect (Inner)
U = Unprotected (Outer) U = Unprotected (Outer)
Figure 6: Protection of CoAP Header Fields and Payload Figure 6: Protection of CoAP Header Fields and Payload
4.2. CoAP Header Fields and Payload
A summary of how the CoAP header fields and payload are protected is
shown in Figure 6, including fields specific to CoAP over UDP and
CoAP over TCP (marked accordingly in the table).
Most CoAP Header fields (i.e. the message fields in the fixed 4-byte Most CoAP Header fields (i.e. the message fields in the fixed 4-byte
header) are required to be read and/or changed by CoAP proxies and header) are required to be read and/or changed by CoAP proxies and
thus cannot in general be protected end-to-end between the endpoints. thus cannot in general be protected end-to-end between the endpoints.
As mentioned in Section 1, OSCORE protects the CoAP Request/Response As mentioned in Section 1, OSCORE protects the CoAP Request/Response
layer only, and not the Messaging Layer (Section 2 of [RFC7252]), so Layer only, and not the Messaging Layer (Section 2 of [RFC7252]), so
fields such as Type and Message ID are not protected with OSCORE. fields such as Type and Message ID are not protected with OSCORE.
The CoAP Header field Code is protected by OSCORE. Code SHALL be The CoAP Header field Code is protected by OSCORE. Code SHALL be
encrypted and integrity protected (Class E) to prevent an encrypted and integrity protected (Class E) to prevent an
intermediary from eavesdropping on or manipulating the Code (e.g., intermediary from eavesdropping on or manipulating the Code (e.g.,
changing from GET to DELETE). changing from GET to DELETE).
The sending endpoint SHALL write the Code of the original CoAP The sending endpoint SHALL write the Code of the original CoAP
message into the plaintext of the COSE object (see Section 5.3). message into the plaintext of the COSE object (see Section 5.3).
After that, the sending endpoint writes an Outer Code to the OSCORE After that, the sending endpoint writes an Outer Code to the OSCORE
skipping to change at page 25, line 31 skipping to change at page 25, line 14
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 bytes of value zero SHALL be Sequence Number. All leading bytes of value zero SHALL be
removed when encoding the Partial IV, except in the case of removed when encoding the Partial IV, except in the case of
Partial IV of value 0 which is encoded to the byte string 0x00. Partial IV of value 0 which is encoded to the byte string 0x00.
This parameter SHALL be present in requests. The Partial IV This parameter SHALL be present in requests. The Partial IV
SHALL be present in responses to Observe registrations (see SHALL be present in responses to Observe registrations (see
Section 4.1.3.5.1), otherwise the Partial IV will not typically Section 4.1.3.5.1), otherwise the Partial IV will not typically
be present in responses. be present in responses (for one exception, see
Appendix B.1.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 will not typically parameter SHALL be present in requests and will not typically
be 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.ietf-core-oscore-groupcomm]. communication [I-D.ietf-core-oscore-groupcomm].
* Optionally, a 'kid context' parameter (see Section 5.1) * Optionally, a 'kid context' parameter (see Section 5.1). This
containing an ID Context (see Section 3.1). This parameter MAY parameter MAY be present in requests, and if so, MUST contain
be present in requests and MUST NOT be present in responses. an ID Context (see Section 3.1). This parameter SHOULD NOT be
If 'kid context' is present in the request, then the server present in responses: an example of how 'kid context' can be
SHALL use a security context with that ID Context when used in responses is given in Appendix B.2. If 'kid context'
verifying the request. is present in the request, then the server SHALL use a security
context with that ID Context when verifying the request.
o The 'ciphertext' field is computed from the secret key (Sender Key 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].
The encryption process is described in Section 5.3 of [RFC8152]. The encryption process is described in Section 5.3 of [RFC8152].
5.1. Kid Context 5.1. ID Context and 'kid context'
For certain use cases, e.g. deployments where the same Sender ID is For certain use cases, e.g. deployments where the same Sender ID is
used with multiple contexts, it is possible (and sometimes necessary, used with multiple contexts, it is possible (and sometimes necessary,
see Section 3.3) for the client to use an ID Context to distinguish see Section 3.3) for the client to use an ID Context to distinguish
the security contexts (see Section 3.1). For example: the security contexts (see Section 3.1). For example:
o If the client has a unique identifier in some namespace, then that o If the client has a unique identifier in some namespace then that
identifier can be used as ID Context. identifier can be used as ID Context.
o The ID Context may be used to add randomness into new Sender and
Recipient Contexts, see Appendix B.2.
o In case of group communication [I-D.ietf-core-oscore-groupcomm], a o In case of group communication [I-D.ietf-core-oscore-groupcomm], a
group identifier can be used as ID Context to enable different group identifier is used as ID Context to enable different
security contexts for a server belonging to multiple groups. security contexts for a server belonging to multiple groups.
The Sender ID and Context ID are used to establish the necessary The Sender ID and ID Context are used to establish the necessary
input parameters and in the derivation of the security context (see input parameters and in the derivation of the security context (see
Section 3.2). Whereas the 'kid' parameter is used to transport the Section 3.2).
Sender ID, the new COSE header parameter 'kid context' is used to
transport the ID Context, see Figure 7. Whereas the 'kid' parameter is used to transport the Sender ID, the
new COSE header parameter 'kid context' is used to transport the ID
Context in requests, see Figure 7.
+----------+--------+------------+----------------+-----------------+ +----------+--------+------------+----------------+-----------------+
| name | label | value type | value registry | description | | name | label | value type | value registry | description |
+----------+--------+------------+----------------+-----------------+ +----------+--------+------------+----------------+-----------------+
| kid | TBD2 | bstr | | Identifies the | | kid | TBD2 | bstr | | Identifies the |
| context | | | | context for kid | | context | | | | context for kid |
+----------+--------+------------+----------------+-----------------+ +----------+--------+------------+----------------+-----------------+
Figure 7: Common Header Parameter kid context for the COSE object Figure 7: Common Header Parameter 'kid context' for the COSE object
If ID Context is non-empty and the client sends a request without
'kid context' which results in an error indicating that the server
could not find the security context, then the client could include
the ID Context in the 'kid context' when making another request.
Note that since the error is unprotected it may have been spoofed and
the real response blocked by an on-path attacker.
5.2. AEAD Nonce 5.2. AEAD Nonce
The high level design of the AEAD nonce follows Section 4.4 of The high level design of the AEAD nonce follows Section 4.4 of
[I-D.mcgrew-iv-gen], here follows the detailed construction (see [I-D.mcgrew-iv-gen], here follows the detailed construction (see
Figure 8): Figure 8):
1. left-pad the Partial IV (PIV) in network byte order with zeroes 1. left-pad the Partial IV (PIV) with zeroes to exactly 5 bytes,
to exactly 5 bytes,
2. left-pad the Sender ID of the endpoint that generated the Partial 2. left-pad the Sender ID of the endpoint that generated the Partial
IV (ID_PIV) in network byte order with zeroes to exactly nonce IV (ID_PIV) with zeroes to exactly nonce length minus 6 bytes,
length minus 6 bytes,
3. concatenate the size of the ID_PIV (a single byte S) with the 3. concatenate the size of the ID_PIV (a single byte S) with the
padded ID_PIV and the padded PIV, padded ID_PIV and the padded PIV,
4. and then XOR with the Common IV. 4. and then XOR with the Common IV.
Note that in this specification only AEAD algorithms that use nonces Note that in this specification only AEAD algorithms that use nonces
equal or greater than 7 bytes are supported. The nonce construction equal or greater than 7 bytes are supported. The nonce construction
with S, ID_PIV, and PIV together with endpoint unique IDs and with S, ID_PIV, and PIV together with endpoint unique IDs and
encryption keys makes it easy to verify that the nonces used with a encryption keys makes it easy to verify that the nonces used with a
specific key will be unique, see Appendix D.3. specific key will be unique, see Appendix D.4.
If the Partial IV is not present in a response, the nonce from the If the Partial IV is not present in a response, the nonce from the
request is used. For responses that are not notifications (i.e. when request is used. For responses that are not notifications (i.e. when
there is a single response to a request), the request and the there is a single response to a request), the request and the
response should typically use the same nonce to reduce message response should typically use the same nonce to reduce message
overhead. Both alternatives provide all the required security overhead. Both alternatives provide all the required security
properties, see Section 7.4 and Appendix D.3. The only non-Observe properties, see Section 7.4 and Appendix D.4. The only non-Observe
scenario where a Partial IV must be included in a response is when scenario where a Partial IV must be included in a response is when
the server is unable to perform replay protection, see Section 7.5.2. the server is unable to perform replay protection, see
For processing instructions see Section 8. Appendix B.1.2. For processing instructions see Section 8.
<- nonce length minus 6 B -> <-- 5 bytes --> <- nonce length minus 6 B -> <-- 5 bytes -->
+---+-------------------+--------+---------+-----+ +---+-------------------+--------+---------+-----+
| S | padding | ID_PIV | padding | PIV |----+ | S | padding | ID_PIV | padding | PIV |----+
+---+-------------------+--------+---------+-----+ | +---+-------------------+--------+---------+-----+ |
| |
<---------------- nonce length ----------------> | <---------------- nonce length ----------------> |
+------------------------------------------------+ | +------------------------------------------------+ |
| Common IV |->(XOR) | Common IV |->(XOR)
+------------------------------------------------+ | +------------------------------------------------+ |
skipping to change at page 28, line 6 skipping to change at page 27, line 49
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.1.1) present in the o all Inner option message fields (see Section 4.1.1) present in the
original CoAP message (see Section 4.1). The options are encoded 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 instance of Class E option; difference to the previously included instance of Class E option;
and 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).
NOTE: The plaintext contains all CoAP data that needs to be encrypted
end-to-end between the endpoints.
0 1 2 3 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Code | Class E options (if any) ... | Code | Class E options (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 1 1 1 1 1 1 1| Payload (if any) ... |1 1 1 1 1 1 1 1| Payload (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(only if there (only if there
is payload) is payload)
Figure 9: Plaintext Figure 9: Plaintext
NOTE: The plaintext contains all CoAP data that needs to be encrypted
end-to-end between the endpoints.
5.4. Additional Authenticated Data 5.4. Additional Authenticated Data
The external_aad SHALL be a CBOR array wrapped in a bstr object as The external_aad SHALL be a CBOR array wrapped in a bstr object as
defined below: defined below:
external_aad = bstr .cbor aad_array external_aad = bstr .cbor aad_array
aad_array = [ aad_array = [
oscore_version : uint, oscore_version : uint,
algorithms : [ alg_aead : int / tstr ], algorithms : [ alg_aead : int / tstr ],
request_kid : bstr, request_kid : bstr,
request_piv : bstr, request_piv : bstr,
options : bstr options : bstr,
] ]
where: where:
o oscore_version: contains the OSCORE version number. o oscore_version: contains the OSCORE version number.
Implementations of this specification MUST set this field to 1. Implementations of this specification MUST set this field to 1.
Other values are reserved for future versions. Other values are reserved for future versions.
o algorithms: contains (for extensibility) an array of algorithms, o algorithms: contains (for extensibility) an array of algorithms,
according to this specification only containing alg_aead. according to this specification only containing alg_aead.
skipping to change at page 29, line 24 skipping to change at page 29, line 21
band and are thus never transported in OSCORE, but the external_aad band and are thus never transported in OSCORE, but the external_aad
allows to verify that they are the same in both endpoints. allows to verify that they are the same in both endpoints.
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 all requests. need not be integrity protected in all requests.
The Additional Authenticated Data (AAD) is composed from the The Additional Authenticated Data (AAD) is composed from the
external_aad as described in Section 5.3 of [RFC8152]: external_aad as described in Section 5.3 of [RFC8152]:
AAD = Enc_structure = [ "Encrypt0", h'', external_aad ] AAD = Enc_structure = [ "Encrypt0", h'', external_aad ]
The following is an example of AAD constructed using AEAD Algorithm = The following is an example of AAD constructed using AEAD Algorithm =
AES-CCM-16-64-128 (10), request_kid = 0x00, request_piv = 0x25 and no AES-CCM-16-64-128 (10), request_kid = 0x00, request_piv = 0x25 and no
Class I options. Class I options:
oscore_version = 0x01 o oscore_version: 0x01 (1 byte)
algorithms = 0x810A
request_kid = 0x00
request_piv = 0x25
options = 0x
aad_array = 0x8501810A4100412540 o algorithms: 0x810a (2 bytes)
external_aad = 0x498501810A4100412540 o request_kid: 0x00 (1 byte)
AAD = 0x8368456E63727970743040498501810A4100412540 o request_piv: 0x25 (1 byte)
o options: 0x (0 bytes)
o aad_array: 0x8501810a4100412540 (9 bytes)
o external_aad: 0x498501810a4100412540 (10 bytes)
o AAD: 0x8368456e63727970743040498501810a4100412540 (21 bytes)
Note that the AAD consists of a fixed string of 11 bytes concatenated Note that the AAD consists of a fixed string of 11 bytes concatenated
with the external_aad. with the external_aad.
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
of signed and encrypted data. COSE is however constructed to support of signed and encrypted data. COSE is however constructed to support
skipping to change at page 30, line 18 skipping to change at page 30, line 19
object is called the "compressed COSE object". object is called the "compressed COSE object".
The COSE_Encrypt0 object used in OSCORE is transported in the OSCORE The COSE_Encrypt0 object used in OSCORE is transported in the OSCORE
option and in the Payload. The Payload contains the Ciphertext of option and in the Payload. The Payload contains the Ciphertext of
the COSE object. The headers of the COSE object are compactly the COSE object. The headers of the COSE object are compactly
encoded as described in the next section. encoded as described in the next section.
6.1. Encoding of the OSCORE Option Value 6.1. Encoding of the OSCORE Option Value
The value of the OSCORE option SHALL contain the OSCORE flag bits, The value of the OSCORE option SHALL contain the OSCORE flag bits,
the Partial IV parameter, the kid context parameter (length and the Partial IV parameter, the 'kid context' parameter (length and
value), and the kid parameter as follows: value), and the 'kid' parameter as follows:
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) ... |
+------------+----------------------+------------------+ +------------+----------------------+------------------+
skipping to change at page 30, line 41 skipping to change at page 30, line 42
Figure 10: The OSCORE Option Value Figure 10: The OSCORE Option Value
o The first byte, containing the OSCORE flag bits, encodes the o The first byte, containing the OSCORE flag bits, encodes the
following set of bits and the length of the Partial IV parameter: following set of bits and 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
to 1 if the kid is present in the compressed COSE object. set to 1 if the kid is present in the compressed COSE object.
* The fifth least significant bit is the kid context flag, h: it * The fifth least significant bit is the 'kid context' flag, h:
is set to 1 if the compressed COSE object contains a kid it is set to 1 if the compressed COSE object contains a 'kid
context (see Section 5.1). context (see Section 5.1).
* The sixth to eighth least significant bits are reserved for * The sixth to eighth least significant bits are reserved for
future use. These bits SHALL be set to zero when not in use. future use. These bits SHALL be set to zero when not in use.
According to this specification, if any of these bits are set According to this specification, if any of these bits are set
to 1 the message is considered to be malformed and to 1 the message is considered to be malformed and
decompression fails as specified in item 3 of Section 8.2. decompression fails as specified in item 2 of Section 8.2.
The flag bits are registered in the OSCORE Flag Bits registry The flag bits are registered in the OSCORE Flag Bits registry
specified in Section 13.7. specified in Section 13.7.
o The following n bytes encode the value of the Partial IV, if the o The following n bytes encode the value of the Partial IV, if the
Partial IV is present (n > 0). Partial IV is present (n > 0).
o The following 1 byte encode the length of the kid context o The following 1 byte encode the length of the 'kid context'
(Section 5.1) s, if the kid context flag is set (h = 1). (Section 5.1) s, if the 'kid context' flag is set (h = 1).
o The following s bytes encode the kid context, if the kid context o The following s bytes encode the 'kid context', if the 'kid
flag is set (h = 1). context' flag is set (h = 1).
o The remaining bytes encode the value of the kid, if the kid is o The remaining bytes encode the value of the 'kid', if the 'kid' is
present (k = 1). present (k = 1).
Note that the kid MUST be the last field of the OSCORE option value, Note that the 'kid' MUST be the last field of the OSCORE option
even in case reserved bits are used and additional fields are added value, even in case reserved bits are used and additional fields are
to it. added to it.
The length of the OSCORE option thus depends on the presence and The length of the OSCORE option thus depends on the presence and
length of Partial IV, kid context, kid, as specified in this section, length of Partial IV, 'kid context', 'kid', as specified in this
and on the presence and length of the other parameters, as defined in section, and on the presence and length of the other parameters, as
the separate documents. defined in the separate documents.
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
This section covers a list of OSCORE Header Compression examples for This section covers a list of OSCORE Header Compression examples for
requests and responses. The examples assume the COSE_Encrypt0 object requests and responses. The examples assume the COSE_Encrypt0 object
skipping to change at page 32, line 7 skipping to change at page 32, line 7
input necessary to the compression mechanism, i.e. the COSE_Encrypt0 input necessary to the compression mechanism, i.e. the COSE_Encrypt0
object. The output is the compressed COSE object as defined in object. The output is the compressed COSE object as defined in
Section 6, divided into two parts, since the object is transported in Section 6, divided into two parts, since the object is transported in
two CoAP fields: OSCORE option and payload. two CoAP fields: OSCORE option and payload.
1. Request with ciphertext = 0xaea0155667924dff8a24e4cb35b9, kid = 1. Request with ciphertext = 0xaea0155667924dff8a24e4cb35b9, kid =
0x25, and Partial IV = 0x05 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 (1 byte)
Option Value: 09 05 25 (3 bytes) Option Value: 0x090525 (3 bytes)
Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) Payload: 0xaea0155667924dff8a24e4cb35b9 (14 bytes)
2. Request with ciphertext = 0xaea0155667924dff8a24e4cb35b9, kid = 2. Request with ciphertext = 0xaea0155667924dff8a24e4cb35b9, kid =
empty string, and Partial IV = 0x00 empty string, and Partial IV = 0x00
Before compression (23 bytes): Before compression (23 bytes):
[ [
h'', h'',
{ 4:h'', 6:h'00' }, { 4:h'', 6:h'00' },
h'aea0155667924dff8a24e4cb35b9' h'aea0155667924dff8a24e4cb35b9',
] ]
After compression (16 bytes): After compression (16 bytes):
Flag byte: 0b00001001 = 0x09 Flag byte: 0b00001001 = 0x09 (1 byte)
Option Value: 09 00 (2 bytes) Option Value: 0x0900 (2 bytes)
Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) Payload: 0xaea0155667924dff8a24e4cb35b9 (14 bytes)
3. Request with ciphertext = 0xaea0155667924dff8a24e4cb35b9, kid = 3. Request with ciphertext = 0xaea0155667924dff8a24e4cb35b9, kid =
empty string, Partial IV = 0x05, and kid context = 0x44616c656b empty string, Partial IV = 0x05, and kid context = 0x44616c656b
Before compression (30 bytes): Before compression (30 bytes):
[ [
h'', h'',
{ 4:h'', 6:h'05', 8:h'44616c656b' }, { 4:h'', 6:h'05', 8:h'44616c656b' },
h'aea0155667924dff8a24e4cb35b9' h'aea0155667924dff8a24e4cb35b9',
] ]
After compression (22 bytes): After compression (22 bytes):
Flag byte: 0b00011001 = 0x19 Flag byte: 0b00011001 = 0x19 (1 byte)
Option Value: 19 05 05 44 61 6c 65 6b (8 bytes) Option Value: 0x19050544616c656b (8 bytes)
Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) Payload: 0xae a0155667924dff8a24e4cb35b9 (14 bytes)
4. Response with ciphertext = 0xaea0155667924dff8a24e4cb35b9 and no 4. Response with ciphertext = 0xaea0155667924dff8a24e4cb35b9 and no
Partial IV Partial IV
Before compression (18 bytes): Before compression (18 bytes):
[ [
h'', h'',
{}, {},
h'aea0155667924dff8a24e4cb35b9' h'aea0155667924dff8a24e4cb35b9',
] ]
After compression (14 bytes): After compression (14 bytes):
Flag byte: 0b00000000 = 0x00 Flag byte: 0b00000000 = 0x00 (1 byte)
Option Value: (0 bytes) Option Value: 0x (0 bytes)
Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) Payload: 0xaea0155667924dff8a24e4cb35b9 (14 bytes)
5. Response with ciphertext = 0xaea0155667924dff8a24e4cb35b9 and 5. Response with ciphertext = 0xaea0155667924dff8a24e4cb35b9 and
Partial IV = 0x07 Partial IV = 0x07
Before compression (21 bytes): Before compression (21 bytes):
[ [
h'', h'',
{ 6:h'07' }, { 6:h'07' },
h'aea0155667924dff8a24e4cb35b9' h'aea0155667924dff8a24e4cb35b9',
] ]
After compression (16 bytes): After compression (16 bytes):
Flag byte: 0b00000001 = 0x01 Flag byte: 0b00000001 = 0x01 (1 byte)
Option Value: 01 07 (2 bytes) Option Value: 0x0107 (2 bytes)
Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) Payload: 0xaea0155667924dff8a24e4cb35b9 (14 bytes)
7. Message Binding, Sequence Numbers, Freshness and Replay Protection 7. Message Binding, Sequence Numbers, Freshness, and Replay Protection
7.1. Message Binding 7.1. Message Binding
In order to prevent response delay and mismatch attacks In order to prevent response delay and mismatch attacks
[I-D.mattsson-core-coap-actuators] from on-path attackers and [I-D.mattsson-core-coap-actuators] from on-path attackers and
compromised intermediaries, OSCORE binds responses to the requests by compromised intermediaries, OSCORE binds responses to the requests by
including the kid and Partial IV of the request in the AAD of the including the 'kid' and Partial IV of the request in the AAD of the
response. The server therefore needs to store the kid and Partial IV response. The server therefore needs to store the 'kid' and Partial
of the request until all responses have been sent. IV of the request until all responses have been sent.
7.2. Sequence Numbers 7.2. Sequence Numbers
An AEAD nonce MUST NOT be used more than once per AEAD key. The An AEAD nonce MUST NOT be used more than once per AEAD key. The
uniqueness of (key, nonce) pairs is shown in Appendix D.3, and in uniqueness of (key, nonce) pairs is shown in Appendix D.4, and in
particular depends on a correct usage of Partial IVs (which encode particular depends on a correct usage of Partial IVs (which encode
the Sender Sequence Numbers, see Section 5). If messages are the Sender Sequence Numbers, see Section 5). If messages are
processed concurrently, the operation of reading and increasing the processed concurrently, the operation of reading and increasing the
Sender Sequence Number MUST be atomic. Sender Sequence Number MUST be atomic.
7.2.1. Maximum Sequence Number 7.2.1. Maximum Sequence Number
The maximum Sender Sequence Number is algorithm dependent (see The maximum Sender Sequence Number is algorithm dependent (see
Section 12), and SHALL be less than 2^40. If the Sender Sequence Section 12), and SHALL be less than 2^40. 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
skipping to change at page 35, line 14 skipping to change at page 35, line 14
For requests and notifications, OSCORE also provides relative For requests and notifications, OSCORE also provides relative
freshness in the sense that the received Partial IV allows a freshness in the sense that the received Partial IV allows a
recipient to determine the relative order of requests or responses. recipient to determine the relative order of requests or responses.
7.4. Replay Protection 7.4. Replay Protection
In order to protect from replay of requests, the server's Recipient In order to protect from replay of requests, the server's Recipient
Context includes a Replay Window. A server SHALL verify that a Context includes a Replay Window. A server SHALL verify that a
Partial IV = Sender Sequence Number received in the COSE object has Partial IV = Sender Sequence Number received in the COSE object has
not been received before. If this verification fails the server not been received before. If this verification fails, the server
SHALL stop processing the message, and MAY optionally respond with a SHALL stop processing the message, and MAY optionally respond with a
4.01 Unauthorized error message. Also, the server MAY set an Outer 4.01 (Unauthorized) error message. Also, the server MAY set an Outer
Max-Age option with value zero, to inform any intermediary that the Max-Age option with value zero, to inform any intermediary that the
response is not to be cached. The diagnostic payload MAY contain the response is not to be cached. The diagnostic payload MAY contain the
"Replay detected" string. The size and type of the Replay Window "Replay detected" string. The size and type of the Replay Window
depends on the use case and the protocol with which the OSCORE depends on the use case and the protocol with which the OSCORE
message is transported. In case of reliable and ordered transport message is transported. In case of reliable and ordered transport
from endpoint to endpoint, e.g. TCP, the server MAY just store the from endpoint to endpoint, e.g. TCP, the server MAY just store the
last received Partial IV and require that newly received Partial IVs last received Partial IV and require that newly received Partial IVs
equals the last received Partial IV + 1. However, in case of mixed equals the last received Partial IV + 1. However, in case of mixed
reliable and unreliable transports and where messages may be lost, reliable and unreliable transports and where messages may be lost,
such a replay mechanism may be too restrictive and the default replay such a replay mechanism may be too restrictive and the default replay
skipping to change at page 36, line 15 skipping to change at page 36, line 15
If the verification of the response succeeds, and the received If the verification of the response succeeds, and the received
Partial IV was greater than the Notification Number then the client Partial IV was greater than the Notification Number then the client
SHALL overwrite the corresponding Notification Number with the SHALL overwrite the corresponding Notification Number with the
received Partial IV. received Partial IV.
7.5. Losing Part of the Context State 7.5. Losing Part of the Context State
To prevent reuse of an AEAD nonce with the same AEAD key, or from To prevent reuse of an AEAD nonce with the same AEAD 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 Sender Sequence Number, and Replay Window. These are typically
Notification Numbers. These are typically stored in RAM and stored in RAM and therefore lost in the case of e.g. an unplanned
therefore lost in the case of an unplanned reboot. reboot. There are different alternatives to recover, for example:
After boot, an endpoint can either use a persistently stored complete
or partial security context, or establish a new security context with
each endpoint it communicates with. However, establishing a fresh
security context may have a non-negligible cost in terms of, e.g.,
power consumption.
If the endpoint uses a persistently stored partial security context,
it MUST NOT reuse a previous Sender Sequence Number and MUST NOT
accept previously received messages. Some ways to achieve this are
described in the following sections.
7.5.1. Sequence Number
To prevent reuse of Sender Sequence Numbers, an endpoint may perform
the following procedure during normal operations:
o Before using a Sender Sequence Number that is evenly divisible by
K, where K is a positive integer, store the Sender Sequence Number
in persistent memory. After boot, the endpoint initiates the
Sender Sequence Number to the value stored in persistent memory +
K. Storing to persistent memory can be costly. The value K gives
a trade-off between the number of storage operations and efficient
use of Sender Sequence Numbers.
7.5.2. Replay Window
To prevent accepting replay of previously received requests, the
server may perform the following procedure after boot:
o For each stored security context, the first time after boot the 1. The endpoints can reuse an existing Security Context after
server receives an OSCORE request, the server responds with the updating the mutable parts of the security context (Sender
Echo option [I-D.ietf-core-echo-request-tag] to get a request with Sequence Number, and Replay Window). This requires that the
verifiable freshness. The server MUST use its Sender Sequence mutable parts of the security context are available throughout
Number (initiated as in Section 7.5.1) when generating the AEAD the lifetime of the device, or that the device can establish safe
nonce and MUST include it as Partial IV in the response. security context after loss of mutable security context data.
Examples is given based on careful use of non-volatile memory,
see Appendix B.1.1, and additionally the use of the Echo option,
see Appendix B.1.2. If an endpoint makes use of a partial
security context stored in non-volatile memory, it MUST NOT reuse
a previous Sender Sequence Number and MUST NOT accept previously
received messages.
If the server using the Echo option can verify a second request as 2. The endpoints can reuse an existing shared Master Secret and
fresh, then the Partial IV of the second request is set as the lower derive new Sender and Recipient Contexts, see Appendix B.2 for an
limit of the replay window of Sender Sequence Numbers. example. This typically requires a good source of randomness.
7.5.3. Replay of Notifications 3. The endpoints can use a trusted-third party assisted key
establishment protocol such as [I-D.ietf-ace-oscore-profile].
This requires the execution of three-party protocol and may
require a good source of randomness.
To prevent accepting replay of previously received notifications, the 4. The endpoints can run a key exchange protocol providing forward
client may perform the following procedure after boot: secrecy resulting in a fresh Master Secret, from which an
entirely new Security Context is derived. This requires a good
source of randomness, and additionally, the transmission and
processing of the protocol may have a non-negligible cost, e.g.
in terms of power consumption.
o The client forgets about earlier registrations, removes all The endpoints need to be configured with information about which
Notification Numbers and registers using Observe. method is used. The choice of method may depend on capabilities of
the devices deployed and the solution architecture. Using a key
exchange protocol is necessary for deployments that require forward
secrecy.
8. Processing 8. Processing
This section describes the OSCORE message processing. Additional This section describes the OSCORE message processing. Additional
processing for Observe or Block-wise are described in subsections. processing for Observe or Block-wise are described in subsections.
Note that, analogously to [RFC7252] where the Token and source/ Note that, analogously to [RFC7252] where the Token and source/
destination pair are used to match a response with a request, both destination pair are used to match a response with a request, both
endpoints MUST keep the association (Token, {Security Context, endpoints MUST keep the association (Token, {Security Context,
Partial IV of the request}), in order to be able to find the Security Partial IV of the request}), in order to be able to find the Security
skipping to change at page 38, line 30 skipping to change at page 38, line 14
2. Decompress the COSE Object (Section 6) and retrieve the Recipient 2. Decompress the COSE Object (Section 6) and retrieve the Recipient
Context associated with the Recipient ID in the 'kid' parameter, Context associated with the Recipient ID in the 'kid' parameter,
additionally using the 'kid context', if present. If either the additionally using the 'kid context', if present. If either the
decompression or the COSE message fails to decode, or the server decompression or the COSE message fails to decode, or the server
fails to retrieve a Recipient Context with Recipient ID fails to retrieve a Recipient Context with Recipient ID
corresponding to the 'kid' parameter received, then the server corresponding to the 'kid' parameter received, then the server
SHALL stop processing the request. SHALL stop processing the request.
* If either the decompression or the COSE message fails to * If either the decompression or the COSE message fails to
decode, the server MAY respond with a 4.02 Bad Option error decode, the server MAY respond with a 4.02 (Bad Option) error
message. The server MAY set an Outer Max-Age option with message. The server MAY set an Outer Max-Age option with
value zero. The diagnostic payload SHOULD contain the string value zero. The diagnostic payload MAY contain the string
"Failed to decode COSE". "Failed to decode COSE".
* If the server fails to retrieve a Recipient Context with * If the server fails to retrieve a Recipient Context with
Recipient ID corresponding to the 'kid' parameter received, Recipient ID corresponding to the 'kid' parameter received,
the server MAY respond with a 4.01 Unauthorized error message. the server MAY respond with a 4.01 (Unauthorized) error
The server MAY set an Outer Max-Age option with value zero. message. The server MAY set an Outer Max-Age option with
The diagnostic payload SHOULD contain the string "Security value zero. The diagnostic payload MAY contain the string
context not found". "Security context not found".
3. Verify that the 'Partial IV' has not been received before using 3. Verify that the 'Partial IV' has not been received before using
the Replay Window, as described in Section 7.4. the Replay Window, as described in Section 7.4.
4. Compose the Additional Authenticated Data, as described in 4. Compose the Additional Authenticated Data, as described in
Section 5.4. Section 5.4.
5. Compute the AEAD nonce from the Recipient ID, Common IV, and the 5. Compute the AEAD nonce from the Recipient ID, Common IV, and the
'Partial IV' parameter, received in the COSE Object. 'Partial IV' parameter, received in the COSE Object.
6. Decrypt the COSE object using the Recipient Key, as per [RFC8152] 6. Decrypt the COSE object using the Recipient Key, as per [RFC8152]
Section 5.3. (The decrypt operation includes the verification of Section 5.3. (The decrypt operation includes the verification of
the integrity.) the integrity.)
* If decryption fails, the server MUST stop processing the * If decryption fails, the server MUST stop processing the
request and MAY respond with a 4.00 Bad Request error message. request and MAY respond with a 4.00 (Bad Request) error
The server MAY set an Outer Max-Age option with value zero. message. The server MAY set an Outer Max-Age option with
The diagnostic payload MAY contain the "Decryption failed" value zero. The diagnostic payload MAY contain the
string. "Decryption failed" string.
* If decryption succeeds, update the Replay Window, as described * If decryption succeeds, update the Replay Window, as described
in Section 7. in Section 7.
7. Add decrypted Code, options, and payload to the decrypted 7. Add decrypted Code, options, and payload to the decrypted
request. The OSCORE option is removed. request. The OSCORE option is removed.
8. The decrypted CoAP request is processed according to [RFC7252]. 8. The decrypted CoAP request is processed according to [RFC7252].
8.2.1. Supporting Block-wise 8.2.1. Supporting Block-wise
If Block-wise is supported, insert the following step before any If Block-wise is supported, insert the following step before any
other: other:
A. If Block-wise is present in the request then process the Outer A. If Block-wise is present in the request, then process the Outer
Block options according to [RFC7959], until all blocks of the request Block options according to [RFC7959], until all blocks of the request
have been received (see Section 4.1.3.4). have been received (see Section 4.1.3.4).
8.3. Protecting the Response 8.3. Protecting the Response
If a CoAP response is generated in response to an OSCORE request, the If a CoAP response is generated in response to an OSCORE request, the
server SHALL perform the following steps to create an OSCORE server SHALL perform the following steps to create an OSCORE
response. Note that CoAP error responses derived from CoAP response. Note that CoAP error responses derived from CoAP
processing (step 8 in Section 8.2) are protected, as well as processing (step 8 in Section 8.2) are protected, as well as
successful CoAP responses, while the OSCORE errors (steps 2, 3, and 6 successful CoAP responses, while the OSCORE errors (steps 2, 3, and 6
skipping to change at page 41, line 43 skipping to change at page 41, line 22
7. The decrypted CoAP response is processed according to [RFC7252]. 7. The decrypted CoAP response is processed according to [RFC7252].
8. In case any of the previous erroneous conditions apply: the 8. In case any of the previous erroneous conditions apply: the
client SHALL stop processing the response. client SHALL stop processing the response.
8.4.1. Supporting Block-wise 8.4.1. Supporting Block-wise
If Block-wise is supported, insert the following step before any If Block-wise is supported, insert the following step before any
other: other:
A. If Block-wise is present in the request then process the Outer A. If Block-wise is present in the request, then process the Outer
Block options according to [RFC7959], until all blocks of the request Block options according to [RFC7959], until all blocks of the request
have been received (see Section 4.1.3.4). have been received (see Section 4.1.3.4).
8.4.2. Supporting Observe 8.4.2. Supporting Observe
If Observe is supported: If Observe is supported:
Insert the following step between step 5 and step 6: Insert the following step between step 5 and step 6:
A. If the request was an Observe registration, then: A. If the request was an Observe registration, then:
skipping to change at page 45, line 20 skipping to change at page 44, line 40
o the CoAP-to-HTTP proxy follows the redirect, instead of the CoAP o the CoAP-to-HTTP proxy follows the redirect, instead of the CoAP
client as in the HTTP case client as in the HTTP case
o the CoAP-to-HTTP proxy copies the HTTP OSCORE header field and o the CoAP-to-HTTP proxy copies the HTTP OSCORE header field and
body to the new request body to the new request
o the target of the redirect has the necessary OSCORE security o the target of the redirect has the necessary OSCORE security
context required to decrypt and verify the message context required to decrypt and verify the message
Since OSCORE requires HTTP body to be preserved across redirects, the Since OSCORE requires HTTP body to be preserved across redirects, the
HTTP server is recommended to reply with 307 or 308 instead of 301 or HTTP server is RECOMMENDED to reply with 307 or 308 instead of 301 or
302. 302.
For the case of HTTP client to CoAP server, although redirect is not For the case of HTTP client to CoAP server, although redirect is not
defined for CoAP servers [RFC7252], an HTTP client receiving a defined for CoAP servers [RFC7252], an HTTP client receiving a
redirect should generate a new OSCORE request for the server it was redirect should generate a new OSCORE request for the server it was
redirected to. redirected to.
11.2. CoAP-to-HTTP Mapping 11.2. CoAP-to-HTTP Mapping
Section 10.1 of [RFC7252] describes the fundamentals of the CoAP-to- Section 10.1 of [RFC7252] describes the fundamentals of the CoAP-to-
skipping to change at page 49, line 40 skipping to change at page 49, line 11
"raise bridge"). Even in the rare cases where all the owners of the "raise bridge"). Even in the rare cases where all the owners of the
intermediary nodes are fully trusted, attacks and data breaches make intermediary nodes are fully trusted, attacks and data breaches make
such an architecture brittle. such an architecture brittle.
(D)TLS protects hop-by-hop the entire message. OSCORE protects end- (D)TLS protects hop-by-hop the entire message. OSCORE protects end-
to-end all information that is not required for proxy operations (see to-end all information that is not required for proxy operations (see
Section 4). (D)TLS and OSCORE can be combined, thereby enabling end- Section 4). (D)TLS and OSCORE can be combined, thereby enabling end-
to-end security of the message payload, in combination with hop-by- to-end security of the message payload, in combination with hop-by-
hop protection of the entire message, during transport between end- hop protection of the entire message, during transport between end-
point and intermediary node. In particular when OSCORE is used with point and intermediary node. In particular when OSCORE is used with
HTTP, the additional TLS protection of HTTP hops is recommended, e.g. HTTP, the additional TLS protection of HTTP hops is RECOMMENDED, e.g.
between an HTTP endpoint and a proxy translating between HTTP and between an HTTP endpoint and a proxy translating between HTTP and
CoAP. CoAP.
Applications need to consider that certain message fields and Applications need to consider that certain message fields and
messages types are not protected end-to-end and may be spoofed or messages types are not protected end-to-end and may be spoofed or
manipulated. The consequences of unprotected message fields are manipulated. The consequences of unprotected message fields are
analyzed in Appendix D.4. analyzed in Appendix D.5.
12.2. Security Context Establishment 12.2. Security Context Establishment
The use of COSE_Encrypt0 and AEAD to protect messages as specified in The use of COSE_Encrypt0 and AEAD to protect messages as specified in
this document requires an established security context. The method this document requires an established security context. The method
to establish the security context described in Section 3.2 is based to establish the security context described in Section 3.2 is based
on a common Master Secret and unique Sender IDs. The necessary input on a common Master Secret and unique Sender IDs. The necessary input
parameters may be pre-established or obtained using a key parameters may be pre-established or obtained using a key
establishment protocol augmented with establishment of Sender/ establishment protocol augmented with establishment of Sender/
Recipient ID such as the OSCORE profile of the ACE framework Recipient ID, such as a key exchange protocol or the OSCORE profile
[I-D.ietf-ace-oscore-profile]. Such a procedure must ensure that the of the ACE framework [I-D.ietf-ace-oscore-profile]. Such a procedure
requirements of the security context parameters for the intended use must ensure that the requirements of the security context parameters
are complied with (see Section 3.3) and also in error situations. for the intended use are complied with (see Section 3.3) and also in
While recipient IDs are allowed to coincide between different error situations. While recipient IDs are allowed to coincide
security contexts (see Section 3.3), this may cause a server to between different security contexts (see Section 3.3), this may cause
process multiple verifications before finding the right security a server to process multiple verifications before finding the right
context or rejecting a message. Moreover, it is recommended to use a security context or rejecting a message. Considerations for
key establishment protocol which provides forward secrecy whenever deploying OSCORE with a fixed Master Secret are given in Appendix B.
possible. Considerations for deploying OSCORE with a fixed Master
Secret are given in Appendix B.
12.3. Master Secret 12.3. Master Secret
OSCORE uses HKDF [RFC5869] and the established input parameters to OSCORE uses HKDF [RFC5869] and the established input parameters to
derive the security context. The required properties of the security derive the security context. The required properties of the security
context parameters are discussed in Section 3.3, in this section we context parameters are discussed in Section 3.3, in this section we
focus on the Master Secret. HKDF denotes in this specification the focus on the Master Secret. HKDF denotes in this specification the
composition of the expand and extract functions as defined in composition of the expand and extract functions as defined in
[RFC5869] and the Master Secret is used as Input Key Material (IKM). [RFC5869] and the Master Secret is used as Input Key Material (IKM).
skipping to change at page 51, line 47 skipping to change at page 51, line 15
In order to prevent cryptanalysis when the same plaintext is In order to prevent cryptanalysis when the same plaintext is
repeatedly encrypted by many different users with distinct AEAD keys, repeatedly encrypted by many different users with distinct AEAD keys,
the AEAD nonce is formed by mixing the sequence number with a secret the AEAD nonce is formed by mixing the sequence number with a secret
per-context initialization vector (Common IV) derived along with the per-context initialization vector (Common IV) derived along with the
keys (see Section 3.1 of [RFC8152]), and by using a Master Salt in keys (see Section 3.1 of [RFC8152]), and by using a Master Salt in
the key derivation (see [MF00] for an overview). The Master Secret, the key derivation (see [MF00] for an overview). The Master Secret,
Sender Key, Recipient Key, and Common IV must be secret, the rest of Sender Key, Recipient Key, and Common IV must be secret, the rest of
the parameters may be public. The Master Secret must have a good the parameters may be public. The Master Secret must have a good
amount of randomness (see Section 12.3). amount of randomness (see Section 12.3).
The ID Context, Sender ID, and Partial IV are always at least
implicitly integrity protected, as manipulation leads to the wrong
nonce or key being used and therefore results in decryption failure.
12.7. Message Segmentation 12.7. Message Segmentation
The Inner Block options enable the sender to split large messages The Inner Block options enable the sender to split large messages
into OSCORE-protected blocks such that the receiving endpoint can into OSCORE-protected blocks such that the receiving endpoint can
verify blocks before having received the complete message. The Outer verify blocks before having received the complete message. The Outer
Block options allow for arbitrary proxy fragmentation operations that Block options allow for arbitrary proxy fragmentation operations that
cannot be verified by the endpoints, but can by policy be restricted cannot be verified by the endpoints, but can by policy be restricted
in size since the Inner Block options allow for secure fragmentation in size since the Inner Block options allow for secure fragmentation
of very large messages. A maximum message size (above which the of very large messages. A maximum message size (above which the
sending endpoint fragments the message and the receiving endpoint sending endpoint fragments the message and the receiving endpoint
skipping to change at page 52, line 22 skipping to change at page 51, line 42
12.8. Privacy Considerations 12.8. 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 5) may reveal privacy sensitive The unprotected options (Figure 5) may reveal privacy sensitive
information, see Appendix D.4. CoAP headers sent in plaintext allow, information, see Appendix D.5. CoAP headers sent in plaintext allow,
for example, matching of CON and ACK (CoAP Message Identifier), for example, matching of CON and ACK (CoAP Message Identifier),
matching of request and responses (Token) and traffic analysis. matching of request and responses (Token) and traffic analysis.
OSCORE does not provide protection for HTTP header fields which are OSCORE does not provide protection for HTTP header fields which are
not both CoAP-mappable and class E. The HTTP message fields which not both CoAP-mappable and class E. The HTTP message fields which
are visible to on-path entity are only used for the purpose of are visible to on-path entity are only used for the purpose of
transporting the OSCORE message, whereas the application layer transporting the OSCORE message, whereas the application layer
message is encoded in CoAP and encrypted. message is encoded in CoAP and encrypted.
COSE message fields, i.e. the OSCORE option, may reveal information COSE message fields, i.e. the OSCORE option, may reveal information
about the communicating endpoints. E.g. 'kid' and 'kid context', about the communicating endpoints. E.g. 'kid' and 'kid context',
skipping to change at page 53, line 10 skipping to change at page 52, line 26
The length of message fields can reveal information about the The length of message fields can reveal information about the
message. Applications may use a padding scheme to protect against message. Applications may use a padding scheme to protect against
traffic analysis. traffic analysis.
13. IANA Considerations 13. IANA Considerations
Note to RFC Editor: Please replace all occurrences of "[[this Note to RFC Editor: Please replace all occurrences of "[[this
document]]" with the RFC number of this specification. document]]" with the RFC number of this specification.
Note to IANA: Please note all occurrences of "TBDx" in this Note to IANA: Please note all occurrences of "TBD1" in this
specification should be assigned the same number. specification should be assigned the same number.
13.1. COSE Header Parameters Registry 13.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: TBD2 o Label: TBD2
o Value Type: bstr o Value Type: bstr
o Value Registry: o Value Registry:
o Description: Identifies the context for kid o Description: Identifies the context for 'kid'
o Reference: Section 5.1 of this document o Reference: Section 5.1 of this document
Note to IANA: Label assignment in (Integer value between 1 and 255) Note to IANA: Label assignment in (Integer value between 1 and 255)
is requested. (RFC Editor: Delete this note after IANA assignment) is requested. (RFC Editor: Delete this note after IANA assignment)
13.2. CoAP Option Numbers Registry 13.2. CoAP Option Numbers Registry
The OSCORE option is added to the CoAP Option Numbers registry: The OSCORE option is added to the CoAP Option Numbers registry:
skipping to change at page 55, line 10 skipping to change at page 54, line 28
TBD1 is not the same as any value in Numbers for any existing entry TBD1 is not the same as any value in Numbers for any existing entry
in the CoAP Signaling Option Numbers registry (at the time of writing in the CoAP Signaling Option Numbers registry (at the time of writing
this, that means make sure TBD1 is not 2 or 4)(RFC Editor: Delete this, that means make sure TBD1 is not 2 or 4)(RFC Editor: Delete
this note after IANA assignment) this note after IANA assignment)
13.4. Header Field Registrations 13.4. Header Field Registrations
The HTTP OSCORE header field is added to the Message Headers The HTTP OSCORE header field is added to the Message Headers
registry: registry:
+-------------------+----------+----------+---------------------------------+ +-------------------+----------+----------+---------------------+
| Header Field Name | Protocol | Status | Reference | | Header Field Name | Protocol | Status | Reference |
+-------------------+----------+----------+---------------------------------+ +-------------------+----------+----------+---------------------+
| OSCORE | http | standard | [[this document]], Section 11.1 | | OSCORE | http | standard | [[this document]], |
+-------------------+----------+----------+---------------------------------+ | | | | Section 11.1 |
+-------------------+----------+----------+---------------------+
13.5. Media Type Registrations 13.5. Media Type Registrations
This section registers the 'application/oscore' media type in the This section registers the 'application/oscore' media type in the
"Media Types" registry. These media types are used to indicate that "Media Types" registry. These media types are used to indicate that
the content is an OSCORE message. The OSCORE body cannot be the content is an OSCORE message. The OSCORE body cannot be
understood without the OSCORE header field value and the security understood without the OSCORE header field value and the security
context. context.
Type name: application Type name: application
skipping to change at page 58, line 16 skipping to change at page 57, line 16
+--------------+-------------+---------------------+-------------------+ +--------------+-------------+---------------------+-------------------+
| Bit Position | Name | Description | Specification | | Bit Position | Name | Description | Specification |
+--------------+-------------+---------------------+-------------------+ +--------------+-------------+---------------------+-------------------+
| 0 | Reserved | | | | 0 | Reserved | | |
+--------------+-------------+---------------------+-------------------+ +--------------+-------------+---------------------+-------------------+
| 1 | Reserved | | | | 1 | Reserved | | |
+--------------+-------------+---------------------+-------------------+ +--------------+-------------+---------------------+-------------------+
| 2 | Unassigned | | | | 2 | Unassigned | | |
+--------------+-------------+---------------------+-------------------+ +--------------+-------------+---------------------+-------------------+
| 3 | Kid Context | Set to 1 if kid | [[this document]] | | 3 | Kid Context | Set to 1 if 'kid | [[this document]] |
| | Flag | context is present | | | | Flag | context' is present | |
| | | in the compressed | | | | | in the compressed | |
| | | COSE object | | | | | COSE object | |
+--------------+-------------+---------------------+-------------------+ +--------------+-------------+---------------------+-------------------+
| 4 | Kid Flag | Set to 1 if kid is | [[this document]] | | 4 | Kid Flag | Set to 1 if kid is | [[this document]] |
| | | present in the com- | | | | | present in the com- | |
| | | pressed COSE object | | | | | pressed COSE object | |
+--------------+-------------+---------------------+-------------------+ +--------------+-------------+---------------------+-------------------+
| 5-7 | Partial IV | Encodes the Partial | [[this document]] | | 5-7 | Partial IV | Encodes the Partial | [[this document]] |
| | Length | IV length; can have | | | | Length | IV length; can have | |
| | | value 0 to 5 | | | | | value 0 to 5 | |
skipping to change at page 61, line 20 skipping to change at page 60, line 20
[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-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) using the OAuth 2.0 Constrained Environments (ACE) using the OAuth 2.0
Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-13 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-22
(work in progress), July 2018. (work in progress), March 2019.
[I-D.ietf-ace-oscore-profile] [I-D.ietf-ace-oscore-profile]
Seitz, L., Palombini, F., Gunnarsson, M., and G. Selander, Palombini, F., Seitz, L., Selander, G., and M. Gunnarsson,
"OSCORE profile of the Authentication and Authorization "OSCORE profile of the Authentication and Authorization
for Constrained Environments Framework", draft-ietf-ace- for Constrained Environments Framework", draft-ietf-ace-
oscore-profile-02 (work in progress), June 2018. oscore-profile-07 (work in progress), February 2019.
[I-D.ietf-cbor-cddl] [I-D.ietf-cbor-cddl]
Birkholz, H., Vigano, C., and C. Bormann, "Concise data Birkholz, H., Vigano, C., and C. Bormann, "Concise data
definition language (CDDL): a notational convention to definition language (CDDL): a notational convention to
express CBOR and JSON data structures", draft-ietf-cbor- express CBOR and JSON data structures", draft-ietf-cbor-
cddl-05 (work in progress), August 2018. cddl-07 (work in progress), February 2019.
[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-02 (work in Request-Tag", draft-ietf-core-echo-request-tag-03 (work in
progress), June 2018. progress), October 2018.
[I-D.ietf-core-oscore-groupcomm] [I-D.ietf-core-oscore-groupcomm]
Tiloca, M., Selander, G., Palombini, F., and J. Park, Tiloca, M., Selander, G., Palombini, F., and J. Park,
"Secure group communication for CoAP", draft-ietf-core- "Group OSCORE - Secure Group Communication for CoAP",
oscore-groupcomm-02 (work in progress), June 2018. draft-ietf-core-oscore-groupcomm-03 (work in progress),
October 2018.
[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-05 (work in progress), March mattsson-core-coap-actuators-06 (work in progress),
2018. September 2018.
[I-D.mcgrew-iv-gen] [I-D.mcgrew-iv-gen]
McGrew, D., "Generation of Deterministic Initialization McGrew, D., "Generation of Deterministic Initialization
Vectors (IVs) and Nonces", draft-mcgrew-iv-gen-03 (work in Vectors (IVs) and Nonces", draft-mcgrew-iv-gen-03 (work in
progress), October 2013. progress), October 2013.
[MF00] McGrew, D. and S. Fluhrer, "Attacks on Encryption of [MF00] McGrew, D. and S. Fluhrer, "Attacks on Encryption of
Redundant Plaintext and Implications on Internet Redundant Plaintext and Implications on Internet
Security", the Proceedings of the Seventh Annual Workshop Security", the Proceedings of the Seventh Annual Workshop
on Selected Areas in Cryptography (SAC 2000), Springer- on Selected Areas in Cryptography (SAC 2000), Springer-
Verlag. , 2000. Verlag. , 2000.
[RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC
Text on Security Considerations", BCP 72, RFC 3552,
DOI 10.17487/RFC3552, July 2003,
<https://www.rfc-editor.org/info/rfc3552>.
[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
skipping to change at page 63, line 17 skipping to change at page 62, line 23
A.1. Secure Access to Sensor A.1. Secure Access to Sensor
This example illustrates a client requesting the alarm status from a This example illustrates a client requesting the alarm status from a
server. server.
Client Proxy Server Client Proxy Server
| | | | | |
+------>| | Code: 0.02 (POST) +------>| | Code: 0.02 (POST)
| POST | | Token: 0x8c | POST | | Token: 0x8c
| | | OSCORE: [kid:5f,Partial IV:42] | | | OSCORE: [kid:5f, Partial IV:42]
| | | Payload: {Code:0.01, | | | Payload: {Code:0.01,
| | | Uri-Path:"alarm_status"} | | | Uri-Path:"alarm_status"}
| | | | | |
| +------>| Code: 0.02 (POST) | +------>| Code: 0.02 (POST)
| | POST | Token: 0x7b | | POST | Token: 0x7b
| | | OSCORE: [kid:5f,Partial IV:42] | | | OSCORE: [kid:5f, Partial IV:42]
| | | Payload: {Code:0.01, | | | Payload: {Code:0.01,
| | | Uri-Path:"alarm_status"} | | | Uri-Path:"alarm_status"}
| | | | | |
| |<------+ Code: 2.04 (Changed) | |<------+ Code: 2.04 (Changed)
| | 2.04 | Token: 0x7b | | 2.04 | Token: 0x7b
| | | OSCORE: - | | | OSCORE: -
| | | Payload: {Code:2.05, "0"} | | | Payload: {Code:2.05, "0"}
| | | | | |
|<------+ | Code: 2.04 (Changed) |<------+ | Code: 2.04 (Changed)
| 2.04 | | Token: 0x8c | 2.04 | | Token: 0x8c
skipping to change at page 64, line 16 skipping to change at page 63, line 23
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)
| FETCH | | Token: 0x83 | FETCH | | Token: 0x83
| | | Observe: 0 | | | Observe: 0
| | | OSCORE: [kid:ca,Partial IV:15] | | | OSCORE: [kid:ca, Partial IV:15]
| | | Payload: {Code:0.01, | | | Payload: {Code:0.01,
| | | Uri-Path:"glucose"} | | | Uri-Path:"glucose"}
| | | | | |
| +------>| Code: 0.05 (FETCH) | +------>| Code: 0.05 (FETCH)
| | FETCH | Token: 0xbe | | FETCH | Token: 0xbe
| | | Observe: 0 | | | Observe: 0
| | | OSCORE: [kid:ca,Partial IV:15] | | | OSCORE: [kid:ca, Partial IV:15]
| | | Payload: {Code:0.01, | | | Payload: {Code:0.01,
| | | Uri-Path:"glucose"} | | | Uri-Path:"glucose"}
| | | | | |
| |<------+ Code: 2.05 (Content) | |<------+ Code: 2.05 (Content)
| | 2.05 | Token: 0xbe | | 2.05 | Token: 0xbe
| | | Observe: 7 | | | Observe: 7
| | | OSCORE: [Partial IV:32] | | | OSCORE: [Partial IV:32]
| | | Payload: {Code:2.05, | | | Payload: {Code:2.05,
| | | Content-Format:0, "220"} | | | Content-Format:0, "220"}
| | | | | |
skipping to change at page 65, line 28 skipping to change at page 64, line 35
Partial IV (15). The COSE headers of the responses contains Partial Partial IV (15). The COSE headers of the responses contains Partial
IVs (32 and 36). IVs (32 and 36).
The server verifies that the Partial IV has not been received before. The server verifies that the Partial IV has not been received before.
The client verifies that the responses are bound to the request and The client verifies that the responses are bound to the request and
that the Partial IVs are greater than any Partial IV previously that the Partial IVs are greater than any Partial IV previously
received in a response bound to the request. received in a response bound to the request.
Appendix B. Deployment Examples Appendix B. Deployment Examples
Two examples complying with the requirements on the security context For many IoT deployments, a 128 bit uniformly random Master Key is
parameters (Section 3.3) are given in this section. sufficient for encrypting all data exchanged with the IoT device
throughout its lifetime. Two examples are given in this section. In
the first example, the security context is only derived once from the
Master Secret. In the second example, security contexts are derived
multiple times using random inputs.
B.1. Master Secret Used Once B.1. Security Context Derived Once
An application may derive a security context once and use it for the An application that only derives the security context once needs to
lifetime of a device. For many IoT deployments, a 128 bit uniformly handle the loss of mutable security context parameters, e.g. due to
random Master Key is sufficient for encrypting all data exchanged reboot.
with the IoT device. This specification describes techniques for
persistent storage of the security context and synchronization of
sequence numbers (see Section 7.5) to ensure that security is
maintained with the existing security context.
B.2. Master Secret Used Multiple Times B.1.1. Sender Sequence Number
Section 12.2 recommends that the Master Secret is obtained from a key In order to handle loss of Sender Sequence Numbers, the device may
establishment protocol providing forward secrecy. implement procedures for writing to non-volatile memory during normal
operations and updating the security context after reboot, provided
that the procedures comply with the requirements on the security
context parameters (Section 3.3). This section gives an example of
such a procedure.
There are known issues related to writing to non-volatile memory.
For example, flash drives may have a limited number of erase
operations during its life time. Also, the time for a write
operation to non-volatile memory to be completed may be
unpredictable, e.g. due to caching, which could result in important
security context data not being stored at the time when the device
reboots.
However, many devices have predictable limits for writing to non-
volatile memory, are physically limited to only send a small amount
of messages per minute, and may have no good source of randomness.
To prevent reuse of Sender Sequence Numbers (SSN), an endpoint may
perform the following procedure during normal operations:
o Before using a Sender Sequence Number that is evenly divisible by
K, where K is a positive integer, store the Sender Sequence Number
(SSN1) in non-volatile memory. After boot, the endpoint initiates
the new Sender Sequence Number (SSN2) to the value stored in
persistent memory plus K plus F: SSN2 = SSN1 + K + F, where F is a
positive integer.
* Writing to non-volatile memory can be costly; the value K gives
a trade-off between frequency of storage operations and
efficient use of Sender Sequence Numbers.
* Writing to non-volatile memory may be subject to delays, or
failure; F MUST be set so that the last Sender Sequence Number
used before reboot is never larger than SSN2.
If F cannot be set so SSN2 is always larger than the last Sender
Sequence Number used before reboot, the method described in this
section MUST NOT be used.
B.1.2. Replay Window
In case of loss of security context on the server, to prevent
accepting replay of previously received requests, the server may
perform the following procedure after boot:
o The server updates its Sender Sequence Number as specified in
Appendix B.1.1, to be used as Partial IV in the response
containing the Echo option (next bullet).
o For each stored security context, the first time after boot the
server receives an OSCORE request, the server responds with an
OSCORE protected 4.01 (Unauthorized), containing only the Echo
option [I-D.ietf-core-echo-request-tag] and no diagnostic payload.
The server MUST use its Partial IV when generating the AEAD nonce
and MUST include the Partial IV in the response (see Section 5).
If the server with use of the Echo option can verify a second
OSCORE request as fresh, then the Partial IV of the second request
is set as the lower limit of the replay window of that security
context.
B.1.3. Notifications
To prevent accepting replay of previously received notifications, the
client may perform the following procedure after boot:
o The client forgets about earlier registrations, removes all
Notification Numbers and registers using Observe.
B.2. Security Context Derived Multiple Times
An application which does not require forward secrecy may allow An application which does not require forward secrecy may allow
multiple security contexts to be derived from one Master Secret. The multiple security contexts to be derived from one Master Secret. The
requirements on the security context parameters must be fulfilled requirements on the security context parameters MUST be fulfilled
(Section 3.3) even if the client or server is rebooted, (Section 3.3) even if the client or server is rebooted,
recommissioned or in error cases. recommissioned or in error cases.
This section gives an example of an application allowing new security This section gives an example of a protocol which adds randomness to
contexts to be derived from input parameters pre-established between the ID Context parameter and uses that together with input parameters
client and server for this purpose: in particular Master Secret, pre-established between client and server, in particular Master
Master Salt and Sender/Recipient ID (see Section 3.2): Secret, Master Salt, and Sender/Recipient ID (see Section 3.2), to
derive new security contexts. The random input is transported
between client and server in the 'kid context' parameter. This
protocol MUST NOT be used unless both endpoints have good sources of
randomness.
o The client generates an ID Context which has previously not been During normal requests the ID Context of an established security
used with the pre-established input parameters and derives a new context may be sent in the 'kid context' which, together with 'kid',
security context. ID context may be pseudo-random and large for facilitates for the server to locate a security context.
stochastic uniqueness, but care must be taken e.g. to avoid re-use Alternatively, the 'kid context' may be omitted since the ID Context
of the same seed for random number generation. Using this new is expected to be known to both client and server, see Section 5.1.
security context, the client generates an OSCORE request with (kid
context, kid) = (ID Context, Sender ID) in the OSCORE option.
o The server receiving such an OSCORE request with kid matching the The protocol described in this section may only be needed when the
Recipient ID of pre-established input parameters, but with a new mutable part of security context is lost in the client or server,
kid context, derives the security context using ID Context = kid e.g. when the endpoint has rebooted. The protocol may additionally
context. If the message verifies then a new security context with be used whenever the client and server need to derive a new security
this ID Context is stored in the server, and used in the response. context. For example, if a device is provisioned with one fixed set
Further requests with the same (kid context, kid) are verified of input parameters (including Master Secret, Sender and Recipient
with this security context. Identifiers) then a randomized ID Context ensures that the security
context is different for each deployment.
As an alternative procedure to reduce the subsequent overhead in The protocol is described below with reference to Figure 14. The
requests due to kid context, the verification of a message with a new client or the server may initiate the protocol, in the latter case
ID Context may trigger the server to generate a new kid to replace step 1 is omitted.
the Client Sender ID in future requests. A client may e.g. indicate
support for such a procedure by requesting a special well-known URI
and receive the new kid in the response, which together with the
input parameters and the ID context is used to derive the new
security context which may be identified only by its kid. The
details are out of scope for this specification.
The procedures may be complemented with the use of the Echo option Client Server
for verifying the aliveness of the client requesting a new security | |
context. 1. Protect with | request #1 |
ID Context = ID1 |--------------------->| 2. Verify with
| kid_context = ID1 | ID Context = ID1
| |
| response #1 | Protect with
3. Verify with |<---------------------| ID Context = R2||ID1
ID Context = R2||ID1 | kid_context = R2 |
| |
Protect with | request #2 |
ID Context = R2||R3 |--------------------->| 4. Verify with
| kid_context = R2||R3 | ID Context = R2||R3
| |
| response #2 | Protect with
5. Verify with |<---------------------| ID Context = R2||R3
ID Context = R2||R3 | |
Figure 14: Protocol for establishing a new security context.
1. (Optional) If the client does not have a valid security context
with the server, e.g. because of reboot or because this is the
first time it contacts the server, then it generates a random
string R1, and uses this as ID Context together with the input
parameters shared with the server to derive a first security
context. The client sends an OSCORE request to the server
protected with the first security context, containing R1 wrapped
in a CBOR bstr as 'kid context'. The request may target a
special resource used for updating security contexts.
2. The server receives an OSCORE request for which it does not have
a valid security context, either because the client has generated
a new security context ID1 = R1, or because the server has lost
part of its security context, e.g. ID Context, Sender Sequence
Number or replay window. If the server is able to verify the
request (see Section 8.2) with the new derived first security
context using the received ID1 (transported in 'kid context') as
ID Context and the input parameters associated to the received
'kid', then the server generates a random string R2, and derives
a second security context with ID Context = ID2 = R2 || ID1. The
server sends a 4.01 (Unauthorized) response protected with the
second security context, containing R2 wrapped in a CBOR bstr as
'kid context', and caches R2. R2 MUST NOT be reused as that may
lead to reuse of key and nonce in reponse #1. Note that the
server may receive several requests #1 associated with one
security context, leading to multiple parallel protocol runs.
Multiple instances of R2 may need to be cached until one of the
protocol runs is completed, see Appendix B.2.1.
3. The client receives a response with 'kid context' containing a
CBOR bstr wrapping R2 to an OSCORE request it made with ID
Context = ID1. The client derives a second security context
using ID Context = ID2 = R2 || ID1. If the client can verify the
response (see Section 8.4) using the second security context,
then the client makes a request protected with a third security
context derived from ID Context = ID3 = R2 || R3, where R3 is a
random byte string generated by the client. The request includes
R2 || R3 wrapped in a CBOR bstr as 'kid context'.
4. If the server receives a request with 'kid context' containing a
CBOR bstr wrapping ID3, where the first part of ID3 is identical
to an R2 sent in a previous response #1 which it has not received
before, then the server derives a third security context with ID
Context = ID3. The server MUST NOT accept replayed request #2
messages. If the server can verify the request (see Section 8.2)
with the third security context, then the server marks the third
security context to be used with this client and removes all
instances of R2 associated to this security context from the
cache. This security context replaces the previous security
context with the client, and the first and the second security
contexts are deleted. The server responds using the same
security context as in the request.
5. If the client receives a response to the request with the third
security context and the response verifies (see Section 8.4),
then the client marks the third security context to be used with
this server. This security context replaces the previous
security context with the server, and the first and second
security contexts are deleted.
If verification fails in any step, the endpoint stops processing that
message.
The length of the nonces R1, R2, and R3 is application specific. The
application needs to set the length of each nonce such the
probability of its value being repeated is negligible; typically, at
least 8 bytes long. Since R2 may be generated as the result of a
replayed request #1, the probability for collision of R2s is impacted
by the birthday paradox. For example, setting the length of R2 to 8
bytes results in an average collision after 2^32 response #1
messages, which should not be an issue for a constrained server
handling on the order of one request per second.
Request #2 can be an ordinary request. The server performs the
action of the request and sends response #2 after having successfully
completed the security context related operations in step 4. The
client acts on response #2 after having successfully completed step
5.
When sending request #2, the client is assured that the Sender Key
(derived with the random value R3) has never been used before. When
receiving response #2, the client is assured that the response
(protected with a key derived from the random value R3 and the Master
Secret) was created by the server in response to request #2.
Similarly, when receiving request #2, the server is assured that the
request (protected with a key derived from the random value R2 and
the Master Secret) was created by the client in response to response
#1. When sending response #2, the server is assured that the Sender
Key (derived with the random value R2) has never been used before.
Implementation and denial-of-service considerations are made in
Appendix B.2.1 and Appendix B.2.2.
B.2.1. Implementation Considerations
This section add some implemention considerations to the protocol
described in the previous section.
The server may only have space for a few security contexts, or only
be able to handle a few protocol runs in parallel. The server may
legitimately receive multiple request #1 messages using the same non-
mutable security context, e.g. due to packet loss. Replays of old
request #1 messages could be difficult for the server to distinguish
from legitimate. The server needs to handle the case when the
maximum number of cached R2s is reached. If the server receives a
request #1 and is not capable of executing it then it may respond
with an unprotected 5.03 (Service Unavailable). The server may clear
up state from protocol runs which never complete, e.g. set a timer
when caching R2, and remove R2 and the associated security contexts
from the cache at timeout. Additionally, state information can be
flushed at reboot.
As an alternative to caching R2, the server could generate R2 in such
a way that it can be sent (in response #1) and verified (at reception
of request #2) as the value of R2 it had generated. Such a procedure
MUST NOT lead to the server accepting replayed request #2 messages.
One construction described in the following is based on using a
secret random HMAC key K_HMAC per set of non-mutable security context
parameters associated to a client. This construction allows the
server to handle verification of R2 in response #2 at the cost of
storing the K_HMAC keys and a slightly larger message overhead in
response #1. Steps below refer to modifications to Appendix B.2:
o In step 2, R2 is generated in the following way. First, the
server generates a random K_HMAC (unless it already has one
associated with the security context), then it sets R2 = S2 ||
HMAC(K_HMAC, S2) where S2 is a random byte string, and the HMAC is
truncated to 8 bytes. K_HMAC may have an expiration time, after
which it is erased. Note that neither R2, S2 nor the derived
first and second security contexts need to be cached.
o In step 4, instead of verifying that R2 coincides with a cached
value, the server looks up the associated K_HMAC and verifies the
truncated HMAC, and the processing continues accordingly depending
on verification success or failure. K_HMAC is used until a run of
the protocol is completed (after verification of request #2), or
until it expires (whatever comes first), after which K_HMAC is
erased. (The latter corresponds to removing the cached values of
R2 in step 4 of Appendix B.2, and makes the server reject replays
of request #2.)
The length of S2 is application specific and the probability for
collision of S2s is impacted by the birthday paradox. For example,
setting the length of S2 to 8 bytes results in an average collision
after 2^32 response #1 messages, which should not be an issue for a
constrained server handling on the order of one request per second.
Two endpoints sharing a security context may accidently initiate two
instances of the protocol at the same time, each in the role of
client, e.g. after a power outage affecting both endpoints. Such a
race condition could potentially lead to both protocols failing, and
both endpoints repeatedly re-initiating the protocol without
converging. Both endpoints can detect this situation and it can be
handled in different ways. The requests could potentially be more
spread out in time, for example by only initiating this protocol when
the endpoint actually needs to make a request, potentially adding a
random delay before requests immediately after reboot or if such
parallel protocol runs are detected.
B.2.2. Attack Considerations
An on-path attacker may inject a message causing the endpoint to
process verification of the message. A message crafted without
access to the Master Secret will fail to verify.
Replaying an old request with a value of 'kid_context' which the
server does not recognize could trigger the protocol. This causes
the server to generate the first and second security context and send
a response. But if the client did not expect a response it will be
discarded. This may still result in a denial-of-service attack
against the server e.g. because of not being able to manage the state
associated with many parallel protocol runs, and it may prevent
legitimate client requests. Implementation alternatives with less
data caching per request #1 message are favorable in this respect,
see Appendix B.2.1.
Replaying response #1 in response to some request other than request
#1 will fail to verify, since response #1 is associated to request
#1, through the dependencies of ID Contexts and the Partial IV of
request #1 included in the external_aad of response #1.
If request #2 has already been well received, then the server has a
valid security context, so a replay of request #2 is handled by the
normal replay protection mechanism. Similarly if response #2 has
already been received, a replay of response #2 to some other request
from the client will fail by the normal verification of binding of
response to request.
Appendix C. Test Vectors Appendix C. Test Vectors
This appendix includes the test vectors for different examples of This appendix includes the test vectors for different examples of
CoAP messages using OSCORE. Given a set of inputs, OSCORE defines CoAP messages using OSCORE. Given a set of inputs, OSCORE defines
how to set up the Security Context in both the client and the server. how to set up the Security Context in both the client and the server.
Note that in Appendix C.4 and all following test vectors the Token Note that in Appendix C.4 and all following test vectors the Token
and the Message ID of the OSCORE-protected CoAP messages are set to and the Message ID of the OSCORE-protected CoAP messages are set to
the same value of the unprotected CoAP message, to help the reader the same value of the unprotected CoAP message, to help the reader
skipping to change at page 68, line 4 skipping to change at page 72, line 50
o sender nonce: 0x4622d4dd6d944168eefb54987c (13 bytes) o sender nonce: 0x4622d4dd6d944168eefb54987c (13 bytes)
o recipient nonce: 0x4722d4dd6d944169eefb54987c (13 bytes) o recipient nonce: 0x4722d4dd6d944169eefb54987c (13 bytes)
C.1.2. Server C.1.2. Server
Inputs: Inputs:
o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes)
o Master Salt: 0x9e7ca92223786340 (8 bytes)
o Master Salt: 0x9e7ca92223786340 (8 bytes)
o Sender ID: 0x01 (1 byte) o Sender ID: 0x01 (1 byte)
o Recipient ID: 0x (0 byte) o Recipient ID: 0x (0 byte)
From the previous parameters, From the previous parameters,
o info (for Sender Key): 0x854101f60a634b657910 (10 bytes) o info (for Sender Key): 0x854101f60a634b657910 (10 bytes)
o info (for Recipient Key): 0x8540f60a634b657910 (9 bytes) o info (for Recipient Key): 0x8540f60a634b657910 (9 bytes)
skipping to change at page 69, line 4 skipping to change at page 73, line 49
o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes)
o Sender ID: 0x00 (1 byte) o Sender ID: 0x00 (1 byte)
o Recipient ID: 0x01 (1 byte) o Recipient ID: 0x01 (1 byte)
From the previous parameters, From the previous parameters,
o info (for Sender Key): 0x854100f60a634b657910 (10 bytes) o info (for Sender Key): 0x854100f60a634b657910 (10 bytes)
o info (for Recipient Key): 0x854101f60a634b657910 (10 bytes)
o info (for Recipient Key): 0x854101f60a634b657910 (10 bytes)
o info (for Common IV): 0x8540f60a6249560d (8 bytes) o info (for Common IV): 0x8540f60a6249560d (8 bytes)
Outputs: Outputs:
o Sender Key: 0x321b26943253c7ffb6003b0b64d74041 (16 bytes) o Sender Key: 0x321b26943253c7ffb6003b0b64d74041 (16 bytes)
o Recipient Key: 0xe57b5635815177cd679ab4bcec9d7dda (16 bytes) o Recipient Key: 0xe57b5635815177cd679ab4bcec9d7dda (16 bytes)
o Common IV: 0xbe35ae297d2dace910c52e99f9 (13 bytes) o Common IV: 0xbe35ae297d2dace910c52e99f9 (13 bytes)
skipping to change at page 74, line 12 skipping to change at page 79, line 9
From there: From there:
o Protected CoAP request (OSCORE message): 0x440271c30000b932396c6f6 o Protected CoAP request (OSCORE message): 0x440271c30000b932396c6f6
3616c686f737463091400ff4ed339a5a379b0b8bc731fffb0 (36 bytes) 3616c686f737463091400ff4ed339a5a379b0b8bc731fffb0 (36 bytes)
C.6. Test Vector 6: OSCORE Request, Client C.6. Test Vector 6: OSCORE Request, Client
This section contains a test vector for an OSCORE protected CoAP GET This section contains a test vector for an OSCORE protected CoAP GET
request for an application that sets the ID Context and requires it request for an application that sets the ID Context and requires it
to be sent in the request, so kid context is present in the protected to be sent in the request, so 'kid context' is present in the
message. This test vector uses the security context derived in protected message. This test vector uses the security context
Appendix C.3. The unprotected request only contains the Uri-Path and derived in Appendix C.3. The unprotected request only contains the
Uri-Host options. Uri-Path and Uri-Host options.
Unprotected CoAP request: Unprotected CoAP request:
0x44012f8eef9bbf7a396c6f63616c686f737483747631 (22 bytes) 0x44012f8eef9bbf7a396c6f63616c686f737483747631 (22 bytes)
Common Context: Common Context:
o AEAD Algorithm: 10 (AES-CCM-16-64-128) o AEAD Algorithm: 10 (AES-CCM-16-64-128)
o Key Derivation Function: HKDF SHA-256 o Key Derivation Function: HKDF SHA-256
skipping to change at page 75, line 4 skipping to change at page 79, line 50
o kid context: 0x37cbf3210017a2d3 (8 bytes) o kid context: 0x37cbf3210017a2d3 (8 bytes)
o external_aad: 0x8501810a40411440 (8 bytes) o external_aad: 0x8501810a40411440 (8 bytes)
o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes) o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes)
o plaintext: 0x01b3747631 (5 bytes) o plaintext: 0x01b3747631 (5 bytes)
o encryption key: 0xaf2a1300a5e95788b356336eeecd2b92 (16 bytes) o encryption key: 0xaf2a1300a5e95788b356336eeecd2b92 (16 bytes)
o nonce: 0x2ca58fb85ff1b81c0b7181b84a (13 bytes)
o nonce: 0x2ca58fb85ff1b81c0b7181b84a (13 bytes)
From the previous parameter, the following is derived: From the previous parameter, the following is derived:
o OSCORE option value: 0x19140837cbf3210017a2d3 (11 bytes) o OSCORE option value: 0x19140837cbf3210017a2d3 (11 bytes)
o ciphertext: 0x72cd7273fd331ac45cffbe55c3 (13 bytes) o ciphertext: 0x72cd7273fd331ac45cffbe55c3 (13 bytes)
From there: From there:
o Protected CoAP request (OSCORE message): o Protected CoAP request (OSCORE message):
0x44022f8eef9bbf7a396c6f63616c686f73746b19140837cbf3210017a2d3ff 0x44022f8eef9bbf7a396c6f63616c686f73746b19140837cbf3210017a2d3ff
72cd7273fd331ac45cffbe55c3 (44 bytes) 72cd7273fd331ac45cffbe55c3 (44 bytes)
C.7. Test Vector 7: OSCORE Response, Server C.7. Test Vector 7: OSCORE Response, Server
This section contains a test vector for an OSCORE protected 2.05 This section contains a test vector for an OSCORE protected 2.05
Content response to the request in Appendix C.4. The unprotected (Content) response to the request in Appendix C.4. The unprotected
response has payload "Hello World!" and no options. The protected response has payload "Hello World!" and no options. The protected
response does not contain a kid nor a Partial IV. Note that some response does not contain a 'kid' nor a Partial IV. Note that some
parameters are derived from the request. parameters are derived from the request.
Unprotected CoAP response: Unprotected CoAP response:
0x64455d1f00003974ff48656c6c6f20576f726c6421 (21 bytes) 0x64455d1f00003974ff48656c6c6f20576f726c6421 (21 bytes)
Common Context: Common Context:
o AEAD Algorithm: 10 (AES-CCM-16-64-128) o AEAD Algorithm: 10 (AES-CCM-16-64-128)
o Key Derivation Function: HKDF SHA-256 o Key Derivation Function: HKDF SHA-256
skipping to change at page 76, line 4 skipping to change at page 80, line 50
o Sender Sequence Number: 0 o Sender Sequence Number: 0
The following COSE and cryptographic parameters are derived: The following COSE and cryptographic parameters are derived:
o external_aad: 0x8501810a40411440 (8 bytes) o external_aad: 0x8501810a40411440 (8 bytes)
o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes) o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes)
o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes) o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes)
o encryption key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes)
o encryption key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes)
o nonce: 0x4622d4dd6d944168eefb549868 (13 bytes) o nonce: 0x4622d4dd6d944168eefb549868 (13 bytes)
From the previous parameter, the following is derived: From the previous parameter, the following is derived:
o OSCORE option value: 0x (0 bytes) o OSCORE option value: 0x (0 bytes)
o ciphertext: 0xdbaad1e9a7e7b2a813d3c31524378303cdafae119106 (22 o ciphertext: 0xdbaad1e9a7e7b2a813d3c31524378303cdafae119106 (22
bytes) bytes)
From there: From there:
o Protected CoAP response (OSCORE message): o Protected CoAP response (OSCORE message):
0x64445d1f0000397490ffdbaad1e9a7e7b2a813d3c31524378303cdafae119106 0x64445d1f0000397490ffdbaad1e9a7e7b2a813d3c31524378303cdafae119106
(32 bytes) (32 bytes)
C.8. Test Vector 8: OSCORE Response with Partial IV, Server C.8. Test Vector 8: OSCORE Response with Partial IV, Server
This section contains a test vector for an OSCORE protected 2.05 This section contains a test vector for an OSCORE protected 2.05
Content response to the request in Appendix C.4. The unprotected (Content) response to the request in Appendix C.4. The unprotected
response has payload "Hello World!" and no options. The protected response has payload "Hello World!" and no options. The protected
response does not contain a kid, but contains a Partial IV. Note response does not contain a 'kid', but contains a Partial IV. Note
that some parameters are derived from the request. that some parameters are derived from the request.
Unprotected CoAP response: Unprotected CoAP response:
0x64455d1f00003974ff48656c6c6f20576f726c6421 (21 bytes) 0x64455d1f00003974ff48656c6c6f20576f726c6421 (21 bytes)
Common Context: Common Context:
o AEAD Algorithm: 10 (AES-CCM-16-64-128) o AEAD Algorithm: 10 (AES-CCM-16-64-128)
o Key Derivation Function: HKDF SHA-256 o Key Derivation Function: HKDF SHA-256
skipping to change at page 77, line 4 skipping to change at page 81, line 49
o Sender ID: 0x01 (1 byte) o Sender ID: 0x01 (1 byte)
o Sender Key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes) o Sender Key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes)
o Sender Sequence Number: 0 o Sender Sequence Number: 0
The following COSE and cryptographic parameters are derived: The following COSE and cryptographic parameters are derived:
o Partial IV: 0x00 (1 byte) o Partial IV: 0x00 (1 byte)
o external_aad: 0x8501810a40411440 (8 bytes)
o external_aad: 0x8501810a40411440 (8 bytes)
o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes) o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes)
o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes) o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes)
o encryption key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes) o encryption key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes)
o nonce: 0x4722d4dd6d944169eefb54987c (13 bytes) o nonce: 0x4722d4dd6d944169eefb54987c (13 bytes)
From the previous parameter, the following is derived: From the previous parameter, the following is derived:
skipping to change at page 77, line 28 skipping to change at page 82, line 26
o ciphertext: 0x4d4c13669384b67354b2b6175ff4b8658c666a6cf88e (22 o ciphertext: 0x4d4c13669384b67354b2b6175ff4b8658c666a6cf88e (22
bytes) bytes)
From there: From there:
o Protected CoAP response (OSCORE message): 0x64445d1f00003974920100 o Protected CoAP response (OSCORE message): 0x64445d1f00003974920100
ff4d4c13669384b67354b2b6175ff4b8658c666a6cf88e (34 bytes) ff4d4c13669384b67354b2b6175ff4b8658c666a6cf88e (34 bytes)
Appendix D. Overview of Security Properties Appendix D. Overview of Security Properties
D.1. Supporting Proxy Operations D.1. Threat Model
This section describes the threat model using the terms of [RFC3552].
It is assumed that the endpoints running OSCORE have not themselves
been compromised. The attacker is assumed to have control of the
CoAP channel over which the endpoints communicate, including
intermediary nodes. The attacker is capable of launching any passive
or active, on-path or off-path attacks; including eavesdropping,
traffic analysis, spoofing, insertion, modification, deletion, delay,
replay, man-in-the-middle, and denial-of-service attacks. This means
that the attacker can read any CoAP message on the network and
undetectably remove, change, or inject forged messages onto the wire.
OSCORE targets the protection of the CoAP request/response layer
(Section 2 of [RFC7252]) between the endpoints, including the CoAP
Payload, Code, Uri-Path/Uri-Query, and the other Class E option
instances (Section 4.1).
OSCORE does not protect the CoAP messaging layer (Section 2 of
[RFC7252]) or other lower layers involved in routing and transporting
the CoAP requests and responses.
Additionally, OSCORE does not protect Class U option instances
(Section 4.1), as these are used to support CoAP forward proxy
operations (see Section 5.7.2 of [RFC7252]). The supported proxies
(forwarding, cross-protocol e.g. CoAP to CoAP-mappable protocols
such as HTTP) must be able to change certain Class U options (by
instruction from the Client), resulting in the CoAP request being
redirected to the server. Changes caused by the proxy may result in
the request not reaching the server or reaching the wrong server.
For cross-protocol proxies, mappings are done on the Outer part of
the message so these protocols are essentially used as transport.
Manipulation of these options may thus impact whether the protected
message reaches or does not reach the destination endpoint.
Attacks on unprotected CoAP message fields generally causes denial-
of-service attacks which are out of scope of this document, more
details are given in Appendix D.5.
Attacks against the CoAP request-response layer are in scope. OSCORE
is intended to protect against eavesdropping, spoofing, insertion,
modification, deletion, replay, and man-in-the middle attacks.
OSCORE is susceptible to traffic analysis as discussed later in
Appendix D.
D.2. Supporting Proxy Operations
CoAP is designed to work with intermediaries reading and/or changing CoAP is designed to work with intermediaries reading and/or changing
CoAP message fields to perform supporting operations in constrained CoAP message fields to perform supporting operations in constrained
environments, e.g. forwarding and cross-protocol translations. environments, e.g. forwarding and cross-protocol translations.
Securing CoAP on transport layer protects the entire message between Securing CoAP on transport layer protects the entire message between
the endpoints in which case CoAP proxy operations are not possible. the endpoints in which case CoAP proxy operations are not possible.
In order to enable proxy operations, security on transport layer In order to enable proxy operations, security on transport layer
needs to be terminated at the proxy in which case the CoAP message in needs to be terminated at the proxy in which case the CoAP message in
its entirety is unprotected in the proxy. its entirety is unprotected in the proxy.
skipping to change at page 78, line 7 skipping to change at page 84, line 5
intended operations. intended operations.
By working at the CoAP layer, OSCORE enables different CoAP message By working at the CoAP layer, OSCORE enables different CoAP message
fields to be protected differently, which allows message fields fields to be protected differently, which allows message fields
required for proxy operations to be available to the proxy while required for proxy operations to be available to the proxy while
message fields intended for the other endpoint remain protected. In message fields intended for the other endpoint remain protected. In
the remainder of this section we analyze how OSCORE protects the the remainder of this section we analyze how OSCORE protects the
protected message fields and the consequences of message fields protected message fields and the consequences of message fields
intended for proxy operation being unprotected. intended for proxy operation being unprotected.
D.2. Protected Message Fields D.3. Protected Message Fields
Protected message fields are included in the Plaintext (Section 5.3) Protected message fields are included in the Plaintext (Section 5.3)
and the Additional Authenticated Data (Section 5.4) of the and the Additional Authenticated Data (Section 5.4) of the
COSE_Encrypt0 object and encrypted using an AEAD algorithm. COSE_Encrypt0 object and encrypted using an AEAD algorithm.
OSCORE depends on a pre-established random Master Secret OSCORE depends on a pre-established random Master Secret
(Section 12.3) used to derive encryption keys, and a construction for (Section 12.3) used to derive encryption keys, and a construction for
making (key, nonce) pairs unique (Appendix D.3). Assuming this is making (key, nonce) pairs unique (Appendix D.4). Assuming this is
true, and the keys are used for no more data than indicated in true, and the keys are used for no more data than indicated in
Section 7.2.1, OSCORE should provide the following guarantees: Section 7.2.1, OSCORE should provide the following guarantees:
o Confidentiality: An attacker should not be able to determine the o Confidentiality: An attacker should not be able to determine the
plaintext contents of a given OSCORE message or determine that plaintext contents of a given OSCORE message or determine that
different plaintexts are related (Section 5.3). different plaintexts are related (Section 5.3).
o Integrity: An attacker should not be able to craft a new OSCORE o Integrity: An attacker should not be able to craft a new OSCORE
message with protected message fields different from an existing message with protected message fields different from an existing
OSCORE message which will be accepted by the receiver. OSCORE message which will be accepted by the receiver.
skipping to change at page 78, line 39 skipping to change at page 84, line 37
o Non-replayability: An attacker should not be able to cause the o Non-replayability: An attacker should not be able to cause the
receiver to accept a message which it has previously received and receiver to accept a message which it has previously received and
accepted. accepted.
In the above, the attacker is anyone except the endpoints, e.g. a In the above, the attacker is anyone except the endpoints, e.g. a
compromised intermediary. Informally, OSCORE provides these compromised intermediary. Informally, OSCORE provides these
properties by AEAD-protecting the plaintext with a strong key and properties by AEAD-protecting the plaintext with a strong key and
uniqueness of (key, nonce) pairs. AEAD encryption [RFC5116] provides uniqueness of (key, nonce) pairs. AEAD encryption [RFC5116] provides
confidentiality and integrity for the data. Response-request binding confidentiality and integrity for the data. Response-request binding
is provided by including the kid and Partial IV of the request in the is provided by including the 'kid' and Partial IV of the request in
AAD of the response. Non-replayability of requests and notifications the AAD of the response. Non-replayability of requests and
is provided by using unique (key, nonce) pairs and a replay notifications is provided by using unique (key, nonce) pairs and a
protection mechanism (application dependent, see Section 7.4). replay protection mechanism (application dependent, see Section 7.4).
OSCORE is susceptible to a variety of traffic analysis attacks based OSCORE is susceptible to a variety of traffic analysis attacks based
on observing the length and timing of encrypted packets. OSCORE does on observing the length and timing of encrypted packets. OSCORE does
not provide any specific defenses against this form of attack but the not provide any specific defenses against this form of attack but the
application may use a padding mechanism to prevent an attacker from application may use a padding mechanism to prevent an attacker from
directly determine the length of the padding. However, information directly determine the length of the padding. However, information
about padding may still be revealed by side-channel attacks observing about padding may still be revealed by side-channel attacks observing
differences in timing. differences in timing.
D.3. Uniqueness of (key, nonce) D.4. Uniqueness of (key, nonce)
In this section we show that (key, nonce) pairs are unique as long as In this section we show that (key, nonce) pairs are unique as long as
the requirements in Sections 3.3 and 7.2.1 are followed. the requirements in Sections 3.3 and 7.2.1 are followed.
Fix a Common Context (Section 3.1) and an endpoint, called the Fix a Common Context (Section 3.1) and an endpoint, called the
encrypting endpoint. An endpoint may alternate between client and encrypting endpoint. An endpoint may alternate between client and
server roles, but each endpoint always encrypts with the Sender Key server roles, but each endpoint always encrypts with the Sender Key
of its Sender Context. Sender Keys are (stochastically) unique since of its Sender Context. Sender Keys are (stochastically) unique since
they are derived with HKDF using unique Sender IDs, so messages they are derived with HKDF using unique Sender IDs, so messages
encrypted by different endpoints use different keys. It remains to encrypted by different endpoints use different keys. It remains to
skipping to change at page 80, line 5 skipping to change at page 86, line 5
o PIV = Partial IV of the request o PIV = Partial IV of the request
Since the Sender IDs are unique, ID_PIV is different from the Sender Since the Sender IDs are unique, ID_PIV is different from the Sender
ID of the encrypting endpoint. Therefore, the nonces in case B are ID of the encrypting endpoint. Therefore, the nonces in case B are
different compared to nonces in case A, where the encrypting endpoint different compared to nonces in case A, where the encrypting endpoint
generated the Partial IV. Since the Partial IV of the request is generated the Partial IV. Since the Partial IV of the request is
verified for replay (Section 7.4) associated to this Recipient verified for replay (Section 7.4) associated to this Recipient
Context, PIV is unique for this ID_PIV, which makes all nonces in Context, PIV is unique for this ID_PIV, which makes all nonces in
case B distinct. case B distinct.
D.4. Unprotected Message Fields D.5. Unprotected Message Fields
This section lists and discusses issues with unprotected message This sections analyses attacks on message fields which are not
fields. protected by OSCORE according to the threat model Appendix D.1.
D.4.1. CoAP Header Fields D.5.1. CoAP Header Fields
o Version. The CoAP version [RFC7252] is not expected to be o Version. The CoAP version [RFC7252] is not expected to be
sensitive to disclose. Currently there is only one CoAP version sensitive to disclose. Currently there is only one CoAP version
defined. A change of this parameter is potentially a denial-of- defined. A change of this parameter is potentially a denial-of-
service attack. Future versions of CoAP need to analyze attacks service attack. Future versions of CoAP need to analyze attacks
to OSCORE protected messages due to an adversary changing the CoAP to OSCORE protected messages due to an adversary changing the CoAP
version. version.
o Token/Token Length. The Token field is a client-local identifier o Token/Token Length. The Token field is a client-local identifier
for differentiating between concurrent requests [RFC7252]. CoAP for differentiating between concurrent requests [RFC7252]. CoAP
skipping to change at page 80, line 32 skipping to change at page 86, line 32
between hops. An eavesdropper reading the Token can match between hops. An eavesdropper reading the Token can match
requests to responses which can be used in traffic analysis. In requests to responses which can be used in traffic analysis. In
particular this is true for notifications, where multiple particular this is true for notifications, where multiple
responses are matched with one request. Modifications of Token responses are matched with one request. Modifications of Token
and Token Length by an on-path attacker may become a denial-of- and Token Length by an on-path attacker may become a denial-of-
service attack, since it may prevent the client to identify to service attack, since it may prevent the client to identify to
which request the response belongs or to find the correct which request the response belongs or to find the correct
information to verify integrity of the response. information to verify integrity of the response.
o Code. The Outer CoAP Code of an OSCORE message is POST or FETCH o Code. The Outer CoAP Code of an OSCORE message is POST or FETCH
for requests with corresponding response codes. The use of FETCH for requests with corresponding response codes. An endpoint
reveals no more than what is revealed by the Outer Observe option. receiving the message discards the Outer CoAP Code and uses the
Changing the Outer Code may be a denial-of-service attack by Inner CoAP Code instead (see Section 4.2). Hence, modifications
causing errors in the proxy processing. from attackers to the Outer Code do not impact the receiving
endpoint. However, changing the Outer Code from FETCH to a Code
value for a method that does not work with Observe (such as POST)
may, depending on proxy implementation since Observe is undefined
for several Codes, cause the proxy to not forward notifications,
which is a denial-of-service attack. The use of FETCH rather than
POST reveals no more than what is revealed by the presence of the
Outer Observe option.
o Type/Message ID. The Type/Message ID fields [RFC7252] reveal o Type/Message ID. The Type/Message ID fields [RFC7252] reveal
information about the UDP transport binding, e.g. an eavesdropper information about the UDP transport binding, e.g. an eavesdropper
reading the Type or Message ID gain information about how UDP reading the Type or Message ID gain information about how UDP
messages are related to each other. CoAP proxies are allowed to messages are related to each other. CoAP proxies are allowed to
change Type and Message ID. These message fields are not present change Type and Message ID. These message fields are not present
in CoAP over TCP [RFC8323], and does not impact the request/ in CoAP over TCP [RFC8323], and does not impact the request/
response message. A change of these fields in a UDP hop is a response message. A change of these fields in a UDP hop is a
denial-of-service attack. By sending an ACK, an attacker can make denial-of-service attack. By sending an ACK, an attacker can make
the endpoint believe that the other endpoint received the previous the endpoint believe that it does not need to retransmit the
message. By sending a RST, an attacker may be able to cancel an previous message. By sending a RST, an attacker may be able to
observation, make one endpoint believe the other endpoint is cancel an observation. By changing a NON to a CON, the attacker
alive, or make one endpoint endpoint believe that the other can cause the receiving endpoint to ACK messages for which no ACK
endpoint is missing some context. By changing a NON to a CON, the was requested.
attacker can cause the receiving endpoint to respond to messages
for which no response was requested.
o Length. This field contain the length of the message [RFC8323] o Length. This field contain the length of the message [RFC8323]
which may be used for traffic analysis. These message fields are which may be used for traffic analysis. These message fields are
not present in CoAP over UDP, and does not impact the request/ not present in CoAP over UDP, and does not impact the request/
response message. A change of Length is a denial-of-service response message. A change of Length is a denial-of-service
attack similar to changing TCP header fields. attack similar to changing TCP header fields.
D.4.2. CoAP Options D.5.2. CoAP Options
o Max-Age. The Outer Max-Age is set to zero to avoid unnecessary o Max-Age. The Outer Max-Age is set to zero to avoid unnecessary
caching of OSCORE error responses. Changing this value thus may caching of OSCORE error responses. Changing this value thus may
cause unnecessary caching. No additional information is carried cause unnecessary caching. No additional information is carried
with this option. with this option.
o Proxy-Uri/Proxy-Scheme. These options are used in forward proxy o Proxy-Uri/Proxy-Scheme. These options are used in CoAP forward
deployments. With OSCORE, the Proxy-Uri option does not contain proxy deployments. With OSCORE, the Proxy-Uri option does not
the Uri-Path/Uri-Query parts of the URI. The other parts of contain the Uri-Path/Uri-Query parts of the URI. The other parts
Proxy-Uri cannot be protected since they are allowed to be changed of Proxy-Uri cannot be protected because forward proxies need to
by a forward proxy. The server can verify what scheme is used in change them in order to perform their functions. The server can
the last hop, but not what was requested by the client or what was verify what scheme is used in the last hop, but not what was
used in previous hops. requested by the client or what was used in previous hops.
o Uri-Host/Uri-Port. In forward proxy deployments, the Uri-Host/ o Uri-Host/Uri-Port. In forward proxy deployments, the Uri-Host/
Uri-Port may be changed by an adversary, and the application needs Uri-Port may be changed by an adversary, and the application needs
to handle the consequences of that (see Section 4.1.3.2). The to handle the consequences of that (see Section 4.1.3.2). The
Uri-Host may either be omitted, reveal information equivalent to Uri-Host may either be omitted, reveal information equivalent to
that of the IP address or more privacy-sensitive information, that of the IP address or more privacy-sensitive information,
which is discouraged. which is discouraged.
o Observe. The Outer Observe option is intended for a proxy to o Observe. The Outer Observe option is intended for a proxy to
support forwarding of Observe messages, but is ignored by the support forwarding of Observe messages, but is ignored by the
endpoints since the Inner Observe determines the processing in the endpoints since the Inner Observe determines the processing in the
endpoints. Since the Partial IV provides absolute ordering of endpoints. Since the Partial IV provides absolute ordering of
notifications it is not possible for an intermediary to spoof notifications it is not possible for an intermediary to spoof
reordering (see Section 4.1.3.5). The absence of Partial IV, reordering (see Section 4.1.3.5). The absence of Partial IV,
since only allowed for the first notification, does not prevent since only allowed for the first notification, does not prevent
correct ordering of notifications. The size and distributions of correct ordering of notifications. The size and distributions of
notifications over time may reveal information about the content notifications over time may reveal information about the content
or nature of the notifications. Cancellations (Section 4.1.3.5.1) or nature of the notifications. Cancellations (Section 4.1.3.5.1)
are not bound to the corresponding registrations in the same way are not bound to the corresponding registrations in the same way
responses are bound to requests in OSCORE (see Appendix D.2), but responses are bound to requests in OSCORE (see Appendix D.3), but
that does not open up for attacks based on mismatched that does not open up for attacks based on mismatched
cancellations, since for cancellations to be accepted, all options cancellations, since for cancellations to be accepted, all options
in the decrypted message except for ETag Options MUST be the same in the decrypted message except for ETag Options MUST be the same
(see Section 4.1.3.5). (see Section 4.1.3.5).
o Block1/Block2/Size1/Size2. The Outer Block options enables o Block1/Block2/Size1/Size2. The Outer Block options enables
fragmentation of OSCORE messages in addition to segmentation fragmentation of OSCORE messages in addition to segmentation
performed by the Inner Block options. The presence of these performed by the Inner Block options. The presence of these
options indicates a large message being sent and the message size options indicates a large message being sent and the message size
can be estimated and used for traffic analysis. Manipulating can be estimated and used for traffic analysis. Manipulating
skipping to change at page 82, line 27 skipping to change at page 88, line 33
denial-of-service attack against the proxy operations, but since denial-of-service attack against the proxy operations, but since
the option has an Inner value its use can be securely agreed the option has an Inner value its use can be securely agreed
between the endpoints. The presence of this option is not between the endpoints. The presence of this option is not
expected to reveal any sensitive information about the message expected to reveal any sensitive information about the message
exchange. exchange.
o OSCORE. The OSCORE option contains information about the o OSCORE. The OSCORE option contains information about the
compressed COSE header. Changing this field may cause OSCORE compressed COSE header. Changing this field may cause OSCORE
verification to fail. verification to fail.
D.4.3. Error and Signaling Messages D.5.3. Error and Signaling Messages
Error messages occurring during CoAP processing are protected end-to- Error messages occurring during CoAP processing are protected end-to-
end. Error messages occurring during OSCORE processing are not end. Error messages occurring during OSCORE processing are not
always possible to protect, e.g. if the receiving endpoint cannot always possible to protect, e.g. if the receiving endpoint cannot
locate the right security context. For this setting, unprotected locate the right security context. For this setting, unprotected
error messages are allowed as specified to prevent extensive error messages are allowed as specified to prevent extensive
retransmissions. Those error messages can be spoofed or manipulated, retransmissions. Those error messages can be spoofed or manipulated,
which is a potential denial-of-service attack. which is a potential denial-of-service attack.
This document specifies OPTIONAL error codes and specific diagnostic
payloads for OSCORE processing error messages. Such messages might
reveal information about how many and which security contexts exist
on the server. Servers MAY want to omit the diagnostic payload of
error messages, use the same error code for all errors, or avoid
responding altogether in case of OSCORE processing errors, if that is
a security concern for the application. Moreover, clients MUST NOT
rely on the error code or the diagnostic payload to trigger specific
actions, as these errors are unprotected and can be spoofed or
manipulated.
Signaling messages used in CoAP over TCP [RFC8323] are intended to be Signaling messages used in CoAP over TCP [RFC8323] are intended to be
hop-by-hop; spoofing signaling messages can be used as a denial-of- hop-by-hop; spoofing signaling messages can be used as a denial-of-
service attack of a TCP connection. service attack of a TCP connection.
D.4.4. HTTP Message Fields D.5.4. HTTP Message Fields
In contrast to CoAP, where OSCORE does not protect header fields to In contrast to CoAP, where OSCORE does not protect header fields to
enable CoAP-CoAP proxy operations, the use of OSCORE with HTTP is enable CoAP-CoAP proxy operations, the use of OSCORE with HTTP is
restricted to transporting a protected CoAP message over an HTTP hop. restricted to transporting a protected CoAP message over an HTTP hop.
Any unprotected HTTP message fields may reveal information about the Any unprotected HTTP message fields may reveal information about the
transport of the OSCORE message and enable various denial-of-service transport of the OSCORE message and enable various denial-of-service
attacks. It is recommended to additionally use TLS [RFC8446] for attacks. It is RECOMMENDED to additionally use TLS [RFC8446] for
HTTP hops, which enables encryption and integrity protection of HTTP hops, which enables encryption and integrity protection of
headers, but still leaves some information for traffic analysis. headers, but still leaves some information for traffic analysis.
Appendix E. CDDL Summary 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
skipping to change at page 83, line 42 skipping to change at page 90, line 11
enclosed by square brackets "[" and "]". Arrays described by an enclosed by square brackets "[" and "]". Arrays described by an
array description contain elements that correspond one-to-one to array description contain elements that correspond one-to-one to
the sequence of entries given. Each entry of an array description the sequence of entries given. Each entry of an array description
is of the form "name : type", where "name" is the name given to is of the form "name : type", where "name" is the name given to
the entry and "type" is the type of the array element the entry and "type" is the type of the array element
corresponding to this entry. corresponding to this entry.
Acknowledgments Acknowledgments
The following individuals provided input to this document: Christian The following individuals provided input to this document: Christian
Amsuess, Tobias Andersson, Carsten Bormann, Joakim Brorsson, Esko Amsuess, Tobias Andersson, Carsten Bormann, Joakim Brorsson, Ben
Dijk, Thomas Fossati, Martin Gunnarsson, Klaus Hartke, Michael Campbell, Esko Dijk, Jaro Fietz, Thomas Fossati, Martin Gunnarsson,
Richardson, Jim Schaad, Peter van der Stok, Dave Thaler, Marco Klaus Hartke, Mirja Kuehlewind, Kathleen Moriarty, Eric Rescorla,
Tiloca, William Vignat, and Malisa Vucinic. Michael Richardson, Adam Roach, Jim Schaad, Peter van der Stok, Dave
Thaler, Martin Thomson, Marco Tiloca, William Vignat, and Malisa
Vucinic.
Ludwig Seitz and Goeran Selander worked on this document as part of Ludwig Seitz and Goeran Selander worked on this document as part of
the CelticPlus project CyberWI, with funding from Vinnova. the CelticPlus project CyberWI, with funding from Vinnova.
Authors' Addresses Authors' Addresses
Goeran Selander Goeran Selander
Ericsson AB Ericsson AB
Email: goran.selander@ericsson.com Email: goran.selander@ericsson.com
 End of changes. 176 change blocks. 
418 lines changed or deleted 775 lines changed or added

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