draft-ietf-core-coap-tcp-tls-03.txt   draft-ietf-core-coap-tcp-tls-04.txt 
CORE C. Bormann CORE C. Bormann
Internet-Draft Universitaet Bremen TZI Internet-Draft Universitaet Bremen TZI
Intended status: Standards Track S. Lemay Intended status: Standards Track S. Lemay
Expires: January 9, 2017 Zebra Technologies Expires: February 25, 2017 Zebra Technologies
H. Tschofenig 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
July 08, 2016 August 24, 2016
CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets
draft-ietf-core-coap-tcp-tls-03 draft-ietf-core-coap-tcp-tls-04
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
skipping to change at page 1, line 47 skipping to change at page 1, line 47
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 9, 2017. This Internet-Draft will expire on February 25, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5
2. CoAP over TCP . . . . . . . . . . . . . . . . . . . . . . . . 5 2. CoAP over TCP . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1. Messaging Model . . . . . . . . . . . . . . . . . . . . . 5 2.1. Messaging Model . . . . . . . . . . . . . . . . . . . . . 5
2.2. UDP-to-TCP gateways . . . . . . . . . . . . . . . . . . . 6 2.2. UDP-to-TCP gateways . . . . . . . . . . . . . . . . . . . 6
2.3. Message Format . . . . . . . . . . . . . . . . . . . . . 6 2.3. Opening Handshake . . . . . . . . . . . . . . . . . . . . 6
2.4. Message Transmission . . . . . . . . . . . . . . . . . . 9 2.4. Message Format . . . . . . . . . . . . . . . . . . . . . 6
2.5. Message Transmission . . . . . . . . . . . . . . . . . . 10
3. CoAP over WebSockets . . . . . . . . . . . . . . . . . . . . 10 3. CoAP over WebSockets . . . . . . . . . . . . . . . . . . . . 10
3.1. Opening Handshake . . . . . . . . . . . . . . . . . . . . 12 3.1. Opening Handshake . . . . . . . . . . . . . . . . . . . . 12
3.2. Message Format . . . . . . . . . . . . . . . . . . . . . 12 3.2. Message Format . . . . . . . . . . . . . . . . . . . . . 13
3.3. Message Transmission . . . . . . . . . . . . . . . . . . 13 3.3. Message Transmission . . . . . . . . . . . . . . . . . . 14
3.4. Connection Health . . . . . . . . . . . . . . . . . . . . 14 3.4. Connection Health . . . . . . . . . . . . . . . . . . . . 14
3.5. Closing the Connection . . . . . . . . . . . . . . . . . 14 3.5. Closing the Connection . . . . . . . . . . . . . . . . . 15
4. Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . 14 4. Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . . 15 4.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . . 15
4.2. Signaling Option Numbers . . . . . . . . . . . . . . . . 15 4.2. Signaling Option Numbers . . . . . . . . . . . . . . . . 16
4.3. Capability and Settings Messages (CSM) . . . . . . . . . 15 4.3. Capability and Settings Messages (CSM) . . . . . . . . . 16
4.4. Ping and Pong Messages . . . . . . . . . . . . . . . . . 17 4.4. Ping and Pong Messages . . . . . . . . . . . . . . . . . 18
4.5. Release Messages . . . . . . . . . . . . . . . . . . . . 18 4.5. Release Messages . . . . . . . . . . . . . . . . . . . . 19
4.6. Abort Messages . . . . . . . . . . . . . . . . . . . . . 19 4.6. Abort Messages . . . . . . . . . . . . . . . . . . . . . 20
4.7. Capability and Settings examples . . . . . . . . . . . . 20 4.7. Capability and Settings examples . . . . . . . . . . . . 21
5. Block-wise Transfer and Reliable Transports . . . . . . . . . 21 5. Block-wise Transfer and Reliable Transports . . . . . . . . . 21
5.1. Example: GET with BERT Blocks . . . . . . . . . . . . . . 22 5.1. Example: GET with BERT Blocks . . . . . . . . . . . . . . 23
5.2. Example: PUT with BERT Blocks . . . . . . . . . . . . . . 22 5.2. Example: PUT with BERT Blocks . . . . . . . . . . . . . . 23
6. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 23 6. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 24
6.1. CoAP over TCP and TLS URIs . . . . . . . . . . . . . . . 23 6.1. CoAP over TCP and TLS URIs . . . . . . . . . . . . . . . 24
6.2. CoAP over WebSockets URIs . . . . . . . . . . . . . . . . 24 6.2. CoAP over WebSockets URIs . . . . . . . . . . . . . . . . 25
7. Security Considerations . . . . . . . . . . . . . . . . . . . 25 7. Security Considerations . . . . . . . . . . . . . . . . . . . 26
7.1. Signaling Messages . . . . . . . . . . . . . . . . . . . 26 7.1. Signaling Messages . . . . . . . . . . . . . . . . . . . 27
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27
8.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . . 26 8.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . . 27
8.2. CoAP Signaling Option Numbers Registry . . . . . . . . . 27 8.2. CoAP Signaling Option Numbers Registry . . . . . . . . . 28
8.3. Service Name and Port Number Registration . . . . . . . . 27 8.3. Service Name and Port Number Registration . . . . . . . . 29
8.4. URI Scheme Registration . . . . . . . . . . . . . . . . . 29 8.4. Secure Service Name and Port Number Registration . . . . 30
8.5. Well-Known URI Suffix Registration . . . . . . . . . . . 31 8.5. URI Scheme Registration . . . . . . . . . . . . . . . . . 30
8.6. ALPN Protocol ID . . . . . . . . . . . . . . . . . . . . 31 8.6. Well-Known URI Suffix Registration . . . . . . . . . . . 33
8.7. WebSocket Subprotocol Registration . . . . . . . . . . . 31 8.7. ALPN Protocol Identifier . . . . . . . . . . . . . . . . 33
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 32 8.8. WebSocket Subprotocol Registration . . . . . . . . . . . 33
9.1. Normative References . . . . . . . . . . . . . . . . . . 32 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 34
9.2. Informative References . . . . . . . . . . . . . . . . . 33 9.1. Normative References . . . . . . . . . . . . . . . . . . 34
Appendix A. Negotiating Protocol Versions . . . . . . . . . . . 34 9.2. Informative References . . . . . . . . . . . . . . . . . 35
Appendix B. CoAP over WebSocket Examples . . . . . . . . . . . . 34 Appendix A. Negotiating Protocol Versions . . . . . . . . . . . 36
Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 38 Appendix B. CoAP over WebSocket Examples . . . . . . . . . . . . 36
C.1. Since draft-core-coap-tcp-tls-02 . . . . . . . . . . . . 38 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 40
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 38 C.1. Since draft-core-coap-tcp-tls-02 . . . . . . . . . . . . 40
Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 38 C.2. Since draft-core-coap-tcp-tls-03 . . . . . . . . . . . . 40
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 38 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 40
Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 41
1. Introduction 1. Introduction
The Constrained Application Protocol (CoAP) [RFC7252] was designed The Constrained Application Protocol (CoAP) [RFC7252] was designed
for Internet of Things (IoT) deployments, assuming that UDP [RFC0768] for Internet of Things (IoT) deployments, assuming that UDP [RFC0768]
or DTLS [RFC6347] over UDP can be used unimpeded. UDP is a good or DTLS [RFC6347] over UDP can be used unimpeded. UDP is a good
choice for transferring small amounts of data across networks that choice for transferring small amounts of data across networks that
follow the IP architecture. follow the IP architecture.
Some CoAP deployments need to integrate well with existing enterprise Some CoAP deployments need to integrate well with existing enterprise
infrastructures, where UDP-based protocols may not be well-received infrastructures, where UDP-based protocols may not be well-received
or may even be blocked by firewalls. Middleboxes that are unaware of or may even be blocked by firewalls. Middleboxes that are unaware of
CoAP usage for IoT can make the use of UDP brittle, resulting in lost CoAP usage for IoT can make the use of UDP brittle, resulting in lost
or malformed packets. or malformed packets.
To address such environments, this document defines how to transport Emerging standards such as Lightweight Machine to Machine [LWM2M]
currently use CoAP over UDP as a transport and require support for
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
CoAP over TCP, CoAP over TLS, and CoAP over WebSockets. Figure 1 CoAP over TCP, CoAP over TLS, and CoAP over WebSockets. Figure 1
illustrates the layering: illustrates the layering:
+--------------------------------+ +--------------------------------+
| Application | | Application |
+--------------------------------+ +--------------------------------+
+--------------------------------+ +--------------------------------+
| Requests/Responses/Signaling | CoAP (RFC 7252) / This Document | Requests/Responses/Signaling | CoAP (RFC 7252) / This Document
|--------------------------------| |--------------------------------|
| Message Framing | This Document | Message Framing | This Document
skipping to change at page 5, line 8 skipping to change at page 5, line 20
1.1. Terminology 1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "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] and [RFC7252]. concepts that are used in [RFC6455] and [RFC7252].
The term "reliable transport" only refers to stream-based transport
protocols such as TCP.
BERT Option: BERT Option:
A Block1 or Block2 option that includes an SZX value of 7. A Block1 or Block2 option that includes an SZX value of 7.
BERT Block: BERT Block:
The payload of a CoAP message that is affected by a BERT Option in The payload of a CoAP message that is affected by a BERT Option in
descriptive usage (Section 2.1 of [I-D.ietf-core-block]). descriptive usage (Section 2.1 of [I-D.ietf-core-block]).
2. CoAP over TCP 2. CoAP over TCP
The request/response interaction model of CoAP over TCP is the same The request/response interaction model of CoAP over TCP is the same
skipping to change at page 5, line 39 skipping to change at page 6, line 6
message that on datagram transports is provided by the UDP/DTLS message that on datagram transports is provided by the UDP/DTLS
datagram layer. datagram layer.
TCP ensures reliable message transmission, so the CoAP over TCP TCP ensures reliable message transmission, so the CoAP over TCP
messaging layer is not required to support acknowledgements or messaging layer is not required to support acknowledgements or
detection of duplicate messages. As a result, both the Type and detection of duplicate messages. As a result, both the Type and
Message ID fields are no longer required and are removed from the Message ID fields are no longer required and are removed from the
CoAP over TCP message format. All messages are also untyped. CoAP over TCP message format. All messages are also untyped.
Figure 2 illustrates the difference between CoAP over UDP and CoAP Figure 2 illustrates the difference between CoAP over UDP and CoAP
over reliable transport. The removed Type (no type) and Message ID over reliable transport. The removed Type and Message ID fields are
fields are indicated by dashes. indicated by dashes.
Client Server Client Server Client Server Client Server
| | | | | | | |
| CON [0xbc90] | | (-------) [------] | | CON [0xbc90] | | (-------) [------] |
| GET /temperature | | GET /temperature | | GET /temperature | | GET /temperature |
| (Token 0x71) | | (Token 0x71) | | (Token 0x71) | | (Token 0x71) |
+------------------->| +------------------->| +------------------->| +------------------->|
| | | | | | | |
| ACK [0xbc90] | | (-------) [------] | | ACK [0xbc90] | | (-------) [------] |
| 2.05 Content | | 2.05 Content | | 2.05 Content | | 2.05 Content |
skipping to change at page 6, line 32 skipping to change at page 6, line 36
Figure 2: Comparison between CoAP over unreliable and reliable Figure 2: Comparison between CoAP over unreliable and reliable
transport. transport.
2.2. UDP-to-TCP gateways 2.2. UDP-to-TCP gateways
A UDP-to-TCP gateway MUST discard all Empty messages (Code 0.00) A UDP-to-TCP gateway MUST discard all Empty messages (Code 0.00)
after processing at the message layer. For Confirmable (CON), Non- after processing at the message layer. For Confirmable (CON), Non-
Confirmable (NOM), and Acknowledgement (ACK) messages that are not Confirmable (NOM), and Acknowledgement (ACK) messages that are not
Empty, their contents are repackaged into untyped messages. Empty, their contents are repackaged into untyped messages.
2.3. Message Format 2.3. Opening Handshake
Both the client and the server MUST send a Capability and Settings
message (CSM see Section 4.3) as its first message on the connection.
This message establishes the initial settings and capabilities for
the endpoint such as maximum message size or support for block-wise
transfers. The absence of options in the CSM indicates that base
values are assumed.
Clients and servers MUST treat a missing or invalid CSM as a
connection error and abort the connection (see Section 4.6).
2.4. Message Format
The CoAP message format defined in [RFC7252], as shown in Figure 3, The CoAP message format defined in [RFC7252], as shown in Figure 3,
relies on the datagram transport (UDP, or DTLS over UDP) for keeping relies on the datagram transport (UDP, or DTLS over UDP) for keeping
the individual messages separate and for providing length the individual messages separate and for providing length
information. information.
0 1 2 3 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Ver| T | TKL | Code | Message ID | |Ver| T | TKL | Code | Message ID |
skipping to change at page 9, line 35 skipping to change at page 10, line 5
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Options (if any) ... | Options (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 1 1 1 1 1 1 1| Payload (if any) ... |1 1 1 1 1 1 1 1| Payload (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 8: CoAP message format with 32-bit Extended Length field. Figure 8: CoAP message format with 32-bit Extended Length field.
The semantics of the other CoAP header fields are left unchanged. The semantics of the other CoAP header fields are left unchanged.
2.4. Message Transmission 2.5. Message Transmission
CoAP requests and responses are exchanged asynchronously over the CoAP requests and responses are exchanged asynchronously over the
TCP/TLS connection. A CoAP client can send multiple requests without TCP/TLS connection. A CoAP client can send multiple requests without
waiting for a response and the CoAP server can return responses in waiting for a response and the CoAP server can return responses in
any order. Responses MUST be returned over the same connection as any order. Responses MUST be returned over the same connection as
the originating request. Concurrent requests are differentiated by the originating request. Concurrent requests are differentiated by
their Token, which is scoped locally to the connection. their Token, which is scoped locally to the connection.
The connection is bi-directional, so requests can be sent both by the The connection is bi-directional, so requests can be sent both by the
entity that established the connection and the remote host. entity that established the connection and the remote host.
skipping to change at page 12, line 45 skipping to change at page 13, line 29
Figure 13: Example of an Opening Handshake Figure 13: Example of an Opening Handshake
3.2. Message Format 3.2. Message Format
Once a WebSocket connection is established, CoAP requests and Once a WebSocket connection is established, CoAP requests and
responses can be exchanged as WebSocket messages. Since CoAP uses a responses can be exchanged as WebSocket messages. Since CoAP uses a
binary message format, the messages are transmitted in binary data binary message format, the messages are transmitted in binary data
frames as specified in Sections 5 and 6 of [RFC6455]. frames as specified in Sections 5 and 6 of [RFC6455].
The message format shown in Figure 14 is the same as the CoAP over The message format shown in Figure 14 is the same as the CoAP over
TCP message format (see Section 2.3) with one restriction. The TCP message format (see Section 2.4) with one restriction. The
Length (Len) field MUST be set to zero because the WebSockets frame Length (Len) field MUST be set to zero because the WebSockets frame
contains the length. contains the length.
0 1 2 3 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Len | TKL | Code | Token (TKL bytes) ... | Len | TKL | Code | Token (TKL bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Options (if any) ... | Options (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
skipping to change at page 14, line 21 skipping to change at page 14, line 47
3.4. Connection Health 3.4. Connection Health
When a client does not receive any response for some time after When a 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), the resource and it does not receive any notification for some time), the
connection between the WebSocket client and the WebSocket server may connection between the WebSocket client and the WebSocket server may
be lost or temporarily disrupted without the client being aware of be lost or temporarily disrupted without the client being aware of
it. it.
To check the health of the WebSocket connection (and thereby of all To check the health of the WebSocket connection (and thereby of all
active requests, if any), the client can send a Ping frame or an active requests, if any), a client can send a CoAP Ping Signaling
unsolicited Pong frame as specified in Section 5.5 of [RFC6455]. message (Section 4.4). WebSocket Ping and unsolicited Pong frames as
specified in Section 5.5 of [RFC6455] SHOULD NOT be used to ensure
that redundant maintenance traffic is not transmitted.
There is no way to retransmit a request without creating a new one. There is no way to retransmit a request without creating a new one.
Re-registering interest in a resource is permitted, but entirely Re-registering interest in a resource is permitted, but entirely
unnecessary. unnecessary.
3.5. Closing the Connection 3.5. Closing the Connection
The WebSocket connection is closed as specified in Section 7 of The WebSocket connection is closed as specified in Section 7 of
[RFC6455]. [RFC6455].
All requests for which the CoAP client has not received a response All requests for which the CoAP client has not received a response
skipping to change at page 15, line 48 skipping to change at page 16, line 31
4.3. Capability and Settings Messages (CSM) 4.3. Capability and Settings Messages (CSM)
Capability and Settings messages (CSM) are used for two purposes: Capability and Settings messages (CSM) are used for two purposes:
o Each capability option advertises one capability of the sender to o Each capability option advertises one capability of the sender to
the recipient. the recipient.
o Setting options indicate a setting that will be applied by the o Setting options indicate a setting that will be applied by the
sender. sender.
Most CSM Options are useful mainly as initial messages in the A Capability and Settings message MUST be sent by both endpoints at
connection. the start of the connection and MAY be sent at any other time by
either endpoint over the lifetime of the connection.
Both capability and settings options are cumulative. A Capability Both capability and settings options are cumulative. A Capability
and Settings message does not invalidate a previously sent capability and Settings message does not invalidate a previously sent capability
indication or setting even if it is not repeated. A capability indication or setting even if it is not repeated. A capability
message without any option is a no-operation (and can be used as message without any option is a no-operation (and can be used as
such). An option that is sent might override a previous value for such). An option that is sent might override a previous value for
the same option. The option defines how to handle this case if the same option. The option defines how to handle this case if
needed. needed.
Base values are listed below for CSM Options. These are the values Base values are listed below for CSM Options. These are the values
for the Capability and Setting before any Capability and Settings for the Capability and Setting before any Capability and Settings
messages sends a modified value. messages send a modified value.
These are not default values for the option as defined in These are not default values for the option as defined in
Section 5.4.4 in [RFC7252]. A default value would mean that an empty Section 5.4.4 in [RFC7252]. A default value would mean that an empty
Capability and Settings message would result in the option being set Capability and Settings message would result in the option being set
to its default value. to its default value.
Capability and Settings messages are indicated by the 7.01 code Capability and Settings messages are indicated by the 7.01 code
(CSM). (CSM).
4.3.1. Server-Name Setting Option 4.3.1. Server-Name Setting Option
skipping to change at page 17, line 42 skipping to change at page 18, line 19
block-wise transfers are supported by the sender or not. An block-wise transfers are supported by the sender or not. An
implementation that supports block-wise transfers SHOULD indicate the implementation that supports block-wise transfers SHOULD indicate the
Block-wise Transfer Option. If a Max-Message-Size Option is Block-wise Transfer Option. If a Max-Message-Size Option is
indicated with a value that is greater than 1152 (in the same or a indicated with a value that is greater than 1152 (in the same or a
different CSM message), the Block-wise Transfer Option also indicates different CSM message), the Block-wise Transfer Option also indicates
support for BERT (see Section 5). support for BERT (see Section 5).
4.4. Ping and Pong Messages 4.4. Ping and Pong Messages
In CoAP over TCP, Empty messages (Code 0.00) can always be sent and In CoAP over TCP, Empty messages (Code 0.00) can always be sent and
MUST be ignored by the recipient (see also Section 4.4). This MUST be ignored by the recipient. This provides a basic keep-alive
provides a basic keep-alive function that can refresh NAT bindings. function that can refresh NAT bindings. In contrast, Ping and Pong
In contrast, Ping and Pong messages are a bidirectional exchange. messages are a bidirectional exchange.
Upon receipt of a Ping message, a single Pong message is returned Upon receipt of a Ping message, a single Pong message is returned
with the identical token. As with all Signaling messages, the with the identical token. As with all Signaling messages, the
recipient of a Ping or Pong message MUST ignore elective options it recipient of a Ping or Pong message MUST ignore elective options it
does not understand. does not understand.
Ping and Pong messages are indicated by the 7.02 code (Ping) and the Ping and Pong messages are indicated by the 7.02 code (Ping) and the
7.03 code (Pong). 7.03 code (Pong).
4.4.1. Custody Option 4.4.1. Custody Option
skipping to change at page 24, line 22 skipping to change at page 25, line 5
[ "?" query ] [ "?" query ]
The semantics defined in [RFC7252], Section 6.2, apply to this URI The semantics defined in [RFC7252], Section 6.2, apply to this URI
scheme, with the following changes: scheme, with the following changes:
o The port subcomponent indicates the TCP port at which the TLS o The port subcomponent indicates the TCP port at which the TLS
server for the CoAP server is located. If it is empty or not server for the CoAP server is located. If it is empty or not
given, then the default port 443 is assumed (this is different given, then the default port 443 is assumed (this is different
from the default port for "coaps", i.e., CoAP over DTLS over UDP). from the default port for "coaps", i.e., CoAP over DTLS over UDP).
o When CoAP is exchanged over TLS port 443, the "TLS Application o If a server does not support the Application-Layer Protocol
Layer Protocol Negotiation Extension" [RFC7301] MUST be used to Negotiation Extension (ALPN) [RFC7301] or wishes to accommodate
allow demultiplexing at the server-side. clients that do not support ALPN, it MAY offer a coaps+tcp
endpoint on TCP port 5684. This endpoint MAY also be ALPN
enabled. A server MAY offer coaps+tcp endpoints on ports other
than TCP port 5684, which MUST be ALPN enabled.
o For TCP ports other than port 5684, the client MUST use the ALPN
extension to advertise the "coap" protocol identifier (see
Section 8.7) in the list of protocols in its ClientHello. If the
server selects and returns the "coap" protocol identifier using
the ALPN extension in its ServerHello, then the connection
succeeds. If the server either does not negotiate the ALPN
extension or returns a no_application_protocol alert, the client
MUST close the connection.
o For TCP port 5684, a client MAY use the ALPN extension to
advertise the "coap" protocol identifier in the list of protocols
in its ClientHello. If the server selects and returns the "coap"
protocol identifier using the ALPN extension in its ServerHello,
then the connection succeeds. If the server returns a
no_application_protocol alert, then the client MUST close the
connection. If the server does not negotiate the ALPN extension,
then coaps+tcp is implicitly selected.
o For TCP port 5684, if the client does not use the ALPN extension
to negotiate the protocol, then coaps+tcp is implicitly selected.
6.2. CoAP over WebSockets URIs 6.2. CoAP over WebSockets URIs
For the first configuration discussed in Section 3, this document For the first configuration discussed in Section 3, this document
defines two new URIs schemes that can be used for identifying CoAP defines two new URIs schemes that can be used for identifying CoAP
resources and providing a means of locating these resources: resources and providing a means of locating these resources:
"coap+ws" and "coap+wss". "coap+ws" and "coap+wss".
Similar to the "coap" and "coaps" schemes, the "coap+ws" and Similar to the "coap" and "coaps" schemes, the "coap+ws" and
"coap+wss" schemes organize resources hierarchically under a CoAP "coap+wss" schemes organize resources hierarchically under a CoAP
skipping to change at page 25, line 42 skipping to change at page 26, line 47
does not equal the port component in the Host header field in the does not equal the port component in the Host header field in the
WebSocket handshake. WebSocket handshake.
The steps to construct a URI from a request's options are changed The steps to construct a URI from a request's options are changed
accordingly. accordingly.
7. Security Considerations 7. Security Considerations
The security considerations of [RFC7252] apply. The security considerations of [RFC7252] apply.
Implementations of CoAP MUST use TLS version 1.2 or higher for CoAP TLS version 1.2 or higher is mandatory-to-implement and MUST be
over TLS. The general TLS usage guidance in [RFC7525] SHOULD be enabled by default. An endpoint MAY immediately abort a CoAP over
followed. TLS connection that does not meet this requirement (see Section 4.6)
and SHOULD include a diagnostic payload.
Guidelines for use of cipher suites and TLS extensions can be found The TLS usage guidance in [RFC7925] SHOULD be followed.
in [I-D.ietf-dice-profile].
TLS does not protect the TCP header. This may, for example, allow an TLS does not protect the TCP header. This may, for example, allow an
on-path adversary to terminate a TCP connection prematurely by on-path adversary to terminate a TCP connection prematurely by
spoofing a TCP reset message. spoofing a TCP reset message.
CoAP over WebSockets and CoAP over TLS-secured WebSockets do not CoAP over WebSockets and CoAP over TLS-secured WebSockets do not
introduce additional security issues beyond CoAP and DTLS-secured introduce additional security issues beyond CoAP and DTLS-secured
CoAP respectively [RFC7252]. The security considerations of CoAP respectively [RFC7252]. The security considerations of
[RFC6455] apply. [RFC6455] apply.
skipping to change at page 28, line 23 skipping to change at page 30, line 8
Description. Description.
Constrained Application Protocol (CoAP) Constrained Application Protocol (CoAP)
Reference. Reference.
[RFCthis] [RFCthis]
Port Number. Port Number.
5683 5683
Similarly, IANA is requested to assign the service name "coaps+tcp", 8.4. Secure Service Name and Port Number Registration
in accordance with [RFC6335]. However, no separate port number is
used for "coaps" over TCP; instead, the ALPN protocol ID defined in IANA is requested to assign the port number 5684 and the service name
Section 8.6 is used over port 443. "coaps+tcp", in accordance with [RFC6335]. The port number is
requested to address the exceptional case of TLS implementations that
do not support the "Application-Layer Protocol Negotiation Extension"
[RFC7301].
Service Name. Service Name.
coaps+tcp 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.
443 (see also Section 8.6 of [RFCthis]}) 5684
8.4. URI Scheme Registration 8.5. URI Scheme Registration
This document registers two new URI schemes, namely "coap+tcp" and This document registers two new URI schemes, namely "coap+tcp" and
"coaps+tcp", for the use of CoAP over TCP and for CoAP over TLS over "coaps+tcp", for the use of CoAP over TCP and for CoAP over TLS over
TCP, respectively. The "coap+tcp" and "coaps+tcp" URI schemes can TCP, respectively. The "coap+tcp" and "coaps+tcp" URI schemes can
thus be compared to the "http" and "https" URI schemes. thus be compared to the "http" and "https" URI schemes.
The syntax of the "coap" and "coaps" URI schemes is specified in The syntax of the "coap" and "coaps" URI schemes is specified in
Section 6 of [RFC7252] and the present document re-uses their Section 6 of [RFC7252] and the present document re-uses their
semantics for "coap+tcp" and "coaps+tcp", respectively, with the semantics for "coap+tcp" and "coaps+tcp", respectively, with the
exception that TCP, or TLS over TCP is used as a transport protocol. exception that TCP, or TLS over TCP is used as a transport protocol.
IANA is requested to add these new URI schemes to the registry IANA is requested to add these new URI schemes to the registry
established with [RFC7595]. established with [RFC7595].
8.4.1. coap+ws 8.5.1. coap+ws
This document requests the registration of the Uniform Resource This document requests the registration of the Uniform Resource
Identifier (URI) scheme "coap+ws". The registration request complies Identifier (URI) scheme "coap+ws". The registration request complies
with [RFC4395]. with [RFC4395].
URL scheme name. URL scheme name.
coap+ws coap+ws
Status. Status.
Permanent Permanent
skipping to change at page 30, line 16 skipping to change at page 32, line 5
Contact. Contact.
IETF chair <chair@ietf.org> IETF chair <chair@ietf.org>
Author/Change controller. Author/Change controller.
IESG <iesg@ietf.org> IESG <iesg@ietf.org>
References. References.
[RFCthis] [RFCthis]
8.4.2. coap+wss 8.5.2. coap+wss
This document requests the registration of the Uniform Resource This document requests the registration of the Uniform Resource
Identifier (URI) scheme "coap+wss". The registration request Identifier (URI) scheme "coap+wss". The registration request
complies with [RFC4395]. complies with [RFC4395].
URL scheme name. URL scheme name.
coap+wss coap+wss
Status. Status.
Permanent Permanent
skipping to change at page 31, line 4 skipping to change at page 32, line 42
The scheme is used by CoAP endpoints to access CoAP resources The scheme is used by CoAP endpoints to access CoAP resources
using the WebSocket protocol secured with TLS. using the WebSocket protocol secured with TLS.
Interoperability considerations. Interoperability considerations.
None. None.
Security Considerations. Security Considerations.
See Section N of [RFCthis] See Section N of [RFCthis]
Contact. Contact.
IETF chair <chair@ietf.org> IETF chair <chair@ietf.org>
Author/Change controller. Author/Change controller.
IESG <iesg@ietf.org> IESG <iesg@ietf.org>
References. References.
[RFCthis] [RFCthis]
8.5. Well-Known URI Suffix Registration 8.6. Well-Known URI Suffix Registration
IANA is requested to register the 'coap' well-known URI in the "Well- IANA is requested to register the 'coap' well-known URI in the "Well-
Known URIs" registry. This registration request complies with Known URIs" registry. This registration request complies with
[RFC5785]: [RFC5785]:
URI Suffix. URI Suffix.
coap coap
Change controller. Change controller.
IETF IETF
Specification document(s). Specification document(s).
[RFCthis] [RFCthis]
Related information. Related information.
None. None.
8.6. ALPN Protocol ID 8.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]: by [RFC7301]. The "coap" string identifies CoAP when used over TLS.
Protocol. Protocol.
CoAP CoAP
Identification Sequence. Identification Sequence.
0x63 0x6f 0x61 0x70 ("coap") 0x63 0x6f 0x61 0x70 ("coap")
Reference. Reference.
[RFCthis] [RFCthis]
8.7. WebSocket Subprotocol Registration 8.8. WebSocket Subprotocol Registration
IANA is requested to register the WebSocket CoAP subprotocol under IANA is requested to register the WebSocket CoAP subprotocol under
the "WebSocket Subprotocol Name Registry": the "WebSocket Subprotocol Name Registry":
Subprotocol Identifier. Subprotocol Identifier.
coap coap
Subprotocol Common Name. Subprotocol Common Name.
Constrained Application Protocol (CoAP) Constrained Application Protocol (CoAP)
Subprotocol Definition. Subprotocol Definition.
[RFCthis] [RFCthis]
9. References 9. References
9.1. Normative References 9.1. Normative References
[I-D.ietf-dice-profile]
Tschofenig, H. and T. Fossati, "TLS/DTLS Profiles for the
Internet of Things", draft-ietf-dice-profile-17 (work in
progress), October 2015.
[RFC0793] Postel, J., "Transmission Control Protocol", STD 7, RFC [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, RFC
793, DOI 10.17487/RFC0793, September 1981, 793, DOI 10.17487/RFC0793, September 1981,
<http://www.rfc-editor.org/info/rfc793>. <http://www.rfc-editor.org/info/rfc793>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/
RFC2119, March 1997, RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>. <http://www.rfc-editor.org/info/rfc2119>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
skipping to change at page 33, line 19 skipping to change at page 35, line 10
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252, DOI 10.17487/ Application Protocol (CoAP)", RFC 7252, DOI 10.17487/
RFC7252, June 2014, RFC7252, June 2014,
<http://www.rfc-editor.org/info/rfc7252>. <http://www.rfc-editor.org/info/rfc7252>.
[RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan,
"Transport Layer Security (TLS) Application-Layer Protocol "Transport Layer Security (TLS) Application-Layer Protocol
Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301,
July 2014, <http://www.rfc-editor.org/info/rfc7301>. July 2014, <http://www.rfc-editor.org/info/rfc7301>.
[RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre,
"Recommendations for Secure Use of Transport Layer
Security (TLS) and Datagram Transport Layer Security
(DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May
2015, <http://www.rfc-editor.org/info/rfc7525>.
[RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines
and Registration Procedures for URI Schemes", BCP 35, RFC and Registration Procedures for URI Schemes", BCP 35, RFC
7595, DOI 10.17487/RFC7595, June 2015, 7595, DOI 10.17487/RFC7595, June 2015,
<http://www.rfc-editor.org/info/rfc7595>. <http://www.rfc-editor.org/info/rfc7595>.
[RFC7641] Hartke, K., "Observing Resources in the Constrained [RFC7641] Hartke, K., "Observing Resources in the Constrained
Application Protocol (CoAP)", RFC 7641, DOI 10.17487/ Application Protocol (CoAP)", RFC 7641, DOI 10.17487/
RFC7641, September 2015, RFC7641, September 2015,
<http://www.rfc-editor.org/info/rfc7641>. <http://www.rfc-editor.org/info/rfc7641>.
[RFC7925] Tschofenig, H., Ed. and T. Fossati, "Transport Layer
Security (TLS) / Datagram Transport Layer Security (DTLS)
Profiles for the Internet of Things", RFC 7925, DOI
10.17487/RFC7925, July 2016,
<http://www.rfc-editor.org/info/rfc7925>.
9.2. Informative References 9.2. Informative References
[HomeGateway] [HomeGateway]
Eggert, L., "An experimental study of home gateway Eggert, L., "An experimental study of home gateway
characteristics", Proceedings of the 10th annual characteristics", Proceedings of the 10th annual
conference on Internet measurement, 2010. conference on Internet measurement, 2010.
[I-D.becker-core-coap-sms-gprs] [I-D.becker-core-coap-sms-gprs]
Becker, M., Li, K., Kuladinithi, K., and T. Poetsch, Becker, M., Li, K., Kuladinithi, K., and T. Poetsch,
"Transport of CoAP over SMS", draft-becker-core-coap-sms- "Transport of CoAP over SMS", draft-becker-core-coap-sms-
gprs-05 (work in progress), August 2014. gprs-05 (work in progress), August 2014.
[I-D.ietf-core-block] [I-D.ietf-core-block]
Bormann, C. and Z. Shelby, "Block-wise transfers in CoAP", Bormann, C. and Z. Shelby, "Block-wise transfers in CoAP",
draft-ietf-core-block-20 (work in progress), April 2016. draft-ietf-core-block-21 (work in progress), July 2016.
[LWM2M] Open Mobile Alliance, "Lightweight Machine to Machine
Technical Specification Candidate Version 1.0", April
2016, <http://technical.openmobilealliance.org/Technical/R
elease_Program/docs/LightweightM2M/V1_0-20160407-C/
OMA-TS-LightweightM2M-V1_0-20160407-C.pdf>.
[RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, DOI [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, DOI
10.17487/RFC0768, August 1980, 10.17487/RFC0768, August 1980,
<http://www.rfc-editor.org/info/rfc768>. <http://www.rfc-editor.org/info/rfc768>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/ Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/
RFC5234, January 2008, RFC5234, January 2008,
<http://www.rfc-editor.org/info/rfc5234>. <http://www.rfc-editor.org/info/rfc5234>.
skipping to change at page 38, line 14 skipping to change at page 40, line 14
Appendix C. Change Log Appendix C. Change Log
The RFC Editor is requested to remove this section at publication. The RFC Editor is requested to remove this section at publication.
C.1. Since draft-core-coap-tcp-tls-02 C.1. Since draft-core-coap-tcp-tls-02
Merged draft-savolainen-core-coap-websockets-07 Merged draft-bormann- Merged draft-savolainen-core-coap-websockets-07 Merged draft-bormann-
core-block-bert-01 Merged draft-bormann-core-coap-sig-02 core-block-bert-01 Merged draft-bormann-core-coap-sig-02
C.2. Since draft-core-coap-tcp-tls-03
Editorial updates
Added mandatory exchange of Capabilities and Settings messages after
connecting
Added support for coaps+tcp port 5684 and more details on
Application-Layer Protocol Negotiation (ALPN)
Added guidance on CoAP Signaling Ping-Pong versus WebSocket Ping-Pong
Updated references and requirements for TLS security considerations
Acknowledgements Acknowledgements
We would like to thank Stephen Berard, Geoffrey Cristallo, Olivier We would like to thank Stephen Berard, Geoffrey Cristallo, Olivier
Delaby, Christian Groves, Nadir Javed, Michael Koster, Matthias Delaby, Christian Groves, Nadir Javed, Michael Koster, Matthias
Kovatsch, Achim Kraus, David Navarro, Szymon Sasin, Zach Shelby, Kovatsch, Achim Kraus, David Navarro, Szymon Sasin, Zach Shelby,
Andrew Summers, Julien Vermillard, and Gengyu Wei for their feedback. Andrew Summers, Julien Vermillard, and Gengyu Wei for their feedback.
Contributors Contributors
Valik Solorzano Barboza Valik Solorzano Barboza
 End of changes. 38 change blocks. 
89 lines changed or deleted 161 lines changed or added

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