draft-ietf-core-coap-tcp-tls-09.txt   draft-ietf-core-coap-tcp-tls-10.txt 
CORE C. Bormann CORE C. Bormann
Internet-Draft Universitaet Bremen TZI Internet-Draft Universitaet Bremen TZI
Updates: 7252, 7641, 7959 (if approved) S. Lemay Updates: 7641, 7959 (if approved) S. Lemay
Intended status: Standards Track Zebra Technologies Intended status: Standards Track Zebra Technologies
Expires: November 17, 2017 H. Tschofenig Expires: May 3, 2018 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
May 16, 2017 October 30, 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-09 draft-ietf-core-coap-tcp-tls-10
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 RFC 7252 fixing an erratum in transports. It also formally updates RFC 7641 for use with these
the URI syntax, RFC 7641 for use with the new transports, and RFC transports and RFC 7959 to enable the use of larger messages over a
7959 to enable the use of larger messages over a reliable transport. reliable transport.
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 https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 17, 2017. This Internet-Draft will expire on May 3, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2017 IETF Trust and the persons identified as the Copyright (c) 2017 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (https://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
2. Conventions and Terminology . . . . . . . . . . . . . . . . . 5 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 6
3. CoAP over TCP . . . . . . . . . . . . . . . . . . . . . . . . 6 3. CoAP over TCP . . . . . . . . . . . . . . . . . . . . . . . . 7
3.1. Messaging Model . . . . . . . . . . . . . . . . . . . . . 7 3.1. Messaging Model . . . . . . . . . . . . . . . . . . . . . 7
3.2. Message Format . . . . . . . . . . . . . . . . . . . . . 7 3.2. Message Format . . . . . . . . . . . . . . . . . . . . . 8
3.3. Message Transmission . . . . . . . . . . . . . . . . . . 11 3.3. Message Transmission . . . . . . . . . . . . . . . . . . 10
3.4. Connection Health . . . . . . . . . . . . . . . . . . . . 12 3.4. Connection Health . . . . . . . . . . . . . . . . . . . . 11
4. CoAP over WebSockets . . . . . . . . . . . . . . . . . . . . 12 4. CoAP over WebSockets . . . . . . . . . . . . . . . . . . . . 11
4.1. Opening Handshake . . . . . . . . . . . . . . . . . . . . 14 4.1. Opening Handshake . . . . . . . . . . . . . . . . . . . . 13
4.2. Message Format . . . . . . . . . . . . . . . . . . . . . 14 4.2. Message Format . . . . . . . . . . . . . . . . . . . . . 14
4.3. Message Transmission . . . . . . . . . . . . . . . . . . 15 4.3. Message Transmission . . . . . . . . . . . . . . . . . . 15
4.4. Connection Health . . . . . . . . . . . . . . . . . . . . 16 4.4. Connection Health . . . . . . . . . . . . . . . . . . . . 15
5. Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . 16 5. Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . . 16 5.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . . 16
5.2. Signaling Option Numbers . . . . . . . . . . . . . . . . 16 5.2. Signaling Option Numbers . . . . . . . . . . . . . . . . 16
5.3. Capabilities and Settings Messages (CSM) . . . . . . . . 17 5.3. Capabilities and Settings Messages (CSM) . . . . . . . . 16
5.4. Ping and Pong Messages . . . . . . . . . . . . . . . . . 18 5.4. Ping and Pong Messages . . . . . . . . . . . . . . . . . 18
5.5. Release Messages . . . . . . . . . . . . . . . . . . . . 19 5.5. Release Messages . . . . . . . . . . . . . . . . . . . . 20
5.6. Abort Messages . . . . . . . . . . . . . . . . . . . . . 20 5.6. Abort Messages . . . . . . . . . . . . . . . . . . . . . 21
5.7. Signaling examples . . . . . . . . . . . . . . . . . . . 21 5.7. Signaling examples . . . . . . . . . . . . . . . . . . . 22
6. Block-wise Transfer and Reliable Transports . . . . . . . . . 22 6. Block-wise Transfer and Reliable Transports . . . . . . . . . 22
6.1. Example: GET with BERT Blocks . . . . . . . . . . . . . . 23 6.1. Example: GET with BERT Blocks . . . . . . . . . . . . . . 24
6.2. Example: PUT with BERT Blocks . . . . . . . . . . . . . . 24 6.2. Example: PUT with BERT Blocks . . . . . . . . . . . . . . 24
7. CoAP over Reliable Transport URIs . . . . . . . . . . . . . . 24 7. Observing Resources over Reliable Transports . . . . . . . . 25
7.1. Use of the "coap" URI scheme with TCP . . . . . . . . . . 25 7.1. Notifications and Reordering . . . . . . . . . . . . . . 25
7.2. Use of the "coaps" URI scheme with TLS over TCP . . . . . 25 7.2. Transmission and Acknowledgements . . . . . . . . . . . . 25
7.3. Use of the "coap" URI scheme with WebSockets . . . . . . 26 7.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 25
7.4. Use of the "coaps" URI scheme with WebSockets . . . . . . 27 7.4. Cancellation . . . . . . . . . . . . . . . . . . . . . . 26
7.5. Uri-Host and Uri-Port Options . . . . . . . . . . . . . . 27 8. CoAP over Reliable Transport URIs . . . . . . . . . . . . . . 26
7.6. Decomposing URIs into Options . . . . . . . . . . . . . . 28 8.1. coap+tcp URI scheme . . . . . . . . . . . . . . . . . . . 27
7.7. Composing URIs from Options . . . . . . . . . . . . . . . 28 8.2. coaps+tcp URI scheme . . . . . . . . . . . . . . . . . . 27
7.8. Trying out multiple transports at once . . . . . . . . . 29 8.3. coap+ws URI scheme . . . . . . . . . . . . . . . . . . . 28
8. Securing CoAP . . . . . . . . . . . . . . . . . . . . . . . . 29 8.4. coaps+ws URI scheme . . . . . . . . . . . . . . . . . . . 29
8.1. TLS binding for CoAP over TCP . . . . . . . . . . . . . . 30 8.5. Uri-Host and Uri-Port Options . . . . . . . . . . . . . . 30
8.2. TLS usage for CoAP over WebSockets . . . . . . . . . . . 30 8.6. Decomposing URIs into Options . . . . . . . . . . . . . . 30
9. Security Considerations . . . . . . . . . . . . . . . . . . . 31 8.7. Composing URIs from Options . . . . . . . . . . . . . . . 31
9.1. Signaling Messages . . . . . . . . . . . . . . . . . . . 31 9. Securing CoAP . . . . . . . . . . . . . . . . . . . . . . . . 32
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 9.1. TLS binding for CoAP over TCP . . . . . . . . . . . . . . 32
10.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . 31 9.2. TLS usage for CoAP over WebSockets . . . . . . . . . . . 33
10.2. CoAP Signaling Option Numbers Registry . . . . . . . . . 32 10. Security Considerations . . . . . . . . . . . . . . . . . . . 33
10.3. Service Name and Port Number Registration . . . . . . . 33 10.1. Signaling Messages . . . . . . . . . . . . . . . . . . . 34
10.4. Secure Service Name and Port Number Registration . . . . 34 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34
10.5. Well-Known URI Suffix Registration . . . . . . . . . . . 34 11.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . 34
10.6. ALPN Protocol Identifier . . . . . . . . . . . . . . . . 35 11.2. CoAP Signaling Option Numbers Registry . . . . . . . . . 34
10.7. WebSocket Subprotocol Registration . . . . . . . . . . . 35 11.3. Service Name and Port Number Registration . . . . . . . 36
10.8. CoAP Option Numbers Registry . . . . . . . . . . . . . . 35 11.4. Secure Service Name and Port Number Registration . . . . 36
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 36 11.5. URI Scheme Registration . . . . . . . . . . . . . . . . 37
11.1. Normative References . . . . . . . . . . . . . . . . . . 36 11.6. Well-Known URI Suffix Registration . . . . . . . . . . . 39
11.2. Informative References . . . . . . . . . . . . . . . . . 37 11.7. ALPN Protocol Identifier . . . . . . . . . . . . . . . . 39
Appendix A. Updates to RFC 7641 Observing Resources in the 11.8. WebSocket Subprotocol Registration . . . . . . . . . . . 40
Constrained Application Protocol (CoAP) . . . . . . 39 11.9. CoAP Option Numbers Registry . . . . . . . . . . . . . . 40
A.1. Notifications and Reordering . . . . . . . . . . . . . . 39 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 40
A.2. Transmission and Acknowledgements . . . . . . . . . . . . 39 12.1. Normative References . . . . . . . . . . . . . . . . . . 40
A.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 40 12.2. Informative References . . . . . . . . . . . . . . . . . 42
A.4. Cancellation . . . . . . . . . . . . . . . . . . . . . . 40 Appendix A. CoAP over WebSocket Examples . . . . . . . . . . . . 44
Appendix B. CoAP over WebSocket Examples . . . . . . . . . . . . 40 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 47
Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 44 B.1. Since draft-ietf-core-coap-tcp-tls-02 . . . . . . . . . . 47
C.1. Since draft-ietf-core-coap-tcp-tls-02 . . . . . . . . . . 44 B.2. Since draft-ietf-core-coap-tcp-tls-03 . . . . . . . . . . 47
C.2. Since draft-ietf-core-coap-tcp-tls-03 . . . . . . . . . . 44 B.3. Since draft-ietf-core-coap-tcp-tls-04 . . . . . . . . . . 47
C.3. Since draft-ietf-core-coap-tcp-tls-04 . . . . . . . . . . 44 B.4. Since draft-ietf-core-coap-tcp-tls-05 . . . . . . . . . . 47
C.4. Since draft-ietf-core-coap-tcp-tls-05 . . . . . . . . . . 44 B.5. Since draft-ietf-core-coap-tcp-tls-06 . . . . . . . . . . 48
C.5. Since draft-ietf-core-coap-tcp-tls-06 . . . . . . . . . . 45 B.6. Since draft-ietf-core-coap-tcp-tls-07 . . . . . . . . . . 48
C.6. Since draft-ietf-core-coap-tcp-tls-07 . . . . . . . . . . 45 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 48
C.7. Since draft-ietf-core-coap-tcp-tls-08 . . . . . . . . . . 45 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 45 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 49
Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 46
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 Datagram Transport Layer Security (DTLS) [RFC6347] over UDP can be can be used unimpeded, as can the Datagram Transport Layer Security
used unimpeded. UDP is a good choice for transferring small amounts protocol (DTLS [RFC6347]) over UDP. The use of CoAP over UDP is
of data across networks that follow the IP architecture. focused on simplicity, has a low code footprint, and a small over-
the-wire message size.
Some CoAP deployments need to integrate well with existing enterprise The primary reason for introducing CoAP over TCP [RFC0793] and TLS
infrastructures, where UDP-based protocols may not be well-received [RFC5246] is that some networks do not forward UDP packets. Complete
or may even be blocked by firewalls. Middleboxes that are unaware of blocking of UDP happens in between about 2% and 4% of terrestrial
CoAP usage for IoT can make the use of UDP brittle, resulting in lost access networks, according to [EK2016]. UDP impairment is especially
or malformed packets. concentrated in enterprise networks and networks in geographic
regions with otherwise challenged connectivity. Some networks also
rate-limit UDP traffic, as reported in [BK2015] and deployment
investigations related to the standardization of QUIC revealed
numbers around 0.3 % [SW2016].
Emerging standards such as Lightweight Machine to Machine [LWM2M] The introduction of CoAP over TCP also leads to some additional
currently use CoAP over UDP as a transport and require support for effects that may be desirable in a specific deployment:
CoAP over TCP to address the issues above and to protect investments
in existing CoAP implementations and deployments. Although HTTP/2
could also potentially address these requirements, there would be
additional costs and delays introduced by such a transition.
Currently, there are also fewer HTTP/2 implementations available for
constrained devices in comparison to CoAP.
To address these requirements, this document defines how to transport o Where NATs are present along the communication path, CoAP over TCP
CoAP over TCP, CoAP over TLS, and CoAP over WebSockets. For these leads to different NAT traversal behavior than CoAP over UDP.
cases, the reliability offered by the transport protocol subsumes the NATs often calculate expiration timers based on the transport
reliability functions of the message layer used for CoAP over UDP. layer protocol being used by application protocols. Many NATs
(Note that both for a reliable transport and the CoAP over UDP maintain TCP-based NAT bindings for longer periods based on the
message layer, the reliability offered is per transport hop: where assumption that a transport layer protocol, such as TCP, offers
proxies -- see Sections 5.7 and 10 of [RFC7252] -- are involved, that additional information about the session lifecycle. UDP, on the
layer's reliability function does not extend end-to-end.) Figure 1 other hand, does not provide such information to a NAT and
illustrates the layering: timeouts tend to be much shorter [HomeGateway]. According to
[HomeGateway] the mean for TCP and UDP NAT binding timeouts is 386
minutes (TCP) and 160 seconds (UDP). Shorter timeout values
require keepalive messages to be sent more frequently. Hence, the
use of CoAP over TCP requires less frequent transmission of keep-
alive messages.
+--------------------------------+ o TCP utilizes more sophisticated congestion and flow control
| Application | mechanisms than the default mechanisms provided by CoAP over UDP,
+--------------------------------+ which is useful for the transfer of larger payloads. (Work is,
+--------------------------------+ however, ongoing to add advanced congestion control to CoAP over
| Requests/Responses/Signaling | CoAP (RFC 7252) / This Document UDP as well, see [I-D.ietf-core-cocoa].)
|--------------------------------|
| Message Framing | This Document
+--------------------------------+
| Reliable Transport |
+--------------------------------+
Figure 1: Layering of CoAP over Reliable Transports Note that the use of CoAP over UDP (and CoAP over DTLS over UDP) is
still the recommended transport for use in constrained node networks,
particularly when used in concert with blockwise transfer. CoAP over
TCP is applicable for those cases where the networking infrastructure
leaves no other choice. The use of CoAP over TCP leads to a larger
code size, more roundtrips, increased RAM requirements and larger
packet sizes. Developers implementing CoAP over TCP are encouraged
to consult [I-D.gomez-lwig-tcp-constrained-node-networks] for
guidance on low-footprint TCP implementations for IoT devices.
Where NATs are present, CoAP over TCP can help with their traversal. Standards based on CoAP such as Lightweight Machine to Machine
NATs often calculate expiration timers based on the transport layer [LWM2M] currently use CoAP over UDP as a transport; adding support
protocol being used by application protocols. Many NATs maintain for CoAP over TCP enables them to address the issues above for
TCP-based NAT bindings for longer periods based on the assumption specific deployments and to protect investments in existing CoAP
that a transport layer protocol, such as TCP, offers additional implementations and deployments.
information about the session life cycle. UDP, on the other hand,
does not provide such information to a NAT and timeouts tend to be
much shorter [HomeGateway].
Some environments may also benefit from the ability of TCP to Although HTTP/2 could also potentially address the need for
exchange larger payloads, such as firmware images, without enterprise firewall traversal, there would be additional costs and
application layer segmentation and to utilize the more sophisticated delays introduced by such a transition from CoAP to HTTP/2.
congestion control capabilities provided by many TCP implementations. Currently, there are also fewer HTTP/2 implementations available for
constrained devices in comparison to CoAP. Since CoAP also support
group communication using IP layer multicast and unreliable
communication IoT devices would have to support HTTP/2 in addition to
CoAP.
Note that there is ongoing work to add more elaborate congestion Furthermore, CoAP may be integrated into a Web environment where the
control to CoAP (see [I-D.ietf-core-cocoa]). front-end 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 gateway can be used at the cloud boundary to communicate
with the UDP-based IoT device.
CoAP may be integrated into a Web environment where the front-end Finally, CoAP applications running inside a web browser may be
uses CoAP over UDP from IoT devices to a cloud infrastructure and without access to connectivity other than HTTP. In this case, the
then CoAP over TCP between the back-end services. A TCP-to-UDP WebSocket protocol [RFC6455] may be used to transport CoAP requests
gateway can be used at the cloud boundary to communicate with the and responses, as opposed to cross-proxying them via HTTP to an HTTP-
UDP-based IoT device. to-CoAP cross-proxy. This preserves the functionality of CoAP
without translation, in particular the Observe mechanism [RFC7641].
To allow IoT devices to better communicate in these demanding To address the above-mentioned deployment requirements, this document
environments, CoAP needs to support different transport protocols, defines how to transport CoAP over TCP, CoAP over TLS, and CoAP over
namely TCP [RFC0793], in some situations secured by TLS [RFC5246]. WebSockets. For these cases, the reliability offered by the
transport protocol subsumes the reliability functions of the message
layer used for CoAP over UDP. (Note that both for a reliable
transport and the CoAP over UDP message layer, the reliability
offered is per transport hop: where proxies -- see Sections 5.7 and
10 of [RFC7252] -- are involved, that layer's reliability function
does not extend end-to-end.) Figure 1 illustrates the layering:
CoAP applications running inside a web browser without access to +--------------------------------+
connectivity other than HTTP and the WebSocket protocol [RFC6455] may | Application |
cross-proxy their CoAP requests via HTTP to a HTTP-to-CoAP cross- +--------------------------------+
proxy or transport them via the the WebSocket protocol, which +--------------------------------+
provides two-way communication between a WebSocket client and a | Requests/Responses/Signaling | CoAP (RFC 7252) / This Document
WebSocket server after upgrading an HTTP/1.1 [RFC7230] connection. |--------------------------------|
| Message Framing | This Document
+--------------------------------+
| Reliable Transport |
+--------------------------------+
Figure 1: Layering of CoAP over Reliable Transports
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.
Appendix A updates the "Observing Resources in the Constrained Section 7 updates the "Observing Resources in the Constrained
Application Protocol" [RFC7641] specification for use with CoAP over Application Protocol" [RFC7641] specification for use with CoAP over
reliable transports. [RFC7641] is an extension to the CoAP protocol reliable transports. [RFC7641] is an extension to the CoAP protocol
that enables CoAP clients to "observe" a resource on a CoAP server. that enables CoAP clients to "observe" a resource on a CoAP server.
(The CoAP client retrieves a representation of a resource and (The CoAP client retrieves a representation of a resource and
registers to be notified by the CoAP server when the representation registers to be notified by the CoAP server when the representation
is updated.) is updated.)
Section 7 fixes an erratum on the URI scheme syntax in [RFC7252].
Section 6 defines semantics for a value 7 for the field "SZX" in a
Block1 or Block2 option, updating [RFC7959].
2. Conventions and Terminology 2. 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], [RFC7641], and concepts that are used in [RFC6455], [RFC7252], [RFC7641], and
[RFC7959]. [RFC7959].
skipping to change at page 6, line 33 skipping to change at page 7, line 5
Connection Initiator: Connection Initiator:
The peer that opens a reliable byte stream connection, i.e., the The peer that opens a reliable byte stream connection, i.e., the
TCP active opener, TLS client, or WebSocket client. TCP active opener, TLS client, or WebSocket client.
Connection Acceptor: Connection Acceptor:
The peer that accepts the reliable byte stream connection opened The peer that accepts the reliable byte stream connection opened
by the other peer, i.e., the TCP passive opener, TLS server, or by the other peer, i.e., the TCP passive opener, TLS server, or
WebSocket server. 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]).
3. CoAP over TCP 3. 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.
The message layer of CoAP over UDP supports optional reliability by The message layer of CoAP over UDP supports optional reliability by
defining four types of messages: Confirmable, Non-confirmable, defining four types of messages: Confirmable, Non-confirmable,
Acknowledgement, and Reset. In addition, messages include a Message Acknowledgement, and Reset. In addition, messages include a Message
ID to relate Acknowledgments to Confirmable messages and to detect ID to relate Acknowledgments to Confirmable messages and to detect
duplicate messages. duplicate messages.
The management of the connections is left to the application, i.e.,
the present specification does not describe how an application
decides to open a connection or to re-open another one in the
presence of failures (or what it would deem to be a failure, see also
Section 5.4). In particular, the Connection Initiator need not be
the client of the first request placed on the connection.
3.1. Messaging Model 3.1. Messaging Model
Conceptually, CoAP over TCP replaces most of the message layer of Conceptually, CoAP over TCP replaces most of the message layer of
CoAP over UDP 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 message layer of TCP ensures reliable message transmission, so the message layer of
CoAP over TCP is not required to support acknowledgements or to CoAP over TCP is not required to support acknowledgements or to
skipping to change at page 8, line 41 skipping to change at page 9, line 19
known reason to support version numbers different from 1. If known reason to support version numbers different from 1. If
version negotiation needs to be addressed in the future, then version negotiation needs to be addressed in the future, then
Capabilities and Settings Messages (CSM see Section 5.3) have been Capabilities and Settings Messages (CSM see Section 5.3) have been
specifically designed to enable such a potential feature. 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.
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 | TKL | Extended Length (if any, as chosen by Len) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 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 4: CoAP frame with 8-bit Extended Length field Figure 4: CoAP frame for reliable transports
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 inclusive 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.
14: A 16-bit unsigned integer (Extended Length) in network byte 14: A 16-bit unsigned integer (Extended Length) in network byte
order follows the initial byte and indicates the length of order follows the initial byte and indicates the length of
options/payload minus 269. options/payload minus 269.
15: A 32-bit unsigned integer (Extended Length) in network byte 15: A 32-bit unsigned integer (Extended Length) in network byte
order follows the initial byte and indicates the length of order follows the initial byte and indicates the length of
options/payload minus 65805. options/payload minus 65805.
The encoding of the Length field is modeled after the Option Length The encoding of the Length field is modeled after the Option Length
field of the CoAP Options (see Section 3.1 of [RFC7252]). field of the CoAP Options (see Section 3.1 of [RFC7252]).
The following figures show the message format for the 0-bit, 16-bit, For simplicity, a Payload Marker (0xFF) is shown in Figure 4; the
and the 32-bit variable length cases. Payload Marker indicates the start of the optional payload and is
absent for zero-length payloads (see Section 3 of [RFC7252]). (If
0 1 2 3 present, the Payload Marker is included in the message length, which
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 counts from the start of the Options field to the end of the Payload
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ field.)
| Len | TKL | Code | Token (if any, TKL bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Options (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 1 1 1 1 1 1 1| Payload (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
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 is encoded as shown in Figure 5.
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 5: CoAP message with no options or payload
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Len=14 | TKL | Extended Length (16 bits) | Code |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Token (if any, TKL bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Options (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 1 1 1 1 1 1 1| Payload (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 7: CoAP message format with 16-bit Extended Length field
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Len=15 | TKL | Extended Length (32 bits)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Code | Token (if any, TKL bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Options (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 1 1 1 1 1 1 1| Payload (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
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.
3.3. Message Transmission 3.3. Message Transmission
Once a connection is established, both endpoints MUST send a Once a connection is established, each endpoint MUST send a
Capabilities and Settings message (CSM see Section 5.3) as their Capabilities and Settings message (CSM see Section 5.3) as their
first message on the connection. This message establishes the first message on the connection. This message establishes the
initial settings and capabilities for the endpoint, such as maximum initial settings and capabilities for the endpoint, such as maximum
message size or support for block-wise transfers. The absence of message size or support for block-wise transfers. The absence of
options in the CSM indicates that base values are assumed. options in the CSM indicates that base values are assumed.
To avoid a deadlock, the Connection Initiator MUST NOT wait for the To avoid a deadlock, the Connection Initiator MUST NOT wait for the
Connection Acceptor to send its initial CSM message before sending Connection Acceptor to send its initial CSM message before sending
its own initial CSM message. Conversely, the Connection Acceptor MAY its own initial CSM message. Conversely, the Connection Acceptor MAY
wait for the Connection Initiator to send its initial CSM message wait for the Connection Initiator to send its initial CSM message
before sending its own initial CSM message. before sending its own initial CSM message.
To avoid unnecessary latency, a Connection Initiator MAY send To avoid unnecessary latency, a Connection Initiator MAY send
additional messages without waiting to receive the Connection additional messages after its initial CSM without waiting to receive
Acceptor's CSM; however, it is important to note that the Connection the Connection Acceptor's CSM; however, it is important to note that
Acceptor's CSM might advertise capabilities that impact how the the Connection Acceptor's CSM might indicate capabilities that impact
initiator is expected to communicate with the acceptor. For example, how the initiator is expected to communicate with the acceptor. For
the acceptor CSM could advertise a Max-Message-Size option (see example, the acceptor CSM could indicate a Max-Message-Size option
Section 5.3.1) that is smaller than the base value (1152). (see Section 5.3.1) that is smaller than the base value (1152) in
order to limit both buffering requirements and head-of-line blocking.
Endpoints MUST treat a missing or invalid CSM as a connection error Endpoints MUST treat a missing or invalid CSM as a connection error
and abort the connection (see Section 5.6). and abort the connection (see Section 5.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.
skipping to change at page 12, line 18 skipping to change at page 11, line 43
the recipient. This provides a basic keep-alive function that can the recipient. This provides a basic keep-alive function that can
refresh NAT bindings. refresh NAT bindings.
If a CoAP client does not receive any response for some time after If a CoAP client does not receive any response for some time after
sending a CoAP request (or, similarly, when a client observes a sending a CoAP request (or, similarly, when a client observes a
resource and it does not receive any notification for some time), it resource and it does not receive any notification for some time), it
can send a CoAP Ping Signaling message (see Section 5.4) to test the can send a CoAP Ping Signaling message (see Section 5.4) to test the
connection and verify that the CoAP server is responsive. connection and verify that the CoAP server is responsive.
When the underlying TCP connection is closed or reset, the signaling When the underlying TCP connection is closed or reset, the signaling
state and any observation state (see Appendix A.4) associated with state and any observation state (see Section 7.4) associated with the
the reliable connection are removed. In flight messages may or may reliable connection are removed. In flight messages may or may not
not be lost. be lost.
4. CoAP over WebSockets 4. CoAP over WebSockets
CoAP over WebSockets is intentionally similar to CoAP over TCP; CoAP over WebSockets is intentionally similar to CoAP over TCP;
therefore, this section only specifies the differences between the therefore, this section only specifies the differences between the
transports. 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 on a CoAP server that exposes a WebSocket CoAP resource located on a CoAP server that exposes a WebSocket
endpoint (see Figure 9). The CoAP client acts as the WebSocket endpoint (see Figure 6). The CoAP client acts as the WebSocket
client, establishes a WebSocket connection, and sends a CoAP request, client, establishes a WebSocket connection, and sends a CoAP request,
to which the CoAP server returns a CoAP response. The WebSocket to 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 |
| | responses | | | | responses | |
|___________| |___________| |___________| |___________|
WebSocket =============> WebSocket WebSocket =============> WebSocket
Client Connection Server Client Connection Server
Figure 9: CoAP Client (WebSocket client) accesses CoAP Server Figure 6: 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. Section 7.3 and Section 7.4 define how the "coap" and endpoint. Section 8.3 and Section 8.4 define new URI schemes that
"coaps" URI schemes can be used to enable the client to identify both enable the client to identify both a WebSocket endpoint and the path
a WebSocket endpoint and the path and query of the CoAP resource and query of the CoAP resource within that endpoint.
within that endpoint.
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 10), an SMS endpoint (a.k.a. mobile phone), CoAP UDP endpoint (Figure 7), an SMS endpoint (a.k.a. mobile phone),
or even another WebSocket endpoint. The CoAP 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 10: CoAP Client (WebSocket client) accesses CoAP Server (UDP Figure 7: 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 11). The web browser initially connects to a browser (Figure 8). 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 |
| | | | | | | | | | | |
|___________| |___________| |___________| |___________| |___________| |___________|
UDP UDP WebSocket <=== WebSocket UDP UDP WebSocket <=== WebSocket
Client Server Server Client Client Server Server Client
Figure 11: CoAP Client (UDP client) accesses CoAP Server (WebSocket Figure 8: CoAP Client (UDP client) accesses CoAP Server (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.
4.1. Opening Handshake 4.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 12 shows an example. Figure 9 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.
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.
GET /.well-known/coap HTTP/1.1 GET /.well-known/coap HTTP/1.1
Host: example.org Host: example.org
Upgrade: websocket Upgrade: websocket
Connection: Upgrade Connection: Upgrade
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 12: Example of an Opening Handshake Figure 9: Example of an Opening Handshake
4.2. Message Format 4.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 13 is the same as the CoAP over The message format shown in Figure 10 is the same as the CoAP over
TCP message format (see Section 3.2) with one change. The Length TCP message format (see Section 3.2) with one change. The Length
(Len) field MUST be set to zero because the WebSockets frame contains (Len) field MUST be set to zero because the WebSockets frame 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=0 | 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 13: CoAP Message Format over WebSockets Figure 10: CoAP Message Format over WebSockets
As with CoAP over TCP, the message format for CoAP over WebSockets As with CoAP over TCP, the message format for CoAP over WebSockets
eliminates the Version field defined in CoAP over UDP. If CoAP eliminates the Version field defined in CoAP over UDP. If CoAP
version negotiation is required in the future, CoAP over WebSockets version negotiation is required in the future, CoAP over WebSockets
can address the requirement by the definition of a new subprotocol can address the requirement by the definition of a new subprotocol
identifier that is negotiated during 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].
4.3. Message Transmission 4.3. Message Transmission
As with CoAP over TCP, both endpoints MUST send a Capabilities and As with CoAP over TCP, each endpoint MUST send a Capabilities and
Settings message (CSM see Section 5.3) as their first message on the Settings message (CSM see Section 5.3) as their first message on the
WebSocket connection. 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.
skipping to change at page 16, line 15 skipping to change at page 15, line 43
4.4. Connection Health 4.4. Connection Health
As with CoAP over TCP, a CoAP client can test the health of the CoAP As with CoAP over TCP, a CoAP client can test the health of the CoAP
over WebSocket connection by sending a CoAP Ping Signaling message over WebSocket connection by sending a CoAP Ping Signaling message
(Section 5.4). WebSocket Ping and unsolicited Pong frames (Section 5.4). WebSocket Ping and unsolicited Pong frames
(Section 5.5 of [RFC6455]) SHOULD NOT be used to ensure that (Section 5.5 of [RFC6455]) SHOULD NOT be used to ensure that
redundant maintenance traffic is not transmitted. redundant maintenance traffic is not transmitted.
5. Signaling 5. Signaling
Signaling messages are introduced to allow peers to: Signaling messages are specifically introduced only for CoAP over
reliable transports to allow peers to:
o Learn related characteristics, such as maximum message size for o Learn related characteristics, such as maximum message size for
the connection the connection
o Shut down the connection in an orderly fashion o Shut down the connection in an orderly fashion
o Provide diagnostic information when terminating a connection in o Provide diagnostic information when terminating a connection in
response to a serious error condition 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 of the message (See Section 3 of [RFC7252] for the overall structure of the message
format, option format, and option value format.) format, option format, and option value format.)
skipping to change at page 16, line 37 skipping to change at page 16, line 19
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 of the message (See Section 3 of [RFC7252] for the overall structure of the message
format, option format, and option value format.) format, option format, and option value format.)
5.1. Signaling Codes 5.1. Signaling Codes
A code in the 7.00-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 10.1). (see Section 11.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 as defined in 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.
5.2. Signaling Option Numbers 5.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 10.2). sub-registry (see Section 11.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 5.6). If the option is understood but cannot be processed, Section 5.6). If the option is understood but cannot be processed,
the option documents the behavior. the option documents the behavior.
5.3. Capabilities and Settings Messages (CSM) 5.3. Capabilities and Settings Messages (CSM)
Capabilities 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 indicates one capability of the sender to
the recipient. the recipient.
o Each setting option indicates a setting that will be applied by o Each setting option indicates a setting that will be applied by
the sender. the sender.
One CSM MUST be sent by both endpoints at the start of the One CSM MUST be sent by each endpoint at the start of the connection.
connection. Further CSM MAY be sent at any other time by either Further CSM MAY be sent at any other time by either endpoint over the
endpoint over the lifetime of the connection. lifetime of the connection.
Both capability and setting options are cumulative. A CSM does not Both capability and setting options are cumulative. A CSM does not
invalidate a previously sent capability indication or setting even if invalidate a previously sent capability indication or setting even if
it is not repeated. A capability message without any option is a no- it is not repeated. A capability message without any option is a no-
operation (and can be used as such). An option that is sent might operation (and can be used as such). An option that is sent might
override a previous value for the same option. The option defines override a previous value for the same option. The option defines
how to handle this case if needed. how to handle this case if 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 Capabilities 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]. Default values apply on a per-message
Capabilities and Settings message would result in the option being basis and thus reset when the value is not present in a given
set to its default value. Capabilities and Settings message.
Capabilities and Settings messages are indicated by the 7.01 code Capabilities and Settings messages are indicated by the 7.01 code
(CSM). (CSM).
5.3.1. Max-Message-Size Capability Option 5.3.1. Max-Message-Size Capability Option
The sender can use the elective Max-Message-Size Option to indicate The sender can use the elective Max-Message-Size Option to indicate
the maximum message size in bytes that it can receive. the maximum size of a message in bytes that it can receive. The
message size indicated includes the entire message, starting from the
first byte of the message header and ending at the end of the message
payload (there is no relationship of the message size to the overall
request or response body size that may be achievable in block-wise
transfer.)
+---+---+---+---------+------------------+--------+--------+--------+ +---+---+---+---------+------------------+--------+--------+--------+
| # | C | R | Applies | Name | Format | Length | Base | | # | C | R | Applies | Name | Format | Length | Base |
| | | | to | | | | Value | | | | | to | | | | Value |
+---+---+---+---------+------------------+--------+--------+--------+ +---+---+---+---------+------------------+--------+--------+--------+
| 2 | | | CSM | Max-Message-Size | uint | 0-4 | 1152 | | 2 | | | CSM | Max-Message-Size | uint | 0-4 | 1152 |
+---+---+---+---------+------------------+--------+--------+--------+ +---+---+---+---------+------------------+--------+--------+--------+
C=Critical, R=Repeatable C=Critical, R=Repeatable
skipping to change at page 18, line 38 skipping to change at page 18, line 22
| | | | | Transfer | | | | | | | | | Transfer | | | |
+---+---+---+---------+-----------------+--------+--------+---------+ +---+---+---+---------+-----------------+--------+--------+---------+
C=Critical, R=Repeatable C=Critical, R=Repeatable
A sender can use the elective Block-wise Transfer 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 wishing to offer block-wise transfers to its peer
Block-wise Transfer Option. If a Max-Message-Size Option is therefore needs to indicate the Block-wise Transfer Option.
indicated with a value that is greater than 1152 (in the same or a
different CSM message), the Block-wise Transfer Option also indicates If a Max-Message-Size Option is indicated with a value that is
support for BERT (see Section 6). Subsequently, if the Max-Message- greater than 1152 (in the same or a different CSM message), the
Size Option is indicated with a value equal to or less than 1152, Block-wise Transfer Option also indicates support for BERT (see
BERT support is no longer indicated. Section 6). Subsequently, if the Max-Message-Size Option is
indicated with a value equal to or less than 1152, BERT support is no
longer indicated. (Note that indication of BERT support obliges
neither peer to actually choose to make use of BERT.)
Implementation note: When indicating a value of the Max-Message-Size
option with an intention to enable BERT, the indicating
implementation may want to choose a BERT size message it wants to
encourage and add a delta for the header and any options that also
need to be included in the message. Section 4.6 of [RFC7252] adds
128 bytes to a maximum block size of 1024 to arrive at a default
message size of 1152. A BERT-enabled implementation may want to
indicate a BERT block size of 2048 or a higher multiple of 1024, and
at the same time be more generous for the size of header and options
added (say, 256 or 512). Adding 1024 or more however to the base
BERT block size may encourage the peer implementation to vary the
BERT block size based on the size of the options included, which can
be harder to establish interoperability for.
5.4. Ping and Pong Messages 5.4. Ping and Pong Messages
In CoAP over reliable transports, Empty messages (Code 0.00) can In CoAP over reliable transports, Empty messages (Code 0.00) can
always be sent and MUST be ignored by the recipient. This provides a always be sent and MUST be ignored by the recipient. This provides a
basic keep-alive function. In contrast, Ping and Pong messages are a basic keep-alive function. In contrast, Ping and Pong messages are a
bidirectional exchange. bidirectional exchange.
Upon receipt of a Ping message, the receiver MUST return a Pong Upon receipt of a Ping message, the receiver MUST return a Pong
message with an identical token in response. Unless there is an message with an identical token in response. Unless the Ping carries
option with delaying semantics such as the Custody Option, it SHOULD an option with delaying semantics such as the Custody Option, it
respond as soon as practical. As with all Signaling messages, the SHOULD respond as soon as practical. As with all Signaling messages,
recipient of a Ping or Pong message MUST ignore elective options it the recipient of a Ping or Pong message MUST ignore elective options
does not understand. it 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).
Note that, as with similar mechanisms defined in [RFC6455] and
[RFC7540], the present specification does not define any specific
maximum time that the sender of a Ping message has to allow waiting
for a Pong reply. Any limitations on the patience for this reply are
a matter of the application making use of these messages, as is any
approach to recover from a failure to respond in time.
5.4.1. Custody Option 5.4.1. Custody Option
+---+---+---+----------+----------------+--------+--------+---------+ +---+---+---+----------+----------------+--------+--------+---------+
| # | C | R | Applies | Name | Format | Length | Base | | # | C | R | Applies | Name | Format | Length | Base |
| | | | to | | | | Value | | | | | to | | | | Value |
+---+---+---+----------+----------------+--------+--------+---------+ +---+---+---+----------+----------------+--------+--------+---------+
| 2 | | | Ping, | Custody | empty | 0 | (none) | | 2 | | | Ping, | Custody | empty | 0 | (none) |
| | | | Pong | | | | | | | | | Pong | | | | |
+---+---+---+----------+----------------+--------+--------+---------+ +---+---+---+----------+----------------+--------+--------+---------+
skipping to change at page 19, line 50 skipping to change at page 20, line 12
request/response messages received prior to the Ping message on the request/response messages received prior to the Ping message on the
current connection. current connection.
5.5. Release Messages 5.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 (see Section 5.5.2 details are in the options. A diagnostic payload (see Section 5.5.2
of [RFC7252]) MAY be included. A peer will normally respond to a of [RFC7252]) MAY be included. A peer will normally respond to a
Release message by closing the TCP/TLS connection. Messages may be Release message by closing the TCP/TLS connection. Messages may be
in flight when the sender decides to send a Release message. The in flight or responses outstanding when the sender decides to send a
general expectation is that these will still be processed. Release message. The peer responding to the Release message SHOULD
delay the closing of the connection until it has responded to all
requests received by it before the Release message. It also MAY wait
for the responses to its own requests.
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:
+---+---+---+---------+------------------+--------+--------+--------+ +---+---+---+---------+------------------+--------+--------+--------+
| # | C | R | Applies | Name | Format | Length | Base | | # | C | R | Applies | Name | Format | Length | Base |
| | | | to | | | | Value | | | | | to | | | | Value |
+---+---+---+---------+------------------+--------+--------+--------+ +---+---+---+---------+------------------+--------+--------+--------+
| 2 | | x | Release | Alternative- | string | 1-255 | (none) | | 2 | | x | Release | Alternative- | string | 1-255 | (none) |
| | | | | Address | | | | | | | | | Address | | | |
+---+---+---+---------+------------------+--------+--------+--------+ +---+---+---+---------+------------------+--------+--------+--------+
C=Critical, R=Repeatable C=Critical, R=Repeatable
The elective Alternative-Address 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]. (Existing state
related to the connection is not transferred from the present
connection to the new connection.)
The Alternative-Address Option is a repeatable option as defined in The Alternative-Address Option is a repeatable option as defined in
Section 5.4.5 of [RFC7252]. When multiple occurrences of the option Section 5.4.5 of [RFC7252]. When multiple occurrences of the option
are included, the peer can choose any of the alternative transport are included, the peer can choose any of the alternative transport
addresses. addresses.
+---+---+---+---------+-----------------+--------+--------+---------+ +---+---+---+---------+-----------------+--------+--------+---------+
| # | C | R | Applies | Name | Format | Length | Base | | # | C | R | Applies | Name | Format | Length | Base |
| | | | to | | | | Value | | | | | to | | | | Value |
+---+---+---+---------+-----------------+--------+--------+---------+ +---+---+---+---------+-----------------+--------+--------+---------+
skipping to change at page 20, line 51 skipping to change at page 21, line 17
the value. the value.
5.6. Abort Messages 5.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
(see Section 5.5.2 of [RFC7252]) SHOULD be included in the Abort (see Section 5.5.2 of [RFC7252]) SHOULD be included in the Abort
message. Messages may be in flight when the sender decides to send message. Messages may be in flight or responses outstanding when the
an Abort message. The general expectation is that these will NOT be sender decides to send an Abort message. The general expectation is
processed. 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:
+---+---+---+---------+-----------------+--------+--------+---------+ +---+---+---+---------+-----------------+--------+--------+---------+
| # | C | R | Applies | Name | Format | Length | Base | | # | C | R | Applies | Name | Format | Length | Base |
| | | | to | | | | Value | | | | | to | | | | Value |
+---+---+---+---------+-----------------+--------+--------+---------+ +---+---+---+---------+-----------------+--------+--------+---------+
skipping to change at page 21, line 34 skipping to change at page 21, line 48
sender, or when there is parameter problem with the value of an sender, or when there is parameter problem with the value of an
elective option. More detailed information SHOULD be included as a elective option. More detailed information SHOULD be included as a
diagnostic payload. diagnostic payload.
For CoAP over UDP, messages which contain syntax violations are For CoAP over UDP, messages which contain syntax violations are
processed as message format errors. As described in Sections 4.2 and processed as message format errors. As described in Sections 4.2 and
4.3 of [RFC7252], such messages are rejected by sending a matching 4.3 of [RFC7252], such messages are rejected by sending a matching
Reset message and otherwise ignoring the message. Reset message and otherwise ignoring the message.
For CoAP over reliable transports, the recipient rejects such For CoAP over reliable transports, the recipient rejects such
messages by sending an Abort message and otherwise ignoring the messages by sending an Abort message and otherwise ignoring (not
message. No specific option has been defined for the Abort message processing) the message. No specific option has been defined for the
in this case, as the details are best left to a diagnostic payload. Abort message in this case, as the details are best left to a
diagnostic payload.
5.7. Signaling examples 5.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 14. in Figure 11.
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 14: Ping Message Example Figure 11: 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 15. Figure 12.
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 15: Pong Message Example Figure 12: Pong Message Example
6. Block-wise Transfer and Reliable Transports 6. 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 transport. While this suggests that the Block- used over a reliable transport. While this suggests that the Block-
wise transfer protocol [RFC7959] is also no longer needed, it remains wise transfer protocol [RFC7959] is also no longer needed, 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
skipping to change at page 23, line 18 skipping to change at page 23, line 24
In control usage, a BERT option is interpreted in the same way as the In control usage, a BERT option is interpreted in the same way as the
equivalent Option with SZX == 6, except that it also indicates the equivalent Option with SZX == 6, except that it also indicates the
capability to process BERT blocks. As with the basic Block protocol, capability to process BERT blocks. As with the basic Block protocol,
the recipient of a CoAP request with a BERT option in control usage the recipient of a CoAP request with a BERT option in control usage
is allowed to respond with a different SZX value, e.g. to send a non- is allowed to respond with a different SZX value, e.g. to send a non-
BERT block instead. BERT block instead.
In descriptive usage, a BERT Option is interpreted in the same way as In descriptive usage, a BERT Option is interpreted in the same way as
the equivalent Option with SZX == 6, except that the payload is also the equivalent Option with SZX == 6, except that the payload is also
allowed to contain a multiple of 1024 bytes (non-final BERT block) or allowed to contain multiple blocks. For non-final BERT blocks, the
more than 1024 bytes (final BERT block). payload is always a multiple of 1024 bytes. For final BERT blocks,
the payload is a multiple (possibly 0) of 1024 bytes plus a partial
block of less than 1024 bytes.
The recipient of a non-final BERT block (M=1) conceptually partitions The recipient of a non-final BERT block (M=1) conceptually partitions
the payload into a sequence of 1024-byte blocks and acts exactly as the payload into a sequence of 1024-byte blocks and acts exactly as
if it had received this sequence in conjunction with block numbers if it had received this sequence in conjunction with block numbers
starting at, and sequentially increasing from, the block number given starting at, and sequentially increasing from, the block number given
in the Block Option. In other words, the entire BERT block is in the Block Option. In other words, the entire BERT block is
positioned at the byte position that results from multiplying the positioned at the byte position that results from multiplying the
block number with 1024. The position of further blocks to be block number with 1024. The position of further blocks to be
transferred is indicated by incrementing the block number by the transferred is indicated by incrementing the block number by the
number of elements in this sequence (i.e., the size of the payload number of elements in this sequence (i.e., the size of the payload
skipping to change at page 23, line 49 skipping to change at page 24, line 9
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 (2**(SZX+4)) separated by (NUM), more bit (M), and block size (2**(SZX+4)) separated by
slashes. E.g., a Block2 Option value of 33 would be shown as 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.
6.1. Example: GET with BERT Blocks 6.1. Example: GET with BERT Blocks
Figure 16 shows a GET request with a response that is split into Figure 13 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.
CoAP Client CoAP 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 16: GET with BERT blocks Figure 13: GET with BERT blocks
6.2. Example: PUT with BERT Blocks 6.2. Example: PUT with BERT Blocks
Figure 17 demonstrates a PUT exchange with BERT blocks. Figure 14 demonstrates a PUT exchange with BERT blocks.
CoAP Client CoAP 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 17: PUT with BERT blocks Figure 14: PUT with BERT blocks
7. CoAP over Reliable Transport URIs 7. Observing Resources over Reliable Transports
This section describes how the procedures defined in [RFC7641] for
observing resources over CoAP are applied (and modified, as needed)
for reliable transports. In this section, "client" and "server"
refer to the CoAP client and CoAP server.
7.1. Notifications and Reordering
When using the Observe Option with CoAP over UDP, notifications from
the server set the option value to an increasing sequence number for
reordering detection on the client since messages can arrive in a
different order than they were sent. This sequence number is not
required for CoAP over reliable transports since the TCP protocol
ensures reliable and ordered delivery of messages. The value of the
Observe Option in 2.xx notifications MAY be empty on transmission and
MUST be ignored on reception.
Implementation note: This means that a proxy from a reordering
transport to a reliable (in-order) transport (such as a UDP-to-TCP
proxy) needs to process the Observe Option in notifications according
to the rules in Section 3.4 of [RFC7641].
7.2. Transmission and Acknowledgements
For CoAP over UDP, server notifications to the client can be
confirmable or non-confirmable. A confirmable message requires the
client to either respond with an acknowledgement message or a reset
message. An acknowledgement message indicates that the client is
alive and wishes to receive further notifications. A reset message
indicates that the client does not recognize the token which causes
the server to remove the associated entry from the list of observers.
Since TCP eliminates the need for the message layer to support
reliability, CoAP over reliable transports does not support
confirmable or non-confirmable message types. All notifications are
delivered reliably to the client with positive acknowledgement of
receipt occurring at the TCP level. If the client does not recognize
the token in a notification, it MAY immediately abort the connection
(see Section 5.6).
7.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 single CoAP
Ping Signaling message (Section 5.4) rather than individual requests
to confirm each active observation. (Note that such a Ping/Pong only
confirms a single hop: there is no obligation, and no expectation, of
a proxy to react to a Ping by checking all its onward observations or
all the connections, if any, underlying them. A proxy MAY maintain
its own schedule for confirming the onward observations it relies on;
it is however generally inadvisable for a proxy to generate a large
number of outgoing checks based on a single incoming check.)
7.4. Cancellation
For CoAP over UDP, a client that is no longer interested in receiving
notifications can "forget" the observation and respond to the next
notification from the server with a reset message to cancel the
observation.
For CoAP over reliable transports, a client MUST explicitly
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
Option with the value set to 1 (deregister).
If the client observes one or more resources over a reliable
transport, then the CoAP server (or intermediary in the role of the
CoAP server) MUST remove all entries associated with the client
endpoint from the lists of observers when the connection is either
closed or times out.
8. 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.
This document corrects an erratum in Sections 6.1 and 6.2 of This document introduces four additional URI schemes for identifying
[RFC7252] and defines how to use the schemes with the new transports. CoAP resources and providing a means of locating the resource:
Section 8 (Multicast CoAP) in [RFC7252] is not applicable to these
new transports. o the "coap+tcp" URI scheme for CoAP over TCP
o the "coaps+tcp" URI scheme for CoAP over TCP secured by TLS
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 hosted in
distinct namespaces because each URI scheme implies a distinct origin
server.
The syntax for the URI schemes in this section are specified using The syntax for the URI schemes in this section are specified using
Augmented Backus-Naur Form (ABNF) [RFC5234]. The definitions of Augmented Backus-Naur Form (ABNF) [RFC5234]. The definitions of
"host", "port", "path-abempty", "query", and "fragment" are adopted "host", "port", "path-abempty", and "query" are adopted from
from [RFC3986]. [RFC3986].
The ABNF syntax defined in Sections 6.1 and 6.2 of [RFC7252] for Section 8 (Multicast CoAP) in [RFC7252] is not applicable to these
"coap" and "coaps" schemes lacks the fragment identifer. This schemes.
specification updates the two rules in those sections as follows:
coap-URI = "coap:" "//" host [ ":" port ] As with the "coap" and "coaps" schemes defined in [RFC7252], all URI
path-abempty [ "?" query ] [ "#" fragment ] schemes defined in this section also support the path prefix "/.well-
coaps-URI = "coaps:" "//" host [ ":" port ] known/" defined by [RFC5785] for "well-known locations" in the
path-abempty [ "?" query ] [ "#" fragment ] namespace of a host. This enables discovery as per Section 7 of
[RFC7252].
7.1. Use of the "coap" URI scheme with TCP 8.1. coap+tcp URI scheme
The "coap" URI scheme defined in Section 6.1 of [RFC7252] can also be The "coap+tcp" URI scheme identifies CoAP resources that are intended
used to identify CoAP resources that are intended to be accessible to be accessible using CoAP over TCP.
using CoAP over TCP.
The syntax defined in Section 6.1 of [RFC7252] applies to this coap-tcp-URI = "coap+tcp:" "//" host [ ":" port ]
transport, with the following change: path-abempty [ "?" query ]
The syntax defined in Section 6.1 of [RFC7252] applies to this URI
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 Connection Acceptor is located. (If it is empty or not given,
port 5683 is assumed, as with UDP.) then the default port 5683 is assumed, as with UDP.)
7.2. Use of the "coaps" URI scheme with TLS over TCP Encoding considerations: The scheme encoding conforms to the
encoding rules established for URIs in [RFC3986].
The "coaps" URI scheme defined in Section 6.2 of [RFC7252] can also Interoperability considerations: None.
be used to identify CoAP resources that are intended to be accessible
using CoAP over TCP secured with TLS.
The syntax defined in Section 6.2 of [RFC7252] applies to this Security considerations: See Section 11.1 of [RFC7252].
transport, with the following changes:
8.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:
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 Connection Acceptor is located. If it is server for the CoAP Connection Acceptor is located. If it is
empty or not given, then the default port 5684 is assumed. empty or not given, then the default port 5684 is assumed.
o If a TLS 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
TLS clients that do not support ALPN, it MAY offer a coaps TLS clients that do not support ALPN, it MAY offer a coaps+tcp
endpoint on the default TCP port 5684. This endpoint MAY also be endpoint on TCP port 5684. This endpoint MAY also be ALPN
ALPN enabled. A TLS server MAY offer coaps endpoints on TCP ports enabled. A TLS server MAY offer coaps+tcp endpoints on ports
other than 5684; these then MUST be ALPN enabled. other than TCP port 5684, which MUST be ALPN enabled.
o For TCP ports other than port 5684, the TLS client MUST use the o For TCP ports other than port 5684, the TLS client MUST use the
ALPN extension to advertise the "coap" protocol identifier (see ALPN extension to advertise the "coap" protocol identifier (see
Section 10.6) in the list of protocols in its ClientHello. If the Section 11.7) in the list of protocols in its ClientHello. If the
TCP server selects and returns the "coap" protocol identifier TCP server selects and returns the "coap" protocol identifier
using the ALPN extension in its ServerHello, then the connection using the ALPN extension in its ServerHello, then the connection
succeeds. If the TLS 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 TLS extension or returns a no_application_protocol alert, the TLS
client MUST close the connection. client MUST close the connection.
o For TCP port 5684, a TLS 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 TLS server selects and returns the in its ClientHello. If the TLS server selects and returns the
"coap" protocol identifier using the ALPN extension in its "coap" protocol identifier using the ALPN extension in its
ServerHello, then the connection succeeds. If the TLS server ServerHello, then the connection succeeds. If the TLS server
returns a no_application_protocol alert, then the TLS client MUST returns a no_application_protocol alert, then the TLS client MUST
close the connection. If the TLS server does not negotiate the close the connection. If the TLS server does not negotiate the
ALPN extension, then coaps over TCP is implicitly selected. ALPN extension, then coaps+tcp is implicitly selected.
o For TCP port 5684, if the TLS client does not use the ALPN o For TCP port 5684, if the TLS client does not use the ALPN
extension to negotiate the protocol, then coaps over TCP is extension to negotiate the protocol, then coaps+tcp is implicitly
implicitly selected. selected.
7.3. Use of the "coap" URI scheme with WebSockets Encoding considerations: The scheme encoding conforms to the
encoding rules established for URIs in [RFC3986].
The "coap" URI scheme defined in Section 6.1 of [RFC7252] can also be Interoperability considerations: None.
used to identify CoAP resources that are intended to be accessible
using CoAP over WebSockets. Security considerations: See Section 11.1 of [RFC7252].
8.3. coap+ws URI scheme
The "coap+ws" URI scheme identifies CoAP resources that are intended
to be accessible using CoAP over WebSockets.
coap-ws-URI = "coap+ws:" "//" host [ ":" port ]
path-abempty [ "?" query ]
The port subcomponent is OPTIONAL. The default is port 80.
The WebSocket endpoint is identified by a "ws" URI that is composed The WebSocket endpoint is identified by a "ws" URI that is composed
of the authority part of the "coap" URI and the well-known path of the authority part of the "coap+ws" URI and the well-known path
"/.well-known/coap" [RFC5785] [I-D.bormann-hybi-ws-wk]. The path and "/.well-known/coap" [RFC5785] [I-D.bormann-hybi-ws-wk]. The path and
query parts of the "coap" URI identify a resource within the query parts of a "coap+ws" URI identify a resource within the
specified endpoint which can be operated on by the methods defined by specified endpoint which can be operated on by the methods defined by
CoAP: CoAP:
coap://example.org/sensors/temperature?u=Cel coap+ws://example.org/sensors/temperature?u=Cel
\______ ______/\___________ ___________/ \______ ______/\___________ ___________/
\/ \/ \/ \/
Uri-Path: "sensors" Uri-Path: "sensors"
ws://example.org/.well-known/coap Uri-Path: "temperature" ws://example.org/.well-known/coap Uri-Path: "temperature"
Uri-Query: "u=Cel" Uri-Query: "u=Cel"
Figure 18: Building ws URIs and Uri options from coap URIs Figure 15: The "coap+ws" URI Scheme
Note that the default port for "coap" is 5683, while the default port Encoding considerations: The scheme encoding conforms to the
for "ws" is 80. Therefore, if the port given for "coap" is 80, the encoding rules established for URIs in [RFC3986].
default port for "ws" can be used. If the port is not given for
"coap", then an explicit port number of 5683 needs to be given for
"ws".
7.4. Use of the "coaps" URI scheme with WebSockets Interoperability considerations: None.
The "coaps" URI scheme defined in Section 6.2 of [RFC7252] can also Security considerations: See Section 11.1 of [RFC7252].
be used to identify CoAP resources that are intended to be accessible
using CoAP over WebSockets secured by TLS. 8.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 subcomponent is OPTIONAL. The default is port 443.
The WebSocket endpoint is identified by a "wss" URI that is composed The WebSocket endpoint is identified by a "wss" URI that is composed
of the authority part of the "coaps" URI and the well-known path of the authority part of the "coaps+ws" URI and the well-known path
"/.well-known/coap" [RFC5785] [I-D.bormann-hybi-ws-wk]. The path and "/.well-known/coap" [RFC5785] [I-D.bormann-hybi-ws-wk]. The path and
query parts of the "coaps" URI identify a resource within the query parts of a "coaps+ws" URI identify a resource within the
specified endpoint which can be operated on by the methods defined by specified endpoint which can be operated on by the methods defined by
CoAP. CoAP.
coaps://example.org/sensors/temperature?u=Cel coaps+ws://example.org/sensors/temperature?u=Cel
\______ ______/\___________ ___________/ \______ ______/\___________ ___________/
\/ \/ \/ \/
Uri-Path: "sensors" Uri-Path: "sensors"
wss://example.org/.well-known/coap Uri-Path: "temperature" wss://example.org/.well-known/coap Uri-Path: "temperature"
Uri-Query: "u=Cel" Uri-Query: "u=Cel"
Figure 19: Building wss URIs and Uri options from coaps URIs Figure 16: The "coaps+ws" URI Scheme
Note that the default port for "coaps" is 5684, while the default Encoding considerations: The scheme encoding conforms to the
port for "wss" is 443. If the port given for "coap" is 443, the encoding rules established for URIs in [RFC3986].
default port for "wss" can be used. If the port is not given for
"coaps", then an explicit port number of 5684 needs to be given for
"wss".
7.5. Uri-Host and Uri-Port Options Interoperability considerations: None.
Except for the transports over WebSockets, CoAP over reliable Security considerations: See Section 11.1 of [RFC7252].
transports maintains the property from Section 5.10.1 of [RFC7252]:
8.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 The default values for the Uri-Host and Uri-Port Options are
sufficient for requests to most servers. sufficient for requests to most servers.
Unless otherwise noted, the default value of the Uri-Host Option is Unless otherwise noted, the default value of the Uri-Host Option is
the IP literal representing the destination IP address of the request the IP literal representing the destination IP address of the request
message. The default value of the Uri-Port Option is the destination message. The default value of the Uri-Port Option is the destination
TCP port. TCP port.
For CoAP over TLS, these default values are the same unless Server For CoAP over TLS, these default values are the same unless Server
Name Indication (SNI) [RFC6066] is negotiated. In this case, the Name Indication (SNI) [RFC6066] is negotiated. In this case, the
default value of the Uri-Host Option in requests from the TLS client default value of the Uri-Host Option in requests from the TLS client
to the TLS server is the SNI host. to the TLS server is the SNI host.
For CoAP over WebSockets, the default value of the Uri-Host Option in For CoAP over WebSockets, the default value of the Uri-Host Option in
requests from the WebSocket client to the WebSocket server is requests from the WebSocket client to the WebSocket server is
indicated by the Host header field from the WebSocket handshake. indicated by the Host header field from the WebSocket handshake.
7.6. Decomposing URIs into Options 8.6. Decomposing URIs into Options
The steps are the same as specified in Section 6.4 of [RFC7252] with The steps are the same as specified in Section 6.4 of [RFC7252] with
minor changes. minor changes.
This step from [RFC7252]: This step from [RFC7252]:
3. If |url| does not have a <scheme> component whose value, when
converted to ASCII lowercase, is "coap" or "coaps", then fail
this algorithm.
is updated to:
3. If |url| does not have a <scheme> component whose value, when
converted to ASCII lowercase, is "coap+tcp", "coaps+tcp",
"coap+ws", or "coaps+ws", then fail this algorithm.
This step from [RFC7252]:
7. If |port| does not equal the request's destination UDP port, 7. If |port| does not equal the request's destination UDP port,
include a Uri-Port Option and let that option's value be |port|. include a Uri-Port Option and let that option's value be |port|.
is updated to: is updated to:
7. If |port| does not equal the request's destination UDP port or 7. If |port| does not equal the request's destination TCP port,
TCP port, include a Uri-Port Option and let that option's value include a Uri-Port Option and let that option's value be |port|.
be |port|.
7.7. Composing URIs from Options 8.7. Composing URIs from Options
The steps are the same as specified in Section 6.5 of [RFC7252] with The steps are the same as specified in Section 6.5 of [RFC7252] with
minor changes. minor changes.
This step from [RFC7252]: This step from [RFC7252]:
1. If the request is secured using DTLS, let |url| be the string 1. If the request is secured using DTLS, let |url| be the string
"coaps://". Otherwise, let |url| be the string "coap://". "coaps://". Otherwise, let |url| be the string "coap://".
is updated to: is updated to:
1. If the request is secured using DTLS or TLS, let |url| be 1. For CoAP over TCP, if the request is secured using TLS, let |url|
the string "coaps://". Otherwise, let |url| be the string be the string "coaps+tcp://". Otherwise, let |url| be the string
"coap://". "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://".
This step from [RFC7252]: This step from [RFC7252]:
4. If the request includes a Uri-Port Option, let |port| be that 4. If the request includes a Uri-Port Option, let |port| be that
option's value. Otherwise, let |port| be the request's option's value. Otherwise, let |port| be the request's
destination UDP port. destination UDP port.
is updated to: is updated to:
4. If the request includes a Uri-Port Option, let |port| be that 4. If the request includes a Uri-Port Option, let |port| be that
option's value. Otherwise, let |port| be the request's option's value. Otherwise, let |port| be the request's
destination UDP port or TCP port. destination TCP port.
7.8. Trying out multiple transports at once
As in the "Happy Eyeballs" approach to using IPv6 and IPv4 [RFC6555],
an application may want to try out multiple transports for a given
URI at the same time, e.g., DTLS over UDP and TLS over TCP. However,
two important caveats need to be considered:
o Initiating multiple instances of the same exchange with the
intention of using only one of the successful results is only safe
for idempotent exchanges (see Section 5.1 of [RFC7252]).
o An important setback in using the UDP or DTLS over UDP transport
through NATs and other middleboxes can be the quick loss of NAT
bindings during idling periods [HomeGateway]. This will not be
evident right on the initial exchange.
After the initial exchange, or whenever important information is
learned about which selection to prefer, an endpoint may want to
cache this information; however, the information may become stale
after the endpoint moves or the network changes. A cache timeout
(possibly enhanced by movement detection) is advisable.
Alternatively, or additionally, the choice of transport may be aided
by configuration and resource directory information; the self-
description of a node may also include target attributes for links
given to resources there. Details of such attributes are out of
scope for the present document; see for instance
[I-D.ietf-core-resource-directory].
8. Securing CoAP 9. Securing CoAP
Security Challenges for the Internet of Things [SecurityChallenges] Security Challenges for the Internet of Things [SecurityChallenges]
recommends: recommends:
... it is essential that IoT protocol suites specify a mandatory ... it is essential that IoT protocol suites specify a mandatory
to implement but optional to use security solution. This will to implement but optional to use security solution. This will
ensure security is available in all implementations, but ensure security is available in all implementations, but
configurable to use when not necessary (e.g., in closed configurable to use when not necessary (e.g., in closed
environment). ... even if those features stretch the capabilities environment). ... even if those features stretch the capabilities
of such devices. of such devices.
A security solution MUST be implemented to protect CoAP over reliable A security solution MUST be implemented to protect CoAP over reliable
transports and MUST be enabled by default. This document defines the transports and MUST be enabled by default. This document defines the
TLS binding, but alternative solutions at different layers in the TLS binding, but alternative solutions at different layers in the
protocol stack MAY be used to protect CoAP over reliable transports protocol stack MAY be used to protect CoAP over reliable transports
when appropriate. Note that there is ongoing work to support a data when appropriate. Note that there is ongoing work to support a data
object-based security model for CoAP that is independent of transport object-based security model for CoAP that is independent of transport
(see [I-D.ietf-core-object-security]). (see [I-D.ietf-core-object-security]).
8.1. TLS binding for CoAP over TCP 9.1. TLS binding for CoAP over TCP
The TLS usage guidance in [RFC7925] applies, including the guidance The TLS usage guidance in [RFC7925] applies, including the guidance
about cipher suites in that document that are derived from the about cipher suites in that document that are derived from the
mandatory to implement (MTI) cipher suites defined in [RFC7252]. mandatory-to-implement (MTI) cipher suites defined in [RFC7252].
(Note that this selection caters for the device-to-cloud use case of
CoAP over TLS more than for any use within a back-end environment, This guidance assumes implementation in a constrained device or for
where the standard TLS 1.2 cipher suites or the more recent ones communication with a constrained device. CoAP over TCP/TLS has,
defined in [RFC7525] are more appropriate.) however, a wider applicability. It may, for example, be implemented
on a gateway or on a device that is less constrained (such as a smart
phone or a tablet), for communication with a peer that is likewise
less constrained, or within a backend environment that only
communicates with constrained devices via proxies. As an exception
to the previous paragraph, in this case, the recommendations in
[RFC7525] are more appropriate.
Since the guidance offered in [RFC7925] and [RFC7525] differs in
terms of algorithms and credential types, it is assumed that a CoAP
over TCP/TLS implementation that needs to support both cases
implements the recommendations offered by both specifications.
During the provisioning phase, a CoAP device is provided with the During the provisioning phase, a CoAP device is provided with the
security information that it needs, including keying materials, security information that it needs, including keying materials,
access control lists, and authorization servers. At the end of the access control lists, and authorization servers. At the end of the
provisioning phase, the device will be in one of four security modes: provisioning phase, the device will be in one of four security modes:
NoSec: TLS is disabled. NoSec: TLS is disabled.
PreSharedKey: TLS is enabled. The guidance in Section 4.2 of PreSharedKey: TLS is enabled. The guidance in Section 4.2 of
[RFC7925] applies. [RFC7925] applies.
RawPublicKey: TLS is enabled. The guidance in Section 4.3 of RawPublicKey: TLS is enabled. The guidance in Section 4.3 of
[RFC7925] applies. [RFC7925] applies.
Certificate: TLS is enabled. The guidance in Section 4.4 of Certificate: TLS is enabled. The guidance in Section 4.4 of
[RFC7925] applies. [RFC7925] applies.
The "NoSec" mode is optional-to-implement. The system simply sends The "NoSec" mode is optional-to-implement. The system simply sends
the packets over normal TCP which is indicated by the "coap" scheme the packets over normal TCP which is indicated by the "coap+tcp"
and the TCP CoAP default port. The system is secured only by keeping scheme and the TCP CoAP default port. The system is secured only by
attackers from being able to send or receive packets from the network keeping attackers from being able to send or receive packets from the
with the CoAP nodes. network with the CoAP nodes.
"PreSharedKey", "RawPublicKey", or "Certificate" is mandatory-to- "PreSharedKey", "RawPublicKey", or "Certificate" is mandatory-to-
implement for the TLS binding depending on the credential type used implement for the TLS binding depending on the credential type used
with the device. These security modes are achieved using TLS and are with the device. These security modes are achieved using TLS and are
indicated by the "coaps" scheme and TLS-secured CoAP default port. indicated by the "coaps+tcp" scheme and TLS-secured CoAP default
port.
8.2. TLS usage for CoAP over WebSockets 9.2. TLS usage for CoAP over WebSockets
A CoAP client requesting a resource identified by a "coaps" URI A CoAP client requesting a resource identified by a "coaps+ws" URI
negotiates a secure WebSocket connection to a WebSocket server negotiates a secure WebSocket connection to a WebSocket server
endpoint with a "wss" URI. This is described in Section 7.4. endpoint with a "wss" URI. This is described in Section 8.4.
The client MUST perform a TLS handshake after opening the connection The client MUST perform a TLS handshake after opening the connection
to the server. The guidance in Section 4.1 of [RFC6455] applies. to the server. The guidance in Section 4.1 of [RFC6455] applies.
When a CoAP server exposes resources identified by a "coaps" URI, the When a CoAP server exposes resources identified by a "coaps+ws" URI,
guidance in Section 4.4 of [RFC7925] applies towards mandatory-to- the guidance in Section 4.4 of [RFC7925] applies towards mandatory-
implement TLS functionality for certificates. For the server-side to-implement TLS functionality for certificates. For the server-side
requirements in accepting incoming connections over a HTTPS (HTTP- requirements in accepting incoming connections over a HTTPS (HTTP-
over-TLS) port, the guidance in Section 4.2 of [RFC6455] applies. over-TLS) port, the guidance in Section 4.2 of [RFC6455] applies.
Note that this formally inherits the mandatory to implement cipher Note that this formally inherits the mandatory-to-implement cipher
suites defined in [RFC5246]. However, modern usually browsers suites defined in [RFC5246]. However, usually modern browsers
implement more recent cipher suites that then are automatically implement more recent cipher suites that then are automatically
picked up via the JavaScript WebSocket API. WebSocket Servers that picked up via the JavaScript WebSocket API. WebSocket Servers that
provide Secure CoAP over WebSockets for the browser use case will provide Secure CoAP over WebSockets for the browser use case will
need to follow the browser preferences and MUST follow [RFC7525]. need to follow the browser preferences and MUST follow [RFC7525].
9. Security Considerations 10. Security Considerations
The security considerations of [RFC7252] apply. For CoAP over The security considerations of [RFC7252] apply. For CoAP over
WebSockets and CoAP over TLS-secured WebSockets, the security WebSockets and CoAP over TLS-secured WebSockets, the security
considerations of [RFC6455] also apply. considerations of [RFC6455] also apply.
9.1. Signaling Messages 10.1. Signaling Messages
The guidance given by an Alternative-Address Option cannot be 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.
10. IANA Considerations 11. IANA Considerations
10.1. Signaling Codes 11.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.00-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:
skipping to change at page 32, line 24 skipping to change at page 34, line 44
| 7.04 | Release | [RFCthis] | | 7.04 | Release | [RFCthis] |
| | | | | | | |
| 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 [RFC8126].
10.2. CoAP Signaling Option Numbers Registry 11.2. CoAP Signaling Option Numbers Registry
IANA is requested to create a sub-registry for Options Numbers used IANA is requested to create a sub-registry for Options Numbers used
in CoAP signaling options within the "CoRE Parameters" registry. The in CoAP signaling options within the "CoRE Parameters" registry. The
name of this sub-registry is "CoAP Signaling Option Numbers". name of this sub-registry is "CoAP Signaling Option Numbers".
Each entry in the sub-registry must include one or more of the codes Each entry in the sub-registry must include one or more of the codes
in the Signaling Codes subregistry (Section 10.1), the option number, in the Signaling Codes subregistry (Section 11.1), the option number,
the name of the option, and a reference to the option's the name of the option, and a reference to the option's
documentation. documentation.
Initial entries in this sub-registry are as follows: Initial entries in this sub-registry are as follows:
+------------+--------+---------------------+-----------+ +------------+--------+---------------------+-----------+
| Applies to | Number | Name | Reference | | Applies to | Number | Name | Reference |
+------------+--------+---------------------+-----------+ +------------+--------+---------------------+-----------+
| 7.01 | 2 | Max-Message-Size | [RFCthis] | | 7.01 | 2 | Max-Message-Size | [RFCthis] |
| | | | | | | | | |
skipping to change at page 33, line 25 skipping to change at page 35, line 32
| | | | | | | | | |
| 7.04 | 4 | Hold-Off | [RFCthis] | | 7.04 | 4 | Hold-Off | [RFCthis] |
| | | | | | | | | |
| 7.05 | 2 | Bad-CSM-Option | [RFCthis] | | 7.05 | 2 | 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]. (The policy is analogous rather than
identical because the structure of the subregistry includes an
additional column; however, the value of this column has no influence
on the policy.)
The documentation for a Signaling Option Number should specify the The documentation for a Signaling Option Number should specify the
semantics of an option with that number, including the following semantics of an option with that number, including the following
properties: properties:
o Whether the option is critical or elective, as determined by the o Whether the option is critical or elective, as determined by the
Option Number. Option Number.
o Whether the option is repeatable. o Whether the option is repeatable.
o The format and length of the option's value. o The format and length of the option's value.
o The base value for the option, if any. o The base value for the option, if any.
10.3. Service Name and Port Number Registration 11.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", in accordance with [RFC6335]. "coap+tcp", in accordance with [RFC6335].
Service Name. Service Name.
coap 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>
Description. Description.
Constrained Application Protocol (CoAP) Constrained Application Protocol (CoAP)
Reference. Reference.
[RFCthis] [RFCthis]
Port Number. Port Number.
5683 5683
10.4. Secure Service Name and Port Number Registration 11.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 also to address the exceptional case of TLS implementations requested to address the exceptional case of TLS implementations that
that do not support the "Application-Layer Protocol Negotiation do not support the "Application-Layer Protocol Negotiation Extension"
Extension" [RFC7301]. [RFC7301].
Service Name. Service Name.
coaps coaps+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>
Description. Description.
Constrained Application Protocol (CoAP) Constrained Application Protocol (CoAP)
Reference. Reference.
[RFC7301], [RFCthis] [RFC7301], [RFCthis]
Port Number. Port Number.
5684 5684
10.5. Well-Known URI Suffix Registration 11.5. URI Scheme Registration
URI schemes are registered within the "Uniform Resource Identifier
(URI) Schemes" registry maintained at [IANA.uri-schemes].
11.5.1. coap+tcp
IANA is requested to register the Uniform Resource Identifier (URI)
scheme "coap+tcp". This registration request complies with
[RFC7595].
Scheme name:
coap+tcp
Status:
Permanent
Applications/protocols that use this scheme name:
The scheme is used by CoAP endpoints to access CoAP resources
using TCP.
Contact:
IETF chair <chair@ietf.org>
Change controller:
IESG <iesg@ietf.org>
Reference:
Section 8.1 in [RFCthis]
11.5.2. coaps+tcp
IANA is requested to register the Uniform Resource Identifier (URI)
scheme "coaps+tcp". This registration request complies with
[RFC7595].
Scheme name:
coaps+tcp
Status:
Permanent
Applications/protocols that use this scheme name:
The scheme is used by CoAP endpoints to access CoAP resources
using TLS.
Contact:
IETF chair <chair@ietf.org>
Change controller:
IESG <iesg@ietf.org>
Reference:
Section 8.2 in [RFCthis]
11.5.3. coap+ws
IANA is requested to register the Uniform Resource Identifier (URI)
scheme "coap+ws". This registration request complies with [RFC7595].
Scheme name:
coap+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.
Contact:
IETF chair <chair@ietf.org>
Change controller:
IESG <iesg@ietf.org>
Reference:
Section 8.3 in [RFCthis]
11.5.4. coaps+ws
IANA is requested to register the Uniform Resource Identifier (URI)
scheme "coaps+ws". This registration request complies with
[RFC7595].
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>
Change controller:
IESG <iesg@ietf.org>
References:
Section 8.4 in [RFCthis]
11.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.
skipping to change at page 35, line 16 skipping to change at page 39, line 36
Change controller. Change controller.
IETF IETF
Specification document(s). Specification document(s).
[RFCthis] [RFCthis]
Related information. Related information.
None. None.
10.6. ALPN Protocol Identifier 11.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]
10.7. WebSocket Subprotocol Registration 11.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]
10.8. CoAP Option Numbers Registry 11.9. CoAP Option Numbers Registry
IANA is requested to add [RFCthis] to the references for the IANA is requested to add [RFCthis] to the references for the
following entries registered by [RFC7959] in the "CoAP Option following entries registered by [RFC7959] in the "CoAP Option
Numbers" sub-registry defined by [RFC7252]: Numbers" sub-registry defined by [RFC7252]:
+--------+--------+---------------------+ +--------+--------+---------------------+
| Number | Name | Reference | | Number | Name | Reference |
+--------+--------+---------------------+ +--------+--------+---------------------+
| 23 | Block2 | RFC 7959, [RFCthis] | | 23 | Block2 | RFC 7959, [RFCthis] |
| | | | | | | |
| 27 | Block1 | RFC 7959, [RFCthis] | | 27 | Block1 | RFC 7959, [RFCthis] |
+--------+--------+---------------------+ +--------+--------+---------------------+
Table 3: CoAP Option Numbers Table 3: CoAP Option Numbers
11. References 12. References
11.1. Normative References 12.1. Normative References
[I-D.bormann-hybi-ws-wk] [I-D.bormann-hybi-ws-wk]
Bormann, C., "Well-known URIs for the WebSocket Protocol", Bormann, C., "Well-known URIs for the WebSocket Protocol",
draft-bormann-hybi-ws-wk-00 (work in progress), May 2017. draft-bormann-hybi-ws-wk-00 (work in progress), May 2017.
[RFC0793] Postel, J., "Transmission Control Protocol", STD 7, [RFC0793] Postel, J., "Transmission Control Protocol", STD 7,
RFC 793, DOI 10.17487/RFC0793, September 1981, RFC 793, DOI 10.17487/RFC0793, September 1981,
<http://www.rfc-editor.org/info/rfc793>. <https://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, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>. <https://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, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005, RFC 3986, DOI 10.17487/RFC3986, January 2005,
<http://www.rfc-editor.org/info/rfc3986>. <https://www.rfc-editor.org/info/rfc3986>.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
DOI 10.17487/RFC5226, May 2008,
<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, (TLS) Protocol Version 1.2", RFC 5246,
DOI 10.17487/RFC5246, August 2008, DOI 10.17487/RFC5246, August 2008,
<http://www.rfc-editor.org/info/rfc5246>. <https://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, Uniform Resource Identifiers (URIs)", RFC 5785,
DOI 10.17487/RFC5785, April 2010, DOI 10.17487/RFC5785, April 2010,
<http://www.rfc-editor.org/info/rfc5785>. <https://www.rfc-editor.org/info/rfc5785>.
[RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS)
Extensions: Extension Definitions", RFC 6066, Extensions: Extension Definitions", RFC 6066,
DOI 10.17487/RFC6066, January 2011, DOI 10.17487/RFC6066, January 2011,
<http://www.rfc-editor.org/info/rfc6066>. <https://www.rfc-editor.org/info/rfc6066>.
[RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol",
RFC 6455, DOI 10.17487/RFC6455, December 2011, RFC 6455, DOI 10.17487/RFC6455, December 2011,
<http://www.rfc-editor.org/info/rfc6455>. <https://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, Application Protocol (CoAP)", RFC 7252,
DOI 10.17487/RFC7252, June 2014, DOI 10.17487/RFC7252, June 2014,
<http://www.rfc-editor.org/info/rfc7252>. <https://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, <https://www.rfc-editor.org/info/rfc7301>.
[RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre,
"Recommendations for Secure Use of Transport Layer "Recommendations for Secure Use of Transport Layer
Security (TLS) and Datagram Transport Layer Security Security (TLS) and Datagram Transport Layer Security
(DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May
2015, <http://www.rfc-editor.org/info/rfc7525>. 2015, <https://www.rfc-editor.org/info/rfc7525>.
[RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext
Transfer Protocol Version 2 (HTTP/2)", RFC 7540,
DOI 10.17487/RFC7540, May 2015,
<https://www.rfc-editor.org/info/rfc7540>.
[RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines
and Registration Procedures for URI Schemes", BCP 35,
RFC 7595, DOI 10.17487/RFC7595, June 2015,
<https://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, Application Protocol (CoAP)", RFC 7641,
DOI 10.17487/RFC7641, September 2015, DOI 10.17487/RFC7641, September 2015,
<http://www.rfc-editor.org/info/rfc7641>. <https://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, Profiles for the Internet of Things", RFC 7925,
DOI 10.17487/RFC7925, July 2016, DOI 10.17487/RFC7925, July 2016,
<http://www.rfc-editor.org/info/rfc7925>. <https://www.rfc-editor.org/info/rfc7925>.
[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>. <https://www.rfc-editor.org/info/rfc7959>.
11.2. Informative References [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>.
12.2. Informative References
[BK2015] Byrne, C. and J. Kleberg, "Advisory Guidelines for UDP
Deployment", Proceedings draft-byrne-opsec-udp-advisory-00
(expired), 2015.
[EK2016] Edeline, K., Kuehlewind, M., Trammell, B., Aben, E., and
B. Donnet, "Using UDP for Internet Transport Evolution",
Proceedings arXiv preprint 1612.07816, 2016.
[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.gomez-lwig-tcp-constrained-node-networks]
Gomez, C., Crowcroft, J., and M. Scharf, "TCP over
Constrained-Node Networks", draft-gomez-lwig-tcp-
constrained-node-networks-03 (work in progress), June
2017.
[I-D.ietf-core-cocoa] [I-D.ietf-core-cocoa]
Bormann, C., Betzler, A., Gomez, C., and I. Demirkol, Bormann, C., Betzler, A., Gomez, C., and I. Demirkol,
"CoAP Simple Congestion Control/Advanced", draft-ietf- "CoAP Simple Congestion Control/Advanced", draft-ietf-
core-cocoa-01 (work in progress), March 2017. core-cocoa-01 (work in progress), March 2017.
[I-D.ietf-core-object-security] [I-D.ietf-core-object-security]
Selander, G., Mattsson, J., Palombini, F., and L. Seitz, Selander, G., Mattsson, J., Palombini, F., and L. Seitz,
"Object Security of CoAP (OSCOAP)", draft-ietf-core- "Object Security for Constrained RESTful Environments
object-security-03 (work in progress), May 2017. (OSCORE)", draft-ietf-core-object-security-06 (work in
progress), October 2017.
[I-D.ietf-core-resource-directory] [IANA.uri-schemes]
Shelby, Z., Koster, M., Bormann, C., and P. Stok, "CoRE IANA, "Uniform Resource Identifier (URI) Schemes",
Resource Directory", draft-ietf-core-resource-directory-10 <http://www.iana.org/assignments/uri-schemes>.
(work in progress), March 2017.
[LWM2M] Open Mobile Alliance, "Lightweight Machine to Machine [LWM2M] Open Mobile Alliance, "Lightweight Machine to Machine
Technical Specification Version 1.0", February 2017, Technical Specification Version 1.0", February 2017,
<http://www.openmobilealliance.org/release/LightweightM2M/ <http://www.openmobilealliance.org/release/LightweightM2M/
V1_0-20170208-A/ V1_0-20170208-A/
OMA-TS-LightweightM2M-V1_0-20170208-A.pdf>. OMA-TS-LightweightM2M-V1_0-20170208-A.pdf>.
[RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768,
DOI 10.17487/RFC0768, August 1980, DOI 10.17487/RFC0768, August 1980,
<http://www.rfc-editor.org/info/rfc768>. <https://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, Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008, DOI 10.17487/RFC5234, January 2008,
<http://www.rfc-editor.org/info/rfc5234>. <https://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, Transport Protocol Port Number Registry", BCP 165,
RFC 6335, DOI 10.17487/RFC6335, August 2011, RFC 6335, DOI 10.17487/RFC6335, August 2011,
<http://www.rfc-editor.org/info/rfc6335>. <https://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, <https://www.rfc-editor.org/info/rfc6347>.
[RFC6555] Wing, D. and A. Yourtchenko, "Happy Eyeballs: Success with
Dual-Stack Hosts", RFC 6555, DOI 10.17487/RFC6555, April
2012, <http://www.rfc-editor.org/info/rfc6555>.
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Message Syntax and Routing",
RFC 7230, DOI 10.17487/RFC7230, June 2014,
<http://www.rfc-editor.org/info/rfc7230>.
[SecurityChallenges] [SecurityChallenges]
Polk, T. and S. Turner, "Security Challenges for the Polk, T. and S. Turner, "Security Challenges for the
Internet of Things", Interconnecting Smart Objects with Internet of Things", Interconnecting Smart Objects with
the Internet / IAB Workshop , February 2011, the Internet / IAB Workshop , February 2011,
<http://www.iab.org/wp-content/IAB-uploads/2011/03/ <http://www.iab.org/wp-content/IAB-uploads/2011/03/
Turner.pdf>. Turner.pdf>.
Appendix A. Updates to RFC 7641 Observing Resources in the Constrained [SW2016] Swett, I., "QUIC Deployment Experience @Google",
Application Protocol (CoAP) Proceedings
https://www.ietf.org/proceedings/96/slides/slides-96-quic-
In this appendix, "client" and "server" refer to the CoAP client and 3.pdf, 2016.
CoAP server.
A.1. Notifications and Reordering
When using the Observe Option with CoAP over UDP, notifications from
the server set the option value to an increasing sequence number for
reordering detection on the client since messages can arrive in a
different order than they were sent. This sequence number is not
required for CoAP over reliable transports since the TCP protocol
ensures reliable and ordered delivery of messages. The value of the
Observe Option in 2.xx notifications MAY be empty on transmission and
MUST be ignored on reception.
A.2. Transmission and Acknowledgements
For CoAP over UDP, server notifications to the client can be
confirmable or non-confirmable. A confirmable message requires the
client to either respond with an acknowledgement message or a reset
message. An acknowledgement message indicates that the client is
alive and wishes to receive further notifications. A reset message
indicates that the client does not recognize the token which causes
the server to remove the associated entry from the list of observers.
Since TCP eliminates the need for the message layer to support
reliability, CoAP over reliable transports does not support
confirmable or non-confirmable message types. All notifications are
delivered reliably to the client with positive acknowledgement of
receipt occurring at the TCP level. If the client does not recognize
the token in a notification, it MAY immediately abort the connection
(see Section 5.6).
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 5.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
notifications can "forget" the observation and respond to the next
notification from the server with a reset message to cancel the
observation.
For CoAP over reliable transports, a client MUST explicitly
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
Option with the value set to 1 (deregister).
If the client observes one or more resources over a reliable
transport, then the CoAP server (or intermediary in the role of the
CoAP server) MUST remove all entries associated with the client
endpoint from the lists of observers when the connection is either
closed or times out.
Appendix B. CoAP over WebSocket Examples Appendix A. 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 4. discussed in Section 4.
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" URI might be as representation of a resource identified by a "coap+ws" URI might be
follows. Figure 20 below illustrates the WebSocket and CoAP messages as follows. Figure 17 below illustrates the WebSocket and CoAP
exchanged in detail. messages exchanged in detail.
1. The CoAP client obtains the URI <coap://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>.
3. It sends a single-frame, masked, binary message containing a CoAP 3. It sends a single-frame, masked, binary message containing a CoAP
request. The request indicates the target resource with the Uri- request. The request indicates the target resource with the Uri-
Path ("sensors", "temperature") and Uri-Query ("u=Cel") options. Path ("sensors", "temperature") and Uri-Query ("u=Cel") options.
skipping to change at page 42, line 50 skipping to change at page 45, 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 20: A CoAP client retrieves the representation of a resource Figure 17: A CoAP client retrieves the representation of a resource
identified by a "coap" URI over the WebSocket protocol identified by a "coap+ws" URI
Figure 21 shows how a CoAP client uses a CoAP forward proxy with a Figure 18 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 43, line 49 skipping to change at page 46, 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 21: A CoAP client retrieves the representation of a resource Figure 18: A CoAP client retrieves the representation of a resource
identified by a "coap" URI via a WebSocket-enabled CoAP proxy identified by a "coap" URI via a WebSocket-enabled CoAP proxy
Appendix C. Change Log Appendix B. Change Log
The RFC Editor is requested to remove this section at publication. The RFC Editor is requested to remove this section at publication.
C.1. Since draft-ietf-core-coap-tcp-tls-02 B.1. Since draft-ietf-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
C.2. Since draft-ietf-core-coap-tcp-tls-03 B.2. Since draft-ietf-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
C.3. Since draft-ietf-core-coap-tcp-tls-04 B.3. Since draft-ietf-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 initiator to send messages before receiving Handshake to allow initiator to send messages before receiving
acceptor CSM acceptor CSM
C.4. Since draft-ietf-core-coap-tcp-tls-05 B.4. Since draft-ietf-core-coap-tcp-tls-05
Addressed feedback from Working Group Last Call Addressed feedback from Working Group Last Call
Added Securing CoAP section and informative reference to OSCOAP Added Securing CoAP section and informative reference to OSCOAP
Removed the Server-Name and Bad-Server-Name Options Removed the Server-Name and Bad-Server-Name Options
Clarified the Capability and Settings Message (CSM) exchange Clarified the Capability and Settings Message (CSM) exchange
Updated Pong response requirements Updated Pong response requirements
Added Connection Initiator and Connection Acceptor terminology where Added Connection Initiator and Connection Acceptor terminology where
appropriate appropriate
Updated LWM2M 1.0 informative reference Updated LWM2M 1.0 informative reference
C.5. Since draft-ietf-core-coap-tcp-tls-06 B.5. Since draft-ietf-core-coap-tcp-tls-06
Addressed feedback from second Working Group Last Call Addressed feedback from second Working Group Last Call
C.6. Since draft-ietf-core-coap-tcp-tls-07 B.6. Since draft-ietf-core-coap-tcp-tls-07
Addressed feedback from IETF Last Call Addressed feedback from IETF Last Call
Addressed feedback from ARTART review Addressed feedback from ARTART review
Addressed feedback from GENART review Addressed feedback from GENART review
Addressed feedback from TSVART review Addressed feedback from TSVART review
Added fragment identifiers to URI schemes Added fragment identifiers to URI schemes
Added "Updates RFC7959" for BERT Added "Updates RFC7959" for BERT
Added "Updates RFC6455" to extend well-known URI mechanism to ws and Added "Updates RFC6455" to extend well-known URI mechanism to ws and
wss wss
Clarified well-known URI mechanism use for all URI schemes Clarified well-known URI mechanism use for all URI schemes
Changed NoSec to optional-to-implement Changed NoSec to optional-to-implement
C.7. Since draft-ietf-core-coap-tcp-tls-08
Reverted "Updates RFC6455" to extend well-known URI mechanism to ws
and wss; point to [I-D.bormann-hybi-ws-wk] instead
Don't use port 443 as the default port for coaps+tcp
Remove coap+tt and coaps+tt URI schemes (where tt is tcp or ws); map
everything to coap/coaps
Acknowledgements Acknowledgements
We would like to thank Stephen Berard, Geoffrey Cristallo, Olivier We would like to thank Stephen Berard, Geoffrey Cristallo, Olivier
Delaby, Esko Dijk, Christian Groves, Nadir Javed, Michael Koster, Delaby, Esko Dijk, Christian Groves, Nadir Javed, Michael Koster,
Matthias Kovatsch, Achim Kraus, David Navarro, Szymon Sasin, Goran Matthias Kovatsch, Achim Kraus, David Navarro, Szymon Sasin, Goran
Selander, Zach Shelby, Andrew Summers, Julien Vermillard, and Gengyu Selander, Zach Shelby, Andrew Summers, Julien Vermillard, and Gengyu
Wei for their feedback. Last-call reviews from Mark Nottingham and Wei for their feedback.
Yoshifumi Nishida as well as several IESG reviewers provided
extensive comments; from the IESG, we would like to specifically call
out Adam Roach, Ben Campbell, Eric Rescorla, Mirja Kuehlewind, and
the responsible AD Alexey Melnikov.
Contributors Last-call reviews from Yoshifumi Nishida, Mark Nottingham, and Meral
Shirazipour as well as several IESG reviewers provided extensive
comments; from the IESG, we would like to specifically call out Ben
Campbell, Mirja Kuehlewind, Eric Rescorla, Adam Roach, and the
responsible AD Alexey Melnikov.
Contributors
Matthias Kovatsch Matthias Kovatsch
Siemens AG Siemens AG
Otto-Hahn-Ring 6 Otto-Hahn-Ring 6
Munich D-81739 Munich D-81739
Phone: +49-173-5288856 Phone: +49-173-5288856
EMail: matthias.kovatsch@siemens.com EMail: matthias.kovatsch@siemens.com
Teemu Savolainen Teemu Savolainen
Nokia Technologies Nokia Technologies
 End of changes. 186 change blocks. 
551 lines changed or deleted 730 lines changed or added

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