draft-ietf-core-coap-tcp-tls-05.txt   draft-ietf-core-coap-tcp-tls-06.txt 
CORE C. Bormann CORE C. Bormann
Internet-Draft Universitaet Bremen TZI Internet-Draft Universitaet Bremen TZI
Updates: 7641 (if approved) S. Lemay Updates: 7641 (if approved) S. Lemay
Intended status: Standards Track Zebra Technologies Intended status: Standards Track Zebra Technologies
Expires: April 14, 2017 H. Tschofenig Expires: August 18, 2017 H. Tschofenig
ARM Ltd. ARM Ltd.
K. Hartke K. Hartke
Universitaet Bremen TZI Universitaet Bremen TZI
B. Silverajan B. Silverajan
Tampere University of Technology Tampere University of Technology
B. Raymor, Ed. B. Raymor, Ed.
Microsoft Microsoft
October 11, 2016 February 14, 2017
CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets
draft-ietf-core-coap-tcp-tls-05 draft-ietf-core-coap-tcp-tls-06
Abstract Abstract
The Constrained Application Protocol (CoAP), although inspired by The Constrained Application Protocol (CoAP), although inspired by
HTTP, was designed to use UDP instead of TCP. The message layer of HTTP, was designed to use UDP instead of TCP. The message layer of
the CoAP over UDP protocol includes support for reliable delivery, the CoAP over UDP protocol includes support for reliable delivery,
simple congestion control, and flow control. simple congestion control, and flow control.
Some environments benefit from the availability of CoAP carried over Some environments benefit from the availability of CoAP carried over
reliable transports such as TCP or TLS. This document outlines the reliable transports such as TCP or TLS. This document outlines the
changes required to use CoAP over TCP, TLS, and WebSockets changes required to use CoAP over TCP, TLS, and WebSockets
transports. It also formally updates [RFC7641] for use with these
transports. transports.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 14, 2017. This Internet-Draft will expire on August 18, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2017 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 5
2. CoAP over TCP . . . . . . . . . . . . . . . . . . . . . . . . 5 2. CoAP over TCP . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1. Messaging Model . . . . . . . . . . . . . . . . . . . . . 5 2.1. Messaging Model . . . . . . . . . . . . . . . . . . . . . 6
2.2. UDP-to-TCP gateways . . . . . . . . . . . . . . . . . . . 6 2.2. Message Format . . . . . . . . . . . . . . . . . . . . . 7
2.3. Opening Handshake . . . . . . . . . . . . . . . . . . . . 6 2.3. Message Transmission . . . . . . . . . . . . . . . . . . 10
2.4. Message Format . . . . . . . . . . . . . . . . . . . . . 7 2.4. Connection Health . . . . . . . . . . . . . . . . . . . . 11
2.5. Message Transmission . . . . . . . . . . . . . . . . . . 10 3. CoAP over WebSockets . . . . . . . . . . . . . . . . . . . . 11
3. CoAP over WebSockets . . . . . . . . . . . . . . . . . . . . 10 3.1. Opening Handshake . . . . . . . . . . . . . . . . . . . . 13
3.1. Opening Handshake . . . . . . . . . . . . . . . . . . . . 12 3.2. Message Format . . . . . . . . . . . . . . . . . . . . . 14
3.2. Message Format . . . . . . . . . . . . . . . . . . . . . 13 3.3. Message Transmission . . . . . . . . . . . . . . . . . . 15
3.3. Message Transmission . . . . . . . . . . . . . . . . . . 14
3.4. Connection Health . . . . . . . . . . . . . . . . . . . . 15 3.4. Connection Health . . . . . . . . . . . . . . . . . . . . 15
3.5. Closing the Connection . . . . . . . . . . . . . . . . . 15
4. Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . 15 4. Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . . 16 4.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . . 16
4.2. Signaling Option Numbers . . . . . . . . . . . . . . . . 16 4.2. Signaling Option Numbers . . . . . . . . . . . . . . . . 16
4.3. Capability and Settings Messages (CSM) . . . . . . . . . 16 4.3. Capabilities and Settings Messages (CSM) . . . . . . . . 16
4.4. Ping and Pong Messages . . . . . . . . . . . . . . . . . 18 4.4. Ping and Pong Messages . . . . . . . . . . . . . . . . . 18
4.5. Release Messages . . . . . . . . . . . . . . . . . . . . 19 4.5. Release Messages . . . . . . . . . . . . . . . . . . . . 19
4.6. Abort Messages . . . . . . . . . . . . . . . . . . . . . 20 4.6. Abort Messages . . . . . . . . . . . . . . . . . . . . . 20
4.7. Capability and Settings examples . . . . . . . . . . . . 21 4.7. Signaling examples . . . . . . . . . . . . . . . . . . . 21
5. Block-wise Transfer and Reliable Transports . . . . . . . . . 21 5. Block-wise Transfer and Reliable Transports . . . . . . . . . 22
5.1. Example: GET with BERT Blocks . . . . . . . . . . . . . . 23 5.1. Example: GET with BERT Blocks . . . . . . . . . . . . . . 23
5.2. Example: PUT with BERT Blocks . . . . . . . . . . . . . . 23 5.2. Example: PUT with BERT Blocks . . . . . . . . . . . . . . 24
6. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 24 6. CoAP over Reliable Transport URIs . . . . . . . . . . . . . . 24
6.1. CoAP over TCP and TLS URIs . . . . . . . . . . . . . . . 24 6.1. coap+tcp URI scheme . . . . . . . . . . . . . . . . . . . 25
6.2. CoAP over WebSockets URIs . . . . . . . . . . . . . . . . 26 6.2. coaps+tcp URI scheme . . . . . . . . . . . . . . . . . . 25
7. Security Considerations . . . . . . . . . . . . . . . . . . . 27 6.3. coap+ws URI scheme . . . . . . . . . . . . . . . . . . . 26
7.1. Signaling Messages . . . . . . . . . . . . . . . . . . . 27 6.4. coaps+ws URI scheme . . . . . . . . . . . . . . . . . . . 27
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 6.5. Uri-Host and Uri-Port Options . . . . . . . . . . . . . . 28
8.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . . 28 6.6. Decomposing URIs into Options . . . . . . . . . . . . . . 28
8.2. CoAP Signaling Option Numbers Registry . . . . . . . . . 28 6.7. Composing URIs from Options . . . . . . . . . . . . . . . 29
8.3. Service Name and Port Number Registration . . . . . . . . 29
8.4. Secure Service Name and Port Number Registration . . . . 30 7. Securing CoAP . . . . . . . . . . . . . . . . . . . . . . . . 29
8.5. URI Scheme Registration . . . . . . . . . . . . . . . . . 30 7.1. TLS binding for CoAP over TCP . . . . . . . . . . . . . . 29
8.6. Well-Known URI Suffix Registration . . . . . . . . . . . 33 7.2. TLS usage for CoAP over WebSockets . . . . . . . . . . . 30
8.7. ALPN Protocol Identifier . . . . . . . . . . . . . . . . 33 8. Security Considerations . . . . . . . . . . . . . . . . . . . 30
8.8. WebSocket Subprotocol Registration . . . . . . . . . . . 33 8.1. Signaling Messages . . . . . . . . . . . . . . . . . . . 31
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 34 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31
9.1. Normative References . . . . . . . . . . . . . . . . . . 34 9.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . . 31
9.2. Informative References . . . . . . . . . . . . . . . . . 35 9.2. CoAP Signaling Option Numbers Registry . . . . . . . . . 31
9.3. Service Name and Port Number Registration . . . . . . . . 32
9.4. Secure Service Name and Port Number Registration . . . . 33
9.5. URI Scheme Registration . . . . . . . . . . . . . . . . . 34
9.6. Well-Known URI Suffix Registration . . . . . . . . . . . 36
9.7. ALPN Protocol Identifier . . . . . . . . . . . . . . . . 36
9.8. WebSocket Subprotocol Registration . . . . . . . . . . . 36
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 37
10.1. Normative References . . . . . . . . . . . . . . . . . . 37
10.2. Informative References . . . . . . . . . . . . . . . . . 38
Appendix A. Updates to RFC7641 Observing Resources in the Appendix A. Updates to RFC7641 Observing Resources in the
Constrained Application Protocol (CoAP) . . . . . . 36 Constrained Application Protocol (CoAP) . . . . . . 40
A.1. Notifications and Reordering . . . . . . . . . . . . . . 36 A.1. Notifications and Reordering . . . . . . . . . . . . . . 40
A.2. Transmission and Acknowledgements . . . . . . . . . . . . 36 A.2. Transmission and Acknowledgements . . . . . . . . . . . . 40
A.3. Cancellation . . . . . . . . . . . . . . . . . . . . . . 37 A.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 40
Appendix B. Negotiating Protocol Versions . . . . . . . . . . . 37 A.4. Cancellation . . . . . . . . . . . . . . . . . . . . . . 41
Appendix C. CoAP over WebSocket Examples . . . . . . . . . . . . 37 Appendix B. CoAP over WebSocket Examples . . . . . . . . . . . . 41
Appendix D. Change Log . . . . . . . . . . . . . . . . . . . . . 41 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 44
D.1. Since draft-core-coap-tcp-tls-02 . . . . . . . . . . . . 41 C.1. Since draft-core-coap-tcp-tls-02 . . . . . . . . . . . . 44
D.2. Since draft-core-coap-tcp-tls-03 . . . . . . . . . . . . 41 C.2. Since draft-core-coap-tcp-tls-03 . . . . . . . . . . . . 44
D.3. Since draft-core-coap-tcp-tls-04 . . . . . . . . . . . . 41 C.3. Since draft-core-coap-tcp-tls-04 . . . . . . . . . . . . 44
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 41 C.4. Since draft-core-coap-tcp-tls-05 . . . . . . . . . . . . 44
Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 45
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 42 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 45
1. Introduction 1. Introduction
The Constrained Application Protocol (CoAP) [RFC7252] was designed The Constrained Application Protocol (CoAP) [RFC7252] was designed
for Internet of Things (IoT) deployments, assuming that UDP [RFC0768] for Internet of Things (IoT) deployments, assuming that UDP [RFC0768]
or DTLS [RFC6347] over UDP can be used unimpeded. UDP is a good or DTLS [RFC6347] over UDP can be used unimpeded. UDP is a good
choice for transferring small amounts of data across networks that choice for transferring small amounts of data across networks that
follow the IP architecture. follow the IP architecture.
Some CoAP deployments need to integrate well with existing enterprise Some CoAP deployments need to integrate well with existing enterprise
skipping to change at page 4, line 35 skipping to change at page 4, line 44
TCP-based NAT bindings for longer periods based on the assumption TCP-based NAT bindings for longer periods based on the assumption
that a transport layer protocol, such as TCP, offers additional that a transport layer protocol, such as TCP, offers additional
information about the session life cycle. UDP, on the other hand, information about the session life cycle. UDP, on the other hand,
does not provide such information to a NAT and timeouts tend to be does not provide such information to a NAT and timeouts tend to be
much shorter [HomeGateway]. much shorter [HomeGateway].
Some environments may also benefit from the ability of TCP to Some environments may also benefit from the ability of TCP to
exchange larger payloads, such as firmware images, without exchange larger payloads, such as firmware images, without
application layer segmentation and to utilize the more sophisticated application layer segmentation and to utilize the more sophisticated
congestion control capabilities provided by many TCP implementations. congestion control capabilities provided by many TCP implementations.
Note that there is ongoing work to add more elaborate congestion
control to CoAP (see [I-D.ietf-core-cocoa]).
CoAP may be integrated into a Web environment where the front-end CoAP may be integrated into a Web environment where the front-end
uses CoAP over UDP from IoT devices to a cloud infrastructure and uses CoAP over UDP from IoT devices to a cloud infrastructure and
then CoAP over TCP between the back-end services. A TCP-to-UDP then CoAP over TCP between the back-end services. A TCP-to-UDP
gateway can be used at the cloud boundary to communicate with the gateway can be used at the cloud boundary to communicate with the
UDP-based IoT device. UDP-based IoT device.
To allow IoT devices to better communicate in these demanding To allow IoT devices to better communicate in these demanding
environments, CoAP needs to support different transport protocols, environments, CoAP needs to support different transport protocols,
namely TCP [RFC0793], in some situations secured by TLS [RFC5246]. namely TCP [RFC0793], in some situations secured by TLS [RFC5246].
In addition, some corporate networks only allow Internet access via a In addition, some corporate networks only allow Internet access via a
HTTP proxy. In this case, the best transport for CoAP would be the HTTP proxy. In this case, the best transport for CoAP might be the
WebSocket Protocol [RFC6455]. The WebSocket protocol provides two- WebSocket Protocol [RFC6455]. The WebSocket protocol provides two-
way communication between a client and a server after upgrading an way communication between a WebSocket client and a WebSocket server
HTTP/1.1 [RFC7230] connection and may be available in an environment after upgrading an HTTP/1.1 [RFC7230] connection and may be available
that blocks CoAP over UDP. Another scenario for CoAP over WebSockets in an environment that blocks CoAP over UDP. Another scenario for
is a CoAP application running inside a web browser without access to CoAP over WebSockets is a CoAP application running inside a web
connectivity other than HTTP and WebSockets. browser without access to connectivity other than HTTP and
WebSockets.
This document specifies how to access resources using CoAP requests This document specifies how to access resources using CoAP requests
and responses over the TCP/TLS and WebSocket protocols. This allows and responses over the TCP/TLS and WebSocket protocols. This allows
connectivity-limited applications to obtain end-to-end CoAP connectivity-limited applications to obtain end-to-end CoAP
connectivity either by communicating CoAP directly with a CoAP server connectivity either by communicating CoAP directly with a CoAP server
accessible over a TCP/TLS or WebSocket connection or via a CoAP accessible over a TCP/TLS or WebSocket connection or via a CoAP
intermediary that proxies CoAP requests and responses between intermediary that proxies CoAP requests and responses between
different transports, such as between WebSockets and UDP. different transports, such as between WebSockets and UDP.
1.1. Terminology Appendix A updates Observing Resources in the Constrained Application
Protocol [RFC7641] for use with CoAP over reliable transports.
[RFC7641] is an extension to the CoAP core protocol that enables CoAP
clients to "observe" a resource on a CoAP server. (The CoAP client
retrieves a representation of a resource and registers to be notified
by the CoAP server when the representation is updated.)
1.1. Conventions and 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", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in "OPTIONAL" in this document are to be interpreted as described in
[RFC2119]. [RFC2119].
This document assumes that readers are familiar with the terms and This document assumes that readers are familiar with the terms and
concepts that are used in [RFC6455], [RFC7252], and [RFC7641]. concepts that are used in [RFC6455], [RFC7252], [RFC7641], and
[RFC7959].
The term "reliable transport" only refers to stream-based transport The term "reliable transport" is used only to refer to transport
protocols such as TCP. protocols such as TCP which provide reliable and ordered delivery of
a byte-stream.
BERT Option: BERT Option:
A Block1 or Block2 option that includes an SZX value of 7. A Block1 or Block2 option that includes an SZX value of 7.
BERT Block: BERT Block:
The payload of a CoAP message that is affected by a BERT Option in The payload of a CoAP message that is affected by a BERT Option in
descriptive usage (Section 2.1 of [RFC7959]). descriptive usage (Section 2.1 of [RFC7959]).
Connection Initiator:
The peer that opens a reliable byte stream connection, i.e., the
TCP active opener, TLS client, or WebSocket client.
Connection Acceptor:
The peer that accepts the reliable byte stream connection opened
by the other peer, i.e., the TCP passive opener, TLS server, or
WebSocket server.
For simplicity, a Payload Marker (0xFF) is shown in all examples for
message formats:
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 1 1 1 1 1 1 1| Payload (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
The Payload Marker indicates the start of the optional payload and is
absent for zero-length payloads (see section 3 of [RFC7252]).
2. CoAP over TCP 2. CoAP over TCP
The request/response interaction model of CoAP over TCP is the same The request/response interaction model of CoAP over TCP is the same
as CoAP over UDP. The primary differences are in the message layer. as CoAP over UDP. The primary differences are in the message layer.
CoAP over UDP supports optional reliability by defining four types of The message layer of CoAP over UDP supports optional reliability by
messages: Confirmable, Non-confirmable, Acknowledgement, and Reset. defining four Types of messages: Confirmable, Non-confirmable,
TCP eliminates the need for the message layer to support reliability. Acknowledgement, and Reset. In addition, messages include a Message
As a result, message types are not defined in CoAP over TCP. ID to relate Acknowledgments to Confirmable messages and to detect
duplicate messages.
2.1. Messaging Model 2.1. Messaging Model
Conceptually, CoAP over TCP replaces most of the CoAP over UDP Conceptually, CoAP over TCP replaces most of the message layer of
message layer with a framing mechanism on top of the byte stream CoAP over UDP with a framing mechanism on top of the byte-stream
provided by TCP/TLS, conveying the length information for each provided by TCP/TLS, conveying the length information for each
message that on datagram transports is provided by the UDP/DTLS message that on datagram transports is provided by the UDP/DTLS
datagram layer. datagram layer.
TCP ensures reliable message transmission, so the CoAP over TCP TCP ensures reliable message transmission, so the message layer of
messaging layer is not required to support acknowledgements or CoAP over TCP is not required to support acknowledgements or to
detection of duplicate messages. As a result, both the Type and detect duplicate messages. As a result, both the Type and Message ID
Message ID fields are no longer required and are removed from the fields are no longer required and are removed from the CoAP over TCP
CoAP over TCP message format. All messages are also untyped. message format.
Figure 2 illustrates the difference between CoAP over UDP and CoAP Figure 2 illustrates the difference between CoAP over UDP and CoAP
over reliable transport. The removed Type and Message ID fields are over reliable transport. The removed Type and Message ID fields are
indicated by dashes. indicated by dashes.
Client Server Client Server CoAP Client CoAP Server CoAP Client CoAP Server
| | | | | | | |
| CON [0xbc90] | | (-------) [------] | | CON [0xbc90] | | (-------) [------] |
| GET /temperature | | GET /temperature | | GET /temperature | | GET /temperature |
| (Token 0x71) | | (Token 0x71) | | (Token 0x71) | | (Token 0x71) |
+------------------->| +------------------->| +------------------->| +------------------->|
| | | | | | | |
| ACK [0xbc90] | | (-------) [------] | | ACK [0xbc90] | | (-------) [------] |
| 2.05 Content | | 2.05 Content | | 2.05 Content | | 2.05 Content |
| (Token 0x71) | | (Token 0x71) | | (Token 0x71) | | (Token 0x71) |
| "22.5 C" | | "22.5 C" | | "22.5 C" | | "22.5 C" |
|<-------------------+ |<-------------------+ |<-------------------+ |<-------------------+
| | | | | | | |
CoAP over UDP CoAP over reliable CoAP over UDP CoAP over reliable
transport transport
Figure 2: Comparison between CoAP over unreliable and reliable Figure 2: Comparison between CoAP over unreliable and reliable
transport. transport
2.2. UDP-to-TCP gateways
A UDP-to-TCP gateway MUST discard all Empty messages (Code 0.00)
after processing at the message layer. For Confirmable (CON), Non-
Confirmable (NOM), and Acknowledgement (ACK) messages that are not
Empty, their contents are repackaged into untyped messages.
2.3. Opening Handshake
Both the client and the server MUST send a Capability and Settings
message (CSM see Section 4.3) as its first message on the connection.
This message establishes the initial settings and capabilities for
the endpoint such as maximum message size or support for block-wise
transfers. The absence of options in the CSM indicates that base
values are assumed.
To avoid unnecessary latency, a client MAY send additional messages
without waiting to receive the server CSM; however, it is important
to note that the server CSM might advertise capabilities that impact
how a client is expected to communicate with the server. For
example, the server CSM could advertise a Max-Message-Size option
(See Section 4.3.2) that is smaller than the base value (1152).
Clients and servers MUST treat a missing or invalid CSM as a
connection error and abort the connection (see Section 4.6).
2.4. Message Format 2.2. Message Format
The CoAP message format defined in [RFC7252], as shown in Figure 3, The CoAP message format defined in [RFC7252], as shown in Figure 3,
relies on the datagram transport (UDP, or DTLS over UDP) for keeping relies on the datagram transport (UDP, or DTLS over UDP) for keeping
the individual messages separate and for providing length the individual messages separate and for providing length
information. information.
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Ver| T | TKL | Code | Message ID | |Ver| T | TKL | Code | Message ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Token (if any, TKL bytes) ... | Token (if any, TKL bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Options (if any) ... | 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) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 3: RFC 7252 defined CoAP Message Format. Figure 3: RFC 7252 defined CoAP Message Format
The CoAP over TCP message format is very similar to the format The CoAP over TCP message format is very similar to the format
specified for CoAP over UDP. The differences are as follows: specified for CoAP over UDP. The differences are as follows:
o Since the underlying TCP connection provides retransmissions and o Since the underlying TCP connection provides retransmissions and
deduplication, there is no need for the reliability mechanisms deduplication, there is no need for the reliability mechanisms
provided by CoAP over UDP. The "T" and "Message ID" fields in the provided by CoAP over UDP. The Type (T) and Message ID fields in
CoAP message header are elided. the CoAP message header are elided.
o The "Ver" field is elided as well. In constrast to the UDP o The Version (Vers) field is elided as well. In contrast to the
message layer for UDP and DTLS, the CoAP over TCP message layer message format of CoAP over UDP, the message format for CoAP over
does not send a version number in each message. If required in TCP does not include a version number. CoAP is defined in
the future, a new Capability and Settings Option (See Appendix B) [RFC7252] with a version number of 1. At this time, there is no
could be defined to support version negotiation. known reason to support version numbers different from 1. If
version negotiation needs to be addressed in the future, then
Capabilities and Settings Messages (CSM see Section 4.3) have been
specifically designed to enable such a potential feature.
o In a stream oriented transport protocol such as TCP, a form of o In a stream oriented transport protocol such as TCP, a form of
message delimitation is needed. For this purpose, CoAP over TCP message delimitation is needed. For this purpose, CoAP over TCP
introduces a length field with variable size. Figure 4 shows the introduces a length field with variable size. Figure 4 shows the
adjusted CoAP message format with a modified structure for the adjusted CoAP message format with a modified structure for the
fixed header (first 4 bytes of the CoAP over UDP header), which fixed header (first 4 bytes of the CoAP over UDP header), which
includes the length information of variable size, shown here as an includes the length information of variable size, shown here as an
8-bit length. 8-bit length.
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Len=13 | TKL |Extended Length| Code | TKL bytes ... |Len=13 | TKL |Extended Length| Code | TKL bytes ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Options (if any) ... | 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) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 4: CoAP frame with 8-bit Extended Length field. Figure 4: CoAP frame with 8-bit Extended Length field
Length (Len): 4-bit unsigned integer. A value between 0 and 12 Length (Len): 4-bit unsigned integer. A value between 0 and 12
directly indicates the length of the message in bytes starting directly indicates the length of the message in bytes starting
with the first bit of the Options field. Three values are with the first bit of the Options field. Three values are
reserved for special constructs: reserved for special constructs:
13: An 8-bit unsigned integer (Extended Length) follows the 13: An 8-bit unsigned integer (Extended Length) follows the
initial byte and indicates the length of options/payload minus initial byte and indicates the length of options/payload minus
13. 13.
skipping to change at page 9, line 15 skipping to change at page 9, line 25
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Len | TKL | Code | Token (if any, TKL bytes) ... | Len | TKL | Code | Token (if any, TKL bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Options (if any) ... | 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) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 5: CoAP message format without an Extended Length field. Figure 5: CoAP message format without an Extended Length field
For example: A CoAP message just containing a 2.03 code with the For example: A CoAP message just containing a 2.03 code with the
token 7f and no options or payload would be encoded as shown in token 7f and no options or payload would be encoded as shown in
Figure 6. Figure 6.
0 1 2 0 1 2
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0x01 | 0x43 | 0x7f | | 0x01 | 0x43 | 0x7f |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Len = 0 ------> 0x01 Len = 0 ------> 0x01
TKL = 1 ___/ TKL = 1 ___/
Code = 2.03 --> 0x43 Code = 2.03 --> 0x43
Token = 0x7f Token = 0x7f
Figure 6: CoAP message with no options or payload. Figure 6: CoAP message with no options or payload
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Len=14 | TKL | Extended Length (16 bits) | Code | |Len=14 | TKL | Extended Length (16 bits) | Code |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Token (if any, TKL bytes) ... | Token (if any, TKL bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Options (if any) ... | 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) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 7: CoAP message format with 16-bit Extended Length field. Figure 7: CoAP message format with 16-bit Extended Length field
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Len=15 | TKL | Extended Length (32 bits) |Len=15 | TKL | Extended Length (32 bits)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| | Code | Token (if any, TKL bytes) ... | | Code | Token (if any, TKL bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Options (if any) ... | 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) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 8: CoAP message format with 32-bit Extended Length field. Figure 8: CoAP message format with 32-bit Extended Length field
The semantics of the other CoAP header fields are left unchanged. The semantics of the other CoAP header fields are left unchanged.
2.5. Message Transmission 2.3. Message Transmission
Once a connection is established, both endpoints MUST send a
Capabilities and Settings message (CSM see Section 4.3) as their
first message on the connection. This message establishes the
initial settings and capabilities for the endpoint such as maximum
message size or support for block-wise transfers. The absence of
options in the CSM indicates that base values are assumed.
To avoid a deadlock, the Connection Initiator MUST NOT wait for the
Connection Acceptor to send its initial CSM message before sending
its own initial CSM message. Conversely, the Connection Acceptor MAY
wait for the Connection Initiator to send its initial CSM message
before sending its own initial CSM message.
To avoid unnecessary latency, a Connection Initiator MAY send
additional messages without waiting to receive the Connection
Acceptor's CSM; however, it is important to note that the Connection
Acceptor's CSM might advertise capabilities that impact how the
initiator is expected to communicate with the acceptor. For example,
the acceptor CSM could advertise a Max-Message-Size option (see
Section 4.3.1) that is smaller than the base value (1152).
Endpoints MUST treat a missing or invalid CSM as a connection error
and abort the connection (see Section 4.6).
CoAP requests and responses are exchanged asynchronously over the CoAP requests and responses are exchanged asynchronously over the
TCP/TLS connection. A CoAP client can send multiple requests without TCP/TLS connection. A CoAP client can send multiple requests without
waiting for a response and the CoAP server can return responses in waiting for a response and the CoAP server can return responses in
any order. Responses MUST be returned over the same connection as any order. Responses MUST be returned over the same connection as
the originating request. Concurrent requests are differentiated by the originating request. Concurrent requests are differentiated by
their Token, which is scoped locally to the connection. their Token, which is scoped locally to the connection.
The connection is bi-directional, so requests can be sent both by the The connection is bi-directional, so requests can be sent both by the
entity that established the connection and the remote host. entity that established the connection and the remote host.
Retransmission and deduplication of messages is provided by the TCP/ Retransmission and deduplication of messages is provided by the TCP/
TLS protocol. TLS protocol.
2.4. Connection Health
Empty messages (Code 0.00) can always be sent and MUST be ignored by
the recipient. This provides a basic keep-alive function that can
refresh NAT bindings.
If a CoAP client does not receive any response for some time after
sending a CoAP request (or, similarly, when a client observes a
resource and it does not receive any notification for some time), it
can send a CoAP Ping Signaling message (Section 4.4) to test the
connection and verify that the CoAP server is responsive.
3. CoAP over WebSockets 3. CoAP over WebSockets
CoAP over WebSockets is intentionally similar to CoAP over TCP;
therefore, this section only specifies the differences between the
transports.
CoAP over WebSockets can be used in a number of configurations. The CoAP over WebSockets can be used in a number of configurations. The
most basic configuration is a CoAP client retrieving or updating a most basic configuration is a CoAP client retrieving or updating a
CoAP resource located at a CoAP server that exposes a WebSocket CoAP resource located on a CoAP server that exposes a WebSocket
endpoint (Figure 9). The CoAP client acts as the WebSocket client, endpoint (Figure 9). The CoAP client acts as the WebSocket client,
establishes a WebSocket connection, and sends a CoAP request, to establishes a WebSocket connection, and sends a CoAP request, to
which the CoAP server returns a CoAP response. The WebSocket which the CoAP server returns a CoAP response. The WebSocket
connection can be used for any number of requests. connection can be used for any number of requests.
___________ ___________ ___________ ___________
| | | | | | | |
| _|___ requests ___|_ | | _|___ requests ___|_ |
| CoAP / \ \ -------------> / / \ CoAP | | CoAP / \ \ -------------> / / \ CoAP |
| Client \__/__/ <------------- \__\__/ Server | | Client \__/__/ <------------- \__\__/ Server |
skipping to change at page 11, line 22 skipping to change at page 12, line 22
WebSocket =============> WebSocket WebSocket =============> WebSocket
Client Connection Server Client Connection Server
Figure 9: CoAP Client (WebSocket client) accesses CoAP Server Figure 9: CoAP Client (WebSocket client) accesses CoAP Server
(WebSocket server) (WebSocket server)
The challenge with this configuration is how to identify a resource The challenge with this configuration is how to identify a resource
in the namespace of the CoAP server. When the WebSocket protocol is in the namespace of the CoAP server. When the WebSocket protocol is
used by a dedicated client directly (i.e., not from a web page used by a dedicated client directly (i.e., not from a web page
through a web browser), the client can connect to any WebSocket through a web browser), the client can connect to any WebSocket
endpoint. This means it is necessary for the client to identify both endpoint. Section 6.3 and Section 6.4 define new URI schemes that
the WebSocket endpoint (identified by a "ws" or "wss" URI) and the enable the client to identify both a WebSocket endpoint and the path
path and query of the CoAP resource within that endpoint from the and query of the CoAP resource within that endpoint. When the
same URI. When the WebSocket protocol is used from a web page, the WebSocket protocol is used from a web page, the choices are more
choices are more limited [RFC6454], but the challenge persists. limited [RFC6454], but the challenge persists.
Section 6.2 defines a new "coap+ws" URI scheme that identifies both a
WebSocket endpoint and a resource within that endpoint as follows:
coap+ws://example.org/sensors/temperature?u=Cel
\______ ______/\___________ ___________/
\/ \/
Uri-Path: "sensors"
ws://example.org/.well-known/coap Uri-Path: "temperature"
Uri-Query: "u=Cel"
Figure 10: The "coap+ws" URI Scheme
Another possible configuration is to set up a CoAP forward proxy at Another possible configuration is to set up a CoAP forward proxy at
the WebSocket endpoint. Depending on what transports are available the WebSocket endpoint. Depending on what transports are available
to the proxy, it could forward the request to a CoAP server with a to the proxy, it could forward the request to a CoAP server with a
CoAP UDP endpoint (Figure 11), an SMS endpoint (a.k.a. mobile phone), CoAP UDP endpoint (Figure 10), an SMS endpoint (a.k.a. mobile phone),
or even another WebSocket endpoint. The client specifies the or even another WebSocket endpoint. The CoAP client specifies the
resource to be updated or retrieved in the Proxy-URI Option. resource to be updated or retrieved in the Proxy-Uri Option.
___________ ___________ ___________ ___________ ___________ ___________
| | | | | | | | | | | |
| _|___ ___|_ _|___ ___|_ | | _|___ ___|_ _|___ ___|_ |
| CoAP / \ \ ---> / / \ CoAP / \ \ ---> / / \ CoAP | | CoAP / \ \ ---> / / \ CoAP / \ \ ---> / / \ CoAP |
| Client \__/__/ <--- \__\__/ Proxy \__/__/ <--- \__\__/ Server | | Client \__/__/ <--- \__\__/ Proxy \__/__/ <--- \__\__/ Server |
| | | | | | | | | | | |
|___________| |___________| |___________| |___________| |___________| |___________|
WebSocket ===> WebSocket UDP UDP WebSocket ===> WebSocket UDP UDP
Client Server Client Server Client Server Client Server
Figure 11: CoAP Client (WebSocket client) accesses CoAP Server (UDP Figure 10: CoAP Client (WebSocket client) accesses CoAP Server (UDP
server) via a CoAP proxy (WebSocket server/UDP client) server) via a CoAP proxy (WebSocket server/UDP client)
A third possible configuration is a CoAP server running inside a web A third possible configuration is a CoAP server running inside a web
browser (Figure 12). The web browser initially connects to a browser (Figure 11). The web browser initially connects to a
WebSocket endpoint and is then reachable through the WebSocket WebSocket endpoint and is then reachable through the WebSocket
server. When no connection exists, the CoAP server is unreachable. server. When no connection exists, the CoAP server is unreachable.
Because the WebSocket server is the only way to reach the CoAP Because the WebSocket server is the only way to reach the CoAP
server, the CoAP proxy should be a Reverse Proxy. server, the CoAP proxy should be a Reverse Proxy.
___________ ___________ ___________ ___________ ___________ ___________
| | | | | | | | | | | |
| _|___ ___|_ _|___ ___|_ | | _|___ ___|_ _|___ ___|_ |
| CoAP / \ \ ---> / / \ CoAP / / \ ---> / \ \ CoAP | | CoAP / \ \ ---> / / \ CoAP / / \ ---> / \ \ CoAP |
| Client \__/__/ <--- \__\__/ Proxy \__\__/ <--- \__/__/ Server | | Client \__/__/ <--- \__\__/ Proxy \__\__/ <--- \__/__/ Server |
| | | | | | | | | | | |
|___________| |___________| |___________| |___________| |___________| |___________|
skipping to change at page 12, line 35 skipping to change at page 13, line 18
___________ ___________ ___________ ___________ ___________ ___________
| | | | | | | | | | | |
| _|___ ___|_ _|___ ___|_ | | _|___ ___|_ _|___ ___|_ |
| CoAP / \ \ ---> / / \ CoAP / / \ ---> / \ \ CoAP | | CoAP / \ \ ---> / / \ CoAP / / \ ---> / \ \ CoAP |
| Client \__/__/ <--- \__\__/ Proxy \__\__/ <--- \__/__/ Server | | Client \__/__/ <--- \__\__/ Proxy \__\__/ <--- \__/__/ Server |
| | | | | | | | | | | |
|___________| |___________| |___________| |___________| |___________| |___________|
UDP UDP WebSocket <=== WebSocket UDP UDP WebSocket <=== WebSocket
Client Server Server Client Client Server Server Client
Figure 12: CoAP Client (UDP client) accesses sleepy CoAP Server Figure 11: CoAP Client (UDP client) accesses CoAP Server (WebSocket
(WebSocket client) via a CoAP proxy (UDP server/WebSocket server) client) via a CoAP proxy (UDP server/WebSocket server)
Further configurations are possible, including those where a Further configurations are possible, including those where a
WebSocket connection is established through an HTTP proxy. WebSocket connection is established through an HTTP proxy.
CoAP over WebSockets is intentionally very similar to CoAP over UDP.
Therefore, instead of presenting CoAP over WebSockets as a new
protocol, this document specifies it as a series of deltas from
[RFC7252].
3.1. Opening Handshake 3.1. Opening Handshake
Before CoAP requests and responses are exchanged, a WebSocket Before CoAP requests and responses are exchanged, a WebSocket
connection is established as defined in Section 4 of [RFC6455]. connection is established as defined in Section 4 of [RFC6455].
Figure 13 shows an example. Figure 12 shows an example.
The WebSocket client MUST include the subprotocol name "coap" in the The WebSocket client MUST include the subprotocol name "coap" in the
list of protocols, which indicates support for the protocol defined list of protocols, which indicates support for the protocol defined
in this document. Any later, incompatible versions of CoAP or CoAP in this document. Any later, incompatible versions of CoAP or CoAP
over WebSockets will use a different subprotocol name. over WebSockets will use a different subprotocol name.
The WebSocket client includes the hostname of the WebSocket server in The WebSocket client includes the hostname of the WebSocket server in
the Host header field of its handshake as per [RFC6455]. The Host the Host header field of its handshake as per [RFC6455]. The Host
header field also indicates the default value of the Uri-Host Option header field also indicates the default value of the Uri-Host Option
in requests from the WebSocket client to the WebSocket server. in requests from the WebSocket client to the WebSocket server.
skipping to change at page 13, line 29 skipping to change at page 14, line 19
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Protocol: coap Sec-WebSocket-Protocol: coap
Sec-WebSocket-Version: 13 Sec-WebSocket-Version: 13
HTTP/1.1 101 Switching Protocols HTTP/1.1 101 Switching Protocols
Upgrade: websocket Upgrade: websocket
Connection: Upgrade Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
Sec-WebSocket-Protocol: coap Sec-WebSocket-Protocol: coap
Figure 13: Example of an Opening Handshake Figure 12: Example of an Opening Handshake
3.2. Message Format 3.2. Message Format
Once a WebSocket connection is established, CoAP requests and Once a WebSocket connection is established, CoAP requests and
responses can be exchanged as WebSocket messages. Since CoAP uses a responses can be exchanged as WebSocket messages. Since CoAP uses a
binary message format, the messages are transmitted in binary data binary message format, the messages are transmitted in binary data
frames as specified in Sections 5 and 6 of [RFC6455]. frames as specified in Sections 5 and 6 of [RFC6455].
The message format shown in Figure 14 is the same as the CoAP over The message format shown in Figure 13 is the same as the CoAP over
TCP message format (see Section 2.4) with one restriction. The TCP message format (see Section 2.2) with one change. The Length
Length (Len) field MUST be set to zero because the WebSockets frame (Len) field MUST be set to zero because the WebSockets frame contains
contains the length. the length.
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Len | TKL | Code | Token (TKL bytes) ... | Len=0 | TKL | Code | Token (TKL bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Options (if any) ... | 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) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 14: CoAP Message Format over WebSockets Figure 13: CoAP Message Format over WebSockets
The CoAP over TCP message format eliminates the Version field defined As with CoAP over TCP, the message format for CoAP over WebSockets
in CoAP over UDP. If CoAP version negotiation is required in the eliminates the Version field defined in CoAP over UDP. If CoAP
future, CoAP over WebSockets can address the requirement by the version negotiation is required in the future, CoAP over WebSockets
definition of a new subprotocol identifier that is negotiated during can address the requirement by the definition of a new subprotocol
the opening handshake. identifier that is negotiated during the opening handshake.
Requests and response messages can be fragmented as specified in Requests and response messages can be fragmented as specified in
Section 5.4 of [RFC6455], though typically they are sent unfragmented Section 5.4 of [RFC6455], though typically they are sent unfragmented
as they tend to be small and fully buffered before transmission. The as they tend to be small and fully buffered before transmission. The
WebSocket protocol does not provide means for multiplexing. If it is WebSocket protocol does not provide means for multiplexing. If it is
not desirable for a large message to monopolize the connection, not desirable for a large message to monopolize the connection,
requests and responses can be transferred in a block-wise fashion as requests and responses can be transferred in a block-wise fashion as
defined in [RFC7959]. defined in [RFC7959].
Empty messages (Code 0.00) MUST be ignored by the recipient (see also
Section 4.4).
3.3. Message Transmission 3.3. Message Transmission
As with CoAP over TCP, both endpoints MUST send a Capabilities and
Settings message (CSM see Section 4.3) as their first message on the
WebSocket connection.
CoAP requests and responses are exchanged asynchronously over the CoAP requests and responses are exchanged asynchronously over the
WebSocket connection. A CoAP client can send multiple requests WebSocket connection. A CoAP client can send multiple requests
without waiting for a response and the CoAP server can return without waiting for a response and the CoAP server can return
responses in any order. Responses MUST be returned over the same responses in any order. Responses MUST be returned over the same
connection as the originating request. Concurrent requests are connection as the originating request. Concurrent requests are
differentiated by their Token, which is scoped locally to the differentiated by their Token, which is scoped locally to the
connection. connection.
The connection is bi-directional, so requests can be sent both by the The connection is bi-directional, so requests can be sent both by the
entity that established the connection and the remote host. entity that established the connection and the remote host.
Retransmission and deduplication of messages is provided by the As with CoAP over TCP, retransmission and deduplication of messages
WebSocket protocol. CoAP over WebSockets therefore does not make a is provided by the WebSocket protocol. CoAP over WebSockets
distinction between Confirmable or Non-Confirmable messages, and does therefore does not make a distinction between Confirmable or Non-
not provide Acknowledgement or Reset messages. Confirmable messages, and does not provide Acknowledgement or Reset
messages.
3.4. Connection Health 3.4. Connection Health
When a client does not receive any response for some time after As with CoAP over TCP, a CoAP client can test the health of the CoAP
sending a CoAP request (or, similarly, when a client observes a over WebSocket connection by sending a CoAP Ping Signaling message
resource and it does not receive any notification for some time), the (Section 4.4). WebSocket Ping and unsolicited Pong frames
connection between the WebSocket client and the WebSocket server may (Section 5.5 of [RFC6455]) SHOULD NOT be used to ensure that
be lost or temporarily disrupted without the client being aware of redundant maintenance traffic is not transmitted.
it.
To check the health of the WebSocket connection (and thereby of all
active requests, if any), a client can send a CoAP Ping Signaling
message (Section 4.4). WebSocket Ping and unsolicited Pong frames as
specified in Section 5.5 of [RFC6455] SHOULD NOT be used to ensure
that redundant maintenance traffic is not transmitted.
There is no way to retransmit a request without creating a new one.
Re-registering interest in a resource is permitted, but entirely
unnecessary.
3.5. Closing the Connection
The WebSocket connection is closed as specified in Section 7 of
[RFC6455].
All requests for which the CoAP client has not received a response
yet are cancelled when the connection is closed.
4. Signaling 4. Signaling
Signaling messages are introduced to allow peers to: Signaling messages are introduced to allow peers to:
o Share characteristics such as maximum message size for the o Related characteristics such as maximum message size for the
connection connection
o Shutdown the connection in an ordered fashion o Shut down the connection in an orderly fashion
o Terminate the connection in response to a serious error condition o Provide diagnostic information when terminating a connection in
response to a serious error condition
Signaling is a third basic kind of message in CoAP, after requests Signaling is a third basic kind of message in CoAP, after requests
and responses. Signaling messages share a common structure with the and responses. Signaling messages share a common structure with the
existing CoAP messages. There is a code, a token, options, and an existing CoAP messages. There is a code, a token, options, and an
optional payload. optional payload.
(See Section 3 of [RFC7252] for the overall structure, as adapted to (See Section 3 of [RFC7252] for the overall structure, as adapted to
the specific transport.) the specific transport.)
4.1. Signaling Codes 4.1. Signaling Codes
A code in the 7.01-7.31 range indicates a Signaling message. Values A code in the 7.00-7.31 range indicates a Signaling message. Values
in this range are assigned by the "CoAP Signaling Codes" sub-registry in this range are assigned by the "CoAP Signaling Codes" sub-registry
(see Section 8.1). (see Section 9.1).
For each message, there is a sender and a peer receiving the message. For each message, there is a sender and a peer receiving the message.
Payloads in Signaling messages are diagnostic payloads (see Payloads in Signaling messages are diagnostic payloads as defined in
Section 5.5.2 of [RFC7252]), unless otherwise defined by a Signaling Section 5.5.2 of [RFC7252]), unless otherwise defined by a Signaling
message option. message option.
4.2. Signaling Option Numbers 4.2. Signaling Option Numbers
Option numbers for Signaling messages are specific to the message Option numbers for Signaling messages are specific to the message
code. They do not share the number space with CoAP options for code. They do not share the number space with CoAP options for
request/response messages or with Signaling messages using other request/response messages or with Signaling messages using other
codes. codes.
Option numbers are assigned by the "CoAP Signaling Option Numbers" Option numbers are assigned by the "CoAP Signaling Option Numbers"
sub-registry (see Section 8.2). sub-registry (see Section 9.2).
Signaling options are elective or critical as defined in Signaling options are elective or critical as defined in
Section 5.4.1 of [RFC7252]). If a Signaling option is critical and Section 5.4.1 of [RFC7252]. If a Signaling option is critical and
not understood by the receiver, it MUST abort the connection (see not understood by the receiver, it MUST abort the connection (see
Section 4.6). If the option is understood but cannot be processed, Section 4.6). If the option is understood but cannot be processed,
the option documents the behavior. the option documents the behavior.
4.3. Capability and Settings Messages (CSM) 4.3. Capabilities and Settings Messages (CSM)
Capability and Settings messages (CSM) are used for two purposes: Capabilities and Settings messages (CSM) are used for two purposes:
o Each capability option advertises one capability of the sender to o Each capability option advertises one capability of the sender to
the recipient. the recipient.
o Setting options indicate a setting that will be applied by the o Setting options indicate a setting that will be applied by the
sender. sender.
A Capability and Settings message MUST be sent by both endpoints at One CSM MUST be sent by both endpoints at the start of the
the start of the connection and MAY be sent at any other time by connection. Further CSM MAY be sent at any other time by either
either endpoint over the lifetime of the connection. endpoint over the lifetime of the connection.
Both capability and settings options are cumulative. A Capability Both capability and setting options are cumulative. A CSM does not
and Settings message does not invalidate a previously sent capability invalidate a previously sent capability indication or setting even if
indication or setting even if it is not repeated. A capability it is not repeated. A capability message without any option is a no-
message without any option is a no-operation (and can be used as operation (and can be used as such). An option that is sent might
such). An option that is sent might override a previous value for override a previous value for the same option. The option defines
the same option. The option defines how to handle this case if how to handle this case if needed.
needed.
Base values are listed below for CSM Options. These are the values Base values are listed below for CSM Options. These are the values
for the Capability and Setting before any Capability and Settings for the capability and setting before any Capabilities and Settings
messages send a modified value. messages send a modified value.
These are not default values for the option as defined in These are not default values for the option as defined in
Section 5.4.4 in [RFC7252]. A default value would mean that an empty Section 5.4.4 in [RFC7252]. A default value would mean that an empty
Capability and Settings message would result in the option being set Capabilities and Settings message would result in the option being
to its default value. set to its default value.
Capability and Settings messages are indicated by the 7.01 code Capabilities and Settings messages are indicated by the 7.01 code
(CSM). (CSM).
4.3.1. Server-Name Setting Option 4.3.1. Max-Message-Size Capability Option
+--------+------------+-------------+--------+--------+-------------+
| Number | Applies to | Name | Format | Length | Base Value |
+--------+------------+-------------+--------+--------+-------------+
| 1 | CSM | Server-Name | string | 1-255 | (see below) |
+--------+------------+-------------+--------+--------+-------------+
A client can use the Server-Name critical option to indicate the
default value for the Uri-Host Options in the messages that it sends
to the server. It has the same restrictions as the Uri-Host Option
(Section 5.10 of [RFC7252].
For TLS, the initial value for the Server-Name Option is given by the The sender can use the elective Max-Message-Size Option to indicate
SNI value. the maximum message size in bytes that it can receive.
For Websockets, the initial value for the Server-Name Option is given +---+---+---+---------+------------------+--------+--------+--------+
by the HTTP Host header field. | # | C | R | Applies | Name | Format | Length | Base |
| | | | to | | | | Value |
+---+---+---+---------+------------------+--------+--------+--------+
| 2 | | | CSM | Max-Message-Size | uint | 0-4 | 1152 |
+---+---+---+---------+------------------+--------+--------+--------+
4.3.2. Max-Message-Size Capability Option C=Critical, R=Repeatable
The sender can use the Max-Message-Size elective option to indicate As per Section 4.6 of [RFC7252], the base value (and the value used
the maximum message size in bytes that it can receive. when this option is not implemented) is 1152.
+--------+-----------+------------------+--------+--------+---------+ The active value of the Max-Message-Size Option is replaced each time
| Number | Applies | Name | Format | Length | Base | the option is sent with a modified value. Its starting value is its
| | to | | | | Value | base value.
+--------+-----------+------------------+--------+--------+---------+
| 2 | CSM | Max-Message-Size | uint | 0-4 | 1152 |
+--------+-----------+------------------+--------+--------+---------+
As per Section 4.6 of [RFC7252], the base value (and the value used 4.3.2. Block-wise Transfer Capability Option
when this option is not implemented) is 1152. A peer that relies on
this option being indicated with a certain minimum value will enjoy
limited interoperability.
4.3.3. Block-wise Transfer Capability Option +---+---+---+---------+-----------------+--------+--------+---------+
| # | C | R | Applies | Name | Format | Length | Base |
| | | | to | | | | Value |
+---+---+---+---------+-----------------+--------+--------+---------+
| 4 | | | CSM | Block-wise | empty | 0 | (none) |
| | | | | Transfer | | | |
+---+---+---+---------+-----------------+--------+--------+---------+
+--------+-----------+----------------+--------+--------+-----------+ C=Critical, R=Repeatable
| Number | Applies | Name | Format | Length | Base |
| | to | | | | Value |
+--------+-----------+----------------+--------+--------+-----------+
| 4 | CSM | Block-wise | empty | 0 | (none) |
| | | Transfer | | | |
+--------+-----------+----------------+--------+--------+-----------+
A sender can use the Block-wise Transfer elective Option to indicate A sender can use the elective Block-wise Transfer Option to indicate
that it supports the block-wise transfer protocol [RFC7959]. that it supports the block-wise transfer protocol [RFC7959].
If the option is not given, the peer has no information about whether If the option is not given, the peer has no information about whether
block-wise transfers are supported by the sender or not. An block-wise transfers are supported by the sender or not. An
implementation that supports block-wise transfers SHOULD indicate the implementation that supports block-wise transfers SHOULD indicate the
Block-wise Transfer Option. If a Max-Message-Size Option is Block-wise Transfer Option. If a Max-Message-Size Option is
indicated with a value that is greater than 1152 (in the same or a indicated with a value that is greater than 1152 (in the same or a
different CSM message), the Block-wise Transfer Option also indicates different CSM message), the Block-wise Transfer Option also indicates
support for BERT (see Section 5). support for BERT (see Section 5). Subsequently, if the Max-Message-
Size Option is indicated with a value equal or less than 1152, BERT
support is no longer indicated.
4.4. Ping and Pong Messages 4.4. Ping and Pong Messages
In CoAP over TCP, Empty messages (Code 0.00) can always be sent and In CoAP over reliable transports, Empty messages (Code 0.00) can
MUST be ignored by the recipient. This provides a basic keep-alive always be sent and MUST be ignored by the recipient. This provides a
function that can refresh NAT bindings. In contrast, Ping and Pong basic keep-alive function. In contrast, Ping and Pong messages are a
messages are a bidirectional exchange. bidirectional exchange.
Upon receipt of a Ping message, a single Pong message is returned Upon receipt of a Ping message, the receiver MUST return a Pong
with the identical token. As with all Signaling messages, the message with an identical token in response. Unless there is an
option with delaying semantics such as the Custody Option, it SHOULD
respond as soon as practical. As with all Signaling messages, the
recipient of a Ping or Pong message MUST ignore elective options it recipient of a Ping or Pong message MUST ignore elective options it
does not understand. does not understand.
Ping and Pong messages are indicated by the 7.02 code (Ping) and the Ping and Pong messages are indicated by the 7.02 code (Ping) and the
7.03 code (Pong). 7.03 code (Pong).
4.4.1. Custody Option 4.4.1. Custody Option
+---+---+---+----------+----------------+--------+--------+---------+
| # | C | R | Applies | Name | Format | Length | Base |
| | | | to | | | | Value |
+---+---+---+----------+----------------+--------+--------+---------+
| 2 | | | Ping, | Custody | empty | 0 | (none) |
| | | | Pong | | | | |
+---+---+---+----------+----------------+--------+--------+---------+
+--------+------------+---------+--------+--------+------------+ C=Critical, R=Repeatable
| Number | Applies to | Name | Format | Length | Base Value |
+--------+------------+---------+--------+--------+------------+
| 2 | Ping, Pong | Custody | empty | 0 | (none) |
+--------+------------+---------+--------+--------+------------+
A peer replying to a Ping message can add a Custody elective option When responding to a Ping message, the receiver can include an
to the Pong message it returns. This option indicates that the elective Custody Option in the Pong message. This option indicates
application has processed all request/response messages that it has that the application has processed all the request/response messages
received in the present connection ahead of the Ping message that received prior to the Ping message on the current connection. (Note
prompted the Pong message. (Note that there is no definition of that there is no definition of specific application semantics for
specific application semantics of "processed", but there is an "processed", but there is an expectation that the receiver of a Pong
expectation that the sender of the Ping leading to the Pong with a Message with a Custody Option should be able to free buffers based on
Custody Option should be able to free buffers based on this this indication.)
indication.)
A Custody elective option can also be sent in a Ping message to A sender can also include an elective Custody Option in a Ping
explicitly request the return of a Custody Option in the Pong message to explicitly request the inclusion of an elective Custody
message. A peer is always free to indicate that it has finished Option in the corresponding Pong message. The receiver SHOULD delay
processing all previous request/response messages by sending a its Pong message until it finishes processing all the request/
Custody Option in a Pong message. A peer is also free NOT to send a response messages received prior to the Ping message on the current
Custody Option in case it is still processing previous request/ connection.
response messages; however, it SHOULD delay its response to a Ping
with a Custody Option until it can also return one.
4.5. Release Messages 4.5. Release Messages
A release message indicates that the sender does not want to continue A Release message indicates that the sender does not want to continue
maintaining the connection and opts for an orderly shutdown; the maintaining the connection and opts for an orderly shutdown. The
details are in the options. A diagnostic payload MAY be included. A details are in the options. A diagnostic payload (see Section 5.5.2
release message will normally be replied to by the peer by closing of [RFC7252]) MAY be included. A peer will normally respond to a
the TCP/TLS connection. Messages may be in flight when the sender Release message by closing the TCP/TLS connection. Messages may be
decides to send a Release message. The general expectation is that in flight when the sender decides to send a Release message. The
these will still be processed. general expectation is that these will still be processed.
Release messages are indicated by the 7.04 code (Release). Release messages are indicated by the 7.04 code (Release).
Release messages can indicate one or more reasons using elective Release messages can indicate one or more reasons using elective
options. The following options are defined: options. The following options are defined:
+--------+-----------+-----------------+--------+--------+----------+ +---+---+---+---------+------------------+--------+--------+--------+
| Number | Applies | Name | Format | Length | Base | | # | C | R | Applies | Name | Format | Length | Base |
| | to | | | | Value | | | | | to | | | | Value |
+--------+-----------+-----------------+--------+--------+----------+ +---+---+---+---------+------------------+--------+--------+--------+
| 2 | Release | Bad-Server-Name | empty | 0 | (none) | | 2 | | x | Release | Alternative- | string | 1-255 | (none) |
+--------+-----------+-----------------+--------+--------+----------+ | | | | | Address | | | |
+---+---+---+---------+------------------+--------+--------+--------+
The Bad-Server-Name elective option indicates that the default
indicated by the CSM Server-Name Option is unlikely to be useful for
this server.
+--------+----------+-------------------+--------+--------+---------+ C=Critical, R=Repeatable
| Number | Applies | Name | Format | Length | Base |
| | to | | | | Value |
+--------+----------+-------------------+--------+--------+---------+
| 4 | Release | Alternate-Address | string | 1-255 | (none) |
+--------+----------+-------------------+--------+--------+---------+
The Alternative-Address elective option requests the peer to instead The elective Alternative-Address Option requests the peer to instead
open a connection of the same scheme as the present connection to the open a connection of the same scheme as the present connection to the
alternative transport address given. Its value is in the form alternative transport address given. Its value is in the form
"authority" as defined in Section 3.2 of [RFC3986]. "authority" as defined in Section 3.2 of [RFC3986].
+--------+------------+----------+--------+--------+------------+ The Alternative-Address Option is a repeatable option as defined in
| Number | Applies to | Name | Format | Length | Base Value | Section 5.4.5 of [RFC7252].
+--------+------------+----------+--------+--------+------------+
| 6 | Release | Hold-Off | uint | 0-3 | (none) |
+--------+------------+----------+--------+--------+------------+
The Hold-Off elective option indicates that the server is requesting +---+---+---+---------+-----------------+--------+--------+---------+
| # | C | R | Applies | Name | Format | Length | Base |
| | | | to | | | | Value |
+---+---+---+---------+-----------------+--------+--------+---------+
| 4 | | | Release | Hold-Off | uint | 0-3 | (none) |
+---+---+---+---------+-----------------+--------+--------+---------+
C=Critical, R=Repeatable
The elective Hold-Off Option indicates that the server is requesting
that the peer not reconnect to it for the number of seconds given in that the peer not reconnect to it for the number of seconds given in
the value. the value.
4.6. Abort Messages 4.6. Abort Messages
An abort message indicates that the sender is unable to continue An Abort message indicates that the sender is unable to continue
maintaining the connection and cannot even wait for an orderly maintaining the connection and cannot even wait for an orderly
release. The sender shuts down the connection immediately after the release. The sender shuts down the connection immediately after the
abort (and may or may not wait for a release or abort message or abort (and may or may not wait for a Release or Abort message or
connection shutdown in the inverse direction). A diagnostic payload connection shutdown in the inverse direction). A diagnostic payload
SHOULD be included in the Abort message. Messages may be in flight (see Section 5.5.2 of [RFC7252]) SHOULD be included in the Abort
when the sender decides to send an abort message. The general message. Messages may be in flight when the sender decides to send
expectation is that these will NOT be processed. an Abort message. The general expectation is that these will NOT be
processed.
Abort messages are indicated by the 7.05 code (Abort). Abort messages are indicated by the 7.05 code (Abort).
Abort messages can indicate one or more reasons using elective Abort messages can indicate one or more reasons using elective
options. The following option is defined: options. The following option is defined:
+--------+-----------+----------------+--------+--------+-----------+ +---+---+---+---------+-----------------+--------+--------+---------+
| Number | Applies | Name | Format | Length | Base | | # | C | R | Applies | Name | Format | Length | Base |
| | to | | | | Value | | | | | to | | | | Value |
+--------+-----------+----------------+--------+--------+-----------+ +---+---+---+---------+-----------------+--------+--------+---------+
| 2 | Abort | Bad-CSM-Option | uint | 0-2 | (none) | | 2 | | | Abort | Bad-CSM-Option | uint | 0-2 | (none) |
+--------+-----------+----------------+--------+--------+-----------+ +---+---+---+---------+-----------------+--------+--------+---------+
The Bad-CSM-Option Option indicates that the sender is unable to C=Critical, R=Repeatable
process the CSM option identified by its option number, e.g. when it
is critical and the option number is unknown by the sender, or when
there is parameter problem with the value of an elective option.
More detailed information SHOULD be included as a diagnostic payload.
One reason for an sender to generate an abort message is a general The elective Bad-CSM-Option Option indicates that the sender is
syntax error in the byte stream received. No specific option has unable to process the CSM option identified by its option number,
e.g. when it is critical and the option number is unknown by the
sender, or when there is parameter problem with the value of an
elective option. More detailed information SHOULD be included as a
diagnostic payload.
One reason for an sender to generate an Abort message is a general
syntax error in the byte-stream received. No specific option has
been defined for this, as the details of that syntax error are best been defined for this, as the details of that syntax error are best
left to a diagnostic payload. left to a diagnostic payload.
4.7. Capability and Settings examples 4.7. Signaling examples
An encoded example of a Ping message with a non-empty token is shown An encoded example of a Ping message with a non-empty token is shown
in Figure 15. in Figure 14.
0 1 2 0 1 2
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0x01 | 0xe2 | 0x42 | | 0x01 | 0xe2 | 0x42 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Len = 0 -------> 0x01 Len = 0 -------> 0x01
TKL = 1 ___/ TKL = 1 ___/
Code = 7.02 Ping --> 0xe2 Code = 7.02 Ping --> 0xe2
Token = 0x42 Token = 0x42
Figure 15: Ping Message Example Figure 14: Ping Message Example
An encoded example of the corresponding Pong message is shown in An encoded example of the corresponding Pong message is shown in
Figure 16. Figure 15.
0 1 2 0 1 2
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0x01 | 0xe3 | 0x42 | | 0x01 | 0xe3 | 0x42 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Len = 0 -------> 0x01 Len = 0 -------> 0x01
TKL = 1 ___/ TKL = 1 ___/
Code = 7.03 Pong --> 0xe3 Code = 7.03 Pong --> 0xe3
Token = 0x42 Token = 0x42
Figure 16: Pong Message Example Figure 15: Pong Message Example
5. Block-wise Transfer and Reliable Transports 5. Block-wise Transfer and Reliable Transports
The message size restrictions defined in Section 4.6 of CoAP The message size restrictions defined in Section 4.6 of CoAP
[RFC7252] to avoid IP fragmentation are not necessary when CoAP is [RFC7252] to avoid IP fragmentation are not necessary when CoAP is
used over a reliable byte stream transport. While this suggests that used over a reliable transport. While this suggests that the Block-
the Block-wise transfer protocol [RFC7959] is also no longer needed, wise transfer protocol [RFC7959] is also no longer needed, it remains
it remains applicable for a number of cases: applicable for a number of cases:
o large messages, such as firmware downloads, may cause undesired o large messages, such as firmware downloads, may cause undesired
head-of-line blocking when a single TCP connection is used head-of-line blocking when a single TCP connection is used
o a UDP-to-TCP gateway may simply not have the context to convert a o a UDP-to-TCP gateway may simply not have the context to convert a
message with a Block Option into the equivalent exchange without message with a Block Option into the equivalent exchange without
any use of a Block Option (it would need to convert the entire any use of a Block Option (it would need to convert the entire
blockwise exchange from start to end into a single exchange) blockwise exchange from start to end into a single exchange)
The 'Block-wise Extension for Reliable Transport (BERT)' extends the The 'Block-wise Extension for Reliable Transport (BERT)' extends the
skipping to change at page 23, line 18 skipping to change at page 23, line 33
In all these examples, a Block Option is decomposed to indicate the In all these examples, a Block Option is decomposed to indicate the
kind of Block Option (1 or 2) followed by a colon, the block number kind of Block Option (1 or 2) followed by a colon, the block number
(NUM), more bit (M), and block size exponent (2**(SZX+4)) separated (NUM), more bit (M), and block size exponent (2**(SZX+4)) separated
by slashes. E.g., a Block2 Option value of 33 would be shown as by slashes. E.g., a Block2 Option value of 33 would be shown as
2:2/0/32), or a Block1 Option value of 59 would be shown as 2:2/0/32), or a Block1 Option value of 59 would be shown as
1:3/1/128. 1:3/1/128.
5.1. Example: GET with BERT Blocks 5.1. Example: GET with BERT Blocks
Figure 17 shows a GET request with a response that is split into Figure 16 shows a GET request with a response that is split into
three BERT blocks. The first response contains 3072 bytes of three BERT blocks. The first response contains 3072 bytes of
payload; the second, 5120; and the third, 4711. Note how the block payload; the second, 5120; and the third, 4711. Note how the block
number increments to move the position inside the response body number increments to move the position inside the response body
forward. forward.
CLIENT SERVER CoAP Client CoAP Server
| | | |
| GET, /status ------> | | GET, /status ------> |
| | | |
| <------ 2.05 Content, 2:0/1/BERT(3072) | | <------ 2.05 Content, 2:0/1/BERT(3072) |
| | | |
| GET, /status, 2:3/0/BERT ------> | | GET, /status, 2:3/0/BERT ------> |
| | | |
| <------ 2.05 Content, 2:3/1/BERT(5120) | | <------ 2.05 Content, 2:3/1/BERT(5120) |
| | | |
| GET, /status, 2:8/0/BERT ------> | | GET, /status, 2:8/0/BERT ------> |
| | | |
| <------ 2.05 Content, 2:8/0/BERT(4711) | | <------ 2.05 Content, 2:8/0/BERT(4711) |
Figure 17: GET with BERT blocks. Figure 16: GET with BERT blocks
5.2. Example: PUT with BERT Blocks 5.2. Example: PUT with BERT Blocks
Figure 18 demonstrates a PUT exchange with BERT blocks. Figure 17 demonstrates a PUT exchange with BERT blocks.
CLIENT SERVER CoAP Client CoAP Server
| | | |
| PUT, /options, 1:0/1/BERT(8192) ------> | | PUT, /options, 1:0/1/BERT(8192) ------> |
| | | |
| <------ 2.31 Continue, 1:0/1/BERT | | <------ 2.31 Continue, 1:0/1/BERT |
| | | |
| PUT, /options, 1:8/1/BERT(16384) ------> | | PUT, /options, 1:8/1/BERT(16384) ------> |
| | | |
| <------ 2.31 Continue, 1:8/1/BERT | | <------ 2.31 Continue, 1:8/1/BERT |
| | | |
| PUT, /options, 1:24/0/BERT(5683) ------> | | PUT, /options, 1:24/0/BERT(5683) ------> |
| | | |
| <------ 2.04 Changed, 1:24/0/BERT | | <------ 2.04 Changed, 1:24/0/BERT |
| | | |
Figure 18: PUT with BERT blocks. Figure 17: PUT with BERT blocks
6. CoAP URIs 6. CoAP over Reliable Transport URIs
CoAP over UDP [RFC7252] defines the "coap" and "coaps" URI schemes CoAP over UDP [RFC7252] defines the "coap" and "coaps" URI schemes.
for identifying CoAP resources and providing a means of locating the This document introduces four additional URI schemes for identifying
resource. CoAP resources and providing a means of locating the resource:
6.1. CoAP over TCP and TLS URIs o the "coap+tcp" URI scheme for CoAP over TCP
CoAP over TCP uses the "coap+tcp" URI scheme. CoAP over TLS uses the o the "coaps+tcp" URI scheme for CoAP over TCP secured by TLS
"coaps+tcp" scheme. The rules from Section 6 of [RFC7252] apply to
both of these URI schemes.
[RFC7252], Section 8 (Multicast CoAP) is not applicable to these o the "coap+ws" URI scheme for CoAP over WebSockets
o the "coaps+ws" URI scheme for CoAP over WebSockets secured by TLS
Resources made available via these schemes have no shared identity
even if their resource identifiers indicate the same authority (the
same host listening to the same TCP port). They are distinct
namespaces and are considered to be distinct origin servers.
The syntax for the URI schemes in this section are specified using
Augmented Backus-Naur Form (ABNF) [RFC5234]. The definitions of
"host", "port", "path-abempty", and "query" are adopted from
[RFC3986].
Section 8 (Multicast CoAP) in [RFC7252] is not applicable to these
schemes. schemes.
Resources made available via one of the "coap+tcp" or "coaps+tcp" 6.1. coap+tcp URI scheme
schemes have no shared identity with the other scheme or with the
"coap" or "coaps" scheme, even if their resource identifiers indicate
the same authority (the same host listening to the same port). The
schemes constitute distinct namespaces and, in combination with the
authority, are considered to be distinct origin servers.
6.1.1. coap+tcp URI scheme The "coap+tcp" URI scheme identifies CoAP resources that are intended
to be accessible using CoAP over TCP.
coap-tcp-URI = "coap+tcp:" "//" host [ ":" port ] path-abempty coap+tcp-URI =
[ "?" query ] "coap+tcp:" "//" host [ ":" port ] path-abempty [ "?" query ]
The semantics defined in [RFC7252], Section 6.1, apply to this URI The syntax defined in Section 6.1 of [RFC7252] applies to this URI
scheme, with the following changes: scheme with the following changes:
o The port subcomponent indicates the TCP port at which the CoAP o The port subcomponent indicates the TCP port at which the CoAP
server is located. (If it is empty or not given, then the default server is located. (If it is empty or not given, then the default
port 5683 is assumed, as with UDP.) port 5683 is assumed, as with UDP.)
6.1.2. coaps+tcp URI scheme Encoding considerations: The scheme encoding conforms to the
encoding rules established for URIs in [RFC3986].
coaps-tcp-URI = "coaps+tcp:" "//" host [ ":" port ] path-abempty Interoperability considerations: None.
[ "?" query ]
The semantics defined in [RFC7252], Section 6.2, apply to this URI Security considerations: See Section 11.1 of [RFC7252].
6.2. coaps+tcp URI scheme
The "coaps+tcp" URI scheme identifies CoAP resources that are
intended to be accessible using CoAP over TCP secured with TLS.
coaps+tcp-URI =
"coaps+tcp:" "//" host [ ":" port ] path-abempty [ "?" query ]
The syntax defined in Section 6.2 of [RFC7252] applies to this URI
scheme, with the following changes: scheme, with the following changes:
o The port subcomponent indicates the TCP port at which the TLS o The port subcomponent indicates the TCP port at which the TLS
server for the CoAP server is located. If it is empty or not server for the CoAP server is located. If it is empty or not
given, then the default port 443 is assumed (this is different given, then the default port 443 is assumed (this is different
from the default port for "coaps", i.e., CoAP over DTLS over UDP). from the default port for "coaps", i.e., CoAP over DTLS over UDP).
o If a server does not support the Application-Layer Protocol o If a TLS server does not support the Application-Layer Protocol
Negotiation Extension (ALPN) [RFC7301] or wishes to accommodate Negotiation Extension (ALPN) [RFC7301] or wishes to accommodate
clients that do not support ALPN, it MAY offer a coaps+tcp TLS clients that do not support ALPN, it MAY offer a coaps+tcp
endpoint on TCP port 5684. This endpoint MAY also be ALPN endpoint on TCP port 5684. This endpoint MAY also be ALPN
enabled. A server MAY offer coaps+tcp endpoints on ports other enabled. A TLS server MAY offer coaps+tcp endpoints on ports
than TCP port 5684, which MUST be ALPN enabled. other than TCP port 5684, which MUST be ALPN enabled.
o For TCP ports other than port 5684, the client MUST use the ALPN o For TCP ports other than port 5684, the TLS client MUST use the
extension to advertise the "coap" protocol identifier (see ALPN extension to advertise the "coap" protocol identifier (see
Section 8.7) in the list of protocols in its ClientHello. If the Section 9.7) in the list of protocols in its ClientHello. If the
server selects and returns the "coap" protocol identifier using TCP server selects and returns the "coap" protocol identifier
the ALPN extension in its ServerHello, then the connection using the ALPN extension in its ServerHello, then the connection
succeeds. If the server either does not negotiate the ALPN succeeds. If the TLS server either does not negotiate the ALPN
extension or returns a no_application_protocol alert, the client extension or returns a no_application_protocol alert, the TLS
MUST close the connection. client MUST close the connection.
o For TCP port 5684, a client MAY use the ALPN extension to o For TCP port 5684, a TLS client MAY use the ALPN extension to
advertise the "coap" protocol identifier in the list of protocols advertise the "coap" protocol identifier in the list of protocols
in its ClientHello. If the server selects and returns the "coap" in its ClientHello. If the TLS server selects and returns the
protocol identifier using the ALPN extension in its ServerHello, "coap" protocol identifier using the ALPN extension in its
then the connection succeeds. If the server returns a ServerHello, then the connection succeeds. If the TLS server
no_application_protocol alert, then the client MUST close the returns a no_application_protocol alert, then the TLS client MUST
connection. If the server does not negotiate the ALPN extension, close the connection. If the TLS server does not negotiate the
then coaps+tcp is implicitly selected. ALPN extension, then coaps+tcp is implicitly selected.
o For TCP port 5684, if the client does not use the ALPN extension o For TCP port 5684, if the TLS client does not use the ALPN
to negotiate the protocol, then coaps+tcp is implicitly selected. extension to negotiate the protocol, then coaps+tcp is implicitly
selected.
6.2. CoAP over WebSockets URIs Encoding considerations: The scheme encoding conforms to the
encoding rules established for URIs in [RFC3986].
For the first configuration discussed in Section 3, this document Interoperability considerations: None.
defines two new URIs schemes that can be used for identifying CoAP
resources and providing a means of locating these resources:
"coap+ws" and "coap+wss".
Similar to the "coap" and "coaps" schemes, the "coap+ws" and Security considerations: See Section 11.1 of [RFC7252].
"coap+wss" schemes organize resources hierarchically under a CoAP
origin server. The key difference is that the server is potentially
reachable on a WebSocket endpoint instead of a UDP endpoint.
The WebSocket endpoint is identified by a "ws" or "wss" URI that is 6.3. coap+ws URI scheme
composed of the authority part of the "coap+ws" or "coap+wss" URI,
respectively, and the well-known path "/.well-known/coap" [RFC5785].
The path and query parts of a "coap+ws" or "coap+wss" URI identify a
resource within the specified endpoint which can be operated on by
the methods defined by CoAP.
The syntax of the "coap+ws" and "coap+wss" URI schemes is specified The "coap+ws" URI scheme identifies CoAP resources that are intended
below in Augmented Backus-Naur Form (ABNF) [RFC5234]. The to be accessible using CoAP over WebSockets.
definitions of "host", "port", "path-abempty" and "query" are the
same as in [RFC3986].
coap-ws-URI = coap-ws-URI =
"coap+ws:" "//" host [ ":" port ] path-abempty [ "?" query ] "coap+ws:" "//" host [ ":" port ] path-abempty [ "?" query ]
coap-wss-URI = The port component is OPTIONAL. The default is port 80.
"coap+wss:" "//" host [ ":" port ] path-abempty [ "?" query ]
The port component is OPTIONAL; the default for "coap+ws" is port 80, The WebSocket endpoint is identified by a "ws" URI that is composed
while the default for "coap+wss" is port 443. of the authority part of the "coap+ws" URI and the well-known path
"/.well-known/coap" [RFC5785]. The path and query parts of a
"coap+ws" URI identify a resource within the specified endpoint which
can be operated on by the methods defined by CoAP:
Fragment identifiers are not part of the request URI and thus MUST coap+ws://example.org/sensors/temperature?u=Cel
NOT be transmitted in a WebSocket handshake or in the URI options of \______ ______/\___________ ___________/
a CoAP request. \/ \/
Uri-Path: "sensors"
ws://example.org/.well-known/coap Uri-Path: "temperature"
Uri-Query: "u=Cel"
6.2.1. Decomposing and Composing URIs Figure 18: The "coap+ws" URI Scheme
The steps for decomposing a "coap+ws" or "coap+wss" URI into CoAP Encoding considerations: The scheme encoding conforms to the
options are the same as specified in Section 6.4 of [RFC7252] with encoding rules established for URIs in [RFC3986].
Interoperability considerations: None.
Security considerations: See Section 11.1 of [RFC7252].
6.4. coaps+ws URI scheme
The "coaps+ws" URI scheme identifies CoAP resources that are intended
to be accessible using CoAP over WebSockets secured by TLS.
coaps-ws-URI =
"coaps+ws:" "//" host [ ":" port ] path-abempty [ "?" query ]
The port component is OPTIONAL. The default is port 443.
The WebSocket endpoint is identified by a "wss" URI that is composed
of the authority part of the "coaps+ws" URI and the well-known path
"/.well-known/coap" [RFC5785]. The path and query parts of a
"coaps+ws" URI identify a resource within the specified endpoint
which can be operated on by the methods defined by CoAP.
coaps+ws://example.org/sensors/temperature?u=Cel
\______ ______/\___________ ___________/
\/ \/
Uri-Path: "sensors"
wss://example.org/.well-known/coap Uri-Path: "temperature"
Uri-Query: "u=Cel"
Figure 19: The "coaps+ws" URI Scheme
Encoding considerations: The scheme encoding conforms to the
encoding rules established for URIs in [RFC3986].
Interoperability considerations: None.
Security considerations: See Section 11.1 of [RFC7252].
6.5. Uri-Host and Uri-Port Options
CoAP over reliable transports maintains the property from
Section 5.10.1 of [RFC7252]:
The default values for the Uri-Host and Uri-Port Options are
sufficient for requests to most servers.
Unless otherwise noted, the default value of the Uri-Host Option is
the IP literal representing the destination IP address of the request
message. The default value of the Uri-Port Option is the destination
TCP port.
For CoAP over TLS, these default values are the same unless Server
Name Indication (SNI) [RFC6066] is negotiated. In this case, the
default value of the Uri-Host Option in requests from the TLS client
to the TLS server is the SNI host.
For CoAP over WebSockets, the default value of the Uri-Host Option in
requests from the WebSocket client to the WebSocket server is
indicated by the Host header field from the WebSocket handshake.
6.6. Decomposing URIs into Options
The steps are the same as specified in Section 6.4 of [RFC7252] with
the following changes: the following changes:
o The <scheme> component MUST be "coap+ws" or "coap+wss" when 3. If |url| does not have a <scheme> component whose value, when
converted to ASCII lowercase. converted to ASCII lowercase, is "coap" or "coaps", then fail
this algorithm.
o A Uri-Host Option MUST only be included in a request when the If |url| does not have a <scheme> component whose value, when
<host> component does not equal the uri-host component in the Host converted to ASCII lowercase, is "coap+tcp", "coaps+tcp", "coap+ws",
header field in the WebSocket handshake. or "coaps+ws" then fail this algorithm.
o A Uri-Port Option MUST only be included in a request if |port| 7. If |port| does not equal the request's destination UDP port,
does not equal the port component in the Host header field in the include a Uri-Port Option and let that option's value be |port|.
WebSocket handshake.
The steps to construct a URI from a request's options are changed If |port| does not equal the request's destination TCP port, include
accordingly. a Uri-Port Option and let that option's value be |port|.
7. Security Considerations 6.7. Composing URIs from Options
The security considerations of [RFC7252] apply. The steps are the same as specified in Section 6.5 of [RFC7252] with
the following changes:
TLS version 1.2 or higher is mandatory-to-implement and MUST be 1. If the request is secured using DTLS, let |url| be the string
enabled by default. An endpoint MAY immediately abort a CoAP over "coaps://". Otherwise, let |url| be the string "coap://".
TLS connection that does not meet this requirement (see Section 4.6)
and SHOULD include a diagnostic payload.
The TLS usage guidance in [RFC7925] SHOULD be followed. For CoAP over TCP, if the request is secured using TLS, let |url| be
the string "coaps+tcp://". Otherwise, let |url| be the string
"coap+tcp://". For CoAP over WebSockets, if the request is secured
using TLS, let |url| be the string "coaps+ws://". Otherwise,
let |url| be the string "coap+ws://".
TLS does not protect the TCP header. This may, for example, allow an 4. If the request includes a Uri-Port Option, let |port| be that
on-path adversary to terminate a TCP connection prematurely by option's value. Otherwise, let |port| be the request's
spoofing a TCP reset message. destination UDP port.
CoAP over WebSockets and CoAP over TLS-secured WebSockets do not If the request includes a Uri-Port Option, let |port| be that
introduce additional security issues beyond CoAP and DTLS-secured option's value. Otherwise, let |port| be the request's destination
CoAP respectively [RFC7252]. The security considerations of TCP port.
[RFC6455] apply.
7.1. Signaling Messages 7. Securing CoAP
Security Challenges for the Internet of Things [SecurityChallenges]
recommends:
... it is essential that IoT protocol suites specify a mandatory
to implement but optional to use security solution. This will
ensure security is available in all implementations, but
configurable to use when not necessary (e.g., in closed
environment). ... even if those features stretch the capabilities
of such devices.
A security solution MUST be implemented to protect CoAP over reliable
transports and MUST be enabled by default. This document defines the
TLS binding, but alternative solutions at different layers in the
protocol stack MAY be used to protect CoAP over reliable transports
when appropriate. Note that there is ongoing work to support a data
object-based security model for CoAP that is independent of transport
(see [I-D.ietf-core-object-security]).
7.1. TLS binding for CoAP over TCP
The TLS usage guidance in [RFC7925] applies.
During the provisioning phase, a CoAP device is provided with the
security information that it needs, including keying materials,
access control lists, and authorization servers. At the end of the
provisioning phase, the device will be in one of four security modes:
NoSec: TLS is disabled.
PreSharedKey: TLS is enabled. The guidance in Section 4.2 of
[RFC7925] applies.
RawPublicKey: TLS is enabled. The guidance in Section 4.3 of
[RFC7925] applies.
Certificate: TLS is enabled. The guidance in Section 4.4 of
[RFC7925] applies.
The "NoSec" mode is mandatory-to-implement. The system simply sends
the packets over normal TCP which is indicated by the "coap+tcp"
scheme and the TCP CoAP default port. The system is secured only by
keeping attackers from being able to send or receive packets from the
network with the CoAP nodes.
"PreSharedKey", "RawPublicKey", or "Certificate" is mandatory-to-
implement for the TLS binding depending on the credential type used
with the device. These security modes are achieved using TLS and are
indicated by the "coaps+tcp" scheme and TLS-secured CoAP default
port.
7.2. TLS usage for CoAP over WebSockets
A CoAP client requesting a resource identified by a "coaps+ws" URI
negotiates a secure WebSocket connection to a WebSocket server
endpoint with a "wss" URI. This is described in Section 6.4.
The client MUST perform a TLS handshake after opening the connection
to the server. The guidance in Section 4.1 of [RFC6455] applies.
When a CoAP server exposes resources identified by a "coaps+ws" URI,
the guidance in Section 4.4 of [RFC7925] applies towards mandatory-
to-implement TLS functionality for certificates. For the server-side
requirements in accepting incoming connections over a HTTPS (HTTP-
over-TLS) port, the guidance in Section 4.2 of [RFC6455] applies.
8. Security Considerations
The security considerations of [RFC7252] apply. For CoAP over
WebSockets and CoAP over TLS-secured WebSockets, the security
considerations of [RFC6455] also apply.
8.1. Signaling Messages
o The guidance given by an Alternative-Address Option cannot be o The guidance given by an Alternative-Address Option cannot be
followed blindly. In particular, a peer MUST NOT assume that a followed blindly. In particular, a peer MUST NOT assume that a
successful connection to the Alternative-Address inherits all the successful connection to the Alternative-Address inherits all the
security properties of the current connection. security properties of the current connection.
o SNI vs. Server-Name: Any security negotiated in the TLS handshake 9. IANA Considerations
is for the SNI name exchanged in the TLS handshake and checked
against the certificate provided by the server. The Server-Name
Option cannot be used to extend these security properties to the
additional server name.
8. IANA Considerations
8.1. Signaling Codes 9.1. Signaling Codes
IANA is requested to create a third sub-registry for values of the IANA is requested to create a third sub-registry for values of the
Code field in the CoAP header (Section 12.1 of [RFC7252]). The name Code field in the CoAP header (Section 12.1 of [RFC7252]). The name
of this sub-registry is "CoAP Signaling Codes". of this sub-registry is "CoAP Signaling Codes".
Each entry in the sub-registry must include the Signaling Code in the Each entry in the sub-registry must include the Signaling Code in the
range 7.01-7.31, its name, and a reference to its documentation. range 7.00-7.31, its name, and a reference to its documentation.
Initial entries in this sub-registry are as follows: Initial entries in this sub-registry are as follows:
+------+---------+-----------+ +------+---------+-----------+
| Code | Name | Reference | | Code | Name | Reference |
+------+---------+-----------+ +------+---------+-----------+
| 7.01 | CSM | [RFCthis] | | 7.01 | CSM | [RFCthis] |
| | | | | | | |
| 7.02 | Ping | [RFCthis] | | 7.02 | Ping | [RFCthis] |
| | | | | | | |
skipping to change at page 28, line 39 skipping to change at page 31, line 46
| 7.05 | Abort | [RFCthis] | | 7.05 | Abort | [RFCthis] |
+------+---------+-----------+ +------+---------+-----------+
Table 1: CoAP Signal Codes Table 1: CoAP Signal Codes
All other Signaling Codes are Unassigned. All other Signaling Codes are Unassigned.
The IANA policy for future additions to this sub-registry is "IETF The IANA policy for future additions to this sub-registry is "IETF
Review or IESG Approval" as described in [RFC5226]. Review or IESG Approval" as described in [RFC5226].
8.2. CoAP Signaling Option Numbers Registry 9.2. CoAP Signaling Option Numbers Registry
IANA is requested to create a sub-registry for signaling options IANA is requested to create a sub-registry for Options Numbers used
similar to the CoAP Option Numbers Registry (Section 12.2 of in CoAP signaling options within the "CoRE Parameters" registry. The
[RFC7252]), with the single change that a fourth column is added to name of this sub-registry is "CoAP Signaling Option Numbers".
the sub-registry that is one of the codes in the Signaling Codes
subregistry (Section 8.1).
The name of this sub-registry is "CoAP Signaling Option Numbers". Each entry in the sub-registry must include one or more of the codes
in the Signaling Codes subregistry (Section 9.1), the option number,
the name of the option, and a reference to the option's
documentation.
Initial entries in this sub-registry are as follows: Initial entries in this sub-registry are as follows:
+--------+------------+---------------------+-----------+ +------------+--------+---------------------+-----------+
| Number | Applies to | Name | Reference | | Applies to | Number | Name | Reference |
+--------+------------+---------------------+-----------+ +------------+--------+---------------------+-----------+
| 1 | CSM | Server-Name | [RFCthis] | | 7.01 | 2 | Max-Message-Size | [RFCthis] |
| | | | | | | | | |
| 2 | CSM | Max-Message-Size | [RFCthis] | | 7.01 | 4 | Block-wise-Transfer | [RFCthis] |
| | | | | | | | | |
| 4 | CSM | Block-wise-Transfer | [RFCthis] | | 7.02, 7.03 | 2 | Custody | [RFCthis] |
| | | | | | | | | |
| 2 | Ping, Pong | Custody | [RFCthis] | | 7.04 | 2 | Alternative-Address | [RFCthis] |
| | | | | | | | | |
| 2 | Release | Bad-Server-Name | [RFCthis] | | 7.04 | 4 | Hold-Off | [RFCthis] |
| | | | | | | | | |
| 4 | Release | Alternative-Address | [RFCthis] | | 7.05 | 2 | Bad-CSM-Option | [RFCthis] |
| | | | | +------------+--------+---------------------+-----------+
| 6 | Release | Hold-Off | [RFCthis] |
| | | | |
| 2 | Abort | Bad-CSM-Option | [RFCthis] |
+--------+------------+---------------------+-----------+
Table 2: CoAP Signal Option Codes Table 2: CoAP Signal Option Codes
The IANA policy for future additions to this sub-registry is based on The IANA policy for future additions to this sub-registry is based on
number ranges for the option numbers, analogous to the policy defined number ranges for the option numbers, analogous to the policy defined
in Section 12.2 of [RFC7252]. in Section 12.2 of [RFC7252].
8.3. Service Name and Port Number Registration The documentation for a Signaling Option Number should specify the
semantics of an option with that number, including the following
properties:
o Whether the option is critical or elective, as determined by the
Option Number.
o Whether the option is repeatable.
o The format and length of the option's value.
o The base value for the option, if any.
9.3. Service Name and Port Number Registration
IANA is requested to assign the port number 5683 and the service name IANA is requested to assign the port number 5683 and the service name
"coap+tcp", in accordance with [RFC6335]. "coap+tcp", in accordance with [RFC6335].
Service Name. Service Name.
coap+tcp coap+tcp
Transport Protocol. Transport Protocol.
tcp tcp
Assignee. Assignee.
IESG <iesg@ietf.org> IESG <iesg@ietf.org>
Contact. Contact.
IETF Chair <chair@ietf.org> IETF Chair <chair@ietf.org>
skipping to change at page 30, line 8 skipping to change at page 33, line 25
Description. Description.
Constrained Application Protocol (CoAP) Constrained Application Protocol (CoAP)
Reference. Reference.
[RFCthis] [RFCthis]
Port Number. Port Number.
5683 5683
8.4. Secure Service Name and Port Number Registration 9.4. Secure Service Name and Port Number Registration
IANA is requested to assign the port number 5684 and the service name IANA is requested to assign the port number 5684 and the service name
"coaps+tcp", in accordance with [RFC6335]. The port number is "coaps+tcp", in accordance with [RFC6335]. The port number is
requested to address the exceptional case of TLS implementations that requested to address the exceptional case of TLS implementations that
do not support the "Application-Layer Protocol Negotiation Extension" do not support the "Application-Layer Protocol Negotiation Extension"
[RFC7301]. [RFC7301].
Service Name. Service Name.
coaps+tcp coaps+tcp
skipping to change at page 30, line 37 skipping to change at page 34, line 5
Description. Description.
Constrained Application Protocol (CoAP) Constrained Application Protocol (CoAP)
Reference. Reference.
[RFC7301], [RFCthis] [RFC7301], [RFCthis]
Port Number. Port Number.
5684 5684
8.5. URI Scheme Registration 9.5. URI Scheme Registration
This document registers two new URI schemes, namely "coap+tcp" and URI schemes are registered within the "Uniform Resource Identifier
"coaps+tcp", for the use of CoAP over TCP and for CoAP over TLS over (URI) Schemes" registry maintained at
TCP, respectively. The "coap+tcp" and "coaps+tcp" URI schemes can http://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml .
thus be compared to the "http" and "https" URI schemes.
The syntax of the "coap" and "coaps" URI schemes is specified in 9.5.1. coap+tcp
Section 6 of [RFC7252] and the present document re-uses their
semantics for "coap+tcp" and "coaps+tcp", respectively, with the
exception that TCP, or TLS over TCP is used as a transport protocol.
IANA is requested to add these new URI schemes to the registry IANA is requested to register the Uniform Resource Identifier (URI)
established with [RFC7595]. scheme "coap+tcp". This registration request complies with
[RFC7595].
8.5.1. coap+ws Scheme name:
coap+tcp
This document requests the registration of the Uniform Resource Status:
Identifier (URI) scheme "coap+ws". The registration request complies Permanent
with [RFC4395].
URL scheme name. Applications/protocols that use this scheme name:
coap+ws The scheme is used by CoAP endpoints to access CoAP resources
using TCP.
Status. Contact:
Permanent IETF chair <chair@ietf.org>
URI scheme syntax. Change controller:
Defined in Section N of [RFCthis] IESG <iesg@ietf.org>
URI scheme semantics. Reference:
The "coap+ws" URI scheme provides a way to identify resources that Section 6.1 in [RFCthis]
are potentially accessible over the Constrained Application
Protocol (CoAP) using the WebSocket protocol.
Encoding considerations. 9.5.2. coaps+tcp
The scheme encoding conforms to the encoding rules established for
URIs in [RFC3986], i.e., internationalized and reserved characters
are expressed using UTF-8-based percent-encoding.
Applications/protocols that use this URI scheme name. IANA is requested to register the Uniform Resource Identifier (URI)
The scheme is used by CoAP endpoints to access CoAP resources scheme "coaps+tcp". This registration request complies with
using the WebSocket protocol. [RFC7595].
Interoperability considerations. Scheme name:
None. coaps+tcp
Security Considerations. Status:
See Section N of [RFCthis] Permanent
Applications/protocols that use this scheme name:
The scheme is used by CoAP endpoints to access CoAP resources
using TLS.
Contact:
Contact.
IETF chair <chair@ietf.org> IETF chair <chair@ietf.org>
Author/Change controller. Change controller:
IESG <iesg@ietf.org> IESG <iesg@ietf.org>
References. Reference:
[RFCthis] Section 6.2 in [RFCthis]
8.5.2. coap+wss 9.5.3. coap+ws
This document requests the registration of the Uniform Resource IANA is requested to register the Uniform Resource Identifier (URI)
Identifier (URI) scheme "coap+wss". The registration request scheme "coap+ws". This registration request complies with [RFC7595].
complies with [RFC4395].
URL scheme name. Scheme name:
coap+wss coap+ws
Status. Status:
Permanent Permanent
URI scheme syntax. Applications/protocols that use this scheme name:
Defined in Section N of [RFCthis] The scheme is used by CoAP endpoints to access CoAP resources
using the WebSocket protocol.
URI scheme semantics. Contact:
The "coap+ws" URI scheme provides a way to identify resources that IETF chair <chair@ietf.org>
are potentially accessible over the Constrained Application
Protocol (CoAP) using the WebSocket protocol secured with
Transport Layer Security (TLS).
Encoding considerations. Change controller:
The scheme encoding conforms to the encoding rules established for IESG <iesg@ietf.org>
URIs in [RFC3986], i.e., internationalized and reserved characters
are expressed using UTF-8-based percent-encoding.
Applications/protocols that use this URI scheme name. Reference:
The scheme is used by CoAP endpoints to access CoAP resources Section 6.3 in [RFCthis]
using the WebSocket protocol secured with TLS.
Interoperability considerations. 9.5.4. coaps+ws
None.
Security Considerations. IANA is requested to register the Uniform Resource Identifier (URI)
See Section N of [RFCthis] scheme "coaps+ws". This registration request complies with
[RFC7595].
Contact. Scheme name:
coaps+ws
Status:
Permanent
Applications/protocols that use this scheme name:
The scheme is used by CoAP endpoints to access CoAP resources
using the WebSocket protocol secured with TLS.
Contact:
IETF chair <chair@ietf.org> IETF chair <chair@ietf.org>
Author/Change controller. Change controller:
IESG <iesg@ietf.org> IESG <iesg@ietf.org>
References. References:
[RFCthis] Section 6.4 in [RFCthis]
8.6. Well-Known URI Suffix Registration 9.6. Well-Known URI Suffix Registration
IANA is requested to register the 'coap' well-known URI in the "Well- IANA is requested to register the 'coap' well-known URI in the "Well-
Known URIs" registry. This registration request complies with Known URIs" registry. This registration request complies with
[RFC5785]: [RFC5785]:
URI Suffix. URI Suffix.
coap coap
Change controller. Change controller.
IETF IETF
Specification document(s). Specification document(s).
[RFCthis] [RFCthis]
Related information. Related information.
None. None.
8.7. ALPN Protocol Identifier 9.7. ALPN Protocol Identifier
IANA is requested to assign the following value in the registry IANA is requested to assign the following value in the registry
"Application Layer Protocol Negotiation (ALPN) Protocol IDs" created "Application Layer Protocol Negotiation (ALPN) Protocol IDs" created
by [RFC7301]. The "coap" string identifies CoAP when used over TLS. by [RFC7301]. The "coap" string identifies CoAP when used over TLS.
Protocol. Protocol.
CoAP CoAP
Identification Sequence. Identification Sequence.
0x63 0x6f 0x61 0x70 ("coap") 0x63 0x6f 0x61 0x70 ("coap")
Reference. Reference.
[RFCthis] [RFCthis]
8.8. WebSocket Subprotocol Registration 9.8. WebSocket Subprotocol Registration
IANA is requested to register the WebSocket CoAP subprotocol under IANA is requested to register the WebSocket CoAP subprotocol under
the "WebSocket Subprotocol Name Registry": the "WebSocket Subprotocol Name Registry":
Subprotocol Identifier. Subprotocol Identifier.
coap coap
Subprotocol Common Name. Subprotocol Common Name.
Constrained Application Protocol (CoAP) Constrained Application Protocol (CoAP)
Subprotocol Definition. Subprotocol Definition.
[RFCthis] [RFCthis]
9. References 10. References
9.1. Normative References 10.1. Normative References
[RFC0793] Postel, J., "Transmission Control Protocol", STD 7, RFC [RFC0793] Postel, J., "Transmission Control Protocol", STD 7,
793, DOI 10.17487/RFC0793, September 1981, RFC 793, DOI 10.17487/RFC0793, September 1981,
<http://www.rfc-editor.org/info/rfc793>. <http://www.rfc-editor.org/info/rfc793>.
[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, DOI 10.17487/ Requirement Levels", BCP 14, RFC 2119,
RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>. <http://www.rfc-editor.org/info/rfc2119>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC Resource Identifier (URI): Generic Syntax", STD 66,
3986, DOI 10.17487/RFC3986, January 2005, RFC 3986, DOI 10.17487/RFC3986, January 2005,
<http://www.rfc-editor.org/info/rfc3986>. <http://www.rfc-editor.org/info/rfc3986>.
[RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and
Registration Procedures for New URI Schemes", RFC 4395,
DOI 10.17487/RFC4395, February 2006,
<http://www.rfc-editor.org/info/rfc4395>.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226, IANA Considerations Section in RFCs", BCP 26, RFC 5226,
DOI 10.17487/RFC5226, May 2008, DOI 10.17487/RFC5226, May 2008,
<http://www.rfc-editor.org/info/rfc5226>. <http://www.rfc-editor.org/info/rfc5226>.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/ (TLS) Protocol Version 1.2", RFC 5246,
RFC5246, August 2008, DOI 10.17487/RFC5246, August 2008,
<http://www.rfc-editor.org/info/rfc5246>. <http://www.rfc-editor.org/info/rfc5246>.
[RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
Uniform Resource Identifiers (URIs)", RFC 5785, DOI Uniform Resource Identifiers (URIs)", RFC 5785,
10.17487/RFC5785, April 2010, DOI 10.17487/RFC5785, April 2010,
<http://www.rfc-editor.org/info/rfc5785>. <http://www.rfc-editor.org/info/rfc5785>.
[RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", RFC [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS)
6455, DOI 10.17487/RFC6455, December 2011, Extensions: Extension Definitions", RFC 6066,
DOI 10.17487/RFC6066, January 2011,
<http://www.rfc-editor.org/info/rfc6066>.
[RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol",
RFC 6455, DOI 10.17487/RFC6455, December 2011,
<http://www.rfc-editor.org/info/rfc6455>. <http://www.rfc-editor.org/info/rfc6455>.
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252, DOI 10.17487/ Application Protocol (CoAP)", RFC 7252,
RFC7252, June 2014, DOI 10.17487/RFC7252, June 2014,
<http://www.rfc-editor.org/info/rfc7252>. <http://www.rfc-editor.org/info/rfc7252>.
[RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan,
"Transport Layer Security (TLS) Application-Layer Protocol "Transport Layer Security (TLS) Application-Layer Protocol
Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301,
July 2014, <http://www.rfc-editor.org/info/rfc7301>. July 2014, <http://www.rfc-editor.org/info/rfc7301>.
[RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines
and Registration Procedures for URI Schemes", BCP 35, RFC and Registration Procedures for URI Schemes", BCP 35,
7595, DOI 10.17487/RFC7595, June 2015, RFC 7595, DOI 10.17487/RFC7595, June 2015,
<http://www.rfc-editor.org/info/rfc7595>. <http://www.rfc-editor.org/info/rfc7595>.
[RFC7641] Hartke, K., "Observing Resources in the Constrained [RFC7641] Hartke, K., "Observing Resources in the Constrained
Application Protocol (CoAP)", RFC 7641, DOI 10.17487/ Application Protocol (CoAP)", RFC 7641,
RFC7641, September 2015, DOI 10.17487/RFC7641, September 2015,
<http://www.rfc-editor.org/info/rfc7641>. <http://www.rfc-editor.org/info/rfc7641>.
[RFC7925] Tschofenig, H., Ed. and T. Fossati, "Transport Layer [RFC7925] Tschofenig, H., Ed. and T. Fossati, "Transport Layer
Security (TLS) / Datagram Transport Layer Security (DTLS) Security (TLS) / Datagram Transport Layer Security (DTLS)
Profiles for the Internet of Things", RFC 7925, DOI Profiles for the Internet of Things", RFC 7925,
10.17487/RFC7925, July 2016, DOI 10.17487/RFC7925, July 2016,
<http://www.rfc-editor.org/info/rfc7925>. <http://www.rfc-editor.org/info/rfc7925>.
9.2. Informative References 10.2. Informative References
[HomeGateway] [HomeGateway]
Eggert, L., "An experimental study of home gateway Eggert, L., "An experimental study of home gateway
characteristics", Proceedings of the 10th annual characteristics", Proceedings of the 10th annual
conference on Internet measurement, 2010. conference on Internet measurement , 2010.
[I-D.ietf-core-cocoa]
Bormann, C., Betzler, A., Gomez, C., and I. Demirkol,
"CoAP Simple Congestion Control/Advanced", draft-ietf-
core-cocoa-00 (work in progress), October 2016.
[I-D.ietf-core-object-security]
Selander, G., Mattsson, J., Palombini, F., and L. Seitz,
"Object Security of CoAP (OSCOAP)", draft-ietf-core-
object-security-01 (work in progress), December 2016.
[LWM2M] Open Mobile Alliance, "Lightweight Machine to Machine [LWM2M] Open Mobile Alliance, "Lightweight Machine to Machine
Technical Specification Candidate Version 1.0", April Technical Specification Version 1.0", February 2017,
2016, <http://technical.openmobilealliance.org/Technical/R <http://www.openmobilealliance.org/release/LightweightM2M/
elease_Program/docs/LightweightM2M/V1_0-20160407-C/ V1_0-20170208-A/
OMA-TS-LightweightM2M-V1_0-20160407-C.pdf>. OMA-TS-LightweightM2M-V1_0-20170208-A.pdf>.
[RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, DOI [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768,
10.17487/RFC0768, August 1980, DOI 10.17487/RFC0768, August 1980,
<http://www.rfc-editor.org/info/rfc768>. <http://www.rfc-editor.org/info/rfc768>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/ Specifications: ABNF", STD 68, RFC 5234,
RFC5234, January 2008, DOI 10.17487/RFC5234, January 2008,
<http://www.rfc-editor.org/info/rfc5234>. <http://www.rfc-editor.org/info/rfc5234>.
[RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S.
Cheshire, "Internet Assigned Numbers Authority (IANA) Cheshire, "Internet Assigned Numbers Authority (IANA)
Procedures for the Management of the Service Name and Procedures for the Management of the Service Name and
Transport Protocol Port Number Registry", BCP 165, RFC Transport Protocol Port Number Registry", BCP 165,
6335, DOI 10.17487/RFC6335, August 2011, RFC 6335, DOI 10.17487/RFC6335, August 2011,
<http://www.rfc-editor.org/info/rfc6335>. <http://www.rfc-editor.org/info/rfc6335>.
[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>.
[RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, DOI [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454,
10.17487/RFC6454, December 2011, DOI 10.17487/RFC6454, December 2011,
<http://www.rfc-editor.org/info/rfc6454>. <http://www.rfc-editor.org/info/rfc6454>.
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Message Syntax and Routing", RFC Protocol (HTTP/1.1): Message Syntax and Routing",
7230, DOI 10.17487/RFC7230, June 2014, RFC 7230, DOI 10.17487/RFC7230, June 2014,
<http://www.rfc-editor.org/info/rfc7230>. <http://www.rfc-editor.org/info/rfc7230>.
[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>.
[SecurityChallenges]
Polk, T. and S. Turner, "Security Challenges for the
Internet of Things", Interconnecting Smart Objects with
the Internet / IAB Workshop , February 2011,
<http://www.iab.org/wp-content/IAB-uploads/2011/03/
Turner.pdf>.
Appendix A. Updates to RFC7641 Observing Resources in the Constrained Appendix A. Updates to RFC7641 Observing Resources in the Constrained
Application Protocol (CoAP) Application Protocol (CoAP)
In this appendix, "client" and "server" refer to the CoAP client and
CoAP server.
A.1. Notifications and Reordering A.1. Notifications and Reordering
When using the Observe Option with CoAP over UDP, notifications from When using the Observe Option with CoAP over UDP, notifications from
the server set the option value to an increasing sequence number for the server set the option value to an increasing sequence number for
reordering detection on the client since messages can arrive in a reordering detection on the client since messages can arrive in a
different order than they were sent. This sequence number is not different order than they were sent. This sequence number is not
required for CoAP over reliable transports since the TCP protocol required for CoAP over reliable transports since the TCP protocol
ensures reliable and ordered delivery of messages. The value of the ensures reliable and ordered delivery of messages. The value of the
Observe Option in 2.xx notifications MAY be empty on transmission and Observe Option in 2.xx notifications MAY be empty on transmission and
MUST be ignored on reception. MUST be ignored on reception.
skipping to change at page 37, line 11 skipping to change at page 40, line 38
alive and wishes to receive further notifications. A reset message alive and wishes to receive further notifications. A reset message
indicates that the client does not recognize the token which causes indicates that the client does not recognize the token which causes
the server to remove the associated entry from the list of observers. the server to remove the associated entry from the list of observers.
Since TCP eliminates the need for the message layer to support Since TCP eliminates the need for the message layer to support
reliability, CoAP over reliable transports does not support reliability, CoAP over reliable transports does not support
confirmable or non-confirmable message types. All notifications are confirmable or non-confirmable message types. All notifications are
delivered reliably to the client with positive acknowledgement of delivered reliably to the client with positive acknowledgement of
receipt occurring at the TCP level. If the client does not recognize receipt occurring at the TCP level. If the client does not recognize
the token in a notification, it MAY immediately abort the connection the token in a notification, it MAY immediately abort the connection
(see Section 4.6) and SHOULD include a diagnostic payload. (see Section 4.6).
A.3. Cancellation A.3. Freshness
For CoAP over UDP, if a client does not receive a notification for
some time, it MAY send a new GET request with the same token as the
original request to re-register its interest in a resource and verify
that the server is still responsive. For CoAP over reliable
transports, it is more efficient to check the health of the
connection (and all its active observations) by sending a CoAP Ping
Signaling message (Section 4.4) rather than individual requests to
confirm active observations.
A.4. Cancellation
For CoAP over UDP, a client that is no longer interested in receiving For CoAP over UDP, a client that is no longer interested in receiving
notifications can "forget" the observation and respond to the next notifications can "forget" the observation and respond to the next
notification from the server with a reset message to cancel the notification from the server with a reset message to cancel the
observation. observation.
For CoAP over reliable transports, a client MUST explicitly For CoAP over reliable transports, a client MUST explicitly
deregister by issuing a GET request that has the Token field set to deregister by issuing a GET request that has the Token field set to
the token of the observation to be cancelled and includes an Observe the token of the observation to be cancelled and includes an Observe
Option with the value set to 1 (deregister). Option with the value set to 1 (deregister).
If the client observes one or more resources over a reliable If the client observes one or more resources over a reliable
connection, then the CoAP server (or intermediary in the role of the transport, then the CoAP server (or intermediary in the role of the
CoAP server) MUST remove all entries associated with the client CoAP server) MUST remove all entries associated with the client
endpoint from the lists of observers when the connection is either endpoint from the lists of observers when the connection is either
closed or times out. closed or times out.
Appendix B. Negotiating Protocol Versions Appendix B. CoAP over WebSocket Examples
CoAP is defined in [RFC7252] with a version number of 1. At this
time, there is no known reason to support version numbers different
from 1.
In contrast to the message layer for UDP and DTLS, the CoAP over TCP
message format does not include a version number. If version
negotiation needs to be addressed in the future, then Capability and
Settings have been specifically designed to enable such a potential
feature.
Appendix C. CoAP over WebSocket Examples
This section gives examples for the first two configurations This section gives examples for the first two configurations
discussed in Section 3. discussed in Section 3.
An example of the process followed by a CoAP client to retrieve the An example of the process followed by a CoAP client to retrieve the
representation of a resource identified by a "coap+ws" URI might be representation of a resource identified by a "coap+ws" URI might be
as follows. Figure 19 below illustrates the WebSocket and CoAP as follows. Figure 20 below illustrates the WebSocket and CoAP
messages exchanged in detail. messages exchanged in detail.
1. The CoAP client obtains the URI <coap+ws://example.org/sensors/ 1. The CoAP client obtains the URI <coap+ws://example.org/sensors/
temperature?u=Cel>, for example, from a resource representation temperature?u=Cel>, for example, from a resource representation
that it retrieved previously. that it retrieved previously.
2. It establishes a WebSocket connection to the endpoint URI 2. It establishes a WebSocket connection to the endpoint URI
composed of the authority "example.org" and the well-known path composed of the authority "example.org" and the well-known path
"/.well-known/coap", <ws://example.org/.well-known/coap>. "/.well-known/coap", <ws://example.org/.well-known/coap>.
skipping to change at page 39, line 50 skipping to change at page 42, line 50
| | | Payload: "22.3 Cel" | | | | Payload: "22.3 Cel" |
| | +-------------------------+ | | +-------------------------+
: : : :
: : : :
| | | |
+--------->| Close frame (opcode=%x8, FIN=1, MASK=1) +--------->| Close frame (opcode=%x8, FIN=1, MASK=1)
| | | |
|<---------+ Close frame (opcode=%x8, FIN=1, MASK=0) |<---------+ Close frame (opcode=%x8, FIN=1, MASK=0)
| | | |
Figure 19: A CoAP client retrieves the representation of a resource Figure 20: A CoAP client retrieves the representation of a resource
identified by a "coap+ws" URI identified by a "coap+ws" URI
Figure 20 shows how a CoAP client uses a CoAP forward proxy with a Figure 21 shows how a CoAP client uses a CoAP forward proxy with a
WebSocket endpoint to retrieve the representation of the resource WebSocket endpoint to retrieve the representation of the resource
"coap://[2001:DB8::1]/". The use of the forward proxy and the "coap://[2001:DB8::1]/". The use of the forward proxy and the
address of the WebSocket endpoint are determined by the client from address of the WebSocket endpoint are determined by the client from
local configuration rules. The request URI is specified in the local configuration rules. The request URI is specified in the
Proxy-Uri Option. Since the request URI uses the "coap" URI scheme, Proxy-Uri Option. Since the request URI uses the "coap" URI scheme,
the proxy fulfills the request by issuing a Confirmable GET request the proxy fulfills the request by issuing a Confirmable GET request
over UDP to the CoAP server and returning the response over the over UDP to the CoAP server and returning the response over the
WebSocket connection to the client. WebSocket connection to the client.
CoAP CoAP CoAP CoAP CoAP CoAP
skipping to change at page 40, line 49 skipping to change at page 43, line 49
| | | +------------------------------------+ | | | +------------------------------------+
| | | | | |
|<---------+ | Binary frame (opcode=%x2, FIN=1, MASK=0) |<---------+ | Binary frame (opcode=%x2, FIN=1, MASK=0)
| | | +------------------------------------+ | | | +------------------------------------+
| | | | 2.05 Content | | | | | 2.05 Content |
| | | | Token: 0x7d | | | | | Token: 0x7d |
| | | | Payload: "ready" | | | | | Payload: "ready" |
| | | +------------------------------------+ | | | +------------------------------------+
| | | | | |
Figure 20: A CoAP client retrieves the representation of a resource Figure 21: A CoAP client retrieves the representation of a resource
identified by a "coap" URI via a WebSockets-enabled CoAP proxy identified by a "coap" URI via a WebSockets-enabled CoAP proxy
Appendix D. Change Log Appendix C. Change Log
The RFC Editor is requested to remove this section at publication. The RFC Editor is requested to remove this section at publication.
D.1. Since draft-core-coap-tcp-tls-02 C.1. Since draft-core-coap-tcp-tls-02
Merged draft-savolainen-core-coap-websockets-07 Merged draft-bormann- Merged draft-savolainen-core-coap-websockets-07 Merged draft-bormann-
core-block-bert-01 Merged draft-bormann-core-coap-sig-02 core-block-bert-01 Merged draft-bormann-core-coap-sig-02
D.2. Since draft-core-coap-tcp-tls-03 C.2. Since draft-core-coap-tcp-tls-03
Editorial updates Editorial updates
Added mandatory exchange of Capabilities and Settings messages after Added mandatory exchange of Capabilities and Settings messages after
connecting connecting
Added support for coaps+tcp port 5684 and more details on Added support for coaps+tcp port 5684 and more details on
Application-Layer Protocol Negotiation (ALPN) Application-Layer Protocol Negotiation (ALPN)
Added guidance on CoAP Signaling Ping-Pong versus WebSocket Ping-Pong Added guidance on CoAP Signaling Ping-Pong versus WebSocket Ping-Pong
Updated references and requirements for TLS security considerations Updated references and requirements for TLS security considerations
D.3. Since draft-core-coap-tcp-tls-04 C.3. Since draft-core-coap-tcp-tls-04
Updated references Updated references
Added Appendix: Updates to RFC7641 Observing Resources in the Added Appendix: Updates to RFC7641 Observing Resources in the
Constrained Application Protocol (CoAP) Constrained Application Protocol (CoAP)
Updated Capability and Settings Message (CSM) exchange in the Opening Updated Capability and Settings Message (CSM) exchange in the Opening
Handshake to allow client to send messages before receiving server Handshake to allow initiator to send messages before receiving
CSM acceptor CSM
C.4. Since draft-core-coap-tcp-tls-05
Addressed feedback from Working Group Last Call
Added Securing CoAP section and informative reference to OSCOAP
Removed the Server-Name and Bad-Server-Name Options
Clarified the Capability and Settings Message (CSM) exchange
Updated Pong response requirements
Added Connection Initiator and Connection Acceptor terminology where
appropriate
Updated LWM2M 1.0 informative reference
Acknowledgements Acknowledgements
We would like to thank Stephen Berard, Geoffrey Cristallo, Olivier We would like to thank Stephen Berard, Geoffrey Cristallo, Olivier
Delaby, Christian Groves, Nadir Javed, Michael Koster, Matthias Delaby, Christian Groves, Nadir Javed, Michael Koster, Matthias
Kovatsch, Achim Kraus, David Navarro, Szymon Sasin, Zach Shelby, Kovatsch, Achim Kraus, David Navarro, Szymon Sasin, Goran Selander,
Andrew Summers, Julien Vermillard, and Gengyu Wei for their feedback. Zach Shelby, Andrew Summers, Julien Vermillard, and Gengyu Wei for
their feedback.
Contributors Contributors
Valik Solorzano Barboza
Zebra Technologies
820 W. Jackson Blvd. Suite 700
Chicago 60607
United States of America
Phone: +1-847-634-6700 Matthias Kovatsch
Email: vsolorzanobarboza@zebra.com Siemens AG
Otto-Hahn-Ring 6
Munich D-81739
Phone: +49-173-5288856
EMail: matthias.kovatsch@siemens.com
Teemu Savolainen Teemu Savolainen
Nokia Technologies Nokia Technologies
Hatanpaan valtatie 30 Hatanpaan valtatie 30
Tampere FI-33100 Tampere FI-33100
Finland Finland
Email: teemu.savolainen@nokia.com Email: teemu.savolainen@nokia.com
Authors' Addresses Valik Solorzano Barboza
Zebra Technologies
820 W. Jackson Blvd. Suite 700
Chicago 60607
United States of America
Phone: +1-847-634-6700
Email: vsolorzanobarboza@zebra.com
Authors' Addresses
Carsten Bormann Carsten Bormann
Universitaet Bremen TZI Universitaet Bremen TZI
Postfach 330440 Postfach 330440
Bremen D-28359 Bremen D-28359
Germany Germany
Phone: +49-421-218-63921 Phone: +49-421-218-63921
Email: cabo@tzi.org Email: cabo@tzi.org
Simon Lemay Simon Lemay
 End of changes. 237 change blocks. 
631 lines changed or deleted 850 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/