GENWiki

Premier IT Outsourcing and Support Services within the UK

User Tools

Site Tools


rfc:rfc8323

Internet Engineering Task Force (IETF) C. Bormann Request for Comments: 8323 Universitaet Bremen TZI Updates: 7641, 7959 S. Lemay Category: Standards Track Zebra Technologies ISSN: 2070-1721 H. Tschofenig

                                                              ARM Ltd.
                                                             K. Hartke
                                               Universitaet Bremen TZI
                                                         B. Silverajan
                                      Tampere University of Technology
                                                        B. Raymor, Ed.
                                                         February 2018

CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets

Abstract

 The Constrained Application Protocol (CoAP), although inspired by
 HTTP, was designed to use UDP instead of TCP.  The message layer of
 CoAP over UDP includes support for reliable delivery, simple
 congestion control, and flow control.
 Some environments benefit from the availability of CoAP carried over
 reliable transports such as TCP or Transport Layer Security (TLS).
 This document outlines the changes required to use CoAP over TCP,
 TLS, and WebSockets transports.  It also formally updates RFC 7641
 for use with these transports and RFC 7959 to enable the use of
 larger messages over a reliable transport.

Status of This Memo

 This is an Internet Standards Track document.
 This document is a product of the Internet Engineering Task Force
 (IETF).  It represents the consensus of the IETF community.  It has
 received public review and has been approved for publication by the
 Internet Engineering Steering Group (IESG).  Further information on
 Internet Standards is available in Section 2 of RFC 7841.
 Information about the current status of this document, any errata,
 and how to provide feedback on it may be obtained at
 https://www.rfc-editor.org/info/rfc8323.

Bormann, et al. Standards Track [Page 1] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

