draft-ietf-core-object-security-02.txt   draft-ietf-core-object-security-03.txt 
CoRE Working Group G. Selander CoRE Working Group G. Selander
Internet-Draft J. Mattsson Internet-Draft J. Mattsson
Intended status: Standards Track F. Palombini Intended status: Standards Track F. Palombini
Expires: September 14, 2017 Ericsson AB Expires: November 4, 2017 Ericsson AB
L. Seitz L. Seitz
SICS Swedish ICT SICS Swedish ICT
March 13, 2017 May 03, 2017
Object Security of CoAP (OSCOAP) Object Security of CoAP (OSCOAP)
draft-ietf-core-object-security-02 draft-ietf-core-object-security-03
Abstract Abstract
This document defines Object Security of CoAP (OSCOAP), a method for This document defines Object Security of CoAP (OSCOAP), a method for
application layer protection of the Constrained Application Protocol application layer protection of the Constrained Application Protocol
(CoAP), using the CBOR Object Signing and Encryption (COSE). OSCOAP (CoAP), using the CBOR Object Signing and Encryption (COSE). OSCOAP
provides end-to-end encryption, integrity and replay protection to provides end-to-end encryption, integrity and replay protection to
CoAP payload, options, and header fields, as well as a secure message CoAP payload, options, and header fields, as well as a secure message
binding. OSCOAP is designed for constrained nodes and networks and binding. OSCOAP is designed for constrained nodes and networks and
can be used across intermediaries and over any layer. The use of can be used across intermediaries and over any layer. The use of
skipping to change at page 1, line 41 skipping to change at page 1, line 41
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 http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 14, 2017. This Internet-Draft will expire on November 4, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2017 IETF Trust and the persons identified as the Copyright (c) 2017 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 19 skipping to change at page 2, line 19
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
2. The Object-Security Option . . . . . . . . . . . . . . . . . 5 2. The Object-Security Option . . . . . . . . . . . . . . . . . 5
3. The Security Context . . . . . . . . . . . . . . . . . . . . 6 3. The Security Context . . . . . . . . . . . . . . . . . . . . 6
3.1. Security Context Definition . . . . . . . . . . . . . . . 6 3.1. Security Context Definition . . . . . . . . . . . . . . . 6
3.2. Derivation of Security Context Parameters . . . . . . . . 8 3.2. Derivation of Security Context Parameters . . . . . . . . 9
3.3. Requirements on the Security Context Parameters . . . . . 10 3.3. Requirements on the Security Context Parameters . . . . . 10
4. Protected CoAP Message Fields . . . . . . . . . . . . . . . . 11 4. Protected CoAP Message Fields . . . . . . . . . . . . . . . . 11
4.1. CoAP Payload . . . . . . . . . . . . . . . . . . . . . . 11 4.1. CoAP Payload . . . . . . . . . . . . . . . . . . . . . . 12
4.2. CoAP Header . . . . . . . . . . . . . . . . . . . . . . . 12 4.2. CoAP Header . . . . . . . . . . . . . . . . . . . . . . . 12
4.3. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 12 4.3. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 12
5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 17 5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 18
5.1. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 18 5.1. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 19
5.2. Additional Authenticated Data . . . . . . . . . . . . . . 19 5.2. Additional Authenticated Data . . . . . . . . . . . . . . 19
6. Sequence Numbers, Replay, Message Binding, and Freshness . . 20 6. Sequence Numbers, Replay, Message Binding, and Freshness . . 20
6.1. AEAD Nonce Uniqueness . . . . . . . . . . . . . . . . . . 20 6.1. AEAD Nonce Uniqueness . . . . . . . . . . . . . . . . . . 20
6.2. Replay Protection . . . . . . . . . . . . . . . . . . . . 20 6.2. Replay Protection . . . . . . . . . . . . . . . . . . . . 20
6.3. Sequence Number and Replay Window State . . . . . . . . . 20 6.3. Sequence Number and Replay Window State . . . . . . . . . 21
6.4. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 21 6.4. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 22
6.5. Delay and Mismatch Attacks . . . . . . . . . . . . . . . 21 6.5. Delay and Mismatch Attacks . . . . . . . . . . . . . . . 23
7. Processing . . . . . . . . . . . . . . . . . . . . . . . . . 22 7. Processing . . . . . . . . . . . . . . . . . . . . . . . . . 23
7.1. Protecting the Request . . . . . . . . . . . . . . . . . 22 7.1. Protecting the Request . . . . . . . . . . . . . . . . . 23
7.2. Verifying the Request . . . . . . . . . . . . . . . . . . 22 7.2. Verifying the Request . . . . . . . . . . . . . . . . . . 23
7.3. Protecting the Response . . . . . . . . . . . . . . . . . 23 7.3. Protecting the Response . . . . . . . . . . . . . . . . . 25
7.4. Verifying the Response . . . . . . . . . . . . . . . . . 23 7.4. Verifying the Response . . . . . . . . . . . . . . . . . 25
8. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 24 8. OSCOAP Compression . . . . . . . . . . . . . . . . . . . . . 26
9. Security Considerations . . . . . . . . . . . . . . . . . . . 25 8.1. Encoding of the Object-Security Option . . . . . . . . . 27
10. Privacy Considerations . . . . . . . . . . . . . . . . . . . 27 8.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . 28
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 29
11.1. CoAP Option Numbers Registry . . . . . . . . . . . . . . 27 10. Security Considerations . . . . . . . . . . . . . . . . . . . 29
11.2. Media Type Registrations . . . . . . . . . . . . . . . . 27 11. Privacy Considerations . . . . . . . . . . . . . . . . . . . 31
11.3. CoAP Content Format Registration . . . . . . . . . . . . 28 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32
12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 29 12.1. CoAP Option Numbers Registry . . . . . . . . . . . . . . 32
13. References . . . . . . . . . . . . . . . . . . . . . . . . . 29 12.2. Media Type Registrations . . . . . . . . . . . . . . . . 32
13.1. Normative References . . . . . . . . . . . . . . . . . . 29 12.3. CoAP Content Format Registration . . . . . . . . . . . . 33
13.2. Informative References . . . . . . . . . . . . . . . . . 30 13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 34
Appendix A. OSCOAP Compression . . . . . . . . . . . . . . . . . 31 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 34
A.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 32 14.1. Normative References . . . . . . . . . . . . . . . . . . 34
14.2. Informative References . . . . . . . . . . . . . . . . . 35
Appendix B. Test Vectors . . . . . . . . . . . . . . . . . . . . 33 Appendix A. Test Vectors . . . . . . . . . . . . . . . . . . . . 36
Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 33 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 36
C.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 33 B.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 36
C.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 34 B.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 37
Appendix D. Object Security of Content (OSCON) . . . . . . . . . 36 Appendix C. Object Security of Content (OSCON) . . . . . . . . . 39
D.1. Overhead OSCON . . . . . . . . . . . . . . . . . . . . . 37 C.1. Overhead OSCON . . . . . . . . . . . . . . . . . . . . . 40
D.2. MAC Only . . . . . . . . . . . . . . . . . . . . . . . . 38 C.2. MAC Only . . . . . . . . . . . . . . . . . . . . . . . . 41
D.3. Signature Only . . . . . . . . . . . . . . . . . . . . . 38 C.3. Signature Only . . . . . . . . . . . . . . . . . . . . . 41
D.4. Authenticated Encryption with Additional Data (AEAD) . . 39 C.4. Authenticated Encryption with Additional Data (AEAD) . . 42
D.5. Symmetric Encryption with Asymmetric Signature (SEAS) . . 40 C.5. Symmetric Encryption with Asymmetric Signature (SEAS) . . 43
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 40 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 43
1. Introduction 1. Introduction
The Constrained Application Protocol (CoAP) is a web application The Constrained Application Protocol (CoAP) is a web application
protocol, designed for constrained nodes and networks [RFC7228]. protocol, designed for constrained nodes and networks [RFC7228].
CoAP specifies the use of proxies for scalability and efficiency. At CoAP specifies the use of proxies for scalability and efficiency. At
the same time CoAP [RFC7252] references DTLS [RFC6347] for security. the same time CoAP [RFC7252] references DTLS [RFC6347] for security.
Proxy operations on CoAP messages require DTLS to be terminated at Proxy operations on CoAP messages require DTLS to be terminated at
the proxy. The proxy therefore not only has access to the data the proxy. The proxy therefore not only has access to the data
required for performing the intended proxy functionality, but is also required for performing the intended proxy functionality, but is also
able to eavesdrop on, or manipulate any part of the CoAP payload and able to eavesdrop on, or manipulate any part of the CoAP payload and
metadata, in transit between client and server. The proxy can also metadata, in transit between client and server. The proxy can also
inject, delete, or reorder packages without being protected or inject, delete, or reorder packages since they are no longer
detected by DTLS. protected by DTLS.
This document defines Object Security of CoAP (OSCOAP), a data object This document defines Object Security of CoAP (OSCOAP), a data object
based security protocol, protecting CoAP message exchanges end-to- based security protocol, protecting CoAP message exchanges end-to-
end, across intermediary nodes. An analysis of end-to-end security end, across intermediary nodes. An analysis of end-to-end security
for CoAP messages through intermediary nodes is performed in for CoAP messages through intermediary nodes is performed in
[I-D.hartke-core-e2e-security-reqs], this specification addresses the [I-D.hartke-core-e2e-security-reqs], this specification addresses the
forwarding case. In addition to the core features defined in forwarding case. In addition to the core features defined in
[RFC7252], OSCOAP supports Observe [RFC7641] and Blockwise [RFC7959]. [RFC7252], OSCOAP supports Observe [RFC7641] and Blockwise [RFC7959].
OSCOAP is designed for constrained nodes and networks and provides an OSCOAP is designed for constrained nodes and networks and provides an
skipping to change at page 3, line 52 skipping to change at page 4, line 4
used, including unreliable transport [RFC7228], reliable transport used, including unreliable transport [RFC7228], reliable transport
[I-D.ietf-core-coap-tcp-tls], and non-IP transport [I-D.ietf-core-coap-tcp-tls], and non-IP transport
[I-D.bormann-6lo-coap-802-15-ie]. OSCOAP may also be used to protect [I-D.bormann-6lo-coap-802-15-ie]. OSCOAP may also be used to protect
group communication for CoAP [I-D.tiloca-core-multicast-oscoap]. The group communication for CoAP [I-D.tiloca-core-multicast-oscoap]. The
use of OSCOAP does not affect the URI scheme and OSCOAP can therefore use of OSCOAP does not affect the URI scheme and OSCOAP can therefore
be used with any URI scheme defined for CoAP. The application be used with any URI scheme defined for CoAP. The application
decides the conditions for which OSCOAP is required. decides the conditions for which OSCOAP is required.
OSCOAP builds on CBOR Object Signing and Encryption (COSE) OSCOAP builds on CBOR Object Signing and Encryption (COSE)
[I-D.ietf-cose-msg], providing end-to-end encryption, integrity, [I-D.ietf-cose-msg], providing end-to-end encryption, integrity,
replay protection, and secure message binding. The use of OSCOAP is replay protection, and secure message binding. A compressed version
signaled with the CoAP option Object-Security, defined in Section 2. of COSE is used, see Section 8. The use of OSCOAP is signaled with
OSCOAP provides protection of CoAP payload, certain options, and the CoAP option Object-Security, defined in Section 2. OSCOAP
header fields. The solution transforms an unprotected CoAP message provides protection of CoAP payload, certain options, and header
into a protected CoAP message in the following way: the unprotected fields. The solution transforms an unprotected CoAP message into a
CoAP message is protected by including payload (if present), certain protected CoAP message in the following way: the unprotected CoAP
message is protected by including payload (if present), certain
options, and header fields in a COSE object. The message fields that options, and header fields in a COSE object. The message fields that
have been encrypted are removed from the message whereas the Object- have been encrypted are removed from the message whereas the Object-
Security option and the COSE object are added, see Figure 1. Security option and the compressed COSE object are added, see
Figure 1.
Client Server Client Server
| request: | | request: |
| GET example.com | | GET example.com |
| [Header, Token, Options:{..., | | [Header, Token, Options:{..., |
| Object-Security:COSE object}] | | Object-Security:COSE object}] |
+---------------------------------------------->| +---------------------------------------------->|
| response: | | response: |
| 2.05 (Content) | | 2.05 (Content) |
| [Header, Token, Options:{..., | | [Header, Token, Options:{..., |
skipping to change at page 4, line 34 skipping to change at page 4, line 37
| | | |
Figure 1: Sketch of OSCOAP Figure 1: Sketch of OSCOAP
OSCOAP may be used in extremely constrained settings, where CoAP over OSCOAP may be used in extremely constrained settings, where CoAP over
DTLS may be prohibitive e.g. due to large code size. Alternatively, DTLS may be prohibitive e.g. due to large code size. Alternatively,
OSCOAP can be combined with DTLS, thereby enabling end-to-end OSCOAP can be combined with DTLS, thereby enabling end-to-end
security of e.g. CoAP payload and options, in combination with hop- security of e.g. CoAP payload and options, in combination with hop-
by-hop protection of the entire CoAP message, during transport by-hop protection of the entire CoAP message, during transport
between end-point and intermediary node. Examples of the use of between end-point and intermediary node. Examples of the use of
OSCOAP are given in Appendix C. OSCOAP are given in Appendix B.
The message protection provided by OSCOAP can alternatively be The message protection provided by OSCOAP can alternatively be
applied only to the payload of individual messages. We call this applied only to the payload of individual messages. We call this
object security of content (OSCON) and it is defined in Appendix D. object security of content (OSCON), which is defined in Appendix C.
1.1. Terminology 1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. These document are to be interpreted as described in [RFC2119]. These
words may also appear in this document in lowercase, absent their words may also appear in this document in lowercase, absent their
normative meanings. normative meanings.
Readers are expected to be familiar with the terms and concepts Readers are expected to be familiar with the terms and concepts
skipping to change at page 5, line 4 skipping to change at page 5, line 8
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. These document are to be interpreted as described in [RFC2119]. These
words may also appear in this document in lowercase, absent their words may also appear in this document in lowercase, absent their
normative meanings. normative meanings.
Readers are expected to be familiar with the terms and concepts Readers are expected to be familiar with the terms and concepts
described in CoAP [RFC7252], Observe [RFC7641], Blockwise [RFC7959], described in CoAP [RFC7252], Observe [RFC7641], Blockwise [RFC7959],
COSE [I-D.ietf-cose-msg], CBOR [RFC7049], CDDL COSE [I-D.ietf-cose-msg], CBOR [RFC7049], CDDL
[I-D.greevenbosch-appsawg-cbor-cddl], and constrained environments [I-D.greevenbosch-appsawg-cbor-cddl], and constrained environments
[RFC7228]. [RFC7228].
The terms Common/Sender/Recipient Context, Master Secret/Salt, Sender
ID/Key/IV, Recepient ID/Key/IV and Context IV are defined in
Section 3.1.
2. The Object-Security Option 2. The Object-Security Option
The Object-Security option (see Figure 2) indicates that OSCOAP is The Object-Security option (see Figure 2) indicates that OSCOAP is
used to protect the CoAP message exchange. The Object-Security used to protect the CoAP message exchange. The Object-Security
option is critical, safe to forward, part of the cache key, not option is critical, safe to forward, part of the cache key, not
repeatable, and opaque. repeatable, and opaque.
+-----+---+---+---+---+-----------------+--------+--------+ +-----+---+---+---+---+-----------------+--------+--------+
| No. | C | U | N | R | Name | Format | Length | | No. | C | U | N | R | Name | Format | Length |
+-----+---+---+---+---+-----------------+--------+--------| +-----+---+---+---+---+-----------------+--------+--------|
skipping to change at page 5, line 34 skipping to change at page 5, line 41
A successful response to a request with the Object-Security option A successful response to a request with the Object-Security option
SHALL contain the Object-Security option. A CoAP endpoint SHOULD NOT SHALL contain the Object-Security option. A CoAP endpoint SHOULD NOT
cache a response to a request with an Object-Security option, since cache a response to a request with an Object-Security option, since
the response is only applicable to the original client's request. the response is only applicable to the original client's request.
The Object-Security option is included in the cache key for backward The Object-Security option is included in the cache key for backward
compatibility with proxies not recognizing the Object-Security compatibility with proxies not recognizing the Object-Security
option. The effect is that messages with the Object-Security option option. The effect is that messages with the Object-Security option
will never generate cache hits. For Max-Age processing, see will never generate cache hits. For Max-Age processing, see
Section 4.3.1.1. Section 4.3.1.1.
The protection is achieved by means of a COSE object (see Section 5) The protection is achieved by means of a COSE object (see Section 5),
included in the protected CoAP message. The placement of the COSE which is compressed and then included in the protected CoAP message.
object depends on whether the method/response code allows payload The placement of the COSE object depends on whether the method/
(see [RFC7252]): response code allows payload (see [RFC7252]):
o If the method/response code allows payload, then the compressed o If the method/response code allows payload, then the compressed
COSE object is the payload of the protected message, and the COSE object Section 8 is the payload of the protected message, and
Object-Security option has length zero. An endpoint receiving a the Object-Security option has length zero. An endpoint receiving
CoAP message with payload, that also contains a non-empty Object- a CoAP message with payload, that also contains a non-empty
Security option SHALL treat it as malformed and reject it. Object-Security option SHALL treat it as malformed and reject it.
o If the method/response code does not allow payload, then the o If the method/response code does not allow payload, then the
compressed COSE object is the value of the Object-Security option compressed COSE object Section 8 is the value of the Object-
and the length of the Object-Security option is equal to the size Security option and the length of the Object-Security option is
of the compressed COSE object. An endpoint receiving a CoAP equal to the size of the compressed COSE object. An endpoint
message without payload, that also contains an empty Object- receiving a CoAP message without payload, that also contains an
Security option SHALL treat it as malformed and reject it. empty Object-Security option SHALL treat it as malformed and
reject it.
The size of the COSE object depends on whether the method/response The size of the COSE object depends on whether the method/response
code allows payload, if the message is a request or response, on the code allows payload, if the message is a request or response, on the
set of options that are included in the unprotected message, the AEAD set of options that are included in the unprotected message, the AEAD
algorithm, the length of the information identifying the security algorithm, the length of the information identifying the security
context, and the length of the sequence number. context, and the length of the sequence number.
3. The Security Context 3. The Security Context
OSCOAP uses COSE with an Authenticated Encryption with Additional OSCOAP uses COSE with an Authenticated Encryption with Additional
Data (AEAD) algorithm between a CoAP client and a CoAP server. An Data (AEAD) algorithm between a CoAP client and a CoAP server. An
implementation supporting this specification MAY only implement the implementation supporting this specification MAY only implement the
client part or MAY only the server part. client part or MAY only implement the server part.
The specification requires that client and server establish a This specification requires that client and server establish a
security context to apply to the COSE objects protecting the CoAP security context to apply to the COSE objects protecting the CoAP
messages. In this section we define the security context, and also messages. In this section we define the security context, and also
specify how to derive the initial security contexts in client and specify how to derive the initial security contexts in client and
server based on common shared secret and a key derivation function server based on common shared secret and a key derivation function
(KDF). (KDF).
3.1. Security Context Definition 3.1. Security Context Definition
The security context is the set of information elements necessary to The security context is the set of information elements necessary to
carry out the cryptographic operations in OSCOAP. For each endpoint, carry out the cryptographic operations in OSCOAP. For each endpoint,
skipping to change at page 7, line 16 skipping to change at page 7, line 16
| Common, | | Common, | | Common, | | Common, |
| Sender, | | Recipient,| | Sender, | | Recipient,|
| Recipient | | Sender | | Recipient | | Sender |
'------------' '------------' '------------' '------------'
Client Server Client Server
| | | |
Retrieve context for | request: | Retrieve context for | request: |
target resource | [Token = Token1, | target resource | [Token = Token1, |
Protect request with | kid = SID, ...] | Protect request with | kid = SID, ...] |
Sender Context +---------------------->| Retrieve context with Sender Context +---------------------->| Retrieve context with
| | RID = SID | | RID = kid
| | Verify request with | | Verify request with
| | Recipient Context | | Recipient Context
| response: | Protect response with | 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 3: Retrieval and use of the Security Context Figure 3: Retrieval and use of the Security Context
skipping to change at page 8, line 34 skipping to change at page 8, line 34
once the security context is established. once the security context is established.
o Recipient IV. Byte string containing the IV to verify messages o Recipient IV. Byte string containing the IV to verify messages
received. Derived from Common Context and Recipient ID. Length received. Derived from Common Context and Recipient ID. Length
is determined by Algorithm. Its value is immutable once the is determined by Algorithm. Its value is immutable once the
security context is established. security context is established.
o Replay Window. The replay window to verify requests and observe o Replay Window. The replay window to verify requests and observe
responses received. responses received.
When it is understood which context is referred to (Sender Context or
Recipient Context), the term "Context IV" is used to denote the IV
currently used with this context.
An endpoint may free up memory by not storing the Sender Key, Sender An endpoint may free up memory by not storing the Sender Key, Sender
IV, Recipient Key, and Recipient IV, deriving them from the Common IV, Recipient Key, and Recipient IV, deriving them from the Common
Context when needed. Alternatively, an endpoint may free up memory Context when needed. Alternatively, an endpoint may free up memory
by not storing the Master Secret and Master Salt after the other by not storing the Master Secret and Master Salt after the other
parameters have been derived. parameters have been derived.
The endpoints MAY interchange the client and server roles while The endpoints MAY interchange the client and server roles while
maintaining the same security context. When this happens, the former maintaining the same security context. When this happens, the former
server still protects messages to send using its Sender Context, and server still protects messages to send using its Sender Context, and
verifies messages received using its Recipient Context. The same is verifies messages received using its Recipient Context. The same is
skipping to change at page 9, line 17 skipping to change at page 9, line 23
o Sender ID o Sender ID
o Recipient ID o Recipient ID
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 (Alg) o AEAD Algorithm (Alg)
* Default is AES-CCM-64-64-128 (value 12) * Default is AES-CCM-64-64-128 (COSE abbreviation: 12)
o Master Salt o Master Salt
* Default is the empty string * Default is the empty 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
skipping to change at page 9, line 39 skipping to change at page 9, line 45
* Default is DTLS-type replay protection with a window size of 32 * Default is DTLS-type replay protection with a window size of 32
How the input parameters are pre-established, is application How the input parameters are pre-established, is application
specific. The EDHOC protocol [I-D.selander-ace-cose-ecdhe] enables specific. The EDHOC protocol [I-D.selander-ace-cose-ecdhe] enables
the establishment of input parameters with the property of forward the establishment of input parameters with the property of forward
secrecy and negotiation of KDF and AEAD, it thus provides all secrecy and negotiation of KDF and AEAD, it thus provides all
necessary pre-requisite steps for using OSCOAP as defined here. necessary pre-requisite steps for using OSCOAP as defined here.
3.2.1. Derivation of Sender Key/IV, Recipient Key/IV 3.2.1. Derivation of Sender Key/IV, Recipient Key/IV
The KDF MUST be one of the HKDF [RFC5869] algorithms defined in COSE. The KDF MUST be one of the HMAC based HKDF [RFC5869] algorithms
HKDF SHA-256 is mandatory to implement. The security context defined in COSE. HKDF SHA-256 is mandatory to implement. The
parameters Sender Key/IV and Recipient Key/IV SHALL be derived from security context parameters Sender Key/IV and Recipient Key/IV SHALL
the input parameters using the HKDF, which consists of the be derived from the input parameters using the HKDF, which consists
composition of the HKDF-Extract and HKDF-Expand steps ([RFC5869]): of the composition of the HKDF-Extract and HKDF-Expand steps
([RFC5869]):
output parameter = HKDF(salt, IKM, info, L) output parameter = HKDF(salt, IKM, info, L)
where: where:
o salt is the Master Salt as defined above o salt is the Master Salt as defined above
o IKM is the Master Secret is defined above o IKM is the Master Secret is defined above
o info is a CBOR array consisting of: o info is a CBOR array consisting of:
info = [ info = [
id : bstr, id : bstr,
alg : int, alg : int,
type : tstr, type : tstr,
L : int L : int
] ]
* id is the Sender ID or Recipient ID * id is the Sender ID or Recipient ID
skipping to change at page 10, line 17 skipping to change at page 10, line 24
id : bstr, id : bstr,
alg : int, alg : int,
type : tstr, type : tstr,
L : int L : int
] ]
* id is the Sender ID or Recipient ID * id is the Sender ID or Recipient ID
* type is "Key" or "IV" * type is "Key" or "IV"
o L is the key/IV size of the AEAD algorithm in octets without o L is the size of the key/IV for the AEAD algorithm used, in
leading zeroes. octets.
For example, if the algorithm AES-CCM-64-64-128 (see Section 10.2 in For example, if the algorithm AES-CCM-64-64-128 (see Section 10.2 in
[I-D.ietf-cose-msg]) is used, the value for L is 16 for keys and 7 [I-D.ietf-cose-msg]) is used, the value for L is 16 for keys and 7
for IVs. for IVs.
3.2.2. Initial Sequence Numbers and Replay Window 3.2.2. Initial Sequence Numbers and Replay Window
The Sequence Number is initialized to 0. The supported types of The Sequence Number is initialized to 0. The supported types of
replay protection and replay window length is application specific replay protection and replay window length is application specific
and depends on the lower layers. Default is DTLS-type replay and depends on the lower layers. Default is DTLS-type replay
protection with a window size of 32 initiated as described in protection with a window size of 32 initiated as described in
Section 4.1.2.6 of [RFC6347]. Section 4.1.2.6 of [RFC6347].
3.3. Requirements on the Security Context Parameters 3.3. Requirements on the Security Context Parameters
As collisions may lead to the loss of both confidentiality and As collisions may lead to the loss of both confidentiality and
integrity, Sender ID SHALL be unique in the set of all security integrity, Sender ID SHALL be unique in the set of all security
contexts using the same Master Secret. Normally (e.g. when using contexts using the same Master Secret. Normally (e.g. when using
EDHOC) Sender IDs can be very short. Note that Sender IDs of EDHOC [I-D.selander-ace-cose-ecdhe]) Sender IDs can be very short.
different lengths can be used with the same Master Secret. E.g. the Note that Sender IDs of different lengths can be used with the same
SID with value 0x00 is different from the SID with the value 0x0000. Master Secret. E.g. the SID with value 0x00 is different from the
If Sender ID uniqueness cannot be guaranteed, random Sender IDs MUST SID with the value 0x0000. If Sender ID uniqueness cannot be
be used. Random Sender IDs MUST be long enough so that the guaranteed, random Sender IDs MUST be used. Random Sender IDs MUST
probability of collisions is negligible. be long enough so that the probability of collisions is negligible.
To enable retrieval of the right Recipient Context, the Recipient ID To enable retrieval of the right Recipient Context, the Recipient ID
SHOULD be unique in the sets of all Recipient Contexts used by an SHOULD be unique in the sets of all Recipient Contexts used by an
endpoint. endpoint.
The same Master Salt MAY be used with several Master Secrets. The same Master Salt MAY be used with several Master Secrets.
4. Protected CoAP Message Fields 4. Protected CoAP Message Fields
OSCOAP transforms an unprotected CoAP message into a protected CoAP OSCOAP transforms an unprotected CoAP message into a protected CoAP
message, and vice versa. This section defines how the CoAP message message, and vice versa. This section defines how the CoAP message
fields are protected. OSCOAP protects as much of the unprotected fields are protected. Note that OSCOAP protects messages from the
CoAP message as possible, while still allowing forward proxy CoAP Requests/Responses layer only, and not from the Messaging layer
operations [I-D.hartke-core-e2e-security-reqs]. Message fields may (Section 2 of [RFC7252]): this means that RST and ACK empty messages
either be are not protected, while ACK with piggybacked responses are protected
using the process defined in this document. All the messages
mentioned in this document refer to CON, NON and non-empty ACK
messages.
OSCOAP protects as much of the unprotected CoAP message as possible,
while still allowing forward proxy operations
[I-D.hartke-core-e2e-security-reqs]. Message fields may either be
o Class E: encrypted and integrity protected, o Class E: encrypted and integrity protected,
o Class I: integrity protected only, or o Class I: integrity protected only, or
o Class U: unprotected. o Class U: unprotected.
This section also outlines how the message fields are transferred, a This section also outlines how the message fields are transferred, a
detailed description of the processing is provided in Section 7. detailed description of the processing is provided in Section 7.
Message fields of the unprotected CoAP message are either transferred Message fields of the unprotected CoAP message are either transferred
in the header/options part of the protected CoAP message, or in the in the header/options part of the protected CoAP message, or in the
plaintext of the COSE object. Depending on which, the location of plaintext of the COSE object. Depending on which, the location of
the message field in the protected CoAP message is called "inner" or the message field in the protected CoAP message is called "inner" or
"outer": "outer":
o Inner message field: message field included in the plaintext of o Inner message field: message field included in the plaintext of
the COSE object of the protected CoAP message (see Section 5.1) the COSE object of the protected CoAP message (see Section 5.1).
The inner message fields are by definition encrypted and integrity
protected by the COSE object (Class E).
o Outer message field: message field included in the header or o Outer message field: message field included in the header or
options part of the protected CoAP message options part of the protected CoAP message. The outer message
fields are not encrypted and thus visible to an intermediary, but
The inner message fields are by definition encrypted and integrity may be integrity protected by including the message field values
protected by the COSE object (Class E). The outer message fields are in the Additional Authenticated Data (AAD) of the COSE object (see
not encrypted and thus visible to an intermediary, but may be Section 5.2). I.e. outer message fields may be Class I or Class
integrity protected by including the message field values in the AAD U.
of the COSE object (see Section 5.2). I.e. outer message fields may
be Class I or Class U.
Note that, even though the message formats are slightly different, Note that, even though the message formats are slightly different,
OSCOAP complies with CoAP over unreliable transport [RFC7252] as well OSCOAP complies with CoAP over unreliable transport [RFC7252] as well
as CoAP over reliable transport [I-D.ietf-core-coap-tcp-tls]. as CoAP over reliable transport [I-D.ietf-core-coap-tcp-tls].
4.1. CoAP Payload 4.1. CoAP Payload
The CoAP Payload SHALL be encrypted and integrity protected (Class The CoAP Payload SHALL be encrypted and integrity protected (Class
E), and thus is an inner message field. E), and thus is an inner message field.
The sending endpoint writes the payload of the unprotected CoAP The sending endpoint writes the payload of the unprotected CoAP
message into the plaintext of the COSE object. message into the plaintext of the COSE object.
The receiving endpoint verifies and decrypts the COSE object, and The receiving endpoint verifies and decrypts the COSE object, and
recreates the payload of the unprotected CoAP message. recreates the payload of the unprotected CoAP message.
4.2. CoAP Header 4.2. CoAP Header
Many CoAP header fields are required to be read and changed during a Many CoAP header fields are required to be read and changed during a
normal message exchange or when traversing a proxy and thus cannot be normal message exchange or when traversing a proxy and thus cannot in
protected between the endpoints, e.g. CoAP message layer fields such general be protected between the endpoints, e.g. CoAP message layer
as Message ID. fields such as Message ID.
The CoAP header field Code MUST be sent in plaintext to support The CoAP header field Code MUST be sent in plaintext to support
RESTful processing, but MUST be integrity protected to prevent an RESTful processing, but MUST be integrity protected to prevent an
intermediary from changing, e.g. from GET to DELETE (Class I). The intermediary from changing, e.g. from GET to DELETE (Class I). The
CoAP version number MUST be integrity protected to prevent potential CoAP version number MUST be integrity protected to prevent potential
future version-based attacks (Class I). Note that while the version future version-based attacks (Class I). Note that while the version
number is not sent in each CoAP message over reliable transport number is not sent in each CoAP message over reliable transport
[I-D.ietf-core-coap-tcp-tls], its value is known to client and [I-D.ietf-core-coap-tcp-tls], its value is known to client and
server. server.
Other CoAP header fields SHALL neither be integrity protected nor The other CoAP header fields SHALL neither be integrity protected nor
encrypted (Class U). The CoAP header fields are thus outer message encrypted (Class U). All CoAP header fields are thus outer message
fields. fields.
The sending endpoint SHALL copy the header fields from the The sending endpoint SHALL copy the header fields from the
unprotected CoAP message to the protected CoAP message. The unprotected CoAP message to the header of the protected CoAP message.
receiving endpoint SHALL copy the header fields from the protected The receiving endpoint SHALL copy the header fields from the
CoAP message to the unprotected CoAP message. Both sender and protected CoAP message to the header of the unprotected CoAP message.
receiver insert the CoAP version number and header field Code in the Both sender and receiver include the CoAP version number and header
AAD of the COSE object (see section Section 5.2). field Code in the AAD of the COSE object (see Section 5.2).
4.3. CoAP Options 4.3. CoAP Options
Most options are encrypted and integrity protected (Class E), and Most options are encrypted and integrity protected (Class E), and
thus inner message fields. But to allow certain proxy operations, thus inner message fields. But to allow certain proxy operations,
some options have outer values, i.e. are present in the protected some options have outer values, i.e. are present as options in the
CoAP message. Certain options may have both an inner value and a protected CoAP message. Certain options may have both an inner value
potentially different outer value, where the inner value is intended and a potentially different outer value, where the inner value is
for the destination endpoint and the outer value is intended for the intended for the destination endpoint and the outer value is intended
proxy. for the proxy.
A summary of how options are protected and processed is shown in A summary of how options are protected and processed is shown in
Figure 4. Options within each class are protected and processed in a Figure 4. Options within each class are protected and processed in a
similar way, but certain options which require special processing as similar way, but certain options which require special processing are
described in the subsections and indicated by a * in Figure 4. indicated by a * in Figure 4 and described in the subsections below.
+----+----------------+---+---+---+ +----+----------------+---+---+---+
| No.| Name | E | I | U | | No.| Name | E | I | U |
+----+----------------+---+---+---+ +----+----------------+---+---+---+
| 1 | If-Match | x | | | | 1 | If-Match | x | | |
| 3 | Uri-Host | | | x | | 3 | Uri-Host | | | x |
| 4 | ETag | x | | | | 4 | ETag | x | | |
| 5 | If-None-Match | x | | | | 5 | If-None-Match | x | | |
| 6 | Observe | | * | | | 6 | Observe | | * | |
| 7 | Uri-Port | | | x | | 7 | Uri-Port | | | x |
skipping to change at page 13, line 40 skipping to change at page 13, line 48
U=Unprotected, *=Special U=Unprotected, *=Special
Figure 4: Protection of CoAP Options Figure 4: Protection of CoAP Options
Unless specified otherwise, CoAP options not listed in Figure 4 SHALL Unless specified otherwise, CoAP options not listed in Figure 4 SHALL
be encrypted and integrity protected and processed as class E be encrypted and integrity protected and processed as class E
options. options.
Specifications of new CoAP options SHOULD define how they are Specifications of new CoAP options SHOULD define how they are
processed with OSCOAP. New COAP options SHOULD be of class E and processed with OSCOAP. New COAP options SHOULD be of class E and
SHOULD NOT have outer options unless a forwarding proxy needs to read SHOULD NOT have outer values unless a forwarding proxy needs to read
that option value. If a certain option is both inner and outer, the that option value. If a certain option has both inner and outer
two values SHOULD NOT be the same, unless a proxy is required by values, the two values SHOULD NOT be the same.
specification to be able to read the end-to-end value.
4.3.1. Class E Options 4.3.1. Class E Options
For options in class E (see Figure 4) the option value in the For options in class E (see Figure 4) the option value in the
unprotected CoAP message, if present, SHALL be encrypted and unprotected CoAP message, if present, SHALL be encrypted and
integrity protected between the endpoints. Hence the actions integrity protected between the endpoints. Hence the actions
resulting from the use of such options is analogous to communicating resulting from the use of such options is analogous to communicating
in a protected manner with the endpoint. For example, a client using in a protected manner directly with the endpoint. For example, a
an ETag option will not be served by a proxy. client using an If-Match option will not be served by a proxy.
The sending endpoint SHALL write the class E option from the The sending endpoint SHALL write the class E option from the
unprotected CoAP message into the plaintext of the COSE object. unprotected CoAP message into the plaintext of the COSE object.
Except for the special options described in the subsections, the Except for the special options described in the subsections, the
sending endpoint SHALL NOT use the outer options of class E. sending endpoint SHALL NOT use the outer options of class E.
However, note that an intermediary may, legitimately or not, add, However, note that an intermediary may, legitimately or not, add,
change or remove the value of an outer option. change or remove the value of an outer option.
Except for the Block options Section 4.3.1.2, the receiving endpoint Except for the Block options Section 4.3.1.2, the receiving endpoint
SHALL discard any outer options of class E from the protected CoAP SHALL discard any outer options of class E from the protected CoAP
message and SHALL replace it in the unprotected CoAP messages with message and SHALL write the Class E options present in the plaintext
the value from the COSE object when present. of the COSE object into the unprotected CoAP message.
4.3.1.1. Max-Age 4.3.1.1. Max-Age
An inner Max-Age option, like other class E options, is used as An inner Max-Age option, like other class E options, is used as
defined in [RFC7252] taking into account that it is not accessible to defined in [RFC7252] taking into account that it is not accessible to
proxies. proxies.
Since OSCOAP binds CoAP responses to requests, a cached response Since OSCOAP binds CoAP responses to requests, a cached response
would not be possible to use for any other request. To avoid would not be possible to use for any other request. To avoid
unnecessary caching, a server MAY add an outer Max-Age option with unnecessary caching, a server MAY add an outer Max-Age option with
value zero to protected CoAP responses (see Section 5.6.1 of value zero to protected CoAP responses (see Section 5.6.1 of
[RFC7252]). [RFC7252]). The outer Max-Age option is not integrity protected.
The outer Max-Age option is not integrity protected.
4.3.1.2. The Block Options 4.3.1.2. The Block Options
Blockwise [RFC7959] is an optional feature. An implementation MAY Blockwise [RFC7959] is an optional feature. An implementation MAY
comply with [RFC7252] and the Object-Security option without comply with [RFC7252] and the Object-Security option without
implementing [RFC7959]. implementing [RFC7959].
The Block options (Block1, Block2, Size1 and Size2) MAY be either The Block options (Block1, Block2, Size1 and Size2) MAY be either
only inner options, only outer options or both inner and outer only inner options, only outer options or both inner and outer
options. The inner and outer options are processed independently. options. The inner and outer options are processed independently.
skipping to change at page 15, line 27 skipping to change at page 15, line 35
defined in this document. defined in this document.
If the unprotected CoAP message in turn contains Block options, the If the unprotected CoAP message in turn contains Block options, the
receiving endpoint processes this according to [RFC7959]. receiving endpoint processes this according to [RFC7959].
TODO: Update processing to support multiple concurrently proceeding TODO: Update processing to support multiple concurrently proceeding
requests requests
4.3.2. Class I Options 4.3.2. Class I Options
Except for the special options described in the subsections, for A Class I option is an outer option and hence visible in the options
options in Class I (see Figure 4) the option value SHALL only be part of the protected CoAP message. Except for special options
integrity protected between the endpoints. Options in Class I have described in the subsections, for options in Class I (see Figure 4)
outer values. Unless otherwise specified, the sending endpoint SHALL the option value SHALL be integrity protected between the endpoints,
encode the Class I options in the protected CoAP message as described see (Section 5.2). Unless otherwise specified, the sending endpoint
in Section 4.3.4. SHALL encode the Class I options in the protected CoAP message as
described in Section 4.3.4.
Class I options are included in the external_aad (Section 5.2).
4.3.2.1. Observe 4.3.2.1. Observe
Observe [RFC7641] is an optional feature. An implementation MAY Observe [RFC7641] is an optional feature. An implementation MAY
support [RFC7252] and the Object-Security option without supporting support [RFC7252] and the Object-Security option without supporting
[RFC7641]. The Observe option as used here targets the requirements [RFC7641]. The Observe option as used here targets the requirements
on forwarding of [I-D.hartke-core-e2e-security-reqs] on forwarding of [I-D.hartke-core-e2e-security-reqs]
(Section 2.2.1.2). (Section 2.2.1.2).
In order for a proxy to support forwarding of Observe, there MUST be In order for a proxy to support forwarding of Observe messages, there
an outer Observe option in the message. must be an Observe option present in options part of the protected
CoAP message ([RFC7641]), so Observe must have an outer value:
o The Observe Registration (see Section 1.2 of [RFC7641]) of the
unprotected CoAP request SHALL be encoded in the protected CoAP
request as described in Section 4.3.4.
o The Observe Notification (see Section 1.2 of [RFC7641]) of the
unprotected CoAP response SHALL be encoded in the protected CoAP
response as described in Section 4.3.4.
To secure the Observe Registration and the order of the o The Observe option of the unprotected CoAP request SHALL be
Notifications, Observe SHALL be integrity protected as described in encoded in the protected CoAP request as described in
this section: Section 4.3.4.
o The Observe option in the unprotected CoAP request SHALL be To secure the order of the notifications, responses with the Observe
included in the external_aad of the request (see Section 5.2). option SHALL be integrity protected in the following way:
o The Observe option SHALL be included in the external_aad of the o The Observe option SHALL be included in the external_aad of the
response (see Section 5.2), with value set to the 3 least response (see Section 5.2), with value set to the 3 least
significant bytes of the Sequence Number of the response significant bytes of the Sequence Number of the response.
The Observe option in the CoAP request SHALL NOT be integrity
protected, since it may be legitimately removed by a proxy.
If the Observe option is removed from a CoAP request by a proxy, then
the server can still verify the request (as a non-Observe request),
and produce a non-Observe response. If the OSCOAP client receives a
response to an Observe request without an outer Observe value, then
it MUST verify the response as a non-Observe response, i.e. not
include the Sequence Number of the response in the external_aad.
4.3.3. Class U Options 4.3.3. Class U Options
Options in Class U have outer values and are used to support forward Options in Class U have outer values and are used to support forward
proxy operations. Unless otherwise specified, the sending endpoint proxy operations. Unless otherwise specified, the sending endpoint
SHALL encode the Class U options in the protected CoAP message as SHALL encode the Class U options in the options part of the protected
described in Section 4.3.4. CoAP message as described in Section 4.3.4.
4.3.3.1. Uri-Host, Uri-Port, and Proxy-Scheme 4.3.3.1. Uri-Host, Uri-Port, and Proxy-Scheme
The sending endpoint SHALL copy Uri-Host, Uri-Port, and Proxy-Scheme The sending endpoint SHALL copy Uri-Host, Uri-Port, and Proxy-Scheme
from the unprotected CoAP message to the protected CoAP message. from the unprotected CoAP message to the options part of the
When Uri-Host, Uri-Port, Proxy-Scheme options are present, Proxy-Uri protected CoAP message. When Uri-Host, Uri-Port, or Proxy-Scheme
is not used [RFC7252]. options are present, Proxy-Uri is not used [RFC7252].
4.3.3.2. Proxy-Uri 4.3.3.2. Proxy-Uri
Proxy-Uri, when present, is split by OSCOAP into class U options and Proxy-Uri, when present, is split by OSCOAP into class U options and
privacy sensitive class E options, which are processed accordingly. class E options, which are processed accordingly. When Proxy-Uri is
When Proxy-Uri is used in the unprotected CoAP message, Uri-* are not used in the unprotected CoAP message, Uri-* are not present
present [RFC7252]. [RFC7252].
The sending endpoint SHALL first decompose the Proxy-Uri value of the The sending endpoint SHALL first decompose the Proxy-Uri value of the
unprotected CoAP message into the Proxy-Scheme, Uri-Host, Uri-Port, unprotected CoAP message into the Proxy-Scheme, Uri-Host, Uri-Port,
Uri-Path and Uri-Query options (if present) according to section 6.4 Uri-Path and Uri-Query options (if present) according to section 6.4
of [RFC7252]. of [RFC7252].
Uri-Path and Uri-Query are class E options and MUST be protected and Uri-Path and Uri-Query are class E options and MUST be protected and
processed as if obtained from the unprotected CoAP message, see processed as if obtained from the unprotected CoAP message, see
Section 4.3.1. Section 4.3.1.
The value of the Proxy-Uri option of the protected CoAP message MUST The value of the Proxy-Uri option of the protected CoAP message MUST
be replaced with Proxy-Scheme, Uri-Host and Uri-Port options (if be replaced with Proxy-Scheme, Uri-Host and Uri-Port options (if
present) composed according to section 6.5 of [RFC7252] and MUST be present) composed according to section 6.5 of [RFC7252] and MUST be
processed as a class U option, see Section 4.3.3. processed as a class U option, see Section 4.3.3.
An example of how Proxy-Uri is processed is given below. An example of how Proxy-Uri is processed is given here. Assume that
the unprotected CoAP message contains:
An unprotected CoAP message contains:
o Proxy-Uri = "coap://example.com/resource?q=1" o Proxy-Uri = "coap://example.com/resource?q=1"
During OSCOAP processing, Proxy-Uri is split into: During OSCOAP processing, Proxy-Uri is split into:
o Proxy-Scheme = "coap" o Proxy-Scheme = "coap"
o Uri-Host = "example.com" o Uri-Host = "example.com"
o Uri-Port = "5863" o Uri-Port = "5863"
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.3.1. Proxy-Uri is added to the OSCOAP protected message Section 4.3.1, and are thus encrypted and transported in the COSE
with value: object. The remaining options are composed into the Proxy-Uri
included in the options part of the protected CoAP message, which has
value:
o Proxy-Uri = "coap://example.com" o Proxy-Uri = "coap://example.com"
4.3.4. Outer Options in the Protected CoAP Message 4.3.4. Outer Options in the Protected CoAP Message
All options with outer values present in the protected CoAP message, All options with outer values present in the protected CoAP message,
including the Object-Security option, SHALL be encoded as described including the Object-Security option, SHALL be encoded as described
in Section 3.1 of [RFC7252], where the delta is the difference to the in Section 3.1 of [RFC7252], where the delta is the difference to the
previously included outer option. previously included outer option value.
5. The COSE Object 5. The COSE Object
This section defines how to use COSE [I-D.ietf-cose-msg] to wrap and This section defines how to use COSE [I-D.ietf-cose-msg] to wrap and
protect data in the unprotected CoAP message. OSCOAP uses the protect data in the unprotected CoAP message. OSCOAP uses the
untagged COSE_Encrypt0 structure with an Authenticated Encryption untagged COSE_Encrypt0 structure with an Authenticated Encryption
with Additional Data (AEAD) algorithm. The key lengths, IV lengths, with Additional Data (AEAD) algorithm. The key lengths, IV lengths,
and maximum sequence number are algorithm dependent. and maximum sequence number are algorithm dependent.
The AEAD algorithm AES-CCM-64-64-128 defined in Section 10.2 of The AEAD algorithm AES-CCM-64-64-128 defined in Section 10.2 of
[I-D.ietf-cose-msg] is mandatory to implement. For AES-CCM-64-64-128 [I-D.ietf-cose-msg] is mandatory to implement. For AES-CCM-64-64-128
the length of Sender Key and Recipient Key is 128 bits, the length of the length of Sender Key and Recipient Key is 128 bits, the length of
nonce, Sender IV, and Recipient IV is 7 bytes, and the maximum nonce, Sender IV, and Recipient IV is 7 bytes. The maximum Sequence
Sequence Number is 2^55 - 1. Number is specified in Section 10.
The nonce is constructed as described in Section 3.1 of The nonce is constructed as described in Section 3.1 of
[I-D.ietf-cose-msg], i.e. by padding the partial IV (Sequence Number [I-D.ietf-cose-msg], i.e. by padding the partial IV (Sequence Number
in network byte order) with zeroes and XORing it with the context IV in network byte order) with zeroes and XORing it with the Context IV
(Sender IV or Recipient IV). The first bit in the Sender IV or (Sender IV or Recipient IV), with the following addition: The most
Recipient IV SHALL be flipped in responses. significant bit in the first byte of the Context IV SHALL be flipped
for responses, in case there is a unique response (not Observe). In
this way, the same sequence number can be reused for requests and
corresponding responses, which reduces the size of the responses in
the most common case. For detailed processing instructions, see
Section 7.
We denote by Plaintext the data that is encrypted and integrity We denote by Plaintext the data that is encrypted and integrity
protected, and by Additional Authenticated Data (AAD) the data that protected, and by Additional Authenticated Data (AAD) the data that
is integrity protected only. is 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 includes: o The "protected" field is empty.
o The "unprotected" field includes:
* The "Partial IV" parameter. The value is set to the Sequence * The "Partial IV" parameter. The value is set to the Sequence
Number. The Partial IV SHALL be of minimum length needed to Number. The Partial IV SHALL be of minimum length needed to
encode the sequence number. This parameter SHALL be present in encode the sequence number. This parameter SHALL be present in
requests, and MAY be present in responses. In case of Observe requests. In case of Observe (Section 4.3.2.1) the Partial IV
(Section 4.3.2.1}) the Partial IV SHALL be present in the SHALL be present in the response, and otherwise the Partial IV
response. SHALL NOT be present in the response.
* The "kid" parameter. The value is set to the Sender ID (see * The "kid" parameter. The value is set to the Sender ID (see
Section 3). This parameter SHALL be present in requests and Section 3). This parameter SHALL be present in requests and
SHALL NOT be present in responses. SHALL NOT be present in responses.
o The "unprotected" field is empty.
o The "ciphertext" field is computed from the Plaintext (see o The "ciphertext" field is computed from the Plaintext (see
Section 5.1) and the Additional Authenticated Data (AAD) (see Section 5.1) and the Additional Authenticated Data (AAD) (see
Section 5.2) following Section 5.2 of [I-D.ietf-cose-msg]. Section 5.2) following Section 5.2 of [I-D.ietf-cose-msg].
The encryption process is described in Section 5.3 of The encryption process is described in Section 5.3 of
[I-D.ietf-cose-msg]. [I-D.ietf-cose-msg].
5.1. Plaintext 5.1. Plaintext
The Plaintext is formatted as a CoAP message without Header (see The Plaintext is formatted as a CoAP message without Header (see
Figure 5) consisting of: Figure 5) consisting of:
o all Class E options Section 4.3.1 present in the unprotected CoAP o all Class E option values Section 4.3.1 present in the unprotected
message (see Section 4). The options are encoded as described in CoAP message (see Section 4.3). The options are encoded as
Section 3.1 of [RFC7252], where the delta is the difference to the described in Section 3.1 of [RFC7252], where the delta is the
previously included Class E option; and difference to the previously included Class E option; and
o the Payload of unprotected CoAP message, if present, and in that o the Payload of unprotected CoAP message, if present, and in that
case prefixed by the one-byte Payload Marker (0xFF). case prefixed by the one-byte Payload Marker (0xFF).
0 1 2 3 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Options to Encrypt (if any) ... | Class E options (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 1 1 1 1 1 1 1| Payload (if any) ... |1 1 1 1 1 1 1 1| Payload (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(only if there (only if there
is payload) is payload)
Figure 5: Plaintext Figure 5: Plaintext
5.2. Additional Authenticated Data 5.2. Additional Authenticated Data
skipping to change at page 20, line 7 skipping to change at page 20, line 27
exchange (see Section 3.1). 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_seq: contains the value of the 'Partial IV' in the COSE o request_seq: contains the value of the 'Partial IV' in the COSE
object of the request (see Section 5). object of the request (see Section 5).
6. Sequence Numbers, Replay, Message Binding, and Freshness 6. Sequence Numbers, Replay, Message Binding, and Freshness
Sequence numbers and replay window are initialized as defined in
Section 3.2.2.
6.1. AEAD Nonce Uniqueness 6.1. AEAD Nonce Uniqueness
An AEAD nonce MUST NOT be used more than once per AEAD key. In order An AEAD nonce MUST NOT be used more than once per AEAD key. In order
to assure unique nonces, each Sender Context contains a Sequence to assure unique nonces, each Sender Context contains a Sequence
Number used to protect requests, and - in case of Observe - Number used to protect requests, and - in case of Observe -
responses. The maximum sequence number is algorithm dependent and responses. The maximum sequence number is algorithm dependent, see
SHALL be 2^(min(nonce length in bits, 56) - 1) - 1. If the Sequence Section 10. If the Sequence Number exceeds the maximum sequence
Number exceeds the maximum sequence number, the endpoint MUST NOT number, the endpoint MUST NOT process any more messages with the
process any more messages with the given Sender Context. The given Sender Context. The endpoint SHOULD acquire a new security
endpoint SHOULD acquire a new security context (and consequently context (and consequently inform the other endpoint) before this
inform the other endpoint) before this happens. The latter is out of happens. The latter is out of scope of this document.
scope of this document.
6.2. Replay Protection 6.2. Replay Protection
In order to protect from replay of messages, each Recipient Context In order to protect from replay of messages, each Recipient Context
contains a Replay Window used to verify request, and - in case of contains a Replay Window used to verify request, and - in case of
Observe - responses. A receiving endpoint SHALL verify that a Observe - responses. A receiving endpoint SHALL verify that a
Sequence Number (Partial IV) received in the COSE object has not been Sequence Number (Partial IV) received in the COSE object has not been
received before in the Recipient Context. The size and type of the received before in the Recipient Context. For requests, if this
Replay Window depends on the use case and lower protocol layers. In verification fails and the message received is a CON message, the
case of reliable and ordered transport from endpoint to endpoint, the server SHALL respond with a 4.00 Bad Request error message. The
recipient MAY just store the last received sequence number and diagnostic payload MAY contain the "Replay protection failed" string.
require that newly received Sequence Numbers equals the last received For responses, if this verification fails and the message received is
Sequence Number + 1. a CON message, the client SHALL respond with an empty ACK and stop
processing the response.
6.3. Sequence Number and Replay Window State The size and type of the Replay Window depends on the use case and
lower protocol layers. In case of reliable and ordered transport
from endpoint to endpoint, the recipient MAY just store the last
received sequence number and require that newly received Sequence
Numbers equals the last received Sequence Number + 1.
6.3.1. The Basic Case 6.3. Sequence Number and Replay Window State
To prevent reuse of the Nonce/Sequence Number with the same key, or To prevent reuse of the Nonce/Sequence Number with the same key, or
from accepting replayed messages, a node needs to handle the from accepting replayed messages, a node needs to handle the
situation of suddenly losing sequence number and replay window state situation of suddenly losing sequence number and replay window state
in RAM, e.g. as a result of a reboot. in RAM, e.g. as a result of a reboot.
After boot, a node MAY reject to use existing security contexts from After boot, a node MAY reject to use existing security contexts from
before it booted and MAY establish a new security context with each before it booted and MAY establish a new security context with each
party it communicates, e.g. using EDHOC party it communicates, e.g. using EDHOC
[I-D.selander-ace-cose-ecdhe]. However, establishing a fresh [I-D.selander-ace-cose-ecdhe]. However, establishing a fresh
security context may have a non-negligible cost in terms of e.g. security context may have a non-negligible cost in terms of e.g.
power consumption. power consumption.
If a stored security context is to be used after reboot, then the If a stored security context is to be used after reboot, then the
node MUST NOT reuse a previous Sequence Number and MUST NOT accept node MUST NOT reuse a previous Sequence Number and MUST NOT accept
previously accepted messages. The node MAY perform the following previously accepted messages.
procedure:
6.3.1. The Basic Case
To prevent reuse of Sequence Number, the node MAY perform the
following procedure during normal operations:
o Before sending a message, the client stores in persistent memory a o Before sending a message, the client stores in persistent memory a
sequence number associated to the stored security context higher sequence number associated to the stored security context higher
than any sequence number which has been or are being sent using than any sequence number which has been or are being sent using
this security context. After boot, the client does not use any this security context. After boot, the client does not use any
lower sequence number in a request than what was persistently lower sequence number in a request than what was persistently
stored with that security context. stored with that security context.
* Storing to persistent memory can be costly. Instead of storing * Storing to persistent memory can be costly. Instead of storing
a sequence number for each request, the client may store Seq + a sequence number for each request, the client may store Seq +
K to persistent memory every K requests, where Seq is the K to persistent memory every K requests, where Seq is the
current sequence number and K > 1. This is a trade-off between current sequence number and K > 1. This is a trade-off between
the number of storage operations and efficient use of sequence the number of storage operations and efficient use of sequence
numbers. numbers.
o After boot, before accepting a message from a stored security To prevent accepting replay of previously received messages, the node
context, the server synchronizes the replay window so that no old MAY perform the following procedure:
messages are being accepted. The server uses the Repeat option
[I-D.mattsson-core-coap-actuators] for synchronizing the replay o After boot, before verifying a message using a security context
window: For each stored security context, the first time after stored before boot, the server synchronizes the replay window so
boot the server receives an OSCOAP request, it generates a pseudo- that no old messages are being accepted. The server uses the
random nonce and responds with the Repeat option set to the nonce Repeat option [I-D.mattsson-core-coap-actuators] for synchronizing
as described in [I-D.mattsson-core-coap-actuators]. If the server the replay window: For each stored security context, the first
receives a repeated OSCOAP request containing the Repeat option time after boot the server receives an OSCOAP request, it
and the same nonce, and if the server can verify the request, then generates a pseudo-random nonce and responds with the Repeat
the sequence number obtained in the repeated message is set as the option set to the nonce as described in
lower limit of the replay window. [I-D.mattsson-core-coap-actuators]. If the server receives a
repeated OSCOAP request containing the Repeat option and the same
nonce, and if the server can verify the request, then the sequence
number obtained in the repeated message is set as the lower limit
of the replay window.
6.3.2. The Observe Case
To prevent reuse of Sequence Number in case of Observe, the node MAY
perform the following procedure during normal operations:
o Before sending a notification, the server stores in persistent
memory a sequence number associated to the stored security context
higher than any sequence number for which a notification has been
or are being sent using this security context. After boot, the
server does not use any lower sequence number in an Observe
response than what was persistently stored with that security
context.
* Storing to persistent memory can be costly. Instead of storing
a sequence number for each notification, the server may store
Seq + K to persistent memory every K requests, where Seq is the
current sequence number and K > 1. This is a trade-off between
the number of storage operations and efficient use of sequence
numbers.
Note that a client MAY continue an ongoing observation after reboot
using a stored security context. With Observe, the client can only
verify the order of the notifications, as they may be delayed. If
the client wants to synchronize with a server resource it MAY restart
an observation.
6.4. Freshness 6.4. Freshness
For responses without Observe, OSCOAP provides absolute freshness. For responses without Observe, OSCOAP provides absolute freshness.
For requests, and responses with Observe, OSCOAP provides relative For requests, and responses with Observe, OSCOAP provides relative
freshness in the sense that the sequence numbers allows a recipient freshness in the sense that the sequence numbers allows a recipient
to determine the relative order of messages. For applications having to determine the relative order of messages.
stronger demands on freshness (e.g. control of actuators), OSCOAP
needs to be augmented with mechanisms providing absolute freshness For applications having stronger demands on freshness (e.g. control
[I-D.mattsson-core-coap-actuators]. of actuators), OSCOAP needs to be augmented with mechanisms providing
absolute freshness [I-D.mattsson-core-coap-actuators].
6.5. Delay and Mismatch Attacks 6.5. Delay and Mismatch Attacks
In order to prevent response delay and mismatch attacks In order to prevent response delay and mismatch attacks
[I-D.mattsson-core-coap-actuators] from on-path attackers and [I-D.mattsson-core-coap-actuators] from on-path attackers and
compromised proxies, OSCOAP binds responses to the request by compromised proxies, OSCOAP binds responses to the request by
including the request's ID (Sender ID or Recipient ID) and sequence including the request's ID (Sender ID or Recipient ID) and sequence
number in the AAD of the response. The server therefore needs to number in the AAD of the response. The server therefore needs to
store the request's ID (Sender ID or Recipient ID) and sequence store the request's ID (Sender ID or Recipient ID) and sequence
number until all responses have been sent. number until all responses have been sent.
skipping to change at page 22, line 17 skipping to change at page 23, line 31
7.1. Protecting the Request 7.1. Protecting the Request
Given an unprotected request, the client SHALL perform the following Given an unprotected request, the client SHALL perform the following
steps to create a protected request: steps to create a protected request:
1. Retrieve the Sender Context associated with the target resource. 1. Retrieve the Sender Context associated with the target resource.
2. Compose the Additional Authenticated Data, as described in 2. Compose the Additional Authenticated Data, as described in
Section 5. Section 5.
3. Compose the AEAD nonce by XORing the context IV (Sender IV) with 3. Compose the AEAD nonce by XORing the Context IV (Sender IV) with
the partial IV (Sequence Number in network byte order). the partial IV (Sequence Number in network byte order).
Increment the Sequence Number by one.
4. Encrypt the COSE object using the Sender Key. Compress the COSE 4. Encrypt the COSE object using the Sender Key. Compress the COSE
Object as specified in Appendix A. Object as specified in Section 8.
5. Format the protected CoAP message according to Section 4. The 5. Format the protected CoAP message according to Section 4. The
Object-Security option is added, see Section 4.3.4. Object-Security option is added, see Section 4.3.4.
6. Store the association Token - Security Context. The client SHALL 6. Store the association Token - Security Context. The client SHALL
be able to find the Recipient Context from the Token in the be able to find the Recipient Context from the Token in the
response. response.
7. Increment the Sequence Number by one.
7.2. Verifying the Request 7.2. Verifying the Request
A server receiving a request containing the Object-Security option A server receiving a request containing the Object-Security option
SHALL perform the following steps: SHALL perform the following steps:
1. Process outer Block options according to [RFC7959], until all 1. Process outer Block options according to [RFC7959], until all
blocks of the request have been received, see Section 4.3.1.2. blocks of the request have been received, see Section 4.3.1.2.
2. Retrieve the Recipient Context associated with the Recipient ID 2. Decompress the COSE Object (Section 8) and retrieve the Recipient
in the 'kid' parameter of the COSE object. Context associated with the Recipient ID in the 'kid' parameter.
If the request is a CON message, and:
3. Verify the Sequence Number in the 'Partial IV' parameter, as * either the decompression or the COSE message fails to decode,
the server SHALL respond with a 4.02 Bad Option error message.
The diagnostic payload SHOULD contain the string "Failed to
decode COSE".
* the server fails to retrieve a Recipient Context with
Recipient ID corresponding to the 'kid' parameter received,
the server SHALL respond with a 4.01 Unauthorized error
message. The diagnostic payload MAY contain the string
"Security context not found".
If the request is a NON message and either the decompression or the
COSE message fails to decode, or the server fails to retrieve a
Recipient Context with Recipient ID corresponding to the 'kid'
parameter received, then the server SHALL stop processing the
request.
1. Verify the Sequence Number in the 'Partial IV' parameter, as
described in Section 6. described in Section 6.
4. Compose the Additional Authenticated Data, as described in 2. Compose the Additional Authenticated Data, as described in
Section 5. Section 5.
5. Compose the AEAD nonce by XORing the context IV (Recipient IV) 3. Compose the AEAD nonce by XORing the Context IV (Recipient IV)
with the padded 'Partial IV' parameter, received in the COSE with the padded 'Partial IV' parameter, received in the COSE
Object. Object.
6. Decrypt the COSE object using the Recipient Key. 4. Decrypt the COSE object using the Recipient Key.
* If decryption fails, the server MUST stop processing the * If decryption fails, the server MUST stop processing the
request and SHOULD send an 4.01 error message. request and, if the request is a CON message, the server MUST
respond with a 4.00 Bad Request error message. The diagnostic
payload MAY contain the "Decryption failed" string.
* If decryption succeeds, update the Recipient Replay Window, as * If decryption succeeds, update the Recipient Replay Window, as
described in Section 6. described in Section 6.
7. Add decrypted options or payload to the unprotected request, 5. Add decrypted options and payload to the unprotected request,
overwriting any outer E options (see Section 4). The Object- processing the E options as described in (Section 4). The
Security option is removed. Object-Security option is removed.
8. The unprotected CoAP request is processed according to [RFC7252] 6. The unprotected CoAP request is processed according to [RFC7252]
7.3. Protecting the Response 7.3. Protecting the Response
Given an unprotected response, the server SHALL perform the following Given an unprotected response, the server SHALL perform the following
steps to create a protected response: steps to create a protected response:
1. Retrieve the Sender Context in the Security Context used to 1. Retrieve the Sender Context in the Security Context used to
verify the request. verify the request.
2. Compose the Additional Authenticated Data, as described in 2. Compose the Additional Authenticated Data, as described in
Section 5. Section 5.
3. Compose the AEAD nonce 3. Compose the AEAD nonce
* If Observe is not used, compose the AEAD nonce by XORing the * If Observe is not used, compose the AEAD nonce by XORing the
context IV (Recipient IV with the first bit flipped) with the Context IV (Sender IV with the most significant bit in the
padded Partial IV parameter from the request. first byte flipped) with the padded Partial IV parameter from
the request.
* If Observe is used, compose the AEAD nonce by XORing the * If Observe is used, compose the AEAD nonce by XORing the
context IV (Recipient IV with the first bit flipped) with the Context IV (Sender IV) with the Partial IV of the response
partial IV (Sequence Number in network byte order). Increment (Sequence Number in network byte order).
the Sequence Number by one.
4. Encrypt the COSE object using the Sender Key. Compress the COSE 4. Encrypt the COSE object using the Sender Key. Compress the COSE
Object as specified in Appendix A. Object as specified in Section 8.
5. Format the protected CoAP message according to Section 4. The 5. Format the protected CoAP message according to Section 4. The
Object-Security option is added, see Section 4.3.4. Object-Security option is added, see Section 4.3.4.
6. If Observe is used, increment the Sequence Number by one.
7.4. Verifying the Response 7.4. Verifying the Response
A client receiving a response containing the Object-Security option A client receiving a response containing the Object-Security option
SHALL perform the following steps: SHALL perform the following steps:
1. Process outer Block options according to [RFC7959], until all 1. Process outer Block options according to [RFC7959], until all
blocks of the protected CoAP message have been received, see blocks of the protected CoAP message have been received, see
Section 4.3.1.2. Section 4.3.1.2.
2. Retrieve the Recipient Context associated with the Token. 2. Retrieve the Recipient Context associated with the Token.
Decompress the COSE Object (Section 8). If the response is a CON
message and either the decompression or the COSE message fails to
decode, then the client SHALL send an empty ACK back and stop
processing the response. If the response is a NON message and
any of the previous conditions appear, then the client SHALL
simply stop processing the response.
3. If Observe is used, verify the Sequence Number in the 'Partial 1. For Observe notifications, verify the Sequence Number in the
IV' parameter as described in Section 6. 'Partial IV' parameter as described in Section 6.
4. Compose the Additional Authenticated Data, as described in 2. Compose the Additional Authenticated Data, as described in
Section 5. Section 5.
5. Compose the AEAD nonce 3. Compose the AEAD nonce
* If Observe is not used, compose the AEAD nonce by XORing the * If the Observe option is not present in the response, compose
context IV (Recipient IV with the first bit flipped) with the the AEAD nonce by XORing the Context IV (Recipient IV with the
the most significant bit in the first byte flipped) with the
padded Partial IV parameter from the request. padded Partial IV parameter from the request.
* If Observe is used, compose the AEAD nonce by XORing the * If the Observe option is present in the response, compose the
context IV (Recipient IV with the first bit flipped) with the AEAD nonce by XORing the Context IV (Recipient IV) with the
padded Partial IV parameter from the response. padded Partial IV parameter from the response.
6. Decrypt the COSE object using the Recipient Key. 4. Decrypt the COSE object using the Recipient Key.
* If decryption fails, the client MUST stop processing the * If decryption fails, the client MUST stop processing the
response and SHOULD send an 4.01 error message. response and, if the request is a CON message, the client MUST
respond with an empty ACK back.
* If decryption succeeds and Observe is used, update the * If decryption succeeds and Observe is used, update the
Recipient Replay Window, as described in Section 6. Recipient Replay Window, as described in Section 6.
7. Add decrypted options or payload to the unprotected response 5. Add decrypted options or payload to the unprotected response
overwriting any outer E options (see Section 4). The Object- overwriting any outer E options (see Section 4). The Object-
Security option is removed. Security option is removed.
* If Observe is used, replace the Observe value with the 3 least * If Observe is used, replace the Observe value with the 3 least
significant bytes in the sequence number. significant bytes in the sequence number.
8. The unprotected CoAP response is processed according to [RFC7252] 6. The unprotected CoAP response is processed according to [RFC7252]
8. Web Linking 8. OSCOAP Compression
The Concise Binary Object Representation (CBOR) [RFC7049] combines
very small message sizes with extensibility. The CBOR Object Signing
and Encryption (COSE) [I-D.ietf-cose-msg] uses CBOR to create compact
encoding of signed and encrypted data. COSE is however constructed
to support a large number of different stateless use cases, and is
not fully optimized for use as a stateful security protocol, leading
to a larger than necessary message expansion. In this section we
define a simple stateless compression mechanism for OSCOAP, which
significantly reduces the per-packet overhead.
8.1. Encoding of the Object-Security Option
The value of the Object-Security option SHALL be encoded as follows:
o The first byte MUST encode a set of flags and the length of the
Partial IV parameter.
* The three least significant bits encode the Partial IV size.
If their value is 0, the Partial IV is not present in the
compressed message.
* The fourth least significant bit is set to 1 if the kid is
present in the compressed message.
* The fifth-eighth least significant bits (= most significant
half-byte) are reserved and SHALL be set to zero when not in
use.
o The following n bytes (n being the value of the Partial IV size in
the first byte) encode the value of the Partial IV, if the Partial
IV is present (size not 0).
o The following byte encodes the size of the kid parameter, if the
kid is present (flag bit set to 1)
o The following m bytes (m given by the previous byte) encode the
value of the kid, if the kid is present (flag bit set to 1)
o The remainining bytes encode the ciphertext.
The presence of Partial IV and kid in requests and responses is
specified in Section 5, and summarized in Figure 6.
7 6 5 4 3 2 1 0
+-+-+-+-+-+-+-+-+ k: kid flag bit
|0 0 0 0|k|pivsz| pivsz: Partial IV size (3 bits)
+-+-+-+-+-+-+-+-+
+-------+---------+------------+-----------+
| | Request | Resp with- | Resp with |
| | | out observe| observe |
+-------+---------+------------+-----------+
| k | 1 | 0 | 0 |
| pivsz | > 0 | 0 | > 0 |
+-------+---------+------------+-----------+
Figure 6: Flag byte for OSCOAP compression
8.2. Examples
This section provides examples of COSE Objects before and after
OSCOAP compression.
8.2.1. Example: Request
Before compression:
[
h'',
{ 4:h'25', 6:h'05' },
h'aea0155667924dff8a24e4cb35b9'
]
0x83 40 a2 04 41 25 06 41 05 4e ae a0 15 56 67 92
4d ff 8a 24 e4 cb 35 b9 (24 bytes)
After compression:
First byte: 0b00001001 = 0x09
0x09 05 01 25 ae a0 15 56 67 92 4d ff 8a 24 e4 cb
35 b9 (18 bytes)
8.2.2. Example: Response (without Observe)
Before compression:
[
h'',
{},
h'aea0155667924dff8a24e4cb35b9'
]
0x83 40 a0 4e ae a0 15 56 67 92 4d ff 8a 24 e4 cb
35 b9 (18 bytes)
After compression:
First byte: 0b00000000 = 0x00
0x00 ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9
(15 bytes)
8.2.3. Example: Response (with Observe)
Before compression:
[
h'',
{ 6:h'07' },
h'aea0155667924dff8a24e4cb35b9'
]
0x83 40 a1 06 41 07 4e ae a0 15 56 67 92 4d ff
8a 24 e4 cb 35 b9 (21 bytes)
After compression:
First byte: 0b00000001 = 0x01
0x01 07 ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9
(16 bytes)
9. Web Linking
The use of OSCOAP MAY be indicated by a target attribute "osc" in a The use of OSCOAP MAY be indicated by a target attribute "osc" in a
web link [RFC5988] to a CoAP resource. This attribute is a hint web link [RFC5988] to a CoAP resource. This attribute is a hint
indicating that the destination of that link is to be accessed using indicating that the destination of that link is to be accessed using
OSCOAP. Note that this is simply a hint, it does not include any OSCOAP. Note that this is simply a hint, it does not include any
security context material or any other information required to run security context material or any other information required to run
OSCOAP. OSCOAP.
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.
9. Security Considerations 10. Security Considerations
In scenarios with intermediary nodes such as proxies or brokers, In scenarios with intermediary nodes such as proxies or brokers,
transport layer security such as DTLS only protects data hop-by-hop. transport layer security such as DTLS only protects data hop-by-hop.
As a consequence the intermediary nodes can read and modify As a consequence the intermediary nodes can read and modify
information. The trust model where all intermediate nodes are information. The trust model where all intermediate nodes are
considered trustworthy is problematic, not only from a privacy considered trustworthy is problematic, not only from a privacy
perspective, but also from a security perspective, as the perspective, but also from a security perspective, as the
intermediaries are free to delete resources on sensors and falsify intermediaries are free to delete resources on sensors and falsify
commands to actuators (such as "unlock door", "start fire alarm", commands to actuators (such as "unlock door", "start fire alarm",
"raise bridge"). Even in the rare cases, where all the owners of the "raise bridge"). Even in the rare cases, where all the owners of the
skipping to change at page 25, line 44 skipping to change at page 30, line 30
since message layer is excluded from that. since message layer is excluded from that.
The use of COSE to protect CoAP messages as specified in this The use of COSE to protect CoAP messages as specified in this
document requires an established security context. The method to document requires an established security context. The method to
establish the security context described in Section 3.2 is based on a establish the security context described in Section 3.2 is based on a
common shared secret material in client and server, which may be common shared secret material in client and server, which may be
obtained e.g. by using EDHOC [I-D.selander-ace-cose-ecdhe] or the ACE obtained e.g. by using EDHOC [I-D.selander-ace-cose-ecdhe] or the ACE
framework [I-D.ietf-ace-oauth-authz]. An OSCOAP profile of ACE is framework [I-D.ietf-ace-oauth-authz]. An OSCOAP profile of ACE is
described in [I-D.seitz-ace-oscoap-profile]. described in [I-D.seitz-ace-oscoap-profile].
The formula 2^(min(nonce length in bits, 56) - 1) - 1 (Section 6.1)
guarantees unique nonces during the required use the algorithm,
considering the same partial IV and flipped first bit of IV
(Section 5) is used in request and response (which is the reason for
-1 in the exponent). The compression algorithm (Appendix A) assumes
that the partial IV is 56 bits or less (which is the reason for
min(,) in the exponent).
The mandatory-to-implement AEAD algorithm AES-CCM-64-64-128 is The mandatory-to-implement AEAD algorithm AES-CCM-64-64-128 is
selected for broad applicability in terms of message size (2^64 selected for broad applicability in terms of message size (2^64
blocks) and maximum number of messages (2^56). Compatibility with blocks) and maximum number of messages (2^56). Compatibility with
CCM* is achieved by using the algorithm AES-CCM-16-64-128 CCM* is achieved by using the algorithm AES-CCM-16-64-128
[I-D.ietf-cose-msg]. [I-D.ietf-cose-msg].
Most AEAD algorithms require a unique nonce for each message, for Most AEAD algorithms require a unique nonce for each message, for
which the sequence numbers in the COSE message field "Partial IV" is which the sequence numbers in the COSE message field "Partial IV" is
used. If the recipient accepts any sequence number larger than the used. If the recipient accepts any sequence number larger than the
one previously received, then the problem of sequence number one previously received, then the problem of sequence number
synchronization is avoided. With reliable transport it may be synchronization is avoided. With reliable transport it may be
defined that only messages with sequence number which are equal to defined that only messages with sequence number which are equal to
previous sequence number + 1 are accepted. The alternatives to previous sequence number + 1 are accepted. The alternatives to
sequence numbers have their issues: very constrained devices may not sequence numbers have their issues: very constrained devices may not
be able to support accurate time, or to generate and store large be able to support accurate time, or to generate and store large
numbers of random nonces. The requirement to change key at counter numbers of random nonces. The requirement to change key at counter
wrap is a complication, but it also forces the user of this wrap is a complication, but it also forces the user of this
specification to think about implementing key renewal. specification to think about implementing key renewal.
The maximum sequence number to guarantee nonce uniqueness
(Section 6.1) is algorithm dependent. Using AES_CCM, with the
maximum sequence number SHALL be 2^(min(nonce length in bits, 56) -
1) - 1. The "-1" in the exponent stems from the same partial IV and
flipped bit of IV (Section 5) is used in request and response. The
compression algorithm (Section 8) assumes that the partial IV is 56
bits or less (which is the reason for min(,) in the exponent).
The inner block options enable the sender to split large messages The inner block options enable the sender to split large messages
into protected blocks such that the receiving node can verify blocks into protected blocks such that the receiving node can verify blocks
before having received the complete message. The outer block options before having received the complete message. The outer block options
allow for arbitrary proxy fragmentation operations that cannot be allow for arbitrary proxy fragmentation operations that cannot be
verified by the endpoints, but can by policy be restricted in size verified by the endpoints, but can by policy be restricted in size
since the encrypted options allow for secure fragmentation of very since the encrypted options allow for secure fragmentation of very
large messages. A maximum message size (above which the sending large messages. A maximum message size (above which the sending
endpoint fragments the message and the receiving endpoint discards endpoint fragments the message and the receiving endpoint discards
the message, if complying to the policy) may be obtained as part of the message, if complying to the policy) may be obtained as part of
normal resource discovery. normal resource discovery.
skipping to change at page 27, line 5 skipping to change at page 31, line 36
1, 2 and 3 will provide information about where in the range things 1, 2 and 3 will provide information about where in the range things
are. Three different methods to deal with this are: 1) ensure that are. Three different methods to deal with this are: 1) ensure that
all messages are the same length. For example using 0 and 1 instead all messages are the same length. For example using 0 and 1 instead
of 'yes' and 'no'. 2) Use a character which is not part of the of 'yes' and 'no'. 2) Use a character which is not part of the
responses to pad to a fixed length. For example, pad with a space to responses to pad to a fixed length. For example, pad with a space to
three characters. 3) Use the PKCS #7 style padding scheme where m three characters. 3) Use the PKCS #7 style padding scheme where m
bytes are appended each having the value of m. For example, bytes are appended each having the value of m. For example,
appending a 0 to "YES" and two 1's to "NO". This style of padding appending a 0 to "YES" and two 1's to "NO". This style of padding
means that all values need to be padded. means that all values need to be padded.
10. Privacy Considerations 11. Privacy Considerations
Privacy threats executed through intermediate nodes are considerably Privacy threats executed through intermediate nodes are considerably
reduced by means of OSCOAP. End-to-end integrity protection and reduced by means of OSCOAP. End-to-end integrity protection and
encryption of CoAP payload and all options that are not used for encryption of CoAP payload and all options that are not used for
forwarding, provide mitigation against attacks on sensor and actuator forwarding, provide mitigation against attacks on sensor and actuator
communication, which may have a direct impact on the personal sphere. communication, which may have a direct impact on the personal sphere.
The unprotected options (Figure 4) may reveal privacy sensitive The unprotected options (Figure 4) may reveal privacy sensitive
information. In particular Uri-Host SHOULD NOT contain privacy information. In particular Uri-Host SHOULD NOT contain privacy
sensitive information. sensitive information.
CoAP headers sent in plaintext allow for example matching of CON and CoAP headers sent in plaintext allow for example matching of CON and
ACK (CoAP Message Identifier), matching of request and responses ACK (CoAP Message Identifier), matching of request and responses
(Token) and traffic analysis. (Token) and traffic analysis.
11. IANA Considerations 12. IANA Considerations
Note to RFC Editor: Please replace all occurrences of "[[this Note to RFC Editor: Please replace all occurrences of "[[this
document]]" with the RFC number of this specification. document]]" with the RFC number of this specification.
11.1. CoAP Option Numbers Registry 12.1. CoAP Option Numbers Registry
The Object-Security option is added to the CoAP Option Numbers The Object-Security option is added to the CoAP Option Numbers
registry: registry:
+--------+-----------------+-------------------+ +--------+-----------------+-------------------+
| Number | Name | Reference | | Number | Name | Reference |
+--------+-----------------+-------------------+ +--------+-----------------+-------------------+
| TBD | Object-Security | [[this document]] | | TBD | Object-Security | [[this document]] |
+--------+-----------------+-------------------+ +--------+-----------------+-------------------+
11.2. Media Type Registrations 12.2. Media Type Registrations
The "application/oscon" media type is added to the Media Types The "application/oscon" media type is added to the Media Types
registry: registry:
Type name: application Type name: application
Subtype name: oscon Subtype name: oscon
Required parameters: N/A Required parameters: N/A
skipping to change at page 28, line 42 skipping to change at page 33, line 42
Person & email address to contact for further information: Person & email address to contact for further information:
Goeran Selander <goran.selander@ericsson.com> Goeran Selander <goran.selander@ericsson.com>
Intended usage: COMMON Intended usage: COMMON
Restrictions on usage: N/A Restrictions on usage: N/A
Author: Goeran Selander, goran.selander@ericsson.com Author: Goeran Selander, goran.selander@ericsson.com
11.3. CoAP Content Format Registration 12.3. CoAP Content Format Registration
The "application/oscon" content format is added to the CoAP Content The "application/oscon" content format is added to the CoAP Content
Format registry: Format registry:
+-------------------+----------+----+-------------------+ +-------------------+----------+----+-------------------+
| Media type | Encoding | ID | Reference | | Media type | Encoding | ID | Reference |
+-------------------+----------+----+-------------------+ +-------------------+----------+----+-------------------+
| application/oscon | - | 70 | [[this document]] | | application/oscon | - | 70 | [[this document]] |
+-------------------+----------+----+-------------------+ +-------------------+----------+----+-------------------+
12. Acknowledgments 13. Acknowledgments
The following individuals provided input to this document: Christian The following individuals provided input to this document: Christian
Amsuess, Carsten Bormann, Joakim Brorsson, Martin Gunnarsson, Klaus Amsuess, Carsten Bormann, Joakim Brorsson, Martin Gunnarsson, Klaus
Hartke, Jim Schaad, Marco Tiloca, and Malisa Vu&#269;ini&#263;. Hartke, Jim Schaad, Marco Tiloca, and Malisa Vu&#269;ini&#263;.
Ludwig Seitz and Goeran Selander worked on this document as part of Ludwig Seitz and Goeran Selander worked on this document as part of
the CelticPlus project CyberWI, with funding from Vinnova. the CelticPlus project CyberWI, with funding from Vinnova.
13. References 14. References
13.1. Normative References 14.1. Normative References
[I-D.ietf-cose-msg] [I-D.ietf-cose-msg]
Schaad, J., "CBOR Object Signing and Encryption (COSE)", Schaad, J., "CBOR Object Signing and Encryption (COSE)",
draft-ietf-cose-msg-24 (work in progress), November 2016. draft-ietf-cose-msg-24 (work in progress), November 2016.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>. <http://www.rfc-editor.org/info/rfc2119>.
skipping to change at page 30, line 10 skipping to change at page 35, line 10
[RFC7641] Hartke, K., "Observing Resources in the Constrained [RFC7641] Hartke, K., "Observing Resources in the Constrained
Application Protocol (CoAP)", RFC 7641, Application Protocol (CoAP)", RFC 7641,
DOI 10.17487/RFC7641, September 2015, DOI 10.17487/RFC7641, September 2015,
<http://www.rfc-editor.org/info/rfc7641>. <http://www.rfc-editor.org/info/rfc7641>.
[RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in
the Constrained Application Protocol (CoAP)", RFC 7959, the Constrained Application Protocol (CoAP)", RFC 7959,
DOI 10.17487/RFC7959, August 2016, DOI 10.17487/RFC7959, August 2016,
<http://www.rfc-editor.org/info/rfc7959>. <http://www.rfc-editor.org/info/rfc7959>.
13.2. Informative References 14.2. Informative References
[I-D.bormann-6lo-coap-802-15-ie] [I-D.bormann-6lo-coap-802-15-ie]
Bormann, C., "Constrained Application Protocol (CoAP) over Bormann, C., "Constrained Application Protocol (CoAP) over
IEEE 802.15.4 Information Element for IETF", draft- IEEE 802.15.4 Information Element for IETF", draft-
bormann-6lo-coap-802-15-ie-00 (work in progress), April bormann-6lo-coap-802-15-ie-00 (work in progress), April
2016. 2016.
[I-D.greevenbosch-appsawg-cbor-cddl] [I-D.greevenbosch-appsawg-cbor-cddl]
Vigano, C. and H. Birkholz, "CBOR data definition language Birkholz, H., Vigano, C., and C. Bormann, "CBOR data
(CDDL): a notational convention to express CBOR data definition language (CDDL): a notational convention to
structures", draft-greevenbosch-appsawg-cbor-cddl-09 (work express CBOR data structures", draft-greevenbosch-appsawg-
in progress), September 2016. cbor-cddl-10 (work in progress), March 2017.
[I-D.hartke-core-e2e-security-reqs] [I-D.hartke-core-e2e-security-reqs]
Selander, G., Palombini, F., and K. Hartke, "Requirements Selander, G., Palombini, F., and K. Hartke, "Requirements
for CoAP End-To-End Security", draft-hartke-core-e2e- for CoAP End-To-End Security", draft-hartke-core-e2e-
security-reqs-02 (work in progress), January 2017. security-reqs-02 (work in progress), January 2017.
[I-D.ietf-ace-oauth-authz] [I-D.ietf-ace-oauth-authz]
Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and
H. Tschofenig, "Authentication and Authorization for H. Tschofenig, "Authentication and Authorization for
Constrained Environments (ACE)", draft-ietf-ace-oauth- Constrained Environments (ACE)", draft-ietf-ace-oauth-
authz-05 (work in progress), February 2017. authz-06 (work in progress), March 2017.
[I-D.ietf-core-coap-tcp-tls] [I-D.ietf-core-coap-tcp-tls]
Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., Bormann, C., Lemay, S., Tschofenig, H., Hartke, K.,
Silverajan, B., and B. Raymor, "CoAP (Constrained Silverajan, B., and B. Raymor, "CoAP (Constrained
Application Protocol) over TCP, TLS, and WebSockets", Application Protocol) over TCP, TLS, and WebSockets",
draft-ietf-core-coap-tcp-tls-07 (work in progress), March draft-ietf-core-coap-tcp-tls-08 (work in progress), April
2017. 2017.
[I-D.mattsson-core-coap-actuators] [I-D.mattsson-core-coap-actuators]
Mattsson, J., Fornehed, J., Selander, G., and F. Mattsson, J., Fornehed, J., Selander, G., and F.
Palombini, "Controlling Actuators with CoAP", draft- Palombini, "Controlling Actuators with CoAP", draft-
mattsson-core-coap-actuators-02 (work in progress), mattsson-core-coap-actuators-02 (work in progress),
November 2016. November 2016.
[I-D.seitz-ace-oscoap-profile] [I-D.seitz-ace-oscoap-profile]
Seitz, L. and F. Palombini, "OSCOAP profile of ACE", Seitz, L. and F. Palombini, "OSCOAP profile of ACE",
draft-seitz-ace-oscoap-profile-01 (work in progress), draft-seitz-ace-oscoap-profile-01 (work in progress),
October 2016. October 2016.
[I-D.selander-ace-cose-ecdhe] [I-D.selander-ace-cose-ecdhe]
Selander, G., Mattsson, J., and F. Palombini, "Ephemeral Selander, G., Mattsson, J., and F. Palombini, "Ephemeral
Diffie-Hellman Over COSE (EDHOC)", draft-selander-ace- Diffie-Hellman Over COSE (EDHOC)", draft-selander-ace-
cose-ecdhe-04 (work in progress), October 2016. cose-ecdhe-06 (work in progress), April 2017.
[I-D.tiloca-core-multicast-oscoap] [I-D.tiloca-core-multicast-oscoap]
Tiloca, M., Selander, G., and F. Palombini, "Secure group Tiloca, M., Selander, G., and F. Palombini, "Secure group
communication for CoAP", draft-tiloca-core-multicast- communication for CoAP", draft-tiloca-core-multicast-
oscoap-00 (work in progress), October 2016. oscoap-01 (work in progress), March 2017.
[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,
<http://www.rfc-editor.org/info/rfc7228>. <http://www.rfc-editor.org/info/rfc7228>.
Appendix A. OSCOAP Compression Appendix A. Test Vectors
The Concise Binary Object Representation (CBOR) combines very small
message sizes with extensibility. CBOR Object Signing and Encryption
(COSE) uses CBOR to achieve smaller message sizes than JOSE. COSE is
however constructed to support a large number of different stateless
use cases, and is not fully optimized for use as a stateful security
protocol, leading to a larger than necessary message expansion. In
this section we define a simple stateless compression mechanism for
OSCOAP, which significantly reduces the per-packet overhead.
The value of the Object-Security option SHALL in general be encoded
as:
[
Partial IV,
? kid,
ciphertext
]
Furthermore, the type and length for the ciphertext is redundant and
10 bits in the first two bytes are static. The type and length for
the ciphertext SHALL be excluded, and the first sixteen bits in the
above COSE array SHALL be encoded as a single byte:
10000abc 01000def -> 00abcdef
The exception is Responses without Observe that SHALL be encoded as:
ciphertext
A.1. Examples
A.1.1. Example Request
COSE Object Before Compression (24 bytes)
83 a2 04 41 25 06 41 05 a0 4e ae a0 15 56 67 92
4d ff 8a 24 e4 cb 35 b9
[
{
4:h'25',
6:h'05'
},
{},
h'aea0155667924dff8a24e4cb35b9'
]
After Compression (18 bytes)
19 05 41 25 ae a0 15 56 67 92 4d ff 8a 24 e4 cb
35 b9
A.1.2. Example Response
COSE Object Before Compression (18 bytes)
83 a0 a0 4e ae a0 15 56 67 92 4d ff 8a 24 e4 cb
35 b9
[
{},
{},
h'aea0155667924dff8a24e4cb35b9'
]
After Compression (14 bytes)
ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9
A.1.3. Example Response (with Observe)
COSE Object Before Compression (21 bytes)
83 a1 06 41 07 a0 4e ae a0 15 56 67 92 4d ff 8a
24 e4 cb 35 b9
[
{
6:h'07'
},
{},
h'aea0155667924dff8a24e4cb35b9'
]
After Compression (16 bytes)
11 07 ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9
Appendix B. Test Vectors
TODO: This section needs to be updated. TODO: This section needs to be updated.
Appendix C. Examples Appendix B. Examples
This section gives examples of OSCOAP. The message exchanges are This section gives examples of OSCOAP. The message exchanges are
made, based on the assumption that there is a security context made, based on the assumption that there is a security context
established between client and server. For simplicity, these established between client and server. For simplicity, these
examples only indicate the content of the messages without going into examples only indicate the content of the messages without going into
detail of the COSE message format. detail of the COSE message format.
C.1. Secure Access to Sensor B.1. Secure Access to Sensor
This example targets the scenario in Section 3.1 of This example targets the scenario in Section 3.1 of
[I-D.hartke-core-e2e-security-reqs] and illustrates a client [I-D.hartke-core-e2e-security-reqs] and illustrates a client
requesting the alarm status from a server. requesting the alarm status from a server.
Client Proxy Server Client Proxy Server
| | | | | |
+----->| | Code: 0.01 (GET) +----->| | Code: 0.01 (GET)
| GET | | Token: 0x8c | GET | | Token: 0x8c
| | | Object-Security: [kid:5f, seq:42, | | | Object-Security: [kid:5f, seq:42,
skipping to change at page 34, line 30 skipping to change at page 37, line 30
| | 2.05 | Token: 0x7b | | 2.05 | Token: 0x7b
| | | Object-Security: - | | | Object-Security: -
| | | Payload: [{"OFF"}] | | | Payload: [{"OFF"}]
| | | | | |
|<-----+ | Code: 2.05 (Content) |<-----+ | Code: 2.05 (Content)
| 2.05 | | Token: 0x8c | 2.05 | | Token: 0x8c
| | | Object-Security: - | | | Object-Security: -
| | | Payload: [{"OFF"}] | | | Payload: [{"OFF"}]
| | | | | |
Figure 6: Secure Access to Sensor. Square brackets [ ... ] indicate Figure 7: Secure Access to Sensor. Square brackets [ ... ] indicate
a COSE object. Curly brackets { ... } indicate encrypted data. a COSE object. Curly brackets { ... } indicate encrypted data.
Since the method (GET) doesn't allow payload, the Object-Security Since the method (GET) doesn't allow payload, the Object-Security
option carries the COSE object as its value. Since the response code option carries the COSE object as its value. Since the response code
(Content) allows payload, the COSE object is carried as the CoAP (Content) allows payload, the COSE object is carried as the CoAP
payload. payload.
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 sequence number (42). The option Uri-Path ("alarm_status") and a sequence number (42). The option Uri-Path ("alarm_status") and
payload ("OFF") are encrypted. payload ("OFF") are encrypted.
The server verifies that the sequence number has not been received The server verifies that the sequence number has not been received
before. The client verifies that the response is bound to the before. The client verifies that the response is bound to the
request. request.
C.2. Secure Subscribe to Sensor B.2. Secure Subscribe to Sensor
This example targets the scenario in Section 3.2 of This example targets the scenario in Section 3.2 of
[I-D.hartke-core-e2e-security-reqs] and illustrates a client [I-D.hartke-core-e2e-security-reqs] and illustrates a client
requesting subscription to a blood sugar measurement resource (GET requesting subscription to a blood sugar measurement resource (GET
/glucose), first receiving the value 220 mg/dl and then a second /glucose), first receiving the value 220 mg/dl and then a second
value 180 mg/dl. value 180 mg/dl.
Client Proxy Server Client Proxy Server
| | | | | |
+----->| | Code: 0.01 (GET) +----->| | Code: 0.01 (GET)
skipping to change at page 35, line 49 skipping to change at page 38, line 49
| | | Object-Security: - | | | Object-Security: -
| | | Payload: [seq:36, {Content-Format:0, "180"}] | | | Payload: [seq:36, {Content-Format:0, "180"}]
| | | | | |
|<-----+ | Code: 2.05 (Content) |<-----+ | Code: 2.05 (Content)
| 2.05 | | Token: 0x83 | 2.05 | | Token: 0x83
| | | Observe: 000036 | | | Observe: 000036
| | | Object-Security: - | | | Object-Security: -
| | | Payload: [seq:36, {Content-Format:0, "180"}] | | | Payload: [seq:36, {Content-Format:0, "180"}]
| | | | | |
Figure 7: Secure Subscribe to Sensor. Square brackets [ ... ] Figure 8: Secure Subscribe to Sensor. Square brackets [ ... ]
indicate a COSE object. Curly brackets { ... } indicate encrypted indicate a COSE object. Curly brackets { ... } indicate encrypted
data. data.
Since the method (GET) doesn't allow payload, the Object-Security Since the method (GET) doesn't allow payload, the Object-Security
option carries the COSE object as its value. Since the response code option carries the COSE object as its value. Since the response code
(Content) allows payload, the COSE object is carried as the CoAP (Content) allows payload, the COSE object is carried as the CoAP
payload. payload.
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
Sequence Number (15). The COSE header of the responses contains Sequence Number (15). The COSE header of the responses contains
sequence numbers (32 and 36). The options Content-Format (0) and the sequence numbers (32 and 36). The options Content-Format (0) and the
payload ("220" and "180"), are encrypted. The Observe option is payload ("220" and "180"), are encrypted. The Observe option is
integrity protected. The shown Observe values (000032 and 000036) integrity protected. The shown Observe values (000032 and 000036)
are the ones that the client will see after OSCOAP processing. are the ones that the client will see after OSCOAP processing.
The server verifies that the sequence number has not been received The server verifies that the sequence number has not been received
before. The client verifies that the sequence number has not been before. The client verifies that the sequence number has not been
received before and that the responses are bound to the request. received before and that the responses are bound to the request.
Appendix D. Object Security of Content (OSCON) Appendix C. Object Security of Content (OSCON)
TODO: This section needs to be updated. TODO: This section needs to be updated.
OSCOAP protects message exchanges end-to-end between a certain client OSCOAP protects message exchanges end-to-end between a certain client
and a certain server, targeting the security requirements for forward and a certain server, targeting the security requirements for forward
proxy of [I-D.hartke-core-e2e-security-reqs]. In contrast, many use proxy of [I-D.hartke-core-e2e-security-reqs]. In contrast, many use
cases require one and the same message to be protected for, and cases require one and the same message to be protected for, and
verified by, multiple endpoints, see caching proxy section of verified by, multiple endpoints, see caching proxy section of
[I-D.hartke-core-e2e-security-reqs]. Those security requirements can [I-D.hartke-core-e2e-security-reqs]. Those security requirements can
be addressed by protecting essentially the payload/content of be addressed by protecting essentially the payload/content of
skipping to change at page 36, line 50 skipping to change at page 39, line 50
the unprotected CoAP message. We call the result the "protected" the unprotected CoAP message. We call the result the "protected"
CoAP message. CoAP message.
The unprotected payload shall be the plaintext/payload of the COSE The unprotected payload shall be the plaintext/payload of the COSE
object. The 'protected' field of the COSE object 'Headers' shall object. The 'protected' field of the COSE object 'Headers' shall
include the context identifier, both for requests and responses. If include the context identifier, both for requests and responses. If
the unprotected CoAP message includes a Content-Format option, then the unprotected CoAP message includes a Content-Format option, then
the COSE object shall include a protected 'content type' field, whose the COSE object shall include a protected 'content type' field, whose
value is set to the unprotected message Content-Format value. The value is set to the unprotected message Content-Format value. The
Content-Format option of the protected CoAP message shall be replaced Content-Format option of the protected CoAP message shall be replaced
with "application/oscon" (Section 11) with "application/oscon" (Section 12)
The COSE object shall be protected (encrypted) and verified The COSE object shall be protected (encrypted) and verified
(decrypted) as described in ([I-D.ietf-cose-msg]). (decrypted) as described in ([I-D.ietf-cose-msg]).
Most AEAD algorithms require a unique nonce for each message. Most AEAD algorithms require a unique nonce for each message.
Sequence numbers for partial IV as specified for OSCOAP may be used Sequence numbers for partial IV as specified for OSCOAP may be used
for replay protection as described in Section 6. The use of time for replay protection as described in Section 6. The use of time
stamps in the COSE header parameter 'operation time' stamps in the COSE header parameter 'operation time'
[I-D.ietf-cose-msg] for freshness may be used. [I-D.ietf-cose-msg] for freshness may be used.
OSCON shall not be used in cases where CoAP header fields (such as OSCON shall not be used in cases where CoAP header fields (such as
Code or Version) or CoAP options need to be integrity protected or Code or Version) or CoAP options need to be integrity protected or
encrypted. OSCON shall not be used in cases which require a secure encrypted. OSCON shall not be used in cases which require a secure
binding between request and response. binding between request and response.
The scenarios in Sections 3.3 - 3.5 of The scenarios in Sections 3.3 - 3.5 of
[I-D.hartke-core-e2e-security-reqs] assume multiple recipients for a [I-D.hartke-core-e2e-security-reqs] assume multiple recipients for a
particular content. In this case the use of symmetric keys does not particular content. In this case the use of symmetric keys does not
provide data origin authentication. Therefore the COSE object should provide data origin authentication. Therefore the COSE object should
in general be protected with a digital signature. in general be protected with a digital signature.
D.1. Overhead OSCON C.1. Overhead OSCON
In general there are four different kinds of modes that need to be In general there are four different kinds of modes that need to be
supported: message authentication code, digital signature, supported: message authentication code, digital signature,
authenticated encryption, and symmetric encryption + digital authenticated encryption, and symmetric encryption + digital
signature. The use of digital signature is necessary for signature. The use of digital signature is necessary for
applications with many legitimate recipients of a given message, and applications with many legitimate recipients of a given message, and
where data origin authentication is required. where data origin authentication is required.
To distinguish between these different cases, the tagged structures To distinguish between these different cases, the tagged structures
of COSE are used (see Section 2 of [I-D.ietf-cose-msg]). of COSE are used (see Section 2 of [I-D.ietf-cose-msg]).
skipping to change at page 38, line 11 skipping to change at page 41, line 11
("Cid+Seq" column) and of the Tag ("MAC"/"SIG"/"TAG"). The "Message ("Cid+Seq" column) and of the Tag ("MAC"/"SIG"/"TAG"). The "Message
OH" column shows the total expansions of the CoAP message size, while OH" column shows the total expansions of the CoAP message size, while
the "COSE OH" column is calculated from the previous columns. the "COSE OH" column is calculated from the previous columns.
Overhead incurring from CBOR encoding is also included in the COSE Overhead incurring from CBOR encoding is also included in the COSE
overhead count. overhead count.
To make it easier to read, COSE objects are represented using CBOR's To make it easier to read, COSE objects are represented using CBOR's
diagnostic notation rather than a binary dump. diagnostic notation rather than a binary dump.
D.2. MAC Only C.2. MAC Only
This example is based on HMAC-SHA256, with truncation to 8 bytes This example is based on HMAC-SHA256, with truncation to 8 bytes
(HMAC 256/64). (HMAC 256/64).
Since the key is implicitly known by the recipient, the Since the key is implicitly known by the recipient, the
COSE_Mac0_Tagged structure is used (Section 6.2 of COSE_Mac0_Tagged structure is used (Section 6.2 of
[I-D.ietf-cose-msg]). [I-D.ietf-cose-msg]).
The object in COSE encoding gives: The object in COSE encoding gives:
skipping to change at page 38, line 35 skipping to change at page 41, line 35
{04:h'a1534e3c', {04:h'a1534e3c',
06:h'a3'} 06:h'a3'}
{}, # unprotected {}, # unprotected
h'', # payload h'', # payload
MAC # truncated 8-byte MAC MAC # truncated 8-byte MAC
] ]
) )
This COSE object encodes to a total size of 26 bytes. This COSE object encodes to a total size of 26 bytes.
Figure 8 summarizes these results. Figure 9 summarizes these results.
+------------------+-----+-----+---------+------------+ +------------------+-----+-----+---------+------------+
| Structure | Tid | MAC | COSE OH | Message OH | | Structure | Tid | MAC | COSE OH | Message OH |
+------------------+-----+-----+---------+------------+ +------------------+-----+-----+---------+------------+
| COSE_Mac0_Tagged | 5 B | 8 B | 13 B | 26 B | | COSE_Mac0_Tagged | 5 B | 8 B | 13 B | 26 B |
+------------------+-----+-----+---------+------------+ +------------------+-----+-----+---------+------------+
Figure 8: Message overhead for a 5-byte Tid using HMAC 256/64 Figure 9: Message overhead for a 5-byte Tid using HMAC 256/64
D.3. Signature Only C.3. Signature Only
This example is based on ECDSA, with a signature of 64 bytes. This example is based on ECDSA, with a signature of 64 bytes.
Since only one signature is used, the COSE_Sign1_Tagged structure is Since only one signature is used, the COSE_Sign1_Tagged structure is
used (Section 4.2 of [I-D.ietf-cose-msg]). used (Section 4.2 of [I-D.ietf-cose-msg]).
The object in COSE encoding gives: The object in COSE encoding gives:
997( # COSE_Sign1_Tagged 997( # COSE_Sign1_Tagged
[ [
skipping to change at page 39, line 18 skipping to change at page 42, line 18
{04:h'a1534e3c', {04:h'a1534e3c',
06:h'a3'} 06:h'a3'}
{}, # unprotected {}, # unprotected
h'', # payload h'', # payload
SIG # 64-byte signature SIG # 64-byte signature
] ]
) )
This COSE object encodes to a total size of 83 bytes. This COSE object encodes to a total size of 83 bytes.
Figure 9 summarizes these results. Figure 10 summarizes these results.
+-------------------+-----+------+---------+------------+ +-------------------+-----+------+---------+------------+
| Structure | Tid | SIG | COSE OH | Message OH | | Structure | Tid | SIG | COSE OH | Message OH |
+-------------------+-----+------+---------+------------+ +-------------------+-----+------+---------+------------+
| COSE_Sign1_Tagged | 5 B | 64 B | 14 B | 83 bytes | | COSE_Sign1_Tagged | 5 B | 64 B | 14 B | 83 bytes |
+-------------------+-----+------+---------+------------+ +-------------------+-----+------+---------+------------+
Figure 9: Message overhead for a 5-byte Tid using 64 byte ECDSA Figure 10: Message overhead for a 5-byte Tid using 64 byte ECDSA
signature. signature.
D.4. Authenticated Encryption with Additional Data (AEAD) C.4. Authenticated Encryption with Additional Data (AEAD)
This example is based on AES-CCM with the Tag truncated to 8 bytes. This example is based on AES-CCM with the Tag truncated to 8 bytes.
Since the key is implicitly known by the recipient, the Since the key is implicitly known by the recipient, the
COSE_Encrypt0_Tagged structure is used (Section 5.2 of COSE_Encrypt0_Tagged structure is used (Section 5.2 of
[I-D.ietf-cose-msg]). [I-D.ietf-cose-msg]).
The object in COSE encoding gives: The object in COSE encoding gives:
993( # COSE_Encrypt0_Tagged 993( # COSE_Encrypt0_Tagged
[ [
h'a20444a1534e3c0641a3', # protected: h'a20444a1534e3c0641a3', # protected:
{04:h'a1534e3c', {04:h'a1534e3c',
06:h'a3'} 06:h'a3'}
{}, # unprotected {}, # unprotected
TAG # ciphertext + truncated 8-byte TAG ciphertext # ciphertext including truncated 8-byte TAG
] ]
) )
This COSE object encodes to a total size of 25 bytes. This COSE object encodes to a total size of 25 bytes.
Figure 10 summarizes these results. Figure 11 summarizes these results.
+----------------------+-----+-----+---------+------------+ +----------------------+-----+-----+---------+------------+
| Structure | Tid | TAG | COSE OH | Message OH | | Structure | Tid | TAG | COSE OH | Message OH |
+----------------------+-----+-----+---------+------------+ +----------------------+-----+-----+---------+------------+
| COSE_Encrypt0_Tagged | 5 B | 8 B | 12 B | 25 bytes | | COSE_Encrypt0_Tagged | 5 B | 8 B | 12 B | 25 bytes |
+----------------------+-----+-----+---------+------------+ +----------------------+-----+-----+---------+------------+
Figure 10: Message overhead for a 5-byte Tid using AES_128_CCM_8. Figure 11: Message overhead for a 5-byte Tid using AES_128_CCM_8.
D.5. Symmetric Encryption with Asymmetric Signature (SEAS) C.5. Symmetric Encryption with Asymmetric Signature (SEAS)
This example is based on AES-CCM and ECDSA with 64 bytes signature. This example is based on AES-CCM and ECDSA with 64 bytes signature.
The same assumption on the security context as in Appendix D.4. COSE The same assumption on the security context as in Appendix C.4. COSE
defines the field 'counter signature w/o headers' that is used here defines the field 'counter signature w/o headers' that is used here
to sign a COSE_Encrypt0_Tagged message (see Section 3 of to sign a COSE_Encrypt0_Tagged message (see Section 3 of
[I-D.ietf-cose-msg]). [I-D.ietf-cose-msg]).
The object in COSE encoding gives: The object in COSE encoding gives:
993( # COSE_Encrypt0_Tagged 993( # COSE_Encrypt0_Tagged
[ [
h'a20444a1534e3c0641a3', # protected: h'a20444a1534e3c0641a3', # protected:
{04:h'a1534e3c', {04:h'a1534e3c',
06:h'a3'} 06:h'a3'}
{9:SIG}, # unprotected: {9:SIG}, # unprotected:
09: 64 bytes signature 09: 64 bytes signature
TAG # ciphertext + truncated 8-byte TAG ciphertext # ciphertext including truncated 8-byte TAG
] ]
) )
This COSE object encodes to a total size of 92 bytes. This COSE object encodes to a total size of 92 bytes.
Figure 11 summarizes these results. Figure 12 summarizes these results.
+----------------------+-----+-----+------+---------+------------+ +----------------------+-----+-----+------+---------+------------+
| Structure | Tid | TAG | SIG | COSE OH | Message OH | | Structure | Tid | TAG | SIG | COSE OH | Message OH |
+----------------------+-----+-----+------+---------+------------+ +----------------------+-----+-----+------+---------+------------+
| COSE_Encrypt0_Tagged | 5 B | 8 B | 64 B | 15 B | 92 B | | COSE_Encrypt0_Tagged | 5 B | 8 B | 64 B | 15 B | 92 B |
+----------------------+-----+-----+------+---------+------------+ +----------------------+-----+-----+------+---------+------------+
Figure 11: Message overhead for a 5-byte Tid using AES-CCM Figure 12: Message overhead for a 5-byte Tid using AES-CCM
countersigned with ECDSA. countersigned with ECDSA.
Authors' Addresses Authors' Addresses
Goeran Selander Goeran Selander
Ericsson AB Ericsson AB
Email: goran.selander@ericsson.com Email: goran.selander@ericsson.com
John Mattsson John Mattsson
Ericsson AB Ericsson AB
 End of changes. 133 change blocks. 
394 lines changed or deleted 533 lines changed or added

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