draft-ietf-core-object-security-12.txt   draft-ietf-core-object-security-13.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: October 1, 2018 Ericsson AB Expires: December 29, 2018 Ericsson AB
L. Seitz L. Seitz
RISE SICS RISE SICS
March 30, 2018 June 27, 2018
Object Security for Constrained RESTful Environments (OSCORE) Object Security for Constrained RESTful Environments (OSCORE)
draft-ietf-core-object-security-12 draft-ietf-core-object-security-13
Abstract Abstract
This document defines Object Security for Constrained RESTful This document defines Object Security for Constrained RESTful
Environments (OSCORE), a method for application-layer protection of Environments (OSCORE), a method for application-layer protection of
the Constrained Application Protocol (CoAP), using CBOR Object the Constrained Application Protocol (CoAP), using CBOR Object
Signing and Encryption (COSE). OSCORE provides end-to-end protection Signing and Encryption (COSE). OSCORE provides end-to-end protection
between endpoints communicating using CoAP or CoAP-mappable HTTP. between endpoints communicating using CoAP or CoAP-mappable HTTP.
OSCORE is designed for constrained nodes and networks supporting a OSCORE is designed for constrained nodes and networks supporting a
range of proxy operations, including translation between different range of proxy operations, including translation between different
skipping to change at page 1, line 40 skipping to change at page 1, line 40
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on October 1, 2018. This Internet-Draft will expire on December 29, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6
2. The OSCORE Option . . . . . . . . . . . . . . . . . . . . . . 7 2. The OSCORE Option . . . . . . . . . . . . . . . . . . . . . . 7
3. The Security Context . . . . . . . . . . . . . . . . . . . . 7 3. The Security Context . . . . . . . . . . . . . . . . . . . . 7
3.1. Security Context Definition . . . . . . . . . . . . . . . 7 3.1. Security Context Definition . . . . . . . . . . . . . . . 8
3.2. Establishment of Security Context Parameters . . . . . . 10 3.2. Establishment of Security Context Parameters . . . . . . 10
3.3. Requirements on the Security Context Parameters . . . . . 12 3.3. Requirements on the Security Context Parameters . . . . . 12
4. Protected Message Fields . . . . . . . . . . . . . . . . . . 12 4. Protected Message Fields . . . . . . . . . . . . . . . . . . 13
4.1. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 13 4.1. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 14
4.2. CoAP Header Fields and Payload . . . . . . . . . . . . . 20 4.2. CoAP Header Fields and Payload . . . . . . . . . . . . . 21
4.3. Signaling Messages . . . . . . . . . . . . . . . . . . . 21 4.3. Signaling Messages . . . . . . . . . . . . . . . . . . . 23
5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 22 5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 23
5.1. Kid Context . . . . . . . . . . . . . . . . . . . . . . . 23 5.1. Kid Context . . . . . . . . . . . . . . . . . . . . . . . 24
5.2. Nonce . . . . . . . . . . . . . . . . . . . . . . . . . . 24 5.2. Nonce . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.3. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 25 5.3. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 26
5.4. Additional Authenticated Data . . . . . . . . . . . . . . 26 5.4. Additional Authenticated Data . . . . . . . . . . . . . . 27
6. OSCORE Header Compression . . . . . . . . . . . . . . . . . . 26 6. OSCORE Header Compression . . . . . . . . . . . . . . . . . . 28
6.1. Encoding of the OSCORE Option Value . . . . . . . . . . . 27 6.1. Encoding of the OSCORE Option Value . . . . . . . . . . . 28
6.2. Encoding of the OSCORE Payload . . . . . . . . . . . . . 28 6.2. Encoding of the OSCORE Payload . . . . . . . . . . . . . 30
6.3. Examples of Compressed COSE Objects . . . . . . . . . . . 28 6.3. Examples of Compressed COSE Objects . . . . . . . . . . . 30
7. Message Binding, Sequence Numbers, Freshness and Replay 7. Message Binding, Sequence Numbers, Freshness and Replay
Protection . . . . . . . . . . . . . . . . . . . . . . . . . 31 Protection . . . . . . . . . . . . . . . . . . . . . . . . . 32
7.1. Message Binding . . . . . . . . . . . . . . . . . . . . . 31 7.1. Message Binding . . . . . . . . . . . . . . . . . . . . . 32
7.2. Sequence Numbers . . . . . . . . . . . . . . . . . . . . 31 7.2. Sequence Numbers . . . . . . . . . . . . . . . . . . . . 32
7.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 31 7.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 33
7.4. Replay Protection . . . . . . . . . . . . . . . . . . . . 32 7.4. Replay Protection . . . . . . . . . . . . . . . . . . . . 33
7.5. Losing Part of the Context State . . . . . . . . . . . . 32 7.5. Losing Part of the Context State . . . . . . . . . . . . 34
8. Processing . . . . . . . . . . . . . . . . . . . . . . . . . 34 8. Processing . . . . . . . . . . . . . . . . . . . . . . . . . 35
8.1. Protecting the Request . . . . . . . . . . . . . . . . . 34 8.1. Protecting the Request . . . . . . . . . . . . . . . . . 36
8.2. Verifying the Request . . . . . . . . . . . . . . . . . . 34 8.2. Verifying the Request . . . . . . . . . . . . . . . . . . 36
8.3. Protecting the Response . . . . . . . . . . . . . . . . . 36 8.3. Protecting the Response . . . . . . . . . . . . . . . . . 37
8.4. Verifying the Response . . . . . . . . . . . . . . . . . 36 8.4. Verifying the Response . . . . . . . . . . . . . . . . . 38
9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 38 9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 40
10. CoAP-to-CoAP Forwarding Proxy . . . . . . . . . . . . . . . . 38 10. CoAP-to-CoAP Forwarding Proxy . . . . . . . . . . . . . . . . 41
11. HTTP Operations . . . . . . . . . . . . . . . . . . . . . . . 39 11. HTTP Operations . . . . . . . . . . . . . . . . . . . . . . . 42
11.1. The HTTP OSCORE Header Field . . . . . . . . . . . . . . 39 11.1. The HTTP OSCORE Header Field . . . . . . . . . . . . . . 42
11.2. CoAP-to-HTTP Mapping . . . . . . . . . . . . . . . . . . 40 11.2. CoAP-to-HTTP Mapping . . . . . . . . . . . . . . . . . . 43
11.3. HTTP-to-CoAP Mapping . . . . . . . . . . . . . . . . . . 40 11.3. HTTP-to-CoAP Mapping . . . . . . . . . . . . . . . . . . 43
11.4. HTTP Endpoints . . . . . . . . . . . . . . . . . . . . . 41 11.4. HTTP Endpoints . . . . . . . . . . . . . . . . . . . . . 44
11.5. Example: HTTP Client and CoAP Server . . . . . . . . . . 41 11.5. Example: HTTP Client and CoAP Server . . . . . . . . . . 44
11.6. Example: CoAP Client and HTTP Server . . . . . . . . . . 43 11.6. Example: CoAP Client and HTTP Server . . . . . . . . . . 46
12. Security Considerations . . . . . . . . . . . . . . . . . . . 44 12. Security Considerations . . . . . . . . . . . . . . . . . . . 47
12.1. End-to-end Protection . . . . . . . . . . . . . . . . . 44 12.1. End-to-end Protection . . . . . . . . . . . . . . . . . 47
12.2. Security Context Establishment . . . . . . . . . . . . . 45 12.2. Security Context Establishment . . . . . . . . . . . . . 48
12.3. Master Secret . . . . . . . . . . . . . . . . . . . . . 45 12.3. Master Secret . . . . . . . . . . . . . . . . . . . . . 48
12.4. Replay Protection . . . . . . . . . . . . . . . . . . . 45 12.4. Replay Protection . . . . . . . . . . . . . . . . . . . 48
12.5. Client Aliveness . . . . . . . . . . . . . . . . . . . . 46 12.5. Client Aliveness . . . . . . . . . . . . . . . . . . . . 49
12.6. Cryptographic Considerations . . . . . . . . . . . . . . 46 12.6. Cryptographic Considerations . . . . . . . . . . . . . . 49
12.7. Message Segmentation . . . . . . . . . . . . . . . . . . 46 12.7. Message Segmentation . . . . . . . . . . . . . . . . . . 49
12.8. Privacy Considerations . . . . . . . . . . . . . . . . . 47 12.8. Privacy Considerations . . . . . . . . . . . . . . . . . 50
13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 50
13.1. COSE Header Parameters Registry . . . . . . . . . . . . 47 13.1. COSE Header Parameters Registry . . . . . . . . . . . . 51
13.2. CoAP Option Numbers Registry . . . . . . . . . . . . . . 48 13.2. CoAP Option Numbers Registry . . . . . . . . . . . . . . 51
13.3. CoAP Signaling Option Numbers Registry . . . . . . . . . 48 13.3. CoAP Signaling Option Numbers Registry . . . . . . . . . 51
13.4. Header Field Registrations . . . . . . . . . . . . . . . 48 13.4. Header Field Registrations . . . . . . . . . . . . . . . 51
13.5. Media Type Registrations . . . . . . . . . . . . . . . . 49 13.5. Media Type Registrations . . . . . . . . . . . . . . . . 52
13.6. CoAP Content-Formats Registry . . . . . . . . . . . . . 51 13.6. CoAP Content-Formats Registry . . . . . . . . . . . . . 54
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 51 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 54
14.1. Normative References . . . . . . . . . . . . . . . . . . 51 14.1. Normative References . . . . . . . . . . . . . . . . . . 54
14.2. Informative References . . . . . . . . . . . . . . . . . 53 14.2. Informative References . . . . . . . . . . . . . . . . . 56
Appendix A. Scenario Examples . . . . . . . . . . . . . . . . . 55 Appendix A. Scenario Examples . . . . . . . . . . . . . . . . . 58
A.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 55 A.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 58
A.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 56 A.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 59
Appendix B. Deployment Examples . . . . . . . . . . . . . . . . 57 Appendix B. Deployment Examples . . . . . . . . . . . . . . . . 60
B.1. Master Secret Used Once . . . . . . . . . . . . . . . . . 57 B.1. Master Secret Used Once . . . . . . . . . . . . . . . . . 60
B.2. Master Secret Used Multiple Times . . . . . . . . . . . . 58 B.2. Master Secret Used Multiple Times . . . . . . . . . . . . 61
Appendix C. Test Vectors . . . . . . . . . . . . . . . . . . . . 59 Appendix C. Test Vectors . . . . . . . . . . . . . . . . . . . . 62
C.1. Test Vector 1: Key Derivation with Master Salt . . . . . 59 C.1. Test Vector 1: Key Derivation with Master Salt . . . . . 62
C.2. Test Vector 2: Key Derivation without Master Salt . . . . 60 C.2. Test Vector 2: Key Derivation without Master Salt . . . . 63
C.3. Test Vector 3: OSCORE Request, Client . . . . . . . . . . 61 C.3. Test Vector 3: Key Derivation with ID Context . . . . . . 64
C.4. Test Vector 4: OSCORE Request, Client . . . . . . . . . . 63 C.4. Test Vector 4: OSCORE Request, Client . . . . . . . . . . 66
C.5. Test Vector 5: OSCORE Response, Server . . . . . . . . . 64 C.5. Test Vector 5: OSCORE Request, Client . . . . . . . . . . 67
C.6. Test Vector 6: OSCORE Response with Partial IV, Server . 65 C.6. Test Vector 6: OSCORE Request, Client . . . . . . . . . . 68
Appendix D. Overview of Security Properties . . . . . . . . . . 66 C.7. Test Vector 7: OSCORE Response, Server . . . . . . . . . 69
D.1. Supporting Proxy Operations . . . . . . . . . . . . . . . 66 C.8. Test Vector 8: OSCORE Response with Partial IV, Server . 70
D.2. Protected Message Fields . . . . . . . . . . . . . . . . 66 Appendix D. Overview of Security Properties . . . . . . . . . . 71
D.3. Uniqueness of (key, nonce) . . . . . . . . . . . . . . . 67 D.1. Supporting Proxy Operations . . . . . . . . . . . . . . . 71
D.4. Unprotected Message Fields . . . . . . . . . . . . . . . 68 D.2. Protected Message Fields . . . . . . . . . . . . . . . . 72
Appendix E. CDDL Summary . . . . . . . . . . . . . . . . . . . . 71 D.3. Uniqueness of (key, nonce) . . . . . . . . . . . . . . . 73
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 72 D.4. Unprotected Message Fields . . . . . . . . . . . . . . . 74
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 72 Appendix E. CDDL Summary . . . . . . . . . . . . . . . . . . . . 76
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 77
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 77
1. Introduction 1. Introduction
The Constrained Application Protocol (CoAP) [RFC7252] is a web The Constrained Application Protocol (CoAP) [RFC7252] is a web
transfer protocol, designed for constrained nodes and networks transfer protocol, designed for constrained nodes and networks
[RFC7228], and may be mapped from HTTP [RFC8075]. CoAP specifies the [RFC7228], and may be mapped from HTTP [RFC8075]. CoAP specifies the
use of proxies for scalability and efficiency and references DTLS use of proxies for scalability and efficiency and references DTLS
[RFC6347] for security. CoAP-to-CoAP, HTTP-to-CoAP, and CoAP-to-HTTP [RFC6347] for security. CoAP-to-CoAP, HTTP-to-CoAP, and CoAP-to-HTTP
proxies require DTLS or TLS [RFC5246] to be terminated at the proxy. proxies require DTLS or TLS [RFC5246] to be terminated at the proxy.
The proxy therefore not only has access to the data required for The proxy therefore not only has access to the data required for
skipping to change at page 5, line 13 skipping to change at page 5, line 33
addition to what is required by CoAP. Examples of the use of OSCORE addition to what is required by CoAP. Examples of the use of OSCORE
are given in Appendix A. OSCORE does not depend on underlying are given in Appendix A. OSCORE does not depend on underlying
layers, and can be used with non-IP transports (e.g., layers, and can be used with non-IP transports (e.g.,
[I-D.bormann-6lo-coap-802-15-ie]). OSCORE may also be used in [I-D.bormann-6lo-coap-802-15-ie]). OSCORE may also be used in
different ways with HTTP. OSCORE messages may be transported in different ways with HTTP. OSCORE messages may be transported in
HTTP, and OSCORE may also be used to protect CoAP-mappable HTTP HTTP, and OSCORE may also be used to protect CoAP-mappable HTTP
messages, as described below. messages, as described below.
OSCORE is designed to protect as much information as possible while OSCORE is designed to protect as much information as possible while
still allowing CoAP proxy operations (Section 10). It works with still allowing CoAP proxy operations (Section 10). It works with
legacy CoAP-to-CoAP forward proxies [RFC7252], but an OSCORE-aware existing CoAP-to-CoAP forward proxies [RFC7252], but an OSCORE-aware
proxy will be more efficient. HTTP-to-CoAP proxies [RFC8075] and proxy will be more efficient. HTTP-to-CoAP proxies [RFC8075] and
CoAP-to-HTTP proxies can also be used with OSCORE, as specified in CoAP-to-HTTP proxies can also be used with OSCORE, as specified in
Section 11. OSCORE may be used together with TLS or DTLS over one or Section 11. OSCORE may be used together with TLS or DTLS over one or
more hops in the end-to-end path, e.g. transported with HTTPS in one more hops in the end-to-end path, e.g. transported with HTTPS in one
hop and with plain CoAP in another hop. The use of OSCORE does not hop and with plain CoAP in another hop. The use of OSCORE does not
affect the URI scheme and OSCORE can therefore be used with any URI affect the URI scheme and OSCORE can therefore be used with any URI
scheme defined for CoAP or HTTP. The application decides the scheme defined for CoAP or HTTP. The application decides the
conditions for which OSCORE is required. conditions for which OSCORE is required.
OSCORE uses pre-shared keys which may have been established out-of- OSCORE uses pre-shared keys which may have been established out-of-
skipping to change at page 6, line 49 skipping to change at page 7, line 10
path. The concept "hop-by-hop" (as in "hop-by-hop encryption" or path. The concept "hop-by-hop" (as in "hop-by-hop encryption" or
"hop-by-hop fragmentation") opposed to "end-to-end", is used in this "hop-by-hop fragmentation") opposed to "end-to-end", is used in this
document to indicate that the messages are processed accordingly in document to indicate that the messages are processed accordingly in
the intermediaries, rather than just forwarded to the next node. the intermediaries, rather than just forwarded to the next node.
The term "stop processing" is used throughout the document to denote The term "stop processing" is used throughout the document to denote
that the message is not passed up to the CoAP Request/Response layer that the message is not passed up to the CoAP Request/Response layer
(see Figure 1). (see Figure 1).
The terms Common/Sender/Recipient Context, Master Secret/Salt, Sender The terms Common/Sender/Recipient Context, Master Secret/Salt, Sender
ID/Key, Recipient ID/Key, and Common IV are defined in Section 3.1. ID/Key, Recipient ID/Key, ID Context, and Common IV are defined in
Section 3.1.
2. The OSCORE Option 2. The OSCORE Option
The OSCORE option (see Figure 3, which extends Table 4 of [RFC7252]) The OSCORE option (see Figure 3, which extends Table 4 of [RFC7252])
indicates that the CoAP message is an OSCORE message and that it indicates that the CoAP message is an OSCORE message and that it
contains a compressed COSE object (see Section 5 and Section 6). The contains a compressed COSE object (see Sections 5 and 6). The OSCORE
OSCORE option is critical, safe to forward, part of the cache key, option is critical, safe to forward, part of the cache key, and not
and not repeatable. repeatable.
+------+---+---+---+---+-----------------+--------+--------+---------+ +------+---+---+---+---+----------------+--------+--------+---------+
| No. | C | U | N | R | Name | Format | Length | Default | | No. | C | U | N | R | Name | Format | Length | Default |
+------+---+---+---+---+-----------------+--------+--------+---------+ +------+---+---+---+---+----------------+--------+--------+---------+
| TBD1 | x | | | | OSCORE | (*) | 0-255 | (none) | | TBD1 | x | | | | OSCORE | (*) | 0-255 | (none) |
+------+---+---+---+---+-----------------+--------+--------+---------+ +------+---+---+---+---+----------------+--------+--------+---------+
C = Critical, U = Unsafe, N = NoCacheKey, R = Repeatable C = Critical, U = Unsafe, N = NoCacheKey, R = Repeatable
(*) See below. (*) See below.
Figure 3: The OSCORE Option Figure 3: The OSCORE Option
The OSCORE option includes the OSCORE flag bits (Section 6), the The OSCORE option includes the OSCORE flag bits (Section 6), the
Sender Sequence Number and the Sender ID when present (Section 3). Sender Sequence Number, the Sender ID, and the ID Context when these
The detailed format and length is specified in Section 6. If the fields are present (Section 3). The detailed format and length is
OSCORE flag bits are all zero (0x00) the Option value SHALL be empty specified in Section 6. If the OSCORE flag bits are all zero (0x00)
(Option Length = 0). An endpoint receiving a CoAP message without the Option value SHALL be empty (Option Length = 0). An endpoint
payload, that also contains an OSCORE option SHALL treat it as receiving a CoAP message without payload, that also contains an
malformed and reject it. OSCORE option SHALL treat it as malformed and reject it.
A successful response to a request with the OSCORE option SHALL A successful response to a request with the OSCORE option SHALL
contain the OSCORE option. Whether error responses contain the contain the OSCORE option. Whether error responses contain the
OSCORE option depends on the error type (see Section 8). OSCORE option depends on the error type (see Section 8).
For CoAP proxy operations, see Section 10. For CoAP proxy operations, see Section 10.
3. The Security Context 3. The Security Context
OSCORE requires that client and server establish a shared security OSCORE requires that client and server establish a shared security
skipping to change at page 8, line 41 skipping to change at page 8, line 50
| | RID = kid | | RID = kid
| | Verify request with | | Verify request with
| | Recipient Context | | Recipient Context
| OSCORE response: | Protect response with | OSCORE response: | Protect response with
| Token = Token1, ... | Sender Context | Token = Token1, ... | Sender Context
Retrieve context with |<----------------------+ Retrieve context with |<----------------------+
Token = Token1 | | Token = Token1 | |
Verify request with | | Verify request with | |
Recipient Context | | Recipient Context | |
Figure 4: Retrieval and use of the Security Context Figure 4: Retrieval and Use of the Security Context
The Common Context contains the following parameters: The Common Context contains the following parameters:
o AEAD Algorithm. The COSE AEAD algorithm to use for encryption. o AEAD Algorithm. The COSE AEAD algorithm to use for encryption.
o Key Derivation Function. The HMAC based HKDF [RFC5869] used to o Key Derivation Function. The HMAC based HKDF [RFC5869] used to
derive Sender Key, Recipient Key, and Common IV. derive Sender Key, Recipient Key, and Common IV.
o Master Secret. Variable length, random byte string (see o Master Secret. Variable length, random byte string (see
Section 12.3) containing the keying material used to derive Section 12.3) used to derive traffic keys and IVs.
traffic keys and IVs.
o Master Salt. Variable length byte string containing the salt used o Master Salt. Optional variable length byte string containing the
to derive traffic keys and IVs. salt used to derive traffic keys and IVs.
o Common IV. Byte string derived from Master Secret and Master o ID Context. Optional variable length byte string providing
Salt. Length is determined by the AEAD Algorithm. additional information to identify the Common Context and to
derive traffic keys and IVs.
o Common IV. Byte string derived from Master Secret, Master Salt,
and ID Context. Length is determined by the AEAD Algorithm.
The Sender Context contains the following parameters: The Sender Context contains the following parameters:
o Sender ID. Byte string used to identify the Sender Context and to o Sender ID. Byte string used to identify the Sender Context, to
assure unique AEAD nonces. Maximum length is determined by the derive traffic keys and IVs, and to assure unique nonces. Maximum
AEAD Algorithm. length is determined by the AEAD Algorithm.
o Sender Key. Byte string containing the symmetric key to protect o Sender Key. Byte string containing the symmetric key to protect
messages to send. Derived from Common Context and Sender ID. messages to send. Derived from Common Context and Sender ID.
Length is determined by the AEAD Algorithm. Length is determined by the AEAD Algorithm.
o Sender Sequence Number. Non-negative integer used by the sender o Sender Sequence Number. Non-negative integer used by the sender
to protect requests and certain responses, e.g. Observe to protect requests and certain responses, e.g. Observe
notifications. Used as 'Partial IV' [RFC8152] to generate unique notifications. Used as 'Partial IV' [RFC8152] to generate unique
nonces for the AEAD. Maximum value is determined by the AEAD nonces for the AEAD. Maximum value is determined by the AEAD
Algorithm. Algorithm.
The Recipient Context contains the following parameters: The Recipient Context contains the following parameters:
o Recipient ID. Byte string used to identify the Recipient Context o Recipient ID. Byte string used to identify the Recipient Context,
and to assure unique AEAD nonces. Maximum length is determined by to derive traffic keys and IVs, and to assure unique nonces.
the AEAD Algorithm. Maximum length is determined by the AEAD Algorithm.
o Recipient Key. Byte string containing the symmetric key to verify o Recipient Key. Byte string containing the symmetric key to verify
messages received. Derived from Common Context and Recipient ID. messages received. Derived from Common Context and Recipient ID.
Length is determined by the AEAD Algorithm. Length is determined by the AEAD Algorithm.
o Replay Window (Server only). The replay window to verify requests o Replay Window (Server only). The replay window to verify requests
received. received.
All parameters except Sender Sequence Number and Replay Window are All parameters except Sender Sequence Number and Replay Window are
immutable once the security context is established. An endpoint may immutable once the security context is established. An endpoint may
free up memory by not storing the Common IV, Sender Key, and free up memory by not storing the Common IV, Sender Key, and
Recipient Key, deriving them from the Master Key and Master Salt when Recipient Key, deriving them when needed. Alternatively, an endpoint
needed. Alternatively, an endpoint may free up memory by not storing may free up memory by not storing the Master Secret and Master Salt
the Master Secret and Master Salt after the other parameters have after the other parameters have been derived.
been derived.
Endpoints MAY operate as both client and server and use the same Endpoints MAY operate as both client and server and use the same
security context for those roles. Independent of being client or security context for those roles. Independent of being client or
server, the endpoint protects messages to send using its Sender server, the endpoint protects messages to send using its Sender
Context, and verifies messages received using its Recipient Context. Context, and verifies messages received using its Recipient Context.
The endpoints MUST NOT change the Sender/Recipient ID when changing The endpoints MUST NOT change the Sender/Recipient ID when changing
roles. In other words, changing the roles does not change the set of roles. In other words, changing the roles does not change the set of
keys to be used. keys to be used.
3.2. Establishment of Security Context Parameters 3.2. Establishment of Security Context Parameters
skipping to change at page 10, line 29 skipping to change at page 10, line 42
The following input parameters MAY be pre-established. In case any The following input parameters MAY be pre-established. In case any
of these parameters is not pre-established, the default value of these parameters is not pre-established, the default value
indicated below is used: indicated below is used:
o AEAD Algorithm o AEAD Algorithm
* Default is AES-CCM-16-64-128 (COSE algorithm encoding: 10) * Default is AES-CCM-16-64-128 (COSE algorithm encoding: 10)
o Master Salt o Master Salt
* Default is the empty string * Default is the empty byte string
o Key Derivation Function (KDF) o Key Derivation Function (KDF)
* Default is HKDF SHA-256 * Default is HKDF SHA-256
o Replay Window Type and Size o Replay Window Type and Size
* Default is DTLS-type replay protection with a window size of 32 * Default is DTLS-type replay protection with a window size of 32
[RFC6347] [RFC6347]
All input parameters need to be known to and agreed on by both All input parameters need to be known to and agreed on by both
endpoints, but the replay window may be different in the two endpoints, but the replay window may be different in the two
endpoints. The way the input parameters are pre-established, is endpoints. The way the input parameters are pre-established, is
application specific. Considerations of security context application specific. Considerations of security context
establishment are given in Section 12.2 and examples of deploying establishment are given in Section 12.2 and examples of deploying
OSCORE in Appendix B. OSCORE in Appendix B.
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 for COSE [RFC8152]. HKDF SHA-256 is mandatory to implement.
security context parameters Sender Key, Recipient Key, and Common IV The security context parameters Sender Key, Recipient Key, and Common
SHALL be derived from the input parameters using the HKDF, which IV SHALL be derived from the input parameters using the HKDF, which
consists of the composition of the HKDF-Extract and HKDF-Expand steps consists of the composition of the HKDF-Extract and HKDF-Expand steps
[RFC5869]: [RFC5869]:
output parameter = HKDF(salt, IKM, info, L) output parameter = HKDF(salt, IKM, info, L)
where: where:
o salt is the Master Salt as defined above o salt is the Master Salt as defined above
o IKM is the Master Secret as defined above o IKM is the Master Secret as defined above
o info is a CBOR array consisting of: o info is the serialization of a CBOR array consisting of:
info = [ info = [
id : bstr, id : bstr,
id_context : bstr / nil,
alg_aead : int / tstr, alg_aead : int / tstr,
type : tstr, type : tstr,
L : uint L : uint
] ]
where: where:
o id is the Sender ID or Recipient ID when deriving keys and the o id is the Sender ID or Recipient ID when deriving keys and the
empty string when deriving the Common IV. The encoding is empty byte string when deriving the Common IV. The encoding is
described in Section 5. described in Section 5.
o id_context is the ID Context, or nil if ID Context is not
provided.
o alg_aead is the AEAD Algorithm, encoded as defined in [RFC8152]. o alg_aead is the AEAD Algorithm, encoded as defined in [RFC8152].
o type is "Key" or "IV". The label is an ASCII string, and does not o type is "Key" or "IV". The label is an ASCII string, and does not
include a trailing NUL byte. include a trailing NUL byte.
o L is the size of the key/IV for the AEAD algorithm used, in bytes. o L is the size of the key/IV for the AEAD algorithm used, in bytes.
For example, if the algorithm AES-CCM-16-64-128 (see Section 10.2 in For example, if the algorithm AES-CCM-16-64-128 (see Section 10.2 in
[RFC8152]) is used, the integer value for alg_aead is 10, the value [RFC8152]) is used, the integer value for alg_aead is 10, the value
for L is 16 for keys and 13 for the Common IV. for L is 16 for keys and 13 for the Common IV.
Note that [RFC5869] specifies that if the salt is not provided, it is
set to a string of zeros. For implementation purposes, not providing
the salt is the same as setting the salt to the empty byte string.
OSCORE sets the salt default value to empty byte string, which in
[RFC5869] is converted to a string of zeroes (see Section 2.2 of
[RFC5869]).
3.2.2. Initial Sequence Numbers and Replay Window 3.2.2. Initial Sequence Numbers and Replay Window
The Sender Sequence Number is initialized to 0. The supported types The Sender Sequence Number is initialized to 0. The supported types
of replay protection and replay window length is application specific of replay protection and replay window length is application specific
and depends on how OSCORE is transported, see Section 7.4. The and depends on how OSCORE is transported, see Section 7.4. The
default is DTLS-type replay protection with a window size of 32 default is DTLS-type replay protection with a window size of 32
initiated as described in Section 4.1.2.6 of [RFC6347]. initiated as described in Section 4.1.2.6 of [RFC6347].
3.3. Requirements on the Security Context Parameters 3.3. Requirements on the Security Context Parameters
As collisions may lead to the loss of both confidentiality and To ensure unique Sender Keys, the quartet (Master Secret, Master
integrity, Sender ID SHALL be unique in the set of all security Salt, ID Context, Sender ID) MUST be unique, i.e. the pair (ID
contexts using the same Master Secret and Master Salt. To assign Context, Sender ID) SHALL be unique in the set of all security
identifiers, a trusted third party (e.g., [I-D.ietf-ace-oauth-authz]) contexts using the same Master Secret and Master Salt. The
or a protocol that allows the parties to negotiate locally unique requirement that Sender ID SHALL be unique in the set of all security
identifiers can be used. The Sender IDs can be very short. The contexts using the same Master Secret, Master Salt, and ID Context
maximum length of Sender ID in bytes equals the length of AEAD nonce guarantees unique (key, nonce) pairs, which avoids nonce reuse.
minus 6. For AES-CCM-16-64-128 the maximum length of Sender ID is 7
bytes. Different methods can be used to assign Sender IDs: a protocol that
allows the parties to negotiate locally unique identifiers, a trusted
third party (e.g., [I-D.ietf-ace-oauth-authz]), or the identifiers
can be assigned out-of-band. The Sender IDs can be very short (note
that the empty string is a legitimate value). The maximum length of
Sender ID in bytes equals the length of AEAD nonce minus 6. For AES-
CCM-16-64-128 the maximum length of Sender ID is 7 bytes.
To simplify retrieval of the right Recipient Context, the Recipient To simplify retrieval of the right Recipient Context, the Recipient
ID SHOULD be unique in the sets of all Recipient Contexts used by an ID SHOULD be unique in the sets of all Recipient Contexts used by an
endpoint. If an endpoint has the same Recipient ID with different endpoint. If an endpoint has the same Recipient ID with different
Recipient Contexts, i.e. the Recipient Contexts are derived from Recipient Contexts, i.e. the Recipient Contexts are derived from
different keying material, then the endpoint may need to try multiple different Common Contexts, then the endpoint may need to try multiple
times before finding the right security context associated to the times before verifying the right security context associated to the
Recipient ID. The Client MAY provide a 'kid context' parameter Recipient ID.
(Section 5.1) to help the Server find the right context.
While the triple (Master Secret, Master Salt, Sender ID) MUST be The ID Context is used to distinguish between security contexts. The
unique, the same Master Salt MAY be used with several Master Secrets methods used for assigning Sender ID can also be used for assigning
and the same Master Secret MAY be used with several Master Salts. the ID Context. Additionally, the ID Context can be generated by the
client (see Appendix B.2). ID Context can be arbitrarily long.
4. Protected Message Fields 4. Protected Message Fields
OSCORE transforms a CoAP message (which may have been generated from OSCORE transforms a CoAP message (which may have been generated from
an HTTP message) into an OSCORE message, and vice versa. OSCORE an HTTP message) into an OSCORE message, and vice versa. OSCORE
protects as much of the original message as possible while still protects as much of the original message as possible while still
allowing certain proxy operations (see Section 10 and Section 11). allowing certain proxy operations (see Sections 10 and 11). This
This section defines how OSCORE protects the message fields and section defines how OSCORE protects the message fields and transfers
transfers them end-to-end between client and server (in any them end-to-end between client and server (in any direction).
direction).
The remainder of this section and later sections focus on the The remainder of this section and later sections focus on the
behavior in terms of CoAP messages. If HTTP is used for a particular behavior in terms of CoAP messages. If HTTP is used for a particular
hop in the end-to-end path, then this section applies to the hop in the end-to-end path, then this section applies to the
conceptual CoAP message that is mappable to/from the original HTTP conceptual CoAP message that is mappable to/from the original HTTP
message as discussed in Section 11. That is, an HTTP message is message as discussed in Section 11. That is, an HTTP message is
conceptually transformed to a CoAP message and then to an OSCORE conceptually transformed to a CoAP message and then to an OSCORE
message, and similarly in the reverse direction. An actual message, and similarly in the reverse direction. An actual
implementation might translate directly from HTTP to OSCORE without implementation might translate directly from HTTP to OSCORE without
the intervening CoAP representation. the intervening CoAP representation.
skipping to change at page 13, line 32 skipping to change at page 14, line 11
Message fields not visible to proxies, i.e., transported in the Message fields not visible to proxies, i.e., transported in the
ciphertext of the COSE object, are called "Inner" (Class E). Message ciphertext of the COSE object, are called "Inner" (Class E). Message
fields transferred in the header or options part of the OSCORE fields transferred in the header or options part of the OSCORE
message, which is visible to proxies, are called "Outer" (Class I or message, which is visible to proxies, are called "Outer" (Class I or
U). There are currently no Class I options defined. U). There are currently no Class I options defined.
An OSCORE message may contain both an Inner and an Outer instance of An OSCORE message may contain both an Inner and an Outer instance of
a certain CoAP message field. Inner message fields are intended for a certain CoAP message field. Inner message fields are intended for
the receiving endpoint, whereas Outer message fields are used to the receiving endpoint, whereas Outer message fields are used to
enable proxy operations. Inner and Outer message fields are enable proxy operations.
processed independently.
4.1. CoAP Options 4.1. CoAP Options
A summary of how options are protected is shown in Figure 5. Note A summary of how options are protected is shown in Figure 5. Note
that some options may have both Inner and Outer message fields which that some options may have both Inner and Outer message fields which
are protected accordingly. Certain options require special are protected accordingly. Certain options require special
processing as is described in Section 4.1.3. processing as is described in Section 4.1.3.
+------+-----------------+---+---+ +------+-----------------+---+---+
| No. | Name | E | U | | No. | Name | E | U |
+------+-----------------+---+---+ +------+-----------------+---+---+
| 1 | If-Match | x | | | 1 | If-Match | x | |
| 3 | Uri-Host | | x | | 3 | Uri-Host | | x |
| 4 | ETag | x | | | 4 | ETag | x | |
| 5 | If-None-Match | x | | | 5 | If-None-Match | x | |
| 6 | Observe | | x | | 6 | Observe | x | x |
| 7 | Uri-Port | | x | | 7 | Uri-Port | | x |
| 8 | Location-Path | x | | | 8 | Location-Path | x | |
| TBD1 | OSCORE | | x | | TBD1 | OSCORE | | x |
| 11 | Uri-Path | x | | | 11 | Uri-Path | x | |
| 12 | Content-Format | x | | | 12 | Content-Format | x | |
| 14 | Max-Age | x | x | | 14 | Max-Age | x | x |
| 15 | Uri-Query | x | | | 15 | Uri-Query | x | |
| 17 | Accept | x | | | 17 | Accept | x | |
| 20 | Location-Query | x | | | 20 | Location-Query | x | |
| 23 | Block2 | x | x | | 23 | Block2 | x | x |
skipping to change at page 14, line 40 skipping to change at page 15, line 9
E = Encrypt and Integrity Protect (Inner) E = Encrypt and Integrity Protect (Inner)
U = Unprotected (Outer) U = Unprotected (Outer)
Figure 5: Protection of CoAP Options Figure 5: Protection of CoAP Options
Options that are unknown or for which OSCORE processing is not Options that are unknown or for which OSCORE processing is not
defined SHALL be processed as class E (and no special processing). defined SHALL be processed as class E (and no special processing).
Specifications of new CoAP options SHOULD define how they are Specifications of new CoAP options SHOULD define how they are
processed with OSCORE. A new COAP option SHOULD be of class E unless processed with OSCORE. A new COAP option SHOULD be of class E unless
it requires proxy processing. it requires proxy processing. If a new CoAP option is of class U,
the potential issues with the option being unprotected SHOULD be
documented (see Appendix D.4).
4.1.1. Inner Options 4.1.1. Inner Options
Inner option message fields (class E) are used to communicate Inner option message fields (class E) are used to communicate
directly with the other endpoint. directly with the other endpoint.
The sending endpoint SHALL write the Inner option message fields The sending endpoint SHALL write the Inner option message fields
present in the original CoAP message into the plaintext of the COSE present in the original CoAP message into the plaintext of the COSE
object (Section 5.3), and then remove the Inner option message fields object (Section 5.3), and then remove the Inner option message fields
from the OSCORE message. from the OSCORE message.
The processing of Inner option message fields by the receiving The processing of Inner option message fields by the receiving
endpoint is specified in Section 8.2 and Section 8.4. endpoint is specified in Sections 8.2 and 8.4.
4.1.2. Outer Options 4.1.2. Outer Options
Outer option message fields (Class U or I) are used to support proxy Outer option message fields (Class U or I) are used to support proxy
operations, see Appendix D.1. operations, see Appendix D.1.
The sending endpoint SHALL include the Outer option message field The sending endpoint SHALL include the Outer option message field
present in the original message in the options part of the OSCORE present in the original message in the options part of the OSCORE
message. All Outer option message fields, including the OSCORE message. All Outer option message fields, including the OSCORE
option, SHALL be encoded as described in Section 3.1 of [RFC7252], option, SHALL be encoded as described in Section 3.1 of [RFC7252],
where the delta is the difference to the previously included instance where the delta is the difference to the previously included instance
of Outer option message field. of Outer option message field.
The processing of Outer options by the receiving endpoint is The processing of Outer options by the receiving endpoint is
specified in Section 8.2 and Section 8.4. specified in Sections 8.2 and 8.4.
A procedure for integrity-protection-only of Class I option message A procedure for integrity-protection-only of Class I option message
fields is specified in Section 5.4. Proxies MUST NOT change the fields is specified in Section 5.4. Specifications that introduce
order of option's occurrences, for options repeatable and of class I. repeatable Class I options MUST specify that proxies MUST NOT change
the order of the instances of such an option in the CoAP message.
Note: There are currently no Class I option message fields defined. Note: There are currently no Class I option message fields defined.
4.1.3. Special Options 4.1.3. Special Options
Some options require special processing as specified in this section. Some options require special processing as specified in this section.
4.1.3.1. Max-Age 4.1.3.1. Max-Age
An Inner Max-Age message field is used to indicate the maximum time a An Inner Max-Age message field is used to indicate the maximum time a
response may be cached by the client (as defined in [RFC7252]), end- response may be cached by the client (as defined in [RFC7252]), end-
to-end from the server to the client, taking into account that the to-end from the server to the client, taking into account that the
option is not accessible to proxies. The Inner Max-Age SHALL be option is not accessible to proxies. The Inner Max-Age SHALL be
processed by OSCORE as a normal Inner option, specified in processed by OSCORE as a normal Inner option, specified in
Section 4.1.1. Section 4.1.1.
An Outer Max-Age message field is used to avoid unnecessary caching An Outer Max-Age message field is used to avoid unnecessary caching
of OSCORE error responses at OSCORE unaware intermediary nodes. A of OSCORE error responses at OSCORE-unaware intermediary nodes. A
server MAY set a Class U Max-Age message field with value zero to server MAY set a Class U Max-Age message field with value zero to
OSCORE error responses, which are described in Section 7.4, OSCORE error responses, which are described in Sections 7.4, 8.2, and
Section 8.2 and Section 8.4. Such message field is then processed 8.4. Such a message field is then processed according to
according to Section 4.1.2. Section 4.1.2.
Successful OSCORE responses do not need to include an Outer Max-Age Successful OSCORE responses do not need to include an Outer Max-Age
option since the responses are non-cacheable by construction (see option since the responses are non-cacheable by construction (see
Section 4.2). Section 4.2).
4.1.3.2. Proxy-Uri 4.1.3.2. Uri-Host and Uri-Port
Proxy-Uri, when present, is split by OSCORE into class U options and When the Uri-Host and Uri-Port are set to their default values (see
class E options, which are processed accordingly. When Proxy-Uri is Section 5.10.1 [RFC7252]), they are omitted from the message
used in the original CoAP message, Uri-* are not present [RFC7252]. (Section 5.4.4 of [RFC7252]), which is favorable both for overhead
and privacy.
The sending endpoint SHALL first decompose the Proxy-Uri value of the In order to support forward proxy operations, Proxy-Scheme, Uri-Host,
original CoAP message into the Proxy-Scheme, Uri-Host, Uri-Port, Uri- and Uri-Port need to be Class U. For the use of Proxy-Uri, see
Path, and Uri-Query options (if present) according to Section 6.4 of Section 4.1.3.3.
[RFC7252].
Manipulation of unprotected message fields (including Uri-Host, Uri-
Port, destination IP/port or request scheme) MUST NOT lead to an
OSCORE message becoming verified by an unintended server. Different
servers SHOULD have different security contexts.
4.1.3.3. Proxy-Uri
When Proxy-Uri is present, the client SHALL first decompose the
Proxy-Uri value of the original CoAP message into the Proxy-Scheme,
Uri-Host, Uri-Port, Uri-Path, and Uri-Query options according to
Section 6.4 of [RFC7252].
Uri-Path and Uri-Query are class E options and SHALL be protected and Uri-Path and Uri-Query are class E options and SHALL be protected and
processed as Inner options (Section 4.1.1). Uri-Host being an Outer processed as Inner options (Section 4.1.1).
option SHOULD NOT contain privacy sensitive information.
The Proxy-Uri option of the OSCORE message SHALL be set to the The Proxy-Uri option of the OSCORE message SHALL be set to the
composition of Proxy-Scheme, Uri-Host, and Uri-Port options (if composition of Proxy-Scheme, Uri-Host, and Uri-Port options as
present) as specified in Section 6.5 of [RFC7252], and processed as specified in Section 6.5 of [RFC7252], and processed as an Outer
an Outer option of Class U (Section 4.1.2). option of Class U (Section 4.1.2).
Note that replacing the Proxy-Uri value with the Proxy-Scheme and Note that replacing the Proxy-Uri value with the Proxy-Scheme and
Uri-* options works by design for all CoAP URIs (see Section 6 of Uri-* options works by design for all CoAP URIs (see Section 6 of
[RFC7252]). OSCORE-aware HTTP servers should not use the userinfo [RFC7252]). OSCORE-aware HTTP servers should not use the userinfo
component of the HTTP URI (as defined in Section 3.2.1 of [RFC3986]), component of the HTTP URI (as defined in Section 3.2.1 of [RFC3986]),
so that this type of replacement is possible in the presence of CoAP- so that this type of replacement is possible in the presence of CoAP-
to-HTTP proxies. In future documents specifying cross-protocol to-HTTP proxies (see Section 11.2). In future specifications of
proxying behavior using different URI structures, it is expected that cross-protocol proxying behavior using different URI structures, it
the authors will create Uri-* options that allow decomposing the is expected that the authors will create Uri-* options that allow
Proxy-Uri, and specify in which OSCORE class they belong. decomposing the Proxy-Uri, and specifying the OSCORE processing.
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 17, line 4 skipping to change at page 17, line 33
o Proxy-Scheme = "coap" o Proxy-Scheme = "coap"
o Uri-Host = "example.com" o Uri-Host = "example.com"
o Uri-Port = "5683" o Uri-Port = "5683"
o Uri-Path = "resource" o Uri-Path = "resource"
o Uri-Query = "q=1" o Uri-Query = "q=1"
Uri-Path and Uri-Query follow the processing defined in Uri-Path and Uri-Query follow the processing defined in
Section 4.1.1, and are thus encrypted and transported in the COSE Section 4.1.1, and are thus encrypted and transported in the COSE
object. The remaining options are composed into the Proxy-Uri object:
included in the options part of the OSCORE message, which has value:
o Uri-Path = "resource"
o Uri-Query = "q=1"
The remaining options are composed into the Proxy-Uri included in the
options part of the OSCORE message, which has value:
o Proxy-Uri = "coap://example.com" o Proxy-Uri = "coap://example.com"
See Sections 6.1 and 12.6 of [RFC7252] for more information. See Sections 6.1 and 12.6 of [RFC7252] for more details.
4.1.3.3. The Block Options 4.1.3.4. The Block Options
Block-wise [RFC7959] is an optional feature. An implementation MAY Block-wise [RFC7959] is an optional feature. An implementation MAY
support [RFC7252] and the OSCORE option without supporting block-wise support [RFC7252] and the OSCORE option without supporting block-wise
transfers. The Block options (Block1, Block2, Size1, Size2), when transfers. The Block options (Block1, Block2, Size1, Size2), when
Inner message fields, provide secure message segmentation such that Inner message fields, provide secure message segmentation such that
each segment can be verified. The Block options, when Outer message each segment can be verified. The Block options, when Outer message
fields, enables hop-by-hop fragmentation of the OSCORE message. fields, enables hop-by-hop fragmentation of the OSCORE message.
Inner and Outer block processing may have different performance Inner and Outer block processing may have different performance
properties depending on the underlying transport. The end-to-end properties depending on the underlying transport. The end-to-end
integrity of the message can be verified both in case of Inner and integrity of the message can be verified both in case of Inner and
Outer Block-wise transfers provided all blocks are received. Outer Block-wise transfers provided all blocks are received.
4.1.3.3.1. Inner Block Options 4.1.3.4.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 normal Inner the Block options SHALL be processed by OSCORE as normal Inner
options (Section 4.1.1). The receiving CoAP endpoint SHALL process options (Section 4.1.1). The receiving CoAP endpoint SHALL process
the OSCORE message before processing Block-wise as defined in the OSCORE message before processing Block-wise as defined in
[RFC7959]. [RFC7959].
4.1.3.3.2. Outer Block Options 4.1.3.4.2. Outer Block Options
Proxies MAY fragment an OSCORE message using [RFC7959], by Proxies MAY fragment an OSCORE message using [RFC7959], by
introducing Block option message fields that are Outer introducing Block option message fields that are Outer
(Section 4.1.2). Note that the Outer Block options are neither (Section 4.1.2). Note that the Outer Block options are neither
encrypted nor integrity protected. As a consequence, a proxy can encrypted nor integrity protected. As a consequence, a proxy can
maliciously inject block fragments indefinitely, since the receiving maliciously inject block fragments indefinitely, since the receiving
endpoint needs to receive the last block (see [RFC7959]) to be able endpoint needs to receive the last block (see [RFC7959]) to be able
to compose the OSCORE message and verify its integrity. Therefore, to compose the OSCORE message and verify its integrity. Therefore,
applications supporting OSCORE and [RFC7959] MUST specify a security applications supporting OSCORE and [RFC7959] MUST specify a security
policy defining a maximum unfragmented message size policy defining a maximum unfragmented message size
(MAX_UNFRAGMENTED_SIZE) considering the maximum size of message which (MAX_UNFRAGMENTED_SIZE) considering the maximum size of message which
can be handled by the endpoints. Messages exceeding this size SHOULD can be handled by the endpoints. Messages exceeding this size SHOULD
be fragmented by the sending endpoint using Inner Block options be fragmented by the sending endpoint using Inner Block options
(Section 4.1.3.3.1). (Section 4.1.3.4.1).
An endpoint receiving an OSCORE message with an Outer Block option An endpoint receiving an OSCORE message with an Outer Block option
SHALL first process this option according to [RFC7959], until all SHALL first process this option according to [RFC7959], until all
blocks of the OSCORE message have been received, or the cumulated blocks of the OSCORE message have been received, or the cumulated
message size of the blocks exceeds MAX_UNFRAGMENTED_SIZE. In the message size of the blocks exceeds MAX_UNFRAGMENTED_SIZE. In the
former case, the processing of the OSCORE message continues as former case, the processing of the OSCORE message continues as
defined in this document. In the latter case the message SHALL be defined in this document. In the latter case the message SHALL be
discarded. discarded.
Because of encryption of Uri-Path and Uri-Query, messages to the same Because of encryption of Uri-Path and Uri-Query, messages to the same
server may, from the point of view of a proxy, look like they also server may, from the point of view of a proxy, look like they also
target the same resource. A proxy SHOULD mitigate a potential mix-up target the same resource. A proxy SHOULD mitigate a potential mix-up
of blocks from concurrent requests to the same server, for example of blocks from concurrent requests to the same server, for example
using the Request-Tag processing specified in Section 3.3.2 of using the Request-Tag processing specified in Section 3.3.2 of
[I-D.ietf-core-echo-request-tag]. [I-D.ietf-core-echo-request-tag].
4.1.3.4. Observe 4.1.3.5. Observe
Observe [RFC7641] is an optional feature. An implementation MAY Observe [RFC7641] is an optional feature. An implementation MAY
support [RFC7252] and the OSCORE option without supporting [RFC7641]. support [RFC7252] and the OSCORE option without supporting [RFC7641],
The Observe option as used here targets the requirements on in which case the Observe related processing can be omitted.
forwarding of [I-D.hartke-core-e2e-security-reqs] (Section 2.2.1).
An Observe intermediary MUST forward the OSCORE option unchanged. In The support for Observe [RFC7641] with OSCORE targets the
order for an OSCORE-unaware proxy to support forwarding of Observe requirements on forwarding of Section 2.2.1 of
messages [RFC7641], there SHALL be an Outer Observe option, i.e., [I-D.hartke-core-e2e-security-reqs], i.e. that observations go
present in the options part of the OSCORE message. With OSCORE, through intermediary nodes, as illustrated in Figure 8 of [RFC7641].
Observe intermediaries are forwarding messages without being able to
re-send cached notifications to other clients.
In order to support multiple concurrent Observe registrations in the Inner Observe SHALL be used to protect the value of the Observe
same endpoint, Observe intermediaries are allowed to deviate from option between the endpoints. Outer Observe SHALL be used to support
[RFC7641] and register multiple times to the same (root) resource, forwarding by intermediary nodes.
since the actual target resource is encrypted and not visible in the
OSCORE message. The processing of the CoAP Code for Observe messages
is described in Section 4.2.
The Observe option in the CoAP request may be legitimately removed by The server SHALL include a new Partial IV in responses (with or
a proxy or ignored by the server. In these cases, the server without the Observe option) to Observe registrations.
processes the request as a non-Observe request and produce a non-
Observe response. If the OSCORE client receives a response to an
Observe request without an Outer Observe value, then it verifies the
response as a non-Observe response, as specified in Section 8.4. If
the OSCORE client receives a response to a non-Observe request with
an Outer Observe value, it stops processing the message, as specified
in Section 8.4.
It the server accepts the Observe registration, a Partial IV must be [RFC7252] does not specify how the server should act upon receiving
included in all notifications (both successful and error). To secure the same Token in different requests. When using OSCORE, the server
the order of notifications, the client SHALL maintain a Notification SHOULD NOT remove an active observation just because it receives a
request with the same Token.
Since POST with Observe is not defined, for messages with Observe,
the Outer Code MUST be set to 0.05 (FETCH) for requests and to 2.05
(Content) for responses (see Section 4.2).
4.1.3.5.1. Registrations and Cancellations
The Inner and Outer Observe in the request MUST contain the Observe
value of the original CoAP request; 0 (registration) or 1
(cancellation).
Every time a client issues a new Observe request, a new Partial IV
MUST be used (see Section 5), and so the payload and OSCORE option
are changed. The server uses the Partial IV of the new request as
the 'request_piv' of all associated notifications (see Section 5.4).
The Partial IV of the registration is also used as 'request_piv' of
associated cancellations (see Section 5.4).
Intermediaries are not assumed to have access to the OSCORE security
context used by the endpoints, and thus cannot make requests or
transform responses with the OSCORE option which verify at the
receiving endpoint as coming from the other endpoint. This has the
following consequences and limitations for Observe operations.
o An intermediary node removing the Outer Observe 0 does not change
the registration request to a request without Observe (see
Section 2 of [RFC7641]). Instead other means for cancellation may
be used as described in Section 3.6 of [RFC7641].
o An intermediary node is not able to transform a normal response
into an OSCORE protected Observe notification (see figure 7 of
[RFC7641]) which verifies as coming from the server.
o An intermediary node is not able to initiate an OSCORE protected
Observe registration (Observe with value 0) which verifies as
coming from the client. An OSCORE-aware intermediary SHALL NOT
initiate registrations of observations (see Section 10). If an
OSCORE-unaware proxy re-sends an old registration message from a
client this will trigger the replay protection mechanism in the
server. To prevent this from resulting in the OSCORE-unaware
proxy to cancel of the registration, a server MAY respond to a
replayed registration request with a replay of a cached
notification. Alternatively, the server MAY send a new
notification.
o An intermediary node is not able to initiate an OSCORE protected
Observe cancellation (Observe with value 1) which verifies as
coming from the client. An application MAY decide to allow
intermediaries to cancel Observe registrations, e.g. to send
Observe with value 1 (see Section 3.6 of [RFC7641]), but that can
also be done with other methods, e.g. reusing the Token in a
different request or sending a RST message. This is out of scope
for this specification.
4.1.3.5.2. Notifications
If the server accepts an Observe registration, a Partial IV MUST be
included in all notifications (both successful and error). To
protect against replay, the client SHALL maintain a Notification
Number for each Observation it registers. The Notification Number is Number for each Observation it registers. The Notification Number is
a non-negative integer containing the largest Partial IV of the a non-negative integer containing the largest Partial IV of the
received notifications for the associated Observe registration (see received notifications for the associated Observe registration.
Section 7.4). The Notification Number is initialized to the Partial Further details of replay protection of notifications are specified
IV of the first successfully received notification response to the in Section 7.4.1.
registration request. In contrast to [RFC7641], the received Partial
IV MUST always be compared with the Notification Number, which thus
MUST NOT be forgotten after 128 seconds. Further details of replay
protection of notifications are specified in Section 7.4. The client
MAY ignore the Observe option value.
Clients can re-register observations to ensure that the observation For notifications, the Inner Observe value MUST be empty (see
is still active and establish freshness again ([RFC7641] Section 3.2 of [RFC7252]). The Outer Observe in a notification is
Section 3.3.1). When an OSCORE observation is refreshed, not only needed for intermediary nodes to allow multiple responses to one
the ETags, but also the partial IV (and thus the payload and OSCORE request, and may be set to the value of Observe in the original CoAP
option) change. The server uses the new request's Partial IV as the message. The client performs ordering of notifications and replay
'request_piv' of new responses. protection by comparing their Partial IVs and SHALL ignore the outer
Observe value.
4.1.3.5. No-Response If the client receives a response to an Observe request without an
Inner Observe option, then it verifies the response as a non-Observe
response, as specified in Section 8.4. If the client receives a
response to a non-Observe request with an Inner Observe option, then
it stops processing the message, as specified in Section 8.4.
No-Response [RFC7967] is an optional feature. Clients using No- A client MUST consider the notification with the highest Partial IV
Response MUST set both an Inner (Class E) and an Outer (Class U) No- as the freshest, regardless of the order of arrival. In order to
Response option, with the same value. support existing Observe implementations the OSCORE client
implementation MAY set the Observe value to the three least
significant bytes of the Partial IV.
The Inner No-Response option is used to communicate to the server the 4.1.3.6. No-Response
client's disinterest in certain classes of responses to a particular
request. The Inner No-Response SHALL be processed by OSCORE as
specified in Section 4.1.1.
The Outer No-Response option is used to support proxy functionality, No-Response [RFC7967] is an optional feature used by the client to
specifically to avoid error transmissions from proxies to clients, communicate its disinterest in certain classes of responses to a
and to avoid bandwidth reduction to servers by proxies applying particular request. An implementation MAY support [RFC7252] and the
congestion control when not receiving responses. The Outer No- OSCORE option without supporting [RFC7967].
Response option is processed according to Section 4.1.2.
Note the effect in step 8 of Section 8.4 when applied to No-Response. If used, No-Response MUST be Inner. The Inner No-Response SHALL be
Applications should consider that a proxy may remove the Outer No- processed by OSCORE as specified in Section 4.1.1. The Outer option
Response option from the request. Applications using No-Response can SHOULD NOT be present. The server SHALL ignore the Outer No-Response
specify policies to deal with cases where servers receive an Inner option. The client MAY set the Outer No-Response value to 26
No-Response option only, which may be the result of the request ('suppress all known codes') if the Inner value is set to 26. The
having traversed a No-Response unaware proxy, and update the client MUST be prepared to receive and discard 5.04 Gateway Timeout
processing in Section 8.4 accordingly. This avoids unnecessary error error messages from intermediaries potentially resulting from
responses to clients and bandwidth reductions to servers, due to No- destination time out due to no response.
Response unaware proxies.
4.1.3.6. OSCORE 4.1.3.7. OSCORE
The OSCORE option is only defined to be present in OSCORE messages, The OSCORE option is only defined to be present in OSCORE messages,
as an indication that OSCORE processing have been performed. The as an indication that OSCORE processing have been performed. The
content in the OSCORE option is neither encrypted nor integrity content in the OSCORE option is neither encrypted nor integrity
protected as a whole but some part of the content of this option is protected as a whole but some part of the content of this option is
protected (see Section 5.4). Nested use of OSCORE is not supported: protected (see Section 5.4). Nested use of OSCORE is not supported:
If OSCORE processing detects an OSCORE option in the original CoAP If OSCORE processing detects an OSCORE option in the original CoAP
message, then processing SHALL be stopped. message, then processing SHALL be stopped.
4.2. CoAP Header Fields and Payload 4.2. CoAP Header Fields and Payload
skipping to change at page 21, line 4 skipping to change at page 22, line 37
layer only, and not the Messaging Layer (Section 2 of [RFC7252]), so layer only, and not the Messaging Layer (Section 2 of [RFC7252]), so
fields such as Type and Message ID are not protected with OSCORE. fields such as Type and Message ID are not protected with OSCORE.
The CoAP Header field Code is protected by OSCORE. Code SHALL be The CoAP Header field Code is protected by OSCORE. Code SHALL be
encrypted and integrity protected (Class E) to prevent an encrypted and integrity protected (Class E) to prevent an
intermediary from eavesdropping on or manipulating the Code (e.g., intermediary from eavesdropping on or manipulating the Code (e.g.,
changing from GET to DELETE). changing from GET to DELETE).
The sending endpoint SHALL write the Code of the original CoAP The sending endpoint SHALL write the Code of the original CoAP
message into the plaintext of the COSE object (see Section 5.3). message into the plaintext of the COSE object (see Section 5.3).
After that, the sending endpoint writes an Outer Code to the OSCORE After that, the sending endpoint writes an Outer Code to the OSCORE
message. The Outer Code SHALL be set to 0.02 (POST) or 0.05 (FETCH) message. With one exception (see Section 4.1.3.5) the Outer Code
for requests. For non-Observe requests the client SHALL set the SHALL be set to 0.02 (POST) for requests and to 2.04 (Changed) for
Outer Code to 0.02 (POST). For responses, the sending endpoint SHALL responses. The receiving endpoint SHALL discard the Outer Code in
respond with Outer Code 2.04 (Changed) to 0.02 (POST) requests, and the OSCORE message and write the Code of the COSE object plaintext
with Outer Code 2.05 (Content) to 0.05 (FETCH) requests. Using FETCH (Section 5.3) into the decrypted CoAP message.
with Observe allows OSCORE to be compliant with the Observe
processing in OSCORE-unaware intermediaries. The choice of POST and
FETCH [RFC8132] allows all OSCORE messages to have payload.
The receiving endpoint SHALL discard the Outer Code in the OSCORE
message and write the Code of the COSE object plaintext (Section 5.3)
into the decrypted CoAP message.
The other currently defined CoAP Header fields are Unprotected (Class The other currently defined CoAP Header fields are Unprotected (Class
U). The sending endpoint SHALL write all other header fields of the U). The sending endpoint SHALL write all other header fields of the
original message into the header of the OSCORE message. The original message into the header of the OSCORE message. The
receiving endpoint SHALL write the header fields from the received receiving endpoint SHALL write the header fields from the received
OSCORE message into the header of the decrypted CoAP message. OSCORE message into the header of the decrypted CoAP message.
The CoAP Payload, if present in the original CoAP message, SHALL be The CoAP Payload, if present in the original CoAP message, SHALL be
encrypted and integrity protected and is thus an Inner message field. encrypted and integrity protected and is thus an Inner message field.
The sending endpoint writes the payload of the original CoAP message The sending endpoint writes the payload of the original CoAP message
skipping to change at page 22, line 44 skipping to change at page 24, line 19
(AAD) denotes the data that is to be integrity protected only. (AAD) denotes the data that is to be integrity protected only.
The COSE Object SHALL be a COSE_Encrypt0 object with fields defined The COSE Object SHALL be a COSE_Encrypt0 object with fields defined
as follows as follows
o The 'protected' field is empty. o The 'protected' field is empty.
o The 'unprotected' field includes: o The 'unprotected' field includes:
* The 'Partial IV' parameter. The value is set to the Sender * The 'Partial IV' parameter. The value is set to the Sender
Sequence Number. All leading zeroes SHALL be removed when Sequence Number. All leading bytes of value zero SHALL be
encoding the Partial IV, except in the case of value 0 which is removed when encoding the Partial IV, except in the case of
encoded to the byte string 0x00. This parameter SHALL be Partial IV of value 0 which is encoded to the byte string 0x00.
present in requests. In case of Observe notifications This parameter SHALL be present in requests. The Partial IV
(Section 4.1.3.4) the Partial IV SHALL be present in responses, SHALL be present in responses to Observe registrations (see
and otherwise the Partial IV will not typically be present in Section 4.1.3.5.1), otherwise the Partial IV will not typically
responses. be present in responses.
* The 'kid' parameter. The value is set to the Sender ID. This * The 'kid' parameter. The value is set to the Sender ID. This
parameter SHALL be present in requests and will not typically parameter SHALL be present in requests and will not typically
be present in responses. An example where the Sender ID is be present in responses. An example where the Sender ID is
included in a response is the extension of OSCORE to group included in a response is the extension of OSCORE to group
communication [I-D.ietf-core-oscore-groupcomm]. communication [I-D.ietf-core-oscore-groupcomm].
* Optionally, a 'kid context' parameter as defined in * Optionally, a 'kid context' parameter (see Section 5.1)
Section 5.1. This parameter MAY be present in requests and containing an ID Context (see Section 3.1). This parameter MAY
SHALL NOT be present in responses. be present in requests and MUST NOT be present in responses.
If 'kid context' is present in the request, then the server
SHALL use a security context with that ID Context when
verifying the request.
o The 'ciphertext' field is computed from the secret key (Sender Key o The 'ciphertext' field is computed from the secret key (Sender Key
or Recipient Key), AEAD nonce (see Section 5.2), plaintext (see or Recipient Key), AEAD nonce (see Section 5.2), plaintext (see
Section 5.3), and the Additional Authenticated Data (AAD) (see Section 5.3), and the Additional Authenticated Data (AAD) (see
Section 5.4) following Section 5.2 of [RFC8152]. Section 5.4) following Section 5.2 of [RFC8152].
The encryption process is described in Section 5.3 of [RFC8152]. The encryption process is described in Section 5.3 of [RFC8152].
5.1. Kid Context 5.1. Kid Context
For certain use cases, e.g. deployments where the same kid is used For certain use cases, e.g. deployments where the same Sender ID is
with multiple contexts, it is necessary or favorable for the sender used with multiple contexts, it is possible (and sometimes necessary,
to provide an additional identifier of the security material to use, see Section 3.3) for the client to use an ID Context to distinguish
in order for the receiver to retrieve or establish the correct key. the security contexts (see Section 3.1). For example:
The kid context parameter is used to provide such additional input.
The kid context and kid are used to determine the security context,
or to establish the necessary input parameters to derive the security
context (see Section 3.2). The application defines how this is done.
The kid context is implicitly integrity protected, as a manipulation
that leads to the wrong key (or no key) being retrieved results in an
error, as described in Section 8.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 a unique identifier in some namespace, then that
identifier can be used as ID Context.
o If the client has an identifier in some other namespace which can o In case of group communication [I-D.ietf-core-oscore-groupcomm], a
be used by the server to retrieve or establish the security group identifier can be used as ID Context to enable different
context, then that identifier can be used as kid context. The kid security contexts for a server belonging to multiple groups.
context may be used as Master Salt (Section 3.1) for additional
entropy of the security contexts (see for example Appendix B.2 or
[I-D.ietf-6tisch-minimal-security]).
o In case of a group communication scenario The Sender ID and Context ID are used to establish the necessary
[I-D.ietf-core-oscore-groupcomm], if the server belongs to input parameters and in the derivation of the security context (see
multiple groups, then a group identifier can be used as kid Section 3.2). Whereas the 'kid' parameter is used to transport the
context to enable the server to find the right security context. Sender ID, the new COSE header parameter 'kid context' is used to
transport the ID Context, see Figure 7.
+----------+--------+------------+----------------+-----------------+ +----------+--------+------------+----------------+-----------------+
| name | label | value type | value registry | description | | name | label | value type | value registry | description |
+----------+--------+------------+----------------+-----------------+ +----------+--------+------------+----------------+-----------------+
| kid | TBD2 | bstr | | Identifies the | | kid | TBD2 | bstr | | Identifies the |
| context | | | | kid context | | context | | | | context for kid |
+----------+--------+------------+----------------+-----------------+ +----------+--------+------------+----------------+-----------------+
Figure 7: Additional common header parameter for the COSE object Figure 7: Common Header Parameter kid context for the COSE object
5.2. Nonce 5.2. Nonce
The AEAD nonce is constructed in the following way (see Figure 8): The AEAD nonce is constructed in the following way (see Figure 8):
1. left-padding the Partial IV (PIV) in network byte order with 1. left-padding the Partial IV (PIV) in network byte order with
zeroes to exactly 5 bytes, zeroes to exactly 5 bytes,
2. left-padding the Sender ID of the endpoint that generated the 2. left-padding the Sender ID of the endpoint that generated the
Partial IV (ID_PIV) in network byte order with zeroes to exactly Partial IV (ID_PIV) in network byte order with zeroes to exactly
skipping to change at page 24, line 41 skipping to change at page 26, line 10
or greater than 7 bytes are supported. The nonce construction with or greater than 7 bytes are supported. The nonce construction with
S, ID_PIV, and PIV together with endpoint unique IDs and encryption S, ID_PIV, and PIV together with endpoint unique IDs and encryption
keys makes it easy to verify that the nonces used with a specific key keys makes it easy to verify that the nonces used with a specific key
will be unique, see Appendix D.3. will be unique, see Appendix D.3.
If the Partial IV is not present in a response, the nonce from the If the Partial IV is not present in a response, the nonce from the
request is used. For responses that are not notifications (i.e. when request is used. For responses that are not notifications (i.e. when
there is a single response to a request), the request and the there is a single response to a request), the request and the
response should typically use the same nonce to reduce message response should typically use the same nonce to reduce message
overhead. Both alternatives provide all the required security overhead. Both alternatives provide all the required security
properties, see Appendix D.3 and Section 7.4. The only non-Observe properties, see Section 7.4 and Appendix D.3. The only non-Observe
scenario where a Partial IV must be included in a response is when scenario where a Partial IV must be included in a response is when
the server is unable to perform replay protection, see Section 7.5.2. the server is unable to perform replay protection, see Section 7.5.2.
For processing instructions see Section 8. For processing instructions see Section 8.
<- nonce length minus 6 B -> <-- 5 bytes --> <- nonce length minus 6 B -> <-- 5 bytes -->
+---+-------------------+--------+---------+-----+ +---+-------------------+--------+---------+-----+
| S | padding | ID_PIV | padding | PIV |----+ | S | padding | ID_PIV | padding | PIV |----+
+---+-------------------+--------+---------+-----+ | +---+-------------------+--------+---------+-----+ |
| |
<---------------- nonce length ----------------> | <---------------- nonce length ----------------> |
skipping to change at page 26, line 33 skipping to change at page 27, line 48
o algorithms: contains (for extensibility) an array of algorithms, o algorithms: contains (for extensibility) an array of algorithms,
according to this specification only containing alg_aead. according to this specification only containing alg_aead.
o alg_aead: contains the AEAD Algorithm from the security context o alg_aead: contains the AEAD Algorithm from the security context
used for the exchange (see Section 3.1). used for the exchange (see Section 3.1).
o request_kid: contains the value of the 'kid' in the COSE object of o request_kid: contains the value of the 'kid' in the COSE object of
the request (see Section 5). the request (see Section 5).
o request_piv: contains the value of the 'Partial IV' in the COSE o request_piv: contains the value of the 'Partial IV' in the COSE
object of the request (see Section 5). object of the request (see Section 5), with one exception: in case
of protection or verification of Observe cancellations, the
request_piv contains the value of the 'Partial IV' in the COSE
object of the corresponding registration (see Section 4.1.3.5.1).
o options: contains the Class I options (see Section 4.1.2) present o options: contains the Class I options (see Section 4.1.2) present
in the original CoAP message encoded as described in Section 3.1 in the original CoAP message encoded as described in Section 3.1
of [RFC7252], where the delta is the difference to the previously of [RFC7252], where the delta is the difference to the previously
included instance of class I option. included instance of class I option.
The oscore_version and algorithms parameters are established out-of- The oscore_version and algorithms parameters are established out-of-
band and are thus never transported in OSCORE, but the external_aad band and are thus never transported in OSCORE, but the external_aad
allows to verify that they are the same in both endpoints. allows to verify that they are the same in both endpoints.
NOTE: The format of the external_aad is for simplicity the same for NOTE: The format of the external_aad is for simplicity the same for
requests and responses, although some parameters, e.g. request_kid, requests and responses, although some parameters, e.g. request_kid,
need not be integrity protected in the requests. need not be integrity protected in all requests.
The Additional Authenticated Data (AAD) is composed from the
external_add as described in Section 5.3 of [RFC8152].
6. OSCORE Header Compression 6. OSCORE Header Compression
The Concise Binary Object Representation (CBOR) [RFC7049] combines The Concise Binary Object Representation (CBOR) [RFC7049] combines
very small message sizes with extensibility. The CBOR Object Signing very small message sizes with extensibility. The CBOR Object Signing
and Encryption (COSE) [RFC8152] uses CBOR to create compact encoding and Encryption (COSE) [RFC8152] uses CBOR to create compact encoding
of signed and encrypted data. COSE is however constructed to support of signed and encrypted data. COSE is however constructed to support
a large number of different stateless use cases, and is not fully a large number of different stateless use cases, and is not fully
optimized for use as a stateful security protocol, leading to a optimized for use as a stateful security protocol, leading to a
larger than necessary message expansion. In this section, we define larger than necessary message expansion. In this section, we define
a stateless header compression mechanism, simply removing redundant a stateless header compression mechanism, simply removing redundant
information from the COSE objects, which significantly reduces the information from the COSE objects, which significantly reduces the
per-packet overhead. The result of applying this mechanism to a COSE per-packet overhead. The result of applying this mechanism to a COSE
object is called the "compressed COSE object". object is called the "compressed COSE object".
The COSE_Encrypt0 object used in OSCORE is transported in the OSCORE The COSE_Encrypt0 object used in OSCORE is transported in the OSCORE
option and in the Payload. The Payload contains the Ciphertext and option and in the Payload. The Payload contains the Ciphertext of
the headers of the COSE object are compactly encoded as described in the COSE object. The headers of the COSE object are compactly
the next section. encoded as described in the next section.
6.1. Encoding of the OSCORE Option Value 6.1. Encoding of the OSCORE Option Value
The value of the OSCORE option SHALL contain the OSCORE flag bits, The value of the OSCORE option SHALL contain the OSCORE flag bits,
the Partial IV parameter, the kid context parameter (length and the Partial IV parameter, the kid context parameter (length and
value), and the kid parameter as follows: value), and the kid parameter as follows:
0 1 2 3 4 5 6 7 <--------- n bytes -------------> 0 1 2 3 4 5 6 7 <------------- n bytes -------------->
+-+-+-+-+-+-+-+-+--------------------------------- +-+-+-+-+-+-+-+-+--------------------------------------
|0 0 0|h|k| n | Partial IV (if any) ... |0 0 0|h|k| n | Partial IV (if any) ...
+-+-+-+-+-+-+-+-+--------------------------------- +-+-+-+-+-+-+-+-+--------------------------------------
<- 1 byte -> <------ s bytes -----> <- 1 byte -> <----- s bytes ------>
+------------+----------------------+------------------+ +------------+----------------------+------------------+
| s (if any) | kid context (if any) | kid (if any) ... | | s (if any) | kid context (if any) | kid (if any) ... |
+------------+----------------------+------------------+ +------------+----------------------+------------------+
Figure 10: The OSCORE Option Value Figure 10: The OSCORE Option Value
o The first byte of flag bits encodes the following set of flags and o The first byte of flag bits encodes the following set of flags and
the length of the Partial IV parameter: the length of the Partial IV parameter:
* The three least significant bits encode the Partial IV length * The three least significant bits encode the Partial IV length
skipping to change at page 31, line 24 skipping to change at page 33, line 5
of the request until all responses have been sent. of the request until all responses have been sent.
7.2. Sequence Numbers 7.2. Sequence Numbers
An AEAD nonce MUST NOT be used more than once per AEAD key. The An AEAD nonce MUST NOT be used more than once per AEAD key. The
uniqueness of (key, nonce) pairs is shown in Appendix D.3, and in uniqueness of (key, nonce) pairs is shown in Appendix D.3, and in
particular depends on a correct usage of Partial IVs. If messages particular depends on a correct usage of Partial IVs. If messages
are processed concurrently, the operation of reading and increasing are processed concurrently, the operation of reading and increasing
the Sender Sequence Number MUST be atomic. the Sender Sequence Number MUST be atomic.
7.2.1. Maximum Sequence Number
The maximum Sender Sequence Number is algorithm dependent (see The maximum Sender Sequence Number is algorithm dependent (see
Section 12), and SHALL be less than 2^40. If the Sender Sequence Section 12), and SHALL be less than 2^40. If the Sender Sequence
Number exceeds the maximum, the endpoint MUST NOT process any more Number exceeds the maximum, the endpoint MUST NOT process any more
messages with the given Sender Context. If necessary, the endpoint messages with the given Sender Context. If necessary, the endpoint
SHOULD acquire a new security context before this happens. The SHOULD acquire a new security context before this happens. The
latter is out of scope of this document. latter is out of scope of this document.
7.3. Freshness 7.3. Freshness
For requests, OSCORE provides only the guarantee that the request is For requests, OSCORE provides only the guarantee that the request is
not older than the security context. For applications having not older than the security context. For applications having
stronger demands on request freshness (e.g., control of actuators), stronger demands on request freshness (e.g., control of actuators),
OSCORE needs to be augmented with mechanisms providing freshness, for OSCORE needs to be augmented with mechanisms providing freshness, for
example as specified in [I-D.ietf-core-echo-request-tag]. example as specified in [I-D.ietf-core-echo-request-tag].
Assuming an honest server, the message binding guarantees that a Assuming an honest server (see Appendix D), the message binding
response is not older than its request. For responses that are not guarantees that a response is not older than its request. For
notifications (i.e. when there is a single response to a request), responses that are not notifications (i.e. when there is a single
this gives absolute freshness. For notifications, the absolute response to a request), this gives absolute freshness. For
freshness gets weaker with time, and it is RECOMMENDED that the notifications, the absolute freshness gets weaker with time, and it
client regularly re-register the observation. Note that the message is RECOMMENDED that the client regularly re-register the observation.
binding does not guarantee that misbehaving server created the Note that the message binding does not guarantee that misbehaving
response before receiving the request, i.e. it does not verify server server created the response before receiving the request, i.e. it
aliveness. does not verify server aliveness.
For requests and notifications, OSCORE also provides relative For requests and notifications, OSCORE also provides relative
freshness in the sense that the received Partial IV allows a freshness in the sense that the received Partial IV allows a
recipient to determine the relative order of requests or responses. recipient to determine the relative order of requests or responses.
7.4. Replay Protection 7.4. Replay Protection
In order to protect from replay of requests, the server's Recipient In order to protect from replay of requests, the server's Recipient
Context includes a Replay Window. A server SHALL verify that a Context includes a Replay Window. A server SHALL verify that a
Partial IV received in the COSE object has not been received before. Partial IV received in the COSE object has not been received before.
If this verification fails the server SHALL stop processing the If this verification fails the server SHALL stop processing the
message, and MAY optionally respond with a 4.01 Unauthorized error message, and MAY optionally respond with a 4.01 Unauthorized error
message. Also, the server MAY set an Outer Max-Age option with value message. Also, the server MAY set an Outer Max-Age option with value
zero. The diagnostic payload MAY contain the "Replay detected" zero, to inform any intermediary that the response is not to be
cached. The diagnostic payload MAY contain the "Replay detected"
string. The size and type of the Replay Window depends on the use string. The size and type of the Replay Window depends on the use
case and the protocol with which the OSCORE message is transported. case and the protocol with which the OSCORE message is transported.
In case of reliable and ordered transport from endpoint to endpoint, In case of reliable and ordered transport from endpoint to endpoint,
e.g. TCP, the server MAY just store the last received Partial IV and e.g. TCP, the server MAY just store the last received Partial IV and
require that newly received Partial IVs equals the last received require that newly received Partial IVs equals the last received
Partial IV + 1. However, in case of mixed reliable and unreliable Partial IV + 1. However, in case of mixed reliable and unreliable
transports and where messages may be lost, such a replay mechanism transports and where messages may be lost, such a replay mechanism
may be too restrictive and the default replay window be more suitable may be too restrictive and the default replay window be more suitable
(see Section 3.2.2). (see Section 3.2.2).
Responses that are not notifications (with or without Partial IV) are Responses (with or without Partial IV) are protected against replay
protected against replay as they are bound to the request and the as they are bound to the request and the fact that only a single
fact that only a single response is accepted. Note that the Partial response is accepted. Note that the Partial IV is not used for
IV is not used for replay protection in this case. replay protection in this case.
A client receiving a notification SHALL compare the Partial IV of a The operation of validating the Partial IV and updating the replay
received notification with the Notification Number associated to that protection MUST be atomic.
Observe registration. A client MUST consider the notification with
the highest Partial IV as the freshest, regardless of the order of
arrival. If the verification of the response succeeds, and the
received Partial IV was greater than the Notification Number then the
client SHALL overwrite the corresponding Notification Number with the
received Partial IV (see step 7 of Section 8.4. The client MUST stop
processing notifications with a Partial IV which has been previously
received. The client MAY process only notifications which have
greater Partial IV than the Notification Number.
If messages are processed concurrently, the Partial IV needs to be 7.4.1. Replay Protection of Notifications
validated a second time after decryption and before updating the
replay protection data. The operation of validating the Partial IV The following applies additionally when Observe is supported.
and updating the replay protection data MUST be atomic.
The Notification Number is initialized to the Partial IV of the first
successfully verified notification in response to the registration
request. A client receiving a notification SHALL compare the Partial
IV with the Notification Number associated to that Observe
registration. The client MUST stop processing notifications with a
Partial IV which has been previously received. Applications MAY
decide that a client only processes notifications which have greater
Partial IV than the Notification Number.
If the verification of the response succeeds, and the received
Partial IV was greater than the Notification Number then the client
SHALL overwrite the corresponding Notification Number with the
received Partial IV.
7.5. Losing Part of the Context State 7.5. Losing Part of the Context State
To prevent reuse of an AEAD nonce with the same key, or from To prevent reuse of an AEAD nonce with the same key, or from
accepting replayed messages, an endpoint needs to handle the accepting replayed messages, an endpoint needs to handle the
situation of losing rapidly changing parts of the context, such as situation of losing rapidly changing parts of the context, such as
the request Token, Sender Sequence Number, Replay Window, and the request Token, Sender Sequence Number, Replay Window, and
Notification Numbers. These are typically stored in RAM and Notification Numbers. These are typically stored in RAM and
therefore lost in the case of an unplanned reboot. therefore lost in the case of an unplanned reboot.
After boot, an endpoint MAY reject to use pre-existing security After boot, an endpoint can either use a persistently stored complete
contexts, and MAY establish a new security context with each endpoint or partial security context, or establish a new security context with
it communicates with. However, establishing a fresh security context each endpoint it communicates with. However, establishing a fresh
may have a non-negligible cost in terms of, e.g., power consumption. security context may have a non-negligible cost in terms of, e.g.,
power consumption.
After boot, an endpoint MAY use a partly persistently stored security If the endpoint uses a persistently stored partial security context,
context, but then the endpoint MUST NOT reuse a previous Sender it MUST NOT reuse a previous Sender Sequence Number and MUST NOT
Sequence Number and MUST NOT accept previously accepted messages. accept previously received messages. Some ways to achieve this are
Some ways to achieve this are described in the following sections. described in the following sections.
7.5.1. Sequence Number 7.5.1. Sequence Number
To prevent reuse of Sender Sequence Numbers, an endpoint MAY perform To prevent reuse of Sender Sequence Numbers, an endpoint may perform
the following procedure during normal operations: the following procedure during normal operations:
o Before using a Sender Sequence Number that is evenly divisible by o Before using a Sender Sequence Number that is evenly divisible by
K, where K is a positive integer, store the Sender Sequence Number K, where K is a positive integer, store the Sender Sequence Number
in persistent memory. After boot, the endpoint initiates the in persistent memory. After boot, the endpoint initiates the
Sender Sequence Number to the value stored in persistent memory + Sender Sequence Number to the value stored in persistent memory +
K. Storing to persistent memory can be costly. The value K gives K. Storing to persistent memory can be costly. The value K gives
a trade-off between the number of storage operations and efficient a trade-off between the number of storage operations and efficient
use of Sender Sequence Numbers. use of Sender Sequence Numbers.
7.5.2. Replay Window 7.5.2. Replay Window
To prevent accepting replay of previously received requests, the To prevent accepting replay of previously received requests, the
server MAY perform the following procedure after boot: server may perform the following procedure after boot:
o For each stored security context, the first time after boot the o For each stored security context, the first time after boot the
server receives an OSCORE request, the server responds with the server receives an OSCORE request, the server responds with the
Echo option [I-D.ietf-core-echo-request-tag] to get a request with Echo option [I-D.ietf-core-echo-request-tag] to get a request with
verifiable freshness. The server MUST use its Partial IV when verifiable freshness. The server MUST use its Partial IV when
generating the AEAD nonce and MUST include the Partial IV in the generating the AEAD nonce and MUST include the Partial IV in the
response. response.
If the server using the Echo option can verify a second request as If the server using the Echo option can verify a second request as
fresh, then the Partial IV of the second request is set as the lower fresh, then the Partial IV of the second request is set as the lower
limit of the replay window. limit of the replay window.
7.5.3. Replay Protection of Observe Notifications 7.5.3. Replay of Notifications
To prevent accepting replay of previously received notification To prevent accepting replay of previously received notifications, the
responses, the client MAY perform the following procedure after boot: client may perform the following procedure after boot:
o The client rejects notifications bound to the earlier o The client forgets about earlier registrations, removes all
registration, removes all Notification Numbers and re-registers Notification Numbers and registers using Observe.
using Observe.
8. Processing 8. Processing
This section describes the OSCORE message processing. This section describes the OSCORE message processing. Additional
processing for Observe or Block-wise are described in subsections.
Note that, analogously to [RFC7252] where the Token and source/
destination pair are used to match a response with a request, both
endpoints MUST keep the association (Token, {Security Context,
Partial IV of the request}), in order to be able to find the Security
Context and compute the AAD to protect or verify the response. The
association MAY be forgotten after it has been used to successfully
protect or verify the response, with the exception of Observe
processing, where the association MUST be kept as long as the
Observation is active.
8.1. Protecting the Request 8.1. Protecting the Request
Given a CoAP request, the client SHALL perform the following steps to Given a CoAP request, the client SHALL perform the following steps to
create an OSCORE request: create an OSCORE request:
1. Retrieve the Sender Context associated with the target resource. 1. Retrieve the Sender Context associated with the target resource.
2. Compose the Additional Authenticated Data and the plaintext, as 2. Compose the Additional Authenticated Data and the plaintext, as
described in Section 5.4 and Section 5.3. described in Sections 5.3 and 5.4.
3. Encode the Partial IV (Sender Sequence Number in network byte 3. Encode the Partial IV (Sender Sequence Number in network byte
order) and increment the Sender Sequence Number by one. Compute order) and increment the Sender Sequence Number by one. Compute
the AEAD nonce from the Sender ID, Common IV, and Partial IV as the AEAD nonce from the Sender ID, Common IV, and Partial IV as
described in Section 5.2. described in Section 5.2.
4. Encrypt the COSE object using the Sender Key. Compress the COSE 4. Encrypt the COSE object using the Sender Key. Compress the COSE
Object as specified in Section 6. Object as specified in Section 6.
5. Format the OSCORE message according to Section 4. The OSCORE 5. Format the OSCORE message according to Section 4. The OSCORE
option is added (see Section 4.1.2). option is added (see Section 4.1.2).
6. Store the attribute-value pair (Token, {Security Context, PIV})
in order to be able to find the Recipient Context and the
request_piv from the Token in the response.
8.2. Verifying the Request 8.2. Verifying the Request
A server receiving a request containing the OSCORE option SHALL A server receiving a request containing the OSCORE option SHALL
perform the following steps: perform the following steps:
1. Process Outer Block options according to [RFC7959], until all 1. Discard Code and all class E options (marked in Figure 5 with 'x'
blocks of the request have been received (see Section 4.1.3.3). in column E) present in the received message. For example, an
If-Match Outer option is discarded, but an Uri-Host Outer option
is not discarded.
2. Discard the message Code and all non-special Inner option 2. Decompress the COSE Object (Section 6) and retrieve the Recipient
message fields (marked in Figure 5 with 'x' in column E only) Context associated with the Recipient ID in the 'kid' parameter,
present in the received message. For example, an If-Match Outer additionally using the 'kid context', if present. If either the
option is discarded, but an Uri-Host Outer option is not decompression or the COSE message fails to decode, or the server
discarded. fails to retrieve a Recipient Context with Recipient ID
corresponding to the 'kid' parameter received, then the server
SHALL stop processing the request.
3. Decompress the COSE Object (Section 6) and retrieve the * If either the decompression or the COSE message fails to
Recipient Context associated with the Recipient ID in the 'kid' decode, the server MAY respond with a 4.02 Bad Option error
parameter. If either the decompression or the COSE message message. The server MAY set an Outer Max-Age option with
fails to decode, or the server fails to retrieve a Recipient value zero. The diagnostic payload SHOULD contain the string
Context with Recipient ID corresponding to the 'kid' parameter "Failed to decode COSE".
received, then the server SHALL stop processing the request.
If:
* either the decompression or the COSE message fails to decode, * If the server fails to retrieve a Recipient Context with
the server MAY respond with a 4.02 Bad Option error message. Recipient ID corresponding to the 'kid' parameter received,
The server MAY set an Outer Max-Age option with value zero. the server MAY respond with a 4.01 Unauthorized error message.
The diagnostic payload SHOULD contain the string "Failed to The server MAY set an Outer Max-Age option with value zero.
decode COSE". The diagnostic payload SHOULD contain the string "Security
context not found".
* the server fails to retrieve a Recipient Context with 3. Verify the 'Partial IV' parameter using the Replay Window, as
Recipient ID corresponding to the 'kid' parameter received, described in Section 7.4.
the server MAY respond with a 4.01 Unauthorized error
message. The server MAY set an Outer Max-Age option with
value zero. The diagnostic payload SHOULD contain the string
"Security context not found".
4. Verify the 'Partial IV' parameter using the Replay Window, as 4. Compose the Additional Authenticated Data, as described in
described in Section 7.4. Section 5.4.
5. Compose the Additional Authenticated Data, as described in 5. Compute the AEAD nonce from the Recipient ID, Common IV, and the
Section 5.4. 'Partial IV' parameter, received in the COSE Object.
6. Compute the AEAD nonce from the Recipient ID, Common IV, and the 6. Decrypt the COSE object using the Recipient Key, as per [RFC8152]
'Partial IV' parameter, received in the COSE Object. Section 5.3. (The decrypt operation includes the verification of
the integrity.)
7. Decrypt the COSE object using the Recipient Key, as per * If decryption fails, the server MUST stop processing the
[RFC8152] Section 5.3. (The decrypt operation includes the request and MAY respond with a 4.00 Bad Request error message.
verification of the integrity.) The server MAY set an Outer Max-Age option with value zero.
The diagnostic payload MAY contain the "Decryption failed"
string.
* If decryption fails, the server MUST stop processing the * If decryption succeeds, update the Replay Window, as described
request and MAY respond with a 4.00 Bad Request error in Section 7.
message. The server MAY set an Outer Max-Age option with
value zero. The diagnostic payload MAY contain the
"Decryption failed" string.
* If decryption succeeds, update the Replay Window, as 7. Add decrypted Code, options, and payload to the decrypted
described in Section 7. request. The OSCORE option is removed.
8. For each decrypted option, check if the option is also present 8. The decrypted CoAP request is processed according to [RFC7252].
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 Outer Max-Age is discarded.
9. Add decrypted code, options and payload to the decrypted 8.2.1. Supporting Block-wise
request. The OSCORE option is removed.
10. The decrypted CoAP request is processed according to [RFC7252]. If Block-wise is supported, insert the following step before any
other:
A. If Block-wise is present in the request then process the Outer
Block options according to [RFC7959], until all blocks of the request
have been received (see Section 4.1.3.4).
8.3. Protecting the Response 8.3. Protecting the Response
If a CoAP response is generated in response to an OSCORE request, the If a CoAP response is generated in response to an OSCORE request, the
server SHALL perform the following steps to create an OSCORE server SHALL perform the following steps to create an OSCORE
response. Note that CoAP error responses derived from CoAP response. Note that CoAP error responses derived from CoAP
processing (point 10. in Section 8.2) are protected, as well as processing (step 8 in Section 8.2) are protected, as well as
successful CoAP responses, while the OSCORE errors (point 3, 4, and 7 successful CoAP responses, while the OSCORE errors (steps 2, 3, and 6
in Section 8.2) do not follow the processing below, but are sent as in Section 8.2) do not follow the processing below, but are sent as
simple CoAP responses, without OSCORE processing. simple CoAP responses, without OSCORE processing.
1. Retrieve the Sender Context in the Security Context used to 1. Retrieve the Sender Context in the Security Context associated
verify the request. with the Token.
2. Compose the Additional Authenticated Data and the plaintext, as 2. Compose the Additional Authenticated Data and the plaintext, as
described in Section 5.4 and Section 5.3. described in Sections 5.3 and 5.4.
3. Compute the AEAD nonce 3. Compute the AEAD nonce as described in Section 5.2:
* For Observe notifications, encode the Partial IV (Sender * Either use the nonce from the request, or
Sequence Number in network byte order) and increment the
Sender Sequence Number by one. Compute the AEAD nonce from
the Sender ID, Common IV, and Partial IV as described in
Section 5.2.
* For responses that are not Observe notifications, either use * Encode the Partial IV (Sender Sequence Number in network byte
the nonce from the request, or compute a new nonce from the order) and increment the Sender Sequence Number by one.
Sender ID, Common IV, and a new Partial IV as described in Compute the AEAD nonce from the Sender ID, Common IV, and
Section 5.2, and increment the Sender Sequence Number by one. Partial IV.
4. Encrypt the COSE object using the Sender Key. Compress the COSE 4. Encrypt the COSE object using the Sender Key. Compress the COSE
Object as specified in Section 6. If the AEAD nonce was Object as specified in Section 6. If the AEAD nonce was
constructed from a new Partial IV, this Partial IV MUST be constructed from a new Partial IV, this Partial IV MUST be
included in the message. If the AEAD nonce from the request was included in the message. If the AEAD nonce from the request was
used, the Partial IV MUST NOT be included in the message. used, the Partial IV MUST NOT be included in the message.
5. Format the OSCORE message according to Section 4. The OSCORE 5. Format the OSCORE message according to Section 4. The OSCORE
option is added (see Section 4.1.2). option is added (see Section 4.1.2).
8.3.1. Supporting Observe
If Observe is supported, insert the following step between step 2 and
3 of Section 8.3:
A. If the request was a registration, encode the Partial IV (Sender
Sequence Number in network byte order) and increment the Sender
Sequence Number by one. Compute the AEAD nonce from the Sender ID,
Common IV, and Partial IV, then go to 4.
8.4. Verifying the Response 8.4. Verifying the Response
A client receiving a response containing the OSCORE option SHALL A client receiving a response containing the OSCORE option SHALL
perform the following steps: perform the following steps:
1. Process Outer Block options according to [RFC7959], until all 1. Discard Code and all class E options (marked in Figure 5 with 'x'
blocks of the OSCORE message have been received (see in column E) present in the received message. For example, ETag
Section 4.1.3.3). Outer option is discarded, as well as Max-Age Outer option.
2. Discard the message Code and all non-special Class E options 2. Retrieve the Recipient Context in the Security Context associated
from the message. For example, ETag Outer option is discarded, with the Token. Decompress the COSE Object (Section 6). If
Max-Age Outer option is not discarded. either the decompression or the COSE message fails to decode,
then go to 8.
3. Retrieve the Recipient Context associated with the Token. 3. Compose the Additional Authenticated Data, as described in
Decompress the COSE Object (Section 6). If either the Section 5.4.
decompression or the COSE message fails to decode, then go to
11.
4. If the Observe option is present in the response, but the 4. Compute the AEAD nonce
request was not an Observe registration, then go to 11. If a
Partial IV is required (i.e. an Observe option is included or
the Notification number for the observation has already been
initiated), but not present in the response, then go to 11. For
Observe notifications, verify the received 'Partial IV'
parameter against the corresponding Notification Number as
described in Section 7.4.
5. Compose the Additional Authenticated Data, as described in * If the Partial IV is not present in the response, the nonce
Section 5.4. from the request is used.
6. Compute the AEAD nonce * If the Partial IV is present in the response, compute the
nonce from the Recipient ID, Common IV, and the 'Partial IV'
parameter, received in the COSE Object.
* If the Partial IV are not present in the response, the nonce 5. Decrypt the COSE object using the Recipient Key, as per [RFC8152]
from the request is used. Section 5.3. (The decrypt operation includes the verification of
the integrity.) If decryption fails, then go to 8.
* If the Partial IV is present in the response, compute the 6. Add decrypted Code, options and payload to the decrypted request.
nonce from the Recipient ID, Common IV, and the 'Partial IV' The OSCORE option is removed.
parameter, received in the COSE Object.
7. Decrypt the COSE object using the Recipient Key, as per 7. The decrypted CoAP response is processed according to [RFC7252].
[RFC8152] Section 5.3. (The decrypt operation includes the
verification of the integrity.) If decryption fails, then go to
11.
8. If the response is a notification, initiate or update the 8. In case any of the previous erroneous conditions apply: the
corresponding Notification Number, as described in Section 7. client SHALL stop processing the response.
Otherwise, delete the attribute-value pair (Token, {Security
Context, PIV}).
9. For each decrypted option, check if the option is also present 8.4.1. Supporting Block-wise
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 Outer Max-Age is discarded.
10. Add decrypted code, options and payload to the decrypted If Block-wise is supported, insert the following step before any
request. The OSCORE option is removed. other:
11. The decrypted CoAP response is processed according to [RFC7252]. A. If Block-wise is present in the request then process the Outer
Block options according to [RFC7959], until all blocks of the request
have been received (see Section 4.1.3.4).
12. In case any of the previous erroneous conditions apply: the 8.4.2. Supporting Observe
client SHALL stop processing the response.
An error condition occurring while processing a response in an If Observe is supported:
observation does not cancel the observation. A client MUST NOT react
to failure in step 7 by re-registering the observation immediately. Insert the following step between step 5 and step 6:
A. If the request was an Observe registration, then:
o If the Partial IV is not present in the response, and either the
client has previously received a successful notification to the
registration (active observation) or Inner Observe is present,
then go to 8.
o If the Partial IV is present in the response and Inner Observe is
present, then follow the processing described in Section 4.1.3.5.2
and Section 7.4.1, then:
* initialize the Notification Number (if first successfully
verified notification), or
* overwrite the Notification Number (if the received Partial IV
was greater than the Notification Number).
Replace step 8 of Section 8.4 with:
B. In case any of the previous erroneous conditions apply: the
client SHALL stop processing the response. An error condition
occurring while processing a response to an observation request does
not cancel the observation. A client MUST NOT react to failure by
re-registering the observation immediately.
9. Web Linking 9. Web Linking
The use of OSCORE MAY be indicated by a target attribute "osc" in a The use of OSCORE MAY be indicated by a target attribute "osc" in a
web link [RFC8288] to a resource, e.g. using a link-format document web link [RFC8288] to a resource, e.g. using a link-format document
[RFC6690] if the resource is accessible over CoAP. [RFC6690] if the resource is accessible over CoAP.
The "osc" attribute is a hint indicating that the destination of that The "osc" attribute is a hint indicating that the destination of that
link is only accessible using OSCORE, and unprotected access to it is link is only accessible using OSCORE, and unprotected access to it is
not supported. Note that this is simply a hint, it does not include not supported. Note that this is simply a hint, it does not include
skipping to change at page 38, line 38 skipping to change at page 40, line 46
A value MUST NOT be given for the "osc" attribute; any present value A value MUST NOT be given for the "osc" attribute; any present value
MUST be ignored by parsers. The "osc" attribute MUST NOT appear more MUST be ignored by parsers. The "osc" attribute MUST NOT appear more
than once in a given link-value; occurrences after the first MUST be than once in a given link-value; occurrences after the first MUST be
ignored by parsers. ignored by parsers.
The example in Figure 11 shows a use of the "osc" attribute: the The example in Figure 11 shows a use of the "osc" attribute: the
client does resource discovery on a server, and gets back a list of client does resource discovery on a server, and gets back a list of
resources, one of which includes the "osc" attribute indicating that resources, one of which includes the "osc" attribute indicating that
the resource is protected with OSCORE. The link-format notation (see the resource is protected with OSCORE. The link-format notation (see
Section 5. of [RFC6690]) is used. Section 5 of [RFC6690]) is used.
REQ: GET /.well-known/core REQ: GET /.well-known/core
RES: 2.05 Content RES: 2.05 Content
</sensors/temp>;osc, </sensors/temp>;osc,
</sensors/light>;if="sensor" </sensors/light>;if="sensor"
Figure 11: The web link Figure 11: The web link
10. CoAP-to-CoAP Forwarding Proxy 10. CoAP-to-CoAP Forwarding Proxy
CoAP is designed for proxy operations (see Section 5.7 of [RFC7252]). CoAP is designed for proxy operations (see Section 5.7 of [RFC7252]).
Security requirements for forwarding are presented in Section 2.2.1
of [I-D.hartke-core-e2e-security-reqs].
OSCORE is designed to work with legacy CoAP proxies. Since a CoAP OSCORE is designed to work with OSCORE-unaware CoAP proxies.
response is only applicable to the original CoAP request, caching is Security requirements for forwarding are listed in Section 2.2.1 of
in general not useful. In support of legacy proxies, OSCORE defines [I-D.hartke-core-e2e-security-reqs]. Proxy processing of the (Outer)
special Max-Age processing, see Section 4.1.3.1. An OSCORE-aware Proxy-Uri option works as defined in [RFC7252]. Proxy processing of
proxy SHOULD NOT cache a response to a request with an OSCORE option the (Outer) Block options works as defined in [RFC7959].
Proxy processing of the (Outer) Proxy-Uri option is as defined in However, not all CoAP proxy operations are useful:
[RFC7252].
Proxy processing of the (Outer) Block options is as defined in o Since a CoAP response is only applicable to the original CoAP
[RFC7959]. request, caching is in general not useful. In support of existing
proxies, OSCORE uses the outer Max-Age option, see
Section 4.1.3.1.
Proxy processing of the (Outer) Observe option is as defined in o Proxy processing of the (Outer) Observe option as defined in
[RFC7641]. OSCORE-aware proxies may look at the Partial IV value [RFC7641] is specified in Section 4.1.3.5.
instead of the Outer Observe option.
Optionally, a CoAP proxy MAY detect OSCORE and act accordingly. An
OSCORE-aware CoAP proxy:
o SHALL bypass caching for the request if the OSCORE option is
present
o SHOULD avoid caching responses to requests with an OSCORE option
In the case of Observe (see Section 4.1.3.5) the OSCORE-aware CoAP
proxy:
o SHALL NOT initiate an Observe registration
o MAY verify the order of notifications using Partial IV rather than
the Observe option
11. HTTP Operations 11. HTTP Operations
The CoAP request/response model may be mapped to HTTP and vice versa The CoAP request/response model may be mapped to HTTP and vice versa
as described in Section 10 of [RFC7252]. The HTTP-CoAP mapping is as described in Section 10 of [RFC7252]. The HTTP-CoAP mapping is
further detailed in [RFC8075]. This section defines the components further detailed in [RFC8075]. This section defines the components
needed to map and transport OSCORE messages over HTTP hops. By needed to map and transport OSCORE messages over HTTP hops. By
mapping between HTTP and CoAP and by using cross-protocol proxies mapping between HTTP and CoAP and by using cross-protocol proxies
OSCORE may be used end-to-end between e.g. an HTTP client and a CoAP OSCORE may be used end-to-end between e.g. an HTTP client and a CoAP
server. Examples are provided at the end of the section. server. Examples are provided at the end of the section.
11.1. The HTTP OSCORE Header Field 11.1. The HTTP OSCORE Header Field
The HTTP OSCORE Header Field (see Section 13.4) is used for carrying The HTTP OSCORE Header Field (see Section 13.4) is used for carrying
the content of the CoAP OSCORE option when transporting OSCORE the content of the CoAP OSCORE option when transporting OSCORE
messages over HTTP hops. messages over HTTP hops.
The HTTP OSCORE header field is only used in POST requests and 200 The HTTP OSCORE header field is only used in POST requests and 200
(OK) responses. When used, the HTTP header field Content-Type is set (OK) responses. When used, the HTTP header field Content-Type is set
to 'application/oscore' (see Section 13.5) indicating that the HTTP to 'application/oscore' (see Section 13.5) indicating that the HTTP
body of this message contains the OSCORE payload (see Section 6.2}. body of this message contains the OSCORE payload (see Section 6.2).
No additional semantics is provided by other message fields. No additional semantics is provided by other message fields.
Using the Augmented Backus-Naur Form (ABNF) notation of [RFC5234], Using the Augmented Backus-Naur Form (ABNF) notation of [RFC5234],
including the following core ABNF syntax rules defined by that including the following core ABNF syntax rules defined by that
specification: ALPHA (letters) and DIGIT (decimal digits), the HTTP specification: ALPHA (letters) and DIGIT (decimal digits), the HTTP
OSCORE header field value is as follows. OSCORE header field value is as follows.
base64url-char = ALPHA / DIGIT / "-" / "_" base64url-char = ALPHA / DIGIT / "-" / "_"
OSCORE = 2*base64url-char OSCORE = 2*base64url-char
skipping to change at page 40, line 4 skipping to change at page 42, line 35
No additional semantics is provided by other message fields. No additional semantics is provided by other message fields.
Using the Augmented Backus-Naur Form (ABNF) notation of [RFC5234], Using the Augmented Backus-Naur Form (ABNF) notation of [RFC5234],
including the following core ABNF syntax rules defined by that including the following core ABNF syntax rules defined by that
specification: ALPHA (letters) and DIGIT (decimal digits), the HTTP specification: ALPHA (letters) and DIGIT (decimal digits), the HTTP
OSCORE header field value is as follows. OSCORE header field value is as follows.
base64url-char = ALPHA / DIGIT / "-" / "_" base64url-char = ALPHA / DIGIT / "-" / "_"
OSCORE = 2*base64url-char OSCORE = 2*base64url-char
The HTTP OSCORE header field is not appropriate to list in the The HTTP OSCORE header field is not appropriate to list in the
Connection header field (see Section 6.1 of [RFC7230]) since it is Connection header field (see Section 6.1 of [RFC7230]) since it is
not hop-by-hop. The HTTP OSCORE header field is not appropriate to not hop-by-hop. OSCORE messages are generally not useful when served
list in a Vary response header field (see Section 7.1.4 of [RFC7231]) from cache (i.e., they will generally be marked Cache-Control: no-
since a cached response would in general not be useful for other cache) and so interaction with Vary is not relevant (Section 7.1.4 of
clients. The HTTP OSCORE header field is not useful in trailers (see [RFC7231]). Since the HTTP OSCORE header field is critical for
Section 4.1 of [RFC7230]). message processing, moving it from headers to trailers renders the
message unusable in case trailers are ignored (see Section 4.1 of
[RFC7230]).
Intermediaries are in general not allowed to insert, delete, or Intermediaries are in general not allowed to insert, delete, or
modify the OSCORE header. Changes to the HTTP OSCORE header field modify the OSCORE header. Changes to the HTTP OSCORE header field
will in general violate the integrity of the OSCORE message resulting will in general violate the integrity of the OSCORE message resulting
in an error. For the same reason the HTTP OSCORE header field is in in an error. For the same reason the HTTP OSCORE header field is in
general not preserved across redirects. A CoAP-to-HTTP proxy general not preserved across redirects.
receiving a request for redirect may copy the HTTP OSCORE header
field to the new request, although the condition for this being Since redirects are not defined in the mappings between HTTP and CoAP
successful is that the server to which the OSCORE message is [RFC8075][RFC7252], a number of conditions need to be fulfilled for
redirected needs to be a clone of the server for which the OSCORE redirects to work. For CoAP client to HTTP server, such conditions
message was intended (same target resource, same OSCORE security include:
context etc.). If an HTTP/OSCORE client receives a redirect it
should instead generate a new OSCORE request for the server it was o the CoAP-to-HTTP proxy follows the redirect, instead of the CoAP
client as in the HTTP case
o the CoAP-to-HTTP proxy copies the HTTP OSCORE header field and
body to the new request
o the target of the redirect has the necessary OSCORE security
context required to decrypt and verify the message
Since OSCORE requires HTTP body to be preserved across redirects, the
HTTP server is recommended to reply with 307 or 308 instead of 301 or
302.
For the case of HTTP client to CoAP server, although redirect is not
defined for CoAP servers [RFC7252], an HTTP client receiving a
redirect should generate a new OSCORE request for the server it was
redirected to. redirected to.
11.2. CoAP-to-HTTP Mapping 11.2. CoAP-to-HTTP Mapping
Section 10.1 of [RFC7252] describes the fundamentals of the CoAP-to- Section 10.1 of [RFC7252] describes the fundamentals of the CoAP-to-
HTTP cross-protocol mapping process. The additional rules for OSCORE HTTP cross-protocol mapping process. The additional rules for OSCORE
messages are: messages are:
o The HTTP OSCORE header field value is set to o The HTTP OSCORE header field value is set to
skipping to change at page 44, line 44 skipping to change at page 47, line 44
(D)TLS protects hop-by-hop the entire message. OSCORE protects end- (D)TLS protects hop-by-hop the entire message. OSCORE protects end-
to-end all information that is not required for proxy operations (see to-end all information that is not required for proxy operations (see
Section 4). (D)TLS and OSCORE can be combined, thereby enabling end- Section 4). (D)TLS and OSCORE can be combined, thereby enabling end-
to-end security of the message payload, in combination with hop-by- to-end security of the message payload, in combination with hop-by-
hop protection of the entire message, during transport between end- hop protection of the entire message, during transport between end-
point and intermediary node. In particular when OSCORE is used with point and intermediary node. In particular when OSCORE is used with
HTTP, the additional TLS protection of HTTP hops is recommended, e.g. HTTP, the additional TLS protection of HTTP hops is recommended, e.g.
between an HTTP endpoint and a proxy translating between HTTP and between an HTTP endpoint and a proxy translating between HTTP and
CoAP. CoAP.
The consequences of unprotected message fields are analyzed in Applications need to consider that certain message fields and
Appendix D.4. Error messages occurring during CoAP processing are messages types are not protected end-to-end and may be spoofed or
protected end-to-end. Error messages occurring during OSCORE manipulated. The consequences of unprotected message fields are
processing are not always possible to protect, e.g. if the receiving analyzed in Appendix D.4.
endpoint cannot locate the right security context. It may still be
favorable to send an unprotected error message, e.g. to prevent
extensive retransmissions, so unprotected error messages are allowed
as specified. Similar to error messages, signaling messages are not
always possible to protect as they may be intended for an
intermediary. Applications using unprotected error and signaling
messages need to consider the threat that these messages may be
spoofed.
12.2. Security Context Establishment 12.2. Security Context Establishment
The use of COSE_Encrypt0 and AEAD to protect messages as specified in The use of COSE_Encrypt0 and AEAD to protect messages as specified in
this document requires an established security context. The method this document requires an established security context. The method
to establish the security context described in Section 3.2 is based to establish the security context described in Section 3.2 is based
on a common Master Secret and unique Sender IDs. The necessary input on a common Master Secret and unique Sender IDs. The necessary input
parameters may be pre-established or obtained using a key parameters may be pre-established or obtained using a key
establishment protocol augmented with establishment of Sender/ establishment protocol augmented with establishment of Sender/
Recipient ID such as the OSCORE profile of the ACE framework Recipient ID such as the OSCORE profile of the ACE framework
[I-D.ietf-ace-oscore-profile]. This procedure must ensure that the [I-D.ietf-ace-oscore-profile]. Such a procedure must ensure that the
requirements of the security context parameters are complied with requirements of the security context parameters for the intended use
Section 3.3 for the intended use and also in error situations. It is are complied with (see Section 3.3) and also in error situations. It
recommended to use a key establishment protocol which provides is recommended to use a key establishment protocol which provides
forward secrecy whenever possible. Considerations for the deploying forward secrecy whenever possible. Considerations for deploying
OSCORE with a fixed Master Secret are given in Appendix B. OSCORE with a fixed Master Secret are given in Appendix B.
12.3. Master Secret 12.3. Master Secret
OSCORE uses HKDF [RFC5869] and the established input parameters to OSCORE uses HKDF [RFC5869] and the established input parameters to
derive the security context. The required properties of the security derive the security context. The required properties of the security
context parameters are discussed in Section 3.3, in this section we context parameters are discussed in Section 3.3, in this section we
focus on the Master Secret. HKDF denotes in this specification the focus on the Master Secret. HKDF denotes in this specification the
composition of the expand and extract functions as defined in composition of the expand and extract functions as defined in
[RFC5869] and the Master Secret is used as Input Key Material (IKM). [RFC5869] and the Master Secret is used as Input Key Material (IKM).
skipping to change at page 45, line 48 skipping to change at page 48, line 45
Therefore, the main requirement for the OSCORE Master Secret, in Therefore, the main requirement for the OSCORE Master Secret, in
addition to being secret, is that it is has a good amount of addition to being secret, is that it is has a good amount of
randomness. The selected key establishment schemes must ensure that randomness. The selected key establishment schemes must ensure that
the necessary properties for the Master Secret are fulfilled. For the necessary properties for the Master Secret are fulfilled. For
pre-shared key deployments and key transport solutions such as pre-shared key deployments and key transport solutions such as
[I-D.ietf-ace-oscore-profile], the Master Secret can be generated [I-D.ietf-ace-oscore-profile], the Master Secret can be generated
offline using a good random number generator. offline using a good random number generator.
12.4. Replay Protection 12.4. Replay Protection
Most AEAD algorithms require a unique nonce for each message, for Replay attacks need to be considered in different parts of the
which the sender sequence numbers in the COSE message field 'Partial implementation. Most AEAD algorithms require a unique nonce for each
IV' is used. If the recipient accepts any sequence number larger message, for which the sender sequence numbers in the COSE message
than the one previously received, then the problem of sequence number field 'Partial IV' is used. If the recipient accepts any sequence
synchronization is avoided. With reliable transport, it may be number larger than the one previously received, then the problem of
defined that only messages with sequence number which are equal to sequence number synchronization is avoided. With reliable transport,
previous sequence number + 1 are accepted. The alternatives to it may be defined that only messages with sequence number which are
sequence numbers have their issues: very constrained devices may not equal to previous sequence number + 1 are accepted. An adversary may
be able to support accurate time, or to generate and store large try to induce a device reboot for the purpose of replaying a message
numbers of random nonces. The requirement to change key at counter (see Section 7.5).
wrap is a complication, but it also forces the user of this
specification to think about implementing key renewal. Note that sharing a security context between servers may open up for
replay attacks, for example if the replay windows are not
synchronized.
12.5. Client Aliveness 12.5. Client Aliveness
A verified OSCORE request enables the server to verify the identity A verified OSCORE request enables the server to verify the identity
of the entity who generated the message. However, it does not verify of the entity who generated the message. However, it does not verify
that the client is currently involved in the communication, since the that the client is currently involved in the communication, since the
message may be a delayed delivery of a previously generated request message may be a delayed delivery of a previously generated request
which now reaches the server. To verify the aliveness of the client which now reaches the server. To verify the aliveness of the client
the server may use the Echo option in the response to a request from the server may use the Echo option in the response to a request from
the client (see [I-D.ietf-core-echo-request-tag]). the client (see [I-D.ietf-core-echo-request-tag]).
skipping to change at page 46, line 41 skipping to change at page 49, line 39
16-64-128 is selected for compatibility with CCM*. 16-64-128 is selected for compatibility with CCM*.
In order to prevent cryptanalysis when the same plaintext is In order to prevent cryptanalysis when the same plaintext is
repeatedly encrypted by many different users with distinct keys, the repeatedly encrypted by many different users with distinct keys, the
nonce is formed by mixing the sequence number with a secret per- nonce is formed by mixing the sequence number with a secret per-
context initialization vector (Common IV) derived along with the keys context initialization vector (Common IV) derived along with the keys
(see Section 3.1 of [RFC8152]), and by using a Master Salt in the key (see Section 3.1 of [RFC8152]), and by using a Master Salt in the key
derivation (see [MF00] for an overview). The Master Secret, Sender derivation (see [MF00] for an overview). The Master Secret, Sender
Key, Recipient Key, and Common IV must be secret, the rest of the Key, Recipient Key, and Common IV must be secret, the rest of the
parameters may be public. The Master Secret must have a good amount parameters may be public. The Master Secret must have a good amount
of randomness (see Section 12.3)). of randomness (see Section 12.3).
12.7. Message Segmentation 12.7. Message Segmentation
The Inner Block options enable the sender to split large messages The Inner Block options enable the sender to split large messages
into OSCORE-protected blocks such that the receiving endpoint can into OSCORE-protected blocks such that the receiving endpoint can
verify blocks before having received the complete message. The Outer verify blocks before having received the complete message. The Outer
Block options allow for arbitrary proxy fragmentation operations that Block options allow for arbitrary proxy fragmentation operations that
cannot be verified by the endpoints, but can by policy be restricted cannot be verified by the endpoints, but can by policy be restricted
in size since the Inner Block options allow for secure fragmentation in size since the Inner Block options allow for secure fragmentation
of very large messages. A maximum message size (above which the of very large messages. A maximum message size (above which the
skipping to change at page 47, line 27 skipping to change at page 50, line 26
The unprotected options (Figure 5) may reveal privacy sensitive The unprotected options (Figure 5) may reveal privacy sensitive
information, see Appendix D.4. CoAP headers sent in plaintext allow, information, see Appendix D.4. CoAP headers sent in plaintext allow,
for example, matching of CON and ACK (CoAP Message Identifier), for example, matching of CON and ACK (CoAP Message Identifier),
matching of request and responses (Token) and traffic analysis. matching of request and responses (Token) and traffic analysis.
OSCORE does not provide protection for HTTP header fields which are OSCORE does not provide protection for HTTP header fields which are
not both CoAP-mappable and class E. The HTTP message fields which not both CoAP-mappable and class E. The HTTP message fields which
are visible to on-path entity are only used for the purpose of are visible to on-path entity are only used for the purpose of
transporting the OSCORE message, whereas the application layer transporting the OSCORE message, whereas the application layer
message is encoded in CoAP and encrypted. message is encoded in CoAP and encrypted.
COSE message fields, i.e. the OSCORE option, may reveal information
about the communicating endpoints. E.g. 'kid' and 'kid context',
which are intended to help the server find the right context, may
reveal information about the client. Tracking 'kid' and 'kid
context' to one server may be used for correlating requests from one
client.
Unprotected error messages reveal information about the security Unprotected error messages reveal information about the security
state in the communication between the endpoints. Unprotected state in the communication between the endpoints. Unprotected
signaling messages reveal information about the reliable transport signaling messages reveal information about the reliable transport
used on a leg of the path. Using the mechanisms described in used on a leg of the path. Using the mechanisms described in
Section 7.5 may reveal when a device goes through a reboot. This can Section 7.5 may reveal when a device goes through a reboot. This can
be mitigated by the device storing the precise state of sender be mitigated by the device storing the precise state of sender
sequence number and replay window on a clean shutdown. sequence number and replay window on a clean shutdown.
The length of message fields can reveal information about the The length of message fields can reveal information about the
message. Applications may use a padding scheme to protect against message. Applications may use a padding scheme to protect against
skipping to change at page 48, line 13 skipping to change at page 51, line 18
Registry": Registry":
o Name: kid context o Name: kid context
o Label: TBD2 o Label: TBD2
o Value Type: bstr o Value Type: bstr
o Value Registry: o Value Registry:
o Description: Identifies the kid context o Description: Identifies the context for kid
o Reference: Section 5.1 of this document o Reference: Section 5.1 of this document
Note to IANA: Label assignment in (Integer value between 1 and 255) Note to IANA: Label assignment in (Integer value between 1 and 255)
is requested. (RFC Editor: Delete this note after IANA assignment) is requested. (RFC Editor: Delete this note after IANA assignment)
13.2. CoAP Option Numbers Registry 13.2. CoAP Option Numbers Registry
The OSCORE option is added to the CoAP Option Numbers registry: The OSCORE option is added to the CoAP Option Numbers registry:
skipping to change at page 53, line 24 skipping to change at page 56, line 24
Bormann, C., "Constrained Application Protocol (CoAP) over Bormann, C., "Constrained Application Protocol (CoAP) over
IEEE 802.15.4 Information Element for IETF", draft- IEEE 802.15.4 Information Element for IETF", draft-
bormann-6lo-coap-802-15-ie-00 (work in progress), April bormann-6lo-coap-802-15-ie-00 (work in progress), April
2016. 2016.
[I-D.hartke-core-e2e-security-reqs] [I-D.hartke-core-e2e-security-reqs]
Selander, G., Palombini, F., and K. Hartke, "Requirements Selander, G., Palombini, F., and K. Hartke, "Requirements
for CoAP End-To-End Security", draft-hartke-core-e2e- for CoAP End-To-End Security", draft-hartke-core-e2e-
security-reqs-03 (work in progress), July 2017. security-reqs-03 (work in progress), July 2017.
[I-D.ietf-6tisch-minimal-security]
Vucinic, M., Simon, J., Pister, K., and M. Richardson,
"Minimal Security Framework for 6TiSCH", draft-ietf-
6tisch-minimal-security-05 (work in progress), March 2018.
[I-D.ietf-ace-oauth-authz] [I-D.ietf-ace-oauth-authz]
Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and
H. Tschofenig, "Authentication and Authorization for H. Tschofenig, "Authentication and Authorization for
Constrained Environments (ACE) using the OAuth 2.0 Constrained Environments (ACE) using the OAuth 2.0
Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-11 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-12
(work in progress), March 2018. (work in progress), May 2018.
[I-D.ietf-ace-oscore-profile] [I-D.ietf-ace-oscore-profile]
Seitz, L., Palombini, F., Gunnarsson, M., and G. Selander, Seitz, L., Palombini, F., Gunnarsson, M., and G. Selander,
"OSCORE profile of the Authentication and Authorization "OSCORE profile of the Authentication and Authorization
for Constrained Environments Framework", draft-ietf-ace- for Constrained Environments Framework", draft-ietf-ace-
oscore-profile-01 (work in progress), March 2018. oscore-profile-01 (work in progress), March 2018.
[I-D.ietf-cbor-cddl] [I-D.ietf-cbor-cddl]
Birkholz, H., Vigano, C., and C. Bormann, "Concise data Birkholz, H., Vigano, C., and C. Bormann, "Concise data
definition language (CDDL): a notational convention to definition language (CDDL): a notational convention to
skipping to change at page 54, line 45 skipping to change at page 57, line 40
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, Format", RFC 6690, DOI 10.17487/RFC6690, August 2012,
<https://www.rfc-editor.org/info/rfc6690>. <https://www.rfc-editor.org/info/rfc6690>.
[RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for
Constrained-Node Networks", RFC 7228, Constrained-Node Networks", RFC 7228,
DOI 10.17487/RFC7228, May 2014, DOI 10.17487/RFC7228, May 2014,
<https://www.rfc-editor.org/info/rfc7228>. <https://www.rfc-editor.org/info/rfc7228>.
[RFC7390] Rahman, A., Ed. and E. Dijk, Ed., "Group Communication for
the Constrained Application Protocol (CoAP)", RFC 7390,
DOI 10.17487/RFC7390, October 2014,
<https://www.rfc-editor.org/info/rfc7390>.
[RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
2015, <https://www.rfc-editor.org/info/rfc7515>. 2015, <https://www.rfc-editor.org/info/rfc7515>.
[RFC7967] Bhattacharyya, A., Bandyopadhyay, S., Pal, A., and T. [RFC7967] Bhattacharyya, A., Bandyopadhyay, S., Pal, A., and T.
Bose, "Constrained Application Protocol (CoAP) Option for Bose, "Constrained Application Protocol (CoAP) Option for
No Server Response", RFC 7967, DOI 10.17487/RFC7967, No Server Response", RFC 7967, DOI 10.17487/RFC7967,
August 2016, <https://www.rfc-editor.org/info/rfc7967>. August 2016, <https://www.rfc-editor.org/info/rfc7967>.
Appendix A. Scenario Examples Appendix A. Scenario Examples
skipping to change at page 55, line 41 skipping to change at page 58, line 36
| | | | | |
| +------>| Code: 0.02 (POST) | +------>| Code: 0.02 (POST)
| | POST | Token: 0x7b | | POST | Token: 0x7b
| | | OSCORE: [kid:5f,Partial IV:42] | | | OSCORE: [kid:5f,Partial IV:42]
| | | Payload: {Code:0.01, | | | Payload: {Code:0.01,
| | | Uri-Path:"alarm_status"} | | | Uri-Path:"alarm_status"}
| | | | | |
| |<------+ Code: 2.04 (Changed) | |<------+ Code: 2.04 (Changed)
| | 2.04 | Token: 0x7b | | 2.04 | Token: 0x7b
| | | OSCORE: - | | | OSCORE: -
| | | Payload: {Code:2.05, "OFF"} | | | Payload: {Code:2.05, "0"}
| | | | | |
|<------+ | Code: 2.04 (Changed) |<------+ | Code: 2.04 (Changed)
| 2.04 | | Token: 0x8c | 2.04 | | Token: 0x8c
| | | OSCORE: - | | | OSCORE: -
| | | Payload: {Code:2.05, "OFF"} | | | Payload: {Code:2.05, "0"}
| | | | | |
Figure 12: Secure Access to Sensor. Square brackets [ ... ] indicate Figure 12: Secure Access to Sensor. Square brackets [ ... ] indicate
content of compressed COSE object. Curly brackets { ... } indicate content of compressed COSE object. Curly brackets { ... } indicate
encrypted data. encrypted data.
The request/response Codes are encrypted by OSCORE and only dummy The request/response Codes are encrypted by OSCORE and only dummy
Codes (POST/Changed) are visible in the header of the OSCORE message. Codes (POST/Changed) are visible in the header of the OSCORE message.
The option Uri-Path ("alarm_status") and payload ("OFF") are The option Uri-Path ("alarm_status") and payload ("0") are encrypted.
encrypted.
The COSE header of the request contains an identifier (5f), The COSE header of the request contains an identifier (5f),
indicating which security context was used to protect the message and indicating which security context was used to protect the message and
a Partial IV (42). a Partial IV (42).
The server verifies the request as specified in Section 8.2. The The server verifies the request as specified in Section 8.2. The
client verifies the response as specified in Section 8.4. client verifies the response as specified in Section 8.4.
A.2. Secure Subscribe to Sensor A.2. Secure Subscribe to Sensor
skipping to change at page 57, line 25 skipping to change at page 60, line 19
| | | Observe: 8 | | | Observe: 8
| | | OSCORE: [Partial IV:36] | | | OSCORE: [Partial IV:36]
| | | Payload: {Code:2.05, | | | Payload: {Code:2.05,
| | | Content-Format:0, "180"} | | | Content-Format:0, "180"}
| | | | | |
Figure 13: Secure Subscribe to Sensor. Square brackets [ ... ] Figure 13: Secure Subscribe to Sensor. Square brackets [ ... ]
indicate content of compressed COSE object header. Curly brackets { indicate content of compressed COSE object header. Curly brackets {
... } indicate encrypted data. ... } indicate encrypted data.
The dummy Codes (FETCH/Content) are visible in the header of the The dummy Codes (FETCH/Content) are used to allow forwarding of
OSCORE message to allow intermediary processing of Observe. The Observe messages. The options Content-Format (0) and the payload
options Content-Format (0) and the payload ("220" and "180"), are ("220" and "180"), are encrypted.
encrypted.
The COSE header of the request contains an identifier (ca), The COSE header of the request contains an identifier (ca),
indicating the security context used to protect the message and a indicating the security context used to protect the message and a
Partial IV (15). The COSE headers of the responses contains Partial Partial IV (15). The COSE headers of the responses contains Partial
IVs (32 and 36). IVs (32 and 36).
The server verifies that the Partial IV has not been received before. The server verifies that the Partial IV has not been received before.
The client verifies that the responses are bound to the request and The client verifies that the responses are bound to the request and
that the Partial IVs are greater than any Partial IV previously that the Partial IVs are greater than any Partial IV previously
received in a response bound to the request. received in a response bound to the request.
Appendix B. Deployment Examples Appendix B. Deployment Examples
Two examples complying with the requirements on the security context Two examples complying with the requirements on the security context
parameters (Section 3.3) are given in this section. parameters (Section 3.3) are given in this section.
B.1. Master Secret Used Once B.1. Master Secret Used Once
For settings where the Master Secret is only used during deployment, An application may derive a security context once and use it for the
the uniqueness of the AEAD nonce may be assured by persistent storage lifetime of a device. For many IoT deployments, a 128 bit uniformly
of the security context as described in this specification (see random Master Key is sufficient for encrypting all data exchanged
Section 7.5). For many IoT deployments, a 128 bit uniformly random with the IoT device. This specification describes techniques for
Master Key is sufficient for encrypting all data exchanged with the persistent storage of the security context and synchronization of
IoT device throughout its lifetime. sequence numbers (see Section 7.5) to ensure that security is
maintained with the existing security context.
B.2. Master Secret Used Multiple Times B.2. Master Secret Used Multiple Times
One Master Secret can be used to derive multiple security contexts if Section 12.2 recommends the use of a key establishment protocol
unique Master Salts can be guaranteed. This may be useful e.g. in providing forward secrecy of the Master Secret.
case of recommissioning with reused Master Secret. In order to
prevent reuse of AEAD nonce and key, which would compromise the
security, the Master Salt must never be used twice, even if the
device is reset, recommissioned or in error cases. Examples of
failures include derivation of pseudorandom master salt from a static
seed, or a deterministic seeding procedure with inputs that are
repeated or can be replayed. Techniques for persistent storage of
security state may be used also in this case, to ensure uniqueness of
Master Salt.
Assuming the Master Salts are indeed unique (or stochastically An application which does not require forward secrecy may allow
unique) we give an example of a procedure which may be implemented in multiple security contexts to be derived from one Master Secret. The
client and server to establish the OSCORE security context based on requirements on the security context parameters must be fulfilled
pre-established input parameters (see Section 3.2) except for the (Section 3.3) even if the client or server is rebooted,
Master Salt, which is transported in kid context parameter (see recommissioned or in error cases.
Section 5.1) of the request.
1. In order to establish a security context with a server for the This section gives an example of an application allowing new security
first time, or a new security context replacing an old security contexts to be derived from input parameters pre-established between
context, the client generates a (pseudo-)random uniformly client and server for this purpose: in particular Master Secret,
distributed 64-bit Master Salt and derives the security context Master Salt and Sender/Recipient ID (see Section 3.2):
as specified in Section 3.2. The client protects a request with
the new Sender Context and sends the message with kid context set
to the Master Salt.
2. The server, receiving an OSCORE request with a non-empty kid o The client generates an ID Context which has previously not been
context derives the new security context using the received kid used with the pre-established input parameters and derives a new
context as Master Salt. The server processes the request as security context. ID context may be pseudo-random and large for
specified in this document using the new Recipient Context. If stochastic uniqueness, but care must be taken e.g. to avoid re-use
the processing of the request completes without error, the server of the same seed for random number generation. Using this new
responds with an Echo option as specified in security context, the client generates an OSCORE request with (kid
[I-D.ietf-core-echo-request-tag]. The response is protected with context, kid) = (ID Context, Sender ID) in the OSCORE option.
the new Sender Context.
3. The client, receiving a response with an Echo option to a request o The server receiving such an OSCORE request with kid matching the
which used a new security context, verifies the response using Recipient ID of pre-established input parameters, but with a new
the new Recipient Context, and if valid repeats the request with kid context, derives the security context using ID Context = kid
the Echo option (see [I-D.ietf-core-echo-request-tag]) using the context. If the message verifies then a new security context with
new Sender Context. Subsequent message exchanges (unless this ID Context is stored in the server, and used in the response.
superseded) are processed using the new security context without Further requests with the same (kid context, kid) are verified
including the Master Salt in the kid context. with this security context.
4. The server, receiving a request with a kid context and a valid As an alternative procedure to reduce the subsequent overhead in
Echo option (see [I-D.ietf-core-echo-request-tag]), repeats the requests due to kid context, the verification of a message with a new
processing described in step 2. If it completes without error, ID Context may trigger the server to generate a new kid to replace
then the new security context is established, and the request is the Client Sender ID in future requests. A client may e.g. indicate
valid. If the server already had an old security context with support for such a procedure by requesting a special well-known URI
this client that is now replaced by the new security context. and receive the new kid in the response, which together with the
input parameters and the ID context is used to derive the new
security context which may be identified only by its kid. The
details are out of scope for this specification.
If the server receives a request without kid context from a client The procedures may be complemented with the use of the Echo option
with which no security context is established, then the server for verifying the aliveness of the client requesting a new security
responds with a 4.01 Unauthorized error message with diagnostic context.
payload containing the string "Security context not found". This
could be the result of the server having lost its security context or
that a new security context has not been successfully established,
which may be a trigger for the client to run this procedure.
Appendix C. Test Vectors Appendix C. Test Vectors
This appendix includes the test vectors for different examples of This appendix includes the test vectors for different examples of
CoAP messages using OSCORE. CoAP messages using OSCORE. Given a set of inputs, OSCORE defines
how to set up the Security Context in both the client and the server.
C.1. Test Vector 1: Key Derivation with Master Salt C.1. Test Vector 1: Key Derivation with Master Salt
Given a set of inputs, OSCORE defines how to set up the Security In this test vector, a Master Salt of 8 bytes is used. The default
Context in both the client and the server. The default values are values are used for AEAD Algorithm and KDF.
used for AEAD Algorithm and KDF.
C.1.1. Client C.1.1. Client
Inputs: Inputs:
o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes)
o Master Salt: 0x9e7ca92223786340 (8 bytes) o Master Salt: 0x9e7ca92223786340 (8 bytes)
o Sender ID: 0x (0 byte) o Sender ID: 0x (0 byte)
o Recipient ID: 0x01 (1 byte) o Recipient ID: 0x01 (1 byte)
From the previous parameters, From the previous parameters,
o info (for Sender Key): 0x84400A634b657910 (8 bytes) o info (for Sender Key): 0x8540f60a634b657910 (9 bytes)
o info (for Recipient Key): 0x8441010A634b657910 (9 bytes) o info (for Recipient Key): 0x854101f60a634b657910 (10 bytes)
o info (for Common IV): 0x84400a6249560d (7 bytes) o info (for Common IV): 0x8540f60a6249560d (8 bytes)
Outputs: Outputs:
o Sender Key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) o Sender Key: 0xf0910ed7295e6ad4b54fc793154302ff (16 bytes)
o Recipient Key: 0xe534a26a64aa3982e988e31f1e401e65 (16 bytes)
o Common IV: 0x01727733ab49ead385b18f7d91 (13 bytes) o Recipient Key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes)
o Common IV: 0x4622d4dd6d944168eefb54987c (13 bytes)
C.1.2. Server C.1.2. Server
Inputs: Inputs:
o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes)
o Master Salt: 0x9e7ca92223786340 (64 bytes) o Master Salt: 0x9e7ca92223786340 (8 bytes)
o Sender ID: 0x01 (1 byte) o Sender ID: 0x01 (1 byte)
o Recipient ID: 0x (0 byte) o Recipient ID: 0x (0 byte)
From the previous parameters, From the previous parameters,
o info (for Sender Key): 0x8441010A634b657910 (9 bytes) o info (for Sender Key): 0x854101f60a634b657910 (10 bytes)
o info (for Recipient Key): 0x84400A634b657910 (8 bytes) o info (for Recipient Key): 0x8540f60a634b657910 (9 bytes)
o info (for Common IV): 0x84400a6249560d (7 bytes) o info (for Common IV): 0x8540f60a6249560d (8 bytes)
Outputs: Outputs:
o Sender Key: 0xe534a26a64aa3982e988e31f1e401e65 (16 bytes) o Sender Key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes)
o Recipient Key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) o Recipient Key: 0xf0910ed7295e6ad4b54fc793154302ff (16 bytes)
o Common IV: 0x01727733ab49ead385b18f7d91 (13 bytes) o Common IV: 0x4622d4dd6d944168eefb54987c (13 bytes)
C.2. Test Vector 2: Key Derivation without Master Salt C.2. Test Vector 2: Key Derivation without Master Salt
Given a set of inputs, OSCORE defines how to set up the Security In this test vector, the default values are used for AEAD Algorithm,
Context in both the client and the server. The default values are KDF, and Master Salt.
used for AEAD Algorithm, KDF, and Master Salt.
C.2.1. Client C.2.1. Client
Inputs: Inputs:
o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes)
o Sender ID: 0x00 (1 byte) o Sender ID: 0x00 (1 byte)
o Recipient ID: 0x01 (1 byte) o Recipient ID: 0x01 (1 byte)
skipping to change at page 61, line 4 skipping to change at page 63, line 36
C.2.1. Client C.2.1. Client
Inputs: Inputs:
o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes)
o Sender ID: 0x00 (1 byte) o Sender ID: 0x00 (1 byte)
o Recipient ID: 0x01 (1 byte) o Recipient ID: 0x01 (1 byte)
From the previous parameters, From the previous parameters,
o info (for Sender Key): 0x8441000A634b657910 (9 bytes) o info (for Sender Key): 0x854100f60a634b657910 (10 bytes)
o info (for Recipient Key): 0x8441010A634b657910 (9 bytes) o info (for Recipient Key): 0x854101f60a634b657910 (10 bytes)
o info (for Common IV): 0x84400a6249560d (7 bytes) o info (for Common IV): 0x8540f60a6249560d (8 bytes)
Outputs: Outputs:
o Sender Key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) o Sender Key: 0x321b26943253c7ffb6003b0b64d74041 (16 bytes)
o Recipient Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) o Recipient Key: 0xe57b5635815177cd679ab4bcec9d7dda (16 bytes)
o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) o Common IV: 0xbe35ae297d2dace910c52e99f9 (13 bytes)
C.2.2. Server C.2.2. Server
Inputs: Inputs:
o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes) o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes)
o Sender ID: 0x01 (1 byte) o Sender ID: 0x01 (1 byte)
o Recipient ID: 0x00 (1 byte) o Recipient ID: 0x00 (1 byte)
From the previous parameters, From the previous parameters,
o info (for Sender Key): 0x8441010A634b657910 (9 bytes) o info (for Sender Key): 0x854101f60a634b657910 (10 bytes)
o info (for Recipient Key): 0x8441000A634b657910 (9 bytes) o info (for Recipient Key): 0x854100f60a634b657910 (10 bytes)
o info (for Common IV): 0x84400a6249560d (7 bytes) o info (for Common IV): 0x8540f60a6249560d (8 bytes)
Outputs: Outputs:
o Sender Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) o Sender Key: 0xe57b5635815177cd679ab4bcec9d7dda (16 bytes)
o Recipient Key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) o Recipient Key: 0x321b26943253c7ffb6003b0b64d74041 (16 bytes)
o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) o Common IV: 0xbe35ae297d2dace910c52e99f9 (13 bytes)
C.3. Test Vector 3: OSCORE Request, Client C.3. Test Vector 3: Key Derivation with ID Context
In this test vector, a Master Salt of 8 bytes and a ID Context of 8
bytes are used. The default values are used for AEAD Algorithm and
KDF.
C.3.1. Client
Inputs:
o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes)
o Master Salt: 0x9e7ca92223786340 (8 bytes)
o Sender ID: 0x (0 byte)
o Recipient ID: 0x01 (1 byte)
o ID Context: 0x37cbf3210017a2d3 (8 bytes)
From the previous parameters,
o info (for Sender Key): 0x85404837cbf3210017a2d30a634b657910 (17
bytes)
o info (for Recipient Key): 0x8541014837cbf3210017a2d30a634b657910
(18 bytes)
o info (for Common IV): 0x85404837cbf3210017a2d30a6249560d (16
bytes)
Outputs:
o Sender Key: 0xaf2a1300a5e95788b356336eeecd2b92 (16 bytes)
o Recipient Key: 0xe39a0c7c77b43f03b4b39ab9a268699f (16 bytes)
o Common IV: 0x2ca58fb85ff1b81c0b7181b85e (13 bytes)
C.3.2. Server
Inputs:
o Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes)
o Master Salt: 0x9e7ca92223786340 (8 bytes)
o Sender ID: 0x01 (1 byte)
o Recipient ID: 0x (0 byte)
o ID Context: 0x37cbf3210017a2d3 (8 bytes)
From the previous parameters,
o info (for Sender Key): 0x8541014837cbf3210017a2d30a634b657910 (18
bytes)
o info (for Recipient Key): 0x85404837cbf3210017a2d30a634b657910 (17
bytes)
o info (for Common IV): 0x85404837cbf3210017a2d30a6249560d (16
bytes)
Outputs:
o Sender Key: 0xe39a0c7c77b43f03b4b39ab9a268699f (16 bytes)
o Recipient Key: 0xaf2a1300a5e95788b356336eeecd2b92 (16 bytes)
o Common IV: 0x2ca58fb85ff1b81c0b7181b85e (13 bytes)
C.4. Test Vector 4: OSCORE Request, Client
This section contains a test vector for an OSCORE protected CoAP GET This section contains a test vector for an OSCORE protected CoAP GET
request using the security context derived in Appendix C.1. The request using the security context derived in Appendix C.1. The
unprotected request only contains the Uri-Path option. unprotected request only contains the Uri-Path and Uri-Host options.
Unprotected CoAP request: Unprotected CoAP request:
0x440149c60000f2a7396c6f63616c686f737483747631 (22 bytes) 0x44015d1f00003974396c6f63616c686f737483747631 (22 bytes)
Common Context: Common Context:
o AEAD Algorithm: 10 (AES-CCM-16-64-128) o AEAD Algorithm: 10 (AES-CCM-16-64-128)
o Key Derivation Function: HKDF SHA-256 o Key Derivation Function: HKDF SHA-256
o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) o Common IV: 0x4622d4dd6d944168eefb54987c (13 bytes)
Sender Context: Sender Context:
o Sender ID: 0x00 (1 byte) o Sender ID: 0x (0 byte)
o Sender Key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) o Sender Key: 0xf0910ed7295e6ad4b54fc793154302ff (16 bytes)
o Sender Sequence Number: 20
The following COSE and cryptographic parameters are derived:
o Partial IV: 0x14 (1 byte)
o kid: 0x (0 byte)
o external_aad: 0x8501810a40411440 (8 bytes)
o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes)
o plaintext: 0x01b3747631 (5 bytes)
o encryption key: 0xf0910ed7295e6ad4b54fc793154302ff (16 bytes)
o nonce: 0x4622d4dd6d944168eefb549868 (13 bytes)
From the previous parameter, the following is derived:
o OSCORE option value: 0x0914 (2 bytes)
o ciphertext: 0x612f1092f1776f1c1668b3825e (13 bytes)
From there:
o Protected CoAP request (OSCORE message): 0x44025d1f00003974396c6f6
3616c686f7374620914ff612f1092f1776f1c1668b3825e (35 bytes)
C.5. Test Vector 5: OSCORE Request, Client
This section contains a test vector for an OSCORE protected CoAP GET
request using the security context derived in Appendix C.2. The
unprotected request only contains the Uri-Path and Uri-Host options.
Unprotected CoAP request:
0x440171c30000b932396c6f63616c686f737483747631 (22 bytes)
Common Context:
o AEAD Algorithm: 10 (AES-CCM-16-64-128)
o Key Derivation Function: HKDF SHA-256
o Common IV: 0xbe35ae297d2dace910c52e99f9 (13 bytes)
Sender Context:
o Sender ID: 0x00 (1 bytes)
o Sender Key: 0x321b26943253c7ffb6003b0b64d74041 (16 bytes)
o Sender Sequence Number: 20 o Sender Sequence Number: 20
The following COSE and cryptographic parameters are derived: The following COSE and cryptographic parameters are derived:
o Partial IV: 0x14 (1 byte) o Partial IV: 0x14 (1 byte)
o kid: 0x00 (1 byte) o kid: 0x00 (1 byte)
o external_aad: 0x8501810a4100411440 (9 bytes) o external_aad: 0x8501810a4100411440 (9 bytes)
o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes) o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes)
o plaintext: 0x01b3747631 (5 bytes) o plaintext: 0x01b3747631 (5 bytes)
o encryption key: 0xf8f3b887436285ed5a66f6026ac2cdc1 (16 bytes) o encryption key: 0x321b26943253c7ffb6003b0b64d74041 (16 bytes)
o nonce: 0xd0a1949aa253278f34c528d2d8 (13 bytes) o nonce: 0xbf35ae297d2dace910c52e99ed (13 bytes)
From the previous parameter, the following is derived: From the previous parameter, the following is derived:
o OSCORE option value: 0x091400 (3 bytes) o OSCORE option value: 0x091400 (3 bytes)
o ciphertext: 0x55b3710d47c611cd3924838a44 (13 bytes) o ciphertext: 0x4ed339a5a379b0b8bc731fffb0 (13 bytes)
From there: From there:
o Protected CoAP request (OSCORE message): 0x44026dd30000acc5396c6f6 o Protected CoAP request (OSCORE message): 0x440271c30000b932396c6f6
3616c686f7374d305091400ff55b3710d47c611cd3924838a44 (37 bytes) 3616c686f737463091400ff4ed339a5a379b0b8bc731fffb0 (36 bytes)
C.4. Test Vector 4: OSCORE Request, Client C.6. Test Vector 6: OSCORE Request, Client
This section contains a test vector for an OSCORE protected CoAP GET This section contains a test vector for an OSCORE protected CoAP GET
request using the security context derived in Appendix C.2. The request carrying the ID Context in the message, using the security
unprotected request only contains the Uri-Path option. context derived in Appendix C.3. The unprotected request only
contains the Uri-Path and Uri-Host options.
Unprotected CoAP request: Unprotected CoAP request:
0x440149c60000f2a7396c6f63616c686f737483747631 (22 bytes) 0x44012f8eef9bbf7a396c6f63616c686f737483747631 (22 bytes)
Common Context: Common Context:
o AEAD Algorithm: 10 (AES-CCM-16-64-128) o AEAD Algorithm: 10 (AES-CCM-16-64-128)
o Key Derivation Function: HKDF SHA-256 o Key Derivation Function: HKDF SHA-256
o Common IV: 0x01727733ab49ead385b18f7d91 (13 bytes) o Common IV: 0x2ca58fb85ff1b81c0b7181b85e (13 bytes)
o ID Context: 0x37cbf3210017a2d3 (8 bytes)
Sender Context: Sender Context:
o Sender ID: 0x (0 bytes) o Sender ID: 0x (0 bytes)
o Sender Key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) o Sender Key: 0xaf2a1300a5e95788b356336eeecd2b92 (16 bytes)
o Sender Sequence Number: 20 o Sender Sequence Number: 20
The following COSE and cryptographic parameters are derived: The following COSE and cryptographic parameters are derived:
o Partial IV: 0x14 (1 byte) o Partial IV: 0x14 (1 byte)
o kid: 0x (0 byte) o kid: 0x (0 byte)
o kid context: 0x37cbf3210017a2d3 (8 bytes)
o external_aad: 0x8501810a40411440 (8 bytes) o external_aad: 0x8501810a40411440 (8 bytes)
o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes) o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes)
o plaintext: 0x01b3747631 (5 bytes) o plaintext: 0x01b3747631 (5 bytes)
o encryption key: 0x7230aab3b549d94c9224aacc744e93ab (16 bytes) o encryption key: 0xaf2a1300a5e95788b356336eeecd2b92 (16 bytes)
o nonce: 0x01727733ab49ead385b18f7d85 (13 bytes) o nonce: 0x2ca58fb85ff1b81c0b7181b84a (13 bytes)
From the previous parameter, the following is derived: From the previous parameter, the following is derived:
o OSCORE option value: 0x0914 (2 bytes) o OSCORE option value: 0x19140837cbf3210017a2d3 (11 bytes)
o ciphertext: 0x6be9214aad448260ff1be1f594 (13 bytes) o ciphertext: 0x72cd7273fd331ac45cffbe55c3 (13 bytes)
From there: From there:
o Protected CoAP request (OSCORE message): 0x44023bfc000066ef396c6f6 o Protected CoAP request (OSCORE message): 0x44022f8eef9bbf7a396c6f6
3616c686f7374d2050914ff6be9214aad448260ff1be1f594 (36 bytes) 3616c686f73746b19140837cbf3210017a2d3ff4ed339a5a379b0b8bc731fffb0
(44 bytes)
C.5. Test Vector 5: OSCORE Response, Server C.7. Test Vector 7: OSCORE Response, Server
This section contains a test vector for an OSCORE protected 2.05 This section contains a test vector for an OSCORE protected 2.05
Content response to the request in Appendix C.3. The unprotected Content response to the request in Appendix C.4. The unprotected
response has payload "Hello World!" and no options. The protected response has payload "Hello World!" and no options. The protected
response does not contain a kid nor a Partial IV. Note that some response does not contain a kid nor a Partial IV. Note that some
parameters are derived from the request. parameters are derived from the request.
Unprotected CoAP response: Unprotected CoAP response:
0x644549c60000f2a7ff48656c6c6f20576f726c6421 (21 bytes) 0x64455d1f00003974ff48656c6c6f20576f726c6421 (21 bytes)
Common Context: Common Context:
o AEAD Algorithm: 10 (AES-CCM-16-64-128) o AEAD Algorithm: 10 (AES-CCM-16-64-128)
o Key Derivation Function: HKDF SHA-256 o Key Derivation Function: HKDF SHA-256
o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) o Common IV: 0x4622d4dd6d944168eefb54987c (13 bytes)
Sender Context: Sender Context:
o Sender ID: 0x01 (1 byte) o Sender ID: 0x01 (1 byte)
o Sender Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) o Sender Key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes)
o Sender Sequence Number: 0 o Sender Sequence Number: 0
The following COSE and cryptographic parameters are derived: The following COSE and cryptographic parameters are derived:
o external_aad: 0x8501810a4100411440 (9 bytes) o external_aad: 0x8501810a40411440 (8 bytes)
o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes)
o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes)
o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes) o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes)
o encryption key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) o encryption key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes)
o nonce: 0xd0a1949aa253278f34c528d2d8 (13 bytes) o nonce: 0x4622d4dd6d944168eefb549868 (13 bytes)
From the previous parameter, the following is derived: From the previous parameter, the following is derived:
o OSCORE option value: 0x (0 bytes) o OSCORE option value: 0x (0 bytes)
o ciphertext: 0xe4e8c28c41c8f31ca56eec24f6c71d94eacbcdffdc6d (22 o ciphertext: 0xdbaad1e9a7e7b2a813d3c31524378303cdafae119106 (22
bytes) bytes)
From there: From there:
o Protected CoAP response (OSCORE message): 0x64446dd30000acc5d008ff o Protected CoAP response (OSCORE message):
e4e8c28c41c8f31ca56eec24f6c71d94eacbcdffdc6d (33 bytes) 0x64445d1f0000397490ffdbaad1e9a7e7b2a813d3c31524378303cdafae119106
(32 bytes)
C.6. Test Vector 6: OSCORE Response with Partial IV, Server C.8. Test Vector 8: OSCORE Response with Partial IV, Server
This section contains a test vector for an OSCORE protected 2.05 This section contains a test vector for an OSCORE protected 2.05
Content response to the request in Appendix C.3. The unprotected Content response to the request in Appendix C.4. The unprotected
response has payload "Hello World!" and no options. The protected response has payload "Hello World!" and no options. The protected
response does not contain a kid, but contains a Partial IV. Note response does not contain a kid, but contains a Partial IV. Note
that some parameters are derived from the request. that some parameters are derived from the request.
Unprotected CoAP response: Unprotected CoAP response:
0x644549c60000f2a7ff48656c6c6f20576f726c6421 (21 bytes) 0x64455d1f00003974ff48656c6c6f20576f726c6421 (21 bytes)
Common Context: Common Context:
o AEAD Algorithm: 10 (AES-CCM-16-64-128) o AEAD Algorithm: 10 (AES-CCM-16-64-128)
o Key Derivation Function: HKDF SHA-256 o Key Derivation Function: HKDF SHA-256
o Common IV: 0xd1a1949aa253278f34c528d2cc (13 bytes) o Common IV: 0x4622d4dd6d944168eefb54987c (13 bytes)
Sender Context: Sender Context:
o Sender ID: 0x01 (1 byte) o Sender ID: 0x01 (1 byte)
o Sender Key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) o Sender Key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes)
o Sender Sequence Number: 0 o Sender Sequence Number: 0
The following COSE and cryptographic parameters are derived: The following COSE and cryptographic parameters are derived:
o Partial IV: 0x00 (1 byte) o Partial IV: 0x00 (1 byte)
o external_aad: 0x8501810a4100411440 (9 bytes) o external_aad: 0x8501810a40411440 (8 bytes)
o AAD: 0x8368456e63727970743040498501810a4100411440 (21 bytes) o AAD: 0x8368456e63727970743040488501810a40411440 (20 bytes)
o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes) o plaintext: 0x45ff48656c6c6f20576f726c6421 (14 bytes)
o encryption key: 0xd904cb101f7341c3f4c56c300fa69941 (16 bytes) o encryption key: 0xffb14e093c94c9cac9471648b4f98710 (16 bytes)
o nonce: 0xd0a1949aa253278e34c528d2cc (13 bytes) o nonce: 0x4722d4dd6d944169eefb54987c (13 bytes)
From the previous parameter, the following is derived: From the previous parameter, the following is derived:
o OSCORE option value: 0x0100 (2 bytes) o OSCORE option value: 0x0100 (2 bytes)
o ciphertext: 0xa7e3ca27f221f453c0ba68c350bf652ea096b328a1bf (22 o ciphertext: 0x4d4c13669384b67354b2b6175ff4b8658c666a6cf88e (22
bytes) bytes)
From there: From there:
o Protected CoAP response (OSCORE message): 0x64442b130000b29ed20801 o Protected CoAP response (OSCORE message): 0x64445d1f00003974920100
00ffa7e3ca27f221f453c0ba68c350bf652ea096b328a1bf (35 bytes) ff4d4c13669384b67354b2b6175ff4b8658c666a6cf88e (34 bytes)
Appendix D. Overview of Security Properties Appendix D. Overview of Security Properties
D.1. Supporting Proxy Operations D.1. Supporting Proxy Operations
CoAP is designed to work with intermediaries reading and/or changing CoAP is designed to work with intermediaries reading and/or changing
CoAP message fields and performing supporting operations in CoAP message fields to perform supporting operations in constrained
constrained environments, e.g. forwarding and cross-protocol environments, e.g. forwarding and cross-protocol translations.
translations.
Securing CoAP on transport layer protects the entire message between Securing CoAP on transport layer protects the entire message between
the endpoints in which case CoAP proxy operations are not possible. the endpoints in which case CoAP proxy operations are not possible.
In order to enable proxy operations, security on transport layer In order to enable proxy operations, security on transport layer
needs to be terminated at the proxy in which case the CoAP message in needs to be terminated at the proxy in which case the CoAP message in
its entirety is unprotected in the proxy. its entirety is unprotected in the proxy.
Requirements for CoAP end-to-end security are specified in Requirements for CoAP end-to-end security are specified in
[I-D.hartke-core-e2e-security-reqs]. The client and server are [I-D.hartke-core-e2e-security-reqs]. The client and server are
assumed to be honest, but proxies and gateways are only trusted to assumed to be honest, but proxies and gateways are only trusted to
skipping to change at page 66, line 50 skipping to change at page 72, line 17
required for proxy operations to be available to the proxy while required for proxy operations to be available to the proxy while
message fields intended for the other endpoint remain protected. In message fields intended for the other endpoint remain protected. In
the remainder of this section we analyze how OSCORE protects the the remainder of this section we analyze how OSCORE protects the
protected message fields and the consequences of message fields protected message fields and the consequences of message fields
intended for proxy operation being unprotected. intended for proxy operation being unprotected.
D.2. Protected Message Fields D.2. Protected Message Fields
Protected message fields are included in the Plaintext (Section 5.3) Protected message fields are included in the Plaintext (Section 5.3)
and the Additional Authenticated Data (Section 5.4) of the and the Additional Authenticated Data (Section 5.4) of the
COSE_Encrypt0 object using an AEAD algorithm. COSE_Encrypt0 object and encrypted using an AEAD algorithm.
OSCORE depends on a pre-established random Master Secret OSCORE depends on a pre-established random Master Secret
(Section 12.3) which can be used to derive keys, and a construction (Section 12.3) used to derive encryption keys, and a construction for
for making (key, nonce) pairs unique (Appendix D.3). Assuming this making (key, nonce) pairs unique (Appendix D.3). Assuming this is
is true, and the keys are used for no more data than indicated in true, and the keys are used for no more data than indicated in
Section 7.2, OSCORE should provide the following guarantees: Section 7.2.1, OSCORE should provide the following guarantees:
o Confidentiality: An attacker should not be able to determine the o Confidentiality: An attacker should not be able to determine the
plaintext contents of a given OSCORE message or determine that plaintext contents of a given OSCORE message or determine that
different plaintexts are related (Section 5.3). different plaintexts are related (Section 5.3).
o Integrity: An attacker should not be able to craft a new OSCORE o Integrity: An attacker should not be able to craft a new OSCORE
message with protected message fields different from an existing message with protected message fields different from an existing
OSCORE message which will be accepted by the receiver. OSCORE message which will be accepted by the receiver.
o Request-response binding: An attacker should not be able to make a o Request-response binding: An attacker should not be able to make a
client match a response to the wrong request. client match a response to the wrong request.
o Non-replayability: An attacker should not be able to cause the o Non-replayability: An attacker should not be able to cause the
receiver to accept a message which it has already accepted. receiver to accept a message which it has previously received and
accepted.
In the above, the attacker is anyone except the endpoints, e.g. a In the above, the attacker is anyone except the endpoints, e.g. a
compromised intermediary. Informally, OSCORE provides these compromised intermediary. Informally, OSCORE provides these
properties by AEAD-protecting the plaintext with a strong key and properties by AEAD-protecting the plaintext with a strong key and
uniqueness of (key, nonce) pairs. AEAD encryption [RFC5116] provides uniqueness of (key, nonce) pairs. AEAD encryption [RFC5116] provides
confidentiality and integrity for the data. Response-request binding confidentiality and integrity for the data. Response-request binding
is provided by including the kid and Partial IV of the request in the is provided by including the kid and Partial IV of the request in the
AAD of the response. Non-replayability of requests and notifications AAD of the response. Non-replayability of requests and notifications
is provided by using unique (key, nonce) pairs and a replay is provided by using unique (key, nonce) pairs and a replay
protection mechanism (application dependent, see Section 7.4). protection mechanism (application dependent, see Section 7.4).
skipping to change at page 67, line 46 skipping to change at page 73, line 12
on observing the length and timing of encrypted packets. OSCORE does on observing the length and timing of encrypted packets. OSCORE does
not provide any specific defenses against this form of attack but the not provide any specific defenses against this form of attack but the
application may use a padding mechanism to prevent an attacker from application may use a padding mechanism to prevent an attacker from
directly determine the length of the padding. However, information directly determine the length of the padding. However, information
about padding may still be revealed by side-channel attacks observing about padding may still be revealed by side-channel attacks observing
differences in timing. differences in timing.
D.3. Uniqueness of (key, nonce) D.3. Uniqueness of (key, nonce)
In this section we show that (key, nonce) pairs are unique as long as In this section we show that (key, nonce) pairs are unique as long as
the requirements Section 3.3 and Section 7.2 are followed. the requirements in Sections 3.3 and 7.2.1 are followed.
Fix a security context and an endpoint, called the encrypting Fix a Common Context (Section 3.1) and an endpoint, called the
endpoint. Endpoints may alternate between client and server roles, encrypting endpoint. An endpoint may alternate between client and
but each endpoint encrypts with the Sender Key of its Sender Context. server roles, but each endpoint always encrypts with the Sender Key
Sender Keys are (stochastically) unique since they are derived with of its Sender Context. Sender Keys are (stochastically) unique since
HKDF from unique Sender IDs, so messages encrypted by different they are derived with HKDF using unique Sender IDs, so messages
endpoints use different keys. It remains to prove that the nonces encrypted by different endpoints use different keys. It remains to
used by the fixed endpoint are unique. prove that the nonces used by the fixed endpoint are unique.
Since the Common IV is fixed, the nonces are determined by a Partial Since the Common IV is fixed, the nonces are determined by a Partial
IV (PIV) and the Sender ID of the endpoint generating that Partial IV IV (PIV) and the Sender ID of the endpoint generating that Partial IV
(ID_PIV). The nonce construction (Section 5.2) with the size of the (ID_PIV). The nonce construction (Section 5.2) with the size of the
ID_PIV (S) creates unique nonces for different (ID_PIV, PIV) pairs. ID_PIV (S) creates unique nonces for different (ID_PIV, PIV) pairs.
There are two cases:
For requests and responses with Partial IV (e.g. Observe A. For requests, and responses with Partial IV (e.g. Observe
notifications): notifications):
o ID_PIV = Sender ID of the encrypting endpoint o ID_PIV = Sender ID of the encrypting endpoint
o PIV = current Partial IV of the encrypting endpoint o PIV = current Partial IV of the encrypting endpoint
Since the encrypting endpoint steps the Partial IV for each use, the Since the encrypting endpoint steps the Partial IV for each use, the
nonces used are all unique as long as the number of encrypted nonces used in case A are all unique as long as the number of
messages is kept within the required range (Section 7.2). encrypted messages is kept within the required range (Section 7.2.1).
For responses without Partial IV (i.e. single response to a request): B. For responses without Partial IV (subset of cases with single
response to a request):
o ID_PIV = Sender ID of the endpoint generating the request o ID_PIV = Sender ID of the endpoint generating the request
o PIV = Partial IV of the request o PIV = Partial IV of the request
Since the Sender IDs are unique, ID_PIV is different from the Sender Since the Sender IDs are unique, ID_PIV is different from the Sender
ID of the encrypting endpoint. Therefore, the nonce is different ID of the encrypting endpoint. Therefore, the nonces in case B are
compared to nonces where the encrypting endpoint generated the different compared to nonces in case A, where the encrypting endpoint
Partial IV. Since the Partial IV of the request is verified for generated the Partial IV. Since the Partial IV of the request is
replay (Section 7.4) associated to this Recipient Context, PIV is verified for replay (Section 7.4) associated to this Recipient
unique for this ID_PIV. Context, PIV is unique for this ID_PIV, which makes all nonces in
case B distinct.
The argumentation also holds for group communication as specified in
[RFC7390] (see [I-D.ietf-core-oscore-groupcomm]).
D.4. Unprotected Message Fields D.4. Unprotected Message Fields
This section lists and discusses issues with unprotected message This section lists and discusses issues with unprotected message
fields. fields.
D.4.1. CoAP Code D.4.1. CoAP Header Fields
The CoAP Code of an OSCORE message is POST or FETCH for requests and
with corresponding response codes. Since the use of Observe is
indicated with the Outer Observe option, no additional information is
revealed by having a special codes for Observe messages. A change of
code does not affect the method of the end-to-end message but may be
a denial service attack caused by error in the OSCORE processing.
Other aspects of Observe are discussed in Appendix D.4.3.
D.4.2. CoAP Header Fields
o Version. The CoAP version [RFC7252] is not expected to be o Version. The CoAP version [RFC7252] is not expected to be
sensitive to disclose. Currently there is only one CoAP version sensitive to disclose. Currently there is only one CoAP version
defined. A change of this parameter is potentially a denial of defined. A change of this parameter is potentially a denial-of-
service attack. Future versions of CoAP need to analyze attacks service attack. Future versions of CoAP need to analyze attacks
to OSCORE protected messages due to an adversary changing the CoAP to OSCORE protected messages due to an adversary changing the CoAP
version. version.
o Token/Token Length. The Token field is a client-local identifier o Token/Token Length. The Token field is a client-local identifier
for differentiating between concurrent requests [RFC7252]. An for differentiating between concurrent requests [RFC7252]. An
eavesdropper reading the token can match requests to responses eavesdropper reading the token can match requests to responses
which can be used in traffic analysis. CoAP proxies are allowed which can be used in traffic analysis. In particular this is true
to change Token and Token Length between UDP hops. However, for notifications, where multiple responses are matched with one
modifications of Token and Token Length during a UDP hop may request. CoAP proxies are allowed to change Token and Token
become a denial of service attack, since it may prevent the client Length between UDP hops. However, modifications of Token and
to identify to which request the response belongs or to find the Token Length during a UDP hop may become a denial-of-service
correct information to verify integrity of the response. attack, since it may prevent the client to identify to which
request the response belongs or to find the correct information to
verify integrity of the response.
o Code. The Outer CoAP Code of an OSCORE message is POST or FETCH
for requests with corresponding response codes. The use of FETCH
reveals no more than what is revealed by the Outer Observe option.
Changing the Outer Code may be a denial-of-service attack by
causing errors in the proxy processing.
o Type/Message ID. The Type/Message ID fields [RFC7252] reveal o Type/Message ID. The Type/Message ID fields [RFC7252] reveal
information about the UDP transport binding, e.g. an eavesdropper information about the UDP transport binding, e.g. an eavesdropper
reading the Type or Message ID gain information about how UDP reading the Type or Message ID gain information about how UDP
messages are related to each other. CoAP proxies are allowed to messages are related to each other. CoAP proxies are allowed to
change Type and Message ID. These message fields are not present change Type and Message ID. These message fields are not present
in CoAP over TCP, and does not impact the request/response in CoAP over TCP [RFC8323], and does not impact the request/
message. A change of these fields in a UDP hop is a denial of response message. A change of these fields in a UDP hop is a
service attack similar to changing UDP header fields. denial-of-service attack. By sending an ACK, an attacker can make
the endpoint believe that the other endpoint received the previous
message. By sending a RST, an attacker may be able to cancel an
observation, make one endpoint believe the other endpoint is
alive, or make one endpoint endpoint believe that the other
endpoint is missing some context. By changing a NON to a CON, the
attacker can cause the receiving endpoint to respond to messages
for which no response was requested.
o Length. This field contain the length of the message [RFC8323] o Length. This field contain the length of the message [RFC8323]
which may be used for traffic analysis. These message fields are which may be used for traffic analysis. These message fields are
not present in CoAP over UDP, and does not impact the request/ not present in CoAP over UDP, and does not impact the request/
response message. A change of Length is a denial of service response message. A change of Length is a denial-of-service
attack similar to changing TCP header fields. attack similar to changing TCP header fields.
D.4.3. CoAP Options D.4.2. CoAP Options
o Max-Age. The Outer Max-Age is set to zero to avoid unnecessary o Max-Age. The Outer Max-Age is set to zero to avoid unnecessary
caching of OSCORE error responses. Changing this value thus may caching of OSCORE error responses. Changing this value thus may
cause unnecessary caching. No additional information is carried cause unnecessary caching. No additional information is carried
with this option. with this option.
o Proxy-Uri/Proxy-Scheme/Uri-Host/Uri-Port. With OSCORE, the Proxy- o Proxy-Uri/Proxy-Scheme. These options are used in forward proxy
Uri option does not contain the Uri-Path/Uri-Query parts of the deployments. With OSCORE, the Proxy-Uri option does not contain
URI. Proxy-Uri/Proxy-Scheme/Uri-Host/Uri-Port cannot be integrity the Uri-Path/Uri-Query parts of the URI. The other parts of
protected since they are allowed to be changed by a forward proxy. Proxy-Uri cannot be protected since they are allowed to be changed
by a forward proxy. The server can verify what scheme is used in
the last hop, but not what was requested by the client or what was
used in previous hops.
Depending on content, the Uri-Host may either reveal information o Uri-Host/Uri-Port. In forward proxy deployments, the Uri-Host/
equivalent to that of the IP address or more privacy-sensitive Uri-Port may be changed by an adversary, and the application needs
information, which is discouraged in Section 4.1.3.2. to handle the consequences of that (see Section 4.1.3.2). The
Uri-Host may either be omitted, reveal information equivalent to
that of the IP address or more privacy-sensitive information,
which is discouraged.
o Observe. The Outer Observe option is intended for an OSCORE- o Observe. The Outer Observe option is intended for an OSCORE-
unaware proxy to support forwarding of Observe messages. Removing unaware proxy to support forwarding of Observe messages, but is
this option in the request turns the notification request into a ignored by the endpoints since the Inner Observe determines the
normal request, which is allowed for a proxy and server and processing in the endpoints. Since the Partial IV provides
understood by the client but changes the performed operation from absolute ordering of notifications it is not possible for an
a request for notifications to a plain request, but the client intermediary to spoof reordering (see Section 4.1.3.5). The size
cannot tell what party removed the option. and distributions of notifications over time may reveal
information about the content or nature of the notifications.
Removing this option in the response may lead to notifications not
being forwarded or cause a denial of service. The Outer option value
indicates a relative order of notifications as read and written by
the proxy and a change of that may affect proxy operations and
potentially lead to denial of service. Since OSCORE provides
absolute ordering of notifications it is not possible for an
intermediary to spoof reordering (see Section 4.1.3.4). The size and
distributions of notifications over time may reveal information about
the content or nature of the notifications.
o Block1/Block2/Size1/Size2. The Outer Block options enables o Block1/Block2/Size1/Size2. The Outer Block options enables
fragmentation of OSCORE messages in addition to segmentation fragmentation of OSCORE messages in addition to segmentation
performed by the Inner Block options. The presence of these performed by the Inner Block options. The presence of these
options indicates a large message being sent and the message size options indicates a large message being sent and the message size
can be estimated and used for traffic analysis. Manipulating can be estimated and used for traffic analysis. Manipulating
these options is a potential denial of service attack, e.g. these options is a potential denial-of-service attack, e.g.
injection of alleged Block fragments. The specification of injection of alleged Block fragments. The specification of a
MAX_UNFRAGMENTED_SIZE (Section 4.1.3.3.2), at which the messages maximum size of message, MAX_UNFRAGMENTED_SIZE
will be dropped, is intended as one measure to mitigate this kind (Section 4.1.3.4.2), above which messages will be dropped, is
of attack. intended as one measure to mitigate this kind of attack.
o No-Response. The Outer No-Response option is used to support o No-Response. The Outer No-Response option is used to support
proxy functionality, specifically to avoid error transmissions proxy functionality, specifically to avoid error transmissions
from proxies to clients, and to avoid bandwidth reduction to from proxies to clients, and to avoid bandwidth reduction to
servers by proxies applying congestion control when not receiving servers by proxies applying congestion control when not receiving
responses. Modifying or introducing this option is a potential responses. Modifying or introducing this option is a potential
denial of service attack against the proxy operations, but since denial-of-service attack against the proxy operations, but since
the option has an Inner value its use can be securely agreed the option has an Inner value its use can be securely agreed
between the endpoints. The presence of this option is not between the endpoints. The presence of this option is not
expected to reveal any sensitive information about the message expected to reveal any sensitive information about the message
exchange. exchange.
o OSCORE. The OSCORE option contains information about the o OSCORE. The OSCORE option contains information about the
compressed COSE header. A change of this field may result in not compressed COSE header. Changing this field may cause OSCORE
being able to verify the OSCORE message. verification to fail.
D.4.3. Error and Signaling Messages
Error messages occurring during CoAP processing are protected end-to-
end. Error messages occurring during OSCORE processing are not
always possible to protect, e.g. if the receiving endpoint cannot
locate the right security context. For this setting, unprotected
error messages are allowed as specified to prevent extensive
retransmissions. Those error messages can be spoofed or manipulated,
which is a potential denial-of-service attack.
Signaling messages used in CoAP over TCP [RFC8323] are intended to be
hop-by-hop; spoofing signaling messages can be used as a denial-of-
service attack of a TCP connection.
D.4.4. HTTP Message Fields D.4.4. HTTP Message Fields
In contrast to CoAP, where OSCORE does not protect header fields to In contrast to CoAP, where OSCORE does not protect header fields to
enable CoAP-CoAP proxy operations, the use of OSCORE with HTTP is enable CoAP-CoAP proxy operations, the use of OSCORE with HTTP is
restricted to transporting a protected CoAP message over an HTTP hop. restricted to transporting a protected CoAP message over an HTTP hop.
Any unprotected HTTP message fields may reveal information about the Any unprotected HTTP message fields may reveal information about the
transport of the OSCORE message and enable various denial of service transport of the OSCORE message and enable various denial-of-service
attacks. It is recommended to additionally use TLS [RFC5246] for attacks. It is recommended to additionally use TLS [RFC5246] for
HTTP hops, which enables encryption and integrity protection of HTTP hops, which enables encryption and integrity protection of
headers, but still leaves some information for traffic analysis. headers, but still leaves some information for traffic analysis.
Appendix E. CDDL Summary Appendix E. CDDL Summary
Data structure definitions in the present specification employ the Data structure definitions in the present specification employ the
CDDL language for conciseness and precision. CDDL is defined in CDDL language for conciseness and precision. CDDL is defined in
[I-D.ietf-cbor-cddl], which at the time of writing this appendix is [I-D.ietf-cbor-cddl], which at the time of writing this appendix is
in the process of completion. As the document is not yet available in the process of completion. As the document is not yet available
skipping to change at page 72, line 9 skipping to change at page 77, line 37
array description contain elements that correspond one-to-one to array description contain elements that correspond one-to-one to
the sequence of entries given. Each entry of an array description the sequence of entries given. Each entry of an array description
is of the form "name : type", where "name" is the name given to is of the form "name : type", where "name" is the name given to
the entry and "type" is the type of the array element the entry and "type" is the type of the array element
corresponding to this entry. corresponding to this entry.
Acknowledgments Acknowledgments
The following individuals provided input to this document: Christian The following individuals provided input to this document: Christian
Amsuess, Tobias Andersson, Carsten Bormann, Joakim Brorsson, Esko Amsuess, Tobias Andersson, Carsten Bormann, Joakim Brorsson, Esko
Dijk, Thomas Fossati, Martin Gunnarsson, Klaus Hartke, Jim Schaad, Dijk, Thomas Fossati, Martin Gunnarsson, Klaus Hartke, Michael
Peter van der Stok, Dave Thaler, Marco Tiloca, William Vignat, and Richardson, Jim Schaad, Peter van der Stok, Dave Thaler, Marco
Malisa Vucinic. Tiloca, William Vignat, and Malisa Vucinic.
Ludwig Seitz and Goeran Selander worked on this document as part of Ludwig Seitz and Goeran Selander worked on this document as part of
the CelticPlus project CyberWI, with funding from Vinnova. the CelticPlus project CyberWI, with funding from Vinnova.
Authors' Addresses Authors' Addresses
Goeran Selander Goeran Selander
Ericsson AB Ericsson AB
Email: goran.selander@ericsson.com Email: goran.selander@ericsson.com
 End of changes. 264 change blocks. 
772 lines changed or deleted 1026 lines changed or added

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