Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 8323

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

Pages: 54
Proposed Standard
Updates:  76417959
Updated by:  8974
Part 2 of 3 – Pages 17 to 35
First   Prev   Next

Top   ToC   RFC8323 - Page 17   prevText

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

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

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].
Top   ToC   RFC8323 - Page 20
   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).
Top   ToC   RFC8323 - Page 21
   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.)
Top   ToC   RFC8323 - Page 22
   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.)
Top   ToC   RFC8323 - Page 23
   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
Top   ToC   RFC8323 - Page 24
   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
Top   ToC   RFC8323 - Page 25
   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.
Top   ToC   RFC8323 - Page 26
   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.
Top   ToC   RFC8323 - Page 27

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
Top   ToC   RFC8323 - Page 28

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
Top   ToC   RFC8323 - Page 29
   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.
Top   ToC   RFC8323 - Page 30
   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].
Top   ToC   RFC8323 - Page 31

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.
Top   ToC   RFC8323 - Page 32
   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].
Top   ToC   RFC8323 - Page 33

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

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.


(page 35 continued on part 3)

Next Section