draft-ietf-core-object-security-06.txt   draft-ietf-core-object-security-07.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: April 28, 2018 Ericsson AB Expires: May 24, 2018 Ericsson AB
L. Seitz L. Seitz
SICS Swedish ICT SICS Swedish ICT
October 25, 2017 November 20, 2017
Object Security for Constrained RESTful Environments (OSCORE) Object Security for Constrained RESTful Environments (OSCORE)
draft-ietf-core-object-security-06 draft-ietf-core-object-security-07
Abstract Abstract
This document defines Object Security for Constrained RESTful This document defines Object Security for Constrained RESTful
Environments (OSCORE), a method for application-layer protection of Environments (OSCORE), a method for application-layer protection of
the Constrained Application Protocol (CoAP), using CBOR Object the Constrained Application Protocol (CoAP), using CBOR Object
Signing and Encryption (COSE). OSCORE provides end-to-end Signing and Encryption (COSE). OSCORE provides end-to-end
encryption, integrity and replay protection, as well as a secure encryption, integrity and replay protection, as well as a secure
message binding. OSCORE is designed for constrained nodes and message binding. OSCORE is designed for constrained nodes and
networks and can be used over any layer and across intermediaries, networks and can be used whereever CoAP can be used, and also with
and also with HTTP. OSCORE may be used to protect group HTTP. OSCORE may be used to protect group communications as is
communications as is specified in a separate draft. specified in a separate draft.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 28, 2018. This Internet-Draft will expire on May 24, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2017 IETF Trust and the persons identified as the Copyright (c) 2017 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(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
skipping to change at page 2, line 23 skipping to change at page 2, line 23
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5
2. The CoAP Object-Security Option . . . . . . . . . . . . . . . 5 2. The CoAP Object-Security Option . . . . . . . . . . . . . . . 5
3. The Security Context . . . . . . . . . . . . . . . . . . . . 6 3. The Security Context . . . . . . . . . . . . . . . . . . . . 6
3.1. Security Context Definition . . . . . . . . . . . . . . . 6 3.1. Security Context Definition . . . . . . . . . . . . . . . 6
3.2. Establishment of Security Context Parameters . . . . . . 9 3.2. Establishment of Security Context Parameters . . . . . . 9
3.3. Requirements on the Security Context Parameters . . . . . 11 3.3. Requirements on the Security Context Parameters . . . . . 11
4. Protected Message Fields . . . . . . . . . . . . . . . . . . 11 4. Protected Message Fields . . . . . . . . . . . . . . . . . . 11
4.1. CoAP Payload . . . . . . . . . . . . . . . . . . . . . . 12 4.1. CoAP Payload . . . . . . . . . . . . . . . . . . . . . . 12
4.2. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 12 4.2. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 13
4.3. CoAP Header . . . . . . . . . . . . . . . . . . . . . . . 18 4.3. CoAP Header . . . . . . . . . . . . . . . . . . . . . . . 18
5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 19 5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 19
5.1. Nonce . . . . . . . . . . . . . . . . . . . . . . . . . . 20 5.1. Kid Context . . . . . . . . . . . . . . . . . . . . . . . 20
5.2. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 20 5.2. Nonce . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.3. Additional Authenticated Data . . . . . . . . . . . . . . 21 5.3. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 22
6. Sequence Numbers, Replay, Message Binding, and Freshness . . 22 5.4. Additional Authenticated Data . . . . . . . . . . . . . . 23
6.1. Message Binding . . . . . . . . . . . . . . . . . . . . . 22 6. Sequence Numbers, Replay, Message Binding, and Freshness . . 23
6.2. AEAD Nonce Uniqueness . . . . . . . . . . . . . . . . . . 22 6.1. Message Binding . . . . . . . . . . . . . . . . . . . . . 23
6.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 22 6.2. AEAD Nonce Uniqueness . . . . . . . . . . . . . . . . . . 24
6.4. Replay Protection . . . . . . . . . . . . . . . . . . . . 23 6.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 24
6.5. Losing Part of the Context State . . . . . . . . . . . . 23 6.4. Replay Protection . . . . . . . . . . . . . . . . . . . . 24
7. Processing . . . . . . . . . . . . . . . . . . . . . . . . . 25 6.5. Losing Part of the Context State . . . . . . . . . . . . 25
7.1. Protecting the Request . . . . . . . . . . . . . . . . . 25 7. Processing . . . . . . . . . . . . . . . . . . . . . . . . . 26
7.2. Verifying the Request . . . . . . . . . . . . . . . . . . 25 7.1. Protecting the Request . . . . . . . . . . . . . . . . . 26
7.3. Protecting the Response . . . . . . . . . . . . . . . . . 27 7.2. Verifying the Request . . . . . . . . . . . . . . . . . . 27
7.4. Verifying the Response . . . . . . . . . . . . . . . . . 27 7.3. Protecting the Response . . . . . . . . . . . . . . . . . 28
8. OSCORE Compression . . . . . . . . . . . . . . . . . . . . . 29 7.4. Verifying the Response . . . . . . . . . . . . . . . . . 29
8.1. Encoding of the Object-Security Value . . . . . . . . . . 29 8. OSCORE Compression . . . . . . . . . . . . . . . . . . . . . 30
8.2. Encoding of the OSCORE Payload . . . . . . . . . . . . . 30 8.1. Encoding of the Object-Security Value . . . . . . . . . . 30
8.3. Context Hint . . . . . . . . . . . . . . . . . . . . . . 30 8.2. Encoding of the OSCORE Payload . . . . . . . . . . . . . 32
8.4. Examples of Compressed COSE Objects . . . . . . . . . . . 30 8.3. Examples of Compressed COSE Objects . . . . . . . . . . . 32
9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 32 9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 33
10. Proxy Operations . . . . . . . . . . . . . . . . . . . . . . 33 10. Proxy Operations . . . . . . . . . . . . . . . . . . . . . . 34
10.1. CoAP-to-CoAP Forwarding Proxy . . . . . . . . . . . . . 33 10.1. CoAP-to-CoAP Forwarding Proxy . . . . . . . . . . . . . 34
10.2. HTTP-to-CoAP Translation Proxy . . . . . . . . . . . . . 33 10.2. HTTP-to-CoAP Translation Proxy . . . . . . . . . . . . . 34
10.3. CoAP-to-HTTP Translation Proxy . . . . . . . . . . . . . 35 10.3. CoAP-to-HTTP Translation Proxy . . . . . . . . . . . . . 36
11. Security Considerations . . . . . . . . . . . . . . . . . . . 36 11. Security Considerations . . . . . . . . . . . . . . . . . . . 37
12. Privacy Considerations . . . . . . . . . . . . . . . . . . . 37 12. Privacy Considerations . . . . . . . . . . . . . . . . . . . 38
13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39
13.1. CoAP Option Numbers Registry . . . . . . . . . . . . . . 38 13.1. COSE Header Parameters Registry . . . . . . . . . . . . 39
13.2. Header Field Registrations . . . . . . . . . . . . . . . 38 13.2. CoAP Option Numbers Registry . . . . . . . . . . . . . . 39
14. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 38 13.3. Header Field Registrations . . . . . . . . . . . . . . . 40
15. References . . . . . . . . . . . . . . . . . . . . . . . . . 39 14. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 40
15.1. Normative References . . . . . . . . . . . . . . . . . . 39 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 40
15.2. Informative References . . . . . . . . . . . . . . . . . 40 15.1. Normative References . . . . . . . . . . . . . . . . . . 40
Appendix A. Test Vectors . . . . . . . . . . . . . . . . . . . . 41 15.2. Informative References . . . . . . . . . . . . . . . . . 41
Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 41 Appendix A. Test Vectors . . . . . . . . . . . . . . . . . . . . 43
B.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 42 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 43
B.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 43 B.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 43
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 44 B.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 44
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 46
1. Introduction 1. Introduction
The Constrained Application Protocol (CoAP) is a web application The Constrained Application Protocol (CoAP) is a web application
protocol, designed for constrained nodes and networks [RFC7228]. protocol, designed for constrained nodes and networks [RFC7228].
CoAP specifies the use of proxies for scalability and efficiency, and CoAP specifies the use of proxies for scalability and efficiency, and
a mapping to HTTP is also specified [RFC8075]. CoAP [RFC7252] a mapping to HTTP is also specified [RFC8075]. CoAP [RFC7252]
references DTLS [RFC6347] for security. CoAP and HTTP proxies references DTLS [RFC6347] for security. CoAP and HTTP proxies
require (D)TLS to be terminated at the proxy. The proxy therefore require (D)TLS to be terminated at the proxy. The proxy therefore
not only has access to the data required for performing the intended not only has access to the data required for performing the intended
proxy functionality, but is also able to eavesdrop on, or manipulate proxy functionality, but is also able to eavesdrop on, or manipulate
any part of the message payload and metadata, in transit between the any part of the message payload and metadata, in transit between the
endpoints. The proxy can also inject, delete, or reorder packets endpoints. The proxy can also inject, delete, or reorder packets
since they are no longer protected by (D)TLS. 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 [RFC7641] CoAP features defined in [RFC7252], OSCORE supports Observe
and Blockwise [RFC7959]. An analysis of end-to-end security for CoAP [RFC7641], Blockwise [RFC7959], PATCH and FETCH [RFC8132]. An
messages through some types of intermediary nodes is performed in analysis of end-to-end security for CoAP messages through some types
of intermediary nodes is performed in
[I-D.hartke-core-e2e-security-reqs]. OSCORE protects the Request/ [I-D.hartke-core-e2e-security-reqs]. OSCORE protects the Request/
Response layer only, and not the CoAP Messaging Layer (Section 2 of Response layer only, and not the CoAP Messaging Layer (Section 2 of
[RFC7252]). Therefore, all the CoAP messages mentioned in this [RFC7252]). Therefore, any Messaging Layer processing follows
document refer to non-Empty CON, NON, and ACK messages [RFC7252]. [RFC7252]. Additionally, since the message formats for CoAP over
Additionally, since the message formats for CoAP over unreliable unreliable transport [RFC7252] and for CoAP over reliable transport
transport [RFC7252] and for CoAP over reliable transport
[I-D.ietf-core-coap-tcp-tls] differ only in terms of Messaging Layer, [I-D.ietf-core-coap-tcp-tls] differ only in terms of Messaging Layer,
OSCORE can be applied to both unreliable and reliable transports. OSCORE can be applied to both unreliable and reliable transports.
OSCORE is designed for constrained nodes and networks and provides an OSCORE is designed for constrained nodes and networks and provides an
in-layer security protocol that does not depend on underlying layers. in-layer security protocol that does not depend on underlying layers.
OSCORE can be used anywhere where CoAP or HTTP can be used, including OSCORE can be used anywhere where CoAP or HTTP can be used, including
non-IP transports (e.g., [I-D.bormann-6lo-coap-802-15-ie]). An non-IP transports (e.g., [I-D.bormann-6lo-coap-802-15-ie]). An
extension of OSCORE may also be used to protect group communication extension of OSCORE may also be used to protect group communication
for CoAP [I-D.tiloca-core-multicast-oscoap]. The use of OSCORE does for CoAP [I-D.tiloca-core-multicast-oscoap]. The use of OSCORE does
not affect the URI scheme and OSCORE can therefore be used with any not affect the URI scheme and OSCORE can therefore be used with any
URI scheme defined for CoAP or HTTP. The application decides the URI scheme defined for CoAP or HTTP. The application decides the
conditions for which OSCORE is required. conditions for which OSCORE is required.
OSCORE builds on CBOR Object Signing and Encryption (COSE) [RFC8152], OSCORE builds on CBOR Object Signing and Encryption (COSE) [RFC8152],
providing end-to-end encryption, integrity, replay protection, and providing end-to-end encryption, integrity, replay protection, and
secure message binding. A compressed version of COSE is used, as secure the binding of response to request. A compressed version of
discussed in Section 8. The use of OSCORE is signaled with the COSE is used, as discussed in Section 8. The use of OSCORE is
Object-Security CoAP option or HTTP header, defined in Section 2 and signaled with the Object-Security CoAP option or HTTP header, defined
Section 10.2. OSCORE is designed to protect as much information as in Section 2 and Section 10.2. OSCORE is designed to protect as much
possible, while still allowing proxy operations (Section 10). OSCORE information as possible, while still allowing proxy operations
provides protection of message payload, almost all CoAP options, and (Section 10). OSCORE provides protection of message payload, almost
the RESTful method. The solution transforms a message into an all CoAP options, and the RESTful method. The solution transforms a
"OSCORE message" before sending, and vice versa after receiving. The message into an "OSCORE message" before sending, and vice versa after
OSCORE message is related to the original message in the following receiving. The OSCORE message is related to the original message in
way: the original message is translated to CoAP (if not already in the following way: the original message is translated to CoAP (if not
CoAP) and the resulting message payload (if present), options not already in CoAP) and the resulting message payload (if present),
processed by a proxy, and the request/response method (CoAP Code) are options not processed by a proxy, and the request/response method
protected in a COSE object. The message fields of the original (CoAP Code) are protected in a COSE object. The message fields of
message that are encrypted are transported in the payload of the the original message that are encrypted are transported in the
OSCORE message, and the Object-Security option is included, see payload of the OSCORE message, and the Object-Security option is
Figure 1. included, see Figure 1.
Client Server Client Server
| OSCORE request - POST example.com: | | OSCORE request - POST example.com: |
| Header, Token, | | Header, Token, |
| Options: {Object-Security, ...}, | | Options: {Object-Security, ...}, |
| Payload: COSE ciphertext | | Payload: COSE ciphertext |
+--------------------------------------------->| +--------------------------------------------->|
| | | |
|<---------------------------------------------+ |<---------------------------------------------+
| OSCORE response - 2.04 (Changed): | | OSCORE response - 2.04 (Changed): |
skipping to change at page 5, line 25 skipping to change at page 5, line 25
1.1. Terminology 1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. These document are to be interpreted as described in [RFC2119]. These
words may also appear in this document in lowercase, absent their words may also appear in this document in lowercase, absent their
normative meanings. normative meanings.
Readers are expected to be familiar with the terms and concepts Readers are expected to be familiar with the terms and concepts
described in CoAP [RFC7252], Observe [RFC7641], Blockwise [RFC7959], described in CoAP [RFC7252], Observe [RFC7641], Blockwise [RFC7959],
COSE [RFC8152], CBOR [RFC7049], CDDL COSE [RFC8152], CBOR [RFC7049], CDDL [I-D.ietf-cbor-cddl], and
[I-D.greevenbosch-appsawg-cbor-cddl], and constrained environments constrained environments [RFC7228].
[RFC7228].
The terms Common/Sender/Recipient Context, Master Secret/Salt, Sender The terms Common/Sender/Recipient Context, Master Secret/Salt, Sender
ID/Key, Recipient ID/Key, and Common IV are defined in Section 3.1. ID/Key, Recipient ID/Key, and Common IV are defined in Section 3.1.
2. The CoAP Object-Security Option 2. The CoAP Object-Security Option
The CoAP Object-Security option (see Figure 2) indicates that the The CoAP Object-Security option (see Figure 2) indicates that the
CoAP message is an OSCORE message and that it contains a compressed CoAP message is an OSCORE message and that it contains a compressed
COSE object (see Section 5 and Section 8). The Object-Security COSE object (see Section 5 and Section 8). The Object-Security
option is critical, safe to forward, part of the cache key, and not option is critical, safe to forward, part of the cache key, and not
skipping to change at page 5, line 50 skipping to change at page 5, line 49
+-----+---+---+---+---+-----------------+--------+--------+---------+ +-----+---+---+---+---+-----------------+--------+--------+---------+
| No. | C | U | N | R | Name | Format | Length | Default | | No. | C | U | N | R | Name | Format | Length | Default |
+-----+---+---+---+---+-----------------+--------+--------+---------+ +-----+---+---+---+---+-----------------+--------+--------+---------+
| TBD | x | | | | Object-Security | (*) | 0-255 | (none) | | TBD | x | | | | Object-Security | (*) | 0-255 | (none) |
+-----+---+---+---+---+-----------------+--------+--------+---------+ +-----+---+---+---+---+-----------------+--------+--------+---------+
C = Critical, U = Unsafe, N = NoCacheKey, R = Repeatable C = Critical, U = Unsafe, N = NoCacheKey, R = Repeatable
(*) See below. (*) See below.
Figure 2: The Object-Security Option Figure 2: The Object-Security Option
The Object-Security option contains the OSCORE flag byte (Section 8), The Object-Security option includes the OSCORE flag byte (Section 8),
the Sender Sequence Number and the Sender ID when present the Sender Sequence Number and the Sender ID when present
(Section 3). The detailed format is specified in Section 8). If the (Section 3). The detailed format is specified in Section 8). If the
OSCORE flag byte is all zero (0x00) the Option value SHALL be empty OSCORE flag byte is all zero (0x00) the Option value SHALL be empty
(Option Length = 0). An endpoint receiving a CoAP message without (Option Length = 0). An endpoint receiving a CoAP message without
payload, that also contains an Object-Security option SHALL treat it payload, that also contains an Object-Security option SHALL treat it
as malformed and reject it. as malformed and reject it.
A successful response to a request with the Object-Security option A successful response to a request with the Object-Security option
SHALL contain the Object-Security option. Whether error responses SHALL contain the Object-Security option. Whether error responses
contain the Object-Security option depends on the error type (see contain the Object-Security option depends on the error type (see
skipping to change at page 8, line 48 skipping to change at page 8, line 48
o Replay Window (Server only). The replay window to verify requests o Replay Window (Server only). The replay window to verify requests
received. received.
An endpoint may free up memory by not storing the Common IV, Sender An endpoint may free up memory by not storing the Common IV, Sender
Key, and Recipient Key, deriving them from the Master Key and Master Key, and Recipient Key, deriving them from the Master Key and Master
Salt when needed. Alternatively, an endpoint may free up memory by Salt when needed. Alternatively, an endpoint may free up memory by
not storing the Master Secret and Master Salt after the other not storing the Master Secret and Master Salt after the other
parameters have been derived. parameters have been derived.
Endpoints MAY operate in either or both roles as client and server Endpoints MAY operate in either or both roles as client and server
and use the same security context for those roles. Indpendent of and use the same security context for those roles. Independent of
being client or server, the endpoint protects messages to send using being client or server, the endpoint protects messages to send using
its Sender Context, and verifies messages received using its its Sender Context, and verifies messages received using its
Recipient Context. The endpoints MUST NOT change the Sender/ Recipient Context. The endpoints MUST NOT change the Sender/
Recipient ID when changing roles. In other words, changing the roles Recipient ID when changing roles. In other words, changing the roles
does not change the set of keys to be used. does not change the set of keys to be used.
3.2. Establishment of Security Context Parameters 3.2. Establishment of Security Context Parameters
The parameters in the security context are derived from a small set The parameters in the security context are derived from a small set
of input parameters. The following input parameters SHALL be pre- of input parameters. The following input parameters SHALL be pre-
skipping to change at page 9, line 43 skipping to change at page 9, 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 replay window type and size is used by the client in endpoints. The replay window type and size is used by the client in
the processing of the Request-Tag the processing of the Request-Tag [I-D.ietf-core-echo-request-tag].
[I-D.amsuess-core-repeat-request-tag]. How the input parameters are How the input parameters are pre-established, is application
pre-established, is application specific. The ACE framework may be specific. The ACE framework may be used to establish the necessary
used to establish the necessary input parameters input parameters [I-D.ietf-ace-oauth-authz].
[I-D.ietf-ace-oauth-authz].
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]):
output parameter = HKDF(salt, IKM, info, L) output parameter = HKDF(salt, IKM, info, L)
where: where:
o salt is the Master Salt as defined above o salt is the Master Salt as defined above
o IKM is the Master Secret is defined above o IKM is the Master Secret as defined above
o info is a CBOR array consisting of: o info is a CBOR array consisting of:
info = [ info = [
id : bstr / nil, id : bstr / nil,
alg : int / tstr, alg : int / tstr,
type : tstr, type : tstr,
L : uint L : uint
] ]
skipping to change at page 11, line 14 skipping to change at page 11, line 14
3.3. Requirements on the Security Context Parameters 3.3. Requirements on the Security Context Parameters
As collisions may lead to the loss of both confidentiality and As collisions may lead to the loss of both confidentiality and
integrity, Sender ID SHALL be unique in the set of all security integrity, Sender ID SHALL be unique in the set of all security
contexts using the same Master Secret and Master Salt. When a contexts using the same Master Secret and Master Salt. When a
trusted third party assigns identifiers (e.g., using trusted third party assigns identifiers (e.g., using
[I-D.ietf-ace-oauth-authz]) or by using a protocol that allows the [I-D.ietf-ace-oauth-authz]) or by using a protocol that allows the
parties to negotiate locally unique identifiers in each endpoint, the parties to negotiate locally unique identifiers in each endpoint, the
Sender IDs can be very short. The maximum length of Sender ID is Sender IDs can be very short. The maximum length of Sender ID is
length of nonce - 6 bytes. For AES-CCM-16-64-128 the maximum length length of nonce subtracted by 6 bytes. For AES-CCM-16-64-128 the
of Sender ID is 7 bytes. If Sender ID uniqueness cannot be maximum length of Sender ID is 7 bytes. If Sender ID uniqueness
guaranteed by construction, Sender IDs MUST be long uniformly random cannot be guaranteed by construction, Sender IDs MUST be long
distributed byte strings such that the probability of collisions is uniformly random distributed byte strings such that the probability
negligible. of collisions is negligible.
To enable retrieval of the right Recipient Context, the Recipient ID To enable retrieval of the right Recipient Context, the Recipient ID
SHOULD be unique in the sets of all Recipient Contexts used by an SHOULD be unique in the sets of all Recipient Contexts used by an
endpoint. The Client MAY provide a Context Hint Section 8.3 to help endpoint. The Client MAY provide a "kid context" parameter
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
skipping to change at page 12, line 15 skipping to change at page 12, line 15
o Class U: unprotected. o Class U: unprotected.
The sending endpoint SHALL transfer Class E message fields in the The sending endpoint SHALL transfer Class E message fields in the
ciphertext of the COSE object in the OSCORE message. The sending ciphertext of the COSE object in the OSCORE message. The sending
endpoint SHALL include Class I message fields in the Additional endpoint SHALL include Class I message fields in the Additional
Authenticated Data (AAD) of the AEAD algorithm, allowing the Authenticated Data (AAD) of the AEAD algorithm, allowing the
receiving endpoint to detect if the value has changed in transfer. receiving endpoint to detect if the value has changed in transfer.
Class U message fields SHALL NOT be protected in transfer. Class I Class U message fields SHALL NOT be protected in transfer. Class I
and Class U message field values are transferred in the header or and Class U message field values are transferred in the header or
options part of the OSCORE message which is visible to proxies. options part of the OSCORE message, which is visible to proxies.
Message fields not visible to proxies, i.e., transported in the Message fields not visible to proxies, i.e., transported in the
ciphertext of the COSE object, are called "Inner" (Class E). Message ciphertext of the COSE object, are called "Inner" (Class E). Message
fields transferred in the header or options part of the OSCORE fields transferred in the header or options part of the OSCORE
message, which is visible to proxies, are called "Outer" (Class I or message, which is visible to proxies, are called "Outer" (Class I or
U). U). There are currently no Class I options defined.
An OSCORE message may contain both an Inner and an Outer message An OSCORE message may contain both an Inner and an Outer instance of
field of certain CoAP message fields. Inner if the value is intended a certain CoAP message field. Inner message fields are intended for
for the destination endpoint, Outer if the value is intended for a the receiving endpoint, whereas Outer message fields are intended for
proxy. Inner and Outer message fields are processed independently. a proxy. Inner and Outer message fields are processed independently.
4.1. CoAP Payload 4.1. CoAP Payload
The CoAP Payload, if present in the original CoAP message, SHALL be The CoAP Payload, if present in the original CoAP message, SHALL be
encrypted and integrity protected and is thus an Inner message field. encrypted and integrity protected and is thus an Inner message field.
See Figure 4.
+------------------+---+---+
| Field | E | U |
+------------------+---+---+
| Payload | x | |
+------------------+---+---+
E = Encrypt and Integrity Protect (Inner)
U = Unprotected (Outer)
Figure 4: Protection of CoAP Payload
The sending endpoint writes the payload of the original CoAP message The sending endpoint writes the payload of the original CoAP message
into the plaintext (Section 5.2) input to the COSE object. The into the Plaintext (Section 5.3) input to the COSE object. The
receiving endpoint verifies and decrypts the COSE object, and receiving endpoint verifies and decrypts the COSE object, and
recreates the payload of the original CoAP message. recreates the payload of the original CoAP message.
4.2. CoAP Options 4.2. CoAP Options
A summary of how options are protected is shown in Figure 4. Options A summary of how options are protected is shown in Figure 5. Note
which require special processing, in particular those which may have that some options may have both Inner and Outer message fields which
both Inner and Outer message fields, are labelled with asterisks. are protected accordingly. The options which require special
processing are labelled with asterisks.
+----+----------------+---+---+---+ +-----+-----------------+---+---+
| No.| Name | E | I | U | | No. | Name | E | U |
+----+----------------+---+---+---+ +-----+-----------------+---+---+
| 1 | If-Match | x | | | | 1 | If-Match | x | |
| 3 | Uri-Host | | | x | | 3 | Uri-Host | | x |
| 4 | ETag | x | | | | 4 | ETag | x | |
| 5 | If-None-Match | x | | | | 5 | If-None-Match | x | |
| 6 | Observe | | | * | | 6 | Observe | | * |
| 7 | Uri-Port | | | x | | 7 | Uri-Port | | x |
| 8 | Location-Path | x | | | | 8 | Location-Path | x | |
| 11 | Uri-Path | x | | | | TBD | Object-Security | | * |
| 12 | Content-Format | x | | | | 11 | Uri-Path | x | |
| 14 | Max-Age | * | | * | | 12 | Content-Format | x | |
| 15 | Uri-Query | x | | | | 14 | Max-Age | * | * |
| 17 | Accept | x | | | | 15 | Uri-Query | x | |
| 20 | Location-Query | x | | | | 17 | Accept | x | |
| 23 | Block2 | * | | * | | 20 | Location-Query | x | |
| 27 | Block1 | * | | * | | 23 | Block2 | * | * |
| 28 | Size2 | * | | * | | 27 | Block1 | * | * |
| 35 | Proxy-Uri | * | | * | | 28 | Size2 | * | * |
| 39 | Proxy-Scheme | | | x | | 35 | Proxy-Uri | | * |
| 60 | Size1 | * | | * | | 39 | Proxy-Scheme | | x |
+----+----------------+---+---+---+ | 60 | Size1 | x | x |
+-----+-----------------+---+---+
E = Encrypt and Integrity Protect (Inner) E = Encrypt and Integrity Protect (Inner)
I = Integrity Protect only (Outer)
U = Unprotected (Outer) U = Unprotected (Outer)
* = Special * = Special
Figure 4: 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. New CoAP options which are repeatable it requires proxy processing.
and of class I MUST specify that proxies MUST NOT change the order of
the option's occurences.
4.2.1. Inner Options 4.2.1. Inner Options
When using OSCORE, Inner option message fields (marked in column E of Inner option message fields (class E) are used in a way analogous to
Figure 4) are sent in a way analogous to communicating in a protected communicating in a protected manner directly with the other endpoint.
manner directly with the other endpoint.
The sending endpoint SHALL write the Inner option message fields The sending endpoint SHALL write the Inner option message fields
present in the original CoAP message into the plaintext of the COSE present in the original CoAP message into the plaintext of the COSE
object Section 5.2, and then remove the Inner option message fields object Section 5.3, and then remove the Inner option message fields
from the OSCORE message. from the OSCORE message.
The processing of Inner option message fields by the receiving The processing of Inner option message fields by the receiving
endpoint is specified in Section 7.2 and Section 7.4. endpoint is specified in Section 7.2 and Section 7.4.
4.2.2. Outer Options 4.2.2. Outer Options
Outer option message fields (marked in column U or I of Figure 4) are Outer option message fields (Class U or I) are used to support proxy
used to support proxy operations. operations.
The sending endpoint SHALL include the Outer option message field The sending endpoint SHALL include the Outer option message field
present in the original message in the options part of the OSCORE present in the original message in the options part of the OSCORE
message. All Outer option message fields, including Object-Security, message. All Outer option message fields, including Object-Security,
SHALL be encoded as described in Section 3.1 of [RFC7252], where the SHALL be encoded as described in Section 3.1 of [RFC7252], where the
delta is the difference to the previously included Outer option delta is the difference to the previously included Outer option
message field. message field.
The processing of Outer options by the receiving endpoint is The processing of Outer options by the receiving endpoint is
specified in Section 7.2 and Section 7.4. specified in Section 7.2 and Section 7.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.3. fields is specified in Section 5.4. New CoAP options which are
repeatable and of class I MUST specify that proxies MUST NOT change
the order of the option's occurrences.
Note: There are currently no Class I option message fields defined. Note: There are currently no Class I option message fields defined.
4.2.3. Special Options 4.2.3. Special Options
Some options require special processing, marked with an asterisk '*' Some options require special processing, marked with an asterisk '*'
in Figure 4. An asterisk in the columns E and U indicate that the in Figure 5; the processing is specified in this section.
option may be added as an Inner and/or Outer message by the sending
endpoint; the processing is specified in this section.
4.2.3.1. Max-Age 4.2.3.1. Max-Age
The Inner Max-Age option is used to specify the freshness (as defined An Inner Max-Age message field is used to specify the freshness (as
in [RFC7252]) of the resource, end-to-end from the server to the defined in [RFC7252]) of the resource, end-to-end from the server to
client, taking into account that the option is not accessible to the client, taking into account that the option is not accessible to
proxies. The Inner Max-Age SHALL be processed by OSCORE as specified proxies. The Inner Max-Age SHALL be processed by OSCORE as specified
in Section 4.2.1. in Section 4.2.1.
The Outer Max-Age option is used to avoid unnecessary caching of An Outer Max-Age message field is used to avoid unnecessary caching
OSCORE responses at OSCORE unaware intermediary nodes. A server MAY of OSCORE error responses at OSCORE unaware intermediary nodes. A
set a Class U Max-Age option with value zero to Observe responses server MAY set a Class U Max-Age message field with value zero to
(see Section 5.6.1 of [RFC7252]) which is then processed according to OSCORE error responses described in Section 6.4, Section 7.2 and
Section 4.2.2. The Outer Max-Age option value SHALL be discarded by Section 7.4, which is then processed according to Section 4.2.2.
the OSCORE client.
Non-Observe OSCORE responses do not need to include a Max-Age option Non-error OSCORE responses do not need to include a Max-Age option
since the responses are non-cacheable by construction (see since the responses are non-cacheable by construction (see
Section 4.3). Section 4.3).
4.2.3.2. The Block Options 4.2.3.2. The Block Options
Blockwise [RFC7959] is an optional feature. An implementation MAY Blockwise [RFC7959] is an optional feature. An implementation MAY
support [RFC7252] and the Object-Security option without supporting support [RFC7252] and the Object-Security option without supporting
[RFC7959]. The Block options are used to secure message [RFC7959]. The Block options (Block1, Block2, Size1, Size2), when
fragmentation end-to-end (Inner options) or for proxies to fragment Inner message fields, provide secure message fragmentation such that
the OSCORE message for the next hop (Outer options). Inner and Outer each fragment can be verified. The Block options, when Outer message
block processing may have different performance properties depending fields, enables hop-by-hop fragmentation of the OSCORE message.
on the underlying transport. The integrity of the message can be Inner and Outer block processing may have different performance
verified end-to-end both in case of Inner and Outer Blockwise properties depending on the underlying transport. The end-to-end
provided all blocks are received (see Section 4.2.3.2.2). integrity of the message can be verified both in case of Inner and
Outer Blockwise provided all blocks are received (see
Section 4.2.3.2.2).
4.2.3.2.1. Inner Block Options 4.2.3.2.1. Inner Block Options
The sending CoAP endpoint MAY fragment a CoAP message as defined in The sending CoAP endpoint MAY fragment a CoAP message as defined in
[RFC7959] before the message is processed by OSCORE. In this case [RFC7959] before the message is processed by OSCORE. In this case
the Block options SHALL be processed by OSCORE as Inner options the Block options SHALL be processed by OSCORE as Inner options
(Section 4.2.1). The receiving CoAP endpoint SHALL process the (Section 4.2.1). The receiving CoAP endpoint SHALL process the
OSCORE message according to Section 4.2.1 before processing blockwise OSCORE message according to Section 4.2.1 before processing blockwise
as defined in [RFC7959]. as defined in [RFC7959].
For blockwise request operations using Block1, an endpoint MUST For concurrent blockwise operations the sending endpoint MUST ensure
comply with the Request-Tag processing defined in Section 3 of that the receiving endpoint can distinguish between blocks from
[I-D.amsuess-core-repeat-request-tag]. In particular, the rules in different operations. One mechanism enabling this is specified in
section 3.3.1 of [I-D.amsuess-core-repeat-request-tag] MUST be [I-D.ietf-core-echo-request-tag].
followed, which guarantee that a specific request body is assembled
only from the corresponding request blocks.
For blockwise response operations using Block2, an endpoint MUST
comply with the ETag processing defined in Section 4 of
[I-D.amsuess-core-repeat-request-tag].
4.2.3.2.2. Outer Block Options 4.2.3.2.2. Outer Block Options
Proxies MAY fragment an OSCORE message using [RFC7959], which then Proxies MAY fragment an OSCORE message using [RFC7959], by
introduces Outer Block options not generated by the sending endpoint. introducing Block option message fields that are Outer Section 4.2.2
Note that the Outer Block options are neither encrypted nor integrity and not generated by the sending endpoint. Note that the Outer Block
protected. As a consequence, a proxy can maliciously inject block options are neither encrypted nor integrity protected. As a
fragments indefinitely, since the receiving endpoint needs to receive consequence, a proxy can maliciously inject block fragments
the last block (see [RFC7959]) to be able to compose the OSCORE indefinitely, since the receiving endpoint needs to receive the last
message and verify its integrity. Therefore, applications supporting block (see [RFC7959]) to be able to compose the OSCORE message and
OSCORE and [RFC7959] MUST specify a security policy defining a verify its integrity. Therefore, applications supporting OSCORE and
maximum unfragmented message size (MAX_UNFRAGMENTED_SIZE) considering
the maximum size of message which can be handled by the endpoints.
[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 Messages exceeding this size SHOULD be fragmented by the sending
endpoint using Inner Block options (Section 4.2.3.2.1). endpoint using Inner Block options (Section 4.2.3.2.1).
An endpoint receiving an OSCORE message with an Outer Block option An endpoint receiving an OSCORE message with an Outer Block option
SHALL first process this option according to [RFC7959], until all SHALL first process this option according to [RFC7959], until all
blocks of the OSCORE message have been received, or the cumulated blocks of the OSCORE message have been received, or the cumulated
message size of the blocks exceeds MAX_UNFRAGMENTED_SIZE. In the message size of the blocks exceeds MAX_UNFRAGMENTED_SIZE. In the
former case, the processing of the OSCORE message continues as former case, the processing of the OSCORE message continues as
defined in this document. In the latter case the message SHALL be defined in this document. In the latter case the message SHALL be
discarded. discarded.
To allow multiple concurrent request operations to the same server To allow multiple concurrent request operations to the same server
(not only same resource), a CoAP proxy SHOULD follow the Request-Tag (not only same resource), a CoAP proxy SHOULD follow the Request-Tag
processing specified in section 3.3.2 of processing specified in section 3.3.2 of
[I-D.amsuess-core-repeat-request-tag]. [I-D.ietf-core-echo-request-tag].
4.2.3.3. Proxy-Uri 4.2.3.3. Proxy-Uri
Proxy-Uri, when present, is split by OSCORE into class U options and Proxy-Uri, when present, is split by OSCORE into class U options and
class E options, which are processed accordingly. When Proxy-Uri is class E options, which are processed accordingly. When Proxy-Uri is
used in the original CoAP message, Uri-* are not present [RFC7252]. used in the original CoAP message, Uri-* are not present [RFC7252].
The sending endpoint SHALL first decompose the Proxy-Uri value of the The sending endpoint SHALL first decompose the Proxy-Uri value of the
original CoAP message into the Proxy-Scheme, Uri-Host, Uri-Port, Uri- original CoAP message into the Proxy-Scheme, Uri-Host, Uri-Port, Uri-
Path, and Uri-Query options (if present) according to section 6.4 of Path, and Uri-Query options (if present) according to section 6.4 of
skipping to change at page 16, line 43 skipping to change at page 16, line 46
processed as Inner options (Section 4.2.1). processed as Inner options (Section 4.2.1).
The Proxy-Uri option of the OSCORE message SHALL be set to the The Proxy-Uri option of the OSCORE message SHALL be set to the
composition of Proxy-Scheme, Uri-Host and Uri-Port options (if composition of Proxy-Scheme, Uri-Host and Uri-Port options (if
present) as specified in section 6.5 of [RFC7252], and processed as present) as specified in section 6.5 of [RFC7252], and processed as
an Outer option of Class U (Section 4.2.2). an Outer option of Class U (Section 4.2.2).
Note that replacing the Proxy-Uri value with the Proxy-Scheme and Note that replacing the Proxy-Uri value with the Proxy-Scheme and
Uri-* options works by design for all CoAP URIs (see Section 6 of Uri-* options works by design for all CoAP URIs (see Section 6 of
[RFC7252]. OSCORE-aware HTTP servers should not use the userinfo [RFC7252]. OSCORE-aware HTTP servers should not use the userinfo
component of the HTTP URI (as defined in section 3.2.1. of component of the HTTP URI (as defined in section 3.2.1 of [RFC3986]),
[RFC3986]), so that this type of replacement is possible in the so that this type of replacement is possible in the presence of CoAP-
presence of CoAP-to-HTTP proxies. In other documents specifying to-HTTP proxies. In other documents specifying cross-protocol
cross-protocol proxying behavior using different URI structures, it proxying behavior using different URI structures, it is expected that
is expected that the authors will create Uri-* options that allow the authors will create Uri-* options that allow decomposing the
decomposing the Proxy-Uri, and specify in which OSCORE class they Proxy-Uri, and specify in which OSCORE class they belong.
belong.
An example of how Proxy-Uri is processed is given here. Assume that An example of how Proxy-Uri is processed is given here. Assume that
the original CoAP message contains: the original CoAP message contains:
o Proxy-Uri = "coap://example.com/resource?q=1" o Proxy-Uri = "coap://example.com/resource?q=1"
During OSCORE processing, Proxy-Uri is split into: During OSCORE processing, Proxy-Uri is split into:
o Proxy-Scheme = "coap" o Proxy-Scheme = "coap"
skipping to change at page 18, line 6 skipping to change at page 18, line 8
Notification Number is a non-negative integer containing the largest Notification Number is a non-negative integer containing the largest
Partial IV of the successfully received notifications for the Partial IV of the successfully received notifications for the
associated Observe registration, see Section 6.4. The Notification associated Observe registration, see Section 6.4. The Notification
Number is initialized to the Partial IV of the first successfully Number is initialized to the Partial IV of the first successfully
received notification response to the registration request. In received notification response to the registration request. In
contrast to [RFC7641], the received Partial IV MUST always be contrast to [RFC7641], the received Partial IV MUST always be
compared with the Notification Number, which thus MUST NOT be compared with the Notification Number, which thus MUST NOT be
forgotten after 128 seconds. forgotten after 128 seconds.
If the verification fails, the client SHALL stop processing the If the verification fails, the client SHALL stop processing the
response, and in the case of CON respond with an empty ACK. The response. The client MAY ignore the Observe option value.
client MAY ignore the Observe option value.
The Observe option in the CoAP request may be legitimately removed by The Observe option in the CoAP request may be legitimately removed by
a proxy. If the Observe option is removed from a CoAP request by a a proxy. If the Observe option is removed from a CoAP request by a
proxy, then the server can still verify the request (as a non-Observe proxy, then the server can still verify the request (as a non-Observe
request), and produce a non-Observe response. If the OSCORE client request), and produce a non-Observe response. If the OSCORE client
receives a response to an Observe request without an outer Observe receives a response to an Observe request without an outer Observe
value, then it MUST verify the response as a non-Observe response. value, then it MUST verify the response as a non-Observe response.
(The reverse case is covered in the verification of the response, see (The reverse case is covered in the verification of the response, see
Section 7.) Section 7.)
4.2.3.5. Object-Security
The Object-Security option is only defined to be present in OSCORE
messages, as an indication that OSCORE processing have been
performed. The content in the Object-Security option is neither
encrypted nor inegrity protected as a whole but some part of the
content of this option is protected, see Section 5.4. "OSCORE over
OSCORE" is not supported: If OSCORE processing detects an OSCORE
option in the original CoAP message, then processing SHALL be
stopped.
4.3. CoAP Header 4.3. CoAP Header
Most CoAP header fields (i.e. the message fields in the fixed 4-byte A summary of how the CoAP Header fields are protected is shown in
Figure 6.
+------------------+---+---+
| Field | E | U |
+------------------+---+---+
| Version (UDP) | | x |
| Type (UDP) | | x |
| Length (TCP) | | x |
| Token Length | | x |
| Code | x | |
| Message ID (UDP) | | x |
| Token | | x |
+------------------+---+---+
E = Encrypt and Integrity Protect (Inner)
U = Unprotected (Outer)
Figure 6: Protection of CoAP Header Fields
Most CoAP Header fields (i.e. the message fields in the fixed 4-byte
header) are required to be read and/or changed by CoAP proxies and header) are required to be read and/or changed by CoAP proxies and
thus cannot in general be protected end-to-end between the endpoints. thus cannot in general be protected end-to-end between the endpoints.
As mentioned in Section 1, OSCORE protects the CoAP Request/Response As mentioned in Section 1, OSCORE protects the CoAP Request/Response
layer only, and not the Messaging Layer (Section 2 of [RFC7252]), so layer only, and not the Messaging Layer (Section 2 of [RFC7252]), so
fields such as Type and Message ID are not protected with OSCORE. fields such as Type and Message ID are not protected with OSCORE.
The CoAP header field Code is protected by OSCORE. Code SHALL be The CoAP Header field Code is protected by OSCORE. Code SHALL be
encrypted and integrity protected (Class E) to prevent an encrypted and integrity protected (Class E) to prevent an
intermediary from eavesdropping or manipulating the Code (e.g., intermediary from eavesdropping or manipulating the Code (e.g.,
changing from GET to DELETE). changing from GET to DELETE).
The sending endpoint SHALL write the Code of the original CoAP The sending endpoint SHALL write the Code of the original CoAP
message into the plaintext of the COSE object Section 5.2. After message into the plaintext of the COSE object Section 5.3. After
that, the Outer Code of the OSCORE message SHALL be set to 0.02 that, the Outer Code of the OSCORE message SHALL be set to 0.02
(POST) for requests and to 2.04 (Changed) for responses, except for (POST) for requests without Observe option, to 0.05 (FETCH) for
Observe messages. For Observe messages, the Outer Code of the OSCORE requests with Observe option, and to 2.04 (Changed) for responses.
message SHALL be set to 0.05 (FETCH) for requests and to 2.05 Using FETCH with Observe allows OSCORE to be compliant with the
(Content) for responses. This exception allows OSCORE to be Observe processing in OSCORE-unaware proxies. The choice of POST and
compliant with the Observe processing in OSCORE-unaware proxies. The FETCH ([RFC8132]) allows all OSCORE messages to have payload.
choice of POST and FETCH ([RFC8132]) allows all OSCORE messages to
have payload.
The receiving endpoint SHALL discard the Code in the OSCORE message The receiving endpoint SHALL discard the Code in the OSCORE message
and write the Code of the Plaintext in the COSE object (Section 5.2) and write the Code of the Plaintext in the COSE object (Section 5.3)
into the decrypted CoAP message. into the decrypted CoAP message.
The other CoAP header fields are Unprotected (Class U). The sending The other CoAP Header fields are Unprotected (Class U). The sending
endpoint SHALL write all other header fields of the original message endpoint SHALL write all other header fields of the original message
into the header of the OSCORE message. The receiving endpoint SHALL into the header of the OSCORE message. The receiving endpoint SHALL
write the header fields from the received OSCORE message into the write the header fields from the received OSCORE message into the
header of the decrypted CoAP message. header of the decrypted CoAP message.
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
skipping to change at page 19, line 46 skipping to change at page 20, line 28
be present in responses. (A non-Observe example where the be present in responses. (A non-Observe example where the
Partial IV is included in a response is provided in Partial IV is included in a response is provided in
Section 6.5.2.) Section 6.5.2.)
* The "kid" parameter. The value is set to the Sender ID. This * The "kid" parameter. The value is set to the Sender ID. This
parameter SHALL be present in requests and SHOULD NOT be parameter SHALL be present in requests and SHOULD NOT be
present in responses. (An example where the Sender ID is present in responses. (An example where the Sender ID is
included in a response is the extension of OSCORE to group included in a response is the extension of OSCORE to group
communication [I-D.tiloca-core-multicast-oscoap].) communication [I-D.tiloca-core-multicast-oscoap].)
* Optionally, a "kid context" parameter as defined in
Section 5.1. This parameter MAY be present in requests and
SHALL NOT be present in responses.
o The "ciphertext" field is computed from the secret key (Sender Key o The "ciphertext" field is computed from the secret key (Sender Key
or Recipient Key), Nonce (see Section 5.1), Plaintext (see or Recipient Key), Nonce (see Section 5.2), Plaintext (see
Section 5.2), and the Additional Authenticated Data (AAD) (see Section 5.3), and the Additional Authenticated Data (AAD) (see
Section 5.3) following Section 5.2 of [RFC8152]. Section 5.4) following Section 5.2 of [RFC8152].
The encryption process is described in Section 5.3 of [RFC8152]. The encryption process is described in Section 5.3 of [RFC8152].
5.1. Nonce 5.1. Kid Context
The nonce is constructed in the following way (see Figure 5): For certain use cases, e.g. deployments where the same "kid" is used
with multiple contexts, it is necessary or favorable for the sender
to provide an additional identifier of the security material to use,
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" is implicitly integrity protected, as manipulation
that leads to the wrong key (or no key) being retrieved which results
in an error, as described in Section 7.2.
A summary of the COSE header parameter "kid context" defined above
can be found in Figure 7.
Some examples of relevant uses of kid context are the following:
o If the client has an identifier in some other namespace which can
be used by the server to retrieve or establish the security
context, then that identifier can be used as kid context. The kid
context may be used as Master Salt Section 3.1 for additional
entropy of the security contexts, see for example
[I-D.ietf-6tisch-minimal-security].
o In case of a group communication scenario
[I-D.tiloca-core-multicast-oscoap], if the server belongs to
multiple groups, then a group identifier can be used as kid
context to enable the server to find the right security context.
+----------+--------+------------+----------------+-----------------+
| name | label | value type | value registry | description |
+----------+--------+------------+----------------+-----------------+
| kid | kidctx | bstr | | Identifies the |
| context | | | | kid context |
+----------+--------+------------+----------------+-----------------+
Figure 7: Additional common header parameter for the COSE object
5.2. Nonce
The nonce is constructed in the following way (see Figure 8):
1. left-padding the Partial IV (in network byte order) with zeroes 1. left-padding the Partial IV (in network byte order) with zeroes
to exactly 5 bytes, to exactly 5 bytes,
2. left-padding the (Sender) ID of the endpoint that generated the 2. left-padding the (Sender) ID of the endpoint that generated the
Partial IV (in network byte order) with zeroes to exactly nonce Partial IV (in network byte order) with zeroes to exactly nonce
length - 6 bytes, length - 6 bytes,
3. concatenating the size of the ID (S) with the padded ID and the 3. concatenating the size of the ID (S) with the padded ID and the
padded Partial IV, padded Partial IV,
skipping to change at page 20, line 41 skipping to change at page 22, line 17
+---+-----------------------+--+--+--+--+--+ | +---+-----------------------+--+--+--+--+--+ |
| |
+------------------------------------------+ | +------------------------------------------+ |
| Common IV |->(XOR) | Common IV |->(XOR)
+------------------------------------------+ | +------------------------------------------+ |
| |
+------------------------------------------+ | +------------------------------------------+ |
| Nonce |<---+ | Nonce |<---+
+------------------------------------------+ +------------------------------------------+
Figure 5: AEAD Nonce Formation Figure 8: AEAD Nonce Formation
5.2. 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 6) consisting of: Figure 9) consisting of:
o the Code of the original CoAP message as defined in Section 3 of o the Code of the original CoAP message as defined in Section 3 of
[RFC7252]; and [RFC7252]; and
o all Inner option message fields (see Section 4.2.1) present in the o all Inner option message fields (see Section 4.2.1) present in the
original CoAP message (see Section 4.2). The options are encoded original CoAP message (see Section 4.2). The options are encoded
as described in Section 3.1 of [RFC7252], where the delta is the as described in Section 3.1 of [RFC7252], where the delta is the
difference to the previously included Class E option; and difference to the previously included Class E option; and
o the Payload of original CoAP message, if present, and in that case o the Payload of original CoAP message, if present, and in that case
skipping to change at page 21, line 20 skipping to change at page 22, line 45
0 1 2 3 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Code | Class E options (if any) ... | Code | Class E options (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 1 1 1 1 1 1 1| Payload (if any) ... |1 1 1 1 1 1 1 1| Payload (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(only if there (only if there
is payload) is payload)
Figure 6: Plaintext Figure 9: Plaintext
5.3. Additional Authenticated Data NOTE: The Plaintext contains all CoAP data that needs to be encrypted
end-to-end between the endpoints.
5.4. Additional Authenticated Data
The external_aad SHALL be a CBOR array as defined below: The external_aad SHALL be a CBOR array as defined below:
external_aad = [ external_aad = [
version : uint, version : uint,
alg : int / tstr, alg : int / tstr,
request_kid : bstr, request_kid : bstr,
request_piv : bstr, request_piv : bstr,
options : bstr options : bstr
] ]
skipping to change at page 22, line 43 skipping to change at page 24, line 26
messages with the given Sender Context. The endpoint SHOULD acquire messages with the given Sender Context. The endpoint SHOULD acquire
a new security context (and consequently inform the other endpoint) a new security context (and consequently inform the other endpoint)
before this happens. The latter is out of scope of this document. before this happens. The latter is out of scope of this document.
6.3. Freshness 6.3. Freshness
For requests, OSCORE provides weak absolute freshness as the only For requests, OSCORE provides weak absolute freshness as the only
guarantee is that the request is not older than the security context. guarantee is that the request is not older than the security context.
For applications having stronger demands on request freshness (e.g., For applications having stronger demands on request freshness (e.g.,
control of actuators), OSCORE needs to be augmented with mechanisms control of actuators), OSCORE needs to be augmented with mechanisms
providing freshness [I-D.amsuess-core-repeat-request-tag]. providing freshness, for example as specified in
[I-D.ietf-core-echo-request-tag].
For responses, the message binding guarantees that a response is not For responses, the message binding guarantees that a response is not
older than its request. For responses without Observe, this gives older than its request. For responses without Observe, this gives
strong absolute freshness. For responses with Observe, the absolute strong absolute freshness. For responses with Observe, the absolute
freshness gets weaker with time, and it is RECOMMENDED that the freshness gets weaker with time, and it is RECOMMENDED that the
client regularly restart the observation. client regularly restart the observation.
For requests, and responses with Observe, OSCORE also provides For requests, and responses with Observe, OSCORE also provides
relative freshness in the sense that the received Partial IV allows a relative freshness in the sense that the received Partial IV allows a
recipient to determine the relative order of responses. recipient to determine the relative order of responses.
6.4. Replay Protection 6.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 and the message received is a CON message, If this verification fails the server SHALL stop processing the
the server SHALL respond with a 5.03 Service Unavailable error message and, MAY optionally respond with a 4.01 Unauthorized error
message with the inner Max-Age option set to 0. The diagnostic message. The server MAY set an Outer Max-Age option with value zero.
payload MAY contain the "Replay protection failed" string. The size The diagnostic payload MAY contain the "Replay protection failed"
and type of the Replay Window depends on the use case and lower string. The size and type of the Replay Window depends on the use
protocol layers. In case of reliable and ordered transport from case and lower protocol layers. In case of reliable and ordered
endpoint to endpoint, the server MAY just store the last received transport from endpoint to endpoint, the server MAY just store the
Partial IV and require that newly received Partial IVs equals the last received Partial IV and require that newly received Partial IVs
last received Partial IV + 1. equals the last received Partial IV + 1.
Responses to non-Observe requests are protected against replay as Responses to non-Observe requests are protected against replay as
they are cryptographically bound to the request. they are cryptographically bound to the request.
In the case of Observe, a client receiving a notification SHALL In the case of Observe, a client receiving a notification SHALL
verify that the Partial IV of a received notification is greater than verify that the Partial IV of a received notification is greater than
the Notification Number bound to that Observe registration. If the the Notification Number bound to that Observe registration. If the
verification fails, the client SHALL stop processing the response, verification fails, the client SHALL stop processing the response.
and in the case of CON respond with an empty ACK. If the If the verification succeeds, the client SHALL overwrite the
verification succeeds, the client SHALL overwrite the corresponding corresponding Notification Number with the received Partial IV.
Notification Number with the received Partial IV.
If messages are processed concurrently, the Partial IV needs to be If messages are processed concurrently, the Partial IV needs to be
validated a second time after decryption and before updating the validated a second time after decryption and before updating the
replay protection data. The operation of validating the Partial IV replay protection data. The operation of validating the Partial IV
and updating the replay protection data MUST be atomic. and updating the replay protection data MUST be atomic.
6.5. Losing Part of the Context State 6.5. Losing Part of the Context State
To prevent reuse of the Nonce with the same key, or from accepting To prevent reuse of the Nonce with the same key, or from accepting
replayed messages, a node needs to handle the situation of losing replayed messages, a node needs to handle the situation of losing
rapidly changing parts of the context, such as the request Token, rapidly changing parts of the context, such as the request Token,
Sender Sequence Number, Replay Window, and Nofitifcation Numbers. Sender Sequence Number, Replay Window, and Notififcation Numbers.
These are typically stored in RAM and therefore lost in the case of These are typically stored in RAM and therefore lost in the case of
an unplanned reboot. an unplanned reboot.
After boot, a node MAY reject to use existing security contexts from After boot, a node MAY reject to use existing security contexts from
before it booted and MAY establish a new security context with each before it booted and MAY establish a new security context with each
party it communicates. However, establishing a fresh security party it communicates. However, establishing a fresh security
context may have a non-negligible cost in terms of, e.g., power context may have a non-negligible cost in terms of, e.g., power
consumption. consumption.
After boot, a node MAY use a partly persistently stored security After boot, a node MAY use a partly persistently stored security
skipping to change at page 24, line 32 skipping to change at page 26, line 12
trade-off between the number of storage operations and efficient trade-off between the number of storage operations and efficient
use of Sender Sequence Numbers. use of Sender Sequence Numbers.
6.5.2. Replay Window 6.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
Repeat option [I-D.amsuess-core-repeat-request-tag] to get a Echo option [I-D.ietf-core-echo-request-tag] to get a request with
request with verifiable freshness. The server MUST use its verifiable freshness. The server MUST use its Partial IV when
Partial IV when generating the nonce and MUST include the Partial generating the nonce and MUST include the Partial IV in the
IV in the response. response.
If the server using the Repeat option can verify a second request as If the server using the Echo option can verify a second request as
fresh, then the Partial IV of the second request is set as the lower fresh, then the Partial IV of the second request is set as the lower
limit of the replay window. limit of the replay window.
6.5.3. Replay Protection of Observe Notifications 6.5.3. Replay Protection of Observe Notifications
To prevent accepting replay of previously received notification To prevent accepting replay of previously received notification
responses, the client MAY perform the following procedure after boot: responses, the client MAY perform the following procedure after boot:
o The client rejects notifications bound to the earlier o The client rejects notifications bound to the earlier
registration, removes all Notification Numbers and re-register registration, removes all Notification Numbers and re-register
skipping to change at page 25, line 16 skipping to change at page 26, line 41
This section describes the OSCORE message processing. This section describes the OSCORE message processing.
7.1. Protecting the Request 7.1. Protecting the Request
Given a CoAP request, the client SHALL perform the following steps to Given a CoAP request, the client SHALL perform the following steps to
create an 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, as described in 2. Compose the Additional Authenticated Data and the Plaintext, as
Section 5. described in Section 5.4 and Section 5.3.
3. Compute the AEAD nonce from the Sender ID, Common IV, and Partial 3. Compute the AEAD nonce from the Sender ID, Common IV, and Partial
IV (Sender Sequence Number in network byte order) as described in IV (Sender Sequence Number in network byte order) as described in
Section 5.1. Then (in one atomic operation, see Section 6.2) Section 5.2. Then (in one atomic operation, see Section 6.2)
increment the Sender Sequence Number by one. increment the Sender Sequence Number by one.
4. Encrypt the COSE object using the Sender Key. Compress the COSE 4. Encrypt the COSE object using the Sender Key. Compress the COSE
Object as specified in Section 8. Object as specified in Section 8.
5. Format the OSCORE message according to Section 4. The Object- 5. Format the OSCORE message according to Section 4. The Object-
Security option is added, see Section 4.2.2. Security option is added, see Section 4.2.2.
6. Store the association Token - Security Context. The client SHALL 6. Store the association Token - Security Context. The client SHALL
be able to find the Recipient Context from the Token in the be able to find the Recipient Context from the Token in the
skipping to change at page 25, line 43 skipping to change at page 27, line 21
7.2. Verifying the Request 7.2. Verifying the Request
A server receiving a request containing the Object-Security option A server receiving a request containing the Object-Security option
SHALL perform the following steps: SHALL perform the following steps:
1. Process outer Block options according to [RFC7959], until all 1. Process outer Block options according to [RFC7959], until all
blocks of the request have been received, see Section 4.2.3.2. blocks of the request have been received, see Section 4.2.3.2.
2. Discard the message Code and all non-special Inner option 2. Discard the message Code and all non-special Inner option
message fields (marked with 'x' in column E of Figure 4) present message fields (marked with 'x' in column E of Figure 5) present
in the received message. For example, an If-Match Outer option in the received message. For example, an If-Match Outer option
is discarded, but an Uri-Host Outer option is not discarded. is discarded, but an Uri-Host Outer option is not discarded.
3. Decompress the COSE Object (Section 8) and retrieve the 3. Decompress the COSE Object (Section 8) 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 the request is a NON message and either the parameter. If either the decompression or the COSE message
decompression or the COSE message fails to decode, or the server fails to decode, or the server fails to retrieve a Recipient
fails to retrieve a Recipient Context with Recipient ID Context with Recipient ID corresponding to the 'kid' parameter
corresponding to the 'kid' parameter received, then the server received, then the server SHALL stop processing the request.
SHALL stop processing the request. If the request is a CON If:
message, and:
* either the decompression or the COSE message fails to decode, * either the decompression or the COSE message fails to decode,
the server SHALL respond with a 4.02 Bad Option error the server MAY respond with a 4.02 Bad Option error message.
message. The diagnostic payload SHOULD contain the string The server MAY set an Outer Max-Age option with value zero.
"Failed to decode COSE". The diagnostic payload SHOULD contain the string "Failed to
decode COSE".
* the server fails to retrieve a Recipient Context with * the server fails to retrieve a Recipient Context with
Recipient ID corresponding to the 'kid' parameter received, Recipient ID corresponding to the 'kid' parameter received,
the server SHALL respond with a 4.01 Unauthorized error the server MAY respond with a 4.01 Unauthorized error
message. The diagnostic payload MAY contain the string message. The server MAY set an Outer Max-Age option with
value zero. The diagnostic payload SHOULD contain the string
"Security context not found". "Security context not found".
4. Verify the 'Partial IV' parameter using the Replay Window, as 4. Verify the 'Partial IV' parameter using the Replay Window, as
described in Section 6. described in Section 6.
5. Compose the Additional Authenticated Data, as described in 5. Compose the Additional Authenticated Data, as described in
Section 5. Section 5.
6. Compute the AEAD nonce from the Recipient ID, Common IV, and the 6. Compute the AEAD nonce from the Recipient ID, Common IV, and the
'Partial IV' parameter, received in the COSE Object. 'Partial IV' parameter, received in the COSE Object.
7. Decrypt the COSE object using the Recipient Key. 7. Decrypt the COSE object using the Recipient Key.
* If decryption fails, the server MUST stop processing the * If decryption fails, the server MUST stop processing the
request and, if the request is a CON message, the server MUST request and MAY respond with a 4.00 Bad Request error
respond with a 4.00 Bad Request error message. The message. The server MAY set an Outer Max-Age option with
diagnostic payload MAY contain the "Decryption failed" value zero. The diagnostic payload SHOULD contain the
string. "Decryption failed" string.
* If decryption succeeds, update the Replay Window, as * If decryption succeeds, update the Replay Window, as
described in Section 6. described in Section 6.
8. For each decrypted option, check if the option is also present 8. For each decrypted option, check if the option is also present
as an Outer option: if it is, discard the Outer. For example: as an Outer option: if it is, discard the Outer. For example:
the message contains a Max-Age Inner and a Max-Age Outer option. the message contains a Max-Age Inner and a Max-Age Outer option.
The Outer Max-Age is discarded. The Outer Max-Age is discarded.
9. Add decrypted code, options and payload to the decrypted 9. Add decrypted code, options and payload to the decrypted
request. The Object-Security option is removed. request. The Object-Security option is removed.
10. The decrypted CoAP request is processed according to [RFC7252] 10. The decrypted CoAP request is processed according to [RFC7252]
7.3. Protecting the Response 7.3. Protecting the Response
Given a CoAP response, the server SHALL perform the following steps Given a CoAP response, the server SHALL perform the following steps
to create an OSCORE response. Note that CoAP error responses derived to create an OSCORE response. Note that CoAP error responses derived
from CoAP processing (point 10. in Section 7.2) are protected, as from CoAP processing (point 10. in Section 7.2) are protected, as
well as successful CoAP responses, while the OSCORE errors (point 3., well as successful CoAP responses, while the OSCORE errors (point 3,
4., 7. in Section 7.2) do not follow the processing below, but are 4, and 7 in Section 7.2) do not follow the processing below, but are
sent as simple CoAP responses, without OSCORE processing. sent as simple CoAP responses, without OSCORE processing.
1. Retrieve the Sender Context in the Security Context used to 1. Retrieve the Sender Context in the Security Context used to
verify the request. verify the request.
2. Compose the Additional Authenticated Data, as described in 2. Compose the Additional Authenticated Data and the Plaintext, as
Section 5. described in Section 5.4 and Section 5.3.
3. Compute the AEAD nonce 3. Compute the AEAD nonce
* If Observe is used, Compute the AEAD nonce from the Sender ID, * If Observe is used, Compute the AEAD nonce from the Sender ID,
Common IV, and Partial IV (Sender Sequence Number in network Common IV, and Partial IV (Sender Sequence Number in network
byte order). Then (in one atomic operation, see Section 6.2) byte order). Then (in one atomic operation, see Section 6.2)
increment the Sender Sequence Number by one. increment the Sender Sequence Number by one.
* If Observe is not used, either the nonce from the request is * If Observe is not used, either the nonce from the request is
used or a new Partial IV is used. used or a new Partial IV is used.
4. Encrypt the COSE object using the Sender Key. Compress the COSE 4. Encrypt the COSE object using the Sender Key. Compress the COSE
Object as specified in Section 8. If in 3. the nonce was Object as specified in Section 8. If the nonce was constructed
constructed from a new Partial IV, this Partial IV MUST be from a new Partial IV, this Partial IV MUST be included in the
included in the message. If the nonce from the request was used, message. If the nonce from the request was used, the Partial IV
the Partial IV MUST NOT be included in the message. MUST NOT be included in the message.
5. Format the OSCORE message according to Section 4. The Object- 5. Format the OSCORE message according to Section 4. The Object-
Security option is added, see Section 4.2.2. Security option is added, see Section 4.2.2.
7.4. Verifying the Response 7.4. Verifying the Response
A client receiving a response containing the Object-Security option A client receiving a response containing the Object-Security option
SHALL perform the following steps: SHALL perform the following steps:
1. Process outer Block options according to [RFC7959], until all 1. Process outer Block options according to [RFC7959], until all
skipping to change at page 28, line 48 skipping to change at page 30, line 21
as an Outer option: if it is, discard the Outer. For example: as an Outer option: if it is, discard the Outer. For example:
the message contains a Max-Age Inner and a Max-Age Outer option. the message contains a Max-Age Inner and a Max-Age Outer option.
The Outer Max-Age is discarded. The Outer Max-Age is discarded.
9. Add decrypted code, options and payload to the decrypted 9. Add decrypted code, options and payload to the decrypted
request. The Object-Security option is removed. request. The Object-Security option is removed.
10. The decrypted CoAP response is processed according to [RFC7252] 10. The decrypted CoAP response is processed according to [RFC7252]
11. (Optional) In case any of the previous erroneous conditions 11. (Optional) In case any of the previous erroneous conditions
apply: if the response is a CON message, then the client SHALL apply: the client SHALL stop processing the response.
send an empty ACK back and stop processing the response; if the
response is a ACK or a NON message, then the client SHALL simply
stop processing the response.
8. OSCORE Compression 8. OSCORE Compression
The Concise Binary Object Representation (CBOR) [RFC7049] combines The Concise Binary Object Representation (CBOR) [RFC7049] combines
very small message sizes with extensibility. The CBOR Object Signing very small message sizes with extensibility. The CBOR Object Signing
and Encryption (COSE) [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 simple stateless compression mechanism for OSCORE called the a simple stateless compression mechanism for OSCORE called the
"compressed COSE object", which significantly reduces the per-packet "compressed COSE object", which significantly reduces the per-packet
overhead. overhead.
8.1. Encoding of the Object-Security Value 8.1. Encoding of the Object-Security Value
The value of the Object-Security option SHALL contain the OSCORE flag The value of the Object-Security option SHALL contain the OSCORE flag
byte, the Partial IV parameter, the Context Hint parameter (length byte, the Partial IV parameter, the kid context parameter (length and
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) | Context Hint (if any) | kid (if any) ... | | s (if any) | kid context (if any) | kid (if any) ... |
+------------+-----------------------+------------------+ +------------+----------------------+------------------+
Figure 7: Object-Security Value Figure 10: Object-Security Value
o The first byte (= the OSCORE flag byte) encodes a set of flags and o The first byte (= the OSCORE flag byte) encodes a 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 is compressed COSE object. The values n = 6 and n = 7 is
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
to 1 if the kid is present in the compressed COSE object. to 1 if the kid is present in the compressed COSE object.
* The fifth least significant bit is the Context Hint flag, h: it * The fifth least significant bit is the kid context flag, h: it
is set to 1 if the compressed COSE object contains a Context is set to 1 if the compressed COSE object contains a kid
Hint, see Section 8.3. context, see Section 5.1.
* The sixth-eighth least significant bits are reserved and SHALL * The sixth least significant bit is reserved for indicating the
be set to zero when not in use. presence of a signature. This needs to be specified in a
separate document. The bit SHALL be set to zero when not in
use.
* The seventh least significant bit is reserved to expand the
flag byte. This needs to be specified in a separate document.
The bit SHALL be set to zero when not in use.
* The eighth least significant bit is reserved for indicating if
a non-compressed COSE object is used. This needs to be
specified in a separate document. The bit SHALL be set to zero
when not in use.
o The following n bytes encode the value of the Partial IV, if the o The following n bytes encode the value of the Partial IV, if the
Partial IV is present (n > 0). Partial IV is present (n > 0).
o The following 1 byte encode the length of the Context Hint o The following 1 byte encode the length of the kid context
(Section 8.3) s, if the Context Hint 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 Context Hint, if the Context Hint 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 object-security
value, even in case reserved bits are used and additional fields are value, even in case reserved bits are used and additional fields are
added to it. added to it.
8.2. Encoding of the OSCORE Payload 8.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.
8.3. Context Hint 8.3. Examples of Compressed COSE Objects
For certain use cases, e.g. deployments where the same Recipient ID
is used with multiple contexts, it is necessary or favorable for the
client to provide a Context Hint in order for the server to retrieve
the Recipient Context. The Context Hint is implicitly integrity
protected, as manipulation leads to the wrong or no context being
retrieved resulting in a verification error, as described in
Section 7.2. This parameter MAY be present in requests and SHALL NOT
be present in responses.
Examples:
o If the client has an identifier in some other namespace which can
be used by the server to retrieve or establish the security
context, then that identifier can be used as Context Hint.
o In case of a group communication scenario
[I-D.tiloca-core-multicast-oscoap], if the server belongs to
multiple groups, then a group identifier can be used as Context
Hint to enable the server to find the right security context.
8.4. Examples of Compressed COSE Objects 8.3.1. Example: Requests
8.4.1. Example: Requests
Request with kid = 25 and Partial IV = 5 Request with kid = 25 and Partial IV = 5
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'
] ]
skipping to change at page 31, line 34 skipping to change at page 32, line 42
Request with kid = empty string and Partial IV = 0 Request with kid = empty string and Partial IV = 0
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)
Request with kid = empty string, Partial IV = 5, and Context Hint = Request with kid = empty string, Partial IV = 5, and kid context =
0x44616c656b 0x44616c656b
After compression (22 bytes): After compression (22 bytes):
Flag byte: 0b00011001 = 0x19 Flag byte: 0b00011001 = 0x19
Option Value: 19 05 01 44 61 6c 65 6b (8 bytes) Option Value: 19 05 05 44 61 6c 65 6b (8 bytes)
Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes) Payload: ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9 (14 bytes)
8.4.2. Example: Response (without Observe) 8.3.2. Example: Response (without Observe)
Before compression (18 bytes): Before compression (18 bytes):
[ [
h'', h'',
{}, {},
h'aea0155667924dff8a24e4cb35b9' h'aea0155667924dff8a24e4cb35b9'
] ]
After compression (14 bytes): After compression (14 bytes):
Flag byte: 0b00000000 = 0x00 Flag byte: 0b00000000 = 0x00
Option Value: (0 bytes) Option Value: (0 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)
8.4.3. Example: Response (with Observe) 8.3.3. Example: Response (with Observe)
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):
skipping to change at page 33, line 16 skipping to change at page 34, line 18
RFC 7252 defines operations for a CoAP-to-CoAP proxy (see Section 5.7 RFC 7252 defines operations for a CoAP-to-CoAP proxy (see Section 5.7
of [RFC7252]) and for proxying between CoAP and HTTP (Section 10 of of [RFC7252]) and for proxying between CoAP and HTTP (Section 10 of
[RFC7252]). A more detailed description of the HTTP-to-CoAP mapping [RFC7252]). A more detailed description of the HTTP-to-CoAP mapping
is provided by [RFC8075]. This section describes the operations of is provided by [RFC8075]. This section describes the operations of
OSCORE-aware proxies. OSCORE-aware proxies.
10.1. CoAP-to-CoAP Forwarding Proxy 10.1. CoAP-to-CoAP Forwarding Proxy
OSCORE is designed to work with legacy CoAP-to-CoAP forward proxies OSCORE is designed to work with legacy CoAP-to-CoAP forward proxies
[RFC7252], but OSCORE-aware proxies provide certain simplifications [RFC7252], but OSCORE-aware proxies MAY provide certain
as specified in this section. simplifications as specified in this section.
The targeted proxy operations are specified in Section 2.2.1 of The targeted proxy operations are specified in Section 2.2.1 of
[I-D.hartke-core-e2e-security-reqs]. In particular caching is [I-D.hartke-core-e2e-security-reqs]. In particular caching is
disabled since the CoAP response is only applicable to the original disabled since the CoAP response is only applicable to the original
client's CoAP request. An OSCORE-aware proxy SHALL NOT cache a client's CoAP request. An OSCORE-aware proxy SHALL NOT cache a
response to a request with an Object-Security option. As a response to a request with an Object-Security option. As a
consequence, the search for cache hits and CoAP freshness/Max-Age consequence, the search for cache hits and CoAP freshness/Max-Age
processing can be omitted. processing can be omitted.
Proxy processing of the (Outer) Proxy-Uri option is as defined in Proxy processing of the (Outer) Proxy-Uri option is as defined in
[RFC7252]. [RFC7252].
Proxy processing of the (Outer) Block options is as defined in Proxy processing of the (Outer) Block options is as defined in
[RFC7959] and [I-D.amsuess-core-repeat-request-tag]. [RFC7959] and [I-D.ietf-core-echo-request-tag].
Proxy processing of the (Outer) Observe option is as defined in Proxy processing of the (Outer) Observe option is as defined in
[RFC7641]. OSCORE-aware proxies MAY look at the Partial IV value [RFC7641]. OSCORE-aware proxies MAY look at the Partial IV value
instead of the Outer Observe option. instead of the Outer Observe option.
10.2. HTTP-to-CoAP Translation Proxy 10.2. HTTP-to-CoAP Translation Proxy
Section 10.2 of [RFC7252] and [RFC8075] specify the behavior of an Section 10.2 of [RFC7252] and [RFC8075] specify the behavior of an
HTTP-to-CoAP proxy. As requested in Section 1 of [RFC8075], this HTTP-to-CoAP proxy. As requested in Section 1 of [RFC8075], this
section describes the HTTP mapping for the OSCORE protocol extension section describes the HTTP mapping for the OSCORE protocol extension
of CoAP. of CoAP.
The presence of the Object-Security option, both in requests and The presence of the Object-Security option, both in requests and
responses, is expressed in an HTTP header field named Object-Security responses, is expressed in an HTTP header field named Object-Security
in the mapped request or response. The value of the field is the in the mapped request or response. The value of the field is:
value of the Object-Security option Section 8.1 in base64url encoding
(Section 5 of [RFC4648]) without padding (see [RFC7515] Appendix C o "" (empty string) if the CoAP Object-Security option is empty, or
for implementation notes for this encoding). The value of the o the value of the CoAP Object-Security option Section 8.1 in
payload is the OSCORE payload Section 8.2, also base64url-encoded base64url encoding (Section 5 of [RFC4648]) without padding (see
without padding. [RFC7515] Appendix C for implementation notes for this encoding).
The value of the body is the OSCORE payload Section 8.2.
Example: Example:
Mapping and notation here is based on "Simple Form" (Section 5.4.1.1 Mapping and notation here is based on "Simple Form" (Section 5.4.1.1
of [RFC8075]). of [RFC8075]).
[HTTP request -- Before object security processing] [HTTP request -- Before object security processing]
GET http://proxy.url/hc/?target_uri=coap://server.url/orders HTTP/1.1 GET http://proxy.url/hc/?target_uri=coap://server.url/orders HTTP/1.1
[HTTP request -- HTTP Client to Proxy] [HTTP request -- HTTP Client to Proxy]
POST http://proxy.url/hc/?target_uri=coap://server.url/ HTTP/1.1 POST http://proxy.url/hc/?target_uri=coap://server.url/ HTTP/1.1
Object-Security: 0b 25 Object-Security: 09 25
Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary]
[CoAP request -- Proxy to CoAP Server] [CoAP request -- Proxy to CoAP Server]
POST coap://server.url/ POST coap://server.url/
Object-Security: 0b 25 Object-Security: 09 25
Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary]
[CoAP response -- CoAP Server to Proxy] [CoAP response -- CoAP Server to Proxy]
2.04 Changed 2.04 Changed
Object-Security: [empty] Object-Security: [empty]
Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary]
[HTTP response -- Proxy to HTTP Client] [HTTP response -- Proxy to HTTP Client]
HTTP/1.1 200 OK HTTP/1.1 200 OK
Object-Security: [empty] Object-Security: "" (empty string)
Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary]
[HTTP response -- After object security processing] [HTTP response -- After object security processing]
HTTP/1.1 200 OK HTTP/1.1 200 OK
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),
skipping to change at page 35, line 23 skipping to change at page 36, line 25
[CoAP request -- Before object security processing] [CoAP request -- Before 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: 0b 25 Object-Security: 09 25
Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary] Payload: 09 07 01 13 61 f7 0f d2 97 b1 [binary]
[HTTP request -- Proxy to HTTP Server] [HTTP request -- Proxy to HTTP Server]
POST http://server.url/ HTTP/1.1 POST http://server.url/ HTTP/1.1
Object-Security: 0b 25 Object-Security: 09 25
Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary] Body: 09 07 01 13 61 f7 0f d2 97 b1 [binary]
[HTTP response -- HTTP Server to Proxy] [HTTP response -- HTTP Server to Proxy]
HTTP/1.1 200 OK HTTP/1.1 200 OK
Object-Security: [empty] Object-Security: "" (empty string)
Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] Body: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary]
[CoAP response -- CoAP Server to Proxy] [CoAP response -- CoAP Server to Proxy]
2.04 Changed 2.04 Changed
Object-Security: [empty] Object-Security: [empty]
Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary] Payload: 00 31 d1 fc f6 70 fb 0c 1d d5 ... [binary]
[CoAP response -- After object security processing] [CoAP response -- After object security processing]
skipping to change at page 37, line 6 skipping to change at page 38, line 11
sequence numbers have their issues: very constrained devices may not sequence numbers have their issues: very constrained devices may not
be able to support accurate time, or to generate and store large be able to support accurate time, or to generate and store large
numbers of random nonces. The requirement to change key at counter numbers of random nonces. The requirement to change key at counter
wrap is a complication, but it also forces the user of this wrap is a complication, but it also forces the user of this
specification to think about implementing key renewal. specification to think about implementing key renewal.
The maximum sender sequence number is dependent on the AEAD The maximum sender sequence number is dependent on the AEAD
algorithm. The maximum sender sequence number SHALL be 2^40 - 1, or algorithm. The maximum sender sequence number SHALL be 2^40 - 1, or
any algorithm specific lower limit, after which a new security any algorithm specific lower limit, after which a new security
context must be generated. The mechanism to build the nonce context must be generated. The mechanism to build the nonce
(Section 5.1) assumes that the nonce is at least 56 bit-long, and the (Section 5.2) assumes that the nonce is at least 56 bit-long, and the
Partial IV is at most 40 bit-long. The mandatory-to-implement AEAD Partial IV is at most 40 bit-long. The mandatory-to-implement AEAD
algorithm AES-CCM-16-64-128 is selected for compatibility with CCM*. algorithm AES-CCM-16-64-128 is selected for compatibility with CCM*.
The inner block options enable the sender to split large messages The inner block options enable the sender to split large messages
into OSCORE-protected blocks such that the receiving node can verify into OSCORE-protected blocks such that the receiving node can verify
blocks before having received the complete message. The outer block blocks before having received the complete message. The outer block
options allow for arbitrary proxy fragmentation operations that options allow for arbitrary proxy fragmentation operations that
cannot be verified by the endpoints, but can by policy be restricted cannot be verified by the endpoints, but can by policy be restricted
in size since the encrypted options allow for secure fragmentation of in size since the encrypted options allow for secure fragmentation of
very large messages. A maximum message size (above which the sending very large messages. A maximum message size (above which the sending
skipping to change at page 37, line 30 skipping to change at page 38, line 35
12. Privacy Considerations 12. Privacy Considerations
Privacy threats executed through intermediate nodes are considerably Privacy threats executed through intermediate 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 4) may reveal privacy sensitive The unprotected options (Figure 5) may reveal privacy sensitive
information. In particular Uri-Host SHOULD NOT contain privacy information. In particular Uri-Host SHOULD NOT contain privacy
sensitive information. sensitive information.
CoAP headers sent in plaintext allow for example matching of CON and CoAP headers sent in plaintext allow for example matching of CON and
ACK (CoAP Message Identifier), matching of request and responses ACK (CoAP Message Identifier), matching of request and responses
(Token) and traffic analysis. (Token) and traffic analysis.
Using the mechanisms described in Section 6.5 may reveal when a Using the mechanisms described in Section 6.5 may reveal when a
device goes through a reboot. This can be mitigated by the device device goes through a reboot. This can be mitigated by the device
storing the precise state of sender sequence number and replay window storing the precise state of sender sequence number and replay window
skipping to change at page 38, line 18 skipping to change at page 39, line 23
style padding scheme where m bytes are appended each having the value style padding scheme where m bytes are appended each having the value
of m. For example, appending a 0 to "YES" and two 1's to "NO". This of m. For example, appending a 0 to "YES" and two 1's to "NO". This
style of padding means that all values need to be padded. Similar style of padding means that all values need to be padded. Similar
arguments apply to other message fields such as resource names. arguments apply to other message fields such as resource names.
13. IANA Considerations 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.
13.1. CoAP Option Numbers Registry 13.1. COSE Header Parameters Registry
The 'kid context' paramter is added to the "COSE Header Parameters
Registry":
o Name: kid context
o Label: kidctx
o Value Type: bstr
o Value Registry:
o Description: kid context
o Reference: Section 5.1 of this document
13.2. CoAP Option Numbers Registry
The Object-Security option is added to the CoAP Option Numbers The Object-Security option is added to the CoAP Option Numbers
registry: registry:
+--------+-----------------+-------------------+ +--------+-----------------+-------------------+
| Number | Name | Reference | | Number | Name | Reference |
+--------+-----------------+-------------------+ +--------+-----------------+-------------------+
| TBD | Object-Security | [[this document]] | | TBD | Object-Security | [[this document]] |
+--------+-----------------+-------------------+ +--------+-----------------+-------------------+
13.2. Header Field Registrations 13.3. Header Field Registrations
The HTTP header field Object-Security is added to the Message Headers The HTTP header field Object-Security is added to the Message Headers
registry: registry:
+-------------------+----------+----------+-------------------+ +-------------------+----------+----------+-------------------+
| Header Field Name | Protocol | Status | Reference | | Header Field Name | Protocol | Status | Reference |
+-------------------+----------+----------+-------------------+ +-------------------+----------+----------+-------------------+
| Object-Security | http | standard | [[this document]] | | Object-Security | http | standard | [[this document]] |
+-------------------+----------+----------+-------------------+ +-------------------+----------+----------+-------------------+
skipping to change at page 39, line 9 skipping to change at page 40, line 30
Fossati, Martin Gunnarsson, Klaus Hartke, Jim Schaad, Dave Thaler, Fossati, Martin Gunnarsson, Klaus Hartke, Jim Schaad, Dave Thaler,
Marco Tiloca, and Malisa Vu&#269;ini&#263;. Marco Tiloca, and Malisa Vu&#269;ini&#263;.
Ludwig Seitz and Goeran Selander worked on this document as part of Ludwig Seitz and Goeran Selander worked on this document as part of
the CelticPlus project CyberWI, with funding from Vinnova. the CelticPlus project CyberWI, with funding from Vinnova.
15. References 15. References
15.1. Normative References 15.1. Normative References
[I-D.amsuess-core-repeat-request-tag]
Amsuess, C., Mattsson, J., and G. Selander, "Repeat And
Request-Tag", draft-amsuess-core-repeat-request-tag-00
(work in progress), July 2017.
[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>.
[RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer
skipping to change at page 40, line 26 skipping to change at page 41, line 42
<https://www.rfc-editor.org/info/rfc8288>. <https://www.rfc-editor.org/info/rfc8288>.
15.2. Informative References 15.2. Informative References
[I-D.bormann-6lo-coap-802-15-ie] [I-D.bormann-6lo-coap-802-15-ie]
Bormann, C., "Constrained Application Protocol (CoAP) over Bormann, C., "Constrained Application Protocol (CoAP) over
IEEE 802.15.4 Information Element for IETF", draft- IEEE 802.15.4 Information Element for IETF", draft-
bormann-6lo-coap-802-15-ie-00 (work in progress), April bormann-6lo-coap-802-15-ie-00 (work in progress), April
2016. 2016.
[I-D.greevenbosch-appsawg-cbor-cddl]
Birkholz, H., Vigano, C., and C. Bormann, "Concise data
definition language (CDDL): a notational convention to
express CBOR data structures", draft-greevenbosch-appsawg-
cbor-cddl-11 (work in progress), July 2017.
[I-D.hartke-core-e2e-security-reqs] [I-D.hartke-core-e2e-security-reqs]
Selander, G., Palombini, F., and K. Hartke, "Requirements Selander, G., Palombini, F., and K. Hartke, "Requirements
for CoAP End-To-End Security", draft-hartke-core-e2e- for CoAP End-To-End Security", draft-hartke-core-e2e-
security-reqs-03 (work in progress), July 2017. security-reqs-03 (work in progress), July 2017.
[I-D.ietf-6tisch-minimal-security]
Vucinic, M., Simon, J., Pister, K., and M. Richardson,
"Minimal Security Framework for 6TiSCH", draft-ietf-
6tisch-minimal-security-04 (work in progress), October
2017.
[I-D.ietf-ace-oauth-authz] [I-D.ietf-ace-oauth-authz]
Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and
H. Tschofenig, "Authentication and Authorization for H. Tschofenig, "Authentication and Authorization for
Constrained Environments (ACE)", draft-ietf-ace-oauth- Constrained Environments (ACE)", draft-ietf-ace-oauth-
authz-07 (work in progress), August 2017. authz-09 (work in progress), November 2017.
[I-D.ietf-cbor-cddl]
Birkholz, H., Vigano, C., and C. Bormann, "Concise data
definition language (CDDL): a notational convention to
express CBOR data structures", draft-ietf-cbor-cddl-00
(work in progress), July 2017.
[I-D.ietf-core-coap-tcp-tls] [I-D.ietf-core-coap-tcp-tls]
Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., Bormann, C., Lemay, S., Tschofenig, H., Hartke, K.,
Silverajan, B., and B. Raymor, "CoAP (Constrained Silverajan, B., and B. Raymor, "CoAP (Constrained
Application Protocol) over TCP, TLS, and WebSockets", Application Protocol) over TCP, TLS, and WebSockets",
draft-ietf-core-coap-tcp-tls-09 (work in progress), May draft-ietf-core-coap-tcp-tls-10 (work in progress),
2017. October 2017.
[I-D.ietf-core-echo-request-tag]
Amsuess, C., Mattsson, J., and G. Selander, "Echo and
Request-Tag", draft-ietf-core-echo-request-tag-00 (work in
progress), October 2017.
[I-D.mattsson-core-coap-actuators] [I-D.mattsson-core-coap-actuators]
Mattsson, J., Fornehed, J., Selander, G., and F. Mattsson, J., Fornehed, J., Selander, G., Palombini, F.,
Palombini, "Controlling Actuators with CoAP", draft- and C. Amsuess, "Controlling Actuators with CoAP", draft-
mattsson-core-coap-actuators-02 (work in progress), mattsson-core-coap-actuators-03 (work in progress),
November 2016. October 2017.
[I-D.seitz-ace-oscoap-profile] [I-D.seitz-ace-oscoap-profile]
Seitz, L., Palombini, F., and M. Gunnarsson, "OSCOAP Seitz, L., Palombini, F., and M. Gunnarsson, "OSCORE
profile of the Authentication and Authorization for profile of the Authentication and Authorization for
Constrained Environments Framework", draft-seitz-ace- Constrained Environments Framework", draft-seitz-ace-
oscoap-profile-05 (work in progress), October 2017. oscoap-profile-06 (work in progress), October 2017.
[I-D.tiloca-core-multicast-oscoap] [I-D.tiloca-core-multicast-oscoap]
Tiloca, M., Selander, G., and F. Palombini, "Secure group Tiloca, M., Selander, G., Palombini, F., and J. Park,
communication for CoAP", draft-tiloca-core-multicast- "Secure group communication for CoAP", draft-tiloca-core-
oscoap-03 (work in progress), July 2017. multicast-oscoap-04 (work in progress), October 2017.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005, RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>. <https://www.rfc-editor.org/info/rfc3986>.
[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>.
skipping to change at page 42, line 36 skipping to change at page 44, line 30
| | 2.04 | Token: 0x7b | | 2.04 | Token: 0x7b
| | | Object-Security: - | | | Object-Security: -
| | | Payload: {Code:2.05, "OFF"} | | | Payload: {Code:2.05, "OFF"}
| | | | | |
|<------+ | Code: 2.04 (Changed) |<------+ | Code: 2.04 (Changed)
| 2.04 | | Token: 0x8c | 2.04 | | Token: 0x8c
| | | Object-Security: - | | | Object-Security: -
| | | Payload: {Code:2.05, "OFF"} | | | Payload: {Code:2.05, "OFF"}
| | | | | |
Figure 8: Secure Access to Sensor. Square brackets [ ... ] indicate Figure 11: Secure Access to Sensor. Square brackets [ ... ] indicate
content of compressed COSE object. Curly brackets { ... } indicate content of compressed COSE object. Curly brackets { ... } indicate
encrypted data. encrypted data.
The request/response Codes are encrypted by OSCORE and only dummy The request/response Codes are encrypted by OSCORE and only dummy
Codes (POST/Changed) are visible in the header of the OSCORE message. Codes (POST/Changed) are visible in the header of the OSCORE message.
The option Uri-Path ("alarm_status") and payload ("OFF") are The option Uri-Path ("alarm_status") and payload ("OFF") are
encrypted. encrypted.
The COSE header of the request contains an identifier (5f), The COSE header of the request contains an identifier (5f),
indicating which security context was used to protect the message and indicating which security context was used to protect the message and
skipping to change at page 43, line 29 skipping to change at page 45, line 21
| | | 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] | | | Object-Security: [kid:ca,Partial IV:15]
| | | Payload: {Code:0.01, | | | Payload: {Code:0.01,
| | | Uri-Path:"glucose"} | | | Uri-Path:"glucose"}
| | | | | |
| |<------+ Code: 2.05 (Content) | |<------+ Code: 2.04 (Changed)
| | 2.05 | Token: 0xbe | | 2.04 | Token: 0xbe
| | | Observe: 7 | | | Observe: 7
| | | Object-Security: [Partial IV:32] | | | Object-Security: [Partial IV:32]
| | | Payload: {Code:2.05, | | | Payload: {Code:2.05,
| | | Content-Format:0, "220"} | | | Content-Format:0, "220"}
| | | | | |
|<------+ | Code: 2.05 (Content) |<------+ | Code: 2.04 (Changed)
| 2.05 | | Token: 0x83 | 2.04 | | Token: 0x83
| | | Observe: 7 | | | Observe: 7
| | | Object-Security: [Partial IV:32] | | | Object-Security: [Partial IV:32]
| | | Payload: {Code:2.05, | | | Payload: {Code:2.05,
| | | Content-Format:0, "220"} | | | Content-Format:0, "220"}
... ... ... ... ... ...
| | | | | |
| |<------+ Code: 2.05 (Content) | |<------+ Code: 2.04 (Changed)
| | 2.05 | Token: 0xbe | | 2.04 | Token: 0xbe
| | | Observe: 8 | | | Observe: 8
| | | Object-Security: [Partial IV:36] | | | Object-Security: [Partial IV:36]
| | | Payload: {Code:2.05, | | | Payload: {Code:2.05,
| | | Content-Format:0, "180"} | | | Content-Format:0, "180"}
| | | | | |
|<------+ | Code: 2.05 (Content) |<------+ | Code: 2.04 (Changed)
| 2.05 | | Token: 0x83 | 2.04 | | Token: 0x83
| | | Observe: 8 | | | Observe: 8
| | | Object-Security: [Partial IV:36] | | | Object-Security: [Partial IV:36]
| | | Payload: {Code:2.05, | | | Payload: {Code:2.05,
| | | Content-Format:0, "180"} | | | Content-Format:0, "180"}
| | | | | |
Figure 9: Secure Subscribe to Sensor. Square brackets [ ... ] Figure 12: Secure Subscribe to Sensor. Square brackets [ ... ]
indicate content of compressed COSE header. Curly brackets { ... } indicate content of compressed COSE header. Curly brackets { ... }
indicate encrypted data. indicate encrypted data.
The request/response Codes are encrypted by OSCORE and only dummy The request/response Codes are encrypted by OSCORE and only dummy
Codes (FETCH/Content) are visible in the header of the OSCORE Codes (FETCH/Changed) are visible in the header of the OSCORE
message. The options Content-Format (0) and the payload ("220" and message. The options Content-Format (0) and the payload ("220" and
"180"), are encrypted. "180"), are encrypted.
The COSE header of the request contains an identifier (ca), The COSE header of the request contains an identifier (ca),
indicating the security context used to protect the message and a indicating the security context used to protect the message and a
Partial IV (15). The COSE headers of the responses contains Partial Partial IV (15). The COSE headers of the responses contains Partial
IVs (32 and 36). IVs (32 and 36).
The server verifies that the Partial IV has not been received before. The server verifies that the Partial IV has not been received before.
The client verifies that the responses are bound to the request and The client verifies that the responses are bound to the request and
 End of changes. 117 change blocks. 
350 lines changed or deleted 440 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/