draft-ietf-core-object-security-11.txt   draft-ietf-core-object-security-12.txt 
CoRE Working Group G. Selander CoRE Working Group G. Selander
Internet-Draft J. Mattsson Internet-Draft J. Mattsson
Intended status: Standards Track F. Palombini Intended status: Standards Track F. Palombini
Expires: September 20, 2018 Ericsson AB Expires: October 1, 2018 Ericsson AB
L. Seitz L. Seitz
RISE SICS RISE SICS
March 19, 2018 March 30, 2018
Object Security for Constrained RESTful Environments (OSCORE) Object Security for Constrained RESTful Environments (OSCORE)
draft-ietf-core-object-security-11 draft-ietf-core-object-security-12
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
skipping to change at page 1, line 40 skipping to change at page 1, line 40
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 September 20, 2018. This Internet-Draft will expire on October 1, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6
2. The CoAP Object-Security Option . . . . . . . . . . . . . . . 6 2. The OSCORE Option . . . . . . . . . . . . . . . . . . . . . . 7
3. The Security Context . . . . . . . . . . . . . . . . . . . . 7 3. The Security Context . . . . . . . . . . . . . . . . . . . . 7
3.1. Security Context Definition . . . . . . . . . . . . . . . 7 3.1. Security Context Definition . . . . . . . . . . . . . . . 7
3.2. Establishment of Security Context Parameters . . . . . . 9 3.2. Establishment of Security Context Parameters . . . . . . 10
3.3. Requirements on the Security Context Parameters . . . . . 11 3.3. Requirements on the Security Context Parameters . . . . . 12
4. Protected Message Fields . . . . . . . . . . . . . . . . . . 12 4. Protected Message Fields . . . . . . . . . . . . . . . . . . 12
4.1. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 13 4.1. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 13
4.2. CoAP Header Fields and Payload . . . . . . . . . . . . . 20 4.2. CoAP Header Fields and Payload . . . . . . . . . . . . . 20
4.3. Signaling Messages . . . . . . . . . . . . . . . . . . . 21 4.3. Signaling Messages . . . . . . . . . . . . . . . . . . . 21
5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 22 5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 22
5.1. Kid Context . . . . . . . . . . . . . . . . . . . . . . . 23 5.1. Kid Context . . . . . . . . . . . . . . . . . . . . . . . 23
5.2. Nonce . . . . . . . . . . . . . . . . . . . . . . . . . . 24 5.2. Nonce . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.3. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 24 5.3. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 25
5.4. Additional Authenticated Data . . . . . . . . . . . . . . 25 5.4. Additional Authenticated Data . . . . . . . . . . . . . . 26
6. OSCORE Header Compression . . . . . . . . . . . . . . . . . . 26 6. OSCORE Header Compression . . . . . . . . . . . . . . . . . . 26
6.1. Encoding of the Object-Security Value . . . . . . . . . . 26 6.1. Encoding of the OSCORE Option Value . . . . . . . . . . . 27
6.2. Encoding of the OSCORE Payload . . . . . . . . . . . . . 28 6.2. Encoding of the OSCORE Payload . . . . . . . . . . . . . 28
6.3. Examples of Compressed COSE Objects . . . . . . . . . . . 28 6.3. Examples of Compressed COSE Objects . . . . . . . . . . . 28
7. Sequence Numbers, Replay, Message Binding, and Freshness . . 30 7. Message Binding, Sequence Numbers, Freshness and Replay
7.1. Message Binding . . . . . . . . . . . . . . . . . . . . . 30 Protection . . . . . . . . . . . . . . . . . . . . . . . . . 31
7.2. AEAD Nonce Uniqueness . . . . . . . . . . . . . . . . . . 30 7.1. Message Binding . . . . . . . . . . . . . . . . . . . . . 31
7.2. Sequence Numbers . . . . . . . . . . . . . . . . . . . . 31
7.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 31 7.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 31
7.4. Replay Protection . . . . . . . . . . . . . . . . . . . . 31 7.4. Replay Protection . . . . . . . . . . . . . . . . . . . . 32
7.5. Losing Part of the Context State . . . . . . . . . . . . 32 7.5. Losing Part of the Context State . . . . . . . . . . . . 32
8. Processing . . . . . . . . . . . . . . . . . . . . . . . . . 33 8. Processing . . . . . . . . . . . . . . . . . . . . . . . . . 34
8.1. Protecting the Request . . . . . . . . . . . . . . . . . 33 8.1. Protecting the Request . . . . . . . . . . . . . . . . . 34
8.2. Verifying the Request . . . . . . . . . . . . . . . . . . 34 8.2. Verifying the Request . . . . . . . . . . . . . . . . . . 34
8.3. Protecting the Response . . . . . . . . . . . . . . . . . 35 8.3. Protecting the Response . . . . . . . . . . . . . . . . . 36
8.4. Verifying the Response . . . . . . . . . . . . . . . . . 36 8.4. Verifying the Response . . . . . . . . . . . . . . . . . 36
9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 37 9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 38
10. Proxy and HTTP Operations . . . . . . . . . . . . . . . . . . 37 10. CoAP-to-CoAP Forwarding Proxy . . . . . . . . . . . . . . . . 38
10.1. CoAP-to-CoAP Forwarding Proxy . . . . . . . . . . . . . 38 11. HTTP Operations . . . . . . . . . . . . . . . . . . . . . . . 39
10.2. HTTP Processing . . . . . . . . . . . . . . . . . . . . 38 11.1. The HTTP OSCORE Header Field . . . . . . . . . . . . . . 39
10.3. HTTP-to-CoAP Translation Proxy . . . . . . . . . . . . . 40 11.2. CoAP-to-HTTP Mapping . . . . . . . . . . . . . . . . . . 40
10.4. CoAP-to-HTTP Translation Proxy . . . . . . . . . . . . . 41 11.3. HTTP-to-CoAP Mapping . . . . . . . . . . . . . . . . . . 40
11. Security Considerations . . . . . . . . . . . . . . . . . . . 43 11.4. HTTP Endpoints . . . . . . . . . . . . . . . . . . . . . 41
11.1. End-to-end protection . . . . . . . . . . . . . . . . . 43 11.5. Example: HTTP Client and CoAP Server . . . . . . . . . . 41
11.2. Security Context Establishment . . . . . . . . . . . . . 44 11.6. Example: CoAP Client and HTTP Server . . . . . . . . . . 43
11.3. Replay Protection . . . . . . . . . . . . . . . . . . . 44 12. Security Considerations . . . . . . . . . . . . . . . . . . . 44
11.4. Cryptographic Considerations . . . . . . . . . . . . . . 44 12.1. End-to-end Protection . . . . . . . . . . . . . . . . . 44
11.5. Message Segmentation . . . . . . . . . . . . . . . . . . 45 12.2. Security Context Establishment . . . . . . . . . . . . . 45
11.6. Privacy Considerations . . . . . . . . . . . . . . . . . 45 12.3. Master Secret . . . . . . . . . . . . . . . . . . . . . 45
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 45 12.4. Replay Protection . . . . . . . . . . . . . . . . . . . 45
12.1. COSE Header Parameters Registry . . . . . . . . . . . . 46 12.5. Client Aliveness . . . . . . . . . . . . . . . . . . . . 46
12.2. CoAP Option Numbers Registry . . . . . . . . . . . . . . 46 12.6. Cryptographic Considerations . . . . . . . . . . . . . . 46
12.3. CoAP Signaling Option Numbers Registry . . . . . . . . . 46 12.7. Message Segmentation . . . . . . . . . . . . . . . . . . 46
12.4. Header Field Registrations . . . . . . . . . . . . . . . 46 12.8. Privacy Considerations . . . . . . . . . . . . . . . . . 47
12.5. Media Type Registrations . . . . . . . . . . . . . . . . 47 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47
12.6. CoAP Content-Formats Registry . . . . . . . . . . . . . 49 13.1. COSE Header Parameters Registry . . . . . . . . . . . . 47
13. References . . . . . . . . . . . . . . . . . . . . . . . . . 49 13.2. CoAP Option Numbers Registry . . . . . . . . . . . . . . 48
13.1. Normative References . . . . . . . . . . . . . . . . . . 49 13.3. CoAP Signaling Option Numbers Registry . . . . . . . . . 48
13.2. Informative References . . . . . . . . . . . . . . . . . 51 13.4. Header Field Registrations . . . . . . . . . . . . . . . 48
Appendix A. Scenario Examples . . . . . . . . . . . . . . . . . 52 13.5. Media Type Registrations . . . . . . . . . . . . . . . . 49
A.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 52 13.6. CoAP Content-Formats Registry . . . . . . . . . . . . . 51
A.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 53 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 51
Appendix B. Deployment examples . . . . . . . . . . . . . . . . 55 14.1. Normative References . . . . . . . . . . . . . . . . . . 51
B.1. Master Secret Used Once . . . . . . . . . . . . . . . . . 55 14.2. Informative References . . . . . . . . . . . . . . . . . 53
B.2. Master Secret Used Multiple Times . . . . . . . . . . . . 55 Appendix A. Scenario Examples . . . . . . . . . . . . . . . . . 55
B.3. Client Aliveness . . . . . . . . . . . . . . . . . . . . 56 A.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 55
Appendix C. Test Vectors . . . . . . . . . . . . . . . . . . . . 57 A.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 56
C.1. Test Vector 1: Key Derivation with Master Salt . . . . . 57 Appendix B. Deployment Examples . . . . . . . . . . . . . . . . 57
C.2. Test Vector 2: Key Derivation without Master Salt . . . . 58 B.1. Master Secret Used Once . . . . . . . . . . . . . . . . . 57
C.3. Test Vector 3: OSCORE Request, Client . . . . . . . . . . 59 B.2. Master Secret Used Multiple Times . . . . . . . . . . . . 58
C.4. Test Vector 4: OSCORE Request, Client . . . . . . . . . . 60 Appendix C. Test Vectors . . . . . . . . . . . . . . . . . . . . 59
C.5. Test Vector 5: OSCORE Response, Server . . . . . . . . . 61 C.1. Test Vector 1: Key Derivation with Master Salt . . . . . 59
C.6. Test Vector 6: OSCORE Response with Partial IV, Server . 62 C.2. Test Vector 2: Key Derivation without Master Salt . . . . 60
Appendix D. Overview of Security Properties . . . . . . . . . . 64 C.3. Test Vector 3: OSCORE Request, Client . . . . . . . . . . 61
D.1. Supporting Proxy Operations . . . . . . . . . . . . . . . 64 C.4. Test Vector 4: OSCORE Request, Client . . . . . . . . . . 63
D.2. Protected Message Fields . . . . . . . . . . . . . . . . 64 C.5. Test Vector 5: OSCORE Response, Server . . . . . . . . . 64
D.3. Uniqueness of (key, nonce) . . . . . . . . . . . . . . . 65 C.6. Test Vector 6: OSCORE Response with Partial IV, Server . 65
D.4. Unprotected Message Fields . . . . . . . . . . . . . . . 66 Appendix D. Overview of Security Properties . . . . . . . . . . 66
Appendix E. CDDL Summary . . . . . . . . . . . . . . . . . . . . 68 D.1. Supporting Proxy Operations . . . . . . . . . . . . . . . 66
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 69 D.2. Protected Message Fields . . . . . . . . . . . . . . . . 66
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 69 D.3. Uniqueness of (key, nonce) . . . . . . . . . . . . . . . 67
D.4. Unprotected Message Fields . . . . . . . . . . . . . . . 68
Appendix E. CDDL Summary . . . . . . . . . . . . . . . . . . . . 71
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 72
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 72
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 (D)TLS to be terminated at the proxy. The proxy proxies require DTLS or TLS [RFC5246] to be terminated at the proxy.
therefore not only has access to the data required for performing the The proxy therefore not only has access to the data required for
intended proxy functionality, but is also able to eavesdrop on, or performing the intended proxy functionality, but is also able to
manipulate any part of, the message payload and metadata in transit eavesdrop on, or manipulate any part of, the message payload and
between the endpoints. The proxy can also inject, delete, or reorder metadata in transit between the endpoints. The proxy can also
packets since they are no longer protected by (D)TLS. inject, delete, or reorder packets since they are no longer protected
by (D)TLS.
This document defines the Object Security for Constrained RESTful This document defines the Object Security for Constrained RESTful
Environments (OSCORE) security protocol, protecting CoAP and CoAP- Environments (OSCORE) security protocol, protecting CoAP and CoAP-
mappable HTTP requests and responses end-to-end across intermediary mappable HTTP requests and responses end-to-end across intermediary
nodes such as CoAP forward proxies and cross-protocol translators nodes such as CoAP forward proxies and cross-protocol translators
including HTTP-to-CoAP proxies [RFC8075]. In addition to the core including HTTP-to-CoAP proxies [RFC8075]. In addition to the core
CoAP features defined in [RFC7252], OSCORE supports Observe CoAP features defined in [RFC7252], OSCORE supports Observe
[RFC7641], Block-wise [RFC7959], No-Response [RFC7967], and PATCH and [RFC7641], Block-wise [RFC7959], No-Response [RFC7967], and PATCH and
FETCH [RFC8132]. An analysis of end-to-end security for CoAP FETCH [RFC8132]. An analysis of end-to-end security for CoAP
messages through some types of intermediary nodes is performed in messages through some types of intermediary nodes is performed in
skipping to change at page 4, line 47 skipping to change at page 5, line 5
+-----------------------------------+ +-----------------------------------+
| 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 OSCORE works in very constrained nodes and networks, thanks to its
small message size and the restricted code and memory requirements in small message size and the restricted code and memory requirements in
addition to what is required by CoAP. Examples of the use of OSCORE addition to what is required by CoAP. Examples of the use of OSCORE
are given in Appendix A. OSCORE does not depend on underlying are given in Appendix A. OSCORE does not depend on underlying
layers, and can be used anywhere where CoAP or HTTP can be used, layers, and can be used with non-IP transports (e.g.,
including non-IP transports (e.g., [I-D.bormann-6lo-coap-802-15-ie]). [I-D.bormann-6lo-coap-802-15-ie]). OSCORE may also be used in
OSCORE may be used together with (D)TLS over one or more hops in the different ways with HTTP. OSCORE messages may be transported in
end-to-end path, e.g. with HTTPS in one hop and with plain CoAP in HTTP, and OSCORE may also be used to protect CoAP-mappable HTTP
another hop. messages, as described below.
The use of OSCORE does not affect the URI scheme and OSCORE can OSCORE is designed to protect as much information as possible while
therefore be used with any URI scheme defined for CoAP or HTTP. The still allowing CoAP proxy operations (Section 10). It works with
application decides the conditions for which OSCORE is required. legacy CoAP-to-CoAP forward proxies [RFC7252], but an OSCORE-aware
proxy will be more efficient. HTTP-to-CoAP proxies [RFC8075] and
CoAP-to-HTTP proxies can also be used with OSCORE, as specified in
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
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
scheme defined for CoAP or HTTP. The application decides the
conditions for which OSCORE is required.
OSCORE uses pre-shared keys which may have been established out-of- OSCORE uses pre-shared keys which may have been established out-of-
band or with a key establishment protocol (see Section 3.2). The band or with a key establishment protocol (see Section 3.2). The
technical solution builds on CBOR Object Signing and Encryption technical solution builds on CBOR Object Signing and Encryption
(COSE) [RFC8152], providing end-to-end encryption, integrity, replay (COSE) [RFC8152], providing end-to-end encryption, integrity, replay
protection, and secure binding of response to request. A compressed protection, and binding of response to request. A compressed version
version of COSE is used, as specified in Section 6. The use of of COSE is used, as specified in Section 6. The use of OSCORE is
OSCORE is signaled with the new Object-Security CoAP option or HTTP signaled in CoAP with a new option (Section 2), and in HTTP with a
header field, defined in Section 2 and Section 10.3. The solution new header field (Section 11.1) and content type (Section 13.5). The
transforms a CoAP/HTTP message into an "OSCORE message" before solution transforms a CoAP/HTTP message into an "OSCORE message"
sending, and vice versa after receiving. The OSCORE message is a before sending, and vice versa after receiving. The OSCORE message
CoAP/HTTP message related to the original message in the following is a CoAP/HTTP message related to the original message in the
way: the original CoAP/HTTP message is translated to CoAP (if not following way: the original CoAP/HTTP message is translated to CoAP
already in CoAP) and protected in a COSE object. The encrypted (if not already in CoAP) and protected in a COSE object. The
message fields of this COSE object are transported in the CoAP encrypted message fields of this COSE object are transported in the
payload/HTTP body of the OSCORE message, and the Object-Security CoAP payload/HTTP body of the OSCORE message, and the OSCORE option/
option/header field is included in the message. A sketch of an header field is included in the message. A sketch of an exchange of
OSCORE message exchange in the case of the original message being OSCORE messages, in the case of the original message being CoAP, is
CoAP is provided in Figure 2). provided in Figure 2.
Client Server Client Server
| OSCORE request - POST example.com: | | OSCORE request - POST example.com: |
| Header, Token, | | Header, Token, |
| Options: {Object-Security, ...}, | | Options: {OSCORE, ...}, |
| Payload: COSE ciphertext | | Payload: COSE ciphertext |
+--------------------------------------------->| +--------------------------------------------->|
| | | |
|<---------------------------------------------+ |<---------------------------------------------+
| OSCORE response - 2.04 (Changed): | | OSCORE response - 2.04 (Changed): |
| Header, Token, | | Header, Token, |
| Options: {Object-Security, ...}, | | Options: {OSCORE, ...}, |
| Payload: COSE ciphertext | | Payload: COSE ciphertext |
| | | |
Figure 2: Sketch of CoAP with OSCORE Figure 2: Sketch of CoAP with OSCORE
An implementation supporting this specification MAY implement only An implementation supporting this specification MAY implement only
the client part, MAY implement only the server part, or MAY implement the client part, MAY implement only the server part, or MAY implement
only one of the proxy parts. OSCORE is designed to protect as much only one of the proxy parts.
information as possible while still allowing proxy operations
(Section 10). It works with legacy CoAP-to-CoAP forward proxies
[RFC7252], but an OSCORE-aware proxy will be more efficient. HTTP-
to-CoAP proxies [RFC8075] and CoAP-to-HTTP proxies can also be used
with OSCORE, as specified in Section 10.
1.1. Terminology 1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
Readers are expected to be familiar with the terms and concepts Readers are expected to be familiar with the terms and concepts
skipping to change at page 6, line 31 skipping to change at page 7, line 5
document to indicate that the messages are processed accordingly in document to indicate that the messages are processed accordingly in
the intermediaries, rather than just forwarded to the next node. the intermediaries, rather than just forwarded to the next node.
The term "stop processing" is used throughout the document to denote The term "stop processing" is used throughout the document to denote
that the message is not passed up to the CoAP Request/Response layer that the message is not passed up to the CoAP Request/Response layer
(see Figure 1). (see Figure 1).
The terms Common/Sender/Recipient Context, Master Secret/Salt, Sender The terms Common/Sender/Recipient Context, Master Secret/Salt, Sender
ID/Key, Recipient ID/Key, and Common IV are defined in Section 3.1. ID/Key, Recipient ID/Key, and Common IV are defined in Section 3.1.
2. The CoAP Object-Security Option 2. The OSCORE Option
The CoAP Object-Security option (see Figure 3, which extends Table 4 The OSCORE option (see Figure 3, which extends Table 4 of [RFC7252])
of [RFC7252]) indicates that the CoAP message is an OSCORE message indicates that the CoAP message is an OSCORE message and that it
and that it contains a compressed COSE object (see Section 5 and contains a compressed COSE object (see Section 5 and Section 6). The
Section 6). The Object-Security option is critical, safe to forward, OSCORE option is critical, safe to forward, part of the cache key,
part of the cache key, and not repeatable. and not repeatable.
+-----+---+---+---+---+-----------------+--------+--------+---------+ +------+---+---+---+---+-----------------+--------+--------+---------+
| No. | C | U | N | R | Name | Format | Length | Default | | No. | C | U | N | R | Name | Format | Length | Default |
+-----+---+---+---+---+-----------------+--------+--------+---------+ +------+---+---+---+---+-----------------+--------+--------+---------+
| TBD | x | | | | Object-Security | (*) | 0-255 | (none) | | TBD1 | x | | | | OSCORE | (*) | 0-255 | (none) |
+-----+---+---+---+---+-----------------+--------+--------+---------+ +------+---+---+---+---+-----------------+--------+--------+---------+
C = Critical, U = Unsafe, N = NoCacheKey, R = Repeatable C = Critical, U = Unsafe, N = NoCacheKey, R = Repeatable
(*) See below. (*) See below.
Figure 3: The Object-Security Option Figure 3: The OSCORE Option
The Object-Security option includes the OSCORE flag bits (Section 6), The OSCORE option includes the OSCORE flag bits (Section 6), the
the Sender Sequence Number and the Sender ID when present Sender Sequence Number and the Sender ID when present (Section 3).
(Section 3). The detailed format and length is specified in The detailed format and length is specified in Section 6. If the
Section 6. If the OSCORE flag bits is all zero (0x00) the Option OSCORE flag bits are all zero (0x00) the Option value SHALL be empty
value SHALL be empty (Option Length = 0). An endpoint receiving a (Option Length = 0). An endpoint receiving a CoAP message without
CoAP message without payload, that also contains an Object-Security payload, that also contains an OSCORE option SHALL treat it as
option SHALL treat it as malformed and reject it. malformed and reject it.
A successful response to a request with the Object-Security option A successful response to a request with the OSCORE option SHALL
SHALL contain the Object-Security option. Whether error responses contain the OSCORE option. Whether error responses contain the
contain the Object-Security option depends on the error type (see OSCORE option depends on the error type (see Section 8).
Section 8).
A CoAP proxy SHOULD NOT cache a response to a request with an Object- For CoAP proxy operations, see Section 10.
Security option, since the response is only applicable to the
original request (see Section 10.1). As the compressed COSE Object
is included in the cache key, messages with the Object-Security
option will never generate cache hits. For Max-Age processing, see
Section 4.1.3.1.
3. The Security Context 3. The Security Context
OSCORE requires that client and server establish a shared security OSCORE requires that client and server establish a shared security
context used to process the COSE objects. OSCORE uses COSE with an context used to process the COSE objects. OSCORE uses COSE with an
Authenticated Encryption with Additional Data (AEAD, [RFC5116]) Authenticated Encryption with Additional Data (AEAD, [RFC5116])
algorithm for protecting message data between a client and a server. algorithm for protecting message data between a client and a server.
In this section, we define the security context and how it is derived In this section, we define the security context and how it is derived
in client and server based on a shared secret and a key derivation in client and server based on a shared secret and a key derivation
function (KDF). function (KDF).
skipping to change at page 8, line 35 skipping to change at page 8, line 50
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 Key Derivation Function. The HMAC based HKDF [RFC5869] used to o Key Derivation Function. The HMAC based HKDF [RFC5869] used to
derive Sender Key, Recipient Key, and Common IV. derive Sender Key, Recipient Key, and Common IV.
o Master Secret. Variable length, uniformly random byte string o Master Secret. Variable length, random byte string (see
containing the key used to derive traffic keys and IVs. Section 12.3) containing the keying material used to derive
traffic keys and IVs.
o Master Salt. Variable length byte string containing the salt used o Master Salt. Variable length byte string containing the salt used
to derive traffic keys and IVs. to derive traffic keys and IVs.
o Common IV. Byte string derived from Master Secret and Master o Common IV. Byte string derived from Master Secret and Master
Salt. Length is determined by the AEAD Algorithm. Salt. Length is determined by the AEAD Algorithm.
The Sender Context contains the following parameters: The Sender Context contains the following parameters:
o Sender ID. Byte string used to identify the Sender Context and to o Sender ID. Byte string used to identify the Sender Context and to
assure unique AEAD nonces. Maximum length is determined by the assure unique AEAD nonces. Maximum length is determined by the
AEAD Algorithm. AEAD Algorithm.
o Sender Key. Byte string containing the symmetric key to protect o Sender Key. Byte string containing the symmetric key to protect
messages to send. Derived from Common Context and Sender ID. messages to send. Derived from Common Context and Sender ID.
Length is determined by the AEAD Algorithm. Length is determined by the AEAD Algorithm.
o Sender Sequence Number. Non-negative integer used by the sender o Sender Sequence Number. Non-negative integer used by the sender
to protect requests and Observe notifications. Used as 'Partial to protect requests and certain responses, e.g. Observe
IV' [RFC8152] to generate unique nonces for the AEAD. Maximum notifications. Used as 'Partial IV' [RFC8152] to generate unique
value is determined by the AEAD Algorithm. nonces for the AEAD. Maximum value is determined by the AEAD
Algorithm.
The Recipient Context contains the following parameters: The Recipient Context contains the following parameters:
o Recipient ID. Byte string used to identify the Recipient Context o Recipient ID. Byte string used to identify the Recipient Context
and to assure unique AEAD nonces. Maximum length is determined by and to assure unique AEAD nonces. Maximum length is determined by
the AEAD Algorithm. the AEAD Algorithm.
o Recipient Key. Byte string containing the symmetric key to verify o Recipient Key. Byte string containing the symmetric key to verify
messages received. Derived from Common Context and Recipient ID. messages received. Derived from Common Context and Recipient ID.
Length is determined by the AEAD Algorithm. Length is determined by the AEAD Algorithm.
skipping to change at page 10, line 28 skipping to change at page 10, line 43
* Default is HKDF SHA-256 * Default is HKDF SHA-256
o Replay Window Type and Size o Replay Window Type and Size
* Default is DTLS-type replay protection with a window size of 32 * Default is DTLS-type replay protection with a window size of 32
[RFC6347] [RFC6347]
All input parameters need to be known to and agreed on by both All input parameters need to be known to and agreed on by both
endpoints, but the replay window may be different in the two endpoints, but the replay window may be different in the two
endpoints. The way the input parameters are pre-established, is endpoints. The way the input parameters are pre-established, is
application specific. The OSCORE profile of the ACE framework may be application specific. Considerations of security context
used to establish the necessary input parameters establishment are given in Section 12.2 and examples of deploying
[I-D.ietf-ace-oscore-profile], or a key exchange protocol for OSCORE in Appendix B.
providing forward secrecy. Other examples of deploying OSCORE are
given in Appendix B.
3.2.1. Derivation of Sender Key, Recipient Key, and Common IV 3.2.1. Derivation of Sender Key, Recipient Key, and Common IV
The KDF MUST be one of the HMAC based HKDF [RFC5869] algorithms The KDF MUST be one of the HMAC based HKDF [RFC5869] algorithms
defined in COSE. HKDF SHA-256 is mandatory to implement. The defined in COSE. HKDF SHA-256 is mandatory to implement. The
security context parameters Sender Key, Recipient Key, and Common IV security context parameters Sender Key, Recipient Key, and Common IV
SHALL be derived from the input parameters using the HKDF, which SHALL be derived from the input parameters using the HKDF, which
consists of the composition of the HKDF-Extract and HKDF-Expand steps consists of the composition of the HKDF-Extract and HKDF-Expand steps
[RFC5869]: [RFC5869]:
skipping to change at page 11, line 41 skipping to change at page 12, line 9
The Sender Sequence Number is initialized to 0. The supported types The Sender Sequence Number is initialized to 0. The supported types
of replay protection and replay window length is application specific of replay protection and replay window length is application specific
and depends on how OSCORE is transported, see Section 7.4. The and depends on how OSCORE is transported, see Section 7.4. The
default is DTLS-type replay protection with a window size of 32 default is DTLS-type replay protection with a window size of 32
initiated as described in Section 4.1.2.6 of [RFC6347]. initiated as described in Section 4.1.2.6 of [RFC6347].
3.3. Requirements on the Security Context Parameters 3.3. Requirements on the Security Context Parameters
As collisions may lead to the loss of both confidentiality and As collisions may lead to the loss of both confidentiality and
integrity, Sender ID SHALL be unique in the set of all security integrity, Sender ID SHALL be unique in the set of all security
contexts using the same Master Secret and Master Salt. When a contexts using the same Master Secret and Master Salt. To assign
trusted third party assigns identifiers (e.g., using identifiers, a trusted third party (e.g., [I-D.ietf-ace-oauth-authz])
[I-D.ietf-ace-oauth-authz]) or by using a protocol that allows the or a protocol that allows the parties to negotiate locally unique
parties to negotiate locally unique identifiers in each endpoint, the identifiers can be used. The Sender IDs can be very short. The
Sender IDs can be very short. The maximum length of Sender ID in maximum length of Sender ID in bytes equals the length of AEAD nonce
bytes equals the length of AEAD nonce minus 6. For AES-CCM-16-64-128 minus 6. For AES-CCM-16-64-128 the maximum length of Sender ID is 7
the maximum length of Sender ID is 7 bytes. bytes.
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 keying material, then the endpoint may need to try multiple different keying material, then the endpoint may need to try multiple
times before finding the right security context associated to the times before finding the right security context associated to the
Recipient ID. The Client MAY provide a 'kid context' parameter Recipient ID. The Client MAY provide a 'kid context' parameter
(Section 5.1) to help the Server find the right context. (Section 5.1) to help the Server find the right context.
While the triple (Master Secret, Master Salt, Sender ID) MUST be While the triple (Master Secret, Master Salt, Sender ID) MUST be
unique, the same Master Salt MAY be used with several Master Secrets unique, the same Master Salt MAY be used with several Master Secrets
and the same Master Secret MAY be used with several Master Salts. and the same Master Secret MAY be used with several Master Salts.
4. Protected Message Fields 4. Protected Message Fields
OSCORE transforms a CoAP message (which may have been generated from OSCORE transforms a CoAP message (which may have been generated from
an HTTP message) into an OSCORE message, and vice versa. OSCORE an HTTP message) into an OSCORE message, and vice versa. OSCORE
protects as much of the original message as possible while still protects as much of the original message as possible while still
allowing certain proxy operations (see Section 10). This section allowing certain proxy operations (see Section 10 and Section 11).
defines how OSCORE protects the message fields and transfers them This section defines how OSCORE protects the message fields and
end-to-end between client and server (in any direction). transfers them end-to-end between client and server (in any
direction).
The remainder of this section and later sections discuss the behavior The remainder of this section and later sections focus on the
in terms of CoAP messages. If HTTP is used for a particular hop in behavior in terms of CoAP messages. If HTTP is used for a particular
the end-to-end path, then this section applies to the conceptual CoAP hop in the end-to-end path, then this section applies to the
message that is mappable to/from the original HTTP message as conceptual CoAP message that is mappable to/from the original HTTP
discussed in Section 10. That is, an HTTP message is conceptually message as discussed in Section 11. That is, an HTTP message is
transformed to a CoAP message and then to an OSCORE message, and conceptually transformed to a CoAP message and then to an OSCORE
similarly in the reverse direction. An actual implementation might message, and similarly in the reverse direction. An actual
translate directly from HTTP to OSCORE without the intervening CoAP implementation might translate directly from HTTP to OSCORE without
representation. the intervening CoAP representation.
Protection of Signaling messages (Section 5 of [RFC8323]) is Protection of Signaling messages (Section 5 of [RFC8323]) is
specified in Section 4.3. The other parts of this section target specified in Section 4.3. The other parts of this section target
Request/Response messages. Request/Response messages.
Message fields of the CoAP message may be protected end-to-end Message fields of the CoAP message may be protected end-to-end
between CoAP client and CoAP server in different ways: between CoAP client and CoAP server in different ways:
o Class E: encrypted and integrity protected, o Class E: encrypted and integrity protected,
skipping to change at page 13, line 23 skipping to change at page 13, line 39
An OSCORE message may contain both an Inner and an Outer instance of An OSCORE message may contain both an Inner and an Outer instance of
a certain CoAP message field. Inner message fields are intended for a certain CoAP message field. Inner message fields are intended for
the receiving endpoint, whereas Outer message fields are used to the receiving endpoint, whereas Outer message fields are used to
enable proxy operations. Inner and Outer message fields are enable proxy operations. Inner and Outer message fields are
processed independently. processed independently.
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. The options which require special are protected accordingly. Certain options require special
processing are labelled with asterisks. processing as is described in Section 4.1.3.
+-----+-----------------+---+---+ +------+-----------------+---+---+
| No. | Name | E | U | | No. | Name | E | U |
+-----+-----------------+---+---+ +------+-----------------+---+---+
| 1 | If-Match | x | | | 1 | If-Match | x | |
| 3 | Uri-Host | | x | | 3 | Uri-Host | | x |
| 4 | ETag | x | | | 4 | ETag | x | |
| 5 | If-None-Match | x | | | 5 | If-None-Match | x | |
| 6 | Observe | | * | | 6 | Observe | | x |
| 7 | Uri-Port | | x | | 7 | Uri-Port | | x |
| 8 | Location-Path | x | | | 8 | Location-Path | x | |
| TBD | Object-Security | | * | | TBD1 | OSCORE | | x |
| 11 | Uri-Path | x | | | 11 | Uri-Path | x | |
| 12 | Content-Format | x | | | 12 | Content-Format | x | |
| 14 | Max-Age | * | * | | 14 | Max-Age | x | x |
| 15 | Uri-Query | x | | | 15 | Uri-Query | x | |
| 17 | Accept | x | | | 17 | Accept | x | |
| 20 | Location-Query | x | | | 20 | Location-Query | x | |
| 23 | Block2 | * | * | | 23 | Block2 | x | x |
| 27 | Block1 | * | * | | 27 | Block1 | x | x |
| 28 | Size2 | * | * | | 28 | Size2 | x | x |
| 35 | Proxy-Uri | | * | | 35 | Proxy-Uri | | x |
| 39 | Proxy-Scheme | | x | | 39 | Proxy-Scheme | | x |
| 60 | Size1 | * | * | | 60 | Size1 | x | x |
| 258 | No-Response | * | * | | 258 | No-Response | x | x |
+-----+-----------------+---+---+ +------+-----------------+---+---+
E = Encrypt and Integrity Protect (Inner) E = Encrypt and Integrity Protect (Inner)
U = Unprotected (Outer) U = Unprotected (Outer)
* = Special
Figure 5: Protection of CoAP Options Figure 5: Protection of CoAP Options
Options that are unknown or for which OSCORE processing is not Options that are unknown or for which OSCORE processing is not
defined SHALL be processed as class E (and no special processing). defined SHALL be processed as class E (and no special processing).
Specifications of new CoAP options SHOULD define how they are Specifications of new CoAP options SHOULD define how they are
processed with OSCORE. A new COAP option SHOULD be of class E unless processed with OSCORE. A new COAP option SHOULD be of class E unless
it requires proxy processing. it requires proxy processing.
4.1.1. Inner Options 4.1.1. Inner Options
skipping to change at page 15, line 11 skipping to change at page 15, line 11
present in the original CoAP message into the plaintext of the COSE present in the original CoAP message into the plaintext of the COSE
object (Section 5.3), and then remove the Inner option message fields object (Section 5.3), and then remove the Inner option message fields
from the OSCORE message. from the OSCORE message.
The processing of Inner option message fields by the receiving The processing of Inner option message fields by the receiving
endpoint is specified in Section 8.2 and Section 8.4. endpoint is specified in Section 8.2 and Section 8.4.
4.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. operations, see Appendix D.1.
The sending endpoint SHALL include the Outer option message field The sending endpoint SHALL include the Outer option message field
present in the original message in the options part of the OSCORE present in the original message in the options part of the OSCORE
message. All Outer option message fields, including Object-Security, message. All Outer option message fields, including the OSCORE
SHALL be encoded as described in Section 3.1 of [RFC7252], where the option, SHALL be encoded as described in Section 3.1 of [RFC7252],
delta is the difference to the previously included instance of Outer where the delta is the difference to the previously included instance
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 Section 8.2 and Section 8.4. specified in Section 8.2 and Section 8.4.
A procedure for integrity-protection-only of Class I option message A procedure for integrity-protection-only of Class I option message
fields is specified in Section 5.4. Proxies MUST NOT change the fields is specified in Section 5.4. Proxies MUST NOT change the
order of option's occurrences, for options repeatable and of class I. order of option's occurrences, for options repeatable and of class I.
Note: There are currently no Class I option message fields defined. Note: There are currently no Class I option message fields defined.
4.1.3. Special Options 4.1.3. Special Options
Some options require special processing, marked with an asterisk '*' Some options require special processing as specified in this section.
in Figure 5; the processing is specified in this section.
4.1.3.1. Max-Age 4.1.3.1. Max-Age
An Inner Max-Age message field is used to indicate the maximum time a An Inner Max-Age message field is used to indicate the maximum time a
response may be cached by the client (as defined in [RFC7252]), end- response may be cached by the client (as defined in [RFC7252]), end-
to-end from the server to the client, taking into account that the to-end from the server to the client, taking into account that the
option is not accessible to proxies. The Inner Max-Age SHALL be option is not accessible to proxies. The Inner Max-Age SHALL be
processed by OSCORE as specified in Section 4.1.1. processed by OSCORE as a normal Inner option, specified in
Section 4.1.1.
An Outer Max-Age message field is used to avoid unnecessary caching An Outer Max-Age message field is used to avoid unnecessary caching
of OSCORE error responses at OSCORE unaware intermediary nodes. A of OSCORE error responses at OSCORE unaware intermediary nodes. A
server MAY set a Class U Max-Age message field with value zero to server MAY set a Class U Max-Age message field with value zero to
OSCORE error responses, which are described in Section 7.4, OSCORE error responses, which are described in Section 7.4,
Section 8.2 and Section 8.4. Such message field is then processed Section 8.2 and Section 8.4. Such message field is then processed
according to Section 4.1.2. according to Section 4.1.2.
Successful OSCORE responses do not need to include an Outer Max-Age Successful OSCORE responses do not need to include an Outer Max-Age
option since the responses are non-cacheable by construction (see option since the responses are non-cacheable by construction (see
Section 4.2). Section 4.2).
4.1.3.2. The Block Options 4.1.3.2. Proxy-Uri
Block-wise [RFC7959] is an optional feature. An implementation MAY
support [RFC7252] and the Object-Security option without supporting
block-wise transfers. The Block options (Block1, Block2, Size1,
Size2), when Inner message fields, provide secure message
segmentation such that each segment can be verified. The Block
options, when Outer message fields, enables hop-by-hop fragmentation
of the OSCORE message. Inner and Outer block processing may have
different performance properties depending on the underlying
transport. The end-to-end integrity of the message can be verified
both in case of Inner and Outer Block-wise transfers provided all
blocks are received.
4.1.3.2.1. Inner Block Options
The sending CoAP endpoint MAY fragment a CoAP message as defined in
[RFC7959] before the message is processed by OSCORE. In this case
the Block options SHALL be processed by OSCORE as Inner options
(Section 4.1.1). The receiving CoAP endpoint SHALL process the
OSCORE message according to Section 4.1.1 before processing Block-
wise as defined in [RFC7959].
4.1.3.2.2. Outer Block Options
Proxies MAY fragment an OSCORE message using [RFC7959], by
introducing Block option message fields that are Outer
(Section 4.1.2) and not generated by the sending endpoint. Note that
the Outer Block options are neither encrypted nor integrity
protected. As a consequence, a proxy can maliciously inject block
fragments indefinitely, since the receiving endpoint needs to receive
the last block (see [RFC7959]) to be able to compose the OSCORE
message and verify its integrity. Therefore, applications supporting
OSCORE and [RFC7959] MUST specify a security policy defining a
maximum unfragmented message size (MAX_UNFRAGMENTED_SIZE) considering
the maximum size of message which can be handled by the endpoints.
Messages exceeding this size SHOULD be fragmented by the sending
endpoint using Inner Block options (Section 4.1.3.2.1).
An endpoint receiving an OSCORE message with an Outer Block option
SHALL first process this option according to [RFC7959], until all
blocks of the OSCORE message have been received, or the cumulated
message size of the blocks exceeds MAX_UNFRAGMENTED_SIZE. In the
former case, the processing of the OSCORE message continues as
defined in this document. In the latter case the message SHALL be
discarded.
Because of encryption of Uri-Path and Uri-Query, messages to the same
server may, from the point of view of a proxy, look like they also
target the same resource. A proxy SHOULD mitigate a potential mix-up
of blocks from concurrent requests to the same server, for example
using the Request-Tag processing specified in Section 3.3.2 of
[I-D.ietf-core-echo-request-tag].
4.1.3.3. Proxy-Uri
Proxy-Uri, when present, is split by OSCORE into class U options and Proxy-Uri, when present, is split by OSCORE into class U options and
class E options, which are processed accordingly. When Proxy-Uri is class E options, which are processed accordingly. When Proxy-Uri is
used in the original CoAP message, Uri-* are not present [RFC7252]. used in the original CoAP message, Uri-* are not present [RFC7252].
The sending endpoint SHALL first decompose the Proxy-Uri value of the The sending endpoint SHALL first decompose the Proxy-Uri value of the
original CoAP message into the Proxy-Scheme, Uri-Host, Uri-Port, Uri- original CoAP message into the Proxy-Scheme, Uri-Host, Uri-Port, Uri-
Path, and Uri-Query options (if present) according to Section 6.4 of Path, and Uri-Query options (if present) according to Section 6.4 of
[RFC7252]. [RFC7252].
Uri-Path and Uri-Query are class E options and SHALL be protected and Uri-Path and Uri-Query are class E options and SHALL be protected and
processed as Inner options (Section 4.1.1). processed as Inner options (Section 4.1.1). Uri-Host being an Outer
option SHOULD NOT contain privacy sensitive information.
The Proxy-Uri option of the OSCORE message SHALL be set to the The Proxy-Uri option of the OSCORE message SHALL be set to the
composition of Proxy-Scheme, Uri-Host, and Uri-Port options (if composition of Proxy-Scheme, Uri-Host, and Uri-Port options (if
present) as specified in Section 6.5 of [RFC7252], and processed as present) as specified in Section 6.5 of [RFC7252], and processed as
an Outer option of Class U (Section 4.1.2). an Outer option of Class U (Section 4.1.2).
Note that replacing the Proxy-Uri value with the Proxy-Scheme and Note that replacing the Proxy-Uri value with the Proxy-Scheme and
Uri-* options works by design for all CoAP URIs (see Section 6 of Uri-* options works by design for all CoAP URIs (see Section 6 of
[RFC7252]). OSCORE-aware HTTP servers should not use the userinfo [RFC7252]). OSCORE-aware HTTP servers should not use the userinfo
component of the HTTP URI (as defined in Section 3.2.1 of [RFC3986]), component of the HTTP URI (as defined in Section 3.2.1 of [RFC3986]),
skipping to change at page 18, line 4 skipping to change at page 16, line 47
o Proxy-Uri = "coap://example.com/resource?q=1" o Proxy-Uri = "coap://example.com/resource?q=1"
During OSCORE processing, Proxy-Uri is split into: During OSCORE processing, Proxy-Uri is split into:
o Proxy-Scheme = "coap" o Proxy-Scheme = "coap"
o Uri-Host = "example.com" o Uri-Host = "example.com"
o Uri-Port = "5683" o Uri-Port = "5683"
o Uri-Path = "resource" o Uri-Path = "resource"
o Uri-Query = "q=1" o Uri-Query = "q=1"
Uri-Path and Uri-Query follow the processing defined in Uri-Path and Uri-Query follow the processing defined in
Section 4.1.1, and are thus encrypted and transported in the COSE Section 4.1.1, and are thus encrypted and transported in the COSE
object. The remaining options are composed into the Proxy-Uri object. The remaining options are composed into the Proxy-Uri
included in the options part of the OSCORE message, which has value: included in the options part of the OSCORE message, which has value:
o Proxy-Uri = "coap://example.com" o Proxy-Uri = "coap://example.com"
See Sections 6.1 and 12.6 of [RFC7252] for more information. See Sections 6.1 and 12.6 of [RFC7252] for more information.
4.1.3.3. The Block Options
Block-wise [RFC7959] is an optional feature. An implementation MAY
support [RFC7252] and the OSCORE option without supporting block-wise
transfers. The Block options (Block1, Block2, Size1, Size2), when
Inner message fields, provide secure message segmentation such that
each segment can be verified. The Block options, when Outer message
fields, enables hop-by-hop fragmentation of the OSCORE message.
Inner and Outer block processing may have different performance
properties depending on the underlying transport. The end-to-end
integrity of the message can be verified both in case of Inner and
Outer Block-wise transfers provided all blocks are received.
4.1.3.3.1. Inner Block Options
The sending CoAP endpoint MAY fragment a CoAP message as defined in
[RFC7959] before the message is processed by OSCORE. In this case
the Block options SHALL be processed by OSCORE as normal Inner
options (Section 4.1.1). The receiving CoAP endpoint SHALL process
the OSCORE message before processing Block-wise as defined in
[RFC7959].
4.1.3.3.2. Outer Block Options
Proxies MAY fragment an OSCORE message using [RFC7959], by
introducing Block option message fields that are Outer
(Section 4.1.2). Note that the Outer Block options are neither
encrypted nor integrity protected. As a consequence, a proxy can
maliciously inject block fragments indefinitely, since the receiving
endpoint needs to receive the last block (see [RFC7959]) to be able
to compose the OSCORE message and verify its integrity. Therefore,
applications supporting OSCORE and [RFC7959] MUST specify a security
policy defining a maximum unfragmented message size
(MAX_UNFRAGMENTED_SIZE) considering the maximum size of message which
can be handled by the endpoints. Messages exceeding this size SHOULD
be fragmented by the sending endpoint using Inner Block options
(Section 4.1.3.3.1).
An endpoint receiving an OSCORE message with an Outer Block option
SHALL first process this option according to [RFC7959], until all
blocks of the OSCORE message have been received, or the cumulated
message size of the blocks exceeds MAX_UNFRAGMENTED_SIZE. In the
former case, the processing of the OSCORE message continues as
defined in this document. In the latter case the message SHALL be
discarded.
Because of encryption of Uri-Path and Uri-Query, messages to the same
server may, from the point of view of a proxy, look like they also
target the same resource. A proxy SHOULD mitigate a potential mix-up
of blocks from concurrent requests to the same server, for example
using the Request-Tag processing specified in Section 3.3.2 of
[I-D.ietf-core-echo-request-tag].
4.1.3.4. Observe 4.1.3.4. Observe
Observe [RFC7641] is an optional feature. An implementation MAY Observe [RFC7641] is an optional feature. An implementation MAY
support [RFC7252] and the Object-Security option without supporting support [RFC7252] and the OSCORE option without supporting [RFC7641].
[RFC7641]. The Observe option as used here targets the requirements The Observe option as used here targets the requirements on
on forwarding of [I-D.hartke-core-e2e-security-reqs] (Section 2.2.1). forwarding of [I-D.hartke-core-e2e-security-reqs] (Section 2.2.1).
In order for an OSCORE-unaware proxy to support forwarding of Observe An Observe intermediary MUST forward the OSCORE option unchanged. In
order for an OSCORE-unaware proxy to support forwarding of Observe
messages [RFC7641], there SHALL be an Outer Observe option, i.e., messages [RFC7641], there SHALL be an Outer Observe option, i.e.,
present in the options part of the OSCORE message. The processing of present in the options part of the OSCORE message. With OSCORE,
the CoAP Code for Observe messages is described in Section 4.2. Observe intermediaries are forwarding messages without being able to
re-send cached notifications to other clients.
To secure the order of notifications, the client SHALL maintain a
Notification Number for each Observation it registers. The
Notification Number is a non-negative integer containing the largest
Partial IV of the successfully received notifications for the
associated Observe registration (see Section 7.4). The Notification
Number is initialized to the Partial IV of the first successfully
received notification response to the registration request. In
contrast to [RFC7641], the received Partial IV MUST always be
compared with the Notification Number, which thus MUST NOT be
forgotten after 128 seconds. The client MAY ignore the Observe
option value.
If the verification fails, the client SHALL stop processing the In order to support multiple concurrent Observe registrations in the
response. same endpoint, Observe intermediaries are allowed to deviate from
[RFC7641] and register multiple times to the same (root) resource,
since the actual target resource is encrypted and not visible in the
OSCORE message. The processing of the CoAP Code for Observe messages
is described in Section 4.2.
The Observe option in the CoAP request may be legitimately removed by The Observe option in the CoAP request may be legitimately removed by
a proxy. If the Observe option is removed from a CoAP request by a a proxy or ignored by the server. In these cases, the server
proxy, then the server can still verify the request (as a non-Observe processes the request as a non-Observe request and produce a non-
request), and produce a non-Observe response. If the OSCORE client Observe response. If the OSCORE client receives a response to an
receives a response to an Observe request without an Outer Observe Observe request without an Outer Observe value, then it verifies the
value, then it MUST verify the response as a non-Observe response. response as a non-Observe response, as specified in Section 8.4. If
If the OSCORE client receives a response to a non-Observe request the OSCORE client receives a response to a non-Observe request with
with an Outer Observe value, it stops processing the message, as an Outer Observe value, it stops processing the message, as specified
specified in Section 8.4. in Section 8.4.
It the server accepts the Observe registration, a Partial IV must be
included in all notifications (both successful and error). To secure
the order of notifications, the client SHALL maintain a Notification
Number for each Observation it registers. The Notification Number is
a non-negative integer containing the largest Partial IV of the
received notifications for the associated Observe registration (see
Section 7.4). The Notification Number is initialized to the Partial
IV of the first successfully received notification response to the
registration request. In contrast to [RFC7641], the received Partial
IV MUST always be compared with the Notification Number, which thus
MUST NOT be forgotten after 128 seconds. Further details of replay
protection of notifications are specified in Section 7.4. The client
MAY ignore the Observe option value.
Clients can re-register observations to ensure that the observation Clients can re-register observations to ensure that the observation
is still active and establish freshness again ([RFC7641] is still active and establish freshness again ([RFC7641]
Section 3.3.1). When an OSCORE observation is refreshed, not only Section 3.3.1). When an OSCORE observation is refreshed, not only
the ETags, but also the partial IV (and thus the payload and Object- the ETags, but also the partial IV (and thus the payload and OSCORE
Security option) change. The server uses the new request's Partial option) change. The server uses the new request's Partial IV as the
IV as the 'request_piv' of new responses. 'request_piv' of new responses.
4.1.3.5. No-Response 4.1.3.5. No-Response
No-Response is defined in [RFC7967]. Clients using No-Response MUST No-Response [RFC7967] is an optional feature. Clients using No-
set both an Inner (Class E) and an Outer (Class U) No-Response Response MUST set both an Inner (Class E) and an Outer (Class U) No-
option, with same value. Response option, with the same value.
The Inner No-Response option is used to communicate to the server the The Inner No-Response option is used to communicate to the server the
client's disinterest in certain classes of responses to a particular client's disinterest in certain classes of responses to a particular
request. The Inner No-Response SHALL be processed by OSCORE as request. The Inner No-Response SHALL be processed by OSCORE as
specified in Section 4.1.1. specified in Section 4.1.1.
The Outer No-Response option is used to support proxy functionality, The Outer No-Response option is used to support proxy functionality,
specifically to avoid error transmissions from proxies to clients, specifically to avoid error transmissions from proxies to clients,
and to avoid bandwidth reduction to servers by proxies applying and to avoid bandwidth reduction to servers by proxies applying
congestion control when not receiving responses. The Outer No- congestion control when not receiving responses. The Outer No-
Response option is processed according to Section 4.1.2. Response option is processed according to Section 4.1.2.
In particular, step 8 of Section 8.4 is applied to No-Response. Note the effect in step 8 of Section 8.4 when applied to No-Response.
Applications should consider that a proxy may remove the Outer No- Applications should consider that a proxy may remove the Outer No-
Response option from the request. Applications using No-Response can Response option from the request. Applications using No-Response can
specify policies to deal with cases where servers receive an Inner specify policies to deal with cases where servers receive an Inner
No-Response option only, which may be the result of the request No-Response option only, which may be the result of the request
having traversed a No-Response unaware proxy, and update the having traversed a No-Response unaware proxy, and update the
processing in Section 8.4 accordingly. This avoids unnecessary error processing in Section 8.4 accordingly. This avoids unnecessary error
responses to clients and bandwidth reductions to servers, due to No- responses to clients and bandwidth reductions to servers, due to No-
Response unaware proxies. Response unaware proxies.
4.1.3.6. Object-Security 4.1.3.6. OSCORE
The Object-Security option is only defined to be present in OSCORE The OSCORE option is only defined to be present in OSCORE messages,
messages, as an indication that OSCORE processing have been as an indication that OSCORE processing have been performed. The
performed. The content in the Object-Security option is neither content in the OSCORE option is neither encrypted nor integrity
encrypted nor integrity protected as a whole but some part of the protected as a whole but some part of the content of this option is
content of this option is protected (see Section 5.4). "OSCORE protected (see Section 5.4). Nested use of OSCORE is not supported:
within OSCORE" is not supported: If OSCORE processing detects an If OSCORE processing detects an OSCORE option in the original CoAP
Object-Security option in the original CoAP message, then processing message, then processing SHALL be stopped.
SHALL be stopped.
4.2. 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 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 shown in Figure 6, including fields specific to CoAP over UDP and
CoAP over TCP (marked accordingly in the table). CoAP over TCP (marked accordingly in the table).
+------------------+---+---+ +------------------+---+---+
| Field | E | U | | Field | E | U |
+------------------+---+---+ +------------------+---+---+
skipping to change at page 20, line 43 skipping to change at page 21, line 4
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 Outer Code of the OSCORE message SHALL be set to 0.02
(POST) for requests without Observe option, to 0.05 (FETCH) for After that, the sending endpoint writes an Outer Code to the OSCORE
requests with Observe option, and to 2.04 (Changed) for responses. message. The Outer Code SHALL be set to 0.02 (POST) or 0.05 (FETCH)
Using FETCH with Observe allows OSCORE to be compliant with the for requests. For non-Observe requests the client SHALL set the
Observe processing in OSCORE-unaware proxies. The choice of POST and Outer Code to 0.02 (POST). For responses, the sending endpoint SHALL
respond with Outer Code 2.04 (Changed) to 0.02 (POST) requests, and
with Outer Code 2.05 (Content) to 0.05 (FETCH) requests. Using FETCH
with Observe allows OSCORE to be compliant with the Observe
processing in OSCORE-unaware intermediaries. The choice of POST and
FETCH [RFC8132] allows all OSCORE messages to have payload. FETCH [RFC8132] allows all OSCORE messages to have payload.
The receiving endpoint SHALL discard the Code in the OSCORE message The receiving endpoint SHALL discard the Outer Code in the OSCORE
and write the Code of the plaintext in the COSE object (Section 5.3) message and write the Code of the COSE object plaintext (Section 5.3)
into the decrypted CoAP message. into the decrypted CoAP message.
The other currently defined CoAP Header fields are Unprotected (Class The other currently defined CoAP Header fields are Unprotected (Class
U). The sending endpoint SHALL write all other header fields of the U). The sending endpoint SHALL write all other header fields of the
original message into the header of the OSCORE message. The original message into the header of the OSCORE message. The
receiving endpoint SHALL write the header fields from the received receiving endpoint SHALL write the header fields from the received
OSCORE message into the header of the decrypted CoAP message. OSCORE message into the header of the decrypted CoAP message.
The CoAP Payload, if present in the original CoAP message, SHALL be The CoAP Payload, if present in the original CoAP message, SHALL be
encrypted and integrity protected and is thus an Inner message field. encrypted and integrity protected and is thus an Inner message field.
skipping to change at page 21, line 41 skipping to change at page 22, line 9
o Signaling messages SHALL be protected as CoAP Request messages, o Signaling messages SHALL be protected as CoAP Request messages,
except in the case the Signaling message is a response to a except in the case the Signaling message is a response to a
previous Signaling message, in which case it SHALL be protected as previous Signaling message, in which case it SHALL be protected as
a CoAP Response message. For example, 7.02 (Ping) is protected as a CoAP Response message. For example, 7.02 (Ping) is protected as
a CoAP Request and 7.03 (Pong) as a CoAP response. a CoAP Request and 7.03 (Pong) as a CoAP response.
o The Outer Code for Signaling messages SHALL be set to 0.02 (POST), o The Outer Code for Signaling messages SHALL be set to 0.02 (POST),
unless it is a response to a previous Signaling message, in which unless it is a response to a previous Signaling message, in which
case it SHALL be set to 2.04 (Changed). case it SHALL be set to 2.04 (Changed).
o All Signaling options, except the Object-Security option, SHALL be o All Signaling options, except the OSCORE option, SHALL be Inner
Inner (Class E). (Class E).
NOTE: Option numbers for Signaling messages are specific to the CoAP NOTE: Option numbers for Signaling messages are specific to the CoAP
Code (see Section 5.2 of [RFC8323]). Code (see Section 5.2 of [RFC8323]).
If OSCORE is not used to protect Signaling, Signaling messages SHALL If OSCORE is not used to protect Signaling, Signaling messages SHALL
be unaltered by OSCORE. be unaltered by OSCORE.
5. The COSE Object 5. The COSE Object
This section defines how to use COSE [RFC8152] to wrap and protect This section defines how to use COSE [RFC8152] to wrap and protect
data in the original message. OSCORE uses the untagged COSE_Encrypt0 data in the original message. OSCORE uses the untagged COSE_Encrypt0
structure with an Authenticated Encryption with Additional Data structure with an Authenticated Encryption with Additional Data
(AEAD) algorithm. The key lengths, IV length, nonce length, and (AEAD) algorithm. The key lengths, IV length, nonce length, and
maximum Sender Sequence Number are algorithm dependent. maximum Sender Sequence Number are algorithm dependent.
The AEAD algorithm AES-CCM-16-64-128 defined in Section 10.2 of The AEAD algorithm AES-CCM-16-64-128 defined in Section 10.2 of
[RFC8152] is mandatory to implement. For AES-CCM-16-64-128 the [RFC8152] is mandatory to implement. For AES-CCM-16-64-128 the
length of Sender Key and Recipient Key is 128 bits, the length of length of Sender Key and Recipient Key is 128 bits, the length of
nonce and Common IV is 13 bytes. The maximum Sender Sequence Number nonce and Common IV is 13 bytes. The maximum Sender Sequence Number
is specified in Section 11. is specified in Section 12.
As specified in [RFC5116], plaintext denotes the data that is to be As specified in [RFC5116], plaintext denotes the data that is to be
encrypted and integrity protected, and Additional Authenticated Data encrypted and integrity protected, and Additional Authenticated Data
(AAD) denotes the data that is to be integrity protected only. (AAD) denotes the data that is to be integrity protected only.
The COSE Object SHALL be a COSE_Encrypt0 object with fields defined The COSE Object SHALL be a COSE_Encrypt0 object with fields defined
as follows as follows
o The 'protected' field is empty. o The 'protected' field is empty.
o The 'unprotected' field includes: o The 'unprotected' field includes:
* The 'Partial IV' parameter. The value is set to the Sender * The 'Partial IV' parameter. The value is set to the Sender
Sequence Number. All leading zeroes SHALL be removed when Sequence Number. All leading zeroes SHALL be removed when
encoding the Partial IV, except in the case of value 0 which is encoding the Partial IV, except in the case of value 0 which is
encoded to the byte string 0x00. This parameter SHALL be encoded to the byte string 0x00. This parameter SHALL be
present in requests. In case of Observe (Section 4.1.3.4) the present in requests. In case of Observe notifications
Partial IV SHALL be present in responses, and otherwise the (Section 4.1.3.4) the Partial IV SHALL be present in responses,
Partial IV will not typically be present in responses. (A non- and otherwise the Partial IV will not typically be present in
Observe example where the Partial IV is included in a response responses.
is provided in Section 7.5.2.)
* The 'kid' parameter. The value is set to the Sender ID. This * The 'kid' parameter. The value is set to the Sender ID. This
parameter SHALL be present in requests and 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 as defined in * Optionally, a 'kid context' parameter as defined in
Section 5.1. This parameter MAY be present in requests and Section 5.1. This parameter MAY be present in requests and
SHALL NOT be present in responses. SHALL NOT be present in responses.
skipping to change at page 23, line 20 skipping to change at page 23, line 33
For certain use cases, e.g. deployments where the same kid is used For certain use cases, e.g. deployments where the same kid is used
with multiple contexts, it is necessary or favorable for the sender with multiple contexts, it is necessary or favorable for the sender
to provide an additional identifier of the security material to use, to provide an additional identifier of the security material to use,
in order for the receiver to retrieve or establish the correct key. in order for the receiver to retrieve or establish the correct key.
The kid context parameter is used to provide such additional input. The kid context parameter is used to provide such additional input.
The kid context and kid are used to determine the security context, The kid context and kid are used to determine the security context,
or to establish the necessary input parameters to derive the security or to establish the necessary input parameters to derive the security
context (see Section 3.2). The application defines how this is done. context (see Section 3.2). The application defines how this is done.
The kid context is implicitly integrity protected, as manipulation The kid context is implicitly integrity protected, as a manipulation
that leads to the wrong key (or no key) being retrieved which results that leads to the wrong key (or no key) being retrieved results in an
in an error, as described in Section 8.2. error, as described in Section 8.2.
A summary of the COSE header parameter kid context defined above can A summary of the COSE header parameter kid context defined above can
be found in Figure 7. be found in Figure 7.
Some examples of relevant uses of kid context are the following: Some examples of relevant uses of kid context are the following:
o If the client has an identifier in some other namespace which can o If the client has an identifier in some other namespace which can
be used by the server to retrieve or establish the security be used by the server to retrieve or establish the security
context, then that identifier can be used as kid context. The kid context, then that identifier can be used as kid context. The kid
context may be used as Master Salt (Section 3.1) for additional context may be used as Master Salt (Section 3.1) for additional
skipping to change at page 23, line 44 skipping to change at page 24, line 8
[I-D.ietf-6tisch-minimal-security]). [I-D.ietf-6tisch-minimal-security]).
o In case of a group communication scenario o In case of a group communication scenario
[I-D.ietf-core-oscore-groupcomm], if the server belongs to [I-D.ietf-core-oscore-groupcomm], if the server belongs to
multiple groups, then a group identifier can be used as kid multiple groups, then a group identifier can be used as kid
context to enable the server to find the right security context. context to enable the server to find the right security context.
+----------+--------+------------+----------------+-----------------+ +----------+--------+------------+----------------+-----------------+
| name | label | value type | value registry | description | | name | label | value type | value registry | description |
+----------+--------+------------+----------------+-----------------+ +----------+--------+------------+----------------+-----------------+
| kid | kidctx | bstr | | Identifies the | | kid | TBD2 | bstr | | Identifies the |
| context | | | | kid context | | context | | | | kid context |
+----------+--------+------------+----------------+-----------------+ +----------+--------+------------+----------------+-----------------+
Figure 7: Additional common header parameter for the COSE object Figure 7: Additional common header parameter for the COSE object
5.2. Nonce 5.2. Nonce
The AEAD nonce is constructed in the following way (see Figure 8): The AEAD nonce is constructed in the following way (see Figure 8):
1. left-padding the Partial IV (in network byte order) with zeroes 1. left-padding the Partial IV (PIV) in network byte order with
to exactly 5 bytes, zeroes to exactly 5 bytes,
2. left-padding the (Sender) ID of the endpoint that generated the 2. left-padding the Sender ID of the endpoint that generated the
Partial IV (in network byte order) with zeroes to exactly nonce Partial IV (ID_PIV) in network byte order with zeroes to exactly
length - 6 bytes, nonce length minus 6 bytes,
3. concatenating the size of the ID (S) with the padded ID and the 3. concatenating the size of the ID_PIV (a single byte S) with the
padded Partial IV, padded ID_PIV and the padded PIV,
4. and then XORing with the Common IV. 4. and then XORing with the Common IV.
Note that in this specification only algorithms that use nonces equal Note that in this specification only algorithms that use nonces equal
or greater than 7 bytes are supported. The nonce construction with or greater than 7 bytes are supported. The nonce construction with
S, ID of PIV generator, and Partial IV together with endpoint unique S, ID_PIV, and PIV together with endpoint unique IDs and encryption
IDs and encryption keys make it easy to verify that the nonces used keys makes it easy to verify that the nonces used with a specific key
with a specific key will be unique. will be unique, see Appendix D.3.
When Observe is not used, the request and the response may use the If the Partial IV is not present in a response, the nonce from the
same nonce. In this way, the Partial IV does not have to be sent in request is used. For responses that are not notifications (i.e. when
responses, which reduces the size. For processing instructions see there is a single response to a request), the request and the
Section 8. response should typically use the same nonce to reduce message
overhead. Both alternatives provide all the required security
properties, see Appendix D.3 and Section 7.4. The only non-Observe
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.
For processing instructions see Section 8.
+---+-----------------------+--+--+--+--+--+ <- nonce length minus 6 B -> <-- 5 bytes -->
| S | ID of PIV generator | Partial IV |----+ +---+-------------------+--------+---------+-----+
+---+-----------------------+--+--+--+--+--+ | | S | padding | ID_PIV | padding | PIV |----+
| +---+-------------------+--------+---------+-----+ |
+------------------------------------------+ | |
| Common IV |->(XOR) <---------------- nonce length ----------------> |
+------------------------------------------+ | +------------------------------------------------+ |
| | Common IV |->(XOR)
+------------------------------------------+ | +------------------------------------------------+ |
| Nonce |<---+ |
+------------------------------------------+ <---------------- nonce length ----------------> |
+------------------------------------------------+ |
| Nonce |<---+
+------------------------------------------------+
Figure 8: AEAD Nonce Formation Figure 8: AEAD Nonce Formation
5.3. Plaintext 5.3. Plaintext
The plaintext is formatted as a CoAP message without Header (see The plaintext is formatted as a CoAP message without Header (see
Figure 9) consisting of: Figure 9) consisting of:
o the Code of the original CoAP message as defined in Section 3 of o the Code of the original CoAP message as defined in Section 3 of
[RFC7252]; and [RFC7252]; and
skipping to change at page 26, line 16 skipping to change at page 26, line 40
the request (see Section 5). the request (see Section 5).
o request_piv: contains the value of the 'Partial IV' in the COSE o request_piv: contains the value of the 'Partial IV' in the COSE
object of the request (see Section 5). object of the request (see Section 5).
o options: contains the Class I options (see Section 4.1.2) present o options: contains the Class I options (see Section 4.1.2) present
in the original CoAP message encoded as described in Section 3.1 in the original CoAP message encoded as described in Section 3.1
of [RFC7252], where the delta is the difference to the previously of [RFC7252], where the delta is the difference to the previously
included instance of class I option. included instance of class I option.
The oscore_version and algorithms parameters are established out-of-
band and are thus never transported in OSCORE, but the external_aad
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 the requests. need not be integrity protected in the requests.
6. OSCORE Header Compression 6. OSCORE Header Compression
The Concise Binary Object Representation (CBOR) [RFC7049] combines The Concise Binary Object Representation (CBOR) [RFC7049] combines
very small message sizes with extensibility. The CBOR Object Signing very small message sizes with extensibility. The CBOR Object Signing
and Encryption (COSE) [RFC8152] uses CBOR to create compact encoding and Encryption (COSE) [RFC8152] uses CBOR to create compact encoding
of signed and encrypted data. COSE is however constructed to support of signed and encrypted data. COSE is however constructed to support
a large number of different stateless use cases, and is not fully a large number of different stateless use cases, and is not fully
optimized for use as a stateful security protocol, leading to a optimized for use as a stateful security protocol, leading to a
larger than necessary message expansion. In this section, we define larger than necessary message expansion. In this section, we define
a stateless header compression mechanism, simply removing redundant a stateless header compression mechanism, simply removing redundant
information from the COSE objects, which significantly reduces the information from the COSE objects, which significantly reduces the
per-packet overhead. The result of applying this mechanism to a COSE per-packet overhead. The result of applying this mechanism to a COSE
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 Object- The COSE_Encrypt0 object used in OSCORE is transported in the OSCORE
Security option and in the Payload. The Payload contains the option and in the Payload. The Payload contains the Ciphertext and
Ciphertext and the headers of the COSE object are compactly encoded the headers of the COSE object are compactly encoded as described in
as described in the next section. the next section.
6.1. Encoding of the Object-Security Value 6.1. Encoding of the OSCORE Option Value
The value of the Object-Security option SHALL contain the OSCORE flag The value of the OSCORE option SHALL contain the OSCORE flag bits,
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) ... |
+------------+----------------------+------------------+ +------------+----------------------+------------------+
Figure 10: Object-Security Value Figure 10: The OSCORE Option Value
o The first byte of flag bits encodes the following set of flags and o The first byte of flag bits encodes the following set of flags and
the length of the Partial IV parameter: the length of the Partial IV parameter:
* The three least significant bits encode the Partial IV length * The three least significant bits encode the Partial IV length
n. If n = 0 then the Partial IV is not present in the n. If n = 0 then the Partial IV is not present in the
compressed COSE object. The values n = 6 and n = 7 are compressed COSE object. The values n = 6 and n = 7 are
reserved. reserved.
* The fourth least significant bit is the kid flag, k: it is set * The fourth least significant bit is the kid flag, k: it is set
skipping to change at page 27, line 50 skipping to change at page 28, line 23
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 context
flag is set (h = 1). 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 object-security Note that the kid MUST be the last field of the OSCORE option value,
value, even in case reserved bits are used and additional fields are even in case reserved bits are used and additional fields are added
added to it. to it.
The length of the Object-Security option thus depends on the presence The length of the OSCORE option thus depends on the presence and
and length of Partial IV, kid context, kid, as specified in this length of Partial IV, kid context, kid, as specified in this section,
section, and on the presence and length of the other parameters, as and on the presence and length of the other parameters, as defined in
defined in the separate documents. 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
is set (which means the CoAP message and cryptographic material is is set (which means the CoAP message and cryptographic material is
known). Note that the full CoAP unprotected message, as well as the known). Note that the full CoAP unprotected message, as well as the
full security context, is not reported in the examples, but only the full security context, is not reported in the examples, but only the
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: Object-Security option value and CoAP payload. two CoAP fields: OSCORE option and payload.
6.3.1. Examples: Requests
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
Option Value: 09 05 25 (3 bytes) Option Value: 09 05 25 (3 bytes)
Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes)
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
Option Value: 09 00 (2 bytes) Option Value: 09 00 (2 bytes)
Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes)
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):
[
h'',
{ 4:h'', 6:h'05', 8:h'44616c656b' },
h'aea0155667924dff8a24e4cb35b9'
]
After compression (22 bytes): Before compression (30 bytes):
Flag byte: 0b00011001 = 0x19 [
h'',
{ 4:h'', 6:h'05', 8:h'44616c656b' },
h'aea0155667924dff8a24e4cb35b9'
]
Option Value: 19 05 05 44 61 6c 65 6b (8 bytes) After compression (22 bytes):
Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) Flag byte: 0b00011001 = 0x19
6.3.2. Example: Response (without Observe) Option Value: 19 05 05 44 61 6c 65 6b (8 bytes)
1. Response not including an Observe option, with ciphertext = Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes)
0xaea0155667924dff8a24e4cb35b9
Before compression (18 bytes): 4. Response with ciphertext = 0xaea0155667924dff8a24e4cb35b9 and no
Partial IV
[ Before compression (18 bytes):
h'',
{},
h'aea0155667924dff8a24e4cb35b9'
]
After compression (14 bytes): [
h'',
{},
h'aea0155667924dff8a24e4cb35b9'
]
Flag byte: 0b00000000 = 0x00 After compression (14 bytes):
Option Value: (0 bytes) Flag byte: 0b00000000 = 0x00
Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) Option Value: (0 bytes)
6.3.3. Example: Response (with Observe) Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes)
1. Response including an Observe option, with ciphertext = 5. Response with ciphertext = 0xaea0155667924dff8a24e4cb35b9 and
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
Option Value: 01 07 (2 bytes) Option Value: 01 07 (2 bytes)
Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes)
7. Sequence Numbers, Replay, Message Binding, and Freshness 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 proxies, 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 IV
of the request until all responses have been sent. of the request until all responses have been sent.
7.2. AEAD Nonce Uniqueness 7.2. Sequence Numbers
An AEAD nonce MUST NOT be used more than once per AEAD key. In order An AEAD nonce MUST NOT be used more than once per AEAD key. The
to assure unique nonces, each Sender Context contains a Sender uniqueness of (key, nonce) pairs is shown in Appendix D.3, and in
Sequence Number used to protect requests, and - in case of Observe - particular depends on a correct usage of Partial IVs. If messages
responses. If messages are processed concurrently, the operation of are processed concurrently, the operation of reading and increasing
reading and increasing the Sender Sequence Number MUST be atomic. the Sender Sequence Number MUST be atomic.
The maximum Sender Sequence Number is algorithm dependent (see The maximum Sender Sequence Number is algorithm dependent (see
Section 11), and 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
messages with the given Sender Context. The endpoint SHOULD acquire messages with the given Sender Context. If necessary, the endpoint
a new security context (and consequently inform the other endpoint) SHOULD acquire a new security context before this happens. The
before this happens. The latter is out of scope of this document. latter is out of scope of this document.
7.3. Freshness 7.3. Freshness
For requests, OSCORE provides only the guarantee that the request is For requests, OSCORE provides only the guarantee that the request is
not older than the security context. For applications having not older than the security context. For applications having
stronger demands on request freshness (e.g., control of actuators), stronger demands on request freshness (e.g., control of actuators),
OSCORE needs to be augmented with mechanisms providing freshness, for OSCORE needs to be augmented with mechanisms providing freshness, for
example as specified in [I-D.ietf-core-echo-request-tag]. example as specified in [I-D.ietf-core-echo-request-tag].
For responses, the message binding guarantees that a response is not Assuming an honest server, the message binding guarantees that a
older than its request. For responses without Observe, this gives response is not older than its request. For responses that are not
strong absolute freshness. For responses with Observe, the absolute notifications (i.e. when there is a single response to a request),
this gives absolute freshness. For notifications, the absolute
freshness gets weaker with time, and it is RECOMMENDED that the freshness gets weaker with time, and it is RECOMMENDED that the
client regularly re-register the observation. client regularly re-register the observation. Note that the message
binding does not guarantee that misbehaving server created the
response before receiving the request, i.e. it does not verify server
aliveness.
For requests, and responses with Observe, OSCORE also provides For requests and notifications, OSCORE also provides relative
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 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 received in the COSE object has not been received before. Partial IV received in the COSE object has not been received before.
If this verification fails the server SHALL stop processing the If this verification fails the server SHALL stop processing the
message, and MAY optionally respond with a 4.01 Unauthorized error message, and MAY optionally respond with a 4.01 Unauthorized error
message. Also, the server MAY set an Outer Max-Age option with value message. Also, the server MAY set an Outer Max-Age option with value
zero. The diagnostic payload MAY contain the "Replay detected" zero. The diagnostic payload MAY contain the "Replay detected"
string. The size and type of the Replay Window depends on the use string. The size and type of the Replay Window depends on the use
case and the protocol with which the OSCORE message is transported. case and the protocol with which the OSCORE message is transported.
In case of reliable and ordered transport from endpoint to endpoint, In case of reliable and ordered transport from endpoint to endpoint,
e.g. TCP, the server MAY just store the last received Partial IV and e.g. TCP, the server MAY just store the last received Partial IV and
require that newly received Partial IVs equals the last received require that newly received Partial IVs equals the last received
Partial IV + 1. However, in case of mixed reliable and unreliable Partial IV + 1. However, in case of mixed reliable and unreliable
transports and where messages may be lost, such a replay mechanism transports and where messages may be lost, such a replay mechanism
may be too restrictive and the default replay window be more suitable may be too restrictive and the default replay window be more suitable
(see Section 3.2.2). (see Section 3.2.2).
Responses to non-Observe requests are protected against replay as Responses that are not notifications (with or without Partial IV) are
they are cryptographically bound to the request. protected against replay as they are bound to the request and the
fact that only a single response is accepted. Note that the Partial
IV is not used for replay protection in this case.
In the case of Observe, a client receiving a notification SHALL A client receiving a notification SHALL compare the Partial IV of a
verify that the Partial IV of a received notification is greater than received notification with the Notification Number associated to that
the Notification Number bound to that Observe registration. If the Observe registration. A client MUST consider the notification with
verification fails, the client SHALL stop processing the response. the highest Partial IV as the freshest, regardless of the order of
If the verification succeeds, the client SHALL overwrite the arrival. If the verification of the response succeeds, and the
corresponding Notification Number with the received Partial IV. received Partial IV was greater than the Notification Number then the
client SHALL overwrite the corresponding Notification Number with the
received Partial IV (see step 7 of Section 8.4. The client MUST stop
processing notifications with a Partial IV which has been previously
received. The client MAY process only notifications which have
greater Partial IV than the Notification Number.
If messages are processed concurrently, the Partial IV needs to be If messages are processed concurrently, the Partial IV needs to be
validated a second time after decryption and before updating the validated a second time after decryption and before updating the
replay protection data. The operation of validating the Partial IV replay protection data. The operation of validating the Partial IV
and updating the replay protection data MUST be atomic. and updating the replay protection data MUST be atomic.
7.5. Losing Part of the Context State 7.5. Losing Part of the Context State
To prevent reuse of the AEAD nonce with the same key, or from To prevent reuse of an AEAD nonce with the same key, or from
accepting replayed messages, an endpoint needs to handle the accepting replayed messages, an endpoint needs to handle the
situation of losing rapidly changing parts of the context, such as situation of losing rapidly changing parts of the context, such as
the request Token, Sender Sequence Number, Replay Window, and the request Token, Sender Sequence Number, Replay Window, and
Notification Numbers. These are typically stored in RAM and Notification Numbers. These are typically stored in RAM and
therefore lost in the case of an unplanned reboot. therefore lost in the case of an unplanned reboot.
After boot, an endpoint MAY reject to use pre-existing security After boot, an endpoint MAY reject to use pre-existing security
contexts, and MAY establish a new security context with each endpoint contexts, and MAY establish a new security context with each endpoint
it communicates with. However, establishing a fresh security context it communicates with. However, establishing a fresh security context
may have a non-negligible cost in terms of, e.g., power consumption. may have a non-negligible cost in terms of, e.g., power consumption.
skipping to change at page 32, line 37 skipping to change at page 33, line 22
After boot, an endpoint MAY use a partly persistently stored security After boot, an endpoint MAY use a partly persistently stored security
context, but then the endpoint MUST NOT reuse a previous Sender context, but then the endpoint MUST NOT reuse a previous Sender
Sequence Number and MUST NOT accept previously accepted messages. Sequence Number and MUST NOT accept previously accepted messages.
Some ways to achieve this are described in the following sections. Some ways to achieve this are described in the following sections.
7.5.1. Sequence Number 7.5.1. Sequence Number
To prevent reuse of Sender Sequence Numbers, an endpoint MAY perform To prevent reuse of Sender Sequence Numbers, an endpoint MAY perform
the following procedure during normal operations: the following procedure during normal operations:
o Each time the Sender Sequence Number is evenly divisible by K, o Before using a Sender Sequence Number that is evenly divisible by
where K is a positive integer, store the Sender Sequence Number in K, where K is a positive integer, store the Sender Sequence Number
persistent memory. After boot, the endpoint initiates the Sender in persistent memory. After boot, the endpoint initiates the
Sequence Number to the value stored in persistent memory + K - 1. Sender Sequence Number to the value stored in persistent memory +
Storing to persistent memory can be costly. The value K gives a K. Storing to persistent memory can be costly. The value K gives
trade-off between the number of storage operations and efficient a trade-off between the number of storage operations and efficient
use of Sender Sequence Numbers. use of Sender Sequence Numbers.
7.5.2. Replay Window 7.5.2. Replay Window
To prevent accepting replay of previously received requests, the To prevent accepting replay of previously received requests, the
server MAY perform the following procedure after boot: server MAY perform the following procedure after boot:
o For each stored security context, the first time after boot the o For each stored security context, the first time after boot the
server receives an OSCORE request, the server responds with the server receives an OSCORE request, the server responds with the
Echo option [I-D.ietf-core-echo-request-tag] to get a request with Echo option [I-D.ietf-core-echo-request-tag] to get a request with
skipping to change at page 33, line 36 skipping to change at page 34, line 23
8.1. Protecting the Request 8.1. Protecting the Request
Given a CoAP request, the client SHALL perform the following steps to Given a CoAP request, the client SHALL perform the following steps to
create an OSCORE request: create an OSCORE request:
1. Retrieve the Sender Context associated with the target resource. 1. Retrieve the Sender Context associated with the target resource.
2. Compose the Additional Authenticated Data and the plaintext, as 2. Compose the Additional Authenticated Data and the plaintext, as
described in Section 5.4 and Section 5.3. described in Section 5.4 and Section 5.3.
3. Compute the AEAD nonce from the Sender ID, Common IV, and Partial 3. Encode the Partial IV (Sender Sequence Number in network byte
IV (Sender Sequence Number in network byte order) as described in order) and increment the Sender Sequence Number by one. Compute
Section 5.2 and (in one atomic operation, see Section 7.2) the AEAD nonce from the Sender ID, Common IV, and Partial IV as
increment the Sender Sequence Number by one. described in Section 5.2.
4. Encrypt the COSE object using the Sender Key. Compress the COSE 4. Encrypt the COSE object using the Sender Key. Compress the COSE
Object as specified in Section 6. Object as specified in Section 6.
5. Format the OSCORE message according to Section 4. The Object- 5. Format the OSCORE message according to Section 4. The OSCORE
Security option is added (see Section 4.1.2). option is added (see Section 4.1.2).
6. Store the association Token - Security Context, in order to be 6. Store the attribute-value pair (Token, {Security Context, PIV})
able to find the Recipient Context from the Token in the in order to be able to find the Recipient Context and the
response. request_piv from the Token in the response.
8.2. Verifying the Request 8.2. Verifying the Request
A server receiving a request containing the Object-Security option A server receiving a request containing the OSCORE option SHALL
SHALL perform the following steps: perform the following steps:
1. Process Outer Block options according to [RFC7959], until all 1. Process Outer Block options according to [RFC7959], until all
blocks of the request have been received (see Section 4.1.3.2). blocks of the request have been received (see Section 4.1.3.3).
2. Discard the message Code and all non-special Inner option 2. Discard the message Code and all non-special Inner option
message fields (marked with 'x' in column E of Figure 5) present message fields (marked in Figure 5 with 'x' in column E only)
in the received message. For example, an If-Match Outer option present in the received message. For example, an If-Match Outer
is discarded, but an Uri-Host Outer option is not discarded. option is discarded, but an Uri-Host Outer option is not
discarded.
3. Decompress the COSE Object (Section 6) and retrieve the 3. Decompress the COSE Object (Section 6) and retrieve the
Recipient Context associated with the Recipient ID in the 'kid' Recipient Context associated with the Recipient ID in the 'kid'
parameter. If either the decompression or the COSE message parameter. If either the decompression or the COSE message
fails to decode, or the server fails to retrieve a Recipient fails to decode, or the server fails to retrieve a Recipient
Context with Recipient ID corresponding to the 'kid' parameter Context with Recipient ID corresponding to the 'kid' parameter
received, then the server SHALL stop processing the request. received, then the server SHALL stop processing the request.
If: If:
* either the decompression or the COSE message fails to decode, * either the decompression or the COSE message fails to decode,
skipping to change at page 35, line 19 skipping to change at page 36, line 6
* If decryption succeeds, update the Replay Window, as * If decryption succeeds, update the Replay Window, as
described in Section 7. described in Section 7.
8. For each decrypted option, check if the option is also present 8. For each decrypted option, check if the option is also present
as an Outer option: if it is, discard the Outer. For example: as an Outer option: if it is, discard the Outer. For example:
the message contains a Max-Age Inner and a Max-Age Outer option. the message contains a Max-Age Inner and a Max-Age Outer option.
The Outer Max-Age is discarded. The Outer Max-Age is discarded.
9. Add decrypted code, options and payload to the decrypted 9. Add decrypted code, options and payload to the decrypted
request. The Object-Security option is removed. request. The OSCORE option is removed.
10. The decrypted CoAP request is processed according to [RFC7252]. 10. The decrypted CoAP request is processed according to [RFC7252].
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 (point 10. in Section 8.2) are protected, as well as processing (point 10. in Section 8.2) are protected, as well as
successful CoAP responses, while the OSCORE errors (point 3, 4, and 7 successful CoAP responses, while the OSCORE errors (point 3, 4, and 7
skipping to change at page 35, line 41 skipping to change at page 36, line 28
simple CoAP responses, without OSCORE processing. simple CoAP responses, without OSCORE processing.
1. Retrieve the Sender Context in the Security Context used to 1. Retrieve the Sender Context in the Security Context used to
verify the request. verify the request.
2. Compose the Additional Authenticated Data and the plaintext, as 2. Compose the Additional Authenticated Data and the plaintext, as
described in Section 5.4 and Section 5.3. described in Section 5.4 and Section 5.3.
3. Compute the AEAD nonce 3. Compute the AEAD nonce
* If Observe is used, compute the nonce from the Sender ID, * For Observe notifications, encode the Partial IV (Sender
Common IV, and Partial IV (Sender Sequence Number in network Sequence Number in network byte order) and increment the
byte order). Then (in one atomic operation, see Section 7.2) Sender Sequence Number by one. Compute the AEAD nonce from
increment the Sender Sequence Number by one. the Sender ID, Common IV, and Partial IV as described in
Section 5.2.
* If Observe is not used, either the nonce from the request is * For responses that are not Observe notifications, either use
used or a new Partial IV is used (see bullet on 'Partial IV' the nonce from the request, or compute a new nonce from the
in Section 5). Sender ID, Common IV, and a new Partial IV as described in
Section 5.2, and increment the Sender Sequence Number by one.
4. Encrypt the COSE object using the Sender Key. Compress the COSE 4. Encrypt the COSE object using the Sender Key. Compress the COSE
Object as specified in Section 6. If the AEAD nonce was Object as specified in Section 6. If the AEAD nonce was
constructed from a new Partial IV, this Partial IV MUST be constructed from a new Partial IV, this Partial IV MUST be
included in the message. If the AEAD nonce from the request was included in the message. If the AEAD nonce from the request was
used, the Partial IV MUST NOT be included in the message. used, the Partial IV MUST NOT be included in the message.
5. Format the OSCORE message according to Section 4. The Object- 5. Format the OSCORE message according to Section 4. The OSCORE
Security option is added (see Section 4.1.2). option is added (see Section 4.1.2).
8.4. Verifying the Response 8.4. Verifying the Response
A client receiving a response containing the Object-Security option A client receiving a response containing the OSCORE option SHALL
SHALL perform the following steps: perform the following steps:
1. Process Outer Block options according to [RFC7959], until all 1. Process Outer Block options according to [RFC7959], until all
blocks of the OSCORE message have been received (see blocks of the OSCORE message have been received (see
Section 4.1.3.2). Section 4.1.3.3).
2. Discard the message Code and all non-special Class E options 2. Discard the message Code and all non-special Class E options
from the message. For example, ETag Outer option is discarded, from the message. For example, ETag Outer option is discarded,
Max-Age Outer option is not discarded. Max-Age Outer option is not discarded.
3. Retrieve the Recipient Context associated with the Token. 3. Retrieve the Recipient Context associated with the Token.
Decompress the COSE Object (Section 6). If either the Decompress the COSE Object (Section 6). If either the
decompression or the COSE message fails to decode, then go to decompression or the COSE message fails to decode, then go to
11. 11.
4. For Observe notifications, verify the received 'Partial IV' 4. If the Observe option is present in the response, but the
request was not an Observe registration, then go to 11. If a
Partial IV is required (i.e. an Observe option is included or
the Notification number for the observation has already been
initiated), but not present in the response, then go to 11. For
Observe notifications, verify the received 'Partial IV'
parameter against the corresponding Notification Number as parameter against the corresponding Notification Number as
described in Section 7.4. If the client receives a notification described in Section 7.4.
for which no Observe request was sent, then go to 11.
5. Compose the Additional Authenticated Data, as described in 5. Compose the Additional Authenticated Data, as described in
Section 5.4. Section 5.4.
6. Compute the AEAD nonce 6. Compute the AEAD nonce
1. If the Observe option and the Partial IV are not present in * If the Partial IV are not present in the response, the nonce
the response, the nonce from the request is used. from the request is used.
2. If the Observe option is present in the response, and the
Partial IV is not present in the response, then go to 11.
3. If the Partial IV is present in the response, compute the * If the Partial IV is present in the response, compute the
nonce from the Recipient ID, Common IV, and the 'Partial IV' nonce from the Recipient ID, Common IV, and the 'Partial IV'
parameter, received in the COSE Object. parameter, received in the COSE Object.
7. Decrypt the COSE object using the Recipient Key, as per 7. Decrypt the COSE object using the Recipient Key, as per
[RFC8152] Section 5.3. (The decrypt operation includes the [RFC8152] Section 5.3. (The decrypt operation includes the
verification of the integrity.) verification of the integrity.) If decryption fails, then go to
* If decryption fails, then go to 11. 11.
* If decryption succeeds and Observe is used, update the 8. If the response is a notification, initiate or update the
corresponding Notification Number, as described in Section 7. corresponding Notification Number, as described in Section 7.
Otherwise, delete the attribute-value pair (Token, {Security
Context, PIV}).
8. For each decrypted option, check if the option is also present 9. For each decrypted option, check if the option is also present
as an Outer option: if it is, discard the Outer. For example: as an Outer option: if it is, discard the Outer. For example:
the message contains a Max-Age Inner and a Max-Age Outer option. the message contains a Max-Age Inner and a Max-Age Outer option.
The Outer Max-Age is discarded. The Outer Max-Age is discarded.
9. Add decrypted code, options and payload to the decrypted 10. Add decrypted code, options and payload to the decrypted
request. The Object-Security option is removed. request. The OSCORE option is removed.
10. The decrypted CoAP response is processed according to [RFC7252]. 11. The decrypted CoAP response is processed according to [RFC7252].
11. In case any of the previous erroneous conditions apply: the 12. In case any of the previous erroneous conditions apply: the
client SHALL stop processing the response. client SHALL stop processing the response.
An error condition occurring while processing a response in an An error condition occurring while processing a response in an
observation does not cancel the observation. A client MUST NOT react observation does not cancel the observation. A client MUST NOT react
to failure in step 7 by re-registering the observation immediately. to failure in step 7 by re-registering the observation immediately.
9. Web Linking 9. Web Linking
The use of OSCORE MAY be indicated by a target attribute "osc" in a The use of OSCORE MAY be indicated by a target attribute "osc" in a
web link [RFC8288] to a resource. This attribute is a hint web link [RFC8288] to a resource, e.g. using a link-format document
indicating that the destination of that link is to be accessed using [RFC6690] if the resource is accessible over CoAP.
OSCORE. Note that this is simply a hint, it does not include any
security context material or any other information required to run The "osc" attribute is a hint indicating that the destination of that
OSCORE. link is only accessible using OSCORE, and unprotected access to it is
not supported. Note that this is simply a hint, it does not include
any security context material or any other information required to
run OSCORE.
A value MUST NOT be given for the "osc" attribute; any present value A value MUST NOT be given for the "osc" attribute; any present value
MUST be ignored by parsers. The "osc" attribute MUST NOT appear more MUST be ignored by parsers. The "osc" attribute MUST NOT appear more
than once in a given link-value; occurrences after the first MUST be than once in a given link-value; occurrences after the first MUST be
ignored by parsers. ignored by parsers.
10. Proxy and HTTP Operations The example in Figure 11 shows a use of the "osc" attribute: the
client does resource discovery on a server, and gets back a list of
resources, one of which includes the "osc" attribute indicating that
the resource is protected with OSCORE. The link-format notation (see
Section 5. of [RFC6690]) is used.
RFC 7252 defines operations for a CoAP-to-CoAP proxy (see Section 5.7 REQ: GET /.well-known/core
of [RFC7252]) and for proxying between CoAP and HTTP (Section 10 of
[RFC7252]). A more detailed description of the HTTP-to-CoAP mapping
is provided by [RFC8075]. This section describes the operations of
OSCORE-aware proxies.
10.1. CoAP-to-CoAP Forwarding Proxy RES: 2.05 Content
</sensors/temp>;osc,
</sensors/light>;if="sensor"
OSCORE is designed to work with legacy CoAP-to-CoAP forward proxies Figure 11: The web link
[RFC7252], but OSCORE-aware proxies MAY provide certain
simplifications as specified in this section.
10. CoAP-to-CoAP Forwarding Proxy
CoAP is designed for proxy operations (see Section 5.7 of [RFC7252]).
Security requirements for forwarding are presented in Section 2.2.1 Security requirements for forwarding are presented in Section 2.2.1
of [I-D.hartke-core-e2e-security-reqs]. OSCORE complies with the of [I-D.hartke-core-e2e-security-reqs].
extended security requirements also addressing Block-wise [RFC7959]
and CoAP-mappable HTTP. In particular caching is disabled since the OSCORE is designed to work with legacy CoAP proxies. Since a CoAP
CoAP response is only applicable to the original CoAP request. An response is only applicable to the original CoAP request, caching is
OSCORE-aware proxy SHALL NOT cache a response to a request with an in general not useful. In support of legacy proxies, OSCORE defines
Object-Security option. As a consequence, the search for cache hits special Max-Age processing, see Section 4.1.3.1. An OSCORE-aware
and CoAP freshness/Max-Age processing can be omitted. proxy SHOULD NOT cache a response to a request with an OSCORE option
Proxy processing of the (Outer) Proxy-Uri option is as defined in Proxy processing of the (Outer) Proxy-Uri option is as defined in
[RFC7252]. [RFC7252].
Proxy processing of the (Outer) Block options is as defined in Proxy processing of the (Outer) Block options is as defined in
[RFC7959]. [RFC7959].
Proxy processing of the (Outer) Observe option is as defined in Proxy processing of the (Outer) Observe option is as defined in
[RFC7641]. OSCORE-aware proxies MAY look at the Partial IV value [RFC7641]. OSCORE-aware proxies may look at the Partial IV value
instead of the Outer Observe option. instead of the Outer Observe option.
10.2. HTTP Processing 11. HTTP Operations
In order to use OSCORE over HTTP hops, a node needs to be able to map
HTTP messages to CoAP messages (see [RFC8075]), and to apply OSCORE
to CoAP messages (as defined in this document).
For this purpose, this specification defines a new HTTP header field
named CoAP-Object-Security, see Section 12.4. The CoAP-Object-
Security header field is only used in POST requests and 200 (OK)
responses, i.e. essentially using HTTP as a transport of an encrypted
CoAP mappable message contained in the payload.
The header field is neither appropriate to list in the Connection The CoAP request/response model may be mapped to HTTP and vice versa
header field (see Section 6.1 of [RFC7230]), nor in a Vary response as described in Section 10 of [RFC7252]. The HTTP-CoAP mapping is
header field (see Section 7.1.4 of [RFC7231]), nor allowed in further detailed in [RFC8075]. This section defines the components
trailers (see Section 4.1 of [RFC7230]). needed to map and transport OSCORE messages over HTTP hops. By
mapping between HTTP and CoAP and by using cross-protocol proxies
OSCORE may be used end-to-end between e.g. an HTTP client and a CoAP
server. Examples are provided at the end of the section.
[Ed. Note: Reconsider use of Vary] 11.1. The HTTP OSCORE Header Field
Intermediaries cannot insert, delete, or modify the field's value The HTTP OSCORE Header Field (see Section 13.4) is used for carrying
without being detected. The header field is not preserved across the content of the CoAP OSCORE option when transporting OSCORE
redirects. messages over HTTP hops.
[Ed. Note: Reconsider support for redirects] The HTTP OSCORE header field is only used in POST requests and 200
(OK) responses. When used, the HTTP header field Content-Type is set
to 'application/oscore' (see Section 13.5) indicating that the HTTP
body of this message contains the OSCORE payload (see Section 6.2}.
No additional semantics is provided by other message fields.
Using the Augmented Backus-Naur Form (ABNF) notation of [RFC5234], Using the Augmented Backus-Naur Form (ABNF) notation of [RFC5234],
including the following core ABNF syntax rules defined by that including the following core ABNF syntax rules defined by that
specification: ALPHA (letters) and DIGIT (decimal digits), the CoAP- specification: ALPHA (letters) and DIGIT (decimal digits), the HTTP
Object-Security header field is as follows. OSCORE header field value is as follows.
base64-char = ALPHA / DIGIT / "_" / "-"
CoAP-Object-Security = 2*base64-char base64url-char = ALPHA / DIGIT / "-" / "_"
A sending endpoint uses [RFC8075] to translate an HTTP message into a OSCORE = 2*base64url-char
CoAP message. It then protects the message with OSCORE processing, The HTTP OSCORE header field is not appropriate to list in the
and adds the Object-Security option (as defined in this document). Connection header field (see Section 6.1 of [RFC7230]) since it is
Then, the endpoint maps the resulting CoAP message to an HTTP message not hop-by-hop. The HTTP OSCORE header field is not appropriate to
that includes the HTTP header field CoAP-Object-Security, whose value list in a Vary response header field (see Section 7.1.4 of [RFC7231])
is: since a cached response would in general not be useful for other
clients. The HTTP OSCORE header field is not useful in trailers (see
Section 4.1 of [RFC7230]).
o "" if the CoAP Object-Security option is empty, or Intermediaries are in general not allowed to insert, delete, or
modify the OSCORE header. Changes to the HTTP OSCORE header field
will in general violate the integrity of the OSCORE message resulting
in an error. For the same reason the HTTP OSCORE header field is in
general not preserved across redirects. A CoAP-to-HTTP proxy
receiving a request for redirect may copy the HTTP OSCORE header
field to the new request, although the condition for this being
successful is that the server to which the OSCORE message is
redirected needs to be a clone of the server for which the OSCORE
message was intended (same target resource, same OSCORE security
context etc.). If an HTTP/OSCORE client receives a redirect it
should instead generate a new OSCORE request for the server it was
redirected to.
o the value of the CoAP Object-Security option (Section 6.1) in 11.2. CoAP-to-HTTP Mapping
base64url encoding (Section 5 of [RFC4648]) without padding (see
[RFC7515] Appendix C for implementation notes for this encoding).
Note that the value of the HTTP body is the CoAP payload, i.e. the Section 10.1 of [RFC7252] describes the fundamentals of the CoAP-to-
OSCORE payload (Section 6.2). HTTP cross-protocol mapping process. The additional rules for OSCORE
messages are:
The HTTP header field Content-Type is set to 'application/oscore' o The HTTP OSCORE header field value is set to
(see Section 12.5).
The resulting message is an OSCORE message that uses HTTP. * AA if the CoAP OSCORE option is empty, otherwise
A receiving endpoint uses [RFC8075] to translate an HTTP message into * the value of the CoAP OSCORE option (Section 6.1) in base64url
a CoAP message, with the following addition. The HTTP message (Section 5 of [RFC4648]) encoding without padding.
includes the CoAP-Object-Security header field, which is mapped to Implementation notes for this encoding are given in Appendix C
the CoAP Object-Security option in the following way. The CoAP of [RFC7515].
Object-Security option value is:
o empty if the value of the HTTP CoAP-Object-Security header field o The HTTP Content-Type is set to 'application/oscore' (see
is a single zero byte (0x00) represented by AA Section 13.5), independent of CoAP Content-Format.
o the value of the HTTP CoAP-Object-Security header field decoded 11.3. HTTP-to-CoAP Mapping
from base64url (Section 5 of [RFC4648]) without padding (see
[RFC7515] Appendix C for implementation notes for this decoding).
Note that the value of the CoAP payload is the HTTP body, i.e. the Section 10.2 of [RFC7252] and [RFC8075] specify the behavior of an
OSCORE payload (Section 6.2). HTTP-to-CoAP proxy. The additional rules for HTTP messages with the
OSCORE header field are:
The resulting message is an OSCORE message that uses CoAP. o The CoAP OSCORE option is set as follows:
The endpoint can then verify the message according to the OSCORE * empty if the value of the HTTP OSCORE header field is a single
processing and get a verified CoAP message. It can then translate zero byte (0x00) represented by AA, otherwise
the verified CoAP message into a verified HTTP message.
10.3. HTTP-to-CoAP Translation Proxy * the value of the HTTP OSCORE header field decoded from
base64url (Section 5 of [RFC4648]) without padding.
Implementation notes for this encoding are given in Appendix C
of [RFC7515].
Section 10.2 of [RFC7252] and [RFC8075] specify the behavior of an o The CoAP Content-Format option is omitted, the content format for
HTTP-to-CoAP proxy. As requested in Section 1 of [RFC8075], this OSCORE (Section 13.6) MUST NOT be used.
section describes the HTTP mapping for the OSCORE protocol extension
of CoAP.
The presence of the Object-Security option, both in requests and 11.4. HTTP Endpoints
responses, is expressed in an HTTP header field named CoAP-Object-
Security in the mapped request or response. The value of the field
is:
o AA if the CoAP Object-Security option is empty, or Restricted to subsets of HTTP and CoAP supporting a bijective
mapping, OSCORE can be originated or terminated in HTTP endpoints.
o the value of the CoAP Object-Security option (Section 6.1) in The sending HTTP endpoint uses [RFC8075] to translate the HTTP
base64url encoding (Section 5 of [RFC4648]) without padding (see message into a CoAP message. The CoAP message is then processed with
[RFC7515] Appendix C for implementation notes for this encoding). OSCORE as defined in this document. The OSCORE message is then
mapped to HTTP as described in Section 11.2 and sent in compliance
with the rules in Section 11.1.
The header field Content-Type 'application/oscore' (see Section 12.5) The receiving HTTP endpoint maps the HTTP message to a CoAP message
is used for OSCORE messages transported in HTTP. The CoAP Content- using [RFC8075] and Section 11.3. The resulting OSCORE message is
Format option is omitted for OSCORE messages transported in CoAP. processed as defined in this document. If successful, the plaintext
CoAP message is translated to HTTP for normal processing in the
endpoint.
The value of the body is the OSCORE payload (Section 6.2). 11.5. Example: HTTP Client and CoAP Server
Example: This section is giving an example of how a request and a response
between an HTTP client and a CoAP server could look like. The
example is not a test vector but intended as an illustration of how
the message fields are translated in the different steps.
Mapping and notation here is based on "Simple Form" (Section 5.4.1.1 Mapping and notation here is based on "Simple Form" (Section 5.4.1 of
of [RFC8075]). [RFC8075]).
[HTTP request -- Before client object security processing] [HTTP request -- Before client object security processing]
GET http://proxy.url/hc/?target_uri=coap://server.url/orders GET http://proxy.url/hc/?target_uri=coap://server.url/orders
HTTP/1.1 HTTP/1.1
[HTTP request -- HTTP Client to Proxy] [HTTP request -- HTTP Client to Proxy]
POST http://proxy.url/hc/?target_uri=coap://server.url/ HTTP/1.1 POST http://proxy.url/hc/?target_uri=coap://server.url/ HTTP/1.1
Content-Type: application/oscore Content-Type: application/oscore
CoAP-Object-Security: CSU OSCORE: CSU
Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary]
[CoAP request -- Proxy to CoAP Server] [CoAP request -- Proxy to CoAP Server]
POST coap://server.url/ POST coap://server.url/
Object-Security: 09 25 OSCORE: 09 25
Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary]
[CoAP request -- After server object security processing] [CoAP request -- After server object security processing]
GET coap://server.url/orders GET coap://server.url/orders
[CoAP response -- Before server object security processing] [CoAP response -- Before server object security processing]
2.05 Content 2.05 Content
Content-Format: 0 Content-Format: 0
Payload: Exterminate! Exterminate! Payload: Exterminate! Exterminate!
[CoAP response -- CoAP Server to Proxy] [CoAP response -- CoAP Server to Proxy]
2.04 Changed 2.04 Changed
Object-Security: [empty] OSCORE: [empty]
Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary]
[HTTP response -- Proxy to HTTP Client] [HTTP response -- Proxy to HTTP Client]
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/oscore Content-Type: application/oscore
CoAP-Object-Security: "" OSCORE: AA
Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary]
[HTTP response -- After client object security processing] [HTTP response -- After client object security processing]
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: text/plain Content-Type: text/plain
Body: Exterminate! Exterminate! Body: Exterminate! Exterminate!
Note that the HTTP Status Code 200 in the next-to-last message is the Note that the HTTP Status Code 200 in the next-to-last message is the
mapping of CoAP Code 2.04 (Changed), whereas the HTTP Status Code 200 mapping of CoAP Code 2.04 (Changed), whereas the HTTP Status Code 200
in the last message is the mapping of the CoAP Code 2.05 (Content), in the last message is the mapping of the CoAP Code 2.05 (Content),
which was encrypted within the compressed COSE object carried in the which was encrypted within the compressed COSE object carried in the
Body of the HTTP response. Body of the HTTP response.
10.4. CoAP-to-HTTP Translation Proxy 11.6. Example: CoAP Client and HTTP Server
Section 10.1 of [RFC7252] describes the behavior of a CoAP-to-HTTP
proxy. RFC 8075 [RFC8075] does not cover this direction in any more
detail and so an example instantiation of Section 10.1 of [RFC7252]
is used below.
Example: This section is giving an example of how a request and a response
between a CoAP client and an HTTP server could look like. The
example is not a test vector but intended as an illustration of how
the message fields are translated in the different steps
[CoAP request -- Before client object security processing] [CoAP request -- Before client object security processing]
GET coap://proxy.url/ GET coap://proxy.url/
Proxy-Uri=http://server.url/orders Proxy-Uri=http://server.url/orders
[CoAP request -- CoAP Client to Proxy] [CoAP request -- CoAP Client to Proxy]
POST coap://proxy.url/ POST coap://proxy.url/
Proxy-Uri=http://server.url/ Proxy-Uri=http://server.url/
Object-Security: 09 25 OSCORE: 09 25
Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary]
[HTTP request -- Proxy to HTTP Server] [HTTP request -- Proxy to HTTP Server]
POST http://server.url/ HTTP/1.1 POST http://server.url/ HTTP/1.1
Content-Type: application/oscore Content-Type: application/oscore
CoAP-Object-Security: CSU OSCORE: CSU
Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary]
[HTTP request -- After server object security processing] [HTTP request -- After server object security processing]
GET http://server.url/orders HTTP/1.1 GET http://server.url/orders HTTP/1.1
[HTTP response -- Before server object security processing] [HTTP response -- Before server object security processing]
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: text/plain Content-Type: text/plain
Body: Exterminate! Exterminate! Body: Exterminate! Exterminate!
[HTTP response -- HTTP Server to Proxy] [HTTP response -- HTTP Server to Proxy]
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/oscore Content-Type: application/oscore
CoAP-Object-Security: "" OSCORE: AA
Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary]
[CoAP response - Proxy to CoAP Client] [CoAP response -- Proxy to CoAP Client]
2.04 Changed 2.04 Changed
Object-Security: [empty] OSCORE: [empty]
Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary]
[CoAP response -- After client object security processing] [CoAP response -- After client object security processing]
2.05 Content 2.05 Content
Content-Format: 0 Content-Format: 0
Payload: Exterminate! Exterminate! Payload: Exterminate! Exterminate!
Note that the HTTP Code 2.04 (Changed) in the next-to-last message is Note that the HTTP Code 2.04 (Changed) in the next-to-last message is
the mapping of HTTP Status Code 200, whereas the CoAP Code 2.05 the mapping of HTTP Status Code 200, whereas the CoAP Code 2.05
(Content) in the last message is the value that was encrypted within (Content) in the last message is the value that was encrypted within
the compressed COSE object carried in the Body of the HTTP response. the compressed COSE object carried in the Body of the HTTP response.
11. Security Considerations 12. Security Considerations
11.1. End-to-end protection An overview of the security properties is given in Appendix D.
12.1. End-to-end Protection
In scenarios with intermediary nodes such as proxies or gateways, In scenarios with intermediary nodes such as proxies or gateways,
transport layer security such as (D)TLS only protects data hop-by- transport layer security such as (D)TLS only protects data hop-by-
hop. As a consequence, the intermediary nodes can read and modify hop. As a consequence, the intermediary nodes can read and modify
information. The trust model where all intermediary nodes are any information. The trust model where all intermediary nodes are
considered trustworthy is problematic, not only from a privacy considered trustworthy is problematic, not only from a privacy
perspective, but also from a security perspective, as the perspective, but also from a security perspective, as the
intermediaries are free to delete resources on sensors and falsify intermediaries are free to delete resources on sensors and falsify
commands to actuators (such as "unlock door", "start fire alarm", commands to actuators (such as "unlock door", "start fire alarm",
"raise bridge"). Even in the rare cases where all the owners of the "raise bridge"). Even in the rare cases where all the owners of the
intermediary nodes are fully trusted, attacks and data breaches make intermediary nodes are fully trusted, attacks and data breaches make
such an architecture brittle. such an architecture brittle.
(D)TLS protects hop-by-hop the entire message. 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. The CoAP messaging layer, including point and intermediary node. In particular when OSCORE is used with
header fields such as Type and Message ID, as well as CoAP message HTTP, the additional TLS protection of HTTP hops is recommended, e.g.
fields Token and Token Length may be changed by a proxy and thus between an HTTP endpoint and a proxy translating between HTTP and
cannot be protected end-to-end. Error messages occurring during CoAP CoAP.
processing are protected end-to-end. Error messages occurring during
OSCORE processing are not always possible to protect, e.g. if the
receiving endpoint cannot locate the right security context. It may
still be favorable to send an unprotected error message, e.g. to
prevent extensive retransmissions, so unprotected error messages are
allowed as specified. Similar to error messages, signaling messages
are not always possible to protect as they may be intended for an
intermediary. Hop-by-hop protection of signaling messages can be
achieved with (D)TLS. Applications using unprotected error and
signaling messages need to consider the threat that these messages
may be spoofed.
11.2. Security Context Establishment The consequences of unprotected message fields are analyzed in
Appendix D.4. Error messages occurring during CoAP processing are
protected end-to-end. Error messages occurring during OSCORE
processing are not always possible to protect, e.g. if the receiving
endpoint cannot locate the right security context. It may still be
favorable to send an unprotected error message, e.g. to prevent
extensive retransmissions, so unprotected error messages are allowed
as specified. Similar to error messages, signaling messages are not
always possible to protect as they may be intended for an
intermediary. Applications using unprotected error and signaling
messages need to consider the threat that these messages may be
spoofed.
The use of COSE to protect messages as specified in this document 12.2. Security Context Establishment
requires an established security context. The method to establish
the security context described in Section 3.2 is based on a common
keying material in client and server, which may be obtained, e.g., by
using the ACE framework [I-D.ietf-ace-oauth-authz]. An OSCORE
profile of ACE is described in [I-D.ietf-ace-oscore-profile]. The
key establishement procedure need to ensure same key is not installed
twice, even in error situations.
11.3. Replay Protection The use of COSE_Encrypt0 and AEAD to protect messages as specified in
this document requires an established security context. The method
to establish the security context described in Section 3.2 is based
on a common Master Secret and unique Sender IDs. The necessary input
parameters may be pre-established or obtained using a key
establishment protocol augmented with establishment of Sender/
Recipient ID such as the OSCORE profile of the ACE framework
[I-D.ietf-ace-oscore-profile]. This procedure must ensure that the
requirements of the security context parameters are complied with
Section 3.3 for the intended use and also in error situations. It is
recommended to use a key establishment protocol which provides
forward secrecy whenever possible. Considerations for the deploying
OSCORE with a fixed Master Secret are given in Appendix B.
12.3. Master Secret
OSCORE uses HKDF [RFC5869] and the established input parameters to
derive the security context. The required properties of the security
context parameters are discussed in Section 3.3, in this section we
focus on the Master Secret. HKDF denotes in this specification the
composition of the expand and extract functions as defined in
[RFC5869] and the Master Secret is used as Input Key Material (IKM).
Informally, HKDF takes as source an IKM containing some good amount
of randomness but not necessarily distributed uniformly (or for which
an attacker has some partial knowledge) and derive from it one or
more cryptographically strong secret keys [RFC5869].
Therefore, the main requirement for the OSCORE Master Secret, in
addition to being secret, is that it is has a good amount of
randomness. The selected key establishment schemes must ensure that
the necessary properties for the Master Secret are fulfilled. For
pre-shared key deployments and key transport solutions such as
[I-D.ietf-ace-oscore-profile], the Master Secret can be generated
offline using a good random number generator.
12.4. Replay Protection
Most AEAD algorithms require a unique nonce for each message, for Most AEAD algorithms require a unique nonce for each message, for
which the sender sequence numbers in the COSE message field 'Partial which the sender sequence numbers in the COSE message field 'Partial
IV' is used. If the recipient accepts any sequence number larger IV' is used. If the recipient accepts any sequence number larger
than the one previously received, then the problem of sequence number than the one previously received, then the problem of sequence number
synchronization is avoided. With reliable transport, it may be synchronization is avoided. With reliable transport, it may be
defined that only messages with sequence number which are equal to defined that only messages with sequence number which are equal to
previous sequence number + 1 are accepted. The alternatives to previous sequence number + 1 are accepted. The alternatives to
sequence numbers have their issues: very constrained devices may not sequence numbers have their issues: very constrained devices may not
be able to support accurate time, or to generate and store large be able to support accurate time, or to generate and store large
numbers of random nonces. The requirement to change key at counter numbers of random nonces. The requirement to change key at counter
wrap is a complication, but it also forces the user of this wrap is a complication, but it also forces the user of this
specification to think about implementing key renewal. specification to think about implementing key renewal.
11.4. Cryptographic Considerations 12.5. Client Aliveness
A verified OSCORE request enables the server to verify the identity
of the entity who generated the message. However, it does not verify
that the client is currently involved in the communication, since the
message may be a delayed delivery of a previously generated request
which now reaches the server. To verify the aliveness of the client
the server may use the Echo option in the response to a request from
the client (see [I-D.ietf-core-echo-request-tag]).
12.6. Cryptographic Considerations
The maximum sender sequence number is dependent on the AEAD The maximum sender sequence number is dependent on the AEAD
algorithm. The maximum sender sequence number is 2^40 - 1, or any algorithm. The maximum sender sequence number is 2^40 - 1, or any
algorithm specific lower limit, after which a new security context algorithm specific lower limit, after which a new security context
must be generated. The mechanism to build the nonce (Section 5.2) must be generated. The mechanism to build the nonce (Section 5.2)
assumes that the nonce is at least 56 bits, and the Partial IV is at assumes that the nonce is at least 56 bits, and the Partial IV is at
most 40 bits. The mandatory-to-implement AEAD algorithm AES-CCM- most 40 bits. The mandatory-to-implement AEAD algorithm AES-CCM-
16-64-128 is selected for compatibility with CCM*. 16-64-128 is selected for compatibility with CCM*.
The security level of a system with m Masters Keys of length k used In order to prevent cryptanalysis when the same plaintext is
together with Master Salts with entropy n is k + n - log2(m). repeatedly encrypted by many different users with distinct keys, the
Similarly, the security level of a system with m AEAD keys of length nonce is formed by mixing the sequence number with a secret per-
k used together with AEAD nonces of length n is k + n - log2(m). context initialization vector (Common IV) derived along with the keys
Security level here means that an attacker can recover one of the m (see Section 3.1 of [RFC8152]), and by using a Master Salt in the key
keys with complexity 2^(k + n) / m. Protection against such attacks derivation (see [MF00] for an overview). The Master Secret, Sender
can be provided by increasing the size of the keys or the entropy of Key, Recipient Key, and Common IV must be secret, the rest of the
the Master Salt. The complexity of recovering a specific key is parameters may be public. The Master Secret must have a good amount
still 2^k (assuming the Master Salt/AEAD nonce is public) (see [MF00] of randomness (see Section 12.3)).
for a overview). The Master Secret, Sender Key, and Recipient Key
must be secret, the rest of the parameters may be public. The Master
Secret must be uniformly random.
11.5. Message 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
discards the message, if complying to the policy) may be obtained as discards the message, if complying to the policy) may be obtained as
part of normal resource discovery. part of normal resource discovery.
11.6. 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. In particular Uri-Host SHOULD NOT contain privacy information, see Appendix D.4. CoAP headers sent in plaintext allow,
sensitive information. CoAP headers sent in plaintext allow, for for example, matching of CON and ACK (CoAP Message Identifier),
example, matching of CON and ACK (CoAP Message Identifier), matching matching of request and responses (Token) and traffic analysis.
of request and responses (Token) and traffic analysis. OSCORE does OSCORE does not provide protection for HTTP header fields which are
not provide protection for HTTP header fields which are not CoAP- not both CoAP-mappable and class E. The HTTP message fields which
mappable. are visible to on-path entity are only used for the purpose of
transporting the OSCORE message, whereas the application layer
message is encoded in CoAP and encrypted.
Unprotected error messages reveal information about the security Unprotected error messages reveal information about the security
state in the communication between the endpoints. Unprotected state in the communication between the endpoints. Unprotected
signalling messages reveal information about the reliable transport signaling messages reveal information about the reliable transport
used on a leg of the path. Using the mechanisms described in used on a leg of the path. Using the mechanisms described in
Section 7.5 may reveal when a device goes through a reboot. This can Section 7.5 may reveal when a device goes through a reboot. This can
be mitigated by the device storing the precise state of sender be mitigated by the device storing the precise state of sender
sequence number and replay window on a clean shutdown. sequence number and replay window on a clean shutdown.
The length of message fields can reveal information about the The length of message fields can reveal information about the
message. Applications may use a padding scheme to protect against message. Applications may use a padding scheme to protect against
traffic analysis. traffic analysis.
12. 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 "TBD" in this Note to IANA: Please note all occurrences of "TBDx" in this
specification should be assigned the same number. specification should be assigned the same number.
12.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: TBD1 (Integer value between 1 and 255) o Label: TBD2
o Value Type: bstr o Value Type: bstr
o Value Registry: o Value Registry:
o Description: kid context o Description: Identifies the kid context
o Reference: Section 5.1 of this document o Reference: Section 5.1 of this document
12.2. CoAP Option Numbers Registry Note to IANA: Label assignment in (Integer value between 1 and 255)
is requested. (RFC Editor: Delete this note after IANA assignment)
The Object-Security option is added to the CoAP Option Numbers 13.2. CoAP Option Numbers Registry
registry:
The OSCORE option is added to the CoAP Option Numbers registry:
+--------+-----------------+-------------------+ +--------+-----------------+-------------------+
| Number | Name | Reference | | Number | Name | Reference |
+--------+-----------------+-------------------+ +--------+-----------------+-------------------+
| TBD | Object-Security | [[this document]] | | TBD1 | OSCORE | [[this document]] |
+--------+-----------------+-------------------+ +--------+-----------------+-------------------+
12.3. CoAP Signaling Option Numbers Registry 13.3. CoAP Signaling Option Numbers Registry
The Object-Security option is added to the CoAP Signaling Option The OSCORE option is added to the CoAP Signaling Option Numbers
Numbers registry: registry:
+------------+--------+---------------------+-------------------+ +------------+--------+---------------------+-------------------+
| Applies to | Number | Name | Reference | | Applies to | Number | Name | Reference |
+------------+--------+---------------------+-------------------+ +------------+--------+---------------------+-------------------+
| 7.xx (any) | TBD | Object-Security | [[this document]] | | 7.xx (any) | TBD1 | OSCORE | [[this document]] |
+------------+--------+---------------------+-------------------+ +------------+--------+---------------------+-------------------+
12.4. Header Field Registrations 13.4. Header Field Registrations
The HTTP header field CoAP-Object-Security is added to the Message The HTTP OSCORE header field is added to the Message Headers
Headers registry: registry:
+----------------------+----------+----------+-------------------+ +----------------------+----------+----------+-------------------+
| Header Field Name | Protocol | Status | Reference | | Header Field Name | Protocol | Status | Reference |
+----------------------+----------+----------+-------------------+ +----------------------+----------+----------+-------------------+
| CoAP-Object-Security | http | standard | [[this document]] | | OSCORE | http | standard | [[this document]] |
+----------------------+----------+----------+-------------------+ +----------------------+----------+----------+-------------------+
12.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. "Media Types" registry. These media types are used to indicate that
These media types are used to indicate that the content is an OSCORE the content is an OSCORE message. The OSCORE body cannot be
message. understood without the OSCORE header field value and the security
context.
Type name: application Type name: application
Subtype name: oscore Subtype name: oscore
Required parameters: N/A Required parameters: N/A
Optional parameters: N/A Optional parameters: N/A
Encoding considerations: binary Encoding considerations: binary
skipping to change at page 49, line 5 skipping to change at page 51, line 5
Intended usage: COMMON Intended usage: COMMON
Restrictions on usage: N/A Restrictions on usage: N/A
Author: Goeran Selander, goran.selander@ericsson.com Author: Goeran Selander, goran.selander@ericsson.com
Change Controller: IESG Change Controller: IESG
Provisional registration? No Provisional registration? No
12.6. CoAP Content-Formats Registry 13.6. CoAP Content-Formats Registry
TODO Note to IANA: ID assignment in the 10000-64999 range is requested.
(RFC Editor: Delete this note after IANA assignment)
13. References This section registers the media type 'application/oscore' media type
in the "CoAP Content-Format" registry. This Content-Format for the
OSCORE payload is defined for potential future use cases and SHALL
NOT be used in the OSCORE message. The OSCORE payload cannot be
understood without the OSCORE option value and the security context.
13.1. Normative References +----------------------+----------+----------+-------------------+
| Media Type | Encoding | ID | Reference |
+----------------------+----------+----------+-------------------+
| application/oscore | | TBD3 | [[this document]] |
+----------------------+----------+----------+-------------------+
14. References
14.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
<https://www.rfc-editor.org/info/rfc4648>. <https://www.rfc-editor.org/info/rfc4648>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008, DOI 10.17487/RFC5234, January 2008,
<https://www.rfc-editor.org/info/rfc5234>. <https://www.rfc-editor.org/info/rfc5234>.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246,
DOI 10.17487/RFC5246, August 2008,
<https://www.rfc-editor.org/info/rfc5246>.
[RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer
Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347,
January 2012, <https://www.rfc-editor.org/info/rfc6347>. January 2012, <https://www.rfc-editor.org/info/rfc6347>.
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
October 2013, <https://www.rfc-editor.org/info/rfc7049>. October 2013, <https://www.rfc-editor.org/info/rfc7049>.
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Message Syntax and Routing", Protocol (HTTP/1.1): Message Syntax and Routing",
skipping to change at page 50, line 5 skipping to change at page 52, line 20
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Semantics and Content", RFC 7231, Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
DOI 10.17487/RFC7231, June 2014, DOI 10.17487/RFC7231, June 2014,
<https://www.rfc-editor.org/info/rfc7231>. <https://www.rfc-editor.org/info/rfc7231>.
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252, Application Protocol (CoAP)", RFC 7252,
DOI 10.17487/RFC7252, June 2014, DOI 10.17487/RFC7252, June 2014,
<https://www.rfc-editor.org/info/rfc7252>. <https://www.rfc-editor.org/info/rfc7252>.
[RFC7390] Rahman, A., Ed. and E. Dijk, Ed., "Group Communication for
the Constrained Application Protocol (CoAP)", RFC 7390,
DOI 10.17487/RFC7390, October 2014,
<https://www.rfc-editor.org/info/rfc7390>.
[RFC7641] Hartke, K., "Observing Resources in the Constrained [RFC7641] Hartke, K., "Observing Resources in the Constrained
Application Protocol (CoAP)", RFC 7641, Application Protocol (CoAP)", RFC 7641,
DOI 10.17487/RFC7641, September 2015, DOI 10.17487/RFC7641, September 2015,
<https://www.rfc-editor.org/info/rfc7641>. <https://www.rfc-editor.org/info/rfc7641>.
[RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in
the Constrained Application Protocol (CoAP)", RFC 7959, the Constrained Application Protocol (CoAP)", RFC 7959,
DOI 10.17487/RFC7959, August 2016, DOI 10.17487/RFC7959, August 2016,
<https://www.rfc-editor.org/info/rfc7959>. <https://www.rfc-editor.org/info/rfc7959>.
skipping to change at page 51, line 5 skipping to change at page 53, line 11
[RFC8288] Nottingham, M., "Web Linking", RFC 8288, [RFC8288] Nottingham, M., "Web Linking", RFC 8288,
DOI 10.17487/RFC8288, October 2017, DOI 10.17487/RFC8288, October 2017,
<https://www.rfc-editor.org/info/rfc8288>. <https://www.rfc-editor.org/info/rfc8288>.
[RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K.,
Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained
Application Protocol) over TCP, TLS, and WebSockets", Application Protocol) over TCP, TLS, and WebSockets",
RFC 8323, DOI 10.17487/RFC8323, February 2018, RFC 8323, DOI 10.17487/RFC8323, February 2018,
<https://www.rfc-editor.org/info/rfc8323>. <https://www.rfc-editor.org/info/rfc8323>.
13.2. Informative References 14.2. Informative References
[I-D.bormann-6lo-coap-802-15-ie] [I-D.bormann-6lo-coap-802-15-ie]
Bormann, C., "Constrained Application Protocol (CoAP) over Bormann, C., "Constrained Application Protocol (CoAP) over
IEEE 802.15.4 Information Element for IETF", draft- IEEE 802.15.4 Information Element for IETF", draft-
bormann-6lo-coap-802-15-ie-00 (work in progress), April bormann-6lo-coap-802-15-ie-00 (work in progress), April
2016. 2016.
[I-D.hartke-core-e2e-security-reqs] [I-D.hartke-core-e2e-security-reqs]
Selander, G., Palombini, F., and K. Hartke, "Requirements Selander, G., Palombini, F., and K. Hartke, "Requirements
for CoAP End-To-End Security", draft-hartke-core-e2e- for CoAP End-To-End Security", draft-hartke-core-e2e-
security-reqs-03 (work in progress), July 2017. security-reqs-03 (work in progress), July 2017.
[I-D.ietf-6tisch-minimal-security] [I-D.ietf-6tisch-minimal-security]
Vucinic, M., Simon, J., Pister, K., and M. Richardson, Vucinic, M., Simon, J., Pister, K., and M. Richardson,
"Minimal Security Framework for 6TiSCH", draft-ietf- "Minimal Security Framework for 6TiSCH", draft-ietf-
6tisch-minimal-security-05 (work in progress), March 2018. 6tisch-minimal-security-05 (work in progress), March 2018.
[I-D.ietf-ace-oauth-authz] [I-D.ietf-ace-oauth-authz]
Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and
H. Tschofenig, "Authentication and Authorization for H. Tschofenig, "Authentication and Authorization for
Constrained Environments (ACE)", draft-ietf-ace-oauth- Constrained Environments (ACE) using the OAuth 2.0
authz-10 (work in progress), February 2018. Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-11
(work in progress), March 2018.
[I-D.ietf-ace-oscore-profile] [I-D.ietf-ace-oscore-profile]
Seitz, L., Palombini, F., Gunnarsson, M., and G. Selander, Seitz, L., Palombini, F., Gunnarsson, M., and G. Selander,
"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-01 (work in progress), March 2018. oscore-profile-01 (work in progress), March 2018.
[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
skipping to change at page 52, line 8 skipping to change at page 54, line 13
progress), March 2018. progress), March 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- "Secure group communication for CoAP", draft-ietf-core-
oscore-groupcomm-01 (work in progress), March 2018. oscore-groupcomm-01 (work in progress), March 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-04 (work in progress), March mattsson-core-coap-actuators-05 (work in progress), March
2018. 2018.
[MF00] McGrew, D. and S. Fluhrer, "Attacks on Encryption of
Redundant Plaintext and Implications on Internet
Security", the Proceedings of the Seventh Annual Workshop
on Selected Areas in Cryptography (SAC 2000), Springer-
Verlag. , 2000.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005, RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>. <https://www.rfc-editor.org/info/rfc3986>.
[RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated
Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008,
<https://www.rfc-editor.org/info/rfc5116>. <https://www.rfc-editor.org/info/rfc5116>.
[RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand
Key Derivation Function (HKDF)", RFC 5869, Key Derivation Function (HKDF)", RFC 5869,
DOI 10.17487/RFC5869, May 2010, DOI 10.17487/RFC5869, May 2010,
<https://www.rfc-editor.org/info/rfc5869>. <https://www.rfc-editor.org/info/rfc5869>.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, DOI 10.17487/RFC6690, August 2012,
<https://www.rfc-editor.org/info/rfc6690>.
[RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for
Constrained-Node Networks", RFC 7228, Constrained-Node Networks", RFC 7228,
DOI 10.17487/RFC7228, May 2014, DOI 10.17487/RFC7228, May 2014,
<https://www.rfc-editor.org/info/rfc7228>. <https://www.rfc-editor.org/info/rfc7228>.
[RFC7390] Rahman, A., Ed. and E. Dijk, Ed., "Group Communication for
the Constrained Application Protocol (CoAP)", RFC 7390,
DOI 10.17487/RFC7390, October 2014,
<https://www.rfc-editor.org/info/rfc7390>.
[RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
2015, <https://www.rfc-editor.org/info/rfc7515>. 2015, <https://www.rfc-editor.org/info/rfc7515>.
[RFC7967] Bhattacharyya, A., Bandyopadhyay, S., Pal, A., and T. [RFC7967] Bhattacharyya, A., Bandyopadhyay, S., Pal, A., and T.
Bose, "Constrained Application Protocol (CoAP) Option for Bose, "Constrained Application Protocol (CoAP) Option for
No Server Response", RFC 7967, DOI 10.17487/RFC7967, No Server Response", RFC 7967, DOI 10.17487/RFC7967,
August 2016, <https://www.rfc-editor.org/info/rfc7967>. August 2016, <https://www.rfc-editor.org/info/rfc7967>.
Appendix A. Scenario Examples Appendix A. Scenario Examples
skipping to change at page 53, line 9 skipping to change at page 55, line 28
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
| | | Object-Security: [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
| | | Object-Security: [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
| | | Object-Security: - | | | OSCORE: -
| | | Payload: {Code:2.05, "OFF"} | | | Payload: {Code:2.05, "OFF"}
| | | | | |
|<------+ | Code: 2.04 (Changed) |<------+ | Code: 2.04 (Changed)
| 2.04 | | Token: 0x8c | 2.04 | | Token: 0x8c
| | | Object-Security: - | | | OSCORE: -
| | | Payload: {Code:2.05, "OFF"} | | | Payload: {Code:2.05, "OFF"}
| | | | | |
Figure 11: Secure Access to Sensor. Square brackets [ ... ] indicate Figure 12: Secure Access to Sensor. Square brackets [ ... ] indicate
content of compressed COSE object. Curly brackets { ... } indicate content of compressed COSE object. Curly brackets { ... } indicate
encrypted data. encrypted data.
The request/response Codes are encrypted by OSCORE and only dummy The request/response Codes are encrypted by OSCORE and only dummy
Codes (POST/Changed) are visible in the header of the OSCORE message. Codes (POST/Changed) are visible in the header of the OSCORE message.
The option Uri-Path ("alarm_status") and payload ("OFF") are The option Uri-Path ("alarm_status") and payload ("OFF") are
encrypted. encrypted.
The COSE header of the request contains an identifier (5f), The COSE header of the request contains an identifier (5f),
indicating which security context was used to protect the message and indicating which security context was used to protect the message and
skipping to change at page 54, line 8 skipping to change at page 56, line 28
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
| | | Object-Security: [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
| | | Object-Security: [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.04 (Changed) | |<------+ Code: 2.05 (Content)
| | 2.04 | Token: 0xbe | | 2.05 | Token: 0xbe
| | | Observe: 7 | | | Observe: 7
| | | Object-Security: [Partial IV:32] | | | OSCORE: [Partial IV:32]
| | | Payload: {Code:2.05, | | | Payload: {Code:2.05,
| | | Content-Format:0, "220"} | | | Content-Format:0, "220"}
| | | | | |
|<------+ | Code: 2.04 (Changed) |<------+ | Code: 2.05 (Content)
| 2.04 | | Token: 0x83 | 2.05 | | Token: 0x83
| | | Observe: 7 | | | Observe: 7
| | | Object-Security: [Partial IV:32] | | | OSCORE: [Partial IV:32]
| | | Payload: {Code:2.05, | | | Payload: {Code:2.05,
| | | Content-Format:0, "220"} | | | Content-Format:0, "220"}
... ... ... ... ... ...
| | | | | |
| |<------+ Code: 2.04 (Changed) | |<------+ Code: 2.05 (Content)
| | 2.04 | Token: 0xbe | | 2.05 | Token: 0xbe
| | | Observe: 8 | | | Observe: 8
| | | Object-Security: [Partial IV:36] | | | OSCORE: [Partial IV:36]
| | | Payload: {Code:2.05, | | | Payload: {Code:2.05,
| | | Content-Format:0, "180"} | | | Content-Format:0, "180"}
| | | | | |
|<------+ | Code: 2.04 (Changed) |<------+ | Code: 2.05 (Content)
| 2.04 | | Token: 0x83 | 2.05 | | Token: 0x83
| | | Observe: 8 | | | Observe: 8
| | | Object-Security: [Partial IV:36] | | | OSCORE: [Partial IV:36]
| | | Payload: {Code:2.05, | | | Payload: {Code:2.05,
| | | Content-Format:0, "180"} | | | Content-Format:0, "180"}
| | | | | |
Figure 12: Secure Subscribe to Sensor. Square brackets [ ... ] Figure 13: Secure Subscribe to Sensor. Square brackets [ ... ]
indicate content of compressed COSE object header. Curly brackets { indicate content of compressed COSE object header. Curly brackets {
... } indicate encrypted data. ... } indicate encrypted data.
The request/response Codes are encrypted by OSCORE and only dummy The dummy Codes (FETCH/Content) are visible in the header of the
Codes (FETCH/Changed) are visible in the header of the OSCORE OSCORE message to allow intermediary processing of Observe. The
message. The options Content-Format (0) and the payload ("220" and options Content-Format (0) and the payload ("220" and "180"), are
"180"), are encrypted. encrypted.
The COSE header of the request contains an identifier (ca), The COSE header of the request contains an identifier (ca),
indicating the security context used to protect the message and a indicating the security context used to protect the message and a
Partial IV (15). The COSE headers of the responses contains Partial Partial IV (15). The COSE headers of the responses contains Partial
IVs (32 and 36). IVs (32 and 36).
The server verifies that the Partial IV has not been received before. The server verifies that the Partial IV has not been received before.
The client verifies that the responses are bound to the request and The client verifies that the responses are bound to the request and
that the Partial IVs are greater than any Partial IV previously that the Partial IVs are greater than any Partial IV previously
received in a response bound to the request. received in a response bound to the request.
Appendix B. Deployment examples Appendix B. Deployment Examples
OSCORE may be deployed in a variety of settings, a few examples are Two examples complying with the requirements on the security context
given in this section. parameters (Section 3.3) are given in this section.
B.1. Master Secret Used Once B.1. Master Secret Used Once
For settings where the Master Secret is only used during deployment, For settings where the Master Secret is only used during deployment,
the uniqueness of AEAD nonce may be assured by persistent storage of the uniqueness of the AEAD nonce may be assured by persistent storage
the security context as described in this specification (see of the security context as described in this specification (see
Section 7.5). For many IoT deployments, a 128 bit uniformly random Section 7.5). For many IoT deployments, a 128 bit uniformly random
Master Key is sufficient for encrypting all data exchanged with the Master Key is sufficient for encrypting all data exchanged with the
IoT device throughout its lifetime. IoT device throughout its lifetime.
B.2. Master Secret Used Multiple Times B.2. Master Secret Used Multiple Times
In cases where the Master Secret needs to be used to derive multiple One Master Secret can be used to derive multiple security contexts if
security contexts, e.g. due to recommissioning or where the security unique Master Salts can be guaranteed. This may be useful e.g. in
context is not persistently stored, a stochastically unique Master case of recommissioning with reused Master Secret. In order to
Salt prevents the reuse of AEAD nonce and key. The Master Salt may prevent reuse of AEAD nonce and key, which would compromise the
be transported between client and server in the kid context parameter security, the Master Salt must never be used twice, even if the
(see Section 5.1) of the request. device is reset, recommissioned or in error cases. Examples of
failures include derivation of pseudorandom master salt from a static
seed, or a deterministic seeding procedure with inputs that are
repeated or can be replayed. Techniques for persistent storage of
security state may be used also in this case, to ensure uniqueness of
Master Salt.
In this section we give an example of a procedure which may be Assuming the Master Salts are indeed unique (or stochastically
implemented in client and server to establish the OSCORE security unique) we give an example of a procedure which may be implemented in
context based on pre-established input parameters (see Section 3.2) client and server to establish the OSCORE security context based on
except for the Master Salt which is transported in kid context. pre-established input parameters (see Section 3.2) except for the
Master Salt, which is transported in kid context parameter (see
Section 5.1) of the request.
1. In order to establish a security context with a server for the 1. In order to establish a security context with a server for the
first time, or a new security context replacing an old security first time, or a new security context replacing an old security
context, the client generates a (pseudo-)random uniformly context, the client generates a (pseudo-)random uniformly
distributed 64-bit Master Salt and derives the security context distributed 64-bit Master Salt and derives the security context
as specified in Section 3.2. The client protects a request with as specified in Section 3.2. The client protects a request with
the new Sender Context and sends the message with kid context set the new Sender Context and sends the message with kid context set
to the Master Salt. to the Master Salt.
2. The server, receiving an OSCORE request with a non-empty kid 2. The server, receiving an OSCORE request with a non-empty kid
skipping to change at page 56, line 39 skipping to change at page 59, line 17
this client that is now replaced by the new security context. this client that is now replaced by the new security context.
If the server receives a request without kid context from a client If the server receives a request without kid context from a client
with which no security context is established, then the server with which no security context is established, then the server
responds with a 4.01 Unauthorized error message with diagnostic responds with a 4.01 Unauthorized error message with diagnostic
payload containing the string "Security context not found". This payload containing the string "Security context not found". This
could be the result of the server having lost its security context or could be the result of the server having lost its security context or
that a new security context has not been successfully established, that a new security context has not been successfully established,
which may be a trigger for the client to run this procedure. which may be a trigger for the client to run this procedure.
B.3. Client Aliveness
The use of a single OSCORE request and response enables the client to
verify that the server's identity and aliveness through actual
communications. While a verified OSCORE request enables the server
to verify the identity of the entity who generated the message, it
does not verify that the client is currently involved in the
communication, since the message may be a delayed delivery of a
previously generated request which now reaches the server. To verify
the aliveness of the client the server may initiate an OSCORE
protected message exchange with the client, e.g. by switching the
roles of client and server as described in Section 3.1, or by using
the Echo option in the response to a request from the client
[I-D.ietf-core-echo-request-tag].
Appendix C. Test Vectors 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. CoAP messages using OSCORE.
C.1. Test Vector 1: Key Derivation with Master Salt C.1. Test Vector 1: Key Derivation with Master Salt
Given a set of inputs, OSCORE defines how to set up the Security Given a set of inputs, OSCORE defines how to set up the Security
Context in both the client and the server. The default values are Context in both the client and the server. The default values are
used for AEAD Algorithm and KDF. used for AEAD Algorithm and KDF.
skipping to change at page 59, line 39 skipping to change at page 61, line 48
Outputs: Outputs:
o Sender Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) o Sender Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes)
o Recipient Key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) o Recipient Key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes)
o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes)
C.3. Test Vector 3: OSCORE Request, Client C.3. Test Vector 3: OSCORE Request, Client
This section contains a test vector for a OSCORE protected CoAP GET This section contains a test vector for an OSCORE protected CoAP GET
request using the security context derived in Appendix C.1. The request using the security context derived in Appendix C.1. The
unprotected request only contains the Uri-Path option. unprotected request only contains the Uri-Path option.
Unprotected CoAP request: Unprotected CoAP request:
0x440149c60000f2a7396c6f63616c686f737483747631 (22 bytes) 0x440149c60000f2a7396c6f63616c686f737483747631 (22 bytes)
Common Context: Common Context:
o AEAD Algorithm: 10 (AES-CCM-16-64-128) o AEAD Algorithm: 10 (AES-CCM-16-64-128)
skipping to change at page 60, line 30 skipping to change at page 62, line 42
o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes) o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes)
o plaintext: 0x01b3747631 (5 bytes) o plaintext: 0x01b3747631 (5 bytes)
o encryption key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) o encryption key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes)
o nonce: 0xd0a1949aa253278f34c528d2d8 (13 bytes) o nonce: 0xd0a1949aa253278f34c528d2d8 (13 bytes)
From the previous parameter, the following is derived: From the previous parameter, the following is derived:
o Object-Security value: 0x091400 (3 bytes) o OSCORE option value: 0x091400 (3 bytes)
o ciphertext: 0x55b3710d47c611cd3924838a44 (13 bytes) o ciphertext: 0x55b3710d47c611cd3924838a44 (13 bytes)
From there: From there:
o Protected CoAP request (OSCORE message): 0x44026dd30000acc5396c6f6 o Protected CoAP request (OSCORE message): 0x44026dd30000acc5396c6f6
3616c686f7374d305091400ff55b3710d47c611cd3924838a44 (37 bytes) 3616c686f7374d305091400ff55b3710d47c611cd3924838a44 (37 bytes)
C.4. Test Vector 4: OSCORE Request, Client C.4. Test Vector 4: OSCORE Request, Client
This section contains a test vector for a OSCORE protected CoAP GET This section contains a test vector for an OSCORE protected CoAP GET
request using the security context derived in Appendix C.2. The request using the security context derived in Appendix C.2. The
unprotected request only contains the Uri-Path option. unprotected request only contains the Uri-Path option.
Unprotected CoAP request: Unprotected CoAP request:
0x440149c60000f2a7396c6f63616c686f737483747631 (22 bytes) 0x440149c60000f2a7396c6f63616c686f737483747631 (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
o Common IV: 0x01727733ab49ead385b18f7d91 (13 bytes) o Common IV: 0x01727733ab49ead385b18f7d91 (13 bytes)
Sender Context: Sender Context:
o Sender ID: 0x (0 bytes) o Sender ID: 0x (0 bytes)
o Sender Key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) o Sender Key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes)
skipping to change at page 61, line 34 skipping to change at page 63, line 48
o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes) o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes)
o plaintext: 0x01b3747631 (5 bytes) o plaintext: 0x01b3747631 (5 bytes)
o encryption key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) o encryption key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes)
o nonce: 0x01727733ab49ead385b18f7d85 (13 bytes) o nonce: 0x01727733ab49ead385b18f7d85 (13 bytes)
From the previous parameter, the following is derived: From the previous parameter, the following is derived:
o Object-Security value: 0x0914 (2 bytes) o OSCORE option value: 0x0914 (2 bytes)
o ciphertext: 0x6be9214aad448260ff1be1f594 (13 bytes) o ciphertext: 0x6be9214aad448260ff1be1f594 (13 bytes)
From there: From there:
o Protected CoAP request (OSCORE message): 0x44023bfc000066ef396c6f6 o Protected CoAP request (OSCORE message): 0x44023bfc000066ef396c6f6
3616c686f7374d2050914ff6be9214aad448260ff1be1f594 (36 bytes) 3616c686f7374d2050914ff6be9214aad448260ff1be1f594 (36 bytes)
C.5. Test Vector 5: OSCORE Response, Server C.5. Test Vector 5: OSCORE Response, Server
This section contains a test vector for a OSCORE protected 2.05 This section contains a test vector for an OSCORE protected 2.05
Content response to the request in Appendix C.3. The unprotected Content response to the request in Appendix C.3. 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. response does not contain a kid nor a Partial IV. Note that some
parameters are derived from the request.
Unprotected CoAP response: Unprotected CoAP response:
0x644549c60000f2a7ff48656c6c6f20576f726c6421 (21 bytes) 0x644549c60000f2a7ff48656c6c6f20576f726c6421 (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
o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes)
Sender Context: Sender Context:
skipping to change at page 62, line 34 skipping to change at page 64, line 49
o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes) o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes)
o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes) o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes)
o encryption key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) o encryption key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes)
o nonce: 0xd0a1949aa253278f34c528d2d8 (13 bytes) o nonce: 0xd0a1949aa253278f34c528d2d8 (13 bytes)
From the previous parameter, the following is derived: From the previous parameter, the following is derived:
o Object-Security value: 0x (0 bytes) o OSCORE option value: 0x (0 bytes)
o ciphertext: e4e8c28c41c8f31ca56eec24f6c71d94eacbcdffdc6d (22 o ciphertext: 0xe4e8c28c41c8f31ca56eec24f6c71d94eacbcdffdc6d (22
bytes) bytes)
From there: From there:
o Protected CoAP response (OSCORE message): 0x64446dd30000acc5d008ff o Protected CoAP response (OSCORE message): 0x64446dd30000acc5d008ff
e4e8c28c41c8f31ca56eec24f6c71d94eacbcdffdc6d (33 bytes) e4e8c28c41c8f31ca56eec24f6c71d94eacbcdffdc6d (33 bytes)
C.6. Test Vector 6: OSCORE Response with Partial IV, Server C.6. Test Vector 6: OSCORE Response with Partial IV, Server
This section contains a test vector for a OSCORE protected 2.05 This section contains a test vector for an OSCORE protected 2.05
Content response to the request in Appendix C.3. The unprotected Content response to the request in Appendix C.3. 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. response does not contain a kid, but contains a Partial IV. Note
that some parameters are derived from the request.
Unprotected CoAP response: Unprotected CoAP response:
0x644549c60000f2a7ff48656c6c6f20576f726c6421 (21 bytes) 0x644549c60000f2a7ff48656c6c6f20576f726c6421 (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 63, line 40 skipping to change at page 66, line 5
o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes) o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes)
o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes) o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes)
o encryption key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) o encryption key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes)
o nonce: 0xd0a1949aa253278e34c528d2cc (13 bytes) o nonce: 0xd0a1949aa253278e34c528d2cc (13 bytes)
From the previous parameter, the following is derived: From the previous parameter, the following is derived:
o Object-Security value: 0x0100 (2 bytes) o OSCORE option value: 0x0100 (2 bytes)
o ciphertext: 0xa7e3ca27f221f453c0ba68c350bf652ea096b328a1bf (22 o ciphertext: 0xa7e3ca27f221f453c0ba68c350bf652ea096b328a1bf (22
bytes) bytes)
From there: From there:
o Protected CoAP response (OSCORE message): 0x64442b130000b29ed20801 o Protected CoAP response (OSCORE message): 0x64442b130000b29ed20801
00ffa7e3ca27f221f453c0ba68c350bf652ea096b328a1bf (35 bytes) 00ffa7e3ca27f221f453c0ba68c350bf652ea096b328a1bf (35 bytes)
Appendix D. Overview of Security Properties Appendix D. Overview of Security Properties
skipping to change at page 64, line 22 skipping to change at page 66, line 32
translations. 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.
Requirements for CoAP end-to-end security are specified in Requirements for CoAP end-to-end security are specified in
[I-D.hartke-core-e2e-security-reqs]. The client and server are [I-D.hartke-core-e2e-security-reqs]. The client and server are
assumed to trust each other, but proxies and gateways are only assumed to be honest, but proxies and gateways are only trusted to
trusted to perform its intended operations. Forwarding is specified perform their intended operations. Forwarding is specified in
in Section 2.2.1 of [I-D.hartke-core-e2e-security-reqs]. HTTP-CoAP Section 2.2.1 of [I-D.hartke-core-e2e-security-reqs]. HTTP-CoAP
translation is specified in [RFC8075]. Intermediaries translating translation is specified in [RFC8075]. Intermediaries translating
between different transport layers are intended to perform just that. between different transport layers are intended to perform just that.
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.2. 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 using an AEAD algorithm. COSE_Encrypt0 object using an AEAD algorithm.
OSCORE depends on a pre-established strong Master Secret which can be OSCORE depends on a pre-established random Master Secret
used to derive keys, and a construction for making (key, nonce) pairs (Section 12.3) which can be used to derive keys, and a construction
unique (Appendix D.3). Assuming this is true, and the keys are used for making (key, nonce) pairs unique (Appendix D.3). Assuming this
for no more data than indicated in Section 7.2, OSCORE should provide is true, and the keys are used for no more data than indicated in
the following guarantees: Section 7.2, 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.
o Request-response binding: An attacker should not be able to make a o Request-response binding: An attacker should not be able to make a
client match a response to the wrong request. client match a response to the wrong request.
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 already accepted. receiver to accept a message which it has already accepted.
Informally, OSCORE provides these properties by AEAD-protecting the In the above, the attacker is anyone except the endpoints, e.g. a
plaintext with a strong key and uniqueness of (key, nonce) pairs. compromised intermediary. Informally, OSCORE provides these
AEAD encryption [RFC5116] provides confidentiality and integrity for properties by AEAD-protecting the plaintext with a strong key and
the data. Response-request binding is provided by including the kid uniqueness of (key, nonce) pairs. AEAD encryption [RFC5116] provides
and Partial IV of the request in the AAD of the response. Non- confidentiality and integrity for the data. Response-request binding
replayability of requests and notifications is provided by using is provided by including the kid and Partial IV of the request in the
unique (key, nonce) pairs and a replay protection mechanism AAD of the response. Non-replayability of requests and notifications
(application dependent, see Section 7.4). is provided by using unique (key, nonce) pairs and a 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.3. Uniqueness of (key, nonce)
In this section we show (key, nonce) pairs are not reused in the In this section we show that (key, nonce) pairs are unique as long as
encryption of OSCORE messages. the requirements Section 3.3 and Section 7.2 are followed.
Fix a Security Context complying with the requirements Section 3.3) Fix a security context and an endpoint, called the encrypting
and an endpoint. Endpoints may alternate between Client and Server endpoint. Endpoints may alternate between client and server roles,
roles, but each endpoint encrypts with the Sender Key of its Sender but each endpoint encrypts with the Sender Key of its Sender Context.
Context. Sender Keys are (stochastically) unique since they are Sender Keys are (stochastically) unique since they are derived with
derived with HKDF from unique Sender IDs, so messages encrypted by HKDF from unique Sender IDs, so messages encrypted by different
different endpoints use different keys. It remains to prove that the endpoints use different keys. It remains to prove that the nonces
nonces used by the fixed endpoint are unique. used by the fixed endpoint are unique.
Since the Common IV is fixed, the nonces are determined by a Partial Since the Common IV is fixed, the nonces are determined by a Partial
IV (PIV) and the Sender ID of the endpoint generating that Partial IV IV (PIV) and the Sender ID of the endpoint generating that Partial IV
(ID_PIV), and are unique for different (ID_PIV, PIV) pairs (ID_PIV). The nonce construction (Section 5.2) with the size of the
(Section 5.2). ID_PIV (S) creates unique nonces for different (ID_PIV, PIV) pairs.
For requests and notifications (GET Observe responses): For requests and responses with Partial IV (e.g. Observe
notifications):
o ID_PIV = Sender ID of the encrypting endpoint o ID_PIV = Sender ID of the encrypting endpoint
o PIV = current Partial IV of the encrypting endpoint o PIV = current Partial IV of the encrypting endpoint
Since the encrypting endpoint steps the Partial IV for each use, the Since the encrypting endpoint steps the Partial IV for each use, the
nonces used in requests and notifications are all unique as long as nonces used are all unique as long as the number of encrypted
the number of encrypted messages are kept within the required range messages is kept within the required range (Section 7.2).
(Section 7.2).
For responses to requests: For responses without Partial IV (i.e. single response to a request):
o ID_PIV = Sender ID of the endpoint generating the request o ID_PIV = Sender ID of the endpoint generating the request
o PIV = Partial IV of the request o PIV = Partial IV of the request
Since the request has been verified using the Recipient Context, Since the Sender IDs are unique, ID_PIV is different from the Sender
ID_PIV is the Sender ID of another endpoint and is thus different ID of the encrypting endpoint. Therefore, the nonce is different
from the Sender ID of the encrypting endpoint. Therefore the nonces compared to nonces where the encrypting endpoint generated the
used in responses are different compared to nonces in requests and Partial IV. Since the Partial IV of the request is verified for
notifications. Since the Partial IV of the request is verified for replay (Section 7.4) associated to this Recipient Context, PIV is
replay (Section 7.4), PIV is unique for responses and so are nonces unique for this ID_PIV.
used in responses.
Note that the argument does not depend on if the nonce in the first
response to GET Observe is generated as a notification or as a
response to a request. In the former case the Partial IV of the
encrypting endpoint is stepped. In the latter case, the nonce is in
the the requesting endpoint's subset of nonces and would otherwise
not be used by the encrypting endpoint.
The argumentation also holds for group communication as specified in The argumentation also holds for group communication as specified in
[RFC7390] although Observe is not used for that setting (see [RFC7390] (see [I-D.ietf-core-oscore-groupcomm]).
[I-D.ietf-core-oscore-groupcomm]).
D.4. Unprotected Message Fields D.4. Unprotected Message Fields
This section lists and discusses issues with unprotected CoAP message This section lists and discusses issues with unprotected message
fields. fields.
D.4.1. CoAP Header Fields D.4.1. CoAP Code
o Version
The CoAP version will be in plaintext. A change of this parameter is
potentially a denial of service attack. Currently there is only one
CoAP version defined. Future versions of CoAP need to analyse
attacks to OSCORE protected messages due to an adversary changing the
CoAP version.
o Token/Token Length
The Token field is a client-local identifier for differentiating
between concurrent requests. Change of Token is a denial of service
attack, since the client may not be able to identify the request or
verify integrity of the response, which depends on the request.
o Type/Message ID The CoAP Code of an OSCORE message is POST or FETCH for requests and
with corresponding response codes. Since the use of Observe is
indicated with the Outer Observe option, no additional information is
revealed by having a special codes for Observe messages. A change of
code does not affect the method of the end-to-end message but may be
a denial service attack caused by error in the OSCORE processing.
Other aspects of Observe are discussed in Appendix D.4.3.
These fields reveal information about the UDP transport binding. D.4.2. CoAP Header Fields
CoAP proxies are allowed to change Type and Message ID. These
message fields are not present in CoAP over TCP, and does not impact
the request/response message. A change of these fields is a denial
of service attack similar to changing UDP header fields.
o Length o Version. The CoAP version [RFC7252] is not expected to be
sensitive to disclose. Currently there is only one CoAP version
defined. A change of this parameter is potentially a denial of
service attack. Future versions of CoAP need to analyze attacks
to OSCORE protected messages due to an adversary changing the CoAP
version.
This field reveal information about the TCP transport binding. These o Token/Token Length. The Token field is a client-local identifier
message fields are not present in CoAP over UDP, and does not impact for differentiating between concurrent requests [RFC7252]. An
the request/response message. A change of Length is a denial of eavesdropper reading the token can match requests to responses
service attack similar to changing TCP header fields. which can be used in traffic analysis. CoAP proxies are allowed
to change Token and Token Length between UDP hops. However,
modifications of Token and Token Length during a UDP hop may
become a denial of service attack, since it may prevent the client
to identify to which request the response belongs or to find the
correct information to verify integrity of the response.
D.4.2. CoAP Options o Type/Message ID. The Type/Message ID fields [RFC7252] reveal
information about the UDP transport binding, e.g. an eavesdropper
reading the Type or Message ID gain information about how UDP
messages are related to each other. CoAP proxies are allowed to
change Type and Message ID. These message fields are not present
in CoAP over TCP, and does not impact the request/response
message. A change of these fields in a UDP hop is a denial of
service attack similar to changing UDP header fields.
o Max-Age o Length. This field contain the length of the message [RFC8323]
which may be used for traffic analysis. These message fields are
not present in CoAP over UDP, and does not impact the request/
response message. A change of Length is a denial of service
attack similar to changing TCP header fields.
The Outer Max-Age is used to avoid unnecessary caching of OSCORE D.4.3. CoAP Options
error responses. Changing this value is a potential denial of
service attack.
o Proxy-Uri/Proxy-Scheme/Uri-Host/Uri-Port o Max-Age. The Outer Max-Age is set to zero to avoid unnecessary
caching of OSCORE error responses. Changing this value thus may
cause unnecessary caching. No additional information is carried
with this option.
With OSCORE, the Proxy-Uri option does not contain the Uri-Path/Uri- o Proxy-Uri/Proxy-Scheme/Uri-Host/Uri-Port. With OSCORE, the Proxy-
Query parts of the URI. Proxy-Uri/Proxy-Scheme/Uri-Host/Uri-Port Uri option does not contain the Uri-Path/Uri-Query parts of the
cannot be integrity protected since they are allowed to be changed by URI. Proxy-Uri/Proxy-Scheme/Uri-Host/Uri-Port cannot be integrity
a forward proxy. protected since they are allowed to be changed by a forward proxy.
o Observe Depending on content, the Uri-Host may either reveal information
equivalent to that of the IP address or more privacy-sensitive
information, which is discouraged in Section 4.1.3.2.
The Outer Observe option is intended for an OSCORE-unaware proxy to o Observe. The Outer Observe option is intended for an OSCORE-
support forwarding of Observe messages. Changing this option may unaware proxy to support forwarding of Observe messages. Removing
lead to notifications not being forwarded. this option in the request turns the notification request into a
normal request, which is allowed for a proxy and server and
understood by the client but changes the performed operation from
a request for notifications to a plain request, but the client
cannot tell what party removed the option.
o Block1/Block2/Size1/Size2 Removing this option in the response may lead to notifications not
being forwarded or cause a denial of service. The Outer option value
indicates a relative order of notifications as read and written by
the proxy and a change of that may affect proxy operations and
potentially lead to denial of service. Since OSCORE provides
absolute ordering of notifications it is not possible for an
intermediary to spoof reordering (see Section 4.1.3.4). The size and
distributions of notifications over time may reveal information about
the content or nature of the notifications.
The Outer Block options enables fragmentation of OSCORE messages in o Block1/Block2/Size1/Size2. The Outer Block options enables
addition to segmentation performed by the Inner Block options. fragmentation of OSCORE messages in addition to segmentation
Manipulating these options is a potential denial of service attack, performed by the Inner Block options. The presence of these
e.g. injection of alleged Block fragments up to the options indicates a large message being sent and the message size
MAX_UNFRAGMENTED_SIZE, at which the message will be dropped. can be estimated and used for traffic analysis. Manipulating
these options is a potential denial of service attack, e.g.
injection of alleged Block fragments. The specification of
MAX_UNFRAGMENTED_SIZE (Section 4.1.3.3.2), at which the messages
will be dropped, is intended as one measure to mitigate this kind
of attack.
o No-Response o No-Response. The Outer No-Response option is used to support
proxy functionality, specifically to avoid error transmissions
from proxies to clients, and to avoid bandwidth reduction to
servers by proxies applying congestion control when not receiving
responses. Modifying or introducing this option is a potential
denial of service attack against the proxy operations, but since
the option has an Inner value its use can be securely agreed
between the endpoints. The presence of this option is not
expected to reveal any sensitive information about the message
exchange.
The Outer No-Response option is used to support proxy functionality, o OSCORE. The OSCORE option contains information about the
specifically to avoid error transmissions from proxies to clients, compressed COSE header. A change of this field may result in not
and to avoid bandwidth reduction to servers by proxies applying being able to verify the OSCORE message.
congestion control when not receiving responses. Changing this
option is a potential denial of service attack.
o Object-Security D.4.4. HTTP Message Fields
The Object-Security option contains information about the compressed In contrast to CoAP, where OSCORE does not protect header fields to
COSE header. A change of this field may result in not being able to enable CoAP-CoAP proxy operations, the use of OSCORE with HTTP is
verify the OSCORE message. restricted to transporting a protected CoAP message over an HTTP hop.
Any unprotected HTTP message fields may reveal information about the
transport of the OSCORE message and enable various denial of service
attacks. It is recommended to additionally use TLS [RFC5246] for
HTTP hops, which enables encryption and integrity protection of
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
subset of CDDL that is being used in the present specification. subset of CDDL that is being used in the present specification.
skipping to change at page 69, line 10 skipping to change at page 72, line 10
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, Esko
Dijk, Thomas Fossati, Martin Gunnarsson, Klaus Hartke, Jim Schaad, Dijk, Thomas Fossati, Martin Gunnarsson, Klaus Hartke, Jim Schaad,
Peter van der Stok, Dave Thaler, Marco Tiloca, and Malisa Vucinic. Peter van der Stok, Dave Thaler, 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. 303 change blocks. 
873 lines changed or deleted 1025 lines changed or added

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