Copyright Notice

 Copyright (c) 2018 IETF Trust and the persons identified as the
 document authors.  All rights reserved.
 This document is subject to BCP 78 and the IETF Trust's Legal
 Provisions Relating to IETF Documents
 (https://trustee.ietf.org/license-info) in effect on the date of
 publication of this document.  Please review these documents
 carefully, as they describe your rights and restrictions with respect
 to this document.  Code Components extracted from this document must
 include Simplified BSD License text as described in Section 4.e of
 the Trust Legal Provisions and are provided without warranty as
 described in the Simplified BSD License.

Table of Contents

 1. Introduction ....................................................3
 2. Conventions and Terminology .....................................6
 3. CoAP over TCP ...................................................7
    3.1. Messaging Model ............................................7
    3.2. Message Format .............................................9
    3.3. Message Transmission ......................................11
    3.4. Connection Health .........................................12
 4. CoAP over WebSockets ...........................................13
    4.1. Opening Handshake .........................................15
    4.2. Message Format ............................................15
    4.3. Message Transmission ......................................16
    4.4. Connection Health .........................................17
 5. Signaling ......................................................17
    5.1. Signaling Codes ...........................................17
    5.2. Signaling Option Numbers ..................................18
    5.3. Capabilities and Settings Messages (CSMs) .................18
    5.4. Ping and Pong Messages ....................................20
    5.5. Release Messages ..........................................21
    5.6. Abort Messages ............................................23
    5.7. Signaling Examples ........................................24
 6. Block-Wise Transfer and Reliable Transports ....................25
    6.1. Example: GET with BERT Blocks .............................27
    6.2. Example: PUT with BERT Blocks .............................27
 7. Observing Resources over Reliable Transports ...................28
    7.1. Notifications and Reordering ..............................28
    7.2. Transmission and Acknowledgments ..........................28
    7.3. Freshness .................................................28
    7.4. Cancellation ..............................................29

Bormann, et al. Standards Track [Page 2] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 8. CoAP over Reliable Transport URIs ..............................29
    8.1. coap+tcp URI Scheme .......................................30
    8.2. coaps+tcp URI Scheme ......................................31
    8.3. coap+ws URI Scheme ........................................32
    8.4. coaps+ws URI Scheme .......................................33
    8.5. Uri-Host and Uri-Port Options .............................33
    8.6. Decomposing URIs into Options .............................34
    8.7. Composing URIs from Options ...............................35
 9. Securing CoAP ..................................................35
    9.1. TLS Binding for CoAP over TCP .............................36
    9.2. TLS Usage for CoAP over WebSockets ........................37
 10. Security Considerations .......................................37
    10.1. Signaling Messages .......................................37
 11. IANA Considerations ...........................................38
    11.1. Signaling Codes ..........................................38
    11.2. CoAP Signaling Option Numbers Registry ...................38
    11.3. Service Name and Port Number Registration ................40
    11.4. Secure Service Name and Port Number Registration .........40
    11.5. URI Scheme Registration ..................................41
    11.6. Well-Known URI Suffix Registration .......................43
    11.7. ALPN Protocol Identifier .................................44
    11.8. WebSocket Subprotocol Registration .......................44
    11.9. CoAP Option Numbers Registry .............................44
 12. References ....................................................45
    12.1. Normative References .....................................45
    12.2. Informative References ...................................47
 Appendix A. Examples of CoAP over WebSockets ......................49
 Acknowledgments ...................................................52
 Contributors ......................................................52
 Authors' Addresses ................................................53

1. Introduction

 The Constrained Application Protocol (CoAP) [RFC7252] was designed
 for Internet of Things (IoT) deployments, assuming that UDP [RFC768]
 can be used unimpeded as can the Datagram Transport Layer Security
 (DTLS) protocol [RFC6347] over UDP.  The use of CoAP over UDP is
 focused on simplicity, has a low code footprint, and has a small
 over-the-wire message size.
 The primary reason for introducing CoAP over TCP [RFC793] and TLS
 [RFC5246] is that some networks do not forward UDP packets.  Complete
 blocking of UDP happens in between about 2% and 4% of terrestrial
 access networks, according to [EK2016].  UDP impairment is especially
 concentrated in enterprise networks and networks in geographic
 regions with otherwise challenged connectivity.  Some networks also

Bormann, et al. Standards Track [Page 3] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 rate-limit UDP traffic, as reported in [BK2015], and deployment
 investigations related to the standardization of Quick UDP Internet
 Connections (QUIC) revealed numbers around 0.3% [SW2016].
 The introduction of CoAP over TCP also leads to some additional
 effects that may be desirable in a specific deployment:
 o  Where NATs are present along the communication path, CoAP over TCP
    leads to different NAT traversal behavior than CoAP over UDP.
    NATs often calculate expiration timers based on the
    transport-layer protocol being used by application protocols.
    Many NATs maintain TCP-based NAT bindings for longer periods based
    on the assumption that a transport-layer protocol, such as TCP,
    offers additional information about the session lifecycle.  UDP,
    on the other hand, does not provide such information to a NAT and
    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
    keepalive messages.
 o  TCP utilizes mechanisms for congestion control and flow control
    that are more sophisticated than the default mechanisms provided
    by CoAP over UDP; these TCP mechanisms are useful for the transfer
    of larger payloads.  (However, work is ongoing to add advanced
    congestion control to CoAP over UDP as well; see [CoCoA].)
 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 block-wise 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 round trips, increased RAM
 requirements, and larger packet sizes.  Developers implementing CoAP
 over TCP are encouraged to consult [TCP-in-IoT] for guidance on
 low-footprint TCP implementations for IoT devices.
 Standards based on CoAP, such as Lightweight Machine to Machine
 [LWM2M], currently use CoAP over UDP as a transport; adding support
 for CoAP over TCP enables them to address the issues above for
 specific deployments and to protect investments in existing CoAP
 implementations and deployments.
 Although HTTP/2 could also potentially address the need for
 enterprise firewall traversal, there would be additional costs and
 delays introduced by such a transition from CoAP to HTTP/2.
 Currently, there are also fewer HTTP/2 implementations available for

Bormann, et al. Standards Track [Page 4] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 constrained devices in comparison to CoAP.  Since CoAP also supports
 group communication using IP-layer multicast and unreliable
 communication, IoT devices would have to support HTTP/2 in addition
 to CoAP.
 Furthermore, CoAP may be integrated into a web environment where the
 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.
 Finally, CoAP applications running inside a web browser may be
 without access to connectivity other than HTTP.  In this case, the
 WebSocket Protocol [RFC6455] may be used to transport CoAP requests
 and responses, as opposed to cross-proxying them via HTTP to an
 HTTP-to-CoAP cross-proxy.  This preserves the functionality of CoAP
 without translation -- in particular, the Observe Option [RFC7641].
 To address the above-mentioned deployment requirements, this document
 defines how to transport CoAP over TCP, CoAP over TLS, and CoAP over
 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 for both a reliable
 transport and the message layer for CoAP over UDP, 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:
   +--------------------------------+
   |          Application           |
   +--------------------------------+
   +--------------------------------+
   |  Requests/Responses/Signaling  |  CoAP (RFC 7252) / This Document
   |--------------------------------|
   |        Message Framing         |  This Document
   +--------------------------------+
   |      Reliable Transport        |
   +--------------------------------+
          Figure 1: Layering of CoAP over Reliable Transports
 This document specifies how to access resources using CoAP requests
 and responses over the TCP, TLS, and WebSocket protocols.  This
 allows connectivity-limited applications to obtain end-to-end CoAP
 connectivity either (1) by communicating CoAP directly with a CoAP
 server accessible over a TCP, TLS, or WebSocket connection or (2) via
 a CoAP intermediary that proxies CoAP requests and responses between
 different transports, such as between WebSockets and UDP.

Bormann, et al. Standards Track [Page 5] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 Section 7 updates [RFC7641] ("Observing Resources in the Constrained
 Application Protocol (CoAP)") for use with CoAP over reliable
 transports.  [RFC7641] is an extension to CoAP that enables CoAP
 clients to "observe" a resource on a CoAP server.  (The CoAP client
 retrieves a representation of a resource and registers to be notified
 by the CoAP server when the representation is updated.)

2. Conventions and Terminology

 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
 "OPTIONAL" in this document are to be interpreted as described in
 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
 capitals, as shown here.
 This document assumes that readers are familiar with the terms and
 concepts that are used in [RFC6455], [RFC7252], [RFC7641], and
 [RFC7959].
 The term "reliable transport" is used only to refer to transport
 protocols, such as TCP, that provide reliable and ordered delivery of
 a byte stream.
 Block-wise Extension for Reliable Transport (BERT):
    Extends [RFC7959] to enable the use of larger messages over a
    reliable transport.
 BERT Option:
    A Block1 or Block2 option that includes an SZX (block size)
    value of 7.
 BERT Block:
    The payload of a CoAP message that is affected by a BERT Option in
    descriptive usage (see Section 2.1 of [RFC7959]).
 Transport Connection:
    Underlying reliable byte-stream connection, as directly provided
    by TCP or indirectly provided via TLS or WebSockets.
 Connection:
    Transport Connection, unless explicitly qualified otherwise.

Bormann, et al. Standards Track [Page 6] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 Connection Initiator:
    The peer that opens a Transport Connection, i.e., the TCP active
    opener, TLS client, or WebSocket client.
 Connection Acceptor:
    The peer that accepts the Transport Connection opened by the other
    peer, i.e., the TCP passive opener, TLS server, or WebSocket
    server.

3. CoAP over TCP

 The request/response interaction model of CoAP over TCP is the same
 as CoAP over UDP.  The primary differences are in the message layer.
 The message layer of CoAP over UDP supports optional reliability by
 defining four types of messages: Confirmable, Non-confirmable,
 Acknowledgment, and Reset.  In addition, messages include a
 Message ID to relate Acknowledgments to Confirmable messages and to
 detect duplicate messages.
 Management of the transport connections is left to the application,
 i.e., the present specification does not describe how an application
 decides to open a connection or to reopen 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.  Some
 implementations will want to implement dynamic connection management
 similar to the technique described in Section 6 of [RFC7230] for
 HTTP: opening a connection when the first client request is ready to
 be sent, reusing that connection for subsequent messages until no
 more messages are sent for a certain time period and no requests are
 outstanding (possibly with a configurable idle time), and then
 starting a release process (orderly shutdown) (see Section 5.5).  In
 implementations of this kind, connection releases or aborts may not
 be indicated as errors to the application but may simply be handled
 by automatic reconnection once the need arises again.  Other
 implementations may be based on configured connections that are kept
 open continuously and lead to management system notifications on
 release or abort.  The protocol defined in the present specification
 is intended to work with either model (or other, application-specific
 connection management models).

3.1. Messaging Model

 Conceptually, CoAP over TCP replaces most of the message layer of
 CoAP over UDP with a framing mechanism on top of the byte stream
 provided by TCP/TLS, conveying the length information for each
 message that, on datagram transports, is provided by the UDP/DTLS
 datagram layer.

Bormann, et al. Standards Track [Page 7] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 TCP ensures reliable message transmission, so the message layer of
 CoAP over TCP is not required to support Acknowledgment messages or
 to detect duplicate messages.  As a result, both the Type and
 Message ID fields are no longer required and are removed from the
 message format for CoAP over TCP.
 Figure 2 illustrates the difference between CoAP over UDP and CoAP
 over reliable transports.  The removed Type and Message ID fields are
 indicated by dashes.
    CoAP Client       CoAP Server     CoAP Client       CoAP Server
        |                    |            |                    |
        |   CON [0xbc90]     |            | (-------) [------] |
        | GET /temperature   |            | GET /temperature   |
        |   (Token 0x71)     |            |   (Token 0x71)     |
        +------------------->|            +------------------->|
        |                    |            |                    |
        |   ACK [0xbc90]     |            | (-------) [------] |
        |   2.05 Content     |            |   2.05 Content     |
        |   (Token 0x71)     |            |   (Token 0x71)     |
        |     "22.5 C"       |            |     "22.5 C"       |
        |<-------------------+            |<-------------------+
        |                    |            |                    |
            CoAP over UDP                   CoAP over reliable
                                                transports
   Figure 2: Comparison between CoAP over Unreliable Transports and
                     CoAP over Reliable Transports

Bormann, et al. Standards Track [Page 8] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

3.2. Message Format

 The CoAP message format defined in [RFC7252], as shown in Figure 3,
 relies on the datagram transport (UDP, or DTLS over UDP) for keeping
 the individual messages separate and for providing length
 information.
  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
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |Ver| T |  TKL  |      Code     |          Message ID           |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |   Token (if any, TKL bytes) ...
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |   Options (if any) ...
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |1 1 1 1 1 1 1 1|    Payload (if any) ...
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
         Figure 3: CoAP Message Format as Defined in RFC 7252
 The message format for CoAP over TCP is very similar to the format
 specified for CoAP over UDP.  The differences are as follows:
 o  Since the underlying TCP connection provides retransmissions and
    deduplication, there is no need for the reliability mechanisms
    provided by CoAP over UDP.  The Type (T) and Message ID fields in
    the CoAP message header are elided.
 o  The Version (Vers) field is elided as well.  In contrast to the
    message format of CoAP over UDP, the message format for CoAP over
    TCP does not include a version number.  CoAP is defined in
    [RFC7252] with a version number of 1.  At this time, there is no
    known reason to support version numbers different from 1.  If
    version negotiation needs to be addressed in the future,
    Capabilities and Settings Messages (CSMs) (see Section 5.3) have
    been specifically designed to enable such a potential feature.

Bormann, et al. Standards Track [Page 9] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 o  In a stream-oriented transport protocol such as TCP, a form of
    message delimitation is needed.  For this purpose, CoAP over TCP
    introduces a length field with variable size.  Figure 4 shows the
    adjusted CoAP message format with a modified structure for the
    fixed header (first 4 bytes of the header for CoAP over UDP),
    which includes the length information of variable size.
  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  |  TKL  | Extended Length (if any, as chosen by Len) ...
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |      Code     | Token (if any, TKL bytes) ...
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |  Options (if any) ...
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |1 1 1 1 1 1 1 1|    Payload (if any) ...
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
             Figure 4: CoAP Frame for Reliable Transports
 Length (Len):  4-bit unsigned integer.  A value between 0 and 12
    inclusive indicates the length of the message in bytes, starting
    with the first bit of the Options field.  Three values are
    reserved for special constructs:
    13:  An 8-bit unsigned integer (Extended Length) follows the
       initial byte and indicates the length of options/payload
       minus 13.
    14:  A 16-bit unsigned integer (Extended Length) in network byte
       order follows the initial byte and indicates the length of
       options/payload minus 269.
    15:  A 32-bit unsigned integer (Extended Length) in network byte
       order follows the initial byte and indicates the length of
       options/payload minus 65805.
 The encoding of the Length field is modeled after the Option Length
 field of the CoAP Options (see Section 3.1 of [RFC7252]).
 For simplicity, a Payload Marker (0xFF) is shown in Figure 4; the
 Payload Marker indicates the start of the optional payload and is
 absent for zero-length payloads (see Section 3 of [RFC7252]).  (If
 present, the Payload Marker is included in the message length, which
 counts from the start of the Options field to the end of the Payload
 field.)

Bormann, et al. Standards Track [Page 10] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 For example, a CoAP message just containing a 2.03 code with the
 Token 7f and no options or payload is encoded as shown in Figure 5.
  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
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |      0x01     |      0x43     |      0x7f     |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  Len   =    0 ------>  0x01
  TKL   =    1 ___/
  Code  =  2.03     --> 0x43
  Token =               0x7f
           Figure 5: CoAP Message with No Options or Payload
 The semantics of the other CoAP header fields are left unchanged.

3.3. Message Transmission

 Once a Transport Connection is established, each endpoint MUST send a
 CSM (see Section 5.3) as its first message on the connection.  This
 message establishes the initial settings and capabilities for the
 endpoint, such as maximum message size or support for block-wise
 transfers.  The absence of options in the CSM indicates that base
 values are assumed.
 To avoid a deadlock, the Connection Initiator MUST NOT wait for the
 Connection Acceptor to send its initial CSM before sending its own
 initial CSM.  Conversely, the Connection Acceptor MAY wait for the
 Connection Initiator to send its initial CSM before sending its own
 initial CSM.
 To avoid unnecessary latency, a Connection Initiator MAY send
 additional messages after its initial CSM without waiting to receive
 the Connection Acceptor's CSM; however, it is important to note that
 the Connection Acceptor's CSM might indicate capabilities that impact
 how the Connection Initiator is expected to communicate with the
 Connection Acceptor.  For example, the Connection Acceptor's CSM
 could indicate a Max-Message-Size Option (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.

Bormann, et al. Standards Track [Page 11] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 Endpoints MUST treat a missing or invalid CSM as a connection error
 and abort the connection (see Section 5.6).
 CoAP requests and responses are exchanged asynchronously over the
 Transport Connection.  A CoAP client can send multiple requests
 without waiting for a response, and the CoAP server can return
 responses in any order.  Responses MUST be returned over the same
 connection as the originating request.  Each concurrent request is
 differentiated by its Token, which is scoped locally to the
 connection.
 The Transport Connection is bidirectional, so requests can be sent by
 both the entity that established the connection (Connection
 Initiator) and the remote host (Connection Acceptor).  If one side
 does not implement a CoAP server, an error response MUST be returned
 for all CoAP requests from the other side.  The simplest approach is
 to always return 5.01 (Not Implemented).  A more elaborate mock
 server could also return 4.xx responses such as 4.04 (Not Found) or
 4.02 (Bad Option) where appropriate.
 Retransmission and deduplication of messages are provided by TCP.

3.4. Connection Health

 Empty messages (Code 0.00) can always be sent and MUST be ignored by
 the recipient.  This provides a basic keepalive function that can
 refresh NAT bindings.
 If a CoAP client does not receive any response for some time after
 sending a CoAP request (or, similarly, when a client observes a
 resource and it does not receive any notification for some time), it
 can send a CoAP Ping Signaling message (see Section 5.4) to test the
 Transport Connection and verify that the CoAP server is responsive.
 When the underlying Transport Connection is closed or reset, the
 signaling state and any observation state (see Section 7.4)
 associated with the connection are removed.  Messages that are
 in flight may or may not be lost.

Bormann, et al. Standards Track [Page 12] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

4. CoAP over WebSockets

 CoAP over WebSockets is intentionally similar to CoAP over TCP;
 therefore, this section only specifies the differences between the
 transports.
 CoAP over WebSockets can be used in a number of configurations.  The
 most basic configuration is a CoAP client retrieving or updating a
 CoAP resource located on a CoAP server that exposes a WebSocket
 endpoint (see Figure 6).  The CoAP client acts as the WebSocket
 client, establishes a WebSocket connection, and sends a CoAP request,
 to which the CoAP server returns a CoAP response.  The WebSocket
 connection can be used for any number of requests.
          ___________                            ___________
         |           |                          |           |
         |          _|___      requests      ___|_          |
         |   CoAP  /  \  \  ------------->  /  /  \  CoAP   |
         |  Client \__/__/  <-------------  \__\__/ Server  |
         |           |         responses        |           |
         |___________|                          |___________|
                 WebSocket  =============>  WebSocket
                   Client     Connection     Server
     Figure 6: CoAP Client (WebSocket Client) Accesses CoAP Server
                          (WebSocket Server)
 The challenge with this configuration is how to identify a resource
 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
 through a web browser), the client can connect to any WebSocket
 endpoint.  Sections 8.3 and 8.4 define new URI schemes that enable
 the client to identify both a WebSocket endpoint and the path and
 query of the CoAP resource within that endpoint.

Bormann, et al. Standards Track [Page 13] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 Another possible configuration is to set up a CoAP forward proxy at
 the WebSocket endpoint.  Depending on what transports are available
 to the proxy, it could forward the request to a CoAP server with a
 CoAP UDP endpoint (Figure 7), an SMS endpoint (a.k.a. mobile phone),
 or even another WebSocket endpoint.  The CoAP client specifies the
 resource to be updated or retrieved in the Proxy-Uri Option.
   ___________                ___________                ___________
  |           |              |           |              |           |
  |          _|___        ___|_         _|___        ___|_          |
  |   CoAP  /  \  \ ---> /  /  \ CoAP  /  \  \ ---> /  /  \  CoAP   |
  |  Client \__/__/ <--- \__\__/ Proxy \__/__/ <--- \__\__/ Server  |
  |           |              |           |              |           |
  |___________|              |___________|              |___________|
          WebSocket ===> WebSocket      UDP            UDP
            Client        Server      Client          Server
     Figure 7: CoAP Client (WebSocket Client) Accesses CoAP Server
     (UDP Server) via a CoAP Proxy (WebSocket Server / UDP Client)
 A third possible configuration is a CoAP server running inside a web
 browser (Figure 8).  The web browser initially connects to a
 WebSocket endpoint and is then reachable through the WebSocket
 server.  When no connection exists, the CoAP server is unreachable.
 Because the WebSocket server is the only way to reach the CoAP
 server, the CoAP proxy should be a reverse-proxy.
   ___________                ___________                ___________
  |           |              |           |              |           |
  |          _|___        ___|_         _|___        ___|_          |
  |   CoAP  /  \  \ ---> /  /  \ CoAP  /  /  \ ---> /  \  \  CoAP   |
  |  Client \__/__/ <--- \__\__/ Proxy \__\__/ <--- \__/__/ Server  |
  |           |              |           |              |           |
  |___________|              |___________|              |___________|
             UDP            UDP      WebSocket <=== WebSocket
           Client          Server      Server        Client
  Figure 8: CoAP Client (UDP Client) Accesses CoAP Server (WebSocket
       Client) via a CoAP Proxy (UDP Server / WebSocket Server)
 Further configurations are possible, including those where a
 WebSocket connection is established through an HTTP proxy.

Bormann, et al. Standards Track [Page 14] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

4.1. Opening Handshake

 Before CoAP requests and responses are exchanged, a WebSocket
 connection is established as defined in Section 4 of [RFC6455].
 Figure 9 shows an example.
 The WebSocket client MUST include the subprotocol name "coap" in the
 list of protocols; this indicates support for the protocol defined in
 this document.
 The WebSocket client includes the hostname of the WebSocket server in
 the Host header field of its handshake as per [RFC6455].  The Host
 header field also indicates the default value of the Uri-Host Option
 in requests from the WebSocket client to the WebSocket server.
          GET /.well-known/coap HTTP/1.1
          Host: example.org
          Upgrade: websocket
          Connection: Upgrade
          Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
          Sec-WebSocket-Protocol: coap
          Sec-WebSocket-Version: 13
          HTTP/1.1 101 Switching Protocols
          Upgrade: websocket
          Connection: Upgrade
          Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
          Sec-WebSocket-Protocol: coap
               Figure 9: Example of an Opening Handshake

4.2. Message Format

 Once a WebSocket connection is established, CoAP requests and
 responses can be exchanged as WebSocket messages.  Since CoAP uses a
 binary message format, the messages are transmitted in binary data
 frames as specified in Sections 5 and 6 of [RFC6455].

Bormann, et al. Standards Track [Page 15] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 The message format shown in Figure 10 is the same as the message
 format for CoAP over TCP (see Section 3.2), with one change: the
 Length (Len) field MUST be set to zero, because the WebSocket frame
 contains the length.
    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=0 |  TKL  |      Code     |    Token (TKL bytes) ...
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |   Options (if any) ...
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |1 1 1 1 1 1 1 1|    Payload (if any) ...
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
            Figure 10: CoAP Message Format 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
 version negotiation is required in the future, CoAP over WebSockets
 can address the requirement by defining a new subprotocol identifier
 that is negotiated during the opening handshake.
 Requests and responses can be fragmented as specified in Section 5.4
 of [RFC6455], though typically they are sent unfragmented, as they
 tend to be small and fully buffered before transmission.  The
 WebSocket Protocol does not provide means for multiplexing.  If it is
 not desirable for a large message to monopolize the connection,
 requests and responses can be transferred in a block-wise fashion as
 defined in [RFC7959].

4.3. Message Transmission

 As with CoAP over TCP, each endpoint MUST send a CSM (see
 Section 5.3) as its first message on the WebSocket connection.
 CoAP requests and responses are exchanged asynchronously over the
 WebSocket connection.  A CoAP client can send multiple requests
 without waiting for a response, and the CoAP server can return
 responses in any order.  Responses MUST be returned over the same
 connection as the originating request.  Each concurrent request is
 differentiated by its Token, which is scoped locally to the
 connection.
 The connection is bidirectional, so requests can be sent by both the
 entity that established the connection and the remote host.

Bormann, et al. Standards Track [Page 16] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 As with CoAP over TCP, retransmission and deduplication of messages
 are provided by the WebSocket Protocol.  CoAP over WebSockets
 therefore does not make a distinction between Confirmable messages
 and Non-confirmable messages and does not provide Acknowledgment or
 Reset messages.

4.4. Connection Health

 As with CoAP over TCP, a CoAP client can test the health of the
 connection for CoAP over WebSockets by sending a CoAP Ping Signaling
 message (Section 5.4).  To ensure that redundant maintenance traffic
 is not transmitted, WebSocket Ping and unsolicited Pong frames
 (Section 5.5 of [RFC6455]) SHOULD NOT be used.

5. Signaling

 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
    the connection.
 o  Shut down the connection in an orderly fashion.
 o  Provide diagnostic information when terminating a connection in
    response to a serious error condition.
 Signaling is a third basic kind of message in CoAP, after requests
 and responses.  Signaling messages share a common structure with the
 existing CoAP messages.  There are a code, a Token, options, and an
 optional payload.
 (See Section 3 of [RFC7252] for the overall structure of the message
 format, option format, and option value formats.)

5.1. Signaling Codes

 A code in the 7.00-7.31 range indicates a Signaling message.  Values
 in this range are assigned by the "CoAP Signaling Codes" subregistry
 (see Section 11.1).
 For each message, there are a sender and a peer receiving the
 message.
 Payloads in Signaling messages are diagnostic payloads as defined in
 Section 5.5.2 of [RFC7252], unless otherwise defined by a Signaling
 message option.

Bormann, et al. Standards Track [Page 17] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

5.2. Signaling Option Numbers

 Option Numbers for Signaling messages are specific to the message
 code.  They do not share the number space with CoAP options for
 request/response messages or with Signaling messages using other
 codes.
 Option Numbers are assigned by the "CoAP Signaling Option Numbers"
 subregistry (see Section 11.2).
 Signaling Options are elective or critical as defined in
 Section 5.4.1 of [RFC7252].  If a Signaling Option is critical and
 not understood by the receiver, it MUST abort the connection (see
 Section 5.6).  If the option is understood but cannot be processed,
 the option documents the behavior.

5.3. Capabilities and Settings Messages (CSMs)

 CSMs are used for two purposes:
 o  Each capability option indicates one capability of the sender to
    the recipient.
 o  Each setting option indicates a setting that will be applied by
    the sender.
 One CSM MUST be sent by each endpoint at the start of the Transport
 Connection.  Additional CSMs MAY be sent at any other time by either
 endpoint over the lifetime of the connection.
 Both capability options and setting options are cumulative.  A CSM
 does not invalidate a previously sent 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 such).  An option that
 is sent might override a previous value for the same option.  The
 option defines how to handle this case if needed.
 Base values are listed below for CSM options.  These are the values
 for the capability and settings before any CSMs send a modified
 value.
 These are not default values (as defined in Section 5.4.4 in
 [RFC7252]) for the option.  Default values apply on a per-message
 basis and are thus reset when the value is not present in a
 given CSM.
 CSMs are indicated by the 7.01 (CSM) code; see Table 1
 (Section 11.1).

Bormann, et al. Standards Track [Page 18] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

5.3.1. Max-Message-Size Capability Option

 The sender can use the elective Max-Message-Size Option to indicate
 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.
 (Note that there is no relationship of the message size to the
 overall request or response body size that may be achievable in
 block-wise transfer.  For example, the exchange depicted in Figure 13
 (Section 6.1) can be performed if the CoAP client indicates a value
 of around 6000 bytes for the Max-Message-Size Option, even though the
 total body size transferred to the client is 3072 + 5120 + 4711 =
 12903 bytes.)
 +---+---+---+---------+------------------+--------+--------+--------+
 | # | C | R | Applies | Name             | Format | Length | Base   |
 |   |   |   | to      |                  |        |        | Value  |
 +---+---+---+---------+------------------+--------+--------+--------+
 | 2 |   |   | CSM     | Max-Message-Size |   uint |    0-4 | 1152   |
 +---+---+---+---------+------------------+--------+--------+--------+
                       C=Critical, R=Repeatable
 As per Section 4.6 of [RFC7252], the base value (and the value used
 when this option is not implemented) is 1152.
 The active value of the Max-Message-Size Option is replaced each time
 the option is sent with a modified value.  Its starting value is its
 base value.

5.3.2. Block-Wise-Transfer Capability Option

 +---+---+---+---------+------------------+--------+--------+--------+
 | # | C | R | Applies | Name             | Format | Length | Base   |
 |   |   |   | to      |                  |        |        | Value  |
 +---+---+---+---------+------------------+--------+--------+--------+
 | 4 |   |   | CSM     | Block-Wise-      |  empty |      0 | (none) |
 |   |   |   |         | Transfer         |        |        |        |
 +---+---+---+---------+------------------+--------+--------+--------+
                       C=Critical, R=Repeatable
 A sender can use the elective Block-Wise-Transfer Option to indicate
 that it supports the block-wise transfer protocol [RFC7959].

Bormann, et al. Standards Track [Page 19] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 If the option is not given, the peer has no information about whether
 block-wise transfers are supported by the sender or not.  An
 implementation wishing to offer block-wise transfers to its peer
 therefore needs to indicate so via the Block-Wise-Transfer Option.
 If a Max-Message-Size Option is indicated with a value that is
 greater than 1152 (in the same CSM or a different CSM), the
 Block-Wise-Transfer Option also indicates support for BERT (see
 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 the indication of BERT support does not
 oblige either 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 (1) choose a particular BERT block size it
 wants to encourage and (2) add a delta for the header and any options
 that may also need to be included in the message with a BERT block of
 that size.  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 with the size of the header and options added (say, 256 or
 512).  However, adding 1024 or more 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; this type of scenario might make
 it harder to establish interoperability.

5.4. Ping and Pong Messages

 In CoAP over reliable transports, Empty messages (Code 0.00) can
 always be sent and MUST be ignored by the recipient.  This provides a
 basic keepalive function.  In contrast, Ping and Pong messages are a
 bidirectional exchange.
 Upon receipt of a Ping message, the receiver MUST return a Pong
 message with an identical Token in response.  Unless the Ping carries
 an option with delaying semantics such as the Custody Option, it
 SHOULD respond as soon as practical.  As with all Signaling messages,
 the recipient of a Ping or Pong message MUST ignore elective options
 it does not understand.
 Ping and Pong messages are indicated by the 7.02 code (Ping) and
 the 7.03 code (Pong).

Bormann, et al. Standards Track [Page 20] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 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 when
 waiting for a Pong reply.  Any limitations on 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

 +---+---+---+----------+----------------+--------+--------+---------+
 | # | C | R | Applies  | Name           | Format | Length | Base    |
 |   |   |   | to       |                |        |        | Value   |
 +---+---+---+----------+----------------+--------+--------+---------+
 | 2 |   |   | Ping,    | Custody        |  empty |      0 | (none)  |
 |   |   |   | Pong     |                |        |        |         |
 +---+---+---+----------+----------------+--------+--------+---------+
                       C=Critical, R=Repeatable
 When responding to a Ping message, the receiver can include an
 elective Custody Option in the Pong message.  This option indicates
 that the application has processed all the request/response messages
 received prior to the Ping message on the current connection.  (Note
 that there is no definition of specific application semantics for
 "processed", but there is an expectation that the receiver of a Pong
 message with a Custody Option should be able to free buffers based on
 this indication.)
 A sender can also include an elective Custody Option in a Ping
 message to explicitly request the inclusion of an elective Custody
 Option in the corresponding Pong message.  In that case, the receiver
 SHOULD delay its Pong message until it finishes processing all the
 request/response messages received prior to the Ping message on the
 current connection.

5.5. Release Messages

 A Release message indicates that the sender does not want to continue
 maintaining the Transport Connection and opts for an orderly
 shutdown, but wants to leave it to the peer to actually start closing
 the connection.  The 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 Release message by closing the
 Transport Connection.  (In case that does not happen, the sender of
 the release may want to implement a timeout mechanism if getting rid
 of the connection is actually important to it.)

Bormann, et al. Standards Track [Page 21] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 Messages may be in flight or responses outstanding when the sender
 decides to send a Release message (which is one reason the sender had
 decided to wait before closing the connection).  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.
 It is NOT RECOMMENDED for the sender of a Release message to continue
 sending requests on the connection it already indicated to be
 released: the peer might close the connection at any time and miss
 those requests.  The peer is not obligated to check for this
 condition, though.
 Release messages are indicated by the 7.04 code (Release).
 Release messages can indicate one or more reasons using elective
 options.  The following options are defined:
 +---+---+---+---------+------------------+--------+--------+--------+
 | # | C | R | Applies | Name             | Format | Length | Base   |
 |   |   |   | to      |                  |        |        | Value  |
 +---+---+---+---------+------------------+--------+--------+--------+
 | 2 |   | x | Release | Alternative-     | string |  1-255 | (none) |
 |   |   |   |         | Address          |        |        |        |
 +---+---+---+---------+------------------+--------+--------+--------+
                       C=Critical, R=Repeatable
 The elective Alternative-Address Option requests the peer to instead
 open a connection of the same scheme as the present connection to the
 alternative transport address given.  Its value is in the form
 "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.)

Bormann, et al. Standards Track [Page 22] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 The Alternative-Address Option is a repeatable option as defined in
 Section 5.4.5 of [RFC7252].  When multiple occurrences of the option
 are included, the peer can choose any of the alternative transport
 addresses.
 +---+---+---+---------+-----------------+--------+--------+---------+
 | # | C | R | Applies | Name            | Format | Length | Base    |
 |   |   |   | to      |                 |        |        | Value   |
 +---+---+---+---------+-----------------+--------+--------+---------+
 | 4 |   |   | Release | Hold-Off        |   uint |    0-3 | (none)  |
 +---+---+---+---------+-----------------+--------+--------+---------+
                       C=Critical, R=Repeatable
 The elective Hold-Off Option indicates that the server is requesting
 that the peer not reconnect to it for the number of seconds given in
 the value.

5.6. Abort Messages

 An Abort message indicates that the sender is unable to continue
 maintaining the Transport Connection and cannot even wait for an
 orderly release.  The sender shuts down the connection immediately
 after the Abort message (and may or may not wait for a Release
 message, Abort message, or connection shutdown in the inverse
 direction).  A diagnostic payload (see Section 5.5.2 of [RFC7252])
 SHOULD be included in the Abort message.  Messages may be in flight
 or responses outstanding when the sender decides to send an Abort
 message.  The general expectation is that these will NOT be
 processed.
 Abort messages are indicated by the 7.05 code (Abort).
 Abort messages can indicate one or more reasons using elective
 options.  The following option is defined:
 +---+---+---+---------+-----------------+--------+--------+---------+
 | # | C | R | Applies | Name            | Format | Length | Base    |
 |   |   |   | to      |                 |        |        | Value   |
 +---+---+---+---------+-----------------+--------+--------+---------+
 | 2 |   |   | Abort   | Bad-CSM-Option  |   uint |    0-2 | (none)  |
 +---+---+---+---------+-----------------+--------+--------+---------+
                       C=Critical, R=Repeatable

Bormann, et al. Standards Track [Page 23] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 Bad-CSM-Option, which is elective, indicates that the sender is
 unable to process the CSM option identified by its Option Number,
 e.g., when it is critical and the Option Number is unknown by the
 sender, or when there is a parameter problem with the value of an
 elective option.  More detailed information SHOULD be included as a
 diagnostic payload.
 For CoAP over UDP, messages that contain syntax violations are
 processed as message format errors.  As described in Sections 4.2 and
 4.3 of [RFC7252], such messages are rejected by sending a matching
 Reset message and otherwise ignoring the message.
 For CoAP over reliable transports, the recipient rejects such
 messages by sending an Abort message and otherwise ignoring (not
 processing) the message.  No specific Option has been defined for the
 Abort message in this case, as the details are best left to a
 diagnostic payload.

5.7. Signaling Examples

 An encoded example of a Ping message with a non-empty Token is shown
 in Figure 11.
     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
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |      0x01     |      0xe2     |      0x42     |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     Len   =    0 -------> 0x01
     TKL   =    1 ___/
     Code  = 7.02 Ping --> 0xe2
     Token =               0x42
                    Figure 11: Ping Message Example

Bormann, et al. Standards Track [Page 24] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 An encoded example of the corresponding Pong message is shown in
 Figure 12.
     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
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |      0x01     |      0xe3     |      0x42     |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     Len   =    0 -------> 0x01
     TKL   =    1 ___/
     Code  = 7.03 Pong --> 0xe3
     Token =               0x42
                    Figure 12: Pong Message Example

6. Block-Wise Transfer and Reliable Transports

 The message size restrictions defined in Section 4.6 of [RFC7252] to
 avoid IP fragmentation are not necessary when CoAP is used over a
 reliable transport.  While this suggests that the block-wise transfer
 protocol [RFC7959] is also no longer needed, it remains applicable
 for a number of cases:
 o  Large messages, such as firmware downloads, may cause undesired
    head-of-line blocking when a single transport connection is used.
 o  A UDP-to-TCP gateway may simply not have the context to convert a
    message with a Block Option into the equivalent exchange without
    any use of a Block Option (it would need to convert the entire
    block-wise exchange from start to end into a single exchange).
 BERT extends the block-wise transfer protocol to enable the use of
 larger messages over a reliable transport.
 The use of this new extension is signaled by sending Block1 or Block2
 Options with SZX == 7 (a "BERT Option").  SZX == 7 is a reserved
 value in [RFC7959].
 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
 capability to process BERT blocks.  As with the basic block-wise
 transfer protocol, 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-BERT block instead.

Bormann, et al. Standards Track [Page 25] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 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
 allowed to contain multiple blocks.  For non-final BERT blocks, the
 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 payload into a sequence of 1024-byte blocks and acts exactly as
 if it had received this sequence in conjunction with block numbers
 starting at, and sequentially increasing from, the block number given
 in the Block Option.  In other words, the entire BERT block is
 positioned at the byte position that results from multiplying the
 block number by 1024.  The position of further blocks to be
 transferred is indicated by incrementing the block number by the
 number of elements in this sequence (i.e., the size of the payload
 divided by 1024 bytes).
 As with SZX == 6, the recipient of a final BERT block (M=0) simply
 appends the payload at the byte position that is indicated by the
 block number multiplied by 1024.
 The following examples illustrate BERT Options.  A value of SZX == 7
 is labeled as "BERT" or as "BERT(nnn)" to indicate a payload of
 size nnn.
 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
 (NUM), the more bit (M), and the block size (2**(SZX + 4)) separated
 by slashes.  For example, 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
 1:3/1/128.

Bormann, et al. Standards Track [Page 26] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

6.1. Example: GET with BERT Blocks

 Figure 13 shows a GET request with a response that is split into
 three BERT blocks.  The first response contains 3072 bytes of
 payload; the second, 5120; and the third, 4711.  Note how the block
 number increments to move the position inside the response body
 forward.
 CoAP Client                             CoAP Server
   |                                            |
   | GET, /status                       ------> |
   |                                            |
   | <------   2.05 Content, 2:0/1/BERT(3072)   |
   |                                            |
   | GET, /status, 2:3/0/BERT           ------> |
   |                                            |
   | <------   2.05 Content, 2:3/1/BERT(5120)   |
   |                                            |
   | GET, /status, 2:8/0/BERT          ------>  |
   |                                            |
   | <------   2.05 Content, 2:8/0/BERT(4711)   |
                    Figure 13: GET with BERT Blocks

6.2. Example: PUT with BERT Blocks

 Figure 14 demonstrates a PUT exchange with BERT blocks.
 CoAP Client                             CoAP Server
   |                                             |
   | PUT, /options, 1:0/1/BERT(8192)     ------> |
   |                                             |
   | <------   2.31 Continue, 1:0/1/BERT         |
   |                                             |
   | PUT, /options, 1:8/1/BERT(16384)    ------> |
   |                                             |
   | <------   2.31 Continue, 1:8/1/BERT         |
   |                                             |
   | PUT, /options, 1:24/0/BERT(5683)    ------> |
   |                                             |
   | <------   2.04 Changed, 1:24/0/BERT         |
   |                                             |
                    Figure 14: PUT with BERT Blocks

Bormann, et al. Standards Track [Page 27] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

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 [RFC7641] 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 TCP 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 Acknowledgments

 For CoAP over UDP, server notifications to the client can be
 Confirmable or Non-confirmable.  A Confirmable message requires the
 client to respond with either an Acknowledgment message or a Reset
 message.  An Acknowledgment 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; this 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 acknowledgment 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 can 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

Bormann, et al. Standards Track [Page 28] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 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: a proxy is not obligated or expected to react
 to a Ping by checking all its own registered interests or all the
 connections, if any, underlying them.  A proxy MAY maintain its own
 schedule for confirming the interests that it relies on being
 registered toward the origin server; however, it is 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 canceled 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 either
 times out or is closed.

8. CoAP over Reliable Transport URIs

 CoAP over UDP [RFC7252] defines the "coap" and "coaps" URI schemes.
 This document introduces four additional URI schemes for identifying
 CoAP resources and providing a means of locating the resource:
 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.

Bormann, et al. Standards Track [Page 29] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 In this section, the syntax for the URI schemes is specified using
 the Augmented Backus-Naur Form (ABNF) [RFC5234].  The definitions of
 "host", "port", "path-abempty", and "query" are adopted from
 [RFC3986].
 Section 8 ("Multicast CoAP") in [RFC7252] is not applicable to these
 schemes.
 As with the "coap" and "coaps" schemes defined in [RFC7252], all URI
 schemes defined in this section also support the path prefix
 "/.well-known/" as defined by [RFC5785] for "well-known locations" in
 the namespace of a host.  This enables discovery as per Section 7 of
 [RFC7252].

8.1. coap+tcp URI Scheme

 The "coap+tcp" URI scheme identifies CoAP resources that are intended
 to be accessible using CoAP over TCP.
   coap-tcp-URI = "coap+tcp:" "//" host [ ":" port ]
     path-abempty [ "?" query ]
 The syntax defined in Section 6.1 of [RFC7252] applies to this URI
 scheme, with the following change:
 o  The port subcomponent indicates the TCP port at which the CoAP
    Connection Acceptor is located.  (If it is empty or not given,
    then the default port 5683 is assumed, as with UDP.)
 Encoding considerations:  The scheme encoding conforms to the
    encoding rules established for URIs in [RFC3986].
 Interoperability considerations:  None.
 Security considerations:  See Section 11.1 of [RFC7252].

Bormann, et al. Standards Track [Page 30] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

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
    server for the CoAP Connection Acceptor is located.  If it is
    empty or not given, then the default port 5684 is assumed.
 o  If a TLS server does not support the Application-Layer Protocol
    Negotiation (ALPN) extension [RFC7301] or wishes to accommodate
    TLS 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 TLS 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 TLS client MUST use the
    ALPN extension to advertise the "coap" protocol identifier (see
    Section 11.7) in the list of protocols in its ClientHello.  If the
    TCP server selects and returns the "coap" protocol identifier
    using the ALPN extension in its ServerHello, then the connection
    succeeds.  If the TLS server either does not negotiate the ALPN
    extension or returns a no_application_protocol alert, the TLS
    client MUST close the connection.
 o  For TCP port 5684, a TLS client MAY use the ALPN extension to
    advertise the "coap" protocol identifier in the list of protocols
    in its ClientHello.  If the TLS server selects and returns the
    "coap" protocol identifier using the ALPN extension in its
    ServerHello, then the connection succeeds.  If the TLS server
    returns a no_application_protocol alert, then the TLS client MUST
    close the connection.  If the TLS server does not negotiate the
    ALPN extension, then coaps+tcp is implicitly selected.
 o  For TCP port 5684, if the TLS client does not use the ALPN
    extension to negotiate the protocol, then coaps+tcp is implicitly
    selected.

Bormann, et al. Standards Track [Page 31] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 Encoding considerations:  The scheme encoding conforms to the
    encoding rules established for URIs in [RFC3986].
 Interoperability considerations:  None.
 Security considerations:  See Section 11.1 of [RFC7252].

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
 of the authority part of the "coap+ws" URI and the well-known path
 "/.well-known/coap" [RFC5785] [RFC8307].  Within the endpoint
 specified in a "coap+ws" URI, the path and query parts of the URI
 identify a resource that can be operated on by the methods defined
 by CoAP:
           coap+ws://example.org/sensors/temperature?u=Cel
                \______  ______/\___________  ___________/
                       \/                   \/
                                          Uri-Path: "sensors"
     ws://example.org/.well-known/coap    Uri-Path: "temperature"
                                          Uri-Query: "u=Cel"
                  Figure 15: The "coap+ws" URI Scheme
 Encoding considerations:  The scheme encoding conforms to the
    encoding rules established for URIs in [RFC3986].
 Interoperability considerations:  None.
 Security considerations:  See Section 11.1 of [RFC7252].

Bormann, et al. Standards Track [Page 32] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

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
 of the authority part of the "coaps+ws" URI and the well-known path
 "/.well-known/coap" [RFC5785] [RFC8307].  Within the endpoint
 specified in a "coaps+ws" URI, the path and query parts of the URI
 identify a resource that can be operated on by the methods defined
 by CoAP:
           coaps+ws://example.org/sensors/temperature?u=Cel
                 \______  ______/\___________  ___________/
                        \/                   \/
                                          Uri-Path: "sensors"
     wss://example.org/.well-known/coap   Uri-Path: "temperature"
                                          Uri-Query: "u=Cel"
                 Figure 16: The "coaps+ws" URI Scheme
 Encoding considerations:  The scheme encoding conforms to the
    encoding rules established for URIs in [RFC3986].
 Interoperability considerations:  None.
 Security considerations:  See Section 11.1 of [RFC7252].

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
    sufficient for requests to most servers.
 Unless otherwise noted, the default value of the Uri-Host Option is
 the IP literal representing the destination IP address of the request
 message.  The default value of the Uri-Port Option is the destination
 TCP port.

Bormann, et al. Standards Track [Page 33] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 For CoAP over TLS, these default values are the same, unless Server
 Name Indication (SNI) [RFC6066] is negotiated.  In this case, the
 default value of the Uri-Host Option in requests from the TLS client
 to the TLS server is the SNI host.
 For CoAP over WebSockets, the default value of the Uri-Host Option in
 requests from the WebSocket client to the WebSocket server is
 indicated by the Host header field from the WebSocket handshake.

8.6. Decomposing URIs into Options

 The steps are the same as those specified in Section 6.4 of
 [RFC7252], with minor changes:
 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,
     include a Uri-Port Option and let that option's value be |port|.
 is updated to:
 7.  If |port| does not equal the request's destination TCP port,
     include a Uri-Port Option and let that option's value be |port|.

Bormann, et al. Standards Track [Page 34] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

8.7. Composing URIs from Options

 The steps are the same as those specified in Section 6.5 of
 [RFC7252], with minor changes:
 This step from [RFC7252]:
 1.  If the request is secured using DTLS, let |url| be the string
     "coaps://".  Otherwise, let |url| be the string "coap://".
 is updated to:
 1.  For CoAP over TCP, if the request is secured using TLS, let |url|
     be the string "coaps+tcp://".  Otherwise, let |url| be the string
     "coap+tcp://".  For CoAP over WebSockets, if the request is
     secured using TLS, let |url| be the string "coaps+ws://".
     Otherwise, let |url| be the string "coap+ws://".
 This step from [RFC7252]:
 4.  If the request includes a Uri-Port Option, let |port| be that
     option's value.  Otherwise, let |port| be the request's
     destination UDP port.
 is updated to:
 4.  If the request includes a Uri-Port Option, let |port| be that
     option's value.  Otherwise, let |port| be the request's
     destination TCP port.

9. Securing CoAP

 "Security Challenges For the Internet Of Things" [SecurityChallenges]
 recommends the following:
    ... it is essential that IoT protocol suites specify a mandatory
    to implement but optional to use security solution.  This will
    ensure security is available in all implementations, but
    configurable to use when not necessary (e.g., in closed
    environment). ... even if those features stretch the capabilities
    of such devices.
 A security solution MUST be implemented to protect CoAP over reliable
 transports and MUST be enabled by default.  This document defines the
 TLS binding, but alternative solutions at different layers in the
 protocol stack MAY be used to protect CoAP over reliable transports

Bormann, et al. Standards Track [Page 35] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 when appropriate.  Note that there is ongoing work to support a data-
 object-based security model for CoAP that is independent of transport
 (see [OSCORE]).

9.1. TLS Binding for CoAP over TCP

 The TLS usage guidance in [RFC7925] applies, including the guidance
 about cipher suites in that document that are derived from the
 mandatory-to-implement cipher suites defined in [RFC7252].
 This guidance assumes implementation in a constrained device or for
 communication with a constrained device.  However, CoAP over TCP/TLS
 has 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 back-end 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] differs from the guidance
 offered in [RFC7525] in terms of algorithms and credential types, it
 is assumed that an implementation of CoAP over TCP/TLS that needs to
 support both cases implements the recommendations offered by both
 specifications.
 During the provisioning phase, a CoAP device is provided with the
 security information that it needs, including keying materials,
 access control lists, and authorization servers.  At the end of the
 provisioning phase, the device will be in one of four security modes:
 NoSec:  TLS is disabled.
 PreSharedKey:  TLS is enabled.  The guidance in Section 4.2 of
    [RFC7925] applies.
 RawPublicKey:  TLS is enabled.  The guidance in Section 4.3 of
    [RFC7925] applies.
 Certificate:  TLS is enabled.  The guidance in Section 4.4 of
    [RFC7925] applies.
 The "NoSec" mode is optional to implement.  The system simply sends
 the packets over normal TCP; this is indicated by the "coap+tcp"
 scheme and the TCP CoAP default port.  The system is secured only by
 keeping attackers from being able to send or receive packets from the
 network with the CoAP nodes.

Bormann, et al. Standards Track [Page 36] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 "PreSharedKey", "RawPublicKey", or "Certificate" is mandatory to
 implement for the TLS binding, depending on the credential type used
 with the device.  These security modes are achieved using TLS and
 are indicated by the "coaps+tcp" scheme and TLS-secured CoAP
 default port.

9.2. TLS Usage for CoAP over WebSockets

 A CoAP client requesting a resource identified by a "coaps+ws" URI
 negotiates a secure WebSocket connection to a WebSocket server
 endpoint with a "wss" URI.  This is described in Section 8.4.
 The client MUST perform a TLS handshake after opening the connection
 to the server.  The guidance in Section 4.1 of [RFC6455] applies.
 When a CoAP server exposes resources identified by a "coaps+ws" URI,
 the guidance in Section 4.4 of [RFC7925] applies towards mandatory-
 to-implement TLS functionality for certificates.  For the server-side
 requirements for accepting incoming connections over an HTTPS
 (HTTP over TLS) port, the guidance in Section 4.2 of [RFC6455]
 applies.
 Note that the guidance above formally inherits the mandatory-to-
 implement cipher suites defined in [RFC5246].  However, modern
 browsers usually implement cipher suites that are more recent; these
 cipher suites are then automatically picked up via the JavaScript
 WebSocket API.  WebSocket servers that provide secure CoAP over
 WebSockets for the browser use case will need to follow the browser
 preferences and MUST follow [RFC7525].

10. Security Considerations

 The security considerations of [RFC7252] apply.  For CoAP over
 WebSockets and CoAP over TLS-secured WebSockets, the security
 considerations of [RFC6455] also apply.

10.1. Signaling Messages

 The guidance given by an Alternative-Address Option cannot be
 followed blindly.  In particular, a peer MUST NOT assume that a
 successful connection to the Alternative-Address inherits all the
 security properties of the current connection.

Bormann, et al. Standards Track [Page 37] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

11. IANA Considerations

11.1. Signaling Codes

 IANA has created a third subregistry for values of the Code field in
 the CoAP header (Section 12.1 of [RFC7252]).  The name of this
 subregistry is "CoAP Signaling Codes".
 Each entry in the subregistry must include the Signaling Code in the
 range 7.00-7.31, its name, and a reference to its documentation.
 Initial entries in this subregistry are as follows:
                    +------+---------+-----------+
                    | Code | Name    | Reference |
                    +------+---------+-----------+
                    | 7.01 | CSM     | RFC 8323  |
                    |      |         |           |
                    | 7.02 | Ping    | RFC 8323  |
                    |      |         |           |
                    | 7.03 | Pong    | RFC 8323  |
                    |      |         |           |
                    | 7.04 | Release | RFC 8323  |
                    |      |         |           |
                    | 7.05 | Abort   | RFC 8323  |
                    +------+---------+-----------+
                     Table 1: CoAP Signaling Codes
 All other Signaling Codes are Unassigned.
 The IANA policy for future additions to this subregistry is
 "IETF Review" or "IESG Approval" as described in [RFC8126].

11.2. CoAP Signaling Option Numbers Registry

 IANA has created a subregistry for Option Numbers used in CoAP
 Signaling Options within the "Constrained RESTful Environments (CoRE)
 Parameters" registry.  The name of this subregistry is "CoAP
 Signaling Option Numbers".
 Each entry in the subregistry must include one or more of the codes
 in the "CoAP Signaling Codes" subregistry (Section 11.1), the number
 for the Option, the name of the Option, and a reference to the
 Option's documentation.

Bormann, et al. Standards Track [Page 38] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 Initial entries in this subregistry are as follows:
       +------------+--------+---------------------+-----------+
       | Applies to | Number | Name                | Reference |
       +------------+--------+---------------------+-----------+
       | 7.01       |      2 | Max-Message-Size    |  RFC 8323 |
       |            |        |                     |           |
       | 7.01       |      4 | Block-Wise-Transfer |  RFC 8323 |
       |            |        |                     |           |
       | 7.02, 7.03 |      2 | Custody             |  RFC 8323 |
       |            |        |                     |           |
       | 7.04       |      2 | Alternative-Address |  RFC 8323 |
       |            |        |                     |           |
       | 7.04       |      4 | Hold-Off            |  RFC 8323 |
       |            |        |                     |           |
       | 7.05       |      2 | Bad-CSM-Option      |  RFC 8323 |
       +------------+--------+---------------------+-----------+
                 Table 2: CoAP Signaling Option Codes
 The IANA policy for future additions to this subregistry is based on
 number ranges for the option numbers, analogous to the policy defined
 in Section 12.2 of [RFC7252].  (The policy is analogous rather than
 identical because the structure of this subregistry includes an
 additional column ("Applies to"); however, the value of this column
 has no influence on the policy.)
 The documentation for a Signaling Option Number should specify the
 semantics of an option with that number, including the following
 properties:
 o  Whether the option is critical or elective, as determined by the
    Option Number.
 o  Whether the option is repeatable.
 o  The format and length of the option's value.
 o  The base value for the option, if any.

Bormann, et al. Standards Track [Page 39] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

11.3. Service Name and Port Number Registration

 IANA has assigned the port number 5683 and the service name "coap",
 in accordance with [RFC6335].
 Service Name:
    coap
 Transport Protocol:
    tcp
 Assignee:
    IESG <iesg@ietf.org>
 Contact:
    IETF Chair <chair@ietf.org>
 Description:
    Constrained Application Protocol (CoAP)
 Reference:
    RFC 8323
 Port Number:
    5683

11.4. Secure Service Name and Port Number Registration

 IANA has assigned the port number 5684 and the service name "coaps",
 in accordance with [RFC6335].  The port number is to address the
 exceptional case of TLS implementations that do not support the ALPN
 extension [RFC7301].
 Service Name:
    coaps
 Transport Protocol:
    tcp
 Assignee:
    IESG <iesg@ietf.org>
 Contact:
    IETF Chair <chair@ietf.org>
 Description:
    Constrained Application Protocol (CoAP)

Bormann, et al. Standards Track [Page 40] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 Reference:
    [RFC7301], RFC 8323
 Port Number:
    5684

11.5. URI Scheme Registration

 URI schemes are registered within the "Uniform Resource Identifier
 (URI) Schemes" registry maintained at [IANA.uri-schemes].
 Note: The following has been added as a note for each of the URI
 schemes defined in this document:
    CoAP registers different URI schemes for accessing CoAP resources
    via different protocols.  This approach runs counter to the WWW
    principle that a URI identifies a resource and that multiple URIs
    for identifying the same resource should be avoided
    <https://www.w3.org/TR/webarch/#avoid-uri-aliases>.
 This is not a problem for many of the usage scenarios envisioned for
 CoAP over reliable transports; additional URI schemes can be
 introduced to address additional usage scenarios (as being prepared,
 for example, in [Multi-Transport-URIs] and [CoAP-Alt-Transports]).

11.5.1. coap+tcp

 IANA has registered the 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 RFC 8323

Bormann, et al. Standards Track [Page 41] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

11.5.2. coaps+tcp

 IANA has registered the 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 RFC 8323

11.5.3. coap+ws

 IANA has registered the 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 RFC 8323

Bormann, et al. Standards Track [Page 42] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

11.5.4. coaps+ws

 IANA has registered the 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 RFC 8323

11.6. Well-Known URI Suffix Registration

 IANA has registered "coap" in the "Well-Known URIs" registry.  This
 registration request complies with [RFC5785].
 URI suffix:
    coap
 Change controller:
    IETF
 Specification document(s):
    RFC 8323
 Related information:
    None.

Bormann, et al. Standards Track [Page 43] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

11.7. ALPN Protocol Identifier

 IANA has assigned the following value in the "Application-Layer
 Protocol Negotiation (ALPN) Protocol IDs" registry created by
 [RFC7301].  The "coap" string identifies CoAP when used over TLS.
 Protocol:
    CoAP
 Identification Sequence:
    0x63 0x6f 0x61 0x70 ("coap")
 Reference:
    RFC 8323

11.8. WebSocket Subprotocol Registration

 IANA has registered the WebSocket CoAP subprotocol in the "WebSocket
 Subprotocol Name Registry":
 Subprotocol Identifier:
    coap
 Subprotocol Common Name:
    Constrained Application Protocol (CoAP)
 Subprotocol Definition:
    RFC 8323

11.9. CoAP Option Numbers Registry

 IANA has added this document as a reference for the following entries
 registered by [RFC7959] in the "CoAP Option Numbers" subregistry
 defined by [RFC7252]:
               +--------+--------+--------------------+
               | Number | Name   | Reference          |
               +--------+--------+--------------------+
               | 23     | Block2 | RFC 7959, RFC 8323 |
               |        |        |                    |
               | 27     | Block1 | RFC 7959, RFC 8323 |
               +--------+--------+--------------------+
                     Table 3: CoAP Option Numbers

Bormann, et al. Standards Track [Page 44] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

12. References

12.1. Normative References

 [RFC793]   Postel, J., "Transmission Control Protocol", STD 7,
            RFC 793, DOI 10.17487/RFC0793, September 1981,
            <https://www.rfc-editor.org/info/rfc793>.
 [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
            Requirement Levels", BCP 14, RFC 2119,
            DOI 10.17487/RFC2119, March 1997,
            <https://www.rfc-editor.org/info/rfc2119>.
 [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
            Resource Identifier (URI): Generic Syntax", STD 66,
            RFC 3986, DOI 10.17487/RFC3986, January 2005,
            <https://www.rfc-editor.org/info/rfc3986>.
 [RFC5234]  Crocker, D., Ed., and P. Overell, "Augmented BNF for
            Syntax Specifications: ABNF", STD 68, RFC 5234,
            DOI 10.17487/RFC5234, January 2008,
            <https://www.rfc-editor.org/info/rfc5234>.
 [RFC5246]  Dierks, T. and E. Rescorla, "The Transport Layer Security
            (TLS) Protocol Version 1.2", RFC 5246,
            DOI 10.17487/RFC5246, August 2008,
            <https://www.rfc-editor.org/info/rfc5246>.
 [RFC5785]  Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
            Uniform Resource Identifiers (URIs)", RFC 5785,
            DOI 10.17487/RFC5785, April 2010,
            <https://www.rfc-editor.org/info/rfc5785>.
 [RFC6066]  Eastlake 3rd, D., "Transport Layer Security (TLS)
            Extensions: Extension Definitions", RFC 6066,
            DOI 10.17487/RFC6066, January 2011,
            <https://www.rfc-editor.org/info/rfc6066>.
 [RFC6455]  Fette, I. and A. Melnikov, "The WebSocket Protocol",
            RFC 6455, DOI 10.17487/RFC6455, December 2011,
            <https://www.rfc-editor.org/info/rfc6455>.
 [RFC7252]  Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
            Application Protocol (CoAP)", RFC 7252,
            DOI 10.17487/RFC7252, June 2014,
            <https://www.rfc-editor.org/info/rfc7252>.

Bormann, et al. Standards Track [Page 45] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 [RFC7301]  Friedl, S., Popov, A., Langley, A., and E. Stephan,
            "Transport Layer Security (TLS) Application-Layer Protocol
            Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301,
            July 2014, <https://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, <https://www.rfc-editor.org/info/rfc7525>.
 [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
            Application Protocol (CoAP)", RFC 7641,
            DOI 10.17487/RFC7641, September 2015,
            <https://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,
            <https://www.rfc-editor.org/info/rfc7925>.
 [RFC7959]  Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in
            the Constrained Application Protocol (CoAP)", RFC 7959,
            DOI 10.17487/RFC7959, August 2016,
            <https://www.rfc-editor.org/info/rfc7959>.
 [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>.
 [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in
            RFC 2119 Key Words", BCP 14, RFC 8174,
            DOI 10.17487/RFC8174, May 2017,
            <https://www.rfc-editor.org/info/rfc8174>.
 [RFC8307]  Bormann, C., "Well-Known URIs for the WebSocket Protocol",
            RFC 8307, DOI 10.17487/RFC8307, January 2018,
            <https://www.rfc-editor.org/info/rfc8307>.

Bormann, et al. Standards Track [Page 46] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

12.2. Informative References

 [BK2015]   Byrne, C. and J. Kleberg, "Advisory Guidelines for UDP
            Deployment", Work in Progress, draft-byrne-opsec-udp-
            advisory-00, July 2015.
 [CoAP-Alt-Transports]
            Silverajan, B. and T. Savolainen, "CoAP Communication with
            Alternative Transports", Work in Progress,
            draft-silverajan-core-coap-alternative-transports-10,
            July 2017.
 [CoCoA]    Bormann, C., Betzler, A., Gomez, C., and I. Demirkol,
            "CoAP Simple Congestion Control/Advanced", Work in
            Progress, draft-ietf-core-cocoa-02, October 2017.
 [EK2016]   Edeline, K., Kuehlewind, M., Trammell, B., Aben, E., and
            B. Donnet, "Using UDP for Internet Transport Evolution",
            arXiv preprint 1612.07816, December 2016,
            <https://arxiv.org/abs/1612.07816>.
 [HomeGateway]
            Haetoenen, S., Nyrhinen, A., Eggert, L., Strowes, S.,
            Sarolahti, P., and N. Kojo, "An experimental study of home
            gateway characteristics", Proceedings of the 10th ACM
            SIGCOMM conference on Internet measurement,
            DOI 10.1145/1879141.1879174, November 2010.
 [IANA.uri-schemes]
            IANA, "Uniform Resource Identifier (URI) Schemes",
            <https://www.iana.org/assignments/uri-schemes>.
 [LWM2M]    Open Mobile Alliance, "Lightweight Machine to Machine
            Technical Specification Version 1.0", February 2017,
            <http://www.openmobilealliance.org/release/LightweightM2M/
            V1_0-20170208-A/
            OMA-TS-LightweightM2M-V1_0-20170208-A.pdf>.
 [Multi-Transport-URIs]
            Thaler, D., "Using URIs With Multiple Transport Stacks",
            Work in Progress, draft-thaler-appsawg-multi-transport-
            uris-01, July 2017.
 [OSCORE]   Selander, G., Mattsson, J., Palombini, F., and L. Seitz,
            "Object Security for Constrained RESTful Environments
            (OSCORE)", Work in Progress, draft-ietf-core-object-
            security-08, January 2018.

Bormann, et al. Standards Track [Page 47] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 [RFC768]   Postel, J., "User Datagram Protocol", STD 6, RFC 768,
            DOI 10.17487/RFC0768, August 1980,
            <https://www.rfc-editor.org/info/rfc768>.
 [RFC6335]  Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S.
            Cheshire, "Internet Assigned Numbers Authority (IANA)
            Procedures for the Management of the Service Name and
            Transport Protocol Port Number Registry", BCP 165,
            RFC 6335, DOI 10.17487/RFC6335, August 2011,
            <https://www.rfc-editor.org/info/rfc6335>.
 [RFC6347]  Rescorla, E. and N. Modadugu, "Datagram Transport Layer
            Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347,
            January 2012, <https://www.rfc-editor.org/info/rfc6347>.
 [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,
            <https://www.rfc-editor.org/info/rfc7230>.
 [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>.
 [SecurityChallenges]
            Polk, T. and S. Turner, "Security Challenges For the
            Internet Of Things", Interconnecting Smart Objects with
            the Internet / IAB Workshop, February 2011,
            <https://www.iab.org/wp-content/IAB-uploads/2011/03/
            Turner.pdf>.
 [SW2016]   Swett, I., "QUIC Deployment Experience @Google", IETF 96
            Proceedings, Berlin, Germany, July 2016,
            <https://www.ietf.org/proceedings/96/slides/
            slides-96-quic-3.pdf>.
 [TCP-in-IoT]
            Gomez, C., Crowcroft, J., and M. Scharf, "TCP Usage
            Guidance in the Internet of Things (IoT)", Work in
            Progress, draft-ietf-lwig-tcp-constrained-node-
            networks-01, October 2017.

Bormann, et al. Standards Track [Page 48] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

Appendix A. Examples of CoAP over WebSockets

 This appendix gives examples for the first two configurations
 discussed in Section 4.
 An example of the process followed by a CoAP client to retrieve the
 representation of a resource identified by a "coap+ws" URI might be
 as follows.  Figure 17 below illustrates the WebSocket and CoAP
 messages exchanged in detail.
 1.  The CoAP client obtains the URI
     <coap+ws://example.org/sensors/temperature?u=Cel>, for example,
     from a resource representation that it retrieved previously.
 2.  The CoAP client establishes a WebSocket connection to the
     endpoint URI composed of the authority "example.org" and the
     well-known path "/.well-known/coap",
     <ws://example.org/.well-known/coap>.
 3.  CSMs (Section 5.3) are exchanged (not shown).
 4.  The CoAP client sends a single-frame, masked, binary message
     containing a CoAP request.  The request indicates the target
     resource with the Uri-Path ("sensors", "temperature") and
     Uri-Query ("u=Cel") Options.
 5.  The CoAP client waits for the server to return a response.
 6.  The CoAP client uses the connection for further requests, or the
     connection is closed.

Bormann, et al. Standards Track [Page 49] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

    CoAP        CoAP
   Client      Server
 (WebSocket  (WebSocket
   Client)     Server)
      |          |
      |          |
      +=========>|  GET /.well-known/coap HTTP/1.1
      |          |  Host: example.org
      |          |  Upgrade: websocket
      |          |  Connection: Upgrade
      |          |  Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
      |          |  Sec-WebSocket-Protocol: coap
      |          |  Sec-WebSocket-Version: 13
      |          |
      |<=========+  HTTP/1.1 101 Switching Protocols
      |          |  Upgrade: websocket
      |          |  Connection: Upgrade
      |          |  Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
      |          |  Sec-WebSocket-Protocol: coap
      :          :
      :<-------->:  Exchange of CSMs (not shown)
      |          |
      +--------->|  Binary frame (opcode=%x2, FIN=1, MASK=1)
      |          |    +-------------------------+
      |          |    | GET                     |
      |          |    | Token: 0x53             |
      |          |    | Uri-Path: "sensors"     |
      |          |    | Uri-Path: "temperature" |
      |          |    | Uri-Query: "u=Cel"      |
      |          |    +-------------------------+
      |          |
      |<---------+  Binary frame (opcode=%x2, FIN=1, MASK=0)
      |          |    +-------------------------+
      |          |    | 2.05 Content            |
      |          |    | Token: 0x53             |
      |          |    | Payload: "22.3 Cel"     |
      |          |    +-------------------------+
      :          :
      :          :
      +--------->|  Close frame (opcode=%x8, FIN=1, MASK=1)
      |          |
      |<---------+  Close frame (opcode=%x8, FIN=1, MASK=0)
      |          |
  Figure 17: A CoAP Client Retrieves the Representation of a Resource
                     Identified by a "coap+ws" URI

Bormann, et al. Standards Track [Page 50] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 Figure 18 shows how a CoAP client uses a CoAP forward proxy with a
 WebSocket endpoint to retrieve the representation of the resource
 "coap://[2001:db8::1]/".  The use of the forward proxy and the
 address of the WebSocket endpoint are determined by the client from
 local configuration rules.  The request URI is specified in the
 Proxy-Uri Option.  Since the request URI uses the "coap" URI scheme,
 the proxy fulfills the request by issuing a Confirmable GET request
 over UDP to the CoAP server and returning the response over the
 WebSocket connection to the client.
   CoAP        CoAP       CoAP
  Client      Proxy      Server
(WebSocket  (WebSocket    (UDP
  Client)     Server)   Endpoint)
     |          |          |
     +--------->|          |  Binary frame (opcode=%x2, FIN=1, MASK=1)
     |          |          |    +------------------------------------+
     |          |          |    | GET                                |
     |          |          |    | Token: 0x7d                        |
     |          |          |    | Proxy-Uri: "coap://[2001:db8::1]/" |
     |          |          |    +------------------------------------+
     |          |          |
     |          +--------->|  CoAP message (Ver=1, T=Con, MID=0x8f54)
     |          |          |    +------------------------------------+
     |          |          |    | GET                                |
     |          |          |    | Token: 0x0a15                      |
     |          |          |    +------------------------------------+
     |          |          |
     |          |<---------+  CoAP message (Ver=1, T=Ack, MID=0x8f54)
     |          |          |    +------------------------------------+
     |          |          |    | 2.05 Content                       |
     |          |          |    | Token: 0x0a15                      |
     |          |          |    | Payload: "ready"                   |
     |          |          |    +------------------------------------+
     |          |          |
     |<---------+          |  Binary frame (opcode=%x2, FIN=1, MASK=0)
     |          |          |    +------------------------------------+
     |          |          |    | 2.05 Content                       |
     |          |          |    | Token: 0x7d                        |
     |          |          |    | Payload: "ready"                   |
     |          |          |    +------------------------------------+
     |          |          |
  Figure 18: A CoAP Client Retrieves the Representation of a Resource
     Identified by a "coap" URI via a WebSocket-Enabled CoAP Proxy

Bormann, et al. Standards Track [Page 51] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

Acknowledgments

 We would like to thank Stephen Berard, Geoffrey Cristallo, Olivier
 Delaby, Esko Dijk, Christian Groves, Nadir Javed, Michael Koster,
 Achim Kraus, David Navarro, Szymon Sasin, Goeran Selander, Zach
 Shelby, Andrew Summers, Julien Vermillard, and Gengyu Wei for their
 feedback.
 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
 Siemens AG
 Otto-Hahn-Ring 6
 Munich  D-81739
 Germany
 Phone: +49-173-5288856
 Email: matthias.kovatsch@siemens.com
 Teemu Savolainen
 Nokia Technologies
 Hatanpaan valtatie 30
 Tampere  FI-33100
 Finland
 Email: teemu.savolainen@nokia.com
 Valik Solorzano Barboza
 Zebra Technologies
 820 W. Jackson Blvd. Suite 700
 Chicago, IL  60607
 United States of America
 Phone: +1-847-634-6700
 Email: vsolorzanobarboza@zebra.com

Bormann, et al. Standards Track [Page 52] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

Authors' Addresses

 Carsten Bormann
 Universitaet Bremen TZI
 Postfach 330440
 Bremen  D-28359
 Germany
 Phone: +49-421-218-63921
 Email: cabo@tzi.org
 Simon Lemay
 Zebra Technologies
 820 W. Jackson Blvd. Suite 700
 Chicago, IL  60607
 United States of America
 Phone: +1-847-634-6700
 Email: slemay@zebra.com
 Hannes Tschofenig
 ARM Ltd.
 110 Fulbourn Road
 Cambridge  CB1 9NJ
 United Kingdom
 Email: Hannes.tschofenig@gmx.net
 URI:   http://www.tschofenig.priv.at
 Klaus Hartke
 Universitaet Bremen TZI
 Postfach 330440
 Bremen  D-28359
 Germany
 Phone: +49-421-218-63905
 Email: hartke@tzi.org

Bormann, et al. Standards Track [Page 53] RFC 8323 TCP/TLS/WebSockets Transports for CoAP February 2018

 Bilhanan Silverajan
 Tampere University of Technology
 Korkeakoulunkatu 10
 Tampere  FI-33720
 Finland
 Email: bilhanan.silverajan@tut.fi
 Brian Raymor (editor)
 Email: brianraymor@hotmail.com

Bormann, et al. Standards Track [Page 54]

/data/webs/external/dokuwiki/data/pages/rfc/rfc8323.txt · Last modified: 2018/02/15 01:12 by 127.0.0.1

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki