draft-ietf-core-object-security-03.txt   draft-ietf-core-object-security-04.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: November 4, 2017 Ericsson AB Expires: January 2, 2018 Ericsson AB
L. Seitz L. Seitz
SICS Swedish ICT SICS Swedish ICT
May 03, 2017 July 01, 2017
Object Security of CoAP (OSCOAP) Object Security of CoAP (OSCOAP)
draft-ietf-core-object-security-03 draft-ietf-core-object-security-04
Abstract Abstract
This document defines Object Security of CoAP (OSCOAP), a method for This document defines Object Security of CoAP (OSCOAP), a method for
application layer protection of the Constrained Application Protocol application layer protection of the Constrained Application Protocol
(CoAP), using the CBOR Object Signing and Encryption (COSE). OSCOAP (CoAP), using the CBOR Object Signing and Encryption (COSE). OSCOAP
provides end-to-end encryption, integrity and replay protection to provides end-to-end encryption, integrity and replay protection to
CoAP payload, options, and header fields, as well as a secure message CoAP payload, options, and header fields, as well as a secure message
binding. OSCOAP is designed for constrained nodes and networks and binding. OSCOAP is designed for constrained nodes and networks and
can be used across intermediaries and over any layer. The use of can be used across intermediaries and over any layer. The use of
skipping to change at page 1, line 41 skipping to change at page 1, line 41
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 4, 2017. This Internet-Draft will expire on January 2, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2017 IETF Trust and the persons identified as the Copyright (c) 2017 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(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 30 skipping to change at page 2, line 30
3.3. Requirements on the Security Context Parameters . . . . . 10 3.3. Requirements on the Security Context Parameters . . . . . 10
4. Protected CoAP Message Fields . . . . . . . . . . . . . . . . 11 4. Protected CoAP Message Fields . . . . . . . . . . . . . . . . 11
4.1. CoAP Payload . . . . . . . . . . . . . . . . . . . . . . 12 4.1. CoAP Payload . . . . . . . . . . . . . . . . . . . . . . 12
4.2. CoAP Header . . . . . . . . . . . . . . . . . . . . . . . 12 4.2. CoAP Header . . . . . . . . . . . . . . . . . . . . . . . 12
4.3. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 12 4.3. CoAP Options . . . . . . . . . . . . . . . . . . . . . . 12
5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 18 5. The COSE Object . . . . . . . . . . . . . . . . . . . . . . . 18
5.1. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 19 5.1. Plaintext . . . . . . . . . . . . . . . . . . . . . . . . 19
5.2. Additional Authenticated Data . . . . . . . . . . . . . . 19 5.2. Additional Authenticated Data . . . . . . . . . . . . . . 19
6. Sequence Numbers, Replay, Message Binding, and Freshness . . 20 6. Sequence Numbers, Replay, Message Binding, and Freshness . . 20
6.1. AEAD Nonce Uniqueness . . . . . . . . . . . . . . . . . . 20 6.1. AEAD Nonce Uniqueness . . . . . . . . . . . . . . . . . . 20
6.2. Replay Protection . . . . . . . . . . . . . . . . . . . . 20 6.2. Replay Protection . . . . . . . . . . . . . . . . . . . . 21
6.3. Sequence Number and Replay Window State . . . . . . . . . 21 6.3. Sequence Number and Replay Window State . . . . . . . . . 21
6.4. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 22 6.4. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 23
6.5. Delay and Mismatch Attacks . . . . . . . . . . . . . . . 23 6.5. Delay and Mismatch Attacks . . . . . . . . . . . . . . . 23
7. Processing . . . . . . . . . . . . . . . . . . . . . . . . . 23 7. Processing . . . . . . . . . . . . . . . . . . . . . . . . . 23
7.1. Protecting the Request . . . . . . . . . . . . . . . . . 23 7.1. Protecting the Request . . . . . . . . . . . . . . . . . 23
7.2. Verifying the Request . . . . . . . . . . . . . . . . . . 23 7.2. Verifying the Request . . . . . . . . . . . . . . . . . . 24
7.3. Protecting the Response . . . . . . . . . . . . . . . . . 25 7.3. Protecting the Response . . . . . . . . . . . . . . . . . 25
7.4. Verifying the Response . . . . . . . . . . . . . . . . . 25 7.4. Verifying the Response . . . . . . . . . . . . . . . . . 26
8. OSCOAP Compression . . . . . . . . . . . . . . . . . . . . . 26 8. OSCOAP Compression . . . . . . . . . . . . . . . . . . . . . 27
8.1. Encoding of the Object-Security Option . . . . . . . . . 27 8.1. Encoding of the Object-Security Option . . . . . . . . . 27
8.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . 28 8.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . 28
9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 29 9. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 29
10. Security Considerations . . . . . . . . . . . . . . . . . . . 29 10. Security Considerations . . . . . . . . . . . . . . . . . . . 30
11. Privacy Considerations . . . . . . . . . . . . . . . . . . . 31 11. Privacy Considerations . . . . . . . . . . . . . . . . . . . 32
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32
12.1. CoAP Option Numbers Registry . . . . . . . . . . . . . . 32 12.1. CoAP Option Numbers Registry . . . . . . . . . . . . . . 32
12.2. Media Type Registrations . . . . . . . . . . . . . . . . 32 12.2. Media Type Registrations . . . . . . . . . . . . . . . . 32
12.3. CoAP Content Format Registration . . . . . . . . . . . . 33 12.3. CoAP Content Format Registration . . . . . . . . . . . . 33
13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 34 13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 34
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 34 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 34
14.1. Normative References . . . . . . . . . . . . . . . . . . 34 14.1. Normative References . . . . . . . . . . . . . . . . . . 34
14.2. Informative References . . . . . . . . . . . . . . . . . 35 14.2. Informative References . . . . . . . . . . . . . . . . . 35
Appendix A. Test Vectors . . . . . . . . . . . . . . . . . . . . 36 Appendix A. Test Vectors . . . . . . . . . . . . . . . . . . . . 36
Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 36 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 36
skipping to change at page 4, line 8 skipping to change at page 4, line 8
use of OSCOAP does not affect the URI scheme and OSCOAP can therefore use of OSCOAP does not affect the URI scheme and OSCOAP can therefore
be used with any URI scheme defined for CoAP. The application be used with any URI scheme defined for CoAP. The application
decides the conditions for which OSCOAP is required. decides the conditions for which OSCOAP is required.
OSCOAP builds on CBOR Object Signing and Encryption (COSE) OSCOAP builds on CBOR Object Signing and Encryption (COSE)
[I-D.ietf-cose-msg], providing end-to-end encryption, integrity, [I-D.ietf-cose-msg], providing end-to-end encryption, integrity,
replay protection, and secure message binding. A compressed version replay protection, and secure message binding. A compressed version
of COSE is used, see Section 8. The use of OSCOAP is signaled with of COSE is used, see Section 8. The use of OSCOAP is signaled with
the CoAP option Object-Security, defined in Section 2. OSCOAP the CoAP option Object-Security, defined in Section 2. OSCOAP
provides protection of CoAP payload, certain options, and header provides protection of CoAP payload, certain options, and header
fields. The solution transforms an unprotected CoAP message into a fields. The solution transforms a CoAP message into an "OSCOAP
protected CoAP message in the following way: the unprotected CoAP message" before sending, and vice versa after receiving. The OSCOAP
message is protected by including payload (if present), certain message is a CoAP message related to the original CoAP message in the
options, and header fields in a COSE object. The message fields that following way: the original CoAP message is protected by including
have been encrypted are removed from the message whereas the Object- payload (if present), certain options, and header fields in a COSE
Security option and the compressed COSE object are added, see object. The message fields that have been encrypted are removed from
Figure 1. the message whereas the Object-Security option and the compressed
COSE object are added, see Figure 1.
Client Server Client Server
| request: | | OSCOAP request: |
| GET example.com | | GET example.com |
| [Header, Token, Options:{..., | | [Header, Token, Options:{..., |
| Object-Security:COSE object}] | | Object-Security:COSE object}] |
+---------------------------------------------->| +---------------------------------------------->|
| response: | | OSCOAP response: |
| 2.05 (Content) | | 2.05 (Content) |
| [Header, Token, Options:{..., | | [Header, Token, Options:{..., |
| Object-Security:-}, Payload:COSE object] | | Object-Security:-}, Payload:COSE object] |
|<----------------------------------------------+ |<----------------------------------------------+
| | | |
Figure 1: Sketch of OSCOAP Figure 1: Sketch of OSCOAP
OSCOAP may be used in extremely constrained settings, where CoAP over OSCOAP may be used in very constrained settings, thanks to its small
DTLS may be prohibitive e.g. due to large code size. Alternatively, message size, its restricted code and memory requirements, and is
OSCOAP can be combined with DTLS, thereby enabling end-to-end independent of underlying layer below CoAP. OSCOAP can be combined
security of e.g. CoAP payload and options, in combination with hop- with DTLS, thereby enabling end-to-end security of e.g. CoAP payload
by-hop protection of the entire CoAP message, during transport and options, in combination with hop-by-hop protection of the entire
between end-point and intermediary node. Examples of the use of CoAP message, during transport between end-point and intermediary
OSCOAP are given in Appendix B. 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), which is defined in Appendix C. object security of content (OSCON), which is defined in Appendix C.
1.1. Terminology 1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. These document are to be interpreted as described in [RFC2119]. These
skipping to change at page 5, line 42 skipping to change at page 5, line 42
SHALL contain the Object-Security option. A CoAP endpoint SHOULD NOT SHALL contain the Object-Security option. A CoAP endpoint SHOULD NOT
cache a response to a request with an Object-Security option, since cache a response to a request with an Object-Security option, since
the response is only applicable to the original client's request. the response is only applicable to the original client's request.
The Object-Security option is included in the cache key for backward The Object-Security option is included in the cache key for backward
compatibility with proxies not recognizing the Object-Security compatibility with proxies not recognizing the Object-Security
option. The effect is that messages with the Object-Security option option. The effect is that messages with the Object-Security option
will never generate cache hits. For Max-Age processing, see will never generate cache hits. For Max-Age processing, see
Section 4.3.1.1. Section 4.3.1.1.
The protection is achieved by means of a COSE object (see Section 5), The protection is achieved by means of a COSE object (see Section 5),
which is compressed and then included in the protected CoAP message. which is compressed and then included in the OSCOAP message. The
The placement of the COSE object depends on whether the method/ placement of the COSE object depends on whether the method/response
response code allows payload (see [RFC7252]): code allows payload (see [RFC7252]):
o If the method/response code allows payload, then the compressed o If the method/response code allows payload, then the compressed
COSE object Section 8 is the payload of the protected message, and COSE object Section 8 is the payload of the OSCOAP message, and
the Object-Security option has length zero. An endpoint receiving the Object-Security option has length zero. An endpoint receiving
a CoAP message with payload, that also contains a non-empty a CoAP message with payload, that also contains a non-empty
Object-Security option SHALL treat it as malformed and reject it. Object-Security option SHALL treat it as malformed and reject it.
o If the method/response code does not allow payload, then the o If the method/response code does not allow payload, then the
compressed COSE object Section 8 is the value of the Object- compressed COSE object Section 8 is the value of the Object-
Security option and the length of the Object-Security option is Security option and the length of the Object-Security option is
equal to the size of the compressed COSE object. An endpoint equal to the size of the compressed COSE object. An endpoint
receiving a CoAP message without payload, that also contains an receiving a CoAP message without payload, that also contains an
empty Object-Security option SHALL treat it as malformed and empty Object-Security option SHALL treat it as malformed and
reject it. reject it.
The size of the COSE object depends on whether the method/response The size of the COSE object depends on whether the method/response
code allows payload, if the message is a request or response, on the code allows payload, if the message is a request or response, on the
set of options that are included in the unprotected message, the AEAD set of options that are included in the original message, the AEAD
algorithm, the length of the information identifying the security algorithm, the length of the information identifying the security
context, and the length of the sequence number. context, and the length of the sequence number.
3. The Security Context 3. The Security Context
OSCOAP uses COSE with an Authenticated Encryption with Additional OSCOAP uses COSE with an Authenticated Encryption with Additional
Data (AEAD) algorithm between a CoAP client and a CoAP server. An Data (AEAD) algorithm between a CoAP client and a CoAP server. An
implementation supporting this specification MAY only implement the implementation supporting this specification MAY only implement the
client part or MAY only implement the server part. client part or MAY only implement the server part.
skipping to change at page 7, line 12 skipping to change at page 7, line 12
same, but they are partly mirrored. Retrieval and use of the same, but they are partly mirrored. Retrieval and use of the
security context are shown in Figure 3. security context are shown in Figure 3.
.------------. .------------. .------------. .------------.
| Common, | | Common, | | Common, | | Common, |
| Sender, | | Recipient,| | Sender, | | Recipient,|
| Recipient | | Sender | | Recipient | | Sender |
'------------' '------------' '------------' '------------'
Client Server Client Server
| | | |
Retrieve context for | request: | Retrieve context for | OSCOAP request: |
target resource | [Token = Token1, | target resource | [Token = Token1, |
Protect request with | kid = SID, ...] | Protect request with | kid = SID, ...] |
Sender Context +---------------------->| Retrieve context with Sender Context +---------------------->| Retrieve context with
| | RID = kid | | RID = kid
| | Verify request with | | Verify request with
| | Recipient Context | | Recipient Context
| response: | Protect response with | OSCOAP response: | Protect response with
| [Token = Token1, ...] | Sender Context | [Token = Token1, ...] | Sender Context
Retrieve context with |<----------------------+ Retrieve context with |<----------------------+
Token = Token1 | | Token = Token1 | |
Verify request with | | Verify request with | |
Recipient Context | | Recipient Context | |
Figure 3: Retrieval and use of the Security Context Figure 3: Retrieval and use of the Security Context
The Common Context contains the following parameters: The Common Context contains the following parameters:
skipping to change at page 11, line 13 skipping to change at page 11, line 13
be long enough so that the probability of collisions is negligible. be long enough so that the probability of collisions is negligible.
To enable retrieval of the right Recipient Context, the Recipient ID To enable retrieval of the right Recipient Context, the Recipient ID
SHOULD be unique in the sets of all Recipient Contexts used by an SHOULD be unique in the sets of all Recipient Contexts used by an
endpoint. endpoint.
The same Master Salt MAY be used with several Master Secrets. The same Master Salt MAY be used with several Master Secrets.
4. Protected CoAP Message Fields 4. Protected CoAP Message Fields
OSCOAP transforms an unprotected CoAP message into a protected CoAP OSCOAP transforms a CoAP message into an OSCOAP message, and vice
message, and vice versa. This section defines how the CoAP message versa. This section defines how the CoAP message fields are
fields are protected. Note that OSCOAP protects messages from the protected. Note that OSCOAP protects messages from the CoAP
CoAP Requests/Responses layer only, and not from the Messaging layer Requests/Responses layer only, and not from the Messaging layer
(Section 2 of [RFC7252]): this means that RST and ACK empty messages (Section 2 of [RFC7252]): this means that RST and ACK empty messages
are not protected, while ACK with piggybacked responses are protected are not protected, while ACK with piggybacked responses are protected
using the process defined in this document. All the messages using the process defined in this document. All the messages
mentioned in this document refer to CON, NON and non-empty ACK mentioned in this document refer to CON, NON and non-empty ACK
messages. messages.
OSCOAP protects as much of the unprotected CoAP message as possible, OSCOAP protects as much of the original CoAP message as possible,
while still allowing forward proxy operations while still allowing forward proxy operations
[I-D.hartke-core-e2e-security-reqs]. Message fields may either be [I-D.hartke-core-e2e-security-reqs]. Message fields may either be
o Class E: encrypted and integrity protected, o Class E: encrypted and integrity protected,
o Class I: integrity protected only, or o Class I: integrity protected only, or
o Class U: unprotected. o Class U: unprotected.
This section also outlines how the message fields are transferred, a This section also outlines how the message fields are transferred, a
detailed description of the processing is provided in Section 7. detailed description of the processing is provided in Section 7.
Message fields of the unprotected CoAP message are either transferred Message fields of the original CoAP message are either transferred in
in the header/options part of the protected CoAP message, or in the the header/options part of the OSCOAP message, or in the plaintext of
plaintext of the COSE object. Depending on which, the location of the COSE object. Depending on which, the location of the message
the message field in the protected CoAP message is called "inner" or field in the OSCOAP message is called "outer" or "inner":
"outer":
o Inner message field: message field included in the plaintext of o Inner message field: message field included in the plaintext of
the COSE object of the protected CoAP message (see Section 5.1). the COSE object of the OSCOAP message (see Section 5.1). The
The inner message fields are by definition encrypted and integrity inner message fields are by definition encrypted and integrity
protected by the COSE object (Class E). protected by the COSE object (Class E).
o Outer message field: message field included in the header or o Outer message field: message field included in the header or
options part of the protected CoAP message. The outer message options part of the OSCOAP message. The outer message fields are
fields are not encrypted and thus visible to an intermediary, but not encrypted and thus visible to an intermediary, but may be
may be integrity protected by including the message field values integrity protected by including the message field values in the
in the Additional Authenticated Data (AAD) of the COSE object (see Additional Authenticated Data (AAD) of the COSE object (see
Section 5.2). I.e. outer message fields may be Class I or Class Section 5.2). I.e. outer message fields may be Class I or Class
U. U.
Note that, even though the message formats are slightly different, Note that, even though the message formats are slightly different,
OSCOAP complies with CoAP over unreliable transport [RFC7252] as well OSCOAP complies with CoAP over unreliable transport [RFC7252] as well
as CoAP over reliable transport [I-D.ietf-core-coap-tcp-tls]. as CoAP over reliable transport [I-D.ietf-core-coap-tcp-tls].
4.1. CoAP Payload 4.1. CoAP Payload
The CoAP Payload SHALL be encrypted and integrity protected (Class The CoAP Payload SHALL be encrypted and integrity protected (Class
E), and thus is an inner message field. E), and thus is an inner message field.
The sending endpoint writes the payload of the unprotected CoAP The sending endpoint writes the payload of the original CoAP message
message into the plaintext of the COSE object. into the plaintext of the COSE object.
The receiving endpoint verifies and decrypts the COSE object, and The receiving endpoint verifies and decrypts the COSE object, and
recreates the payload of the unprotected CoAP message. recreates the payload of the original CoAP message.
4.2. CoAP Header 4.2. CoAP Header
Many CoAP header fields are required to be read and changed during a Many CoAP header fields are required to be read and changed during a
normal message exchange or when traversing a proxy and thus cannot in normal message exchange or when traversing a proxy and thus cannot in
general be protected between the endpoints, e.g. CoAP message layer general be protected between the endpoints, e.g. CoAP message layer
fields such as Message ID. fields such as Message ID.
The CoAP header field Code MUST be sent in plaintext to support The CoAP header field Code MUST be sent in plaintext to support
RESTful processing, but MUST be integrity protected to prevent an RESTful processing, but MUST be integrity protected (Class I) to
intermediary from changing, e.g. from GET to DELETE (Class I). The prevent an intermediary from changing, e.g. from GET to DELETE. The
CoAP version number MUST be integrity protected to prevent potential CoAP version number MUST be integrity protected to prevent potential
future version-based attacks (Class I). Note that while the version future version-based attacks (Class I). Note that while the version
number is not sent in each CoAP message over reliable transport number is not sent in each CoAP message over reliable transport
[I-D.ietf-core-coap-tcp-tls], its value is known to client and [I-D.ietf-core-coap-tcp-tls], its value is known to client and
server. server.
The other CoAP header fields SHALL neither be integrity protected nor The other CoAP header fields SHALL neither be integrity protected nor
encrypted (Class U). All CoAP header fields are thus outer message encrypted (Class U). All CoAP header fields are thus outer message
fields. fields.
The sending endpoint SHALL copy the header fields from the The sending endpoint SHALL copy the header fields from the original
unprotected CoAP message to the header of the protected CoAP message. CoAP message to the header of the OSCOAP message. The receiving
The receiving endpoint SHALL copy the header fields from the endpoint SHALL copy the header fields from the OSCOAP message to the
protected CoAP message to the header of the unprotected CoAP message. header of the decrypted CoAP message. Both sender and receiver
Both sender and receiver include the CoAP version number and header include the CoAP version number and header field Code in the AAD of
field Code in the AAD of the COSE object (see Section 5.2). the COSE object (see Section 5.2).
4.3. CoAP Options 4.3. CoAP Options
Most options are encrypted and integrity protected (Class E), and Most options are encrypted and integrity protected (Class E), and
thus inner message fields. But to allow certain proxy operations, thus inner message fields. But to allow certain proxy operations,
some options have outer values, i.e. are present as options in the some options have outer values, i.e. are present as options in the
protected CoAP message. Certain options may have both an inner value OSCOAP message. Certain options may have both an inner value and a
and a potentially different outer value, where the inner value is potentially different outer value, where the inner value is intended
intended for the destination endpoint and the outer value is intended for the destination endpoint and the outer value is intended for a
for the proxy. proxy.
A summary of how options are protected and processed is shown in A summary of how options are protected and processed is shown in
Figure 4. Options within each class are protected and processed in a Figure 4. Options within each class are protected and processed in a
similar way, but certain options which require special processing are similar way, but certain options which require special processing as
indicated by a * in Figure 4 and described in the subsections below. indicated by a * in Figure 4 and described in the processing of the
respective option.
+----+----------------+---+---+---+ +----+----------------+---+---+---+
| No.| Name | E | I | U | | No.| Name | E | I | U |
+----+----------------+---+---+---+ +----+----------------+---+---+---+
| 1 | If-Match | x | | | | 1 | If-Match | x | | |
| 3 | Uri-Host | | | x | | 3 | Uri-Host | | | x |
| 4 | ETag | x | | | | 4 | ETag | x | | |
| 5 | If-None-Match | x | | | | 5 | If-None-Match | x | | |
| 6 | Observe | | * | | | 6 | Observe | | * | |
| 7 | Uri-Port | | | x | | 7 | Uri-Port | | | x |
skipping to change at page 14, line 8 skipping to change at page 14, line 8
Specifications of new CoAP options SHOULD define how they are Specifications of new CoAP options SHOULD define how they are
processed with OSCOAP. New COAP options SHOULD be of class E and processed with OSCOAP. New COAP options SHOULD be of class E and
SHOULD NOT have outer values unless a forwarding proxy needs to read SHOULD NOT have outer values unless a forwarding proxy needs to read
that option value. If a certain option has both inner and outer that option value. If a certain option has both inner and outer
values, the two values SHOULD NOT be the same. values, the two values SHOULD NOT be the same.
4.3.1. Class E Options 4.3.1. Class E Options
For options in class E (see Figure 4) the option value in the For options in class E (see Figure 4) the option value in the
unprotected CoAP message, if present, SHALL be encrypted and original CoAP message, if present, SHALL be encrypted and integrity
integrity protected between the endpoints. Hence the actions protected between the endpoints. Hence the actions resulting from
resulting from the use of such options is analogous to communicating the use of such options is analogous to communicating in a protected
in a protected manner directly with the endpoint. For example, a manner directly with the endpoint. For example, a client using an
client using an If-Match option will not be served by a proxy. If-Match option will not be served by a proxy.
The sending endpoint SHALL write the class E option from the The sending endpoint SHALL write the class E option from the original
unprotected CoAP message into the plaintext of the COSE object. CoAP message into the plaintext of the COSE object.
Except for the special options described in the subsections, the Except for the special options (* in Figure 4), the sending endpoint
sending endpoint SHALL NOT use the outer options of class E. SHALL NOT use the outer options of class E. However, note that an
However, note that an intermediary may, legitimately or not, add, intermediary may, legitimately or not, add, change or remove the
change or remove the value of an outer option. value of an outer option.
Except for the Block options Section 4.3.1.2, the receiving endpoint Except for the special options, the receiving endpoint SHALL discard
SHALL discard any outer options of class E from the protected CoAP any outer options of class E from the OSCOAP message and SHALL write
message and SHALL write the Class E options present in the plaintext the Class E options present in the plaintext of the COSE object into
of the COSE object into the unprotected CoAP message. the decrypted CoAP message.
4.3.1.1. Max-Age 4.3.1.1. Max-Age
An inner Max-Age option, like other class E options, is used as An inner Max-Age option, like other class E options, is used as
defined in [RFC7252] taking into account that it is not accessible to defined in [RFC7252] taking into account that it is not accessible to
proxies. proxies.
Since OSCOAP binds CoAP responses to requests, a cached response Since OSCOAP binds CoAP responses to requests, a cached response
would not be possible to use for any other request. To avoid would not be possible to use for any other request. To avoid
unnecessary caching, a server MAY add an outer Max-Age option with unnecessary caching, a server MAY add an outer Max-Age option with
value zero to protected CoAP responses (see Section 5.6.1 of value zero to OSCOAP responses (see Section 5.6.1 of [RFC7252]). The
[RFC7252]). The outer Max-Age option is not integrity protected. outer Max-Age option is not integrity protected.
4.3.1.2. The Block Options 4.3.1.2. The Block Options
Blockwise [RFC7959] is an optional feature. An implementation MAY Blockwise [RFC7959] is an optional feature. An implementation MAY
comply with [RFC7252] and the Object-Security option without comply with [RFC7252] and the Object-Security option without
implementing [RFC7959]. implementing [RFC7959].
The Block options (Block1, Block2, Size1 and Size2) MAY be either The Block options (Block1, Block2, Size1 and Size2) MAY be either
only inner options, only outer options or both inner and outer only inner options, only outer options or both inner and outer
options. The inner and outer options are processed independently. options. The inner and outer options are processed independently.
The inner block options are used for endpoint-to-endpoint secure 4.3.1.2.1. Inner Block Options
The inner Block options are used for endpoint-to-endpoint secure
fragmentation of payload into blocks and protection of information fragmentation of payload into blocks and protection of information
about the fragmentation (block number, block size, last block). In about the fragmentation (block number, block size, last block). In
this case, the CoAP client fragments the CoAP message as defined in this case, the sending CoAP endpoint fragments the CoAP message as
defined in [RFC7959] before the message is processed by OSCOAP. The
receiving CoAP endpoint first processes the OSCOAP message before
processing blockwise as defined in [RFC7959].
[RFC7959] before the message is processed by OSCOAP. The CoAP server Applications using OSCOAP with inner Block options MUST specify a
first processes the OSCOAP message before processing blockwise as security policy defining a maximum unfragmented message size for
defined in [RFC7959]. inner Block options such that messages exceeding this size SHALL be
fragmented by the sending endpoint.
There SHALL be a security policy defining a maximum unfragmented For blockwise request operations (using Block1) the client MUST use
message size for inner Block options such that messages exceeding and process the Request-Tag as defined in Section 3 of
this size SHALL be fragmented by the sending endpoint. [I-D.amsuess-core-repeat-request-tag]. In particular, the rules in
section 3.3.1 of [I-D.amsuess-core-repeat-request-tag] MUST be
followed, which guarantee that a specific request body is assembled
only from the corresponding request blocks.
Additionally, a proxy may arbitrarily do block fragmentation on any For blockwise response operations (using Block2) the server MUST use
CoAP message, in particular an OSCOAP message, as defined in and process the ETag as defined in Section 4 of
[RFC7959] and thereby add outer Block options to a block and send on [I-D.amsuess-core-repeat-request-tag].
the next hop. The outer block options are thus neither encrypted nor
integrity protected.
An endpoint receiving a message with an outer Block option SHALL 4.3.1.2.2. Outer Block Options
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.
If the unprotected CoAP message in turn contains Block options, the A CoAP proxy may do block fragmentation on any CoAP message
receiving endpoint processes this according to [RFC7959]. (including OSCOAP messages) as defined in [RFC7959], and thereby
decompose it into multiple blocks using outer Block options. The
outer block options are thus neither encrypted nor integrity
protected.
TODO: Update processing to support multiple concurrently proceeding To allow multiple concurrent request operations to the same server
requests (not only same resource), a CoAP proxy should use and process the
Request-Tag as specified in section 3.3.2 of
[I-D.amsuess-core-repeat-request-tag]; an OSCOAP server that supports
outer Block options MUST support the Request-Tag option.
An endpoint receiving an OSCOAP message with an outer Block option
SHALL first process this option according to [RFC7959], until all
blocks of the OSCOAP message have been received, or the cumulated
message size of the blocks exceeds the maximum unfragmented message
size. In the latter case the message SHALL be discarded. In the
former case, the processing of the OSCOAP message continues as
defined in this document.
4.3.2. Class I Options 4.3.2. Class I Options
A Class I option is an outer option and hence visible in the options A Class I option is an outer option and hence visible in the options
part of the protected CoAP message. Except for special options part of the OSCOAP message. Except for special options described in
described in the subsections, for options in Class I (see Figure 4) the subsections, for options in Class I (see Figure 4) the option
the option value SHALL be integrity protected between the endpoints, value SHALL be integrity protected between the endpoints, see
see (Section 5.2). Unless otherwise specified, the sending endpoint (Section 5.2). Unless otherwise specified, the sending endpoint
SHALL encode the Class I options in the protected CoAP message as SHALL encode the Class I options in the OSCOAP message as described
described in Section 4.3.4. in Section 4.3.4.
4.3.2.1. Observe 4.3.2.1. Observe
Observe [RFC7641] is an optional feature. An implementation MAY Observe [RFC7641] is an optional feature. An implementation MAY
support [RFC7252] and the Object-Security option without supporting support [RFC7252] and the Object-Security option without supporting
[RFC7641]. The Observe option as used here targets the requirements [RFC7641]. The Observe option as used here targets the requirements
on forwarding of [I-D.hartke-core-e2e-security-reqs] on forwarding of [I-D.hartke-core-e2e-security-reqs]
(Section 2.2.1.2). (Section 2.2.1.2).
In order for a proxy to support forwarding of Observe messages, there In order for a proxy to support forwarding of Observe messages, there
must be an Observe option present in options part of the protected must be an Observe option present in options part of the OSCOAP
CoAP message ([RFC7641]), so Observe must have an outer value: message ([RFC7641]), so Observe must have an outer value:
o The Observe option of the unprotected CoAP request SHALL be o The Observe option of the original CoAP request SHALL be encoded
encoded in the protected CoAP request as described in in the OSCOAP request as described in Section 4.3.4.
Section 4.3.4.
To secure the order of the notifications, responses with the Observe To secure the order of the notifications, responses with the Observe
option SHALL be integrity protected in the following way: option SHALL be integrity protected in the following way:
o The Observe option SHALL be included in the external_aad of the o The Observe option SHALL be included in the external_aad of the
response (see Section 5.2), with value set to the 3 least response (see Section 5.2), with value set to the 3 least
significant bytes of the Sequence Number of the response. significant bytes of the Sequence Number of the response.
The Observe option in the CoAP request SHALL NOT be integrity The Observe option in the CoAP request SHALL NOT be integrity
protected, since it may be legitimately removed by a proxy. protected, since it may be legitimately removed by a proxy.
skipping to change at page 16, line 34 skipping to change at page 16, line 51
the server can still verify the request (as a non-Observe request), the server can still verify the request (as a non-Observe request),
and produce a non-Observe response. If the OSCOAP client receives a and produce a non-Observe response. If the OSCOAP client receives a
response to an Observe request without an outer Observe value, then response to an Observe request without an outer Observe value, then
it MUST verify the response as a non-Observe response, i.e. not it MUST verify the response as a non-Observe response, i.e. not
include the Sequence Number of the response in the external_aad. include the Sequence Number of the response in the external_aad.
4.3.3. Class U Options 4.3.3. Class U Options
Options in Class U have outer values and are used to support forward Options in Class U have outer values and are used to support forward
proxy operations. Unless otherwise specified, the sending endpoint proxy operations. Unless otherwise specified, the sending endpoint
SHALL encode the Class U options in the options part of the protected SHALL encode the Class U options in the options part of the OSCOAP
CoAP message as described in Section 4.3.4. message as described in Section 4.3.4.
4.3.3.1. Uri-Host, Uri-Port, and Proxy-Scheme 4.3.3.1. Uri-Host, Uri-Port, and Proxy-Scheme
The sending endpoint SHALL copy Uri-Host, Uri-Port, and Proxy-Scheme The sending endpoint SHALL copy Uri-Host, Uri-Port, and Proxy-Scheme
from the unprotected CoAP message to the options part of the from the original CoAP message to the options part of the OSCOAP
protected CoAP message. When Uri-Host, Uri-Port, or Proxy-Scheme message. When Uri-Host, Uri-Port, or Proxy-Scheme options are
options are present, Proxy-Uri is not used [RFC7252]. present, Proxy-Uri is not used [RFC7252].
4.3.3.2. Proxy-Uri 4.3.3.2. Proxy-Uri
Proxy-Uri, when present, is split by OSCOAP into class U options and Proxy-Uri, when present, is split by OSCOAP into class U options and
class E options, which are processed accordingly. When Proxy-Uri is class E options, which are processed accordingly. When Proxy-Uri is
used in the unprotected CoAP message, Uri-* are not present used in the original CoAP message, Uri-* are not present [RFC7252].
[RFC7252].
The sending endpoint SHALL first decompose the Proxy-Uri value of the The sending endpoint SHALL first decompose the Proxy-Uri value of the
unprotected CoAP message into the Proxy-Scheme, Uri-Host, Uri-Port, original CoAP message into the Proxy-Scheme, Uri-Host, Uri-Port, Uri-
Uri-Path and Uri-Query options (if present) according to section 6.4 Path and Uri-Query options (if present) according to section 6.4 of
of [RFC7252]. [RFC7252].
Uri-Path and Uri-Query are class E options and MUST be protected and Uri-Path and Uri-Query are class E options and MUST be protected and
processed as if obtained from the unprotected CoAP message, see processed as if obtained from the original CoAP message, see
Section 4.3.1. Section 4.3.1.
The value of the Proxy-Uri option of the protected CoAP message MUST The value of the Proxy-Uri option of the OSCOAP message MUST be
be replaced with Proxy-Scheme, Uri-Host and Uri-Port options (if replaced with Proxy-Scheme, Uri-Host and Uri-Port options (if
present) composed according to section 6.5 of [RFC7252] and MUST be present) composed according to section 6.5 of [RFC7252] and MUST be
processed as a class U option, see Section 4.3.3. processed as a class U option, see Section 4.3.3.
An example of how Proxy-Uri is processed is given here. Assume that An example of how Proxy-Uri is processed is given here. Assume that
the unprotected CoAP message contains: the original CoAP message contains:
o Proxy-Uri = "coap://example.com/resource?q=1" o Proxy-Uri = "coap://example.com/resource?q=1"
During OSCOAP processing, Proxy-Uri is split into: During OSCOAP processing, Proxy-Uri is split into:
o Proxy-Scheme = "coap" o Proxy-Scheme = "coap"
o Uri-Host = "example.com" o Uri-Host = "example.com"
o Uri-Port = "5863" o Uri-Port = "5863"
o Uri-Path = "resource" o Uri-Path = "resource"
o Uri-Query = "q=1" o Uri-Query = "q=1"
Uri-Path and Uri-Query follow the processing defined in Uri-Path and Uri-Query follow the processing defined in
Section 4.3.1, and are thus encrypted and transported in the COSE Section 4.3.1, and are thus encrypted and transported in the COSE
object. The remaining options are composed into the Proxy-Uri object. The remaining options are composed into the Proxy-Uri
included in the options part of the protected CoAP message, which has included in the options part of the OSCOAP message, which has value:
value:
o Proxy-Uri = "coap://example.com" o Proxy-Uri = "coap://example.com"
4.3.4. Outer Options in the Protected CoAP Message 4.3.4. Outer Options in the OSCOAP Message
All options with outer values present in the protected CoAP message, All options with outer values present in the OSCOAP message,
including the Object-Security option, SHALL be encoded as described including the Object-Security option, SHALL be encoded as described
in Section 3.1 of [RFC7252], where the delta is the difference to the in Section 3.1 of [RFC7252], where the delta is the difference to the
previously included outer option value. previously included outer option value.
5. The COSE Object 5. The COSE Object
This section defines how to use COSE [I-D.ietf-cose-msg] to wrap and This section defines how to use COSE [I-D.ietf-cose-msg] to wrap and
protect data in the unprotected CoAP message. OSCOAP uses the protect data in the original CoAP message. OSCOAP uses the untagged
untagged COSE_Encrypt0 structure with an Authenticated Encryption COSE_Encrypt0 structure with an Authenticated Encryption with
with Additional Data (AEAD) algorithm. The key lengths, IV lengths, Additional Data (AEAD) algorithm. The key lengths, IV lengths, and
and maximum sequence number are algorithm dependent. maximum sequence number are algorithm dependent.
The AEAD algorithm AES-CCM-64-64-128 defined in Section 10.2 of The AEAD algorithm AES-CCM-64-64-128 defined in Section 10.2 of
[I-D.ietf-cose-msg] is mandatory to implement. For AES-CCM-64-64-128 [I-D.ietf-cose-msg] is mandatory to implement. For AES-CCM-64-64-128
the length of Sender Key and Recipient Key is 128 bits, the length of the length of Sender Key and Recipient Key is 128 bits, the length of
nonce, Sender IV, and Recipient IV is 7 bytes. The maximum Sequence nonce, Sender IV, and Recipient IV is 7 bytes. The maximum Sequence
Number is specified in Section 10. Number is specified in Section 10.
The nonce is constructed as described in Section 3.1 of The nonce is constructed as described in Section 3.1 of
[I-D.ietf-cose-msg], i.e. by padding the partial IV (Sequence Number [I-D.ietf-cose-msg], i.e. by padding the partial IV (Sequence Number
in network byte order) with zeroes and XORing it with the Context IV in network byte order) with zeroes and XORing it with the Context IV
skipping to change at page 19, line 17 skipping to change at page 19, line 24
Section 5.2) following Section 5.2 of [I-D.ietf-cose-msg]. Section 5.2) following Section 5.2 of [I-D.ietf-cose-msg].
The encryption process is described in Section 5.3 of The encryption process is described in Section 5.3 of
[I-D.ietf-cose-msg]. [I-D.ietf-cose-msg].
5.1. Plaintext 5.1. Plaintext
The Plaintext is formatted as a CoAP message without Header (see The Plaintext is formatted as a CoAP message without Header (see
Figure 5) consisting of: Figure 5) consisting of:
o all Class E option values Section 4.3.1 present in the unprotected o all Class E option values Section 4.3.1 present in the original
CoAP message (see Section 4.3). The options are encoded as CoAP message (see Section 4.3). The options are encoded as
described in Section 3.1 of [RFC7252], where the delta is the described in Section 3.1 of [RFC7252], where the delta is the
difference to the previously included Class E option; and difference to the previously included Class E option; and
o the Payload of unprotected CoAP message, if present, and in that o the Payload of original CoAP message, if present, and in that case
case prefixed by the one-byte Payload Marker (0xFF). prefixed by the one-byte Payload Marker (0xFF).
0 1 2 3 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Class E options (if any) ... | Class E options (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 1 1 1 1 1 1 1| Payload (if any) ... |1 1 1 1 1 1 1 1| Payload (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(only if there (only if there
is payload) is payload)
skipping to change at page 20, line 8 skipping to change at page 20, line 19
alg : int, alg : int,
request_kid : bstr, request_kid : bstr,
request_seq : bstr request_seq : bstr
] ]
where: where:
o ver: contains the CoAP version number, as defined in Section 3 of o ver: contains the CoAP version number, as defined in Section 3 of
[RFC7252]. [RFC7252].
o code: contains is the CoAP Code of the unprotected CoAP message, o code: contains is the CoAP Code of the original CoAP message, as
as defined in Section 3 of [RFC7252]. defined in Section 3 of [RFC7252].
o options: contains the Class I options Section 4.3.2 present in the o options: contains the Class I options Section 4.3.2 present in the
unprotected CoAP message encoded as described in Section 3.1 of original CoAP message encoded as described in Section 3.1 of
[RFC7252], where the delta is the difference to the previously [RFC7252], where the delta is the difference to the previously
included class I option included class I option
o alg: contains the Algorithm from the security context used for the o alg: contains the Algorithm from the security context used for the
exchange (see Section 3.1). exchange (see Section 3.1).
o request_kid: contains the value of the 'kid' in the COSE object of o request_kid: contains the value of the 'kid' in the COSE object of
the request (see Section 5). the request (see Section 5).
o request_seq: contains the value of the 'Partial IV' in the COSE o request_seq: contains the value of the 'Partial IV' in the COSE
skipping to change at page 22, line 8 skipping to change at page 22, line 20
current sequence number and K > 1. This is a trade-off between current sequence number and K > 1. This is a trade-off between
the number of storage operations and efficient use of sequence the number of storage operations and efficient use of sequence
numbers. numbers.
To prevent accepting replay of previously received messages, the node To prevent accepting replay of previously received messages, the node
MAY perform the following procedure: MAY perform the following procedure:
o After boot, before verifying a message using a security context o After boot, before verifying a message using a security context
stored before boot, the server synchronizes the replay window so stored before boot, the server synchronizes the replay window so
that no old messages are being accepted. The server uses the that no old messages are being accepted. The server uses the
Repeat option [I-D.mattsson-core-coap-actuators] for synchronizing Repeat option [I-D.amsuess-core-repeat-request-tag] for
the replay window: For each stored security context, the first synchronizing the replay window: For each stored security context,
time after boot the server receives an OSCOAP request, it the first time after boot the server receives an OSCOAP request,
generates a pseudo-random nonce and responds with the Repeat it generates a pseudo-random nonce and responds with the Repeat
option set to the nonce as described in option set to the nonce as described in
[I-D.mattsson-core-coap-actuators]. If the server receives a [I-D.amsuess-core-repeat-request-tag]. If the server receives a
repeated OSCOAP request containing the Repeat option and the same repeated OSCOAP request containing the Repeat option and the same
nonce, and if the server can verify the request, then the sequence nonce, and if the server can verify the request, then the sequence
number obtained in the repeated message is set as the lower limit number obtained in the repeated message is set as the lower limit
of the replay window. of the replay window.
6.3.2. The Observe Case 6.3.2. The Observe Case
To prevent reuse of Sequence Number in case of Observe, the node MAY To prevent reuse of Sequence Number in case of Observe, the node MAY
perform the following procedure during normal operations: perform the following procedure during normal operations:
skipping to change at page 23, line 23 skipping to change at page 23, line 36
compromised proxies, OSCOAP binds responses to the request by compromised proxies, OSCOAP binds responses to the request by
including the request's ID (Sender ID or Recipient ID) and sequence including the request's ID (Sender ID or Recipient ID) and sequence
number in the AAD of the response. The server therefore needs to number in the AAD of the response. The server therefore needs to
store the request's ID (Sender ID or Recipient ID) and sequence store the request's ID (Sender ID or Recipient ID) and sequence
number until all responses have been sent. number until all responses have been sent.
7. Processing 7. Processing
7.1. Protecting the Request 7.1. Protecting the Request
Given an unprotected request, the client SHALL perform the following Given a CoAP request, the client SHALL perform the following steps to
steps to create a protected request: create an OSCOAP request:
1. Retrieve the Sender Context associated with the target resource. 1. Retrieve the Sender Context associated with the target resource.
2. Compose the Additional Authenticated Data, as described in 2. Compose the Additional Authenticated Data, as described in
Section 5. Section 5.
3. Compose the AEAD nonce by XORing the Context IV (Sender IV) with 3. Compose the AEAD nonce by XORing the Context IV (Sender IV) with
the partial IV (Sequence Number in network byte order). the partial IV (Sequence Number in network byte order).
4. Encrypt the COSE object using the Sender Key. Compress the COSE 4. Encrypt the COSE object using the Sender Key. Compress the COSE
Object as specified in Section 8. Object as specified in Section 8.
5. Format the protected CoAP message according to Section 4. The 5. Format the OSCOAP message according to Section 4. The Object-
Object-Security option is added, see Section 4.3.4. Security option is added, see Section 4.3.4.
6. Store the association Token - Security Context. The client SHALL 6. Store the association Token - Security Context. The client SHALL
be able to find the Recipient Context from the Token in the be able to find the Recipient Context from the Token in the
response. response.
7. Increment the Sequence Number by one. 7. Increment the Sequence Number by one.
7.2. Verifying the Request 7.2. Verifying the Request
A server receiving a request containing the Object-Security option A server receiving a request containing the Object-Security option
skipping to change at page 24, line 46 skipping to change at page 25, line 13
4. Decrypt the COSE object using the Recipient Key. 4. Decrypt the COSE object using the Recipient Key.
* If decryption fails, the server MUST stop processing the * If decryption fails, the server MUST stop processing the
request and, if the request is a CON message, the server MUST request and, if the request is a CON message, the server MUST
respond with a 4.00 Bad Request error message. The diagnostic respond with a 4.00 Bad Request error message. The diagnostic
payload MAY contain the "Decryption failed" string. payload MAY contain the "Decryption failed" string.
* If decryption succeeds, update the Recipient Replay Window, as * If decryption succeeds, update the Recipient Replay Window, as
described in Section 6. described in Section 6.
5. Add decrypted options and payload to the unprotected request, 5. Add decrypted options and payload to the decrypted request,
processing the E options as described in (Section 4). The processing the E options as described in (Section 4). The
Object-Security option is removed. Object-Security option is removed.
6. The unprotected CoAP request is processed according to [RFC7252] 6. The decrypted CoAP request is processed according to [RFC7252]
7.3. Protecting the Response 7.3. Protecting the Response
Given an unprotected response, the server SHALL perform the following Given a CoAP response, the server SHALL perform the following steps
steps to create a protected response: to create an OSCOAP response:
1. Retrieve the Sender Context in the Security Context used to 1. Retrieve the Sender Context in the Security Context used to
verify the request. verify the request.
2. Compose the Additional Authenticated Data, as described in 2. Compose the Additional Authenticated Data, as described in
Section 5. Section 5.
3. Compose the AEAD nonce 3. Compose the AEAD nonce
* If Observe is not used, compose the AEAD nonce by XORing the * If Observe is not used, compose the AEAD nonce by XORing the
skipping to change at page 25, line 30 skipping to change at page 25, line 44
first byte flipped) with the padded Partial IV parameter from first byte flipped) with the padded Partial IV parameter from
the request. the request.
* If Observe is used, compose the AEAD nonce by XORing the * If Observe is used, compose the AEAD nonce by XORing the
Context IV (Sender IV) with the Partial IV of the response Context IV (Sender IV) with the Partial IV of the response
(Sequence Number in network byte order). (Sequence Number in network byte order).
4. Encrypt the COSE object using the Sender Key. Compress the COSE 4. Encrypt the COSE object using the Sender Key. Compress the COSE
Object as specified in Section 8. Object as specified in Section 8.
5. Format the protected CoAP message according to Section 4. The 5. Format the OSCOAP message according to Section 4. The Object-
Object-Security option is added, see Section 4.3.4. Security option is added, see Section 4.3.4.
6. If Observe is used, increment the Sequence Number by one. 6. If Observe is used, increment the Sequence Number by one.
7.4. Verifying the Response 7.4. Verifying the Response
A client receiving a response containing the Object-Security option A client receiving a response containing the Object-Security option
SHALL perform the following steps: SHALL perform the following steps:
1. Process outer Block options according to [RFC7959], until all 1. Process outer Block options according to [RFC7959], until all
blocks of the protected CoAP message have been received, see blocks of the OSCOAP message have been received, see
Section 4.3.1.2. Section 4.3.1.2.
2. Retrieve the Recipient Context associated with the Token. 2. Retrieve the Recipient Context associated with the Token.
Decompress the COSE Object (Section 8). If the response is a CON Decompress the COSE Object (Section 8). If the response is a CON
message and either the decompression or the COSE message fails to message and either the decompression or the COSE message fails to
decode, then the client SHALL send an empty ACK back and stop decode, then the client SHALL send an empty ACK back and stop
processing the response. If the response is a NON message and processing the response. If the response is a NON message and
any of the previous conditions appear, then the client SHALL any of the previous conditions appear, then the client SHALL
simply stop processing the response. simply stop processing the response.
skipping to change at page 26, line 25 skipping to change at page 26, line 42
the most significant bit in the first byte flipped) with the the most significant bit in the first byte flipped) with the
padded Partial IV parameter from the request. padded Partial IV parameter from the request.
* If the Observe option is present in the response, compose the * If the Observe option is present in the response, compose the
AEAD nonce by XORing the Context IV (Recipient IV) with the AEAD nonce by XORing the Context IV (Recipient IV) with the
padded Partial IV parameter from the response. padded Partial IV parameter from the response.
4. Decrypt the COSE object using the Recipient Key. 4. Decrypt the COSE object using the Recipient Key.
* If decryption fails, the client MUST stop processing the * If decryption fails, the client MUST stop processing the
response and, if the request is a CON message, the client MUST response and, if the response is a CON message, the client
respond with an empty ACK back. MUST respond with an empty ACK back.
* If decryption succeeds and Observe is used, update the * If decryption succeeds and Observe is used, update the
Recipient Replay Window, as described in Section 6. Recipient Replay Window, as described in Section 6.
5. Add decrypted options or payload to the unprotected response 5. Add decrypted options or payload to the decrypted response
overwriting any outer E options (see Section 4). The Object- overwriting any outer E options (see Section 4). The Object-
Security option is removed. Security option is removed.
* If Observe is used, replace the Observe value with the 3 least * If Observe is used, replace the Observe value with the 3 least
significant bytes in the sequence number. significant bytes in the sequence number.
6. The unprotected CoAP response is processed according to [RFC7252] 6. The decrypted CoAP response is processed according to [RFC7252]
8. OSCOAP Compression 8. OSCOAP Compression
The Concise Binary Object Representation (CBOR) [RFC7049] combines The Concise Binary Object Representation (CBOR) [RFC7049] combines
very small message sizes with extensibility. The CBOR Object Signing very small message sizes with extensibility. The CBOR Object Signing
and Encryption (COSE) [I-D.ietf-cose-msg] uses CBOR to create compact and Encryption (COSE) [I-D.ietf-cose-msg] uses CBOR to create compact
encoding of signed and encrypted data. COSE is however constructed encoding of signed and encrypted data. COSE is however constructed
to support a large number of different stateless use cases, and is to support a large number of different stateless use cases, and is
not fully optimized for use as a stateful security protocol, leading not fully optimized for use as a stateful security protocol, leading
to a larger than necessary message expansion. In this section we to a larger than necessary message expansion. In this section we
skipping to change at page 31, line 9 skipping to change at page 31, line 27
The maximum sequence number to guarantee nonce uniqueness The maximum sequence number to guarantee nonce uniqueness
(Section 6.1) is algorithm dependent. Using AES_CCM, with the (Section 6.1) is algorithm dependent. Using AES_CCM, with the
maximum sequence number SHALL be 2^(min(nonce length in bits, 56) - maximum sequence number SHALL be 2^(min(nonce length in bits, 56) -
1) - 1. The "-1" in the exponent stems from the same partial IV and 1) - 1. The "-1" in the exponent stems from the same partial IV and
flipped bit of IV (Section 5) is used in request and response. The flipped bit of IV (Section 5) is used in request and response. The
compression algorithm (Section 8) assumes that the partial IV is 56 compression algorithm (Section 8) assumes that the partial IV is 56
bits or less (which is the reason for min(,) in the exponent). bits or less (which is the reason for min(,) in the exponent).
The inner block options enable the sender to split large messages The inner block options enable the sender to split large messages
into protected blocks such that the receiving node can verify blocks into OSCOAP-protected blocks such that the receiving node can verify
before having received the complete message. The outer block options blocks before having received the complete message. The outer block
allow for arbitrary proxy fragmentation operations that cannot be options allow for arbitrary proxy fragmentation operations that
verified by the endpoints, but can by policy be restricted in size cannot be verified by the endpoints, but can by policy be restricted
since the encrypted options allow for secure fragmentation of very in size since the encrypted options allow for secure fragmentation of
large messages. A maximum message size (above which the sending very large messages. A maximum message size (above which the sending
endpoint fragments the message and the receiving endpoint discards endpoint fragments the message and the receiving endpoint discards
the message, if complying to the policy) may be obtained as part of the message, if complying to the policy) may be obtained as part of
normal resource discovery. normal resource discovery.
Applications need to use a padding scheme if the content of a message Applications need to use a padding scheme if the content of a message
can be determined solely from the length of the payload. As an can be determined solely from the length of the payload. As an
example, the strings "YES" and "NO" even if encrypted can be example, the strings "YES" and "NO" even if encrypted can be
distinguished from each other as there is no padding supplied by the distinguished from each other as there is no padding supplied by the
current set of encryption algorithms. Some information can be current set of encryption algorithms. Some information can be
determined even from looking at boundary conditions. An example of determined even from looking at boundary conditions. An example of
skipping to change at page 32, line 5 skipping to change at page 32, line 21
communication, which may have a direct impact on the personal sphere. communication, which may have a direct impact on the personal sphere.
The unprotected options (Figure 4) may reveal privacy sensitive The unprotected options (Figure 4) may reveal privacy sensitive
information. In particular Uri-Host SHOULD NOT contain privacy information. In particular Uri-Host SHOULD NOT contain privacy
sensitive information. sensitive information.
CoAP headers sent in plaintext allow for example matching of CON and CoAP headers sent in plaintext allow for example matching of CON and
ACK (CoAP Message Identifier), matching of request and responses ACK (CoAP Message Identifier), matching of request and responses
(Token) and traffic analysis. (Token) and traffic analysis.
Using the mechanisms described in Section 6.3 reveals when a device
goes through a reboot. This can be mitigated by the device storing
the precise state of sender sequence number and recipient replay
window on a clean shutdown.
12. IANA Considerations 12. IANA Considerations
Note to RFC Editor: Please replace all occurrences of "[[this Note to RFC Editor: Please replace all occurrences of "[[this
document]]" with the RFC number of this specification. document]]" with the RFC number of this specification.
12.1. CoAP Option Numbers Registry 12.1. CoAP Option Numbers Registry
The Object-Security option is added to the CoAP Option Numbers The Object-Security option is added to the CoAP Option Numbers
registry: registry:
skipping to change at page 33, line 47 skipping to change at page 33, line 47
Restrictions on usage: N/A Restrictions on usage: N/A
Author: Goeran Selander, goran.selander@ericsson.com Author: Goeran Selander, goran.selander@ericsson.com
12.3. CoAP Content Format Registration 12.3. CoAP Content Format Registration
The "application/oscon" content format is added to the CoAP Content The "application/oscon" content format is added to the CoAP Content
Format registry: Format registry:
+-------------------+----------+----+-------------------+ +-------------------+----------+-----+-------------------+
| Media type | Encoding | ID | Reference | | Media type | Encoding | ID | Reference |
+-------------------+----------+----+-------------------+ +-------------------+----------+-----+-------------------+
| application/oscon | - | 70 | [[this document]] | | application/oscon | - | TBD | [[this document]] |
+-------------------+----------+----+-------------------+ +-------------------+----------+-----+-------------------+
13. Acknowledgments 13. Acknowledgments
The following individuals provided input to this document: Christian The following individuals provided input to this document: Christian
Amsuess, Carsten Bormann, Joakim Brorsson, Martin Gunnarsson, Klaus Amsuess, Tobias Andersson, Carsten Bormann, Joakim Brorsson, Thomas
Hartke, Jim Schaad, Marco Tiloca, and Malisa Vu&#269;ini&#263;. Fossati, Martin Gunnarsson, Klaus Hartke, Jim Schaad, Marco Tiloca,
and Malisa Vu&#269;ini&#263;.
Ludwig Seitz and Goeran Selander worked on this document as part of Ludwig Seitz and Goeran Selander worked on this document as part of
the CelticPlus project CyberWI, with funding from Vinnova. the CelticPlus project CyberWI, with funding from Vinnova.
14. References 14. References
14.1. Normative References 14.1. Normative References
[I-D.amsuess-core-repeat-request-tag]
Amsuess, C., Mattsson, J., and G. Selander, "Repeat And
Request-Tag", draft-amsuess-core-repeat-request-tag-00
(work in progress), July 2017.
[I-D.ietf-cose-msg] [I-D.ietf-cose-msg]
Schaad, J., "CBOR Object Signing and Encryption (COSE)", Schaad, J., "CBOR Object Signing and Encryption (COSE)",
draft-ietf-cose-msg-24 (work in progress), November 2016. draft-ietf-cose-msg-24 (work in progress), November 2016.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>. <http://www.rfc-editor.org/info/rfc2119>.
[RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand
Key Derivation Function (HKDF)", RFC 5869,
DOI 10.17487/RFC5869, May 2010,
<http://www.rfc-editor.org/info/rfc5869>.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, [RFC5988] Nottingham, M., "Web Linking", RFC 5988,
DOI 10.17487/RFC5988, October 2010, DOI 10.17487/RFC5988, October 2010,
<http://www.rfc-editor.org/info/rfc5988>. <http://www.rfc-editor.org/info/rfc5988>.
[RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer
Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347,
January 2012, <http://www.rfc-editor.org/info/rfc6347>. January 2012, <http://www.rfc-editor.org/info/rfc6347>.
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
skipping to change at page 35, line 39 skipping to change at page 35, line 44
[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-06 (work in progress), March 2017. authz-06 (work in progress), March 2017.
[I-D.ietf-core-coap-tcp-tls] [I-D.ietf-core-coap-tcp-tls]
Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., Bormann, C., Lemay, S., Tschofenig, H., Hartke, K.,
Silverajan, B., and B. Raymor, "CoAP (Constrained Silverajan, B., and B. Raymor, "CoAP (Constrained
Application Protocol) over TCP, TLS, and WebSockets", Application Protocol) over TCP, TLS, and WebSockets",
draft-ietf-core-coap-tcp-tls-08 (work in progress), April draft-ietf-core-coap-tcp-tls-09 (work in progress), May
2017. 2017.
[I-D.mattsson-core-coap-actuators] [I-D.mattsson-core-coap-actuators]
Mattsson, J., Fornehed, J., Selander, G., and F. Mattsson, J., Fornehed, J., Selander, G., and F.
Palombini, "Controlling Actuators with CoAP", draft- Palombini, "Controlling Actuators with CoAP", draft-
mattsson-core-coap-actuators-02 (work in progress), mattsson-core-coap-actuators-02 (work in progress),
November 2016. November 2016.
[I-D.seitz-ace-oscoap-profile] [I-D.seitz-ace-oscoap-profile]
Seitz, L. and F. Palombini, "OSCOAP profile of ACE", Seitz, L., Gunnarsson, M., and F. Palombini, "OSCOAP
draft-seitz-ace-oscoap-profile-01 (work in progress), profile of ACE", draft-seitz-ace-oscoap-profile-03 (work
October 2016. in progress), June 2017.
[I-D.selander-ace-cose-ecdhe] [I-D.selander-ace-cose-ecdhe]
Selander, G., Mattsson, J., and F. Palombini, "Ephemeral Selander, G., Mattsson, J., and F. Palombini, "Ephemeral
Diffie-Hellman Over COSE (EDHOC)", draft-selander-ace- Diffie-Hellman Over COSE (EDHOC)", draft-selander-ace-
cose-ecdhe-06 (work in progress), April 2017. cose-ecdhe-06 (work in progress), April 2017.
[I-D.tiloca-core-multicast-oscoap] [I-D.tiloca-core-multicast-oscoap]
Tiloca, M., Selander, G., and F. Palombini, "Secure group Tiloca, M., Selander, G., and F. Palombini, "Secure group
communication for CoAP", draft-tiloca-core-multicast- communication for CoAP", draft-tiloca-core-multicast-
oscoap-01 (work in progress), March 2017. oscoap-01 (work in progress), March 2017.
[RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand
Key Derivation Function (HKDF)", RFC 5869,
DOI 10.17487/RFC5869, May 2010,
<http://www.rfc-editor.org/info/rfc5869>.
[RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for
Constrained-Node Networks", RFC 7228, Constrained-Node Networks", RFC 7228,
DOI 10.17487/RFC7228, May 2014, DOI 10.17487/RFC7228, May 2014,
<http://www.rfc-editor.org/info/rfc7228>. <http://www.rfc-editor.org/info/rfc7228>.
Appendix A. Test Vectors Appendix A. Test Vectors
TODO: This section needs to be updated. TODO: This section needs to be updated.
Appendix B. Examples Appendix B. Examples
skipping to change at page 39, line 37 skipping to change at page 39, line 37
and a certain server, targeting the security requirements for forward and a certain server, targeting the security requirements for forward
proxy of [I-D.hartke-core-e2e-security-reqs]. In contrast, many use proxy of [I-D.hartke-core-e2e-security-reqs]. In contrast, many use
cases require one and the same message to be protected for, and cases require one and the same message to be protected for, and
verified by, multiple endpoints, see caching proxy section of verified by, multiple endpoints, see caching proxy section of
[I-D.hartke-core-e2e-security-reqs]. Those security requirements can [I-D.hartke-core-e2e-security-reqs]. Those security requirements can
be addressed by protecting essentially the payload/content of be addressed by protecting essentially the payload/content of
individual messages using the COSE format ([I-D.ietf-cose-msg]), individual messages using the COSE format ([I-D.ietf-cose-msg]),
rather than the entire request/response message exchange. This is rather than the entire request/response message exchange. This is
referred to as Object Security of Content (OSCON). referred to as Object Security of Content (OSCON).
OSCON transforms an unprotected CoAP message into a protected CoAP OSCON transforms a CoAP message into an "OSCON message" in the
message in the following way: the payload of the unprotected CoAP following way: the payload of the original CoAP message is wrapped by
message is wrapped by a COSE object, which replaces the payload of a COSE object, which replaces the payload and this then becomes the
the unprotected CoAP message. We call the result the "protected" OSCON message.
CoAP message.
The unprotected payload shall be the plaintext/payload of the COSE The original payload shall be the plaintext/payload of the COSE
object. The 'protected' field of the COSE object 'Headers' shall object. The 'protected' field of the COSE object 'Headers' shall
include the context identifier, both for requests and responses. If include the context identifier, both for requests and responses. If
the unprotected CoAP message includes a Content-Format option, then the original CoAP message includes a Content-Format option, then the
the COSE object shall include a protected 'content type' field, whose 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 original message Content-Format value. The
Content-Format option of the protected CoAP message shall be replaced Content-Format option of the OSCOON message shall be replaced with
with "application/oscon" (Section 12) "application/oscon" (Section 12)
The COSE object shall be protected (encrypted) and verified The COSE object shall be protected (encrypted) and verified
(decrypted) as described in ([I-D.ietf-cose-msg]). (decrypted) as described in ([I-D.ietf-cose-msg]).
Most AEAD algorithms require a unique nonce for each message. Most AEAD algorithms require a unique nonce for each message.
Sequence numbers for partial IV as specified for OSCOAP may be used Sequence numbers for partial IV as specified for OSCOAP may be used
for replay protection as described in Section 6. The use of time for replay protection as described in Section 6. The use of time
stamps in the COSE header parameter 'operation time' stamps in the COSE header parameter 'operation time'
[I-D.ietf-cose-msg] for freshness may be used. [I-D.ietf-cose-msg] for freshness may be used.
OSCON shall not be used in cases where CoAP header fields (such as OSCON shall not be used in cases where CoAP header fields (such as
 End of changes. 84 change blocks. 
200 lines changed or deleted 224 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/