draft-ietf-core-object-security-01.txt   draft-ietf-core-object-security-02.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: June 22, 2017 Ericsson AB Expires: September 14, 2017 Ericsson AB
L. Seitz L. Seitz
SICS Swedish ICT SICS Swedish ICT
December 19, 2016 March 13, 2017
Object Security of CoAP (OSCOAP) Object Security of CoAP (OSCOAP)
draft-ietf-core-object-security-01 draft-ietf-core-object-security-02
Abstract Abstract
This memo defines Object Security of CoAP (OSCOAP), a method for This document defines Object Security of CoAP (OSCOAP), a method for
application layer protection of message exchanges with the application layer protection of the Constrained Application Protocol
Constrained Application Protocol (CoAP), using the CBOR Object (CoAP), using the CBOR Object Signing and Encryption (COSE). OSCOAP
Signing and Encryption (COSE) format. OSCOAP provides end-to-end provides end-to-end encryption, integrity and replay protection to
encryption, integrity and replay protection to CoAP payload, options, CoAP payload, options, and header fields, as well as a secure message
and header fields, as well as a secure binding between CoAP request binding. OSCOAP is designed for constrained nodes and networks and
and response messages. The use of OSCOAP is signaled with the CoAP can be used across intermediaries and over any layer. The use of
option Object-Security, also defined in this memo. OSCOAP is signaled with the CoAP option Object-Security, also defined
in this document.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at 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 June 22, 2017. This Internet-Draft will expire on September 14, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2016 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
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . 8
3.2.1. Derivation of Sender Key/IV, Recipient Key/IV . . . . 10 3.3. Requirements on the Security Context Parameters . . . . . 10
3.2.2. Context Identifier . . . . . . . . . . . . . . . . . 11
3.2.3. Sender ID and Recipient ID . . . . . . . . . . . . . 11
3.2.4. Sequence Numbers and Replay Window . . . . . . . . . 11
4. Protected CoAP Message Fields . . . . . . . . . . . . . . . . 11 4. Protected CoAP Message Fields . . . . . . . . . . . . . . . . 11
4.1. CoAP Payload . . . . . . . . . . . . . . . . . . . . . . 12 4.1. CoAP Payload . . . . . . . . . . . . . . . . . . . . . . 11
4.2. CoAP Header . . . . . . . . . . . . . . . . . . . . . . . 12 4.2. CoAP Header . . . . . . . . . . . . . . . . . . . . . . . 12
4.3. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 13 4.3. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 12
4.3.1. Class E Options . . . . . . . . . . . . . . . . . . . 15
4.3.2. Class A Options . . . . . . . . . . . . . . . . . . . 17
5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 17 5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 17
5.1. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 19 5.1. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 18
5.2. Additional Authenticated Data . . . . . . . . . . . . . . 19 5.2. Additional Authenticated Data . . . . . . . . . . . . . . 19
6. Protecting CoAP Messages . . . . . . . . . . . . . . . . . . 21 6. Sequence Numbers, Replay, Message Binding, and Freshness . . 20
6.1. Replay and Freshness Protection . . . . . . . . . . . . . 21 6.1. AEAD Nonce Uniqueness . . . . . . . . . . . . . . . . . . 20
6.2. Protecting the Request . . . . . . . . . . . . . . . . . 22 6.2. Replay Protection . . . . . . . . . . . . . . . . . . . . 20
6.3. Verifying the Request . . . . . . . . . . . . . . . . . . 23 6.3. Sequence Number and Replay Window State . . . . . . . . . 20
6.4. Protecting the Response . . . . . . . . . . . . . . . . . 24 6.4. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 21
6.5. Verifying the Response . . . . . . . . . . . . . . . . . 25 6.5. Delay and Mismatch Attacks . . . . . . . . . . . . . . . 21
7. Security Considerations . . . . . . . . . . . . . . . . . . . 26 7. Processing . . . . . . . . . . . . . . . . . . . . . . . . . 22
8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 28 7.1. Protecting the Request . . . . . . . . . . . . . . . . . 22
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 7.2. Verifying the Request . . . . . . . . . . . . . . . . . . 22
9.1. CoAP Option Numbers Registry . . . . . . . . . . . . . . 28 7.3. Protecting the Response . . . . . . . . . . . . . . . . . 23
9.2. COSE Header Parameters Registry . . . . . . . . . . . . . 29 7.4. Verifying the Response . . . . . . . . . . . . . . . . . 23
9.3. Media Type Registrations . . . . . . . . . . . . . . . . 29 8. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 24
9.4. CoAP Content Format Registration . . . . . . . . . . . . 30 9. Security Considerations . . . . . . . . . . . . . . . . . . . 25
10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 31 10. Privacy Considerations . . . . . . . . . . . . . . . . . . . 27
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 31 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27
11.1. Normative References . . . . . . . . . . . . . . . . . . 31 11.1. CoAP Option Numbers Registry . . . . . . . . . . . . . . 27
11.2. Informative References . . . . . . . . . . . . . . . . . 32 11.2. Media Type Registrations . . . . . . . . . . . . . . . . 27
Appendix A. Overhead . . . . . . . . . . . . . . . . . . . . . . 33 11.3. CoAP Content Format Registration . . . . . . . . . . . . 28
A.1. Length of the Object-Security Option . . . . . . . . . . 33 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 29
A.2. Size of the COSE Object . . . . . . . . . . . . . . . . . 33 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 29
A.3. Message Expansion . . . . . . . . . . . . . . . . . . . . 34 13.1. Normative References . . . . . . . . . . . . . . . . . . 29
A.4. Example . . . . . . . . . . . . . . . . . . . . . . . . . 35 13.2. Informative References . . . . . . . . . . . . . . . . . 30
Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 36 Appendix A. OSCOAP Compression . . . . . . . . . . . . . . . . . 31
B.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 36 A.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 32
B.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 38
Appendix C. Object Security of Content (OSCON) . . . . . . . . . 39 Appendix B. Test Vectors . . . . . . . . . . . . . . . . . . . . 33
C.1. Overhead OSCON . . . . . . . . . . . . . . . . . . . . . 40 Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 33
C.2. MAC Only . . . . . . . . . . . . . . . . . . . . . . . . 41 C.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 33
C.3. Signature Only . . . . . . . . . . . . . . . . . . . . . 42 C.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 34
C.4. Authenticated Encryption with Additional Data (AEAD) . . 43 Appendix D. Object Security of Content (OSCON) . . . . . . . . . 36
C.5. Symmetric Encryption with Asymmetric Signature (SEAS) . . 43 D.1. Overhead OSCON . . . . . . . . . . . . . . . . . . . . . 37
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 44 D.2. MAC Only . . . . . . . . . . . . . . . . . . . . . . . . 38
D.3. Signature Only . . . . . . . . . . . . . . . . . . . . . 38
D.4. Authenticated Encryption with Additional Data (AEAD) . . 39
D.5. Symmetric Encryption with Asymmetric Signature (SEAS) . . 40
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 40
1. Introduction 1. Introduction
The Constrained Application Protocol (CoAP) [RFC7252] is a web The Constrained Application Protocol (CoAP) is a web application
application protocol, designed for constrained nodes and networks protocol, designed for constrained nodes and networks [RFC7228].
[RFC7228]. CoAP specifies the use of proxies for scalability and CoAP specifies the use of proxies for scalability and efficiency. At
efficiency. At the same time CoAP references DTLS [RFC6347] for the same time CoAP [RFC7252] references DTLS [RFC6347] for security.
security. Proxy operations on CoAP messages require DTLS to be Proxy operations on CoAP messages require DTLS to be terminated at
terminated at the proxy. The proxy therefore not only has access to the proxy. The proxy therefore not only has access to the data
the data required for performing the intended proxy functionality, required for performing the intended proxy functionality, but is also
but is also able to eavesdrop on, or manipulate any part of the CoAP able to eavesdrop on, or manipulate any part of the CoAP payload and
payload and metadata, in transit between client and server. The metadata, in transit between client and server. The proxy can also
proxy can also inject, delete, or reorder packages without being inject, delete, or reorder packages without being protected or
protected or detected by DTLS. detected by DTLS.
This memo 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. forwarding case. In addition to the core features defined in
[RFC7252], OSCOAP supports Observe [RFC7641] and Blockwise [RFC7959].
The solution provides an in-layer security protocol for CoAP which OSCOAP is designed for constrained nodes and networks and provides an
does not depend on underlying layers and is therefore favorable for in-layer security protocol for CoAP which does not depend on
providing security for "CoAP over foo", e.g. CoAP messages passing underlying layers. OSCOAP can be used anywhere that CoAP can be
over both unreliable and reliable transport used, including unreliable transport [RFC7228], reliable transport
[I-D.ietf-core-coap-tcp-tls], CoAP over IEEE 802.15.4 IE [I-D.ietf-core-coap-tcp-tls], and non-IP transport
[I-D.bormann-6lo-coap-802-15-ie]. [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
use of OSCOAP does not affect the URI scheme and OSCOAP can therefore
be used with any URI scheme defined for CoAP. The application
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, and [I-D.ietf-cose-msg], providing end-to-end encryption, integrity,
replay protection. The use of OSCOAP is signaled with the CoAP replay protection, and secure message binding. The use of OSCOAP is
option Object-Security, also defined in this memo. The solution signaled with the CoAP option Object-Security, defined in Section 2.
transforms an unprotected CoAP message into a protected CoAP message OSCOAP provides protection of CoAP payload, certain options, and
in the following way: the unprotected CoAP message is protected by header fields. The solution transforms an unprotected CoAP message
including payload (if present), certain options, and header fields in into a protected CoAP message in the following way: the unprotected
a COSE object. The message fields that have been encrypted are CoAP message is protected by including payload (if present), certain
removed from the message whereas the Object-Security option and the options, and header fields in a COSE object. The message fields that
COSE object are added. We call the result the "protected" CoAP have been encrypted are removed from the message whereas the Object-
message. Thus OSCOAP is a security protocol based on the exchange of Security option and the COSE object are added, see Figure 1.
protected CoAP messages (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:{..., |
| Object-Security:-}, Payload:COSE object] | | Object-Security:-}, Payload:COSE object] |
|<----------------------------------------------+ |<----------------------------------------------+
| | | |
Figure 1: Sketch of OSCOAP Figure 1: Sketch of OSCOAP
OSCOAP provides protection of CoAP payload, certain options, and OSCOAP may be used in extremely constrained settings, where CoAP over
header fields, as well as a secure binding between CoAP request and DTLS may be prohibitive e.g. due to large code size. Alternatively,
response messages. OSCOAP provides replay protection, but like DTLS, OSCOAP can be combined with DTLS, thereby enabling end-to-end
OSCOAP only provides relative freshness in the sense that the security of e.g. CoAP payload and options, in combination with hop-
sequence numbers allows a recipient to determine the relative order by-hop protection of the entire CoAP message, during transport
of messages. For applications having stronger demands on freshness between end-point and intermediary node. Examples of the use of
(e.g. control of actuators), OSCOAP needs to be augmented with OSCOAP are given in Appendix C.
mechanisms providing absolute freshness
[I-D.mattsson-core-coap-actuators].
OSCOAP may be used in extremely constrained settings, where DTLS
cannot be supported. Alternatively, OSCOAP can be combined with
DTLS, thereby enabling end-to-end security of CoAP payload, in
combination with hop-by-hop protection of the entire CoAP message,
during transport between end-point and intermediary node. Examples
of the use of 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 C. object security of content (OSCON) and it is defined in Appendix D.
1.1. Terminology 1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. These document are to be interpreted as described in [RFC2119]. These
words may also appear in this document in lowercase, absent their words may also appear in this document in lowercase, absent their
normative meanings. normative meanings.
Readers are expected to be familiar with the terms and concepts Readers are expected to be familiar with the terms and concepts
described in [RFC7252] and [RFC7641]. Readers are also expected to described in CoAP [RFC7252], Observe [RFC7641], Blockwise [RFC7959],
be familiar with [RFC7049] and understand COSE [I-D.ietf-cose-msg], CBOR [RFC7049], CDDL
[I-D.greevenbosch-appsawg-cbor-cddl]. Terminology for constrained
environments, such as "constrained device", "constrained-node
network", is defined in [RFC7228].
2. The Object-Security Option
The Object-Security option indicates that OSCOAP is used to protect [I-D.greevenbosch-appsawg-cbor-cddl], and constrained environments
the CoAP message exchange. The protection is achieved by means of a [RFC7228].
COSE object included in the protected CoAP message, as detailed in
Section 5.
The Object-Security option is critical, safe to forward, part of the 2. The Object-Security Option
cache key, and not repeatable. Figure 2 illustrates the structure of
the Object-Security option.
A CoAP proxy SHOULD NOT cache a response to a request with an Object- The Object-Security option (see Figure 2) indicates that OSCOAP is
Security option, since the response is only applicable to the used to protect the CoAP message exchange. The Object-Security
original client's request. The Object-Security option is included in option is critical, safe to forward, part of the cache key, not
the cache key for backward compatibility with proxies not recognizing repeatable, and opaque.
the Object-Security option. The effect of this is that messages with
the Object-Security option will never generate cache hits. To
further prevent caching, a Max-Age option with value zero SHOULD be
added to the protected CoAP responses.
+-----+---+---+---+---+-----------------+--------+--------+ +-----+---+---+---+---+-----------------+--------+--------+
| No. | C | U | N | R | Name | Format | Length | | No. | C | U | N | R | Name | Format | Length |
+-----+---+---+---+---+-----------------+--------+--------| +-----+---+---+---+---+-----------------+--------+--------|
| TBD | x | | | | Object-Security | opaque | 0- | | TBD | x | | | | Object-Security | opaque | 0- |
+-----+---+---+---+---+-----------------+--------+--------+ +-----+---+---+---+---+-----------------+--------+--------+
C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable
Figure 2: The Object-Security Option Figure 2: The Object-Security Option
The length of the Object-Security option depends on whether the A successful response to a request with the Object-Security option
unprotected message allows payload, on the set of options that are SHALL contain the Object-Security option. A CoAP endpoint SHOULD NOT
included in the unprotected message, the length of the integrity tag, cache a response to a request with an Object-Security option, since
and the length of the information identifying the security context. the response is only applicable to the original client's request.
The Object-Security option is included in the cache key for backward
compatibility with proxies not recognizing the Object-Security
option. The effect is that messages with the Object-Security option
will never generate cache hits. For Max-Age processing, see
Section 4.3.1.1.
o If the unprotected message allows payload, then the COSE object is The protection is achieved by means of a COSE object (see Section 5)
the payload of the protected message (see Section 6.2 and included in the protected CoAP message. The placement of the COSE
Section 6.4), and the Object-Security option has length zero. An object depends on whether the method/response code allows payload
endpoint receiving a CoAP message with payload, that also contains (see [RFC7252]):
a non-empty Object-Security option SHALL treat it as malformed and
reject it.
o If the unprotected message does not allow payload, then the COSE o If the method/response code allows payload, then the compressed
object is the value of the Object-Security option and the length COSE object is the payload of the protected message, and the
of the Object-Security option is equal to the size of the COSE Object-Security option has length zero. An endpoint receiving a
object. An endpoint receiving a CoAP message without payload, CoAP message with payload, that also contains a non-empty Object-
that also contains an empty Object-Security option SHALL treat it Security option SHALL treat it as malformed and reject it.
as malformed and reject it.
Note that according to [RFC7252], new Methods and Response Codes o If the method/response code does not allow payload, then the
should specify if the payload is optional, required or not allowed compressed COSE object is the value of the Object-Security option
(Section 12.1.2) in the message, and in case this is not defined the and the length of the Object-Security option is equal to the size
sender must not include a payload (Section 5.5). Thus, in this case, of the compressed COSE object. An endpoint receiving a CoAP
the COSE object MUST be the value of the Object-Security option. message without payload, that also contains an empty Object-
Security option SHALL treat it as malformed and reject it.
More details about the message overhead caused by the Object-Security The size of the COSE object depends on whether the method/response
option are given in Appendix A. 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
algorithm, the length of the information identifying the security
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. The specification requires that client and Data (AEAD) algorithm between a CoAP client and a CoAP server. An
server establish a security context to apply to the COSE objects implementation supporting this specification MAY only implement the
protecting the CoAP messages. In this section we define the security client part or MAY only the server part.
context, and also specify how to derive the initial security contexts
in client and server based on common shared secret and a key The specification requires that client and server establish a
derivation function (KDF). security context to apply to the COSE objects protecting the CoAP
messages. In this section we define the security context, and also
specify how to derive the initial security contexts in client and
server based on common shared secret and a key derivation function
(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. Each security carry out the cryptographic operations in OSCOAP. For each endpoint,
context is identified by a Context Identifier. A Context Identifier the security context is composed of a "Common Context", a "Sender
that is no longer in use can be reassigned to a new security context. Context", and a "Recipient Context".
For each endpoint, the security context is composed by a "Common The endpoints protect messages to send using the Sender Context and
Context", a "Sender Context" and a "Recipient Context". The
endpoints protect messages to send using the Sender Context and
verify messages received using the Recipient Context, both contexts verify messages received using the Recipient Context, both contexts
being derived from the Common Context and other data. Each endpoint being derived from the Common Context and other data. Clients need
has a unique ID used to derive its Sender Context, this identifier is to be able to retrieve the correct security context to use.
called "Sender ID". The Recipient Context is derived with the other
endpoint's ID, which is called "Recipient ID". The Recipient ID is
thus the ID of the endpoint from which a CoAP message is received.
In communication between two endpoints, the Sender Context of one
endpoint matches the Recipient Context of the other endpoint, and
vice versa. Thus the two security contexts identified by the same
Context Identifiers in the two endpoints are not the same, but they
are partly mirrored. Retrieval and use of the security context are
shown in Figure 3."
.-Cid = Cid1-. .-Cid = Cid1-. An endpoint uses its Sender ID (SID) to derive its Sender Context,
and the other endpoint uses the same ID, now called Recipient ID
(RID), to derive its Recipient Context. In communication between two
endpoints, the Sender Context of one endpoint matches the Recipient
Context of the other endpoint, and vice versa. Thus the two security
contexts identified by the same IDs in the two endpoints are not the
same, but they are partly mirrored. Retrieval and use of the
security context are shown in Figure 3.
.------------. .------------.
| 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 | Cid = Cid1, ...] | Protect request with | kid = SID, ...] |
Sender Context +---------------------->| Retrieve context with Sender Context +---------------------->| Retrieve context with
| | Cid = Cid1 | | RID = SID
| | 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
The Common Context contains the following parameters: The Common Context contains the following parameters:
o Context Identifier (Cid). Variable length byte string that
identifies the security context. Its value is immutable once the
security context is established.
o Algorithm (Alg). Value that identifies the COSE AEAD algorithm to o Algorithm (Alg). Value that identifies the COSE AEAD algorithm to
use for encryption. Its value is immutable once the security use for encryption. Its value is immutable once the security
context is established. context is established.
o Base Key (master_secret). Variable length, uniformly random byte o Master Secret. Variable length, uniformly random byte string
string containing the key used to derive traffic keys and IVs. containing the key used to derive traffic keys and IVs. Its value
Its value is immutable once the security context is established. is immutable once the security context is established.
o Master Salt (OPTIONAL). Variable length byte string containing
the salt used to derive traffic keys and IVs. Its value is
immutable once the security context is established.
The Sender Context contains the following parameters: The Sender Context contains the following parameters:
o Sender ID. Variable length byte string identifying the endpoint o Sender ID. Variable length byte string identifying the Sender
itself. Its value is immutable once the security context is Context. Its value is immutable once the security context is
established. established.
o Sender Key. Byte string containing the symmetric key to protect o Sender Key. Byte string containing the symmetric key to protect
messages to send. Length is determined by Algorithm. Its value messages to send. Derived from Common Context and Sender ID.
is immutable once the security context is established. Length is determined by Algorithm. Its value is immutable once
the security context is established.
o Sender IV. Byte string containing the fixed context IV o Sender IV. Byte string containing the IV to protect messages to
[I-D.ietf-cose-msg]) to protect messages to send. Length is send. Derived from Common Context and Sender ID. Length is
determined by Algorithm. Its value is immutable once the security determined by Algorithm. Its value is immutable once the security
context is established. context is established.
o Sender Sequence Number. Non-negative integer enumerating the COSE o Sequence Number. Non-negative integer used to protect requests
objects that the endpoint sends using the context. Used as and observe responses to send. Used as partial IV
partial IV [I-D.ietf-cose-msg] to generate unique nonces for the [I-D.ietf-cose-msg] to generate unique nonces for the AEAD.
AEAD. Maximum value is determined by Algorithm. Maximum value is determined by Algorithm.
The Recipient Context contains the following parameters: The Recipient Context contains the following parameters:
o Recipient ID. Variable length byte string identifying the o Recipient ID. Variable length byte string identifying the
endpoint messages are received from. Its value is immutable once Recipient Context. Its value is immutable once the security
the security context is established. context is established.
o Recipient Key. Byte string containing the symmetric key to verify o Recipient Key. Byte string containing the symmetric key to verify
messages received. Length is determined by the Algorithm. Its messages received. Derived from Common Context and Recipient ID.
value is immutable once the security context is established. Length is determined by the Algorithm. Its value is immutable
once the security context is established.
o Recipient IV. Byte string containing the context IV to verify
messages received. Length is determined by Algorithm. Its value
is immutable once the security context is established.
o Recipient Replay Window. The replay protection window for
messages received.
The 3-tuple (Cid, Sender ID, Partial IV) is called Transaction
Identifier (Tid), and SHALL be unique for each Base Key. The Tid is
used as a unique challenge in the COSE object of the protected CoAP
request. The Tid is part of the Additional Authenticated Data (AAD,
see Section 5) of the protected CoAP response message, which is how
responses are bound to requests.
3.2. Derivation of Security Context Parameters o Recipient IV. Byte string containing the IV to verify messages
received. Derived from Common Context and Recipient ID. Length
is determined by Algorithm. Its value is immutable once the
security context is established.
This section describes how to derive the initial parameters in the o Replay Window. The replay window to verify requests and observe
security context, given a small set of input parameters. We also responses received.
give indications on how applications should select the input
parameters.
The following input parameters SHALL be pre-established: An endpoint may free up memory by not storing the Sender Key, Sender
IV, Recipient Key, and Recipient IV, deriving them from the Common
Context when needed. Alternatively, an endpoint may free up memory
by not storing the Master Secret and Master Salt after the other
parameters have been derived.
o Context Identifier (Cid) The endpoints MAY interchange the client and server roles while
o Base Key (master_secret) maintaining the same security context. When this happens, the former
server still protects messages to send using its Sender Context, and
verifies messages received using its Recipient Context. The same is
also true for the former client. The endpoints MUST NOT change the
Sender/Recipient ID. In other words, changing the roles does not
change the set of keys to be used.
o AEAD Algorithm (Alg) 3.2. Derivation of Security Context Parameters
* Default is AES-CCM-64-64-128 (value 12) The parameters in the security context are derived from a small set
of input parameters. The following input parameters SHALL be pre-
established:
The following input parameters MAY be pre-established: o Master Secret
o Sender ID o Sender ID
* Defaults are 0x00 for the endpoint intially being client, and
0x01 for the endpoint initially being server
o Recipient ID o Recipient ID
* Defaults are 0x01 for the endpoint intially being client, and The following input parameters MAY be pre-established. In case any
0x00 for the endpoint initially being server of these parameters is not pre-established, the default value
indicated below is used:
o Key Derivation Function (KDF) o AEAD Algorithm (Alg)
* Default is HKDF SHA-256 * Default is AES-CCM-64-64-128 (value 12)
o Replay Window Size o Master Salt
* Default is 64 * Default is the empty string
The endpoints MAY interchange the CoAP client and server roles while o Key Derivation Function (KDF)
maintaining the same security context. When this happens, the former
server still protects the message to send using the Sender Context,
and verifies the message received using its Recipient Context. The
same is also true for the former client. The endpoints MUST NOT
change the Sender/Recipient ID. In other words, changing the roles
does not change the set of keys to be used.
The input parameters are included unchanged in the security context. * Default is HKDF SHA-256
From the input parameters, the following parameters are derived:
o Sender Key, Sender IV, Sender Sequence Number o Replay Window Type and Size
o Recipient Key, Recipient IV, Recipient Sequence Number * Default is DTLS-type replay protection with a window size of 32
The EDHOC protocol [I-D.selander-ace-cose-ecdhe] enables the How the input parameters are pre-established, is application
establishment of input parameters with the property of forward specific. The EDHOC protocol [I-D.selander-ace-cose-ecdhe] enables
secrecy, and negotiation of KDF and AEAD, it thus provides all the establishment of input parameters with the property of forward
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
Given the input parameters, the client and server can derive all the
other parameters in the security context. The derivation procedure
described here MUST NOT be executed more than once using the same
master_secret and Cid. The same master_secret SHOULD NOT be used with
more than one Cid.
The KDF MUST be one of the HKDF [RFC5869] algorithms defined in COSE. The KDF MUST be one of the HKDF [RFC5869] algorithms defined in COSE.
The KDF HKDF SHA-256 is mandatory to implement. The security context HKDF SHA-256 is mandatory to implement. The security context
parameters Sender Key/IV, Recipient Key/IV SHALL be derived using parameters Sender Key/IV and Recipient Key/IV SHALL be derived from
HKDF, and consists of the composition of the HKDF-Extract and HKDF- the input parameters using the HKDF, which consists of the
Expand steps ({{RFC5869}): composition of the HKDF-Extract and HKDF-Expand steps ([RFC5869]):
output parameter = HKDF(master_secret, salt, info, output_length), output parameter = HKDF(salt, IKM, info, L)
where: where:
o master_secret is defined above o salt is the Master Salt as defined above
o salt is a string of zeros of the length of the hash function
output in octets
o info is a serialized CBOR array consisting of: o IKM is the Master Secret is defined above
o info is a CBOR array consisting of:
info = [ info = [
cid : bstr,
id : bstr, id : bstr,
alg : int, alg : int,
out_type : tstr, type : tstr,
out_len : uint L : int
] ]
- id is the Sender ID or Recipient ID * id is the Sender ID or Recipient ID
- out_type is "Key" or "IV"
- out_len is the key/IV size of the AEAD algorithm * type is "Key" or "IV"
o output_length is the size of the AEAD key/IV in bytes encoded as o L is the key/IV size of the AEAD algorithm in octets without
an 8-bit unsigned integer leading zeroes.
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, output_length for the keys is 128 bits [I-D.ietf-cose-msg]) is used, the value for L is 16 for keys and 7
and output_length for the IVs is 56 bits. for IVs.
3.2.2. Context Identifier
As mentioned, Cid is pre-established. How this is done is
application specific, but it is RECOMMENDED that the application uses
64-bits long pseudo-random Cids, in order to have globally unique
Context Identifiers. Cid SHOULD be unique in the sets of all
security contexts used by all the endpoints. If it is not the case,
it is the role of the application to specify how to handle
collisions.
If the application has total control of both clients and servers, 3.2.2. Initial Sequence Numbers and Replay Window
shorter unique Cids MAY be used. Note that Cids of different lengths
can be used by different clients and that e.g. a Cid with the value
0x00 is different from the Cid with the value 0x0000.
In the same phase during which the Cid is established in the The Sequence Number is initialized to 0. The supported types of
endpoint, the application informs the endpoint what resources can be replay protection and replay window length is application specific
accessed using the corresponding security contexts. Resources that and depends on the lower layers. Default is DTLS-type replay
are accessed with OSCOAP are called "protected" resources. The set protection with a window size of 32 initiated as described in
of resources that can be accessed using a certain security context is Section 4.1.2.6 of [RFC6347].
decided by the application (resource, host, etc.). The client SHALL
save the association resource-Cid, in order to be able to retrieve
the correct security context to access a protected resource. The
server SHALL save the association resource-Cid, in order to determine
whether a particular resource may be accessed using a certain Cid.
3.2.3. Sender ID and Recipient ID 3.3. Requirements on the Security Context Parameters
The Sender ID and Recipient ID SHALL be unique in the set of all As collisions may lead to the loss of both confidentiality and
endpoints using the same security context. Collisions may lead to integrity, Sender ID SHALL be unique in the set of all security
the loss of both confidentiality and integrity. If random IDs are contexts using the same Master Secret. Normally (e.g. when using
used, they MUST be long enough so that the probability of collisions EDHOC) Sender IDs can be very short. Note that Sender IDs of
is negligible. different lengths can be used with the same Master Secret. E.g. the
SID with value 0x00 is different from the SID with the value 0x0000.
If Sender ID uniqueness cannot be guaranteed, random Sender IDs MUST
be used. Random Sender IDs MUST be long enough so that the
probability of collisions is negligible.
3.2.4. Sequence Numbers and Replay Window To enable retrieval of the right Recipient Context, the Recipient ID
SHOULD be unique in the sets of all Recipient Contexts used by an
endpoint.
The Sender Sequence Number is initialized to 0. The Recipient Replay The same Master Salt MAY be used with several Master Secrets.
Window is initiated as described in Section 4.1.2.6 of [RFC6347].
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 unprotected message, and vice versa. This section defines how the CoAP message
CoAP message fields are protected. OSCOAP protects as much of the fields are protected. OSCOAP protects as much of the unprotected
unprotected CoAP message as possible, while still allowing forward CoAP message as possible, while still allowing forward proxy
proxy operations [I-D.hartke-core-e2e-security-reqs]. operations [I-D.hartke-core-e2e-security-reqs]. Message fields may
either be
This section also outlines how the message fields are processed and o Class E: encrypted and integrity protected,
transferred, a detailed description is provided in Section 6.
o Class I: integrity protected only, or
o Class U: unprotected.
This section also outlines how the message fields are transferred, a
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 "outer" or the message field in the protected CoAP message is called "inner" or
"inner": "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)
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 inner message fields are encrypted and integrity protected by the The inner message fields are by definition encrypted and integrity
COSE object. The outer message fields are sent in plain text but may protected by the COSE object (Class E). The outer message fields are
be integrity protected by including the message field values in the not encrypted and thus visible to an intermediary, but may be
AAD of the COSE object (see Section 5.2). integrity protected by including the message field values in the AAD
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, and thus The CoAP Payload SHALL be encrypted and integrity protected (Class
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 (see Section 6.2 and message into the plaintext of the COSE object.
Section 6.4).
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 (see recreates the payload of the unprotected CoAP message.
Section 6.3 and Section 6.5).
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 be
protected between the endpoints, e.g. CoAP message layer fields such protected between the endpoints, e.g. CoAP message layer fields such
as Message ID. 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. The CoAP intermediary from changing, e.g. from GET to DELETE (Class I). The
version number SHALL be integrity protected to prevent potential CoAP version number MUST be integrity protected to prevent potential
future version-based attacks. Note that while the version number is future version-based attacks (Class I). Note that while the version
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 Other CoAP header fields SHALL neither be integrity protected nor
encrypted. The CoAP header fields are thus outer message fields. encrypted (Class U). The CoAP header fields are thus outer message
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 protected CoAP message. The
receiving endpoint SHALL copy the header fields from the protected receiving endpoint SHALL copy the header fields from the protected
CoAP message to the unprotected CoAP message. Both sender and CoAP message to the unprotected CoAP message. Both sender and
receiver inserts the CoAP version number and header field Code in the receiver insert the CoAP version number and header field Code in the
AAD of the COSE object (see section Section 5.2). AAD of the COSE object (see section Section 5.2).
4.3. CoAP Options 4.3. CoAP Options
As with the message fields described in the previous sections, CoAP Most options are encrypted and integrity protected (Class E), and
options may be encrypted and integrity protected, integrity protected thus inner message fields. But to allow certain proxy operations,
only, or neither encrypted nor integrity protected. some options have outer values, i.e. are present in the protected
CoAP message. Certain options may have both an inner value and a
Most options are encrypted and integrity protected (see Figure 4), potentially different outer value, where the inner value is intended
and thus inner message fields. But to allow certain proxy for the destination endpoint and the outer value is intended for the
operations, some options have outer values and require special proxy.
processing. Indeed, certain options may or must have both an inner
value and a potentially different outer value, where the inner value
is intended for the destination endpoint and the outer value is
intended for the proxy.
+----+---+---+---+---+----------------+--------+--------+---+---+
| No.| C | U | N | R | Name | Format | Length | E | A |
+----+---+---+---+---+----------------+--------+--------+---+---+
| 1 | x | | | x | If-Match | opaque | 0-8 | x | |
| 3 | x | x | - | | Uri-Host | string | 1-255 | | x |
| 4 | | | | x | ETag | opaque | 1-8 | x | |
| 5 | x | | | | If-None-Match | empty | 0 | x | |
| 6 | | x | - | | Observe | uint | 0-3 | * | |
| 7 | x | x | - | | Uri-Port | uint | 0-2 | | x |
| 8 | | | | x | Location-Path | string | 0-255 | x | |
| 11 | x | x | - | x | Uri-Path | string | 0-255 | x | |
| 12 | | | | | Content-Format | uint | 0-2 | x | |
| 14 | | x | - | | Max-Age | uint | 0-4 | * | |
| 15 | x | x | - | x | Uri-Query | string | 0-255 | x | |
| 17 | x | | | | Accept | uint | 0-2 | x | |
| 20 | | | | x | Location-Query | string | 0-255 | x | |
| 23 | x | x | - | - | Block2 | uint | 0-3 | * | |
| 27 | x | x | - | - | Block1 | uint | 0-3 | * | |
| 28 | | | x | | Size2 | unit | 0-4 | * | |
| 35 | x | x | - | | Proxy-Uri | string | 1-1034 | | * |
| 39 | x | x | - | | Proxy-Scheme | string | 1-255 | | x |
| 60 | | | x | | Size1 | uint | 0-4 | * | |
+----+---+---+---+---+----------------+--------+--------+---+---+
C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable,
E=Encrypt and Integrity Protect, A=Integrity Protect, *=Special
Figure 4: Protection of CoAP Options
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. The CoAP options are partitioned into two classes: Figure 4. Options within each class are protected and processed in a
similar way, but certain options which require special processing as
described in the subsections and indicated by a * in Figure 4.
o E - options which are encrypted and integrity protected, and +----+----------------+---+---+---+
| No.| Name | E | I | U |
+----+----------------+---+---+---+
| 1 | If-Match | x | | |
| 3 | Uri-Host | | | x |
| 4 | ETag | x | | |
| 5 | If-None-Match | x | | |
| 6 | Observe | | * | |
| 7 | Uri-Port | | | x |
| 8 | Location-Path | x | | |
| 11 | Uri-Path | x | | |
| 12 | Content-Format | x | | |
| 14 | Max-Age | * | | |
| 15 | Uri-Query | x | | |
| 17 | Accept | x | | |
| 20 | Location-Query | x | | |
| 23 | Block2 | * | | |
| 27 | Block1 | * | | |
| 28 | Size2 | * | | |
| 35 | Proxy-Uri | | | * |
| 39 | Proxy-Scheme | | | x |
| 60 | Size1 | * | | |
+----+----------------+---+---+---+
o A - options which are only integrity protected. E=Encrypt and Integrity Protect, I=Integrity Protect only,
U=Unprotected, *=Special
Options within each class are protected and processed in a similar Figure 4: Protection of CoAP Options
way, but certain options which require special processing as
described in the subsections and indicated by a '*' in Figure 4.
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 specify 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 options unless a forwarding proxy needs to read
an option value. If a certain option is both inner and outer, the that option value. If a certain option is both inner and outer, the
two values SHOULD NOT be the same, unless a proxy is required by two values SHOULD NOT be the same, unless a proxy is required by
specification to be able to read the end-to-end value. 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, and thus is not visible to integrity protected between the endpoints. Hence the actions
or possible to change by intermediary nodes. 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 with the endpoint. For example, a client using
an ETag option will not be served by a proxy. an ETag 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 (see unprotected CoAP message into the plaintext of the COSE object.
Section 6.2 and Section 6.4).
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, legimitimately 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.
Execept for the Block options Section 4.3.1.3, 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 with the value from the COSE object when message and SHALL replace it in the unprotected CoAP messages with
present (see Section 6.3 and Section 6.5). the value from the COSE object when present.
4.3.1.1. Max-Age 4.3.1.1. Max-Age
An inner Max-Age option is used as defined in [RFC7252] taking into An inner Max-Age option, like other class E options, is used as
account that it is not accessible to proxies. defined in [RFC7252] taking into account that it is not accessible to
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. Therefore, there would not be possible to use for any other request. To avoid
SHOULD be an outer Max-Age option with value zero to prevent caching unnecessary caching, a server MAY add an outer Max-Age option with
of responses (see Section 5.6.1 of [RFC7252]). value zero to protected CoAP responses (see Section 5.6.1 of
[RFC7252]).
The outer Max-Age option SHALL NOT be encrypted and SHALL NOT be
integrity protected.
4.3.1.2. Observe
The Observe option as used here targets the requirements on
forwarding of [I-D.hartke-core-e2e-security-reqs] (Section 2.2.1.2).
An inner Observe option is used between endpoints. In order for a The outer Max-Age option is not integrity protected.
proxy to support forwarding of notifications, there SHALL be an outer
Observe option. To simplify the processing in the server, the outer
option SHOULD have the same value as the inner Observe option. The
outer Observe option MAY have different values than the inner, but
the order of the different values is SHALL be the same as for the
inner Observe option.
The outer Observe option SHALL neither be encrypted nor integrity 4.3.1.2. The Block Options
protected.
4.3.1.3. The Block Options Blockwise [RFC7959] is an optional feature. An implementation MAY
comply with [RFC7252] and the Object-Security option without
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.
The inner block options are used for endpoint-to-endpoint secure The inner block options are used for endpoint-to-endpoint secure
fragmentation of payload into blocks and protection of information fragmentation of payload into blocks and protection of information
about the fragmentation (block number, last block, etc.). about the fragmentation (block number, block size, last block). In
Additionally, a proxy may arbitrarily do fragmentation operations on this case, the CoAP client fragments the CoAP message as defined in
the protected CoAP message, adding outer block options that are not [RFC7959] before the message is processed by OSCOAP. The CoAP server
intended to be verified by any endpoint or proxy. first processes the OSCOAP message before processing blockwise as
defined in [RFC7959].
There SHALL be a security policy defining a maximum unfragmented There SHALL be a security policy defining a maximum unfragmented
message size for inner Block options such that messages exceeding message size for inner Block options such that messages exceeding
this size SHALL be fragmented by the sending endpoint. this size SHALL be fragmented by the sending endpoint.
In addition to the processing defined for the inner Block options Additionally, a proxy may arbitrarily do block fragmentation on any
inherent to class E options, the AEAD Tag from each block SHALL be CoAP message, in particular an OSCOAP message, as defined in
included in the calculation of the Tag for the next block (see [RFC7959] and thereby add outer Block options to a block and send on
Section 5.2), so that each block in the order being sent can be the next hop. The outer block options are thus neither encrypted nor
verified as it arrives. integrity protected.
The protected CoAP message may be fragmented by the sending endpoint
or proxy as defined in [RFC7959], in which case the outer Block
options are being used. The outer Block options SHALL neither be
encrypted nor integrity protected.
An endpoint receiving a message with an outer Block option SHALL An endpoint receiving a message with an outer Block option SHALL
first process this option according to [RFC7959], until all blocks of first process this option according to [RFC7959], until all blocks of
the protected CoAP message has been received, or the cumulated the protected CoAP message has been received, or the cumulated
message size of the exceeds the maximum unfragmented message size. message size of the exceeds the maximum unfragmented message size.
In the latter case the message SHALL be discarded. In the former In the latter case the message SHALL be discarded. In the former
case, the processing of the protected CoAP message continues as case, the processing of the protected CoAP message continues as
defined in this document (see Section 6.3 and Section 6.5). defined in this document.
If the unprotected CoAP message contains Block options, the receiving If the unprotected CoAP message in turn contains Block options, the
endpoint processes this according to {{RFC7959}. receiving endpoint processes this according to [RFC7959].
4.3.2. Class A Options TODO: Update processing to support multiple concurrently proceeding
requests
Options in this class are used to support forward proxy operations. 4.3.2. Class I Options
Class A options SHALL only have outer values and SHALL NOT be
encrypted. In order for the destination endpoint to verify the Uri,
class A options SHALL be integrity protected.
Uri-Host, Uri-Port, Proxy-Scheme and Proxy-Uri are class A options. Except for the special options described in the subsections, for
When Uri-Host, Uri-Port, Proxy-Scheme options are present, Proxy-Uri options in Class I (see Figure 4) the option value SHALL only be
is not used [RFC7252]. Proxy-Uri is processed like the other class A integrity protected between the endpoints. Options in Class I have
options after a pre-processing step (see Section 4.3.2.1. outer values. Unless otherwise specified, the sending endpoint SHALL
encode the Class I options in the protected CoAP message as described
in Section 4.3.4.
Except for Proxi-Uri, the sending endpoint SHALL copy the class A Class I options are included in the external_aad (Section 5.2).
option from the unprotected CoAP message to the protected CoAP
message. The class A options are inserted in the AAD of the COSE
object (see unencrypted-Uri Section 5.2).
4.3.2.1. Proxy-Uri 4.3.2.1. Observe
Proxy-Uri, when present, is split by OSCOAP into class A options and Observe [RFC7641] is an optional feature. An implementation MAY
support [RFC7252] and the Object-Security option without supporting
[RFC7641]. The Observe option as used here targets the requirements
on forwarding of [I-D.hartke-core-e2e-security-reqs]
(Section 2.2.1.2).
In order for a proxy to support forwarding of Observe, there MUST be
an outer Observe option in the message.
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
Notifications, Observe SHALL be integrity protected as described in
this section:
o The Observe option in the unprotected CoAP request SHALL be
included in the external_aad of the request (see Section 5.2).
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
significant bytes of the Sequence Number of the response
4.3.3. Class U Options
Options in Class U have outer values and are used to support forward
proxy operations. Unless otherwise specified, the sending endpoint
SHALL encode the Class U options in the protected CoAP message as
described in Section 4.3.4.
4.3.3.1. 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.
When Uri-Host, Uri-Port, Proxy-Scheme options are present, Proxy-Uri
is not used [RFC7252].
4.3.3.2. Proxy-Uri
Proxy-Uri, when present, is split by OSCOAP into class U options and
privacy sensitive class E options, which are processed accordingly. privacy sensitive class E options, which are processed accordingly.
When Proxy-Uri is used in the unprotected CoAP message, Uri-* are not When Proxy-Uri is used in the unprotected CoAP message, Uri-* are not
present [RFC7252]. present [RFC7252].
The sending endpoint SHALL first decompose the Proxy-Uri value of the The sending endpoint SHALL first decompose the Proxy-Uri value of the
unprotected CoAP message into the unencrypted-Uri (Section 5.2) and unprotected CoAP message into the Proxy-Scheme, Uri-Host, Uri-Port,
Uri-Path/Query options according to section 6.4 of [RFC7252]. Uri-Path and Uri-Query options (if present) according to section 6.4
of [RFC7252].
Uri-Path and Uri-Query are class E options and SHALL be protected and Uri-Path and Uri-Query are class E options and 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 SHALL The value of the Proxy-Uri option of the protected CoAP message MUST
be replaced with unencrypted-Uri and SHALL be protected and processed be replaced with Proxy-Scheme, Uri-Host and Uri-Port options (if
as a class A option, see Section 4.3.2. present) composed according to section 6.5 of [RFC7252] and MUST be
processed as a class U option, see Section 4.3.3.
5. The COSE Object An example of how Proxy-Uri is processed is given below.
This section defines how to use the COSE format [I-D.ietf-cose-msg] An unprotected CoAP message contains:
to wrap and protect data in the unprotected CoAP message. OSCOAP
uses the COSE_Encrypt0 structure with an Authenticated Encryption
with Additional Data (AEAD) algorithm.
The AEAD algorithm AES-CCM-64-64-128 defined in Section 10.2 of o Proxy-Uri = "coap://example.com/resource?q=1"
[I-D.ietf-cose-msg] is mandatory to implement. For AES-CCM-64-64-128
the length of Sender Key and Recipient Key SHALL be 128 bits, the
length of nonce, Sender IV, and Recipient IV SHALL be 7 bytes, and
the maximum Sequence Number SHALL be 2^56-1. 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) with zeroes and XORing it
with the context IV (Sender IV or Recipient IV).
Since OSCOAP only makes use of a single COSE structure, there is no During OSCOAP processing, Proxy-Uri is split into:
need to explicitly specify the structure, and OSCOAP uses the
untagged version of the COSE_Encrypt0 structure (Section 2. of
[I-D.ietf-cose-msg]). If the COSE object has a different structure,
the recipient MUST reject the message, treating it as malformed.
OSCOAP introduces a new COSE Header Parameter, the Sender Identifier: o Proxy-Scheme = "coap"
sid: This parameter is used to identify the sender of the message. o Uri-Host = "example.com"
Applications MUST NOT assume that 'sid' values are unique. This
is not a security critical field. For this reason, it can be
placed in the unprotected headers bucket.
+------+-------+------------+----------------+-------------------+ o Uri-Port = "5863"
| name | label | value type | value registry | description |
+------+-------+------------+----------------+-------------------+
| sid | TBD | bstr | | Sender Identifier |
+------+-------+------------+----------------+-------------------+
Table 1: Additional COSE Header Parameter o Uri-Path = "resource"
We denote by Plaintext the data that is encrypted and integrity o Uri-Query = "q=1"
protected, and by Additional Authenticated Data (AAD) the data that
is integrity protected only, in the COSE object.
The fields of COSE_Encrypt0 structure are defined as follows (see Uri-Path and Uri-Query follow the processing defined in
example in Appendix C.4). Section 4.3.1. Proxy-Uri is added to the OSCOAP protected message
with value:
o The "Headers" field is formed by: o Proxy-Uri = "coap://example.com"
* The "protected" field, which SHALL include: 4.3.4. Outer Options in the Protected CoAP Message
+ The "Partial IV" parameter. The value is set to the Sender All options with outer values present in the protected CoAP message,
Sequence Number. The Partial IV is a byte string (type: including the Object-Security option, SHALL be encoded as described
bstr), and SHOULD be of minimum length needed to encode the in Section 3.1 of [RFC7252], where the delta is the difference to the
sequence number. previously included outer option.
+ The "kid" parameter. The value is set to the Context 5. The COSE Object
Identifier (see Section 3). This parameter is optional if
the message is a CoAP response.
+ Optionally, the parameter called "sid", defined below. The This section defines how to use COSE [I-D.ietf-cose-msg] to wrap and
value is set to the Sender ID (see Section 3). Note that protect data in the unprotected CoAP message. OSCOAP uses the
since this parameter is sent in clear, privacy issues SHOULD untagged COSE_Encrypt0 structure with an Authenticated Encryption
be considered by the application defining the Sender ID. with Additional Data (AEAD) algorithm. The key lengths, IV lengths,
and maximum sequence number are algorithm dependent.
* The "unprotected" field, which SHALL be empty. 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
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
Sequence Number is 2^55 - 1.
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
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
Recipient IV SHALL be flipped in responses.
We denote by Plaintext the data that is encrypted and integrity
protected, and by Additional Authenticated Data (AAD) the data that
is integrity protected only.
The COSE Object SHALL be a COSE_Encrypt0 object with fields defined
as follows
o The "protected" field includes:
* The "Partial IV" parameter. The value is set to the Sequence
Number. The Partial IV SHALL be of minimum length needed to
encode the sequence number. This parameter SHALL be present in
requests, and MAY be present in responses. In case of Observe
(Section 4.3.2.1}) the Partial IV SHALL be present in the
response.
* The "kid" parameter. The value is set to the Sender ID (see
Section 3). This parameter SHALL be present in requests and
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) and encoded as a byte string (type: bstr), following Section 5.2) following Section 5.2 of [I-D.ietf-cose-msg].
Section 5.2 of [I-D.ietf-cose-msg].
The encryption process is described in Section 5.3 of
[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 CoAP Options present in the unprotected message which are o all Class E options Section 4.3.1 present in the unprotected CoAP
encrypted (see Section 4), in the order as given by the Option message (see Section 4). The options are encoded as described in
number (each Option with Option Header including delta to previous Section 3.1 of [RFC7252], where the delta is the difference to the
included encrypted option); and previously included Class E option; and
o the CoAP Payload, if present, and in that case prefixed by the o the Payload of unprotected CoAP message, if present, and in that
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) ... ~ | Options to Encrypt (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
The Additional Authenticated Data ("Enc_structure") as described is The external_aad SHALL be a CBOR array as defined below:
Section 5.3 of [I-D.ietf-cose-msg] includes:
o the "context" parameter, which has value "Encrypted"
o the "protected" parameter, which includes the "protected" part of external_aad = [
the "Headers" field; ver : uint,
code : uint,
options : bstr,
alg : int,
request_kid : bstr,
request_seq : bstr
]
o the "external_aad" is a serialized CBOR array Figure 6 where the where:
exact content is different in requests (external_aad_req) and
repsonses (external_aad_resp). It contains:
* ver: uint, contains the CoAP version number, as defined in o ver: contains the CoAP version number, as defined in Section 3 of
Section 3 of [RFC7252] [RFC7252].
* code: uint, contains is the CoAP Code of the unprotected CoAP o code: contains is the CoAP Code of the unprotected CoAP message,
message, as defined in Section 3 of [RFC7252]. as defined in Section 3 of [RFC7252].
* alg: int, contains the Algorithm from the security context used o options: contains the Class I options Section 4.3.2 present in the
for the exchange (see Section 3.1); unprotected CoAP message encoded as described in Section 3.1 of
[RFC7252], where the delta is the difference to the previously
included class I option
* unencrypted-uri: tstr with tag URI, contains the part of the o alg: contains the Algorithm from the security context used for the
URI which is not encrypted, and is composed of the request exchange (see Section 3.1).
scheme (Proxy-Scheme if present), Uri-Host and Uri-Port (if
present) options according to the method described in
Section 6.5 of [RFC7252], if the message is a CoAP request;
* cid : bstr, contains the cid for the request (which is same as o request_kid: contains the value of the 'kid' in the COSE object of
the cid for the response). the request (see Section 5).
* id : bstr, is the identifier for the endpoint sending the o request_seq: contains the value of the 'Partial IV' in the COSE
request and verifying the response; which means that for the object of the request (see Section 5).
endpoint sending the response, the id has value Recipient ID,
while for the endpoint receiving the response, id has the value
Sender ID.
* seq : bstr, is the value of the "Partial IV" in the COSE object 6. Sequence Numbers, Replay, Message Binding, and Freshness
of the request (see Section 5).
* tag-previous-block: bstr, contains the AEAD Tag of the message 6.1. AEAD Nonce Uniqueness
containing the previous block in the sequence, as enumerated by
Block1 in the case of a request and Block2 in the case of a
response, if the message is fragmented using a block option
[RFC7959].
external_aad = external_aad_req / external_aad_resp 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
Number used to protect requests, and - in case of Observe -
responses. The maximum sequence number is algorithm dependent and
SHALL be 2^(min(nonce length in bits, 56) - 1) - 1. If the Sequence
Number exceeds the maximum sequence number, the endpoint MUST NOT
process any more messages with the given Sender Context. The
endpoint SHOULD acquire a new security context (and consequently
inform the other endpoint) before this happens. The latter is out of
scope of this document.
external_aad_req = [ 6.2. Replay Protection
ver : uint,
code : uint,
alg : int,
unencrypted-uri : uri,
? tag-previous-block : bstr
]
external_aad_resp = [ In order to protect from replay of messages, each Recipient Context
ver : uint, contains a Replay Window used to verify request, and - in case of
code : uint, Observe - responses. A receiving endpoint SHALL verify that a
alg : int, Sequence Number (Partial IV) received in the COSE object has not been
cid : bstr, received before in the Recipient Context. The size and type of the
id : bstr, Replay Window depends on the use case and lower protocol layers. In
seq : bstr, case of reliable and ordered transport from endpoint to endpoint, the
? tag-previous-block : bstr recipient MAY just store the last received sequence number and
] require that newly received Sequence Numbers equals the last received
Sequence Number + 1.
Figure 6: External AAD (external_aad) 6.3. Sequence Number and Replay Window State
The encryption process is described in Section 5.3 of 6.3.1. The Basic Case
[I-D.ietf-cose-msg].
6. Protecting CoAP Messages To prevent reuse of the Nonce/Sequence Number with the same key, or
from accepting replayed messages, a node needs to handle the
situation of suddenly losing sequence number and replay window state
in RAM, e.g. as a result of a reboot.
6.1. Replay and Freshness Protection After boot, a node MAY reject to use existing security contexts from
before it booted and MAY establish a new security context with each
party it communicates, e.g. using EDHOC
[I-D.selander-ace-cose-ecdhe]. However, establishing a fresh
security context may have a non-negligible cost in terms of e.g.
power consumption.
In order to protect from replay of messages and verify freshness, a If a stored security context is to be used after reboot, then the
CoAP endpoint SHALL maintain a Sender Sequence Number and a Recipient node MUST NOT reuse a previous Sequence Number and MUST NOT accept
Replay Window in the security context. An endpoint uses the Sender previously accepted messages. The node MAY perform the following
Sequence Number to protect messages to send and the Recipient Replay procedure:
Window to verify received messages, as described in Section 3.
A receiving endpoint SHALL verify that the Sequence Number (Partial o Before sending a message, the client stores in persistent memory a
IV) received in the COSE object has not been received before in the sequence number associated to the stored security context higher
security context identified by the Cid. The size of the Replay Window than any sequence number which has been or are being sent using
depends on the use case and lower protocol layers. In case of this security context. After boot, the client does not use any
reliable and ordered transport, the recipient MAY just store the last lower sequence number in a request than what was persistently
received sequence number and require that newly received Sequence stored with that security context.
Numbers equals the last received Recipient Sequence Number + 1.
The receiving endpoint SHALL reject messages with a sequence number * Storing to persistent memory can be costly. Instead of storing
greater than the maximum value of the Partial IV. This maximum value a sequence number for each request, the client may store Seq +
is algorithm specific, for example for AES-CCM-64-64-128 it is K to persistent memory every K requests, where Seq is the
2^56-1. current sequence number and K > 1. This is a trade-off between
the number of storage operations and efficient use of sequence
numbers.
OSCOAP responses are verified to match a prior request, by including o After boot, before accepting a message from a stored security
the unique transaction identifier (Tid as defined in Section 3) of context, the server synchronizes the replay window so that no old
the request in the Additional Authenticated Data of the response messages are being accepted. The server uses the Repeat option
message. In case of CoAP observe, each notification MUST be verified [I-D.mattsson-core-coap-actuators] for synchronizing the replay
using the Tid of the observe registration, so the Tid of the window: For each stored security context, the first time after
registration needs to be cached by the observer until the observation boot the server receives an OSCOAP request, it generates a pseudo-
ends. random nonce and responds with the Repeat option set to the nonce
as described in [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.
If a CoAP server receives a request with the Object-Security option, 6.4. Freshness
then the server SHALL include the Tid of the request in the AAD of
the response, as described in Section 6.4.
If the CoAP client receives a response with the Object-Security For responses without Observe, OSCOAP provides absolute freshness.
option, then the client SHALL verify the integrity of the response, For requests, and responses with Observe, OSCOAP provides relative
using the Tid of its own associated request in the AAD, as described freshness in the sense that the sequence numbers allows a recipient
in Section 6.5. to determine the relative order of messages. For applications having
stronger demands on freshness (e.g. control of actuators), OSCOAP
needs to be augmented with mechanisms providing absolute freshness
[I-D.mattsson-core-coap-actuators].
6.2. Protecting the Request 6.5. Delay and Mismatch Attacks
Given an unprotected CoAP request, including header, options and In order to prevent response delay and mismatch attacks
payload, the client SHALL perform the following steps to create a [I-D.mattsson-core-coap-actuators] from on-path attackers and
protected CoAP request using a security context associated with the compromised proxies, OSCOAP binds responses to the request by
target resource (see Section 3.2.2). including the request's ID (Sender ID or Recipient ID) and sequence
number in the AAD of the response. The server therefore needs to
store the request's ID (Sender ID or Recipient ID) and sequence
number until all responses have been sent.
When using Uri-Host or Proxy-Uri in the construction of the request, 7. Processing
the <host> value MUST be a reg-name ([RFC3986]), and not an IP-
literal or IPv4address, for canonicalization of the destination
address.
1. Compute the COSE object as specified in Section 5 7.1. Protecting the Request
* the AEAD nonce is created by XORing the Sender IV (context IV) Given an unprotected request, the client SHALL perform the following
with the Sender Sequence Number (partial IV). steps to create a protected request:
* If the block option is used, the AAD includes the AEAD Tag 1. Retrieve the Sender Context associated with the target resource.
from the previous block sent (from the second block and
following) Section 5.2. This means that the endpoint MUST
store the Tag of each last-sent block to compute the
following.
* Note that the 'sid' field containing the Sender ID is included 2. Compose the Additional Authenticated Data, as described in
in the COSE object (Section 5) if the application needs it. Section 5.
2. Format the protected CoAP message as an ordinary CoAP message, 3. Compose the AEAD nonce by XORing the context IV (Sender IV) with
with the following Header, Options, and Payload, based on the the partial IV (Sequence Number in network byte order).
unprotected CoAP message: Increment the Sequence Number by one.
* The CoAP header is the same as the unprotected CoAP message. 4. Encrypt the COSE object using the Sender Key. Compress the COSE
Object as specified in Appendix A.
* If present, the CoAP option Proxy-Uri is decomposed as 5. Format the protected CoAP message according to Section 4. The
described in Section 4.3.2.1. Object-Security option is added, see Section 4.3.4.
* The CoAP options which are of class E (Section 4) are removed. 6. Store the association Token - Security Context. The client SHALL
The Object-Security option is added. be able to find the Recipient Context from the Token in the
response.
* If the message type of the unprotected CoAP message does not 7.2. Verifying the Request
allow Payload, then the value of the Object-Security option is
the COSE object. If the message type of the unprotected CoAP
message allows Payload, then the Object-Security option is
empty and the Payload of the protected CoAP message is the
COSE object.
3. Store the association Token - Cid. The Client SHALL be able to A server receiving a request containing the Object-Security option
find the correct security context used to protect the request and SHALL perform the following steps:
verify the response with use of the Token of the message
exchange.
4. Increment the Sender Sequence Number by one. If the Sender 1. Process outer Block options according to [RFC7959], until all
Sequence Number exceeds the maximum number for the AEAD blocks of the request have been received, see Section 4.3.1.2.
algorithm, the client MUST NOT process any more requests with the
given security context. The client SHOULD acquire a new security
context (and consequently inform the server about it) before this
happens. The latter is out of scope of this memo.
6.3. Verifying the Request 2. Retrieve the Recipient Context associated with the Recipient ID
in the 'kid' parameter of the COSE object.
A CoAP server receiving an unprotected CoAP request to access a 3. Verify the Sequence Number in the 'Partial IV' parameter, as
protected resource (as defined Section 3.2.2) SHALL reject the described in Section 6.
message with error code 4.01 (Unauthorized).
A CoAP server receiving a message containing the Object-Security 4. Compose the Additional Authenticated Data, as described in
option and a outer Block option SHALL first process this option Section 5.
according to [RFC7959], until all blocks of the protected CoAP
message has been received, see Section 4.3.1.3.
A CoAP server receiving a message containing the Object-Security 5. Compose the AEAD nonce by XORing the context IV (Recipient IV)
option SHALL perform the following steps, using the security context with the padded 'Partial IV' parameter, received in the COSE
identified by the Context Identifier in the "kid" parameter in the Object.
received COSE object:
1. Verify the Sequence Number in the Partial IV parameter, as 6. Decrypt the COSE object using the Recipient Key.
described in Section 6.1. If it cannot be verified that the
Sequence Number has not been received before, the server MUST
stop processing the request.
2. Recreate the Additional Authenticated Data, as described in * If decryption fails, the server MUST stop processing the
Section 5. request and SHOULD send an 4.01 error message.
* If the block option is used, the AAD includes the AEAD Tag * If decryption succeeds, update the Recipient Replay Window, as
from the previous block received (from the second block and described in Section 6.
following) Section 5.2. This means that the endpoint MUST
store the Tag of each last-received block to compute the
following.
* Note that the server's <host> value MUST be a reg-name 7. Add decrypted options or payload to the unprotected request,
([RFC3986]), and not an IP-literal or IPv4address. overwriting any outer E options (see Section 4). The Object-
Security option is removed.
3. Compose the AEAD nonce by XORing the Recipient IV (context IV) 8. The unprotected CoAP request is processed according to [RFC7252]
with the padded Partial IV parameter, received in the COSE
Object.
4. Retrieve the Recipient Key. 7.3. Protecting the Response
5. Verify and decrypt the message. If the verification fails, the Given an unprotected response, the server SHALL perform the following
server MUST stop processing the request. steps to create a protected response:
6. If the message verifies, update the Recipient Replay Window, as 1. Retrieve the Sender Context in the Security Context used to
described in Section 6.1. verify the request.
7. Restore the unprotected request by adding any decrypted options 2. Compose the Additional Authenticated Data, as described in
or payload from the plaintext. Any outer E options (Section 4) Section 5.
are overwritten. The Object-Security option is removed.
6.4. Protecting the Response 3. Compose the AEAD nonce
A server receiving a valid request with a protected CoAP message * If Observe is not used, compose the AEAD nonce by XORing the
(i.e. containing an Object-Security option) SHALL respond with a context IV (Recipient IV with the first bit flipped) with the
protected CoAP message. padded Partial IV parameter from the request.
Given an unprotected CoAP response, including header, options, and * If Observe is used, compose the AEAD nonce by XORing the
payload, the server SHALL perform the following steps to create a context IV (Recipient IV with the first bit flipped) with the
protected CoAP response, using the security context identified by the partial IV (Sequence Number in network byte order). Increment
Context Identifier of the received request: the Sequence Number by one.
1. Compute the COSE object as specified in Section Section 5 4. Encrypt the COSE object using the Sender Key. Compress the COSE
Object as specified in Appendix A.
* The AEAD nonce is created by XORing the Sender IV (context IV) 5. Format the protected CoAP message according to Section 4. The
and the padded Sender Sequence Number. Object-Security option is added, see Section 4.3.4.
* If the block option [RFC7959] is used, the AAD includes the 7.4. Verifying the Response
AEAD Tag from the previous block sent (from the second block
and following) Section 5.2. This means that the endpoint MUST
store the Tag of each last-sent block to compute the
following. Note that this applies even for random access of
blocks, i.e. when blocks are not requested in the order of
their relative number (NUM).
2. Format the protected CoAP message as an ordinary CoAP message, A client receiving a response containing the Object-Security option
with the following Header, Options, and Payload based on the SHALL perform the following steps:
unprotected CoAP message:
* The CoAP header is the same as the unprotected CoAP message. 1. Process outer Block options according to [RFC7959], until all
blocks of the protected CoAP message have been received, see
Section 4.3.1.2.
* The CoAP options which are of class E are removed, except any 2. Retrieve the Recipient Context associated with the Token.
special option (labelled '*') that is present which has its
outer value (Section 4). The Object-Security option is added.
* If the message type of the unprotected CoAP message does not 3. If Observe is used, verify the Sequence Number in the 'Partial
allow Payload, then the value of the Object-Security option is IV' parameter as described in Section 6.
the COSE object. If the message type of the unprotected CoAP
message allows Payload, then the Object-Security option is
empty and the Payload of the protected CoAP message is the
COSE object.
3. Increment the Sender Sequence Number by one. If the Sender 4. Compose the Additional Authenticated Data, as described in
Sequence Number exceeds the maximum number for the AEAD Section 5.
algorithm, the server MUST NOT process any more responses with
the given security context. The server SHOULD acquire a new
security context (and consequently inform the client about it)
before this happens. The latter is out of scope of this memo.
Note the differences between generating a protected request, and a 5. Compose the AEAD nonce
protected response, for example whether "kid" is present in the
header, or whether Destination URI or Tid is present in the AAD, of
the COSE object.
6.5. Verifying the Response * If Observe is not used, compose the AEAD nonce by XORing the
context IV (Recipient IV with the first bit flipped) with the
padded Partial IV parameter from the request.
A CoAP client receiving a message containing the Object-Security * If Observe is used, compose the AEAD nonce by XORing the
option SHALL perform the following steps, using the security context context IV (Recipient IV with the first bit flipped) with the
identified by the Token of the received response: padded Partial IV parameter from the response.
1. If the message contain an outer Block option the client SHALL 6. Decrypt the COSE object using the Recipient Key.
process this option according to [RFC7959], until all blocks of
the protected CoAP message has been received, see
Section 4.3.1.3.
2. Verify the Sequence Number in the Partial IV parameter as * If decryption fails, the client MUST stop processing the
described in Section 6.1. If it cannot be verified that the response and SHOULD send an 4.01 error message.
Sequence Number has not been received before, the client MUST
stop processing the response.
3. Recreate the Additional Authenticated Data as described in * If decryption succeeds and Observe is used, update the
Section 5. Recipient Replay Window, as described in Section 6.
* If the block option is used, the AAD includes the AEAD Tag 7. Add decrypted options or payload to the unprotected response
from the previous block received (from the second block and overwriting any outer E options (see Section 4). The Object-
following) Section 5.2. This means that the endpoint MUST Security option is removed.
store the Tag of each last-received block to compute the
following.
4. Compose the AEAD nonce by XORing the Recipient IV (context IV) * If Observe is used, replace the Observe value with the 3 least
with the Partial IV parameter, received in the COSE Object. significant bytes in the sequence number.
5. Retrieve the Recipient Key. 8. The unprotected CoAP response is processed according to [RFC7252]
6. Verify and decrypt the message. If the verification fails, the 8. Web Linking
client MUST stop processing the response.
7. If the message verifies, update the Recipient Replay Window, as The use of OSCOAP MAY be indicated by a target attribute "osc" in a
described in Section 6.1. web link [RFC5988] to a CoAP resource. This attribute is a hint
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
security context material or any other information required to run
OSCOAP.
8. Restore the unprotected response by adding any decrypted options A value MUST NOT be given for the "osc" attribute; any present value
or payload from the plaintext. Any class E options (Section 4) MUST be ignored by parsers. The "osc" attribute MUST NOT appear more
are overwritten. The Object-Security option is removed. than once in a given link-value; occurrences after the first MUST be
ignored by parsers.
7. Security Considerations 9. 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 27, line 11 skipping to change at page 25, line 39
ID, as well as Token and Token Length may be changed by a proxy. ID, as well as Token and Token Length may be changed by a proxy.
Moreover, messages that are not possible to verify should for Moreover, messages that are not possible to verify should for
security reasons not always be acknowledged but in some cases be security reasons not always be acknowledged but in some cases be
silently dropped. This would not comply with CoAP message layer, but silently dropped. This would not comply with CoAP message layer, but
does not have an impact on the application layer security solution, does not have an impact on the application layer security solution,
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 and key derivation function in client common shared secret material in client and server, which may be
and server. EDHOC [I-D.selander-ace-cose-ecdhe] describes an obtained e.g. by using EDHOC [I-D.selander-ace-cose-ecdhe] or the ACE
augmented Diffie-Hellman key exchange to produce forward secret framework [I-D.ietf-ace-oauth-authz]. An OSCOAP profile of ACE is
keying material and agree on crypto algorithms necessary for OSCOAP, described in [I-D.seitz-ace-oscoap-profile].
authenticated with pre-established credentials. These pre-
established credentials may, in turn, be provisioned using a trusted The formula 2^(min(nonce length in bits, 56) - 1) - 1 (Section 6.1)
third party such as described in the OAuth-based ACE framework guarantees unique nonces during the required use the algorithm,
[I-D.ietf-ace-oauth-authz]. An OSCOAP profile of ACE is described in considering the same partial IV and flipped first bit of IV
[I-D.seitz-ace-oscoap-profile]. (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 no. messages (2^56-1). Compatibility with CCM* blocks) and maximum number of messages (2^56). Compatibility with
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 encrypted 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. In order to protect before having received the complete message. The outer block options
from attacks replacing blocks from a different message with the same allow for arbitrary proxy fragmentation operations that cannot be
block number between same endpoints and same resource at roughly the verified by the endpoints, but can by policy be restricted in size
same time, the AEAD Tag from the message containing one block is since the encrypted options allow for secure fragmentation of very
included in the external_aad of the message containing the next large messages. A maximum message size (above which the sending
block. endpoint fragments the message and the receiving endpoint discards
the message, if complying to the policy) may be obtained as part of
The unencrypted block options allow for arbitrary proxy fragmentation normal resource discovery.
operations that cannot be verified by the endpoints, but can by
policy be restricted in size since the encrypted options allow for
secure fragmentation of very large messages. A maximum message size
(above which the sending endpoint fragments the message and the
receiving endpoint discards the message, if complying to the policy)
may be obtained as part of normal resource discovery.
Applications need to use a padding scheme if the content of a message Applications need to use a padding scheme if the content of a message
can be determined solely from the length of the payload. As an can be determined solely from the length of the payload. As an
example, the strings "YES" and "NO" even if encrypted can be example, the strings "YES" and "NO" even if encrypted can be
distinguished from each other as there is no padding supplied by the distinguished from each other as there is no padding supplied by the
current set of encryption algorithms. Some information can be current set of encryption algorithms. Some information can be
determined even from looking at boundary conditions. An example of determined even from looking at boundary conditions. An example of
this would be returning an integer between 0 and 100 where lengths of this would be returning an integer between 0 and 100 where lengths of
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.
8. Privacy Considerations 10. 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
information. In particular Uri-Host SHOULD NOT contain privacy
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.
9. IANA Considerations 11. 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.
9.1. CoAP Option Numbers Registry 11.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]] |
+--------+-----------------+-------------------+ +--------+-----------------+-------------------+
9.2. COSE Header Parameters Registry 11.2. Media Type Registrations
The "sid" parameter is added to the COSE Header Parameter Registry:
+------+-------+------------+----------------+-------------------+
| name | label | value type | value registry | description |
+------+-------+------------+----------------+-------------------+
| sid | TBD | bstr | | Sender Identifier |
+------+-------+------------+----------------+-------------------+
9.3. 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
Optional parameters: N/A Optional parameters: N/A
Encoding considerations: binary Encoding considerations: binary
Security considerations: See Appendix C of [[this document]]. Security considerations: See Appendix C of this document.
Interoperability considerations: N/A Interoperability considerations: N/A
Published specification: [[this document]] Published specification: [[this document]] (this document)
Applications that use this media type: To be identified Applications that use this media type: To be identified
Fragment identifier considerations: N/A Fragment identifier considerations: N/A
Additional information: Additional information:
* Magic number(s): N/A * Magic number(s): N/A
* File extension(s): N/A * File extension(s): N/A
* Macintosh file type code(s): N/A * Macintosh file type code(s): N/A
Person & email address to contact for further information: Person & email address to contact for further information:
iesg@ietf.org 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
Change Controller: IESG 11.3. CoAP Content Format Registration
Provisional registration? No
9.4. 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]] |
+-------------------+----------+----+-------------------+ +-------------------+----------+----+-------------------+
10. Acknowledgments 12. Acknowledgments
The following individuals provided input to this document: Carsten The following individuals provided input to this document: Christian
Bormann, Joakim Brorsson, Martin Gunnarsson, Klaus Hartke, Jim Amsuess, Carsten Bormann, Joakim Brorsson, Martin Gunnarsson, Klaus
Schaad, Marco Tiloca, and Malisa Vucinic. 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.
11. References 13. References
11.1. Normative References 13.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>.
[RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand
Key Derivation Function (HKDF)", RFC 5869,
DOI 10.17487/RFC5869, May 2010,
<http://www.rfc-editor.org/info/rfc5869>.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988,
DOI 10.17487/RFC5988, October 2010,
<http://www.rfc-editor.org/info/rfc5988>.
[RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer
Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347,
January 2012, <http://www.rfc-editor.org/info/rfc6347>. January 2012, <http://www.rfc-editor.org/info/rfc6347>.
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
October 2013, <http://www.rfc-editor.org/info/rfc7049>.
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252, Application Protocol (CoAP)", RFC 7252,
DOI 10.17487/RFC7252, June 2014, DOI 10.17487/RFC7252, June 2014,
<http://www.rfc-editor.org/info/rfc7252>. <http://www.rfc-editor.org/info/rfc7252>.
[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>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 13.2. Informative References
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<http://www.rfc-editor.org/info/rfc3986>.
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
October 2013, <http://www.rfc-editor.org/info/rfc7049>.
11.2. Informative References
[I-D.selander-ace-cose-ecdhe]
Selander, G., Mattsson, J., and F. Palombini, "Ephemeral
Diffie-Hellman Over COSE (EDHOC)", draft-selander-ace-
cose-ecdhe-04 (work in progress), October 2016.
[I-D.hartke-core-e2e-security-reqs]
Selander, G., Palombini, F., and K. Hartke, "Requirements
for CoAP End-To-End Security", draft-hartke-core-e2e-
security-reqs-01 (work in progress), July 2016.
[I-D.mattsson-core-coap-actuators]
Mattsson, J., Fornehed, J., Selander, G., and F.
Palombini, "Controlling Actuators with CoAP", draft-
mattsson-core-coap-actuators-02 (work in progress),
November 2016.
[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]
Vigano, C. and H. Birkholz, "CBOR data definition language
(CDDL): a notational convention to express CBOR data
structures", draft-greevenbosch-appsawg-cbor-cddl-09 (work
in progress), September 2016.
[I-D.hartke-core-e2e-security-reqs]
Selander, G., Palombini, F., and K. Hartke, "Requirements
for CoAP End-To-End Security", draft-hartke-core-e2e-
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-04 (work in progress), October 2016. authz-05 (work in progress), February 2017.
[I-D.seitz-ace-oscoap-profile]
Seitz, L. and F. Palombini, "OSCOAP profile of ACE",
draft-seitz-ace-oscoap-profile-01 (work in progress),
October 2016.
[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-05 (work in progress), draft-ietf-core-coap-tcp-tls-07 (work in progress), March
2017.
[I-D.mattsson-core-coap-actuators]
Mattsson, J., Fornehed, J., Selander, G., and F.
Palombini, "Controlling Actuators with CoAP", draft-
mattsson-core-coap-actuators-02 (work in progress),
November 2016.
[I-D.seitz-ace-oscoap-profile]
Seitz, L. and F. Palombini, "OSCOAP profile of ACE",
draft-seitz-ace-oscoap-profile-01 (work in progress),
October 2016. October 2016.
[I-D.greevenbosch-appsawg-cbor-cddl] [I-D.selander-ace-cose-ecdhe]
Vigano, C. and H. Birkholz, "CBOR data definition language Selander, G., Mattsson, J., and F. Palombini, "Ephemeral
(CDDL): a notational convention to express CBOR data Diffie-Hellman Over COSE (EDHOC)", draft-selander-ace-
structures", draft-greevenbosch-appsawg-cbor-cddl-09 (work cose-ecdhe-04 (work in progress), October 2016.
in progress), September 2016.
[RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand [I-D.tiloca-core-multicast-oscoap]
Key Derivation Function (HKDF)", RFC 5869, Tiloca, M., Selander, G., and F. Palombini, "Secure group
DOI 10.17487/RFC5869, May 2010, communication for CoAP", draft-tiloca-core-multicast-
<http://www.rfc-editor.org/info/rfc5869>. oscoap-00 (work in progress), October 2016.
[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. Overhead Appendix A. OSCOAP Compression
OSCOAP transforms an unprotected CoAP message to a protected CoAP
message, and the protected CoAP message is larger than the
unprotected CoAP message. This appendix illustrates the message
expansion.
A.1. Length of the Object-Security Option
The protected CoAP message contains the COSE object. The COSE object
is included in the payload if the message type of the unprotected
CoAP message allows payload or else in the Object-Security option.
In the former case the Object-Security option is empty. So the
length of the Object-Security option is either zero or the size of
the COSE object, depending on whether the CoAP message allows payload
or not.
Length of Object-Security option = { 0, size of COSE Object }
A.2. Size of the COSE Object
The size of the COSE object is the sum of the sizes of
o the Header parameters,
o the Cipher Text (excluding the Tag),
o the Tag, and
o data incurred by the COSE format itself (including CBOR encoding).
Let's analyze the contributions one at a time:
o The header parameters of the COSE object are the Context
Identifier (Cid) and the Sequence Number (Seq) (also part of the
Transaction Identifier (Tid)) if the message is a request, and Seq
only if the message is a response (see Section 5).
* The size of Cid is recommended to be 64 bits, but may be
shorter, as discussed in Section 3.2.2
* The size of Seq is variable, and increases with the number of
messages exchanged.
* As the AEAD nonce is generated from the padded Sequence Number
and a previously agreed upon context IV it is not required to
send the whole nonce in the message.
o The Cipher Text, excluding the Tag, is the encryption of the
payload and the encrypted options Section 4, which are present in
the unprotected CoAP message.
o The size of the Tag depends on the Algorithm. For example, for
the algorithm AES-CCM-64-64-128, the Tag is 8 bytes.
o The overhead from the COSE format itself depends on the sizes of
the previous fields, and is of the order of 10 bytes.
A.3. Message Expansion
The message expansion is not the size of the COSE object. The
ciphertext in the COSE object is encrypted payload and options of the
unprotected CoAP message - the plaintext of which is removed from the
protected CoAP message. Since the size of the ciphertext is the same
as the corresponding plaintext, there is no message expansion due to
encryption; payload and options are just represented in a different
way in the protected CoAP message:
o The encrypted payload is in the payload of the protected CoAP
message
o The encrypted options are in the Object-Security option or within The Concise Binary Object Representation (CBOR) combines very small
the payload. 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.
Therefore the OSCOAP message expansion is due to Cid (if present), The value of the Object-Security option SHALL in general be encoded
Seq, Tag, and COSE overhead: as:
Message Overhead = Cid + Seq + Tag + COSE Overhead [
Partial IV,
? kid,
ciphertext
]
Figure 7: OSCOAP message expansion 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:
A.4. Example 10000abc 01000def -> 00abcdef
This section gives an example of message expansion in a request with The exception is Responses without Observe that SHALL be encoded as:
OSCOAP.
In this example we assume an 8-byte Cid. ciphertext
o Cid: 0xa1534e3c9cecad84 A.1. Examples
In the example the sequence number is 225, requiring 1 byte to A.1.1. Example Request
encode. (The size of Seq could be larger depending on how many
messages that has been sent as is discussed in Appendix A.2.)
o Seq: 225 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
The example is based on AES-CCM-64-64-128. [
{
4:h'25',
6:h'05'
},
{},
h'aea0155667924dff8a24e4cb35b9'
]
o Tag is 8 bytes After Compression (18 bytes)
19 05 41 25 ae a0 15 56 67 92 4d ff 8a 24 e4 cb
35 b9
The COSE object is represented in Figure 8 using CBOR's diagnostic A.1.2. Example Response
notation.
[ COSE Object Before Compression (18 bytes)
h'a20448a1534e3c9cecad840641e2', / protected: 83 a0 a0 4e ae a0 15 56 67 92 4d ff 8a 24 e4 cb
{04:h'a1534e3c9cecad84', 35 b9
06:h'e2'} /
{}, / unprotected: - /
Ciph + Tag / ciphertext + 8 byte
authentication tag /
]
Figure 8: Example of message expansion [
{},
{},
h'aea0155667924dff8a24e4cb35b9'
]
Note that the encrypted CoAP options and payload are omitted since we After Compression (14 bytes)
target the message expansion (see Appendix A.3). Therefore the size ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9
of the COSE Cipher Text equals the size of the Tag, which is 8 bytes.
The COSE object encodes to a total size of 26 bytes, which is the A.1.3. Example Response (with Observe)
message expansion in this example. The COSE overhead in this example COSE Object Before Compression (21 bytes)
is 26 - (8 + 1 + 8) = 9 bytes, according to the formula in Figure 7. 83 a1 06 41 07 a0 4e ae a0 15 56 67 92 4d ff 8a
24 e4 cb 35 b9
Note that in this example two bytes in the COSE overhead are used to [
encode the length of Cid and the length of Seq. {
6:h'07'
},
{},
h'aea0155667924dff8a24e4cb35b9'
]
Figure 9 summarizes these results. After Compression (16 bytes)
11 07 ae a0 15 56 67 92 4d ff 8a 24 e4 cb 35 b9
+---------+---------+---------+----------+------------+ Appendix B. Test Vectors
| Cid | Seq | Tag | COSE OH | Message OH |
+---------+---------+---------+----------+------------+
| 8 bytes | 1 byte | 8 bytes | 9 bytes | 22 bytes |
+---------+---------+---------+----------+------------+
Figure 9: Message overhead for a 8-byte Cid, 1-byte Seq and 8-byte TODO: This section needs to be updated.
Tag.
Appendix B. Examples Appendix C. 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.
B.1. Secure Access to Sensor C.1. Secure Access to Sensor
Here is an example targeting the scenario in the Section 2.2.1. - This example targets the scenario in Section 3.1 of
Forwarding of [I-D.hartke-core-e2e-security-reqs]. The example [I-D.hartke-core-e2e-security-reqs] and illustrates a client
illustrates a client requesting the alarm status from a server. In requesting the alarm status from a server.
the request, CoAP option Uri-Path is encrypted and integrity
protected, and the CoAP header fields Code and Version are integrity
protected (see Section 4). In the response, the CoAP Payload is
encrypted and integrity protected, and the CoAP header fields Code
and Version are integrity protected.
Client Proxy Server Client Proxy Server
| | | | | |
+----->| | Code: 0.01 (GET) +----->| | Code: 0.01 (GET)
| GET | | Token: 0x8c | GET | | Token: 0x8c
| | | Object-Security: [cid:5fdc, seq:42, | | | Object-Security: [kid:5f, seq:42,
| | | {Uri-Path:"alarm_status"}, | | | {Uri-Path:"alarm_status"}]
| | | <Tag>]
| | | Payload: - | | | Payload: -
| | | | | |
| +----->| Code: 0.01 (GET) | +----->| Code: 0.01 (GET)
| | GET | Token: 0x7b | | GET | Token: 0x7b
| | | Object-Security: [cid:5fdc, seq:42, | | | Object-Security: [kid:5f, seq:42,
| | | {Uri-Path:"alarm_status"}, | | | {Uri-Path:"alarm_status"}]
| | | <Tag>]
| | | Payload: - | | | Payload: -
| | | | | |
| |<-----+ Code: 2.05 (Content) | |<-----+ Code: 2.05 (Content)
| | 2.05 | Token: 0x7b | | 2.05 | Token: 0x7b
| | | Max-Age: 0
| | | Object-Security: - | | | Object-Security: -
| | | Payload: [seq:56, {"OFF"}, <Tag>] | | | Payload: [{"OFF"}]
| | | | | |
|<-----+ | Code: 2.05 (Content) |<-----+ | Code: 2.05 (Content)
| 2.05 | | Token: 0x8c | 2.05 | | Token: 0x8c
| | | Max-Age: 0
| | | Object-Security: - | | | Object-Security: -
| | | Payload: [seq:56, {"OFF"}, <Tag>] | | | Payload: [{"OFF"}]
| | | | | |
Figure 10: Indication of CoAP GET protected with OSCOAP. The Figure 6: Secure Access to Sensor. Square brackets [ ... ] indicate
brackets [ ... ] indicate a COSE object. The brackets { ... } a COSE object. Curly brackets { ... } indicate encrypted data.
indicate encrypted data.
Since the unprotected request message (GET) has no payload, the
Object-Security option carries the COSE object as its value. Since
the unprotected response message (Content) has payload ("OFF"), the
COSE object (indicated with [ ... ]) is carried as the CoAP payload.
The COSE header of the request contains a Context Identifier Since the method (GET) doesn't allow payload, the Object-Security
(cid:5fdc), indicating which security context was used to protect the option carries the COSE object as its value. Since the response code
message and a Sequence Number (seq:42). (Content) allows payload, the COSE object is carried as the CoAP
payload.
The option Uri-Path (alarm_status) and payload ("OFF") are formatted The COSE header of the request contains an identifier (5f),
as indicated in Section 5, and encrypted in the COSE Cipher Text indicating which security context was used to protect the message and
(indicated with { ... }). a sequence number (42). The option Uri-Path ("alarm_status") and
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 (see Section 6.1). The client verifies that the Sequence before. The client verifies that the response is bound to the
Number has not been received before and that the response message is request.
generated as a response to the sent request message (see
Section 6.1).
B.2. Secure Subscribe to Sensor C.2. Secure Subscribe to Sensor
Here is an example targeting the scenario in the Forwarding with This example targets the scenario in Section 3.2 of
observe case of [I-D.hartke-core-e2e-security-reqs]. The example [I-D.hartke-core-e2e-security-reqs] and illustrates a client
illustrates a client requesting subscription to a blood sugar requesting subscription to a blood sugar measurement resource (GET
measurement resource (GET /glucose), and first receiving the value /glucose), first receiving the value 220 mg/dl and then a second
220 mg/dl, and then a second reading with value 180 mg/dl. The CoAP value 180 mg/dl.
options Observe, Uri-Path, Content-Format, and Payload are encrypted
and integrity protected, and the CoAP header field Code is integrity
protected (see Section 4).
Client Proxy Server Client Proxy Server
| | | | | |
+----->| | Code: 0.01 (GET) +----->| | Code: 0.01 (GET)
| GET | | Token: 0x83 | GET | | Token: 0x83
| | | Observe: 0 | | | Observe: 0
| | | Object-Security: [cid:ca, seq:15b7, {Observe:0, | | | Object-Security: [kid:ca, seq:15,
| | | Uri-Path:"glucose"}, <Tag>] | | | {Uri-Path:"glucose"}]
| | | Payload: - | | | Payload: -
| | | | | |
| +----->| Code: 0.01 (GET) | +----->| Code: 0.01 (GET)
| | GET | Token: 0xbe | | GET | Token: 0xbe
| | | Observe: 0 | | | Observe: 0
| | | Object-Security: [cid:ca, seq:15b7, {Observe:0, | | | Object-Security: [kid:ca, seq:15,
| | | Uri-Path:"glucose"}, <Tag>] | | | {Uri-Path:"glucose"}]
| | | Payload: - | | | Payload: -
| | | | | |
| |<-----+ Code: 2.05 (Content) | |<-----+ Code: 2.05 (Content)
| | 2.05 | Token: 0xbe | | 2.05 | Token: 0xbe
| | | Max-Age: 0 | | | Observe: 000032
| | | Observe: 1 | | | Object-Security: -
| | | Object-Security: - | | | Payload: [seq:32, {Content-Format:0, "220"}]
| | | Payload: [seq:32c2, {Observe:1, | | |
| | | Content-Format:0, "220"}, <Tag>] |<-----+ | Code: 2.05 (Content)
| | | | 2.05 | | Token: 0x83
|<-----+ | Code: 2.05 (Content) | | | Observe: 000032
| 2.05 | | Token: 0x83 | | | Object-Security: -
| | | Max-Age: 0 | | | Payload: [seq:32, {Content-Format:0, "220"}]
| | | Observe: 1 ... ... ...
| | | Object-Security: - | | |
| | | Payload: [seq:32c2, {Observe:1, | |<-----+ Code: 2.05 (Content)
| | | Content-Format:0, "220"}, <Tag>] | | 2.05 | Token: 0xbe
... ... ... | | | Observe: 000036
| | | | | | Object-Security: -
| |<-----+ Code: 2.05 (Content) | | | Payload: [seq:36, {Content-Format:0, "180"}]
| | 2.05 | Token: 0xbe | | |
| | | Max-Age: 0 |<-----+ | Code: 2.05 (Content)
| | | Observe: 2 | 2.05 | | Token: 0x83
| | | Object-Security: - | | | Observe: 000036
| | | Payload: [seq:32c6, {Observe:2, | | | Object-Security: -
| | | Content-Format:0, "180"}, <Tag>] | | | Payload: [seq:36, {Content-Format:0, "180"}]
| | | | | |
|<-----+ | Code: 2.05 (Content)
| 2.05 | | Token: 0x83
| | | Max-Age: 0
| | | Observe: 2
| | | Object-Security: -
| | | Payload: [seq:32c6, {Observe:2,
| | | Content-Format:0, "180"}, <Tag>]
| | |
Figure 11: Indication of CoAP GET protected with OSCOAP. The Figure 7: Secure Subscribe to Sensor. Square brackets [ ... ]
brackets [ ... ] indicates COSE object. The bracket { ... } indicate a COSE object. Curly brackets { ... } indicate encrypted
indicates encrypted data. data.
Since the unprotected request message (GET) allows no payload, the Since the method (GET) doesn't allow payload, the Object-Security
COSE object (indicated with [ ... ]) is carried in the Object- option carries the COSE object as its value. Since the response code
Security option value. Since the unprotected response message (Content) allows payload, the COSE object is carried as the CoAP
(Content) has payload, the Object-Security option is empty, and the payload.
COSE object is carried as the payload.
The COSE header of the request contains a Context Identifier The COSE header of the request contains an identifier (ca),
(cid:ca), indicating which security context was used to protect the indicating the security context used to protect the message and a
message and a Sequence Number (seq:15b7). Sequence Number (15). The COSE header of the responses contains
sequence numbers (32 and 36). The options Content-Format (0) and the
payload ("220" and "180"), are encrypted. The Observe option is
integrity protected. The shown Observe values (000032 and 000036)
are the ones that the client will see after OSCOAP processing.
The options Observe, Content-Format and the payload are formatted as The server verifies that the sequence number has not been received
indicated in Section 5, and encrypted in the COSE ciphertext before. The client verifies that the sequence number has not been
(indicated with { ... }). received before and that the responses are bound to the request.
The server verifies that the Sequence Number has not been received Appendix D. Object Security of Content (OSCON)
before (see Section 6.1). The client verifies that the Sequence
Number has not been received before and that the response message is
generated as a response to the subscribe request.
Appendix C. Object Security of Content (OSCON) 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
individual messages using the COSE format ([I-D.ietf-cose-msg]), individual messages using the COSE format ([I-D.ietf-cose-msg]),
rather than the entire request/response message exchange. This is rather than the entire request/response message exchange. This is
skipping to change at page 40, line 22 skipping to change at page 36, 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 9) with "application/oscon" (Section 11)
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.1. 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.
C.1. Overhead OSCON D.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 41, line 22 skipping to change at page 37, line 50
signature. A 4-byte Context Identifier and a 1-byte Sequence Number signature. A 4-byte Context Identifier and a 1-byte Sequence Number
are used throughout all examples, with these values: are used throughout all examples, with these values:
o Cid: 0xa1534e3c o Cid: 0xa1534e3c
o Seq: 0xa3 o Seq: 0xa3
For each scheme, we indicate the fixed length of these two parameters For each scheme, we indicate the fixed length of these two parameters
("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.
following the formula in Figure 7.
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.
C.2. MAC Only D.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 42, line 7 skipping to change at page 38, 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 12 summarizes these results. Figure 8 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 12: Message overhead for a 5-byte Tid using HMAC 256/64 Figure 8: Message overhead for a 5-byte Tid using HMAC 256/64
C.3. Signature Only D.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 42, line 39 skipping to change at page 39, 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 13 summarizes these results. Figure 9 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 13: Message overhead for a 5-byte Tid using 64 byte ECDSA Figure 9: Message overhead for a 5-byte Tid using 64 byte ECDSA
signature. signature.
C.4. Authenticated Encryption with Additional Data (AEAD) D.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
skipping to change at page 43, line 27 skipping to change at page 39, line 51
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 TAG # ciphertext + 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 14 summarizes these results. Figure 10 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 14: Message overhead for a 5-byte Tid using AES_128_CCM_8. Figure 10: Message overhead for a 5-byte Tid using AES_128_CCM_8.
C.5. Symmetric Encryption with Asymmetric Signature (SEAS) D.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 C.4. COSE The same assumption on the security context as in Appendix D.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 TAG # ciphertext + 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 15 summarizes these results. Figure 11 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 15: Message overhead for a 5-byte Tid using AES-CCM Figure 11: 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
Farogatan 6
Kista SE-16480 Stockholm
Sweden
Email: goran.selander@ericsson.com Email: goran.selander@ericsson.com
John Mattsson John Mattsson
Ericsson AB Ericsson AB
Farogatan 6
Kista SE-16480 Stockholm
Sweden
Email: john.mattsson@ericsson.com Email: john.mattsson@ericsson.com
Francesca Palombini Francesca Palombini
Ericsson AB Ericsson AB
Farogatan 6
Kista SE-16480 Stockholm
Sweden
Email: francesca.palombini@ericsson.com Email: francesca.palombini@ericsson.com
Ludwig Seitz Ludwig Seitz
SICS Swedish ICT SICS Swedish ICT
Scheelevagen 17
Lund 22370
Sweden
Email: ludwig@sics.se Email: ludwig@sics.se
 End of changes. 307 change blocks. 
1094 lines changed or deleted 958 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/