draft-ietf-core-object-security-00.txt   draft-ietf-core-object-security-01.txt 
CoRE Working Group G. Selander CoRE Working Group G. Selander
Internet-Draft J. Mattsson Internet-Draft J. Mattsson
Intended status: Standards Track F. Palombini Intended status: Standards Track F. Palombini
Expires: April 22, 2017 Ericsson AB Expires: June 22, 2017 Ericsson AB
L. Seitz L. Seitz
SICS Swedish ICT SICS Swedish ICT
October 19, 2016 December 19, 2016
Object Security of CoAP (OSCOAP) Object Security of CoAP (OSCOAP)
draft-ietf-core-object-security-00 draft-ietf-core-object-security-01
Abstract Abstract
This memo defines Object Security of CoAP (OSCOAP), a method for This memo defines Object Security of CoAP (OSCOAP), a method for
application layer protection of message exchanges with the application layer protection of message exchanges with the
Constrained Application Protocol (CoAP), using the CBOR Object Constrained Application Protocol (CoAP), using the CBOR Object
Signing and Encryption (COSE) format. OSCOAP provides end-to-end Signing and Encryption (COSE) format. OSCOAP provides end-to-end
encryption, integrity and replay protection to CoAP payload, options, encryption, integrity and replay protection to CoAP payload, options,
and header fields, as well as a secure binding between CoAP request and header fields, as well as a secure binding between CoAP request
and response messages. The use of OSCOAP is signaled with the CoAP and response messages. The use of OSCOAP is signaled with the CoAP
skipping to change at page 1, line 40 skipping to change at page 1, line 40
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at 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 April 22, 2017. This Internet-Draft will expire on June 22, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 18 skipping to change at page 2, line 18
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. Security Context Establishment . . . . . . . . . . . . . 9 3.2. Derivation of Security Context Parameters . . . . . . . . 8
3.2.1. Derivation of Sender Key/IV, Recipient Key/IV . . . . 9 3.2.1. Derivation of Sender Key/IV, Recipient Key/IV . . . . 10
3.2.2. Sequence Numbers and Replay Window . . . . . . . . . 10 3.2.2. Context Identifier . . . . . . . . . . . . . . . . . 11
3.2.3. Context Identifier and Sender/Recipient ID . . . . . 10 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
5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 14 4.1. CoAP Payload . . . . . . . . . . . . . . . . . . . . . . 12
5.1. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 15 4.2. CoAP Header . . . . . . . . . . . . . . . . . . . . . . . 12
5.2. Additional Authenticated Data . . . . . . . . . . . . . . 16 4.3. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 13
6. Protecting CoAP Messages . . . . . . . . . . . . . . . . . . 17 4.3.1. Class E Options . . . . . . . . . . . . . . . . . . . 15
6.1. Replay and Freshness Protection . . . . . . . . . . . . . 17 4.3.2. Class A Options . . . . . . . . . . . . . . . . . . . 17
6.2. Protecting the Request . . . . . . . . . . . . . . . . . 18 5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 17
6.3. Verifying the Request . . . . . . . . . . . . . . . . . . 19 5.1. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 19
6.4. Protecting the Response . . . . . . . . . . . . . . . . . 20 5.2. Additional Authenticated Data . . . . . . . . . . . . . . 19
6.5. Verifying the Response . . . . . . . . . . . . . . . . . 21 6. Protecting CoAP Messages . . . . . . . . . . . . . . . . . . 21
7. Security Considerations . . . . . . . . . . . . . . . . . . . 22 6.1. Replay and Freshness Protection . . . . . . . . . . . . . 21
8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 24 6.2. Protecting the Request . . . . . . . . . . . . . . . . . 22
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 6.3. Verifying the Request . . . . . . . . . . . . . . . . . . 23
9.1. Sid Registration . . . . . . . . . . . . . . . . . . . . 24 6.4. Protecting the Response . . . . . . . . . . . . . . . . . 24
9.2. CoAP Option Number Registration . . . . . . . . . . . . . 24 6.5. Verifying the Response . . . . . . . . . . . . . . . . . 25
9.3. Media Type Registrations . . . . . . . . . . . . . . . . 24 7. Security Considerations . . . . . . . . . . . . . . . . . . . 26
9.4. CoAP Content Format Registration . . . . . . . . . . . . 25 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 28
10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 26 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 26 9.1. CoAP Option Numbers Registry . . . . . . . . . . . . . . 28
11.1. Normative References . . . . . . . . . . . . . . . . . . 26 9.2. COSE Header Parameters Registry . . . . . . . . . . . . . 29
11.2. Informative References . . . . . . . . . . . . . . . . . 27 9.3. Media Type Registrations . . . . . . . . . . . . . . . . 29
Appendix A. Overhead . . . . . . . . . . . . . . . . . . . . . . 28 9.4. CoAP Content Format Registration . . . . . . . . . . . . 30
A.1. Length of the Object-Security Option . . . . . . . . . . 28 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 31
A.2. Size of the COSE Object . . . . . . . . . . . . . . . . . 28 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 31
A.3. Message Expansion . . . . . . . . . . . . . . . . . . . . 29 11.1. Normative References . . . . . . . . . . . . . . . . . . 31
A.4. Example . . . . . . . . . . . . . . . . . . . . . . . . . 29 11.2. Informative References . . . . . . . . . . . . . . . . . 32
Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 30 Appendix A. Overhead . . . . . . . . . . . . . . . . . . . . . . 33
B.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 31 A.1. Length of the Object-Security Option . . . . . . . . . . 33
B.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 32 A.2. Size of the COSE Object . . . . . . . . . . . . . . . . . 33
Appendix C. Object Security of Content (OSCON) . . . . . . . . . 34 A.3. Message Expansion . . . . . . . . . . . . . . . . . . . . 34
C.1. Overhead OSCON . . . . . . . . . . . . . . . . . . . . . 35 A.4. Example . . . . . . . . . . . . . . . . . . . . . . . . . 35
C.2. MAC Only . . . . . . . . . . . . . . . . . . . . . . . . 35 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 36
C.3. Signature Only . . . . . . . . . . . . . . . . . . . . . 36 B.1. Secure Access to Sensor . . . . . . . . . . . . . . . . . 36
C.4. Authenticated Encryption with Additional Data (AEAD) . . 37 B.2. Secure Subscribe to Sensor . . . . . . . . . . . . . . . 38
C.5. Symmetric Encryption with Asymmetric Signature (SEAS) . . 38 Appendix C. Object Security of Content (OSCON) . . . . . . . . . 39
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 38 C.1. Overhead OSCON . . . . . . . . . . . . . . . . . . . . . 40
C.2. MAC Only . . . . . . . . . . . . . . . . . . . . . . . . 41
C.3. Signature Only . . . . . . . . . . . . . . . . . . . . . 42
C.4. Authenticated Encryption with Additional Data (AEAD) . . 43
C.5. Symmetric Encryption with Asymmetric Signature (SEAS) . . 43
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 44
1. Introduction 1. Introduction
The Constrained Application Protocol (CoAP) [RFC7252] is a web The Constrained Application Protocol (CoAP) [RFC7252] is a web
application protocol, designed for constrained nodes and networks application protocol, designed for constrained nodes and networks
[RFC7228]. CoAP specifies the use of proxies for scalability and [RFC7228]. CoAP specifies the use of proxies for scalability and
efficiency. At the same time CoAP references DTLS [RFC6347] for efficiency. At the same time CoAP references DTLS [RFC6347] for
security. Proxy operations on CoAP messages require DTLS to be security. Proxy operations on CoAP messages require DTLS to be
terminated at the proxy. The proxy therefore not only has access to terminated at the proxy. The proxy therefore not only has access to
the data required for performing the intended proxy functionality, the data required for performing the intended proxy functionality,
skipping to change at page 4, line 22 skipping to change at page 4, line 27
| 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 provides protection of CoAP payload, certain options, and
header fields, as well as a secure binding between CoAP request and header fields, as well as a secure binding between CoAP request and
response messages, and freshness of requests and responses. It may response messages. OSCOAP provides replay protection, but like DTLS,
be used in extremely constrained settings, where DTLS cannot be OSCOAP only provides relative freshness in the sense that the
supported. Alternatively, OSCOAP can be combined with DTLS, thereby sequence numbers allows a recipient to determine the relative order
enabling end-to-end security of CoAP payload, in combination with of messages. For applications having stronger demands on freshness
hop-by-hop protection of the entire CoAP message, during transport (e.g. control of actuators), OSCOAP needs to be augmented with
between end-point and intermediary node. Examples of the use of mechanisms providing absolute freshness
OSCOAP are given in Appendix B. [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 C.
1.1. Terminology 1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. These document are to be interpreted as described in [RFC2119]. These
words may also appear in this document in lowercase, absent their words may also appear in this document in lowercase, absent their
normative meanings. normative meanings.
Readers are expected to be familiar with the terms and concepts Readers are expected to be familiar with the terms and concepts
described in [RFC7252] and [RFC7641]. described in [RFC7252] and [RFC7641]. Readers are also expected to
be familiar with [RFC7049] and understand
Terminology for constrained environments, such as "constrained [I-D.greevenbosch-appsawg-cbor-cddl]. Terminology for constrained
device", "constrained-node network", is defined in [RFC7228]. environments, such as "constrained device", "constrained-node
network", is defined in [RFC7228].
Two different scopes of object security are defined:
o OSCOAP = object security of CoAP, signaled with the Object-
Security option.
o OSCON = object security of content, signaled with Content Format/
Media Type set to application/oscon (defined in Appendix C).
2. The Object-Security Option 2. The Object-Security Option
The Object-Security option indicates that OSCOAP is used to protect The Object-Security option indicates that OSCOAP is used to protect
the CoAP message exchange. The protection is achieved by means of a the CoAP message exchange. The protection is achieved by means of a
COSE object included in the protected CoAP message, as detailed in COSE object included in the protected CoAP message, as detailed in
Section 5. Section 5.
The Object-Security option is critical, safe to forward, part of the The Object-Security option is critical, safe to forward, part of the
cache key, and not repeatable. Figure 2 illustrates the structure of cache key, and not repeatable. Figure 2 illustrates the structure of
skipping to change at page 5, line 38 skipping to change at page 5, line 44
+-----+---+---+---+---+-----------------+--------+--------+ +-----+---+---+---+---+-----------------+--------+--------+
| 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 The length of the Object-Security option depends on whether the
unprotected message has payload, on the set of options that are unprotected message allows payload, on the set of options that are
included in the unprotected message, the length of the integrity tag, included in the unprotected message, the length of the integrity tag,
and the length of the information identifying the security context. and the length of the information identifying the security context.
o If the unprotected message has payload, then the COSE object is o If the unprotected message allows payload, then the COSE object is
the payload of the protected message (see Section 6.2 and the payload of the protected message (see Section 6.2 and
Section 6.4), and the Object-Security option has length zero. An Section 6.4), and the Object-Security option has length zero. An
endpoint receiving a CoAP message with payload, that also contains endpoint receiving a CoAP message with payload, that also contains
a non-empty Object-Security option SHALL treat it as malformed and a non-empty Object-Security option SHALL treat it as malformed and
reject it. reject it.
o If the unprotected message does not have payload, then the COSE o If the unprotected message does not allow payload, then the COSE
object is the value of the Object-Security option and the length object is the value of the Object-Security option and the length
of the Object-Security option is equal to the size of the COSE of the Object-Security option is equal to the size of the COSE
object. An endpoint receiving a CoAP message without payload, object. An endpoint receiving a CoAP message without payload,
that also contains an empty Object-Security option SHALL treat it that also contains an empty Object-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
should specify if the payload is optional, required or not allowed
(Section 12.1.2) in the message, and in case this is not defined the
sender must not include a payload (Section 5.5). Thus, in this case,
the COSE object MUST be the value of the Object-Security option.
More details about the message overhead caused by the Object-Security More details about the message overhead caused by the Object-Security
option is given in Appendix A. option are given in Appendix A.
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. The specification requires that client and
server establish a security context to apply to the COSE objects server establish a security context to apply to the COSE objects
protecting the CoAP messages. In this section we define the security protecting the CoAP messages. In this section we define the security
context, and also specify how to establish a security context in context, and also specify how to derive the initial security contexts
client and server based on common shared secret material and a key in client and server based on common shared secret and a key
derivation function (KDF). derivation function (KDF).
The EDHOC protocol [I-D.selander-ace-cose-ecdhe] enables the
establishment of secret material 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.
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. Each security
context is identified by a Context Identifier. A Context Identifier context is identified by a Context Identifier. A Context Identifier
that is no longer in use can be reassigned to a new security context. that is no longer in use can be reassigned to a new security context.
For each endpoint, the security context is composed by a "Common For each endpoint, the security context is composed by a "Common
Context", a "Sender Context" and a "Recipient Context". The Common Context", a "Sender Context" and a "Recipient Context". The
Context includes common security material. The endpoint protects the endpoints protect messages to send using the Sender Context and
messages sent using the Sender Context. The endpoint verifies the verify messages received using the Recipient Context, both contexts
messages received using the Recipient Context. In communication being derived from the Common Context and other data. Each endpoint
between two endpoints, the Sender Context of one endpoint matches the has a unique ID used to derive its Sender Context, this identifier is
Recipient Context of the other endpoint, and vice versa. Note that, called "Sender ID". The Recipient Context is derived with the other
because of that, the two security contexts identified by the same 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 Context Identifiers in the two endpoints are not the same, but they
are partly mirrored. are partly mirrored. Retrieval and use of the security context are
shown in Figure 3."
An example is shown in Figure 3.
.-Cid = Cid1-. .-Cid = Cid1-. .-Cid = Cid1-. .-Cid = Cid1-.
| context: | | context: | | Common, | | Common, |
| Alg, | | Alg, | | 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 | Cid = Cid1, ...] |
Sender +---------------------->| Retrieve context with Sender Context +---------------------->| Retrieve context with
| | Cid = Cid1 | | Cid = Cid1
| | Verify request with | | Verify request with
| | Recipient | | Recipient Context
| response: | Protect response with | response: | Protect response with
| [Token = Token1, ...]| Sender | [Token = Token1, ...] | Sender Context
Retrieve context with |<----------------------+ Retrieve context with |<----------------------+
Token = Token1 | | Token = Token1 | |
Verify request with | | Verify request with | |
Recipient | | Recipient Context | |
Figure 3: Retrieval and use of the Security Context Figure 3: Retrieval and use of the Security Context
The Common Context structure contains the following parameters: The Common Context contains the following parameters:
o Context Identifier (Cid). Variable length byte string that o Context Identifier (Cid). Variable length byte string that
identifies the security context. Its value is immutable once the identifies the security context. Its value is immutable once the
security context is established. 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 (base_key). Byte string containing the key used to o Base Key (master_secret). Variable length, uniformly random byte
derive the security context Section 3.2. string containing the key used to derive traffic keys and IVs.
Its value is immutable once the security context is established.
The Sender Context structure contains the following parameters: The Sender Context contains the following parameters:
o Sender ID. Variable length byte string identifying oneself. Its o Sender ID. Variable length byte string identifying the endpoint
value is immutable once the security context is established. itself. Its value is immutable once the security context is
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. Length is determined by Algorithm. Its value
is immutable once the security context is established. is immutable once the security context is established.
o Sender IV. Byte string containing the fixed portion of IV o Sender IV. Byte string containing the fixed context IV
(context IV in [I-D.ietf-cose-msg]) to protect messages to send. [I-D.ietf-cose-msg]) to protect messages to send. Length is
determined by Algorithm. Its value is immutable once the security
Length is determined by Algorithm. Its value is immutable once context is established.
the security context is established.
o Sender Sequence Number. Non-negative integer enumerating the COSE o Sender Sequence Number. Non-negative integer enumerating the COSE
objects that the endpoint sends, associated to the Context objects that the endpoint sends using the context. Used as
Identifier. It is used for replay protection, and to generate partial IV [I-D.ietf-cose-msg] to generate unique nonces for the
unique IVs for the AEAD. Maximum value is determined by AEAD. Maximum value is determined by Algorithm.
Algorithm.
The Recipient Context structure 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 or sent to. Its value is endpoint messages are received from. Its value is immutable once
immutable once the security context is established. the security 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. Length is determined by the Algorithm. Its
value is immutable once the security context is established. value is immutable once the security context is established.
o Recipient IV. Byte string containing the context IV to verify o Recipient IV. Byte string containing the context IV to verify
messages received. Length is determined by Algorithm. Its value messages received. Length is determined by Algorithm. Its value
is immutable once the security context is established. is immutable once the security context is established.
o Recipient Sequence Number. Non-negative integer enumerating the o Recipient Replay Window. The replay protection window for
COSE objects received, associated to the Context Identifier. It messages received.
is used for replay protection, and to generate unique IVs for the
AEAD. Maximum value is determined by Algorithm.
o Replay Window. The replay protection window for messages
received, equivalent to the functionality described in
Section 4.1.2.6 of [RFC6347].
The 3-tuple (Cid, Sender ID, Sender Sequence Number) is called The 3-tuple (Cid, Sender ID, Partial IV) is called Transaction
Transaction Identifier (Tid), and SHALL be unique for each COSE Identifier (Tid), and SHALL be unique for each Base Key. The Tid is
object and server. The Tid is used as a unique challenge in the COSE used as a unique challenge in the COSE object of the protected CoAP
object of the protected CoAP request. The Tid is part of the request. The Tid is part of the Additional Authenticated Data (AAD,
Additional Authenticated Data (AAD, see Section 5) of the protected see Section 5) of the protected CoAP response message, which is how
CoAP response message, which is how the challenge becomes signed by responses are bound to requests.
the server.
The client and server may change roles while maintaining the same 3.2. Derivation of Security Context Parameters
security context. The former server will then make the request using
the Sender Context, the former client will verify the request using
its Recipient Context etc.
3.2. Security Context Establishment This section describes how to derive the initial parameters in the
security context, given a small set of input parameters. We also
give indications on how applications should select the input
parameters.
This section aims at describing how to establish the security The following input parameters SHALL be pre-established:
context, given some input parameters. The input parameters, which
are established in a previous phase, are:
o Context Identifier (Cid) o Context Identifier (Cid)
o Base Key (master_secret)
o Algorithm (Alg) o AEAD Algorithm (Alg)
o Base Key (base_key) * Default is AES-CCM-64-64-128 (value 12)
The following input parameters MAY be pre-established:
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
o Replay Window (optionally) * Defaults are 0x01 for the endpoint intially being client, and
0x00 for the endpoint initially being server
These are included unchanged in the security context. We give below o Key Derivation Function (KDF)
some indications on how applications should select these parameters.
Moreover, the following parameters are established as described
below:
o Sender Key * Default is HKDF SHA-256
o Sender IV o Replay Window Size
o Sender Sequence Number * Default is 64
o Recipient Key The endpoints MAY interchange the CoAP client and server roles while
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.
o Recipient IV The input parameters are included unchanged in the security context.
From the input parameters, the following parameters are derived:
o Recipient Sequence Number o Sender Key, Sender IV, Sender Sequence Number
o Replay Window o Recipient Key, Recipient IV, Recipient Sequence Number
3.2.1. Derivation of Sender Key/IV, Recipient Key/IV The EDHOC protocol [I-D.selander-ace-cose-ecdhe] enables 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.
Given a common shared secret material and a common key derivation 3.2.1. Derivation of Sender Key/IV, Recipient Key/IV
function, the client and server can derive the security context
necessary to run OSCOAP. The derivation procedure described here
MUST NOT be executed more than once on a set of common secret
material. Also, the same base_key SHOULD NOT be used in different
security contexts (identified by different Cids).
The procedure assumes that the common shared secret material is Given the input parameters, the client and server can derive all the
uniformly random and that the key derivation function is HKDF 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.
[RFC5869]. This is for example the case after having used EDHOC The KDF MUST be one of the HKDF [RFC5869] algorithms defined in COSE.
[I-D.selander-ace-cose-ecdhe]. The KDF HKDF SHA-256 is mandatory to implement. The security context
parameters Sender Key/IV, Recipient Key/IV SHALL be derived using
HKDF, and consists of the composition of the HKDF-Extract and HKDF-
Expand steps ({{RFC5869}):
Assumptions: output parameter = HKDF(master_secret, salt, info, output_length),
o The hash function, denoted HKDF, is the HMAC based key derivation where:
function defined in [RFC5869] with specified hash function
o The common shared secret material, denoted base_key, is uniformly o master_secret is defined above
pseudo-random of length at least equal to the output of the
specified hash function
The security context parameters Sender Key/IV, Recipient Key/IV SHALL o salt is a string of zeros of the length of the hash function
be derived using the HKDF-Expand primitive [RFC5869]: output in octets
output parameter = HKDF-Expand(base_key, info, key_length), o info is a serialized CBOR array consisting of:
where: info = [
cid : bstr,
id : bstr,
alg : int,
out_type : tstr,
out_len : uint
]
o base_key is defined above - id is the Sender ID or Recipient ID
o info = Cid || Sender ID/Recipient ID || "IV"/"Key" || Algorithm || - out_type is "Key" or "IV"
key_length
o key_length is the key size of the AEAD algorithm - out_len is the key/IV size of the AEAD algorithm
The Sender/Recipient Key shall be derived using the Cid concatenated o output_length is the size of the AEAD key/IV in bytes encoded as
with the Sender/Recipient ID, the label "Key", the Algorithm and the an 8-bit unsigned integer
key_length. The Sender/Recipient IV shall be derived using the Cid
concatenated with the Sender/Recipient ID, the label "IV", the
Algorithm and the key_length.
For example, for 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]), key_length for the keys is 128 bits and [I-D.ietf-cose-msg]) is used, output_length for the keys is 128 bits
key_length for the context IVs is 56 bits. and output_length for the IVs is 56 bits.
3.2.2. Sequence Numbers and Replay Window 3.2.2. Context Identifier
The values of the Sequence Numbers are initialized to 0 during As mentioned, Cid is pre-established. How this is done is
establishment of the security context. The default Replay Window application specific, but it is RECOMMENDED that the application uses
size of 64 is used if no input parameter is provided in the set up 64-bits long pseudo-random Cids, in order to have globally unique
phase. 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.
3.2.3. Context Identifier and Sender/Recipient ID If the application has total control of both clients and servers,
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.
As mentioned, Cid, Sender ID and Recipient ID are established in a In the same phase during which the Cid is established in the
previous phase. How this is done is application specific, but some endpoint, the application informs the endpoint what resources can be
guidelines are given in this section. accessed using the corresponding security contexts. Resources that
are accessed with OSCOAP are called "protected" resources. The set
of resources that can be accessed using a certain security context is
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.
It is RECOMMENDED that the application uses 64-bits long pseudo- 3.2.3. Sender ID and Recipient ID
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.
In the same phase during which the Cid is established in the The Sender ID and Recipient ID SHALL be unique in the set of all
endpoint, the application informs the endpoint what resource can be endpoints using the same security context. Collisions may lead to
accessed using the corresponding security context. The granularity the loss of both confidentiality and integrity. If random IDs are
of that is decided by the application (resource, host, etc). The used, they MUST be long enough so that the probability of collisions
endpoint SHALL save the association resource-Cid, in order to be able is negligible.
to retrieve the correct security context to access a resource.
The Sender ID and Recipient ID are also established in the endpoint 3.2.4. Sequence Numbers and Replay Window
during the previous set up phase. The application SHOULD make sure
that these identifiers are locally unique in the set of all endpoints
using the same security context. If it is not the case, it is again
the role of the application to specify how to handle collisions.
In case of EDHOC [I-D.selander-ace-cose-ecdhe]) the Cid is the hash The Sender Sequence Number is initialized to 0. The Recipient Replay
of the messages exchanged. Window is initiated as described in Section 4.1.2.6 of [RFC6347].
4. Protected CoAP Message Fields 4. Protected CoAP Message Fields
This section defines how the CoAP message fields are protected. OSCOAP transforms an unprotected CoAP message into a protected CoAP
OSCOAP protects as much of the unprotected CoAP message as possible, message, and vice versa. This section defines how the unprotected
while still allowing forward proxy operations CoAP message fields are protected. OSCOAP protects as much of the
[I-D.hartke-core-e2e-security-reqs]. unprotected CoAP message as possible, while still allowing forward
proxy operations [I-D.hartke-core-e2e-security-reqs].
The CoAP Payload SHALL be encrypted and integrity protected. This section also outlines how the message fields are processed and
transferred, a detailed description is provided in Section 6.
Message fields of the unprotected CoAP message are either transferred
in the header/options part of the protected CoAP message, or in the
plaintext of the COSE object. Depending on which, the location of
the message field in the protected CoAP message is called "outer" or
"inner":
The CoAP Header fields Version and Code SHALL be integrity protected o Inner message field = message field included in the plaintext of
but not encrypted. The CoAP Message Layer parameters, Type and the COSE object of the protected CoAP message (see Section 5.1)
Message ID, as well as Token and Token Length SHALL neither be
integrity protected nor encrypted.
Protection of CoAP Options can be summarized as follows: o Outer message field = message field included in the header or
options part of the protected CoAP message
o To prevent information leakage, Uri-Path and Uri-Query SHALL be The inner message fields are encrypted and integrity protected by the
encrypted. If Proxy-Uri is used and thus Uri-* are not present, COSE object. The outer message fields are sent in plain text but may
then OSCOAP implementation MUST first split the Proxy-Uri into the be integrity protected by including the message field values in the
unencrypted Uri Section 5.2 and the Uri-Path/Query options AAD of the COSE object (see Section 5.2).
(according to section 6.4 of [RFC7252]), replace the Proxy-Uri
value with the unencrypted Uri, and encrypt Uri-Path/Query, which
will then be carried in the ciphertext. This means that the proxy
will not be able to see that Uri-Path and Uri-Query options are
present in the message and will thus process the message as
indicated by CoAP.
o The CoAP Options Uri-Host, Uri-Port, Proxy-Uri, and Proxy-Scheme Note that, even though the message formats are slightly different,
SHALL neither be encrypted, nor integrity protected. Note that OSCOAP complies with CoAP over unreliable transport [RFC7252] as well
even though these options are not protected, their values are as CoAP over reliable transport [I-D.ietf-core-coap-tcp-tls].
included in the additional authenticated data, thus they are
indirectly integrity protected (cf. protection of the unencrypted
Uri in Section 5.2).
o The other CoAP options SHALL be encrypted and integrity protected. 4.1. CoAP Payload
A summary of which options are encrypted or integrity protected is The CoAP Payload SHALL be encrypted and integrity protected, and thus
shown in Figure 4. is an inner message field.
The sending endpoint writes the payload of the unprotected CoAP
message into the plaintext of the COSE object (see Section 6.2 and
Section 6.4).
The receiving endpoint verifies and decrypts the COSE object, and
recreates the payload of the unprotected CoAP message (see
Section 6.3 and Section 6.5).
4.2. CoAP Header
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
protected between the endpoints, e.g. CoAP message layer fields such
as Message ID.
The CoAP header field Code MUST be sent in plaintext to support
RESTful processing, but MUST be integrity protected to prevent an
intermediary from changing, e.g. from GET to DELETE. The CoAP
version number SHALL be integrity protected to prevent potential
future version-based attacks. Note that while the version 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
server.
Other CoAP header fields SHALL neither be integrity protected nor
encrypted. The CoAP header fields are thus outer message fields.
The sending endpoint SHALL copy the header fields from the
unprotected CoAP message to the protected CoAP message. The
receiving endpoint SHALL copy the header fields from the protected
CoAP message to the unprotected CoAP message. Both sender and
receiver inserts the CoAP version number and header field Code in the
AAD of the COSE object (see section Section 5.2).
4.3. CoAP Options
As with the message fields described in the previous sections, CoAP
options may be encrypted and integrity protected, integrity protected
only, or neither encrypted nor integrity protected.
Most options are encrypted and integrity protected (see Figure 4),
and thus inner message fields. But to allow certain proxy
operations, some options have outer values and require special
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 | D | | No.| C | U | N | R | Name | Format | Length | E | A |
+----+---+---+---+---+----------------+--------+--------+---+---+ +----+---+---+---+---+----------------+--------+--------+---+---+
| 1 | x | | | x | If-Match | opaque | 0-8 | x | | | 1 | x | | | x | If-Match | opaque | 0-8 | x | |
| 3 | x | x | - | | Uri-Host | string | 1-255 | | | | 3 | x | x | - | | Uri-Host | string | 1-255 | | x |
| 4 | | | | x | ETag | opaque | 1-8 | x | | | 4 | | | | x | ETag | opaque | 1-8 | x | |
| 5 | x | | | | If-None-Match | empty | 0 | x | | | 5 | x | | | | If-None-Match | empty | 0 | x | |
| 6 | | x | - | | Observe | uint | 0-3 | x | x | | 6 | | x | - | | Observe | uint | 0-3 | * | |
| 7 | x | x | - | | Uri-Port | uint | 0-2 | | | | 7 | x | x | - | | Uri-Port | uint | 0-2 | | x |
| 8 | | | | x | Location-Path | string | 0-255 | x | | | 8 | | | | x | Location-Path | string | 0-255 | x | |
| 11 | x | x | - | x | Uri-Path | string | 0-255 | x | | | 11 | x | x | - | x | Uri-Path | string | 0-255 | x | |
| 12 | | | | | Content-Format | uint | 0-2 | x | | | 12 | | | | | Content-Format | uint | 0-2 | x | |
| 14 | | x | - | | Max-Age | uint | 0-4 | x | x | | 14 | | x | - | | Max-Age | uint | 0-4 | * | |
| 15 | x | x | - | x | Uri-Query | string | 0-255 | x | | | 15 | x | x | - | x | Uri-Query | string | 0-255 | x | |
| 17 | x | | | | Accept | uint | 0-2 | x | | | 17 | x | | | | Accept | uint | 0-2 | x | |
| 20 | | | | x | Location-Query | string | 0-255 | x | | | 20 | | | | x | Location-Query | string | 0-255 | x | |
| 23 | x | x | - | - | Block2 | uint | 0-3 | x | x | | 23 | x | x | - | - | Block2 | uint | 0-3 | * | |
| 27 | x | x | - | - | Block1 | uint | 0-3 | x | x | | 27 | x | x | - | - | Block1 | uint | 0-3 | * | |
| 28 | | | x | | Size2 | unit | 0-4 | x | x | | 28 | | | x | | Size2 | unit | 0-4 | * | |
| 35 | x | x | - | | Proxy-Uri | string | 1-1034 | | | | 35 | x | x | - | | Proxy-Uri | string | 1-1034 | | * |
| 39 | x | x | - | | Proxy-Scheme | string | 1-255 | | | | 39 | x | x | - | | Proxy-Scheme | string | 1-255 | | x |
| 60 | | | x | | Size1 | uint | 0-4 | x | x | | 60 | | | x | | Size1 | uint | 0-4 | * | |
+----+---+---+---+---+----------------+--------+--------+---+---+ +----+---+---+---+---+----------------+--------+--------+---+---+
C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable, C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable,
E=Encrypt and Integrity Protect, D=Duplicate. E=Encrypt and Integrity Protect, A=Integrity Protect, *=Special
Figure 4: Protection of CoAP Options Figure 4: Protection of CoAP Options
A summary of how options are protected and processed is shown in
Figure 4. The CoAP options are partitioned into two classes:
o E - options which are encrypted and integrity protected, and
o A - options which are only integrity protected.
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.
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. be encrypted and integrity protected and processed as class E
options.
The encrypted options are in general omitted from the protected CoAP Specifications of new CoAP options SHOULD specify how they are
message and not visible to intermediary nodes (see Section 6.2 and processed with OSCOAP. New COAP options SHOULD be of class E and
Section 6.4). Hence the actions resulting from the use of SHOULD NOT have outer options unless a forwarding proxy needs to read
corresponding options is analogous to the case of communicating an option value. If a certain option is both inner and outer, the
directly with the endpoint. For example, a client using an ETag two values SHOULD NOT be the same, unless a proxy is required by
option will not be served by a proxy. specification to be able to read the end-to-end value.
However, some options which are encrypted need to be readable in the 4.3.1. Class E Options
protected CoAP message to support certain proxy functions. A CoAP
option which may be both encrypted in the COSE object of the
protected CoAP message, and also unencrypted as CoAP option in the
protected CoAP message, is called "duplicate". The "encrypted" value
of a duplicate option is intended for the destination endpoint and
the "unencrypted" value is intended for a proxy. The unencrypted
value is not integrity protected.
o The Max-Age option is duplicate. The unencrypted Max-Age SHOULD For options in class E (see Figure 4) the option value in the
have value zero to prevent caching of responses. The encrypted unprotected CoAP message, if present, SHALL be encrypted and
Max-Age is used as defined in [RFC7252] taking into account that integrity protected between the endpoints, and thus is not visible to
it is not accessible to proxies. or possible to change by intermediary nodes. Hence the actions
resulting from the use of such options is analogous to communicating
in a protected manner with the endpoint. For example, a client using
an ETag option will not be served by a proxy.
o The Observe option is duplicate. If Observe is used, then the The sending endpoint SHALL write the class E option from the
encrypted Observe and the unencrypted Observe SHALL have the same unprotected CoAP message into the plaintext of the COSE object (see
value. The Observe option as used here targets the requirements Section 6.2 and Section 6.4).
on forwarding of [I-D.hartke-core-e2e-security-reqs]
(Section 2.2.1.2).
o The block options Block1 and Block2 are duplicate. The encrypted Except for the special options described in the subsections, the
block options is used for end-to-end secure fragmentation of sending endpoint SHALL NOT use the outer options of class E.
payload into blocks and protected information about the However, note that an intermediary may, legimitimately or not, add,
fragmentation (block number, last block, etc.). The MAC from each change or remove the value of an outer option.
block is included in the calculation of the MAC for the next
block's (see Section 5.2). In this way, each block in ordered
sequence from the first block can be verified as it arrives. The
unencrypted block option allows for arbitrary proxy fragmentation
operations which cannot be verified by the endpoints. An
intermediary node can generate an arbitrarily long sequence of
blocks. However, since it is possible to protect fragmentation of
large messages, there SHALL be a security policy defining a
maximum unfragmented message size such that messages exceeding
this size SHALL be fragmented by the sending endpoint. Hence an
endpoint receiving fragments of a message that exceeds maximum
message size SHALL discard this message.
o The size options Size1 and Size2 are duplicate, analogously to the Execept for the Block options Section 4.3.1.3, the receiving endpoint
block options. 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
present (see Section 6.3 and Section 6.5).
Specifications of new CoAP options SHOULD specify how they are 4.3.1.1. Max-Age
processed with OSCOAP. New COAP options SHALL be encrypted and
integrity protected. New COAP options SHOULD NOT be duplicate unless An inner Max-Age option is used as defined in [RFC7252] taking into
a forwarding proxy needs to read the option. If an option is account that it is not accessible to proxies.
registered as duplicate, the duplicate value SHOULD NOT be the same
as the end-to-end value, unless the proxy is required by Since OSCOAP binds CoAP responses to requests, a cached response
specification to be able to read the end-to-end value. would not be possible to use for any other request. Therefore, there
SHOULD be an outer Max-Age option with value zero to prevent caching
of 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
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
protected.
4.3.1.3. The Block Options
The Block options (Block1, Block2, Size1 and Size2) MAY be either
only inner options, only outer options or both inner and outer
options. The inner and outer options are processed independently.
The inner block options are used for endpoint-to-endpoint secure
fragmentation of payload into blocks and protection of information
about the fragmentation (block number, last block, etc.).
Additionally, a proxy may arbitrarily do fragmentation operations on
the protected CoAP message, adding outer block options that are not
intended to be verified by any endpoint or proxy.
There SHALL be a security policy defining a maximum unfragmented
message size for inner Block options such that messages exceeding
this size SHALL be fragmented by the sending endpoint.
In addition to the processing defined for the inner Block options
inherent to class E options, the AEAD Tag from each block SHALL be
included in the calculation of the Tag for the next block (see
Section 5.2), so that each block in the order being sent can be
verified as it arrives.
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
first process this option according to [RFC7959], until all blocks of
the protected CoAP message has been received, or the cumulated
message size of the exceeds the maximum unfragmented message size.
In the latter case the message SHALL be discarded. In the former
case, the processing of the protected CoAP message continues as
defined in this document (see Section 6.3 and Section 6.5).
If the unprotected CoAP message contains Block options, the receiving
endpoint processes this according to {{RFC7959}.
4.3.2. Class A Options
Options in this class are used to support forward proxy operations.
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.
When Uri-Host, Uri-Port, Proxy-Scheme options are present, Proxy-Uri
is not used [RFC7252]. Proxy-Uri is processed like the other class A
options after a pre-processing step (see Section 4.3.2.1.
Except for Proxi-Uri, the sending endpoint SHALL copy the class A
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
Proxy-Uri, when present, is split by OSCOAP into class A options and
privacy sensitive class E options, which are processed accordingly.
When Proxy-Uri is used in the unprotected CoAP message, Uri-* are not
present [RFC7252].
The sending endpoint SHALL first decompose the Proxy-Uri value of the
unprotected CoAP message into the unencrypted-Uri (Section 5.2) and
Uri-Path/Query options according to section 6.4 of [RFC7252].
Uri-Path and Uri-Query are class E options and SHALL be protected and
processed as if obtained from the unprotected CoAP message, see
Section 4.3.1.
The value of the Proxy-Uri option of the protected CoAP message SHALL
be replaced with unencrypted-Uri and SHALL be protected and processed
as a class A option, see Section 4.3.2.
5. The COSE Object 5. The COSE Object
This section defines how to use the COSE format [I-D.ietf-cose-msg] This section defines how to use the COSE format [I-D.ietf-cose-msg]
to wrap and protect data in the unprotected CoAP message. OSCOAP to wrap and protect data in the unprotected CoAP message. OSCOAP
uses the COSE_Encrypt0 structure with an Authenticated Encryption uses the COSE_Encrypt0 structure with an Authenticated Encryption
with Additional Data (AEAD) algorithm. with Additional Data (AEAD) algorithm.
The mandatory to support AEAD algorithm is AES-CCM-64-64-128 defined The AEAD algorithm AES-CCM-64-64-128 defined in Section 10.2 of
in Section 10.2 of [I-D.ietf-cose-msg]. For AES-CCM-64-64-128 the [I-D.ietf-cose-msg] is mandatory to implement. For AES-CCM-64-64-128
length of Sender Key and Recipient Key SHALL be 128 bits, the length the length of Sender Key and Recipient Key SHALL be 128 bits, the
of IV, Sender IV, and Recipient IV SHALL be 7 bytes, and the maximum length of nonce, Sender IV, and Recipient IV SHALL be 7 bytes, and
Sender Sequence Number and Recipient Sequence Number SHALL be 2^56-1. the maximum Sequence Number SHALL be 2^56-1. The nonce is
The IV is constructed using a Partial IV exactly like in Section 3.1 constructed as described in Section 3.1 of [I-D.ietf-cose-msg], i.e.
of [I-D.ietf-cose-msg], i.e. by padding the Sender Sequence Number or by padding the Partial IV (Sequence Number) with zeroes and XORing it
the Recipient Sequence Number with zeroes and XORing it with the with the context IV (Sender IV or Recipient IV).
Sender IV or Recipient IV, respectively.
Since OSCOAP only makes use of a single COSE structure, there is no Since OSCOAP only makes use of a single COSE structure, there is no
need to explicitly specify the structure, and OSCOAP uses the need to explicitly specify the structure, and OSCOAP uses the
untagged version of the COSE_Encrypt0 structure (Section 2. of untagged version of the COSE_Encrypt0 structure (Section 2. of
[I-D.ietf-cose-msg]). If the COSE object has a different structure, [I-D.ietf-cose-msg]). If the COSE object has a different structure,
the recipient MUST reject the message, treating it as malformed. the recipient MUST reject the message, treating it as malformed.
OSCOAP introduces a new COSE Header Parameter, the Sender Identifier:
sid: This parameter is used to identify the sender of the message.
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.
+------+-------+------------+----------------+-------------------+
| name | label | value type | value registry | description |
+------+-------+------------+----------------+-------------------+
| sid | TBD | bstr | | Sender Identifier |
+------+-------+------------+----------------+-------------------+
Table 1: Additional COSE Header Parameter
We denote by Plaintext the data that is encrypted and integrity We denote by Plaintext the data that is encrypted and integrity
protected, and by Additional Authenticated Data (AAD) the data that protected, and by Additional Authenticated Data (AAD) the data that
is integrity protected only, in the COSE object. is integrity protected only, in the COSE object.
The fields of COSE_Encrypt0 structure are defined as follows (see The fields of COSE_Encrypt0 structure are defined as follows (see
example in Appendix C.4). example in Appendix C.4).
o The "Headers" field is formed by: o The "Headers" field is formed by:
* The "protected" field, which SHALL include: * The "protected" field, which SHALL include:
+ The "Partial IV" parameter. The value is set to the Sender + The "Partial IV" parameter. The value is set to the Sender
Sequence Number. The Partial IV is a byte string (type: Sequence Number. The Partial IV is a byte string (type:
bstr), where the length is the minimum length needed to bstr), and SHOULD be of minimum length needed to encode the
encode the sequence number. An Endpoint that receives a sequence number.
COSE object with a sequence number encoded with leading
zeroes (i.e. longer than the minimum needed length) SHALL
reject the corresponding message as malformed.
+ The "kid" parameter. The value is set to the Context + The "kid" parameter. The value is set to the Context
Identifier (see Section 3). This parameter is optional if Identifier (see Section 3). This parameter is optional if
the message is a CoAP response. the message is a CoAP response.
+ Optionally, the parameter called "sid", defined below. The + Optionally, the parameter called "sid", defined below. The
value is set to the Sender ID (see Section 3). Note that value is set to the Sender ID (see Section 3). Note that
since this parameter is sent in clear, privacy issues SHOULD since this parameter is sent in clear, privacy issues SHOULD
be considered by the application defining the Sender ID. be considered by the application defining the Sender ID.
* The "unprotected" field, which SHALL be empty. * The "unprotected" field, which SHALL be empty.
o The "cipher text" 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) and encoded as a byte string (type: bstr), following
Section 5.2 of [I-D.ietf-cose-msg]. Section 5.2 of [I-D.ietf-cose-msg].
sid: This parameter is used to identify the sender of the message.
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.
+------+-------+------------+----------------+-------------------+
| name | label | value type | value registry | description |
+------+-------+------------+----------------+-------------------+
| sid | TBD | bstr | | Sender identifier |
+------+-------+------------+----------------+-------------------+
Table 1: Additional COSE Header Parameter
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 CoAP Options present in the unprotected message which are
encrypted (see Section 4), in the order as given by the Option encrypted (see Section 4), in the order as given by the Option
number (each Option with Option Header including delta to previous number (each Option with Option Header including delta to previous
included encrypted option); and included encrypted option); and
skipping to change at page 16, line 27 skipping to change at page 19, line 49
5.2. Additional Authenticated Data 5.2. Additional Authenticated Data
The Additional Authenticated Data ("Enc_structure") as described is The Additional Authenticated Data ("Enc_structure") as described is
Section 5.3 of [I-D.ietf-cose-msg] includes: Section 5.3 of [I-D.ietf-cose-msg] includes:
o the "context" parameter, which has value "Encrypted" o the "context" parameter, which has value "Encrypted"
o the "protected" parameter, which includes the "protected" part of o the "protected" parameter, which includes the "protected" part of
the "Headers" field; the "Headers" field;
o the "external_aad" is a serialized CBOR array (see Figure 8) that o the "external_aad" is a serialized CBOR array Figure 6 where the
contains, in the given order: exact content is different in requests (external_aad_req) and
repsonses (external_aad_resp). It contains:
* ver: uint, contains the CoAP version number of the unprotected * ver: uint, contains the CoAP version number, as defined in
CoAP message, as defined in Section 3 of [RFC7252] Section 3 of [RFC7252]
* code: bstr, contains is the CoAP Code of the unprotected CoAP * code: uint, contains is the CoAP Code of the unprotected CoAP
message, as defined in Section 3 of [RFC7252]. message, as defined in Section 3 of [RFC7252].
* alg: bstr, contains the serialized Algorithm from the security * alg: int, contains the Algorithm from the security context used
context used for the exchange (see Section 3.1); for the exchange (see Section 3.1);
* unencrypted-uri: tstr, contains the part of the URI which is * unencrypted-uri: tstr with tag URI, contains the part of the
not encrypted, and is composed of the request scheme (Proxy- URI which is not encrypted, and is composed of the request
Scheme if present), Uri-Host and Uri-Port options according to scheme (Proxy-Scheme if present), Uri-Host and Uri-Port (if
the method described in Section 6.5 of [RFC7252], if the present) options according to the method described in
message is a CoAP request; Section 6.5 of [RFC7252], if the message is a CoAP request;
* transaction-id: bstr, only included if the message to protect * cid : bstr, contains the cid for the request (which is same as
or verify is a CoAP response, contains the Transaction the cid for the response).
Identifier (Tid) of the associated CoAP request (see
Section 3). Note that the Tid is the 3-tuple (Cid, Sender ID,
Sender Sequence Number) for the endpoint sending the request
and verifying the response; which means that for the endpoint
sending the response, the Tid has value (Cid, Recipient ID,
seq), where seq is the value of the "Partial IV" in the COSE
object of the request (see Section 5); and
* mac-previous-block: bstr, contains the MAC of the message * id : bstr, is the identifier for the endpoint sending the
request and verifying the response; which means that for the
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
of the request (see Section 5).
* tag-previous-block: bstr, contains the AEAD Tag of the message
containing the previous block in the sequence, as enumerated by containing the previous block in the sequence, as enumerated by
Block1 in the case of a request and Block2 in the case of a Block1 in the case of a request and Block2 in the case of a
response, if the message is fragmented using a block option response, if the message is fragmented using a block option
[RFC7959]. [RFC7959].
external_aad_req = [ external_aad = external_aad_req / external_aad_resp
ver : uint,
code : bstr,
alg : bstr,
unencrypted-uri : tstr,
? mac-previous-block : bstr
]
Figure 6: external_aad for a request
external_aad_resp = [
ver : uint,
code : bstr,
alg : bstr,
transaction-id : bstr,
? mac-previous-block : bstr
]
Figure 7: external_aad for a response external_aad_req = [
ver : uint,
code : uint,
alg : int,
unencrypted-uri : uri,
? tag-previous-block : bstr
]
external_aad = external_aad_req / external_aad_resp external_aad_resp = [
ver : uint,
code : uint,
alg : int,
cid : bstr,
id : bstr,
seq : bstr,
? tag-previous-block : bstr
]
Figure 8: external_aad Figure 6: External AAD (external_aad)
The encryption process is described in Section 5.3 of The encryption process is described in Section 5.3 of
[I-D.ietf-cose-msg]. [I-D.ietf-cose-msg].
6. Protecting CoAP Messages 6. Protecting CoAP Messages
6.1. Replay and Freshness Protection 6.1. Replay and Freshness Protection
In order to protect from replay of messages and verify freshness, a In order to protect from replay of messages and verify freshness, a
CoAP endpoint SHALL maintain a Sender Sequence Number, and a CoAP endpoint SHALL maintain a Sender Sequence Number and a Recipient
Recipient Sequence Number associated to a security context, which is Replay Window in the security context. An endpoint uses the Sender
identified with a Context Identifier (Cid). The two sequence numbers Sequence Number to protect messages to send and the Recipient Replay
are the highest sequence number the endpoint has sent and the highest Window to verify received messages, as described in Section 3.
sequence number the endpoint has received. An endpoint uses the
Sender Sequence Number to protect messages to send and the Recipient
Sequence Number to verify received messages, as described in
Section 3.
Depending on use case and ordering of messages provided by underlying A receiving endpoint SHALL verify that the Sequence Number (Partial
layers, an endpoint MAY maintain a sliding replay window for Sequence IV) received in the COSE object has not been received before in the
Numbers of received messages associated to each Cid. In case of security context identified by the Cid. The size of the Replay Window
reliable transport, the receiving endpoint MAY require that the depends on the use case and lower protocol layers. In case of
Sequence Number of a received message equals last Sequence Number + reliable and ordered transport, the recipient MAY just store the last
1. received sequence number and require that newly received Sequence
Numbers equals the last received Recipient Sequence Number + 1.
A receiving endpoint SHALL verify that the Sequence Number received The receiving endpoint SHALL reject messages with a sequence number
in the COSE object has not been received before in the security greater than the maximum value of the Partial IV. This maximum value
context identified by the Cid. The receiving endpoint SHALL also is algorithm specific, for example for AES-CCM-64-64-128 it is
reject messages with a sequence number greater than 2^56-1. 2^56-1.
OSCOAP is a challenge-response protocol, where the response is OSCOAP responses are verified to match a prior request, by including
verified to match a prior request, by including the unique the unique transaction identifier (Tid as defined in Section 3) of
transaction identifier (Tid as defined in Section 3) of the request the request in the Additional Authenticated Data of the response
in the Additional Authenticated Data of the response message. message. In case of CoAP observe, each notification MUST be verified
using the Tid of the observe registration, so the Tid of the
registration needs to be cached by the observer until the observation
ends.
If a CoAP server receives a request with the Object-Security option, If a CoAP server receives a request with the Object-Security option,
then the server SHALL include the Tid of the request in the AAD of then the server SHALL include the Tid of the request in the AAD of
the response, as described in Section 6.4. the response, as described in Section 6.4.
If the CoAP client receives a response with the Object-Security If the CoAP client receives a response with the Object-Security
option, then the client SHALL verify the integrity of the response, option, then the client SHALL verify the integrity of the response,
using the Tid of its own associated request in the AAD, as described using the Tid of its own associated request in the AAD, as described
in Section 6.5. in Section 6.5.
6.2. Protecting the Request 6.2. Protecting the Request
Given an unprotected CoAP request, including header, options and Given an unprotected CoAP request, including header, options and
payload, the client SHALL perform the following steps to create a payload, the client SHALL perform the following steps to create a
protected CoAP request using a security context associated with the protected CoAP request using a security context associated with the
target resource (see Section 3.2.3). target resource (see Section 3.2.2).
1. Increment the Sender Sequence Number by one (note that this means When using Uri-Host or Proxy-Uri in the construction of the request,
that sequence number 0 is never used). If the Sender Sequence the <host> value MUST be a reg-name ([RFC3986]), and not an IP-
Number exceeds the maximum number for the AEAD algorithm, the literal or IPv4address, for canonicalization of the destination
client MUST NOT process any requests with the given security address.
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.
2. Compute the COSE object as specified in Section 5 1. Compute the COSE object as specified in Section 5
* the IV in the AEAD is created by XORing the Sender IV (context * the AEAD nonce is created by XORing the Sender IV (context IV)
IV) with the Sender Sequence Number (partial IV). with the Sender Sequence Number (partial IV).
* If the block option is used, the AAD includes the MAC from the * If the block option is used, the AAD includes the AEAD Tag
previous fragment sent (from the second fragment and from the previous block sent (from the second block and
following) Section 5.2. This means that the endpoint MUST following) Section 5.2. This means that the endpoint MUST
store the MAC of each last-sent fragment to compute the store the Tag of each last-sent block to compute the
following. following.
* Note that the 'sid' field containing the Sender ID is included * Note that the 'sid' field containing the Sender ID is included
in the COSE object (Section 5) if the application needs it. in the COSE object (Section 5) if the application needs it.
3. Format the protected CoAP message as an ordinary CoAP message, 2. Format the protected CoAP message as an ordinary CoAP message,
with the following Header, Options, and Payload, based on the with the following Header, Options, and Payload, based on the
unprotected CoAP message: unprotected CoAP message:
* The CoAP header is the same as the unprotected CoAP message. * The CoAP header is the same as the unprotected CoAP message.
* The CoAP options which are encrypted and not duplicate * If present, the CoAP option Proxy-Uri is decomposed as
(Section 4) are removed. Any duplicate option which is described in Section 4.3.2.1.
present has its unencrypted value. The Object-Security option
is added. * The CoAP options which are of class E (Section 4) are removed.
The Object-Security option is added.
* If the message type of the unprotected CoAP message does not * If the message type of the unprotected CoAP message does not
allow Payload, then the value of the Object-Security option is allow Payload, then the value of the Object-Security option is
the COSE object. If the message type of the unprotected CoAP the COSE object. If the message type of the unprotected CoAP
message allows Payload, then the Object-Security option is message allows Payload, then the Object-Security option is
empty and the Payload of the protected CoAP message is the empty and the Payload of the protected CoAP message is the
COSE object. COSE object.
4. Store in memory the association Token - Cid. The Client SHALL be 3. Store the association Token - Cid. The Client SHALL be able to
able to find the correct security context used to protect the find the correct security context used to protect the request and
request and verify the response with use of the Token of the verify the response with use of the Token of the message
message exchange. exchange.
4. Increment the Sender Sequence Number by one. If the Sender
Sequence Number exceeds the maximum number for the AEAD
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 6.3. Verifying the Request
A CoAP server receiving an unprotected CoAP request to access a
protected resource (as defined Section 3.2.2) SHALL reject the
message with error code 4.01 (Unauthorized).
A CoAP server receiving a message containing the Object-Security
option and a outer Block option SHALL first process this option
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 A CoAP server receiving a message containing the Object-Security
option SHALL perform the following steps, using the security context option SHALL perform the following steps, using the security context
identified by the Context Identifier in the "kid" parameter in the identified by the Context Identifier in the "kid" parameter in the
received COSE object: received COSE object:
1. Verify the Sequence Number in the Partial IV parameter, as 1. Verify the Sequence Number in the Partial IV parameter, as
described in Section 6.1. If it cannot be verified that the described in Section 6.1. If it cannot be verified that the
Sequence Number has not been received before, the server MUST Sequence Number has not been received before, the server MUST
stop processing the request. stop processing the request.
2. Recreate the Additional Authenticated Data, as described in 2. Recreate the Additional Authenticated Data, as described in
Section 5. Section 5.
* If the block option is used, the AAD includes the MAC from the * If the block option is used, the AAD includes the AEAD Tag
previous fragment received (from the second fragment and from the previous block received (from the second block and
following) Section 5.2. This means that the endpoint MUST following) Section 5.2. This means that the endpoint MUST
store the MAC of each last-received fragment to compute the store the Tag of each last-received block to compute the
following. following.
3. Compose the IV by XORing the Recipient IV (context IV) with the * Note that the server's <host> value MUST be a reg-name
Partial IV parameter, received in the COSE Object. ([RFC3986]), and not an IP-literal or IPv4address.
3. Compose the AEAD nonce by XORing the Recipient IV (context IV)
with the padded Partial IV parameter, received in the COSE
Object.
4. Retrieve the Recipient Key. 4. Retrieve the Recipient Key.
5. Verify and decrypt the message. If the verification fails, the 5. Verify and decrypt the message. If the verification fails, the
server MUST stop processing the request. server MUST stop processing the request.
6. If the message verifies, update the Recipient Sequence Number or 6. If the message verifies, update the Recipient Replay Window, as
Replay Window, as described in Section 6.1. described in Section 6.1.
7. Restore the unprotected request by adding any decrypted options 7. Restore the unprotected request by adding any decrypted options
or payload from the plaintext. Any duplicate options (Section 4) or payload from the plaintext. Any outer E options (Section 4)
are overwritten. The Object-Security option is removed. are overwritten. The Object-Security option is removed.
6.4. Protecting the Response 6.4. Protecting the Response
A server receiving a valid request with a protected CoAP message A server receiving a valid request with a protected CoAP message
(i.e. containing an Object-Security option) SHALL respond with a (i.e. containing an Object-Security option) SHALL respond with a
protected CoAP message. protected CoAP message.
Given an unprotected CoAP response, including header, options, and Given an unprotected CoAP response, including header, options, and
payload, the server SHALL perform the following steps to create a payload, the server SHALL perform the following steps to create a
protected CoAP response, using the security context identified by the protected CoAP response, using the security context identified by the
Context Identifier of the received request: Context Identifier of the received request:
1. Increment the Sender Sequence Number by one (note that this means 1. Compute the COSE object as specified in Section Section 5
that sequence number 0 is never used). If the Sender Sequence
Number exceeds the maximum number for the AEAD 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.
2. Compute the COSE object as specified in Section Section 5
* The IV in the AEAD is created by XORing the Sender IV (context * The AEAD nonce is created by XORing the Sender IV (context IV)
IV) and the Sender Sequence Number. and the padded Sender Sequence Number.
* If the block option is used, the AAD includes the MAC from the * If the block option [RFC7959] is used, the AAD includes the
previous fragment sent (from the second fragment and AEAD Tag from the previous block sent (from the second block
following) Section 5.2. This means that the endpoint MUST and following) Section 5.2. This means that the endpoint MUST
store the MAC of each last-sent fragment to compute the store the Tag of each last-sent block to compute the
following. 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).
3. Format the protected CoAP message as an ordinary CoAP message, 2. Format the protected CoAP message as an ordinary CoAP message,
with the following Header, Options, and Payload based on the with the following Header, Options, and Payload based on the
unprotected CoAP message: unprotected CoAP message:
* The CoAP header is the same as the unprotected CoAP message. * The CoAP header is the same as the unprotected CoAP message.
* The CoAP options which are encrypted and not duplicate * The CoAP options which are of class E are removed, except any
(Section 4) are removed. Any duplicate option which is special option (labelled '*') that is present which has its
present has its unencrypted value. The Object-Security option outer value (Section 4). The Object-Security option is added.
is added.
* If the message type of the unprotected CoAP message does not * If the message type of the unprotected CoAP message does not
allow Payload, then the value of the Object-Security option is allow Payload, then the value of the Object-Security option is
the COSE object. If the message type of the unprotected CoAP the COSE object. If the message type of the unprotected CoAP
message allows Payload, then the Object-Security option is message allows Payload, then the Object-Security option is
empty and the Payload of the protected CoAP message is the empty and the Payload of the protected CoAP message is the
COSE object. COSE object.
3. Increment the Sender Sequence Number by one. If the Sender
Sequence Number exceeds the maximum number for the AEAD
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 Note the differences between generating a protected request, and a
protected response, for example whether "kid" is present in the protected response, for example whether "kid" is present in the
header, or whether Destination URI or Tid is present in the AAD, of header, or whether Destination URI or Tid is present in the AAD, of
the COSE object. the COSE object.
6.5. Verifying the Response 6.5. Verifying the Response
A CoAP client receiving a message containing the Object-Security A CoAP client receiving a message containing the Object-Security
option SHALL perform the following steps, using the security context option SHALL perform the following steps, using the security context
identified by the Token of the received response: identified by the Token of the received response:
1. Verify the Sequence Number in the Partial IV parameter as 1. If the message contain an outer Block option the client SHALL
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
described in Section 6.1. If it cannot be verified that the described in Section 6.1. If it cannot be verified that the
Sequence Number has not been received before, the client MUST Sequence Number has not been received before, the client MUST
stop processing the response. stop processing the response.
2. Recreate the Additional Authenticated Data as described in 3. Recreate the Additional Authenticated Data as described in
Section 5. Section 5.
* If the block option is used, the AAD includes the MAC from the * If the block option is used, the AAD includes the AEAD Tag
previous fragment received (from the second fragment and from the previous block received (from the second block and
following) Section 5.2. This means that the endpoint MUST following) Section 5.2. This means that the endpoint MUST
store the MAC of each last-received fragment to compute the store the Tag of each last-received block to compute the
following. following.
3. Compose the IV by XORing the Recipient IV (context IV) with the 4. Compose the AEAD nonce by XORing the Recipient IV (context IV)
Partial IV parameter, received in the COSE Object. with the Partial IV parameter, received in the COSE Object.
4. Retrieve the Recipient Key. 5. Retrieve the Recipient Key.
5. Verify and decrypt the message. If the verification fails, the 6. Verify and decrypt the message. If the verification fails, the
client MUST stop processing the response. client MUST stop processing the response.
6. If the message verifies, update the Recipient Sequence Number or 7. If the message verifies, update the Recipient Replay Window, as
Replay Window, as described in Section 6.1. described in Section 6.1.
7. Restore the unprotected response by adding any decrypted options 8. Restore the unprotected response by adding any decrypted options
or payload from the plaintext. Any duplicate options (Section 4) or payload from the plaintext. Any class E options (Section 4)
are overwritten. The Object-Security option is removed. are overwritten. The Object-Security option is removed.
7. Security Considerations 7. 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
skipping to change at page 23, line 12 skipping to change at page 27, line 21
common shared secret material and key derivation function in client common shared secret material and key derivation function in client
and server. EDHOC [I-D.selander-ace-cose-ecdhe] describes an and server. EDHOC [I-D.selander-ace-cose-ecdhe] describes an
augmented Diffie-Hellman key exchange to produce forward secret augmented Diffie-Hellman key exchange to produce forward secret
keying material and agree on crypto algorithms necessary for OSCOAP, keying material and agree on crypto algorithms necessary for OSCOAP,
authenticated with pre-established credentials. These pre- authenticated with pre-established credentials. These pre-
established credentials may, in turn, be provisioned using a trusted established credentials may, in turn, be provisioned using a trusted
third party such as described in the OAuth-based ACE framework third party such as described in the OAuth-based ACE framework
[I-D.ietf-ace-oauth-authz]. An OSCOAP profile of ACE is described in [I-D.ietf-ace-oauth-authz]. An OSCOAP profile of ACE is described in
[I-D.seitz-ace-oscoap-profile]. [I-D.seitz-ace-oscoap-profile].
For symmetric encryption it is required to have a unique IV for each
message, for which the sequence numbers in the COSE message field
"Partial IV" is used. The context IVs (Sender IV and Recipient IV)
SHOULD be established between sender and recipient before the message
is sent, for example using the method in
[I-D.selander-ace-cose-ecdhe], to avoid the overhead of sending it in
each message.
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). For 128 bit CCM*, use blocks) and maximum no. messages (2^56-1). Compatibility with CCM*
instead AES-CCM-16-64-128 [I-D.ietf-cose-msg]. is achieved by using the algorithm AES-CCM-16-64-128
[I-D.ietf-cose-msg].
If the recipient accepts any sequence number larger than the one Most AEAD algorithms require a unique nonce for each message, for
previously received (less than the maximum sequence number), then the which the sequence numbers in the COSE message field "Partial IV" is
problem of sequence number synchronization is avoided. With reliable used. If the recipient accepts any sequence number larger than the
transport it may be defined that only messages with sequence number one previously received, then the problem of sequence number
which are equal to previous sequence number + 1 are accepted. The synchronization is avoided. With reliable transport it may be
alternatives to sequence numbers have their issues: very constrained defined that only messages with sequence number which are equal to
devices may not be able to support accurate time, or to generate and previous sequence number + 1 are accepted. The alternatives to
store large numbers of random IVs. The requirement to change key at sequence numbers have their issues: very constrained devices may not
counter wrap is a complication, but it also forces the user of this be able to support accurate time, or to generate and store large
numbers of random nonces. The requirement to change key at counter
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 encrypted block options enable the sender to split large messages
into protected fragments such that the receiving node can verify into protected blocks such that the receiving node can verify blocks
blocks before having received the complete message. In order to before having received the complete message. In order to protect
protect from attacks replacing fragments from a different message from attacks replacing blocks from a different message with the same
with the same block number between same endpoints and same resource block number between same endpoints and same resource at roughly the
at roughly the same time, the MAC from the message containing one same time, the AEAD Tag from the message containing one block is
block is included in the external_aad of the message containing the included in the external_aad of the message containing the next
next block. block.
The unencrypted block options allow for arbitrary proxy fragmentation The unencrypted block options allow for arbitrary proxy fragmentation
operations which cannot be verified by the endpoints, but can by operations that cannot be verified by the endpoints, but can by
policy be restricted in size since the encrypted options allow for policy be restricted in size since the encrypted options allow for
secure fragmentation of very large messages. A maximum message size secure fragmentation of very large messages. A maximum message size
(above which the sending endpoint fragments the message and the (above which the sending endpoint fragments the message and the
receiving endpoint discards the message, if complying to the policy) receiving endpoint discards the message, if complying to the policy)
may be obtained as part of normal resource discovery. may be obtained as part of normal resource discovery.
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
example, the strings "YES" and "NO" even if encrypted can be
distinguished from each other as there is no padding supplied by the
current set of encryption algorithms. Some information can be
determined even from looking at boundary conditions. An example 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
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
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
three characters. 3) Use the PKCS #7 style padding scheme where m
bytes are appended each having the value of m. For example,
appending a 0 to "YES" and two 1's to "NO". This style of padding
means that all values need to be padded.
8. Privacy Considerations 8. 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.
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 9. 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. Sid Registration 9.1. CoAP Option Numbers Registry
IANA is requested to enter a new parameter entitled "sid" to the
registry "COSE Header Parameters". The parameter is defined in
Table 1.
9.2. CoAP Option Number Registration
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
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 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: cose 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 the Security Considerations section Security considerations: See Appendix C of [[this document]].
of [[this document]].
Interoperability considerations: N/A Interoperability considerations: N/A
Published specification: [[this document]] Published specification: [[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:
skipping to change at page 26, line 17 skipping to change at page 31, line 17
+-------------------+----------+----+-------------------+ +-------------------+----------+----+-------------------+
| application/oscon | - | 70 | [[this document]] | | application/oscon | - | 70 | [[this document]] |
+-------------------+----------+----+-------------------+ +-------------------+----------+----+-------------------+
10. Acknowledgments 10. Acknowledgments
The following individuals provided input to this document: Carsten The following individuals provided input to this document: Carsten
Bormann, Joakim Brorsson, Martin Gunnarsson, Klaus Hartke, Jim Bormann, Joakim Brorsson, Martin Gunnarsson, Klaus Hartke, Jim
Schaad, Marco Tiloca, and Malisa Vucinic. Schaad, Marco Tiloca, and Malisa Vucinic.
Ludwig Seitz and Goeran Selander worked on this document as part of
the CelticPlus project CyberWI, with funding from Vinnova.
11. References 11. References
11.1. Normative References 11.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-20 (work in progress), October 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>.
[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>.
skipping to change at page 27, line 5 skipping to change at page 32, line 5
[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
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 11.2. Informative References
[I-D.bormann-6lo-coap-802-15-ie] [I-D.selander-ace-cose-ecdhe]
Bormann, C., "Constrained Application Protocol (CoAP) over Selander, G., Mattsson, J., and F. Palombini, "Ephemeral
IEEE 802.15.4 Information Element for IETF", draft- Diffie-Hellman Over COSE (EDHOC)", draft-selander-ace-
bormann-6lo-coap-802-15-ie-00 (work in progress), April cose-ecdhe-04 (work in progress), October 2016.
2016.
[I-D.hartke-core-e2e-security-reqs] [I-D.hartke-core-e2e-security-reqs]
Selander, G., Palombini, F., and K. Hartke, "Requirements Selander, G., Palombini, F., and K. Hartke, "Requirements
for CoAP End-To-End Security", draft-hartke-core-e2e- for CoAP End-To-End Security", draft-hartke-core-e2e-
security-reqs-01 (work in progress), July 2016. 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]
Bormann, C., "Constrained Application Protocol (CoAP) over
IEEE 802.15.4 Information Element for IETF", draft-
bormann-6lo-coap-802-15-ie-00 (work in progress), April
2016.
[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-02 (work in progress), June 2016. authz-04 (work in progress), October 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.
[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-04 (work in progress), August draft-ietf-core-coap-tcp-tls-05 (work in progress),
2016. October 2016.
[I-D.seitz-ace-oscoap-profile]
Seitz, L., "OSCOAP profile of ACE", draft-seitz-ace-
oscoap-profile-00 (work in progress), July 2016.
[I-D.selander-ace-cose-ecdhe] [I-D.greevenbosch-appsawg-cbor-cddl]
Selander, G., Mattsson, J., and F. Palombini, "Ephemeral Vigano, C. and H. Birkholz, "CBOR data definition language
Diffie-Hellman Over COSE (EDHOC)", draft-selander-ace- (CDDL): a notational convention to express CBOR data
cose-ecdhe-02 (work in progress), July 2016. structures", draft-greevenbosch-appsawg-cbor-cddl-09 (work
in progress), September 2016.
[RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand
Key Derivation Function (HKDF)", RFC 5869, Key Derivation Function (HKDF)", RFC 5869,
DOI 10.17487/RFC5869, May 2010, DOI 10.17487/RFC5869, May 2010,
<http://www.rfc-editor.org/info/rfc5869>. <http://www.rfc-editor.org/info/rfc5869>.
[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>.
skipping to change at page 28, line 29 skipping to change at page 34, line 4
the COSE object, depending on whether the CoAP message allows payload the COSE object, depending on whether the CoAP message allows payload
or not. or not.
Length of Object-Security option = { 0, size of COSE Object } Length of Object-Security option = { 0, size of COSE Object }
A.2. Size of the COSE Object A.2. Size of the COSE Object
The size of the COSE object is the sum of the sizes of The size of the COSE object is the sum of the sizes of
o the Header parameters, o the Header parameters,
o the Cipher Text (excluding the Tag), o the Cipher Text (excluding the Tag),
o the Tag, and o the Tag, and
o data incurred by the COSE format itself (including CBOR encoding). o data incurred by the COSE format itself (including CBOR encoding).
Let's analyse the contributions one at a time: Let's analyze the contributions one at a time:
o The header parameters of the COSE object are the Context o The header parameters of the COSE object are the Context
Identifier (Cid) and the Sequence Number (Seq) (also known as the Identifier (Cid) and the Sequence Number (Seq) (also part of the
Transaction Identifier (Tid)) if the message is a request, and Seq Transaction Identifier (Tid)) if the message is a request, and Seq
only if the message is a response (see Section 5). only if the message is a response (see Section 5).
* The size of Cid depends on the number of simultaneous clients, * The size of Cid is recommended to be 64 bits, but may be
as discussed in Section 3.2 shorter, as discussed in Section 3.2.2
* The size of Seq is variable, and increases with the number of * The size of Seq is variable, and increases with the number of
messages exchanged. messages exchanged.
* As the IV is generated from the padded Sequence Number and a * As the AEAD nonce is generated from the padded Sequence Number
previously agreed upon context IV it is not required to send and a previously agreed upon context IV it is not required to
the whole IV in the message. send the whole nonce in the message.
o The Cipher Text, excluding the Tag, is the encryption of the o The Cipher Text, excluding the Tag, is the encryption of the
payload and the encrypted options Section 4, which are present in payload and the encrypted options Section 4, which are present in
the unprotected CoAP message. the unprotected CoAP message.
o The size of the Tag depends on the Algorithm. For example, for 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. 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 o The overhead from the COSE format itself depends on the sizes of
the previous fields, and is of the order of 10 bytes. the previous fields, and is of the order of 10 bytes.
A.3. Message Expansion A.3. Message Expansion
The message expansion is not the size of the COSE object. The cipher The message expansion is not the size of the COSE object. The
text in the COSE object is encrypted payload and options of the ciphertext in the COSE object is encrypted payload and options of the
unprotected CoAP message - the plaintext of which is removed from the unprotected CoAP message - the plaintext of which is removed from the
protected CoAP message. Since the size of the cipher text is the protected CoAP message. Since the size of the ciphertext is the same
same as the corresponding plaintext, there is no message expansion as the corresponding plaintext, there is no message expansion due to
due to encryption; payload and options are just represented in a encryption; payload and options are just represented in a different
different way in the protected CoAP message: way in the protected CoAP message:
o The encrypted payload is in the payload of the protected CoAP o The encrypted payload is in the payload of the protected CoAP
message message
o The encrypted options are in the Object-Security option or within o The encrypted options are in the Object-Security option or within
the payload. the payload.
Therefore the OSCOAP message expansion is due to Cid (if present), Therefore the OSCOAP message expansion is due to Cid (if present),
Seq, Tag, and COSE overhead: Seq, Tag, and COSE overhead:
Message Overhead = Cid + Seq + Tag + COSE Overhead Message Overhead = Cid + Seq + Tag + COSE Overhead
Figure 9: OSCOAP message expansion Figure 7: OSCOAP message expansion
A.4. Example A.4. Example
This section gives an example of message expansion in a request with This section gives an example of message expansion in a request with
OSCOAP. OSCOAP.
In this example we assume an extreme 4-byte Cid, based on the In this example we assume an 8-byte Cid.
assumption of an ACE deployment with billions of clients requesting
access to this particular server. (A typical Cid, will be 1-2 byte
as is discussed in Appendix A.2.)
o Cid: 0xa1534e3c o Cid: 0xa1534e3c9cecad84
In the example the sequence number is 225, requiring 1 byte to In the example the sequence number is 225, requiring 1 byte to
encode. (The size of Seq could be larger depending on how many encode. (The size of Seq could be larger depending on how many
messages that has been sent as is discussed in Appendix A.2.) messages that has been sent as is discussed in Appendix A.2.)
o Seq: 225 o Seq: 225
The example is based on AES-CCM-64-64-128. The example is based on AES-CCM-64-64-128.
o Tag is 8 bytes o Tag is 8 bytes
The COSE object is represented in Figure 10 using CBOR's diagnostic The COSE object is represented in Figure 8 using CBOR's diagnostic
notation. notation.
[ [
h'a20444a1534e3c0641e2', # protected: h'a20448a1534e3c9cecad840641e2', / protected:
{04:h'a1534e3c', {04:h'a1534e3c9cecad84',
06:h'e2'} 06:h'e2'} /
{}, # unprotected: - {}, / unprotected: - /
Tag # cipher text + 8 byte authentication tag Ciph + Tag / ciphertext + 8 byte
] authentication tag /
]
Figure 10: Example of message expansion Figure 8: Example of message expansion
Note that the encrypted CoAP options and payload are omitted since we Note that the encrypted CoAP options and payload are omitted since we
target the message expansion (see Appendix A.3). Therefore the size target the message expansion (see Appendix A.3). Therefore the size
of the COSE Cipher Text equals the size of the Tag, which is 8 bytes. of the COSE Cipher Text equals the size of the Tag, which is 8 bytes.
The COSE object encodes to a total size of 22 bytes, which is the The COSE object encodes to a total size of 26 bytes, which is the
message expansion in this example. The COSE overhead in this example message expansion in this example. The COSE overhead in this example
is 22 - (4 + 1 + 8) = 9 bytes, according to the formula in Figure 9. is 26 - (8 + 1 + 8) = 9 bytes, according to the formula in Figure 7.
Note that in this example two bytes in the COSE overhead are used to Note that in this example two bytes in the COSE overhead are used to
encode the length of Cid and the length of Seq. encode the length of Cid and the length of Seq.
Figure 11 summarizes these results. Figure 9 summarizes these results.
+---------+---------+----------+------------+ +---------+---------+---------+----------+------------+
| Tid | Tag | COSE OH | Message OH | | Cid | Seq | Tag | COSE OH | Message OH |
+---------+---------+----------+------------+ +---------+---------+---------+----------+------------+
| 5 bytes | 8 bytes | 9 bytes | 22 bytes | | 8 bytes | 1 byte | 8 bytes | 9 bytes | 22 bytes |
+---------+---------+----------+------------+ +---------+---------+---------+----------+------------+
Figure 11: Message overhead for a 5-byte Tid and 8-byte Tag. Figure 9: Message overhead for a 8-byte Cid, 1-byte Seq and 8-byte
Tag.
Appendix B. Examples Appendix B. Examples
This section gives examples of OSCOAP. The message exchanges are This section gives examples of OSCOAP. The message exchanges are
made, based on the assumption that there is a security context made, based on the assumption that there is a security context
established between client and server. For simplicity, these established between client and server. For simplicity, these
examples only indicate the content of the messages without going into examples only indicate the content of the messages without going into
detail of the COSE message format. detail of the COSE message format.
B.1. Secure Access to Sensor B.1. Secure Access to Sensor
skipping to change at page 31, line 45 skipping to change at page 37, line 34
| | | Object-Security: - | | | Object-Security: -
| | | Payload: [seq:56, {"OFF"}, <Tag>] | | | Payload: [seq:56, {"OFF"}, <Tag>]
| | | | | |
|<-----+ | Code: 2.05 (Content) |<-----+ | Code: 2.05 (Content)
| 2.05 | | Token: 0x8c | 2.05 | | Token: 0x8c
| | | Max-Age: 0 | | | Max-Age: 0
| | | Object-Security: - | | | Object-Security: -
| | | Payload: [seq:56, {"OFF"}, <Tag>] | | | Payload: [seq:56, {"OFF"}, <Tag>]
| | | | | |
Figure 12: Indication of CoAP GET protected with OSCOAP. The Figure 10: Indication of CoAP GET protected with OSCOAP. The
brackets [ ... ] indicate a COSE object. The brackets { ... } brackets [ ... ] indicate a COSE object. The brackets { ... }
indicate encrypted data. indicate encrypted data.
Since the unprotected request message (GET) has no payload, the Since the unprotected request message (GET) has no payload, the
Object-Security option carries the COSE object as its value. Since Object-Security option carries the COSE object as its value. Since
the unprotected response message (Content) has payload ("OFF"), the the unprotected response message (Content) has payload ("OFF"), the
COSE object (indicated with [ ... ]) is carried as the CoAP payload. COSE object (indicated with [ ... ]) is carried as the CoAP payload.
The COSE header of the request contains a Context Identifier The COSE header of the request contains a Context Identifier
(cid:5fdc), indicating which security context was used to protect the (cid:5fdc), indicating which security context was used to protect the
skipping to change at page 33, line 31 skipping to change at page 39, line 21
| | | | | |
|<-----+ | Code: 2.05 (Content) |<-----+ | Code: 2.05 (Content)
| 2.05 | | Token: 0x83 | 2.05 | | Token: 0x83
| | | Max-Age: 0 | | | Max-Age: 0
| | | Observe: 2 | | | Observe: 2
| | | Object-Security: - | | | Object-Security: -
| | | Payload: [seq:32c6, {Observe:2, | | | Payload: [seq:32c6, {Observe:2,
| | | Content-Format:0, "180"}, <Tag>] | | | Content-Format:0, "180"}, <Tag>]
| | | | | |
Figure 13: Indication of CoAP GET protected with OSCOAP. The Figure 11: Indication of CoAP GET protected with OSCOAP. The
brackets [ ... ] indicates COSE object. The bracket { ... } brackets [ ... ] indicates COSE object. The bracket { ... }
indicates encrypted data. indicates encrypted data.
Since the unprotected request message (GET) allows no payload, the Since the unprotected request message (GET) allows no payload, the
COSE object (indicated with [ ... ]) is carried in the Object- COSE object (indicated with [ ... ]) is carried in the Object-
Security option value. Since the unprotected response message Security option value. Since the unprotected response message
(Content) has payload, the Object-Security option is empty, and the (Content) has payload, the Object-Security option is empty, and the
COSE object is carried as 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 a Context Identifier
(cid:ca), indicating which security context was used to protect the (cid:ca), indicating which security context was used to protect the
message and a Sequence Number (seq:15b7). message and a Sequence Number (seq:15b7).
The options Observe, Content-Format and the payload are formatted as The options Observe, Content-Format and the payload are formatted as
indicated in Section 5, and encrypted in the COSE cipher text indicated in Section 5, and encrypted in the COSE ciphertext
(indicated with { ... }). (indicated with { ... }).
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 (see Section 6.1). The client verifies that the Sequence
Number has not been received before and that the response message is Number has not been received before and that the response message is
generated as a response to the subscribe request. generated as a response to the subscribe request.
Appendix C. Object Security of Content (OSCON) Appendix C. Object Security of Content (OSCON)
OSCOAP protects message exchanges end-to-end between a certain client OSCOAP protects message exchanges end-to-end between a certain client
skipping to change at page 34, line 38 skipping to change at page 40, line 27
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 9)
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]).
In the case of symmetric encryption, the same key and IV shall not be Most AEAD algorithms require a unique nonce for each message.
used twice. Sequence numbers for partial IV as specified for OSCOAP Sequence numbers for partial IV as specified for OSCOAP may be used
may be used for replay protection as described in Section 6.1. The for replay protection as described in Section 6.1. The use of time
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 C.1. Overhead OSCON
In general there are four different kinds of ciphersuites that need In general there are four different kinds of modes that need to be
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]).
The size of the COSE message for selected algorithms are detailed in The sizes of COSE messages for selected algorithms are detailed in
this section. this section.
The size of the header is shown separately from the size of the MAC/ The size of the header is shown separately from the size of the MAC/
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 9. 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 C.2. MAC Only
This example is based on HMAC-SHA256, with truncation to 8 bytes This example is based on HMAC-SHA256, with truncation to 8 bytes
skipping to change at page 36, line 18 skipping to change at page 42, line 7
{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 14 summarizes these results. Figure 12 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 14: Message overhead for a 5-byte Tid using HMAC 256/64 Figure 12: Message overhead for a 5-byte Tid using HMAC 256/64
C.3. Signature Only C.3. Signature Only
This example is based on ECDSA, with a signature of 64 bytes. This example is based on ECDSA, with a signature of 64 bytes.
Since only one signature is used, the COSE_Sign1_Tagged structure is Since only one signature is used, the COSE_Sign1_Tagged structure is
used (Section 4.2 of [I-D.ietf-cose-msg]). used (Section 4.2 of [I-D.ietf-cose-msg]).
The object in COSE encoding gives: The object in COSE encoding gives:
skipping to change at page 36, line 50 skipping to change at page 42, line 39
{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 15 summarizes these results. Figure 13 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 15: Message overhead for a 5-byte Tid using 64 byte ECDSA Figure 13: Message overhead for a 5-byte Tid using 64 byte ECDSA
signature. signature.
C.4. Authenticated Encryption with Additional Data (AEAD) C.4. Authenticated Encryption with Additional Data (AEAD)
This example is based on AES-CCM with the MAC truncated to 8 bytes. This example is based on AES-CCM with the Tag truncated to 8 bytes.
It is assumed that the IV is generated from the Sequence Number and
some previously agreed upon context IV. This means it is not
required to explicitly send the whole IV in the message.
Since the key is implicitly known by the recipient, the Since the key is implicitly known by the recipient, the
COSE_Encrypt0_Tagged structure is used (Section 5.2 of COSE_Encrypt0_Tagged structure is used (Section 5.2 of
[I-D.ietf-cose-msg]). [I-D.ietf-cose-msg]).
The object in COSE encoding gives: The object in COSE encoding gives:
993( # COSE_Encrypt0_Tagged 993( # COSE_Encrypt0_Tagged
[ [
h'a20444a1534e3c0641a3', # protected: h'a20444a1534e3c0641a3', # protected:
{04:h'a1534e3c', {04:h'a1534e3c',
06:h'a3'} 06:h'a3'}
{}, # unprotected {}, # unprotected
TAG # cipher text + 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 16 summarizes these results. Figure 14 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 16: Message overhead for a 5-byte Tid using AES_128_CCM_8. Figure 14: Message overhead for a 5-byte Tid using AES_128_CCM_8.
C.5. Symmetric Encryption with Asymmetric Signature (SEAS) C.5. Symmetric Encryption with Asymmetric Signature (SEAS)
This example is based on AES-CCM and ECDSA with 64 bytes signature. This example is based on AES-CCM and ECDSA with 64 bytes signature.
The same assumption on the security context as in Appendix C.4. COSE The same assumption on the security context as in Appendix C.4. COSE
defines the field 'counter signature w/o headers' that is used here defines the field 'counter signature w/o headers' that is used here
to sign a COSE_Encrypt0_Tagged message (see Section 3 of to sign a COSE_Encrypt0_Tagged message (see Section 3 of
[I-D.ietf-cose-msg]). [I-D.ietf-cose-msg]).
The object in COSE encoding gives: The object in COSE encoding gives:
993( # COSE_Encrypt0_Tagged 993( # COSE_Encrypt0_Tagged
[ [
h'a20444a1534e3c0641a3', # protected: h'a20444a1534e3c0641a3', # protected:
{04:h'a1534e3c', {04:h'a1534e3c',
06:h'a3'} 06:h'a3'}
{9:SIG}, # unprotected: {9:SIG}, # unprotected:
09: 64 bytes signature 09: 64 bytes signature
TAG # cipher text + 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 17 summarizes these results. Figure 15 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 17: Message overhead for a 5-byte Tid using AES-CCM Figure 15: 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 Farogatan 6
Kista SE-16480 Stockholm Kista SE-16480 Stockholm
Sweden Sweden
 End of changes. 199 change blocks. 
576 lines changed or deleted 789 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/