Tech-invite   World Map
3GPPspecs     Glossaries     IETF     RFCs     Groups     SIP     ABNFs

RFC 8323

Proposed STD
Pages: 54
Top     in Index     Prev     Next
in Group Index     Prev in Group     No Next: Highest Number in Group     Group: CORE

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

Part 1 of 3, p. 1 to 17
None       Next Section

Updates:    7641    7959


Top       ToC       Page 1 
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.

Top      ToC       Page 2 
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

Top      ToC       Page 3 
   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

Top      ToC       Page 4 
   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

Top      ToC       Page 5 
   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.

Top      ToC       Page 6 
   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.

Top      ToC       Page 7 
   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.

Top      ToC       Page 8 
   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

Top      ToC       Page 9 
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.

Top      ToC       Page 10 
   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.)

Top      ToC       Page 11 
   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.

Top      ToC       Page 12 
   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.

Top      ToC       Page 13 
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.

Top      ToC       Page 14 
   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.

Top      ToC       Page 15 
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].

Top      ToC       Page 16 
   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.

Top      ToC       Page 17 
   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.



(page 17 continued on part 2)

Next Section