    Internet Engineering Task Force (IETF)                         Z. Shelby
    Request for Comments: 7252                                           ARM
    Category: Standards Track                                      K. Hartke
    ISSN: 2070-1721                                               C. Bormann
                                                     Universitaet Bremen TZI
                                                                   June 2014

                  The Constrained Application Protocol (CoAP)

    Abstract

       The Constrained Application Protocol (CoAP) is a specialized web
       transfer protocol for use with constrained nodes and constrained
       (e.g., low-power, lossy) networks.  The nodes often have 8-bit
       microcontrollers with small amounts of ROM and RAM, while constrained
       networks such as IPv6 over Low-Power Wireless Personal Area Networks
       (6LoWPANs) often have high packet error rates and a typical
       throughput of 10s of kbit/s.  The protocol is designed for machine-
       to-machine (M2M) applications such as smart energy and building
       automation.

       CoAP provides a request/response interaction model between
       application endpoints, supports built-in discovery of services and
       resources, and includes key concepts of the Web such as URIs and
       Internet media types.  CoAP is designed to easily interface with HTTP
       for integration with the Web while meeting specialized requirements
       such as multicast support, very low overhead, and simplicity for
       constrained environments.

    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 5741.

       Information about the current status of this document, any errata,
       and how to provide feedback on it may be obtained at
       http://www.rfc-editor.org/info/rfc7252.

    Shelby, et al.               Standards Track                    [Page 1]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    Copyright Notice

       Copyright (c) 2014 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
       (http://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  . . . . . . . . . . . . . . . . . . . . . . . .   5
         1.1.  Features  . . . . . . . . . . . . . . . . . . . . . . . .   5
         1.2.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   6
       2.  Constrained Application Protocol  . . . . . . . . . . . . . .  10
         2.1.  Messaging Model . . . . . . . . . . . . . . . . . . . . .  11
         2.2.  Request/Response Model  . . . . . . . . . . . . . . . . .  12
         2.3.  Intermediaries and Caching  . . . . . . . . . . . . . . .  15
         2.4.  Resource Discovery  . . . . . . . . . . . . . . . . . . .  15
       3.  Message Format  . . . . . . . . . . . . . . . . . . . . . . .  15
         3.1.  Option Format . . . . . . . . . . . . . . . . . . . . . .  17
         3.2.  Option Value Formats  . . . . . . . . . . . . . . . . . .  19
       4.  Message Transmission  . . . . . . . . . . . . . . . . . . . .  20
         4.1.  Messages and Endpoints  . . . . . . . . . . . . . . . . .  20
         4.2.  Messages Transmitted Reliably . . . . . . . . . . . . . .  21
         4.3.  Messages Transmitted without Reliability  . . . . . . . .  23
         4.4.  Message Correlation . . . . . . . . . . . . . . . . . . .  24
         4.5.  Message Deduplication . . . . . . . . . . . . . . . . . .  24
         4.6.  Message Size  . . . . . . . . . . . . . . . . . . . . . .  25
         4.7.  Congestion Control  . . . . . . . . . . . . . . . . . . .  26
         4.8.  Transmission Parameters . . . . . . . . . . . . . . . . .  27
           4.8.1.  Changing the Parameters . . . . . . . . . . . . . . .  27
           4.8.2.  Time Values Derived from Transmission Parameters  . .  28
       5.  Request/Response Semantics  . . . . . . . . . . . . . . . . .  31
         5.1.  Requests  . . . . . . . . . . . . . . . . . . . . . . . .  31
         5.2.  Responses . . . . . . . . . . . . . . . . . . . . . . . .  31
           5.2.1.  Piggybacked . . . . . . . . . . . . . . . . . . . . .  33
           5.2.2.  Separate  . . . . . . . . . . . . . . . . . . . . . .  33
           5.2.3.  Non-confirmable . . . . . . . . . . . . . . . . . . .  34
         5.3.  Request/Response Matching . . . . . . . . . . . . . . . .  34
           5.3.1.  Token . . . . . . . . . . . . . . . . . . . . . . . .  34
           5.3.2.  Request/Response Matching Rules . . . . . . . . . . .  35

    Shelby, et al.               Standards Track                    [Page 2]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

         5.4.  Options . . . . . . . . . . . . . . . . . . . . . . . . .  36
           5.4.1.  Critical/Elective . . . . . . . . . . . . . . . . . .  37
           5.4.2.  Proxy Unsafe or Safe-to-Forward and NoCacheKey  . . .  38
           5.4.3.  Length  . . . . . . . . . . . . . . . . . . . . . . .  38
           5.4.4.  Default Values  . . . . . . . . . . . . . . . . . . .  38
           5.4.5.  Repeatable Options  . . . . . . . . . . . . . . . . .  39
           5.4.6.  Option Numbers  . . . . . . . . . . . . . . . . . . .  39
         5.5.  Payloads and Representations  . . . . . . . . . . . . . .  40
           5.5.1.  Representation  . . . . . . . . . . . . . . . . . . .  40
           5.5.2.  Diagnostic Payload  . . . . . . . . . . . . . . . . .  41
           5.5.3.  Selected Representation . . . . . . . . . . . . . . .  41
           5.5.4.  Content Negotiation . . . . . . . . . . . . . . . . .  41
         5.6.  Caching . . . . . . . . . . . . . . . . . . . . . . . . .  42
           5.6.1.  Freshness Model . . . . . . . . . . . . . . . . . . .  43
           5.6.2.  Validation Model  . . . . . . . . . . . . . . . . . .  43
         5.7.  Proxying  . . . . . . . . . . . . . . . . . . . . . . . .  44
           5.7.1.  Proxy Operation . . . . . . . . . . . . . . . . . . .  44
           5.7.2.  Forward-Proxies . . . . . . . . . . . . . . . . . . .  46
           5.7.3.  Reverse-Proxies . . . . . . . . . . . . . . . . . . .  46
         5.8.  Method Definitions  . . . . . . . . . . . . . . . . . . .  47
           5.8.1.  GET . . . . . . . . . . . . . . . . . . . . . . . . .  47
           5.8.2.  POST  . . . . . . . . . . . . . . . . . . . . . . . .  47
           5.8.3.  PUT . . . . . . . . . . . . . . . . . . . . . . . . .  48
           5.8.4.  DELETE  . . . . . . . . . . . . . . . . . . . . . . .  48
         5.9.  Response Code Definitions . . . . . . . . . . . . . . . .  48
           5.9.1.  Success 2.xx  . . . . . . . . . . . . . . . . . . . .  48
           5.9.2.  Client Error 4.xx . . . . . . . . . . . . . . . . . .  50
           5.9.3.  Server Error 5.xx . . . . . . . . . . . . . . . . . .  51
         5.10. Option Definitions  . . . . . . . . . . . . . . . . . . .  52
           5.10.1.  Uri-Host, Uri-Port, Uri-Path, and Uri-Query  . . . .  53
           5.10.2.  Proxy-Uri and Proxy-Scheme . . . . . . . . . . . . .  54
           5.10.3.  Content-Format . . . . . . . . . . . . . . . . . . .  55
           5.10.4.  Accept . . . . . . . . . . . . . . . . . . . . . . .  55
           5.10.5.  Max-Age  . . . . . . . . . . . . . . . . . . . . . .  55
           5.10.6.  ETag . . . . . . . . . . . . . . . . . . . . . . . .  56
           5.10.7.  Location-Path and Location-Query . . . . . . . . . .  57
           5.10.8.  Conditional Request Options  . . . . . . . . . . . .  57
           5.10.9.  Size1 Option . . . . . . . . . . . . . . . . . . . .  59
       6.  CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . . .  59
         6.1.  coap URI Scheme . . . . . . . . . . . . . . . . . . . . .  59
         6.2.  coaps URI Scheme  . . . . . . . . . . . . . . . . . . . .  60
         6.3.  Normalization and Comparison Rules  . . . . . . . . . . .  61
         6.4.  Decomposing URIs into Options . . . . . . . . . . . . . .  61
         6.5.  Composing URIs from Options . . . . . . . . . . . . . . .  62
       7.  Discovery . . . . . . . . . . . . . . . . . . . . . . . . . .  64
         7.1.  Service Discovery . . . . . . . . . . . . . . . . . . . .  64
         7.2.  Resource Discovery  . . . . . . . . . . . . . . . . . . .  64
           7.2.1.  'ct' Attribute  . . . . . . . . . . . . . . . . . . .  64

    Shelby, et al.               Standards Track                    [Page 3]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       8.  Multicast CoAP  . . . . . . . . . . . . . . . . . . . . . . .  65
         8.1.  Messaging Layer . . . . . . . . . . . . . . . . . . . . .  65
         8.2.  Request/Response Layer  . . . . . . . . . . . . . . . . .  66
           8.2.1.  Caching . . . . . . . . . . . . . . . . . . . . . . .  67
           8.2.2.  Proxying  . . . . . . . . . . . . . . . . . . . . . .  67
       9.  Securing CoAP . . . . . . . . . . . . . . . . . . . . . . . .  68
         9.1.  DTLS-Secured CoAP . . . . . . . . . . . . . . . . . . . .  69
           9.1.1.  Messaging Layer . . . . . . . . . . . . . . . . . . .  70
           9.1.2.  Request/Response Layer  . . . . . . . . . . . . . . .  71
           9.1.3.  Endpoint Identity . . . . . . . . . . . . . . . . . .  71
       10. Cross-Protocol Proxying between CoAP and HTTP . . . . . . . .  74
         10.1.  CoAP-HTTP Proxying . . . . . . . . . . . . . . . . . . .  75
           10.1.1.  GET  . . . . . . . . . . . . . . . . . . . . . . . .  76
           10.1.2.  PUT  . . . . . . . . . . . . . . . . . . . . . . . .  77
           10.1.3.  DELETE . . . . . . . . . . . . . . . . . . . . . . .  77
           10.1.4.  POST . . . . . . . . . . . . . . . . . . . . . . . .  77
         10.2.  HTTP-CoAP Proxying . . . . . . . . . . . . . . . . . . .  77
           10.2.1.  OPTIONS and TRACE  . . . . . . . . . . . . . . . . .  78
           10.2.2.  GET  . . . . . . . . . . . . . . . . . . . . . . . .  78
           10.2.3.  HEAD . . . . . . . . . . . . . . . . . . . . . . . .  79
           10.2.4.  POST . . . . . . . . . . . . . . . . . . . . . . . .  79
           10.2.5.  PUT  . . . . . . . . . . . . . . . . . . . . . . . .  79
           10.2.6.  DELETE . . . . . . . . . . . . . . . . . . . . . . .  80
           10.2.7.  CONNECT  . . . . . . . . . . . . . . . . . . . . . .  80
       11. Security Considerations . . . . . . . . . . . . . . . . . . .  80
         11.1.  Parsing the Protocol and Processing URIs . . . . . . . .  80
         11.2.  Proxying and Caching . . . . . . . . . . . . . . . . . .  81
         11.3.  Risk of Amplification  . . . . . . . . . . . . . . . . .  81
         11.4.  IP Address Spoofing Attacks  . . . . . . . . . . . . . .  83
         11.5.  Cross-Protocol Attacks . . . . . . . . . . . . . . . . .  84
         11.6.  Constrained-Node Considerations  . . . . . . . . . . . .  86
       12. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  86
         12.1.  CoAP Code Registries . . . . . . . . . . . . . . . . . .  86
           12.1.1.  Method Codes . . . . . . . . . . . . . . . . . . . .  87
           12.1.2.  Response Codes . . . . . . . . . . . . . . . . . . .  88
         12.2.  CoAP Option Numbers Registry . . . . . . . . . . . . . .  89
         12.3.  CoAP Content-Formats Registry  . . . . . . . . . . . . .  91
         12.4.  URI Scheme Registration  . . . . . . . . . . . . . . . .  93
         12.5.  Secure URI Scheme Registration . . . . . . . . . . . . .  94
         12.6.  Service Name and Port Number Registration  . . . . . . .  95
         12.7.  Secure Service Name and Port Number Registration . . . .  96
         12.8.  Multicast Address Registration . . . . . . . . . . . . .  97
       13. Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .  97
       14. References  . . . . . . . . . . . . . . . . . . . . . . . . .  98
         14.1.  Normative References . . . . . . . . . . . . . . . . . .  98
         14.2.  Informative References . . . . . . . . . . . . . . . . . 100
       Appendix A.  Examples . . . . . . . . . . . . . . . . . . . . . . 104
       Appendix B.  URI Examples . . . . . . . . . . . . . . . . . . . . 110

    Shelby, et al.               Standards Track                    [Page 4]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    1.  Introduction

       The use of web services (web APIs) on the Internet has become
       ubiquitous in most applications and depends on the fundamental
       Representational State Transfer [REST] architecture of the Web.

       The work on Constrained RESTful Environments (CoRE) aims at realizing
       the REST architecture in a suitable form for the most constrained
       nodes (e.g., 8-bit microcontrollers with limited RAM and ROM) and
       networks (e.g., 6LoWPAN, [RFC4944]).  Constrained networks such as
       6LoWPAN support the fragmentation of IPv6 packets into small link-
       layer frames; however, this causes significant reduction in packet
       delivery probability.  One design goal of CoAP has been to keep
       message overhead small, thus limiting the need for fragmentation.

       One of the main goals of CoAP is to design a generic web protocol for
       the special requirements of this constrained environment, especially
       considering energy, building automation, and other machine-to-machine
       (M2M) applications.  The goal of CoAP is not to blindly compress HTTP
       [RFC2616], but rather to realize a subset of REST common with HTTP
       but optimized for M2M applications.  Although CoAP could be used for
       refashioning simple HTTP interfaces into a more compact protocol,
       more importantly it also offers features for M2M such as built-in
       discovery, multicast support, and asynchronous message exchanges.

       This document specifies the Constrained Application Protocol (CoAP),
       which easily translates to HTTP for integration with the existing Web
       while meeting specialized requirements such as multicast support,
       very low overhead, and simplicity for constrained environments and
       M2M applications.

    1.1.  Features

       CoAP has the following main features:

       o  Web protocol fulfilling M2M requirements in constrained
          environments

       o  UDP [RFC0768] binding with optional reliability supporting unicast
          and multicast requests.

       o  Asynchronous message exchanges.

       o  Low header overhead and parsing complexity.

       o  URI and Content-type support.

       o  Simple proxy and caching capabilities.

    Shelby, et al.               Standards Track                    [Page 5]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       o  A stateless HTTP mapping, allowing proxies to be built providing
          access to CoAP resources via HTTP in a uniform way or for HTTP
          simple interfaces to be realized alternatively over CoAP.

       o  Security binding to Datagram Transport Layer Security (DTLS)
          [RFC6347].

    1.2.  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
       [RFC2119] when they appear in ALL CAPS.  These words may also appear
       in this document in lowercase, absent their normative meanings.

       This specification requires readers to be familiar with all the terms
       and concepts that are discussed in [RFC2616], including "resource",
       "representation", "cache", and "fresh".  (Having been completed
       before the updated set of HTTP RFCs, RFC 7230 to RFC 7235, became
       available, this specification specifically references the predecessor
       version -- RFC 2616.)  In addition, this specification defines the
       following terminology:

       Endpoint
          An entity participating in the CoAP protocol.  Colloquially, an
          endpoint lives on a "Node", although "Host" would be more
          consistent with Internet standards usage, and is further
          identified by transport-layer multiplexing information that can
          include a UDP port number and a security association
          (Section 4.1).

       Sender
          The originating endpoint of a message.  When the aspect of
          identification of the specific sender is in focus, also "source
          endpoint".

       Recipient
          The destination endpoint of a message.  When the aspect of
          identification of the specific recipient is in focus, also
          "destination endpoint".

       Client
          The originating endpoint of a request; the destination endpoint of
          a response.

       Server
          The destination endpoint of a request; the originating endpoint of
          a response.

    Shelby, et al.               Standards Track                    [Page 6]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       Origin Server
          The server on which a given resource resides or is to be created.

       Intermediary
          A CoAP endpoint that acts both as a server and as a client towards
          an origin server (possibly via further intermediaries).  A common
          form of an intermediary is a proxy; several classes of such
          proxies are discussed in this specification.

       Proxy
          An intermediary that mainly is concerned with forwarding requests
          and relaying back responses, possibly performing caching,
          namespace translation, or protocol translation in the process.  As
          opposed to intermediaries in the general sense, proxies generally
          do not implement specific application semantics.  Based on the
          position in the overall structure of the request forwarding, there
          are two common forms of proxy: forward-proxy and reverse-proxy.
          In some cases, a single endpoint might act as an origin server,
          forward-proxy, or reverse-proxy, switching behavior based on the
          nature of each request.

       Forward-Proxy
          An endpoint selected by a client, usually via local configuration
          rules, to perform requests on behalf of the client, doing any
          necessary translations.  Some translations are minimal, such as
          for proxy requests for "coap" URIs, whereas other requests might
          require translation to and from entirely different application-
          layer protocols.

       Reverse-Proxy
          An endpoint that stands in for one or more other server(s) and
          satisfies requests on behalf of these, doing any necessary
          translations.  Unlike a forward-proxy, the client may not be aware
          that it is communicating with a reverse-proxy; a reverse-proxy
          receives requests as if it were the origin server for the target
          resource.

       CoAP-to-CoAP Proxy
          A proxy that maps from a CoAP request to a CoAP request, i.e.,
          uses the CoAP protocol both on the server and the client side.
          Contrast to cross-proxy.

       Cross-Proxy
          A cross-protocol proxy, or "cross-proxy" for short, is a proxy
          that translates between different protocols, such as a CoAP-to-
          HTTP proxy or an HTTP-to-CoAP proxy.  While this specification
          makes very specific demands of CoAP-to-CoAP proxies, there is more
          variation possible in cross-proxies.

    Shelby, et al.               Standards Track                    [Page 7]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       Confirmable Message
          Some messages require an acknowledgement.  These messages are
          called "Confirmable".  When no packets are lost, each Confirmable
          message elicits exactly one return message of type Acknowledgement
          or type Reset.

       Non-confirmable Message
          Some other messages do not require an acknowledgement.  This is
          particularly true for messages that are repeated regularly for
          application requirements, such as repeated readings from a sensor.

       Acknowledgement Message
          An Acknowledgement message acknowledges that a specific
          Confirmable message arrived.  By itself, an Acknowledgement
          message does not indicate success or failure of any request
          encapsulated in the Confirmable message, but the Acknowledgement
          message may also carry a Piggybacked Response (see below).

       Reset Message
          A Reset message indicates that a specific message (Confirmable or
          Non-confirmable) was received, but some context is missing to
          properly process it.  This condition is usually caused when the
          receiving node has rebooted and has forgotten some state that
          would be required to interpret the message.  Provoking a Reset
          message (e.g., by sending an Empty Confirmable message) is also
          useful as an inexpensive check of the liveness of an endpoint
          ("CoAP ping").

       Piggybacked Response
          A piggybacked Response is included right in a CoAP Acknowledgement
          (ACK) message that is sent to acknowledge receipt of the Request
          for this Response (Section 5.2.1).

       Separate Response
          When a Confirmable message carrying a request is acknowledged with
          an Empty message (e.g., because the server doesn't have the answer
          right away), a Separate Response is sent in a separate message
          exchange (Section 5.2.2).

       Empty Message
          A message with a Code of 0.00; neither a request nor a response.
          An Empty message only contains the 4-byte header.

    Shelby, et al.               Standards Track                    [Page 8]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       Critical Option
          An option that would need to be understood by the endpoint
          ultimately receiving the message in order to properly process the
          message (Section 5.4.1).  Note that the implementation of critical
          options is, as the name "Option" implies, generally optional:
          unsupported critical options lead to an error response or summary
          rejection of the message.

       Elective Option
          An option that is intended to be ignored by an endpoint that does
          not understand it.  Processing the message even without
          understanding the option is acceptable (Section 5.4.1).

       Unsafe Option
          An option that would need to be understood by a proxy receiving
          the message in order to safely forward the message
          (Section 5.4.2).  Not every critical option is an unsafe option.

       Safe-to-Forward Option
          An option that is intended to be safe for forwarding by a proxy
          that does not understand it.  Forwarding the message even without
          understanding the option is acceptable (Section 5.4.2).

       Resource Discovery
          The process where a CoAP client queries a server for its list of
          hosted resources (i.e., links as defined in Section 7).

       Content-Format
          The combination of an Internet media type, potentially with
          specific parameters given, and a content-coding (which is often
          the identity content-coding), identified by a numeric identifier
          defined by the "CoAP Content-Formats" registry.  When the focus is
          less on the numeric identifier than on the combination of these
          characteristics of a resource representation, this is also called
          "representation format".

       Additional terminology for constrained nodes and constrained-node
       networks can be found in [RFC7228].

       In this specification, the term "byte" is used in its now customary
       sense as a synonym for "octet".

       All multi-byte integers in this protocol are interpreted in network
       byte order.

       Where arithmetic is used, this specification uses the notation
       familiar from the programming language C, except that the operator
       "**" stands for exponentiation.

    Shelby, et al.               Standards Track                    [Page 9]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    2.  Constrained Application Protocol

       The interaction model of CoAP is similar to the client/server model
       of HTTP.  However, machine-to-machine interactions typically result
       in a CoAP implementation acting in both client and server roles.  A
       CoAP request is equivalent to that of HTTP and is sent by a client to
       request an action (using a Method Code) on a resource (identified by
       a URI) on a server.  The server then sends a response with a Response
       Code; this response may include a resource representation.

       Unlike HTTP, CoAP deals with these interchanges asynchronously over a
       datagram-oriented transport such as UDP.  This is done logically
       using a layer of messages that supports optional reliability (with
       exponential back-off).  CoAP defines four types of messages:
       Confirmable, Non-confirmable, Acknowledgement, Reset.  Method Codes
       and Response Codes included in some of these messages make them carry
       requests or responses.  The basic exchanges of the four types of
       messages are somewhat orthogonal to the request/response
       interactions; requests can be carried in Confirmable and Non-
       confirmable messages, and responses can be carried in these as well
       as piggybacked in Acknowledgement messages.

       One could think of CoAP logically as using a two-layer approach, a
       CoAP messaging layer used to deal with UDP and the asynchronous
       nature of the interactions, and the request/response interactions
       using Method and Response Codes (see Figure 1).  CoAP is however a
       single protocol, with messaging and request/response as just features
       of the CoAP header.

                            +----------------------+
                            |      Application     |
                            +----------------------+
                            +----------------------+  \
                            |  Requests/Responses  |  |
                            |----------------------|  | CoAP
                            |       Messages       |  |
                            +----------------------+  /
                            +----------------------+
                            |          UDP         |
                            +----------------------+

                        Figure 1: Abstract Layering of CoAP

    Shelby, et al.               Standards Track                   [Page 10]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    2.1.  Messaging Model

       The CoAP messaging model is based on the exchange of messages over
       UDP between endpoints.

       CoAP uses a short fixed-length binary header (4 bytes) that may be
       followed by compact binary options and a payload.  This message
       format is shared by requests and responses.  The CoAP message format
       is specified in Section 3.  Each message contains a Message ID used
       to detect duplicates and for optional reliability.  (The Message ID
       is compact; its 16-bit size enables up to about 250 messages per
       second from one endpoint to another with default protocol
       parameters.)

       Reliability is provided by marking a message as Confirmable (CON).  A
       Confirmable message is retransmitted using a default timeout and
       exponential back-off between retransmissions, until the recipient
       sends an Acknowledgement message (ACK) with the same Message ID (in
       this example, 0x7d34) from the corresponding endpoint; see Figure 2.
       When a recipient is not at all able to process a Confirmable message
       (i.e., not even able to provide a suitable error response), it
       replies with a Reset message (RST) instead of an Acknowledgement
       (ACK).

                            Client              Server
                               |                  |
                               |   CON [0x7d34]   |
                               +----------------->|
                               |                  |
                               |   ACK [0x7d34]   |
                               |<-----------------+
                               |                  |

                      Figure 2: Reliable Message Transmission

       A message that does not require reliable transmission (for example,
       each single measurement out of a stream of sensor data) can be sent
       as a Non-confirmable message (NON).  These are not acknowledged, but
       still have a Message ID for duplicate detection (in this example,
       0x01a0); see Figure 3.  When a recipient is not able to process a
       Non-confirmable message, it may reply with a Reset message (RST).

    Shelby, et al.               Standards Track                   [Page 11]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

                            Client              Server
                               |                  |
                               |   NON [0x01a0]   |
                               +----------------->|
                               |                  |

                     Figure 3: Unreliable Message Transmission

       See Section 4 for details of CoAP messages.

       As CoAP runs over UDP, it also supports the use of multicast IP
       destination addresses, enabling multicast CoAP requests.  Section 8
       discusses the proper use of CoAP messages with multicast addresses
       and precautions for avoiding response congestion.

       Several security modes are defined for CoAP in Section 9 ranging from
       no security to certificate-based security.  This document specifies a
       binding to DTLS for securing the protocol; the use of IPsec with CoAP
       is discussed in [IPsec-CoAP].

    2.2.  Request/Response Model

       CoAP request and response semantics are carried in CoAP messages,
       which include either a Method Code or Response Code, respectively.
       Optional (or default) request and response information, such as the
       URI and payload media type are carried as CoAP options.  A Token is
       used to match responses to requests independently from the underlying
       messages (Section 5.3).  (Note that the Token is a concept separate
       from the Message ID.)

       A request is carried in a Confirmable (CON) or Non-confirmable (NON)
       message, and, if immediately available, the response to a request
       carried in a Confirmable message is carried in the resulting
       Acknowledgement (ACK) message.  This is called a piggybacked
       response, detailed in Section 5.2.1.  (There is no need for
       separately acknowledging a piggybacked response, as the client will
       retransmit the request if the Acknowledgement message carrying the
       piggybacked response is lost.)  Two examples for a basic GET request
       with piggybacked response are shown in Figure 4, one successful, one
       resulting in a 4.04 (Not Found) response.

    Shelby, et al.               Standards Track                   [Page 12]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

            Client              Server       Client              Server
               |                  |             |                  |
               |   CON [0xbc90]   |             |   CON [0xbc91]   |
               | GET /temperature |             | GET /temperature |
               |   (Token 0x71)   |             |   (Token 0x72)   |
               +----------------->|             +----------------->|
               |                  |             |                  |
               |   ACK [0xbc90]   |             |   ACK [0xbc91]   |
               |   2.05 Content   |             |  4.04 Not Found  |
               |   (Token 0x71)   |             |   (Token 0x72)   |
               |     "22.5 C"     |             |   "Not found"    |
               |<-----------------+             |<-----------------+
               |                  |             |                  |

               Figure 4: Two GET Requests with Piggybacked Responses

       If the server is not able to respond immediately to a request carried
       in a Confirmable message, it simply responds with an Empty
       Acknowledgement message so that the client can stop retransmitting
       the request.  When the response is ready, the server sends it in a
       new Confirmable message (which then in turn needs to be acknowledged
       by the client).  This is called a "separate response", as illustrated
       in Figure 5 and described in more detail in Section 5.2.2.

                            Client              Server
                               |                  |
                               |   CON [0x7a10]   |
                               | GET /temperature |
                               |   (Token 0x73)   |
                               +----------------->|
                               |                  |
                               |   ACK [0x7a10]   |
                               |<-----------------+
                               |                  |
                               ... Time Passes  ...
                               |                  |
                               |   CON [0x23bb]   |
                               |   2.05 Content   |
                               |   (Token 0x73)   |
                               |     "22.5 C"     |
                               |<-----------------+
                               |                  |
                               |   ACK [0x23bb]   |
                               +----------------->|
                               |                  |

                 Figure 5: A GET Request with a Separate Response

    Shelby, et al.               Standards Track                   [Page 13]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       If a request is sent in a Non-confirmable message, then the response
       is sent using a new Non-confirmable message, although the server may
       instead send a Confirmable message.  This type of exchange is
       illustrated in Figure 6.

                            Client              Server
                               |                  |
                               |   NON [0x7a11]   |
                               | GET /temperature |
                               |   (Token 0x74)   |
                               +----------------->|
                               |                  |
                               |   NON [0x23bc]   |
                               |   2.05 Content   |
                               |   (Token 0x74)   |
                               |     "22.5 C"     |
                               |<-----------------+
                               |                  |

           Figure 6: A Request and a Response Carried in Non-confirmable
                                     Messages

       CoAP makes use of GET, PUT, POST, and DELETE methods in a similar
       manner to HTTP, with the semantics specified in Section 5.8.  (Note
       that the detailed semantics of CoAP methods are "almost, but not
       entirely unlike" [HHGTTG] those of HTTP methods: intuition taken from
       HTTP experience generally does apply well, but there are enough
       differences that make it worthwhile to actually read the present
       specification.)

       Methods beyond the basic four can be added to CoAP in separate
       specifications.  New methods do not necessarily have to use requests
       and responses in pairs.  Even for existing methods, a single request
       may yield multiple responses, e.g., for a multicast request
       (Section 8) or with the Observe option [OBSERVE].

       URI support in a server is simplified as the client already parses
       the URI and splits it into host, port, path, and query components,
       making use of default values for efficiency.  Response Codes relate
       to a small subset of HTTP status codes with a few CoAP-specific codes
       added, as defined in Section 5.9.

    Shelby, et al.               Standards Track                   [Page 14]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    2.3.  Intermediaries and Caching

       The protocol supports the caching of responses in order to
       efficiently fulfill requests.  Simple caching is enabled using
       freshness and validity information carried with CoAP responses.  A
       cache could be located in an endpoint or an intermediary.  Caching
       functionality is specified in Section 5.6.

       Proxying is useful in constrained networks for several reasons,
       including to limit network traffic, to improve performance, to access
       resources of sleeping devices, and for security reasons.  The
       proxying of requests on behalf of another CoAP endpoint is supported
       in the protocol.  When using a proxy, the URI of the resource to
       request is included in the request, while the destination IP address
       is set to the address of the proxy.  See Section 5.7 for more
       information on proxy functionality.

       As CoAP was designed according to the REST architecture [REST], and
       thus exhibits functionality similar to that of the HTTP protocol, it
       is quite straightforward to map from CoAP to HTTP and from HTTP to
       CoAP.  Such a mapping may be used to realize an HTTP REST interface
       using CoAP or to convert between HTTP and CoAP.  This conversion can
       be carried out by a cross-protocol proxy ("cross-proxy"), which
       converts the Method or Response Code, media type, and options to the
       corresponding HTTP feature.  Section 10 provides more detail about
       HTTP mapping.

    2.4.  Resource Discovery

       Resource discovery is important for machine-to-machine interactions
       and is supported using the CoRE Link Format [RFC6690] as discussed in
       Section 7.

    3.  Message Format

       CoAP is based on the exchange of compact messages that, by default,
       are transported over UDP (i.e., each CoAP message occupies the data
       section of one UDP datagram).  CoAP may also be used over Datagram
       Transport Layer Security (DTLS) (see Section 9.1).  It could also be
       used over other transports such as SMS, TCP, or SCTP, the
       specification of which is out of this document's scope.  (UDP-lite
       [RFC3828] and UDP zero checksum [RFC6936] are not supported by CoAP.)

       CoAP messages are encoded in a simple binary format.  The message
       format starts with a fixed-size 4-byte header.  This is followed by a
       variable-length Token value, which can be between 0 and 8 bytes long.

    Shelby, et al.               Standards Track                   [Page 15]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       Following the Token value comes a sequence of zero or more CoAP
       Options in Type-Length-Value (TLV) format, optionally followed by a
       payload that takes up the rest of the datagram.

        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 7: Message Format

       The fields in the header are defined as follows:

       Version (Ver):  2-bit unsigned integer.  Indicates the CoAP version
          number.  Implementations of this specification MUST set this field
          to 1 (01 binary).  Other values are reserved for future versions.
          Messages with unknown version numbers MUST be silently ignored.

       Type (T):  2-bit unsigned integer.  Indicates if this message is of
          type Confirmable (0), Non-confirmable (1), Acknowledgement (2), or
          Reset (3).  The semantics of these message types are defined in
          Section 4.

       Token Length (TKL):  4-bit unsigned integer.  Indicates the length of
          the variable-length Token field (0-8 bytes).  Lengths 9-15 are
          reserved, MUST NOT be sent, and MUST be processed as a message
          format error.

       Code:  8-bit unsigned integer, split into a 3-bit class (most
          significant bits) and a 5-bit detail (least significant bits),
          documented as "c.dd" where "c" is a digit from 0 to 7 for the
          3-bit subfield and "dd" are two digits from 00 to 31 for the 5-bit
          subfield.  The class can indicate a request (0), a success
          response (2), a client error response (4), or a server error
          response (5).  (All other class values are reserved.)  As a
          special case, Code 0.00 indicates an Empty message.  In case of a
          request, the Code field indicates the Request Method; in case of a
          response, a Response Code.  Possible values are maintained in the
          CoAP Code Registries (Section 12.1).  The semantics of requests
          and responses are defined in Section 5.

    Shelby, et al.               Standards Track                   [Page 16]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       Message ID:  16-bit unsigned integer in network byte order.  Used to
          detect message duplication and to match messages of type
          Acknowledgement/Reset to messages of type Confirmable/Non-
          confirmable.  The rules for generating a Message ID and matching
          messages are defined in Section 4.

       The header is followed by the Token value, which may be 0 to 8 bytes,
       as given by the Token Length field.  The Token value is used to
       correlate requests and responses.  The rules for generating a Token
       and correlating requests and responses are defined in Section 5.3.1.

       Header and Token are followed by zero or more Options (Section 3.1).
       An Option can be followed by the end of the message, by another
       Option, or by the Payload Marker and the payload.

       Following the header, token, and options, if any, comes the optional
       payload.  If present and of non-zero length, it is prefixed by a
       fixed, one-byte Payload Marker (0xFF), which indicates the end of
       options and the start of the payload.  The payload data extends from
       after the marker to the end of the UDP datagram, i.e., the Payload
       Length is calculated from the datagram size.  The absence of the
       Payload Marker denotes a zero-length payload.  The presence of a
       marker followed by a zero-length payload MUST be processed as a
       message format error.

       Implementation Note:  The byte value 0xFF may also occur within an
          option length or value, so simple byte-wise scanning for 0xFF is
          not a viable technique for finding the payload marker.  The byte
          0xFF has the meaning of a payload marker only where the beginning
          of another option could occur.

    3.1.  Option Format

       CoAP defines a number of options that can be included in a message.
       Each option instance in a message specifies the Option Number of the
       defined CoAP option, the length of the Option Value, and the Option
       Value itself.

       Instead of specifying the Option Number directly, the instances MUST
       appear in order of their Option Numbers and a delta encoding is used
       between them: the Option Number for each instance is calculated as
       the sum of its delta and the Option Number of the preceding instance
       in the message.  For the first instance in a message, a preceding
       option instance with Option Number zero is assumed.  Multiple
       instances of the same option can be included by using a delta of
       zero.

    Shelby, et al.               Standards Track                   [Page 17]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       Option Numbers are maintained in the "CoAP Option Numbers" registry
       (Section 12.2).  See Section 5.4 for the semantics of the options
       defined in this document.

         0   1   2   3   4   5   6   7
       +---------------+---------------+
       |               |               |
       |  Option Delta | Option Length |   1 byte
       |               |               |
       +---------------+---------------+
       \                               \
       /         Option Delta          /   0-2 bytes
       \          (extended)           \
       +-------------------------------+
       \                               \
       /         Option Length         /   0-2 bytes
       \          (extended)           \
       +-------------------------------+
       \                               \
       /                               /
       \                               \
       /         Option Value          /   0 or more bytes
       \                               \
       /                               /
       \                               \
       +-------------------------------+

                              Figure 8: Option Format

       The fields in an option are defined as follows:

       Option Delta:  4-bit unsigned integer.  A value between 0 and 12
          indicates the Option Delta.  Three values are reserved for special
          constructs:

          13:  An 8-bit unsigned integer follows the initial byte and
             indicates the Option Delta minus 13.

          14:  A 16-bit unsigned integer in network byte order follows the
             initial byte and indicates the Option Delta minus 269.

          15:  Reserved for the Payload Marker.  If the field is set to this
             value but the entire byte is not the payload marker, this MUST
             be processed as a message format error.

    Shelby, et al.               Standards Track                   [Page 18]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

          The resulting Option Delta is used as the difference between the
          Option Number of this option and that of the previous option (or
          zero for the first option).  In other words, the Option Number is
          calculated by simply summing the Option Delta values of this and
          all previous options before it.

       Option Length:  4-bit unsigned integer.  A value between 0 and 12
          indicates the length of the Option Value, in bytes.  Three values
          are reserved for special constructs:

          13:  An 8-bit unsigned integer precedes the Option Value and
             indicates the Option Length minus 13.

          14:  A 16-bit unsigned integer in network byte order precedes the
             Option Value and indicates the Option Length minus 269.

          15:  Reserved for future use.  If the field is set to this value,
             it MUST be processed as a message format error.

       Value:  A sequence of exactly Option Length bytes.  The length and
          format of the Option Value depend on the respective option, which
          MAY define variable-length values.  See Section 3.2 for the
          formats used in this document; options defined in other documents
          MAY make use of other option value formats.

    3.2.  Option Value Formats

       The options defined in this document make use of the following option
       value formats.

       empty:    A zero-length sequence of bytes.

       opaque:   An opaque sequence of bytes.

       uint:     A non-negative integer that is represented in network byte
                 order using the number of bytes given by the Option Length
                 field.

                 An option definition may specify a range of permissible
                 numbers of bytes; if it has a choice, a sender SHOULD
                 represent the integer with as few bytes as possible, i.e.,
                 without leading zero bytes.  For example, the number 0 is
                 represented with an empty option value (a zero-length
                 sequence of bytes) and the number 1 by a single byte with
                 the numerical value of 1 (bit combination 00000001 in most
                 significant bit first notation).  A recipient MUST be
                 prepared to process values with leading zero bytes.

    Shelby, et al.               Standards Track                   [Page 19]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

                 Implementation Note:  The exceptional behavior permitted
                    for the sender is intended for highly constrained,
                    templated implementations (e.g., hardware
                    implementations) that use fixed-size options in the
                    templates.

       string:   A Unicode string that is encoded using UTF-8 [RFC3629] in
                 Net-Unicode form [RFC5198].

                 Note that here, and in all other places where UTF-8
                 encoding is used in the CoAP protocol, the intention is
                 that the encoded strings can be directly used and compared
                 as opaque byte strings by CoAP protocol implementations.
                 There is no expectation and no need to perform
                 normalization within a CoAP implementation (except where
                 Unicode strings that are not known to be normalized are
                 imported from sources outside the CoAP protocol).  Note
                 also that ASCII strings (that do not make use of special
                 control characters) are always valid UTF-8 Net-Unicode
                 strings.

    4.  Message Transmission

       CoAP messages are exchanged asynchronously between CoAP endpoints.
       They are used to transport CoAP requests and responses, the semantics
       of which are defined in Section 5.

       As CoAP is bound to unreliable transports such as UDP, CoAP messages
       may arrive out of order, appear duplicated, or go missing without
       notice.  For this reason, CoAP implements a lightweight reliability
       mechanism, without trying to re-create the full feature set of a
       transport like TCP.  It has the following features:

       o  Simple stop-and-wait retransmission reliability with exponential
          back-off for Confirmable messages.

       o  Duplicate detection for both Confirmable and Non-confirmable
          messages.

    4.1.  Messages and Endpoints

       A CoAP endpoint is the source or destination of a CoAP message.  The
       specific definition of an endpoint depends on the transport being
       used for CoAP.  For the transports defined in this specification, the
       endpoint is identified depending on the security mode used (see
       Section 9): With no security, the endpoint is solely identified by an
       IP address and a UDP port number.  With other security modes, the
       endpoint is identified as defined by the security mode.

    Shelby, et al.               Standards Track                   [Page 20]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       There are different types of messages.  The type of a message is
       specified by the Type field of the CoAP Header.

       Separate from the message type, a message may carry a request, a
       response, or be Empty.  This is signaled by the Request/Response Code
       field in the CoAP Header and is relevant to the request/response
       model.  Possible values for the field are maintained in the CoAP Code
       Registries (Section 12.1).

       An Empty message has the Code field set to 0.00.  The Token Length
       field MUST be set to 0 and bytes of data MUST NOT be present after
       the Message ID field.  If there are any bytes, they MUST be processed
       as a message format error.

    4.2.  Messages Transmitted Reliably

       The reliable transmission of a message is initiated by marking the
       message as Confirmable in the CoAP header.  A Confirmable message
       always carries either a request or response, unless it is used only
       to elicit a Reset message, in which case it is Empty.  A recipient
       MUST either (a) acknowledge a Confirmable message with an
       Acknowledgement message or (b) reject the message if the recipient
       lacks context to process the message properly, including situations
       where the message is Empty, uses a code with a reserved class (1, 6,
       or 7), or has a message format error.  Rejecting a Confirmable
       message is effected by sending a matching Reset message and otherwise
       ignoring it.  The Acknowledgement message MUST echo the Message ID of
       the Confirmable message and MUST carry a response or be Empty (see
       Sections 5.2.1 and 5.2.2).  The Reset message MUST echo the Message
       ID of the Confirmable message and MUST be Empty.  Rejecting an
       Acknowledgement or Reset message (including the case where the
       Acknowledgement carries a request or a code with a reserved class, or
       the Reset message is not Empty) is effected by silently ignoring it.
       More generally, recipients of Acknowledgement and Reset messages MUST
       NOT respond with either Acknowledgement or Reset messages.

       The sender retransmits the Confirmable message at exponentially
       increasing intervals, until it receives an acknowledgement (or Reset
       message) or runs out of attempts.

       Retransmission is controlled by two things that a CoAP endpoint MUST
       keep track of for each Confirmable message it sends while waiting for
       an acknowledgement (or reset): a timeout and a retransmission
       counter.  For a new Confirmable message, the initial timeout is set
       to a random duration (often not an integral number of seconds)
       between ACK_TIMEOUT and (ACK_TIMEOUT * ACK_RANDOM_FACTOR) (see
       Section 4.8), and the retransmission counter is set to 0.  When the
       timeout is triggered and the retransmission counter is less than

    Shelby, et al.               Standards Track                   [Page 21]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       MAX_RETRANSMIT, the message is retransmitted, the retransmission
       counter is incremented, and the timeout is doubled.  If the
       retransmission counter reaches MAX_RETRANSMIT on a timeout, or if the
       endpoint receives a Reset message, then the attempt to transmit the
       message is canceled and the application process informed of failure.
       On the other hand, if the endpoint receives an acknowledgement in
       time, transmission is considered successful.

       This specification makes no strong requirements on the accuracy of
       the clocks used to implement the above binary exponential back-off
       algorithm.  In particular, an endpoint may be late for a specific
       retransmission due to its sleep schedule and may catch up on the next
       one.  However, the minimum spacing before another retransmission is
       ACK_TIMEOUT, and the entire sequence of (re-)transmissions MUST stay
       in the envelope of MAX_TRANSMIT_SPAN (see Section 4.8.2), even if
       that means a sender may miss an opportunity to transmit.

       A CoAP endpoint that sent a Confirmable message MAY give up in
       attempting to obtain an ACK even before the MAX_RETRANSMIT counter
       value is reached.  For example, the application has canceled the
       request as it no longer needs a response, or there is some other
       indication that the CON message did arrive.  In particular, a CoAP
       request message may have elicited a separate response, in which case
       it is clear to the requester that only the ACK was lost and a
       retransmission of the request would serve no purpose.  However, a
       responder MUST NOT in turn rely on this cross-layer behavior from a
       requester, i.e., it MUST retain the state to create the ACK for the
       request, if needed, even if a Confirmable response was already
       acknowledged by the requester.

       Another reason for giving up retransmission MAY be the receipt of
       ICMP errors.  If it is desired to take account of ICMP errors, to
       mitigate potential spoofing attacks, implementations SHOULD take care
       to check the information about the original datagram in the ICMP
       message, including port numbers and CoAP header information such as
       message type and code, Message ID, and Token; if this is not possible
       due to limitations of the UDP service API, ICMP errors SHOULD be
       ignored.  Packet Too Big errors [RFC4443] ("fragmentation needed and
       DF set" for IPv4 [RFC0792]) cannot properly occur and SHOULD be
       ignored if the implementation note in Section 4.6 is followed;
       otherwise, they SHOULD feed into a path MTU discovery algorithm
       [RFC4821].  Source Quench and Time Exceeded ICMP messages SHOULD be
       ignored.  Host, network, port, or protocol unreachable errors or
       parameter problem errors MAY, after appropriate vetting, be used to
       inform the application of a failure in sending.

    Shelby, et al.               Standards Track                   [Page 22]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    4.3.  Messages Transmitted without Reliability

       Some messages do not require an acknowledgement.  This is
       particularly true for messages that are repeated regularly for
       application requirements, such as repeated readings from a sensor
       where eventual success is sufficient.

       As a more lightweight alternative, a message can be transmitted less
       reliably by marking the message as Non-confirmable.  A Non-
       confirmable message always carries either a request or response and
       MUST NOT be Empty.  A Non-confirmable message MUST NOT be
       acknowledged by the recipient.  A recipient MUST reject the message
       if it lacks context to process the message properly, including the
       case where the message is Empty, uses a code with a reserved class
       (1, 6, or 7), or has a message format error.  Rejecting a Non-
       confirmable message MAY involve sending a matching Reset message, and
       apart from the Reset message the rejected message MUST be silently
       ignored.

       At the CoAP level, there is no way for the sender to detect if a Non-
       confirmable message was received or not.  A sender MAY choose to
       transmit multiple copies of a Non-confirmable message within
       MAX_TRANSMIT_SPAN (limited by the provisions of Section 4.7, in
       particular, by PROBING_RATE if no response is received), or the
       network may duplicate the message in transit.  To enable the receiver
       to act only once on the message, Non-confirmable messages specify a
       Message ID as well.  (This Message ID is drawn from the same number
       space as the Message IDs for Confirmable messages.)

       Summarizing Sections 4.2 and 4.3, the four message types can be used
       as in Table 1.  "*" means that the combination is not used in normal
       operation but only to elicit a Reset message ("CoAP ping").

                       +----------+-----+-----+-----+-----+
                       |          | CON | NON | ACK | RST |
                       +----------+-----+-----+-----+-----+
                       | Request  | X   | X   | -   | -   |
                       | Response | X   | X   | X   | -   |
                       | Empty    | *   | -   | X   | X   |
                       +----------+-----+-----+-----+-----+

                          Table 1: Usage of Message Types

    Shelby, et al.               Standards Track                   [Page 23]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    4.4.  Message Correlation

       An Acknowledgement or Reset message is related to a Confirmable
       message or Non-confirmable message by means of a Message ID along
       with additional address information of the corresponding endpoint.
       The Message ID is a 16-bit unsigned integer that is generated by the
       sender of a Confirmable or Non-confirmable message and included in
       the CoAP header.  The Message ID MUST be echoed in the
       Acknowledgement or Reset message by the recipient.

       The same Message ID MUST NOT be reused (in communicating with the
       same endpoint) within the EXCHANGE_LIFETIME (Section 4.8.2).

       Implementation Note:  Several implementation strategies can be
          employed for generating Message IDs.  In the simplest case, a CoAP
          endpoint generates Message IDs by keeping a single Message ID
          variable, which is changed each time a new Confirmable or Non-
          confirmable message is sent, regardless of the destination address
          or port.  Endpoints dealing with large numbers of transactions
          could keep multiple Message ID variables, for example, per prefix
          or destination address.  (Note that some receiving endpoints may
          not be able to distinguish unicast and multicast packets addressed
          to it, so endpoints generating Message IDs need to make sure these
          do not overlap.)  It is strongly recommended that the initial
          value of the variable (e.g., on startup) be randomized, in order
          to make successful off-path attacks on the protocol less likely.

       For an Acknowledgement or Reset message to match a Confirmable or
       Non-confirmable message, the Message ID and source endpoint of the
       Acknowledgement or Reset message MUST match the Message ID and
       destination endpoint of the Confirmable or Non-confirmable message.

    4.5.  Message Deduplication

       A recipient might receive the same Confirmable message (as indicated
       by the Message ID and source endpoint) multiple times within the
       EXCHANGE_LIFETIME (Section 4.8.2), for example, when its
       Acknowledgement went missing or didn't reach the original sender
       before the first timeout.  The recipient SHOULD acknowledge each
       duplicate copy of a Confirmable message using the same
       Acknowledgement or Reset message but SHOULD process any request or
       response in the message only once.  This rule MAY be relaxed in case
       the Confirmable message transports a request that is idempotent (see
       Section 5.1) or can be handled in an idempotent fashion.  Examples
       for relaxed message deduplication:

    Shelby, et al.               Standards Track                   [Page 24]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       o  A server might relax the requirement to answer all retransmissions
          of an idempotent request with the same response (Section 4.2), so
          that it does not have to maintain state for Message IDs.  For
          example, an implementation might want to process duplicate
          transmissions of a GET, PUT, or DELETE request as separate
          requests if the effort incurred by duplicate processing is less
          expensive than keeping track of previous responses would be.

       o  A constrained server might even want to relax this requirement for
          certain non-idempotent requests if the application semantics make
          this trade-off favorable.  For example, if the result of a POST
          request is just the creation of some short-lived state at the
          server, it may be less expensive to incur this effort multiple
          times for a request than keeping track of whether a previous
          transmission of the same request already was processed.

       A recipient might receive the same Non-confirmable message (as
       indicated by the Message ID and source endpoint) multiple times
       within NON_LIFETIME (Section 4.8.2).  As a general rule that MAY be
       relaxed based on the specific semantics of a message, the recipient
       SHOULD silently ignore any duplicated Non-confirmable message and
       SHOULD process any request or response in the message only once.

    4.6.  Message Size

       While specific link layers make it beneficial to keep CoAP messages
       small enough to fit into their link-layer packets (see Section 1),
       this is a matter of implementation quality.  The CoAP specification
       itself provides only an upper bound to the message size.  Messages
       larger than an IP packet result in undesirable packet fragmentation.
       A CoAP message, appropriately encapsulated, SHOULD fit within a
       single IP packet (i.e., avoid IP fragmentation) and (by fitting into
       one UDP payload) obviously needs to fit within a single IP datagram.
       If the Path MTU is not known for a destination, an IP MTU of 1280
       bytes SHOULD be assumed; if nothing is known about the size of the
       headers, good upper bounds are 1152 bytes for the message size and
       1024 bytes for the payload size.

       Implementation Note:  CoAP's choice of message size parameters works
          well with IPv6 and with most of today's IPv4 paths.  (However,
          with IPv4, it is harder to absolutely ensure that there is no IP
          fragmentation.  If IPv4 support on unusual networks is a
          consideration, implementations may want to limit themselves to
          more conservative IPv4 datagram sizes such as 576 bytes; per
          [RFC0791], the absolute minimum value of the IP MTU for IPv4 is as
          low as 68 bytes, which would leave only 40 bytes minus security
          overhead for a UDP payload.  Implementations extremely focused on
          this problem set might also set the IPv4 DF bit and perform some

    Shelby, et al.               Standards Track                   [Page 25]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

          form of path MTU discovery [RFC4821]; this should generally be
          unnecessary in realistic use cases for CoAP, however.)  A more
          important kind of fragmentation in many constrained networks is
          that on the adaptation layer (e.g., 6LoWPAN L2 packets are limited
          to 127 bytes including various overheads); this may motivate
          implementations to be frugal in their packet sizes and to move to
          block-wise transfers [BLOCK] when approaching three-digit message
          sizes.

          Message sizes are also of considerable importance to
          implementations on constrained nodes.  Many implementations will
          need to allocate a buffer for incoming messages.  If an
          implementation is too constrained to allow for allocating the
          above-mentioned upper bound, it could apply the following
          implementation strategy for messages not using DTLS security:
          Implementations receiving a datagram into a buffer that is too
          small are usually able to determine if the trailing portion of a
          datagram was discarded and to retrieve the initial portion.  So,
          at least the CoAP header and options, if not all of the payload,
          are likely to fit within the buffer.  A server can thus fully
          interpret a request and return a 4.13 (Request Entity Too Large;
          see Section 5.9.2.9) Response Code if the payload was truncated.
          A client sending an idempotent request and receiving a response
          larger than would fit in the buffer can repeat the request with a
          suitable value for the Block Option [BLOCK].

    4.7.  Congestion Control

       Basic congestion control for CoAP is provided by the exponential
       back-off mechanism in Section 4.2.

       In order not to cause congestion, clients (including proxies) MUST
       strictly limit the number of simultaneous outstanding interactions
       that they maintain to a given server (including proxies) to NSTART.
       An outstanding interaction is either a CON for which an ACK has not
       yet been received but is still expected (message layer) or a request
       for which neither a response nor an Acknowledgment message has yet
       been received but is still expected (which may both occur at the same
       time, counting as one outstanding interaction).  The default value of
       NSTART for this specification is 1.

       Further congestion control optimizations and considerations are
       expected in the future, may for example provide automatic
       initialization of the CoAP transmission parameters defined in
       Section 4.8, and thus may allow a value for NSTART greater than one.

       After EXCHANGE_LIFETIME, a client stops expecting a response to a
       Confirmable request for which no acknowledgment message was received.

    Shelby, et al.               Standards Track                   [Page 26]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       The specific algorithm by which a client stops to "expect" a response
       to a Confirmable request that was acknowledged, or to a Non-
       confirmable request, is not defined.  Unless this is modified by
       additional congestion control optimizations, it MUST be chosen in
       such a way that an endpoint does not exceed an average data rate of
       PROBING_RATE in sending to another endpoint that does not respond.

       Note:  CoAP places the onus of congestion control mostly on the
          clients.  However, clients may malfunction or actually be
          attackers, e.g., to perform amplification attacks (Section 11.3).
          To limit the damage (to the network and to its own energy
          resources), a server SHOULD implement some rate limiting for its
          response transmission based on reasonable assumptions about
          application requirements.  This is most helpful if the rate limit
          can be made effective for the misbehaving endpoints, only.

    4.8.  Transmission Parameters

       Message transmission is controlled by the following parameters:

                       +-------------------+---------------+
                       | name              | default value |
                       +-------------------+---------------+
                       | ACK_TIMEOUT       | 2 seconds     |
                       | ACK_RANDOM_FACTOR | 1.5           |
                       | MAX_RETRANSMIT    | 4             |
                       | NSTART            | 1             |
                       | DEFAULT_LEISURE   | 5 seconds     |
                       | PROBING_RATE      | 1 byte/second |
                       +-------------------+---------------+

                         Table 2: CoAP Protocol Parameters

    4.8.1.  Changing the Parameters

       The values for ACK_TIMEOUT, ACK_RANDOM_FACTOR, MAX_RETRANSMIT,
       NSTART, DEFAULT_LEISURE (Section 8.2), and PROBING_RATE may be
       configured to values specific to the application environment
       (including dynamically adjusted values); however, the configuration
       method is out of scope of this document.  It is RECOMMENDED that an
       application environment use consistent values for these parameters;
       the specific effects of operating with inconsistent values in an
       application environment are outside the scope of the present
       specification.

       The transmission parameters have been chosen to achieve a behavior in
       the presence of congestion that is safe in the Internet.  If a
       configuration desires to use different values, the onus is on the

    Shelby, et al.               Standards Track                   [Page 27]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       configuration to ensure these congestion control properties are not
       violated.  In particular, a decrease of ACK_TIMEOUT below 1 second
       would violate the guidelines of [RFC5405].  ([RTO-CONSIDER] provides
       some additional background.)  CoAP was designed to enable
       implementations that do not maintain round-trip-time (RTT)
       measurements.  However, where it is desired to decrease the
       ACK_TIMEOUT significantly or increase NSTART, this can only be done
       safely when maintaining such measurements.  Configurations MUST NOT
       decrease ACK_TIMEOUT or increase NSTART without using mechanisms that
       ensure congestion control safety, either defined in the configuration
       or in future standards documents.

       ACK_RANDOM_FACTOR MUST NOT be decreased below 1.0, and it SHOULD have
       a value that is sufficiently different from 1.0 to provide some
       protection from synchronization effects.

       MAX_RETRANSMIT can be freely adjusted, but a value that is too small
       will reduce the probability that a Confirmable message is actually
       received, while a larger value than given here will require further
       adjustments in the time values (see Section 4.8.2).

       If the choice of transmission parameters leads to an increase of
       derived time values (see Section 4.8.2), the configuration mechanism
       MUST ensure the adjusted value is also available to all the endpoints
       with which these adjusted values are to be used to communicate.

    4.8.2.  Time Values Derived from Transmission Parameters

       The combination of ACK_TIMEOUT, ACK_RANDOM_FACTOR, and MAX_RETRANSMIT
       influences the timing of retransmissions, which in turn influences
       how long certain information items need to be kept by an
       implementation.  To be able to unambiguously reference these derived
       time values, we give them names as follows:

       o  MAX_TRANSMIT_SPAN is the maximum time from the first transmission
          of a Confirmable message to its last retransmission.  For the
          default transmission parameters, the value is (2+4+8+16)*1.5 = 45
          seconds, or more generally:

             ACK_TIMEOUT * ((2 ** MAX_RETRANSMIT) - 1) * ACK_RANDOM_FACTOR

    Shelby, et al.               Standards Track                   [Page 28]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       o  MAX_TRANSMIT_WAIT is the maximum time from the first transmission
          of a Confirmable message to the time when the sender gives up on
          receiving an acknowledgement or reset.  For the default
          transmission parameters, the value is (2+4+8+16+32)*1.5 = 93
          seconds, or more generally:

             ACK_TIMEOUT * ((2 ** (MAX_RETRANSMIT + 1)) - 1) *
             ACK_RANDOM_FACTOR

       In addition, some assumptions need to be made on the characteristics
       of the network and the nodes.

       o  MAX_LATENCY is the maximum time a datagram is expected to take
          from the start of its transmission to the completion of its
          reception.  This constant is related to the MSL (Maximum Segment
          Lifetime) of [RFC0793], which is "arbitrarily defined to be 2
          minutes" ([RFC0793] glossary, page 81).  Note that this is not
          necessarily smaller than MAX_TRANSMIT_WAIT, as MAX_LATENCY is not
          intended to describe a situation when the protocol works well, but
          the worst-case situation against which the protocol has to guard.
          We, also arbitrarily, define MAX_LATENCY to be 100 seconds.  Apart
          from being reasonably realistic for the bulk of configurations as
          well as close to the historic choice for TCP, this value also
          allows Message ID lifetime timers to be represented in 8 bits
          (when measured in seconds).  In these calculations, there is no
          assumption that the direction of the transmission is irrelevant
          (i.e., that the network is symmetric); there is just the
          assumption that the same value can reasonably be used as a maximum
          value for both directions.  If that is not the case, the following
          calculations become only slightly more complex.

       o  PROCESSING_DELAY is the time a node takes to turn around a
          Confirmable message into an acknowledgement.  We assume the node
          will attempt to send an ACK before having the sender time out, so
          as a conservative assumption we set it equal to ACK_TIMEOUT.

       o  MAX_RTT is the maximum round-trip time, or:

             (2 * MAX_LATENCY) + PROCESSING_DELAY

       From these values, we can derive the following values relevant to the
       protocol operation:

       o  EXCHANGE_LIFETIME is the time from starting to send a Confirmable
          message to the time when an acknowledgement is no longer expected,
          i.e., message-layer information about the message exchange can be
          purged.  EXCHANGE_LIFETIME includes a MAX_TRANSMIT_SPAN, a
          MAX_LATENCY forward, PROCESSING_DELAY, and a MAX_LATENCY for the

    Shelby, et al.               Standards Track                   [Page 29]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

          way back.  Note that there is no need to consider
          MAX_TRANSMIT_WAIT if the configuration is chosen such that the
          last waiting period (ACK_TIMEOUT * (2 ** MAX_RETRANSMIT) or the
          difference between MAX_TRANSMIT_SPAN and MAX_TRANSMIT_WAIT) is
          less than MAX_LATENCY -- which is a likely choice, as MAX_LATENCY
          is a worst-case value unlikely to be met in the real world.  In
          this case, EXCHANGE_LIFETIME simplifies to:

             MAX_TRANSMIT_SPAN + (2 * MAX_LATENCY) + PROCESSING_DELAY

          or 247 seconds with the default transmission parameters.

       o  NON_LIFETIME is the time from sending a Non-confirmable message to
          the time its Message ID can be safely reused.  If multiple
          transmission of a NON message is not used, its value is
          MAX_LATENCY, or 100 seconds.  However, a CoAP sender might send a
          NON message multiple times, in particular for multicast
          applications.  While the period of reuse is not bounded by the
          specification, an expectation of reliable detection of duplication
          at the receiver is on the timescales of MAX_TRANSMIT_SPAN.
          Therefore, for this purpose, it is safer to use the value:

             MAX_TRANSMIT_SPAN + MAX_LATENCY

          or 145 seconds with the default transmission parameters; however,
          an implementation that just wants to use a single timeout value
          for retiring Message IDs can safely use the larger value for
          EXCHANGE_LIFETIME.

       Table 3 lists the derived parameters introduced in this subsection
       with their default values.

                       +-------------------+---------------+
                       | name              | default value |
                       +-------------------+---------------+
                       | MAX_TRANSMIT_SPAN |          45 s |
                       | MAX_TRANSMIT_WAIT |          93 s |
                       | MAX_LATENCY       |         100 s |
                       | PROCESSING_DELAY  |           2 s |
                       | MAX_RTT           |         202 s |
                       | EXCHANGE_LIFETIME |         247 s |
                       | NON_LIFETIME      |         145 s |
                       +-------------------+---------------+

                       Table 3: Derived Protocol Parameters

    Shelby, et al.               Standards Track                   [Page 30]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    5.  Request/Response Semantics

       CoAP operates under a similar request/response model as HTTP: a CoAP
       endpoint in the role of a "client" sends one or more CoAP requests to
       a "server", which services the requests by sending CoAP responses.
       Unlike HTTP, requests and responses are not sent over a previously
       established connection but are exchanged asynchronously over CoAP
       messages.

    5.1.  Requests

       A CoAP request consists of the method to be applied to the resource,
       the identifier of the resource, a payload and Internet media type (if
       any), and optional metadata about the request.

       CoAP supports the basic methods of GET, POST, PUT, and DELETE, which
       are easily mapped to HTTP.  They have the same properties of safe
       (only retrieval) and idempotent (you can invoke it multiple times
       with the same effects) as HTTP (see Section 9.1 of [RFC2616]).  The
       GET method is safe; therefore, it MUST NOT take any other action on a
       resource other than retrieval.  The GET, PUT, and DELETE methods MUST
       be performed in such a way that they are idempotent.  POST is not
       idempotent, because its effect is determined by the origin server and
       dependent on the target resource; it usually results in a new
       resource being created or the target resource being updated.

       A request is initiated by setting the Code field in the CoAP header
       of a Confirmable or a Non-confirmable message to a Method Code and
       including request information.

       The methods used in requests are described in detail in Section 5.8.

    5.2.  Responses

       After receiving and interpreting a request, a server responds with a
       CoAP response that is matched to the request by means of a client-
       generated token (Section 5.3); note that this is different from the
       Message ID that matches a Confirmable message to its Acknowledgement.

       A response is identified by the Code field in the CoAP header being
       set to a Response Code.  Similar to the HTTP Status Code, the CoAP
       Response Code indicates the result of the attempt to understand and
       satisfy the request.  These codes are fully defined in Section 5.9.
       The Response Code numbers to be set in the Code field of the CoAP
       header are maintained in the CoAP Response Code Registry
       (Section 12.1.2).

    Shelby, et al.               Standards Track                   [Page 31]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

                                  0
                                  0 1 2 3 4 5 6 7
                                 +-+-+-+-+-+-+-+-+
                                 |class|  detail |
                                 +-+-+-+-+-+-+-+-+

                      Figure 9: Structure of a Response Code

       The upper three bits of the 8-bit Response Code number define the
       class of response.  The lower five bits do not have any
       categorization role; they give additional detail to the overall class
       (Figure 9).

       As a human-readable notation for specifications and protocol
       diagnostics, CoAP code numbers including the Response Code are
       documented in the format "c.dd", where "c" is the class in decimal,
       and "dd" is the detail as a two-digit decimal.  For example,
       "Forbidden" is written as 4.03 -- indicating an 8-bit code value of
       hexadecimal 0x83 (4*0x20+3) or decimal 131 (4*32+3).

       There are 3 classes of Response Codes:

       2 - Success:  The request was successfully received, understood, and
          accepted.

       4 - Client Error:  The request contains bad syntax or cannot be
          fulfilled.

       5 - Server Error:  The server failed to fulfill an apparently valid
          request.

       The Response Codes are designed to be extensible: Response Codes in
       the Client Error or Server Error class that are unrecognized by an
       endpoint are treated as being equivalent to the generic Response Code
       of that class (4.00 and 5.00, respectively).  However, there is no
       generic Response Code indicating success, so a Response Code in the
       Success class that is unrecognized by an endpoint can only be used to
       determine that the request was successful without any further
       details.

       The possible Response Codes are described in detail in Section 5.9.

       Responses can be sent in multiple ways, which are defined in the
       following subsections.

    Shelby, et al.               Standards Track                   [Page 32]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    5.2.1.  Piggybacked

       In the most basic case, the response is carried directly in the
       Acknowledgement message that acknowledges the request (which requires
       that the request was carried in a Confirmable message).  This is
       called a "Piggybacked Response".

       The response is returned in the Acknowledgement message, independent
       of whether the response indicates success or failure.  In effect, the
       response is piggybacked on the Acknowledgement message, and no
       separate message is required to return the response.

       Implementation Note:  The protocol leaves the decision whether to
          piggyback a response or not (i.e., send a separate response) to
          the server.  The client MUST be prepared to receive either.  On
          the quality-of-implementation level, there is a strong expectation
          that servers will implement code to piggyback whenever possible --
          saving resources in the network and both at the client and at the
          server.

    5.2.2.  Separate

       It may not be possible to return a piggybacked response in all cases.
       For example, a server might need longer to obtain the representation
       of the resource requested than it can wait to send back the
       Acknowledgement message, without risking the client repeatedly
       retransmitting the request message (see also the discussion of
       PROCESSING_DELAY in Section 4.8.2).  The response to a request
       carried in a Non-confirmable message is always sent separately (as
       there is no Acknowledgement message).

       One way to implement this in a server is to initiate the attempt to
       obtain the resource representation and, while that is in progress,
       time out an acknowledgement timer.  A server may also immediately
       send an acknowledgement if it knows in advance that there will be no
       piggybacked response.  In both cases, the acknowledgement effectively
       is a promise that the request will be acted upon later.

       When the server finally has obtained the resource representation, it
       sends the response.  When it is desired that this message is not
       lost, it is sent as a Confirmable message from the server to the
       client and answered by the client with an Acknowledgement, echoing
       the new Message ID chosen by the server.  (It may also be sent as a
       Non-confirmable message; see Section 5.2.3.)

       When the server chooses to use a separate response, it sends the
       Acknowledgement to the Confirmable request as an Empty message.  Once
       the server sends back an Empty Acknowledgement, it MUST NOT send back

    Shelby, et al.               Standards Track                   [Page 33]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       the response in another Acknowledgement, even if the client
       retransmits another identical request.  If a retransmitted request is
       received (perhaps because the original Acknowledgement was delayed),
       another Empty Acknowledgement is sent, and any response MUST be sent
       as a separate response.

       If the server then sends a Confirmable response, the client's
       Acknowledgement to that response MUST also be an Empty message (one
       that carries neither a request nor a response).  The server MUST stop
       retransmitting its response on any matching Acknowledgement (silently
       ignoring any Response Code or payload) or Reset message.

       Implementation Notes:  Note that, as the underlying datagram
          transport may not be sequence-preserving, the Confirmable message
          carrying the response may actually arrive before or after the
          Acknowledgement message for the request; for the purposes of
          terminating the retransmission sequence, this also serves as an
          acknowledgement.  Note also that, while the CoAP protocol itself
          does not make any specific demands here, there is an expectation
          that the response will come within a time frame that is reasonable
          from an application point of view.  As there is no underlying
          transport protocol that could be instructed to run a keep-alive
          mechanism, the requester may want to set up a timeout that is
          unrelated to CoAP's retransmission timers in case the server is
          destroyed or otherwise unable to send the response.

    5.2.3.  Non-confirmable

       If the request message is Non-confirmable, then the response SHOULD
       be returned in a Non-confirmable message as well.  However, an
       endpoint MUST be prepared to receive a Non-confirmable response
       (preceded or followed by an Empty Acknowledgement message) in reply
       to a Confirmable request, or a Confirmable response in reply to a
       Non-confirmable request.

    5.3.  Request/Response Matching

       Regardless of how a response is sent, it is matched to the request by
       means of a token that is included by the client in the request, along
       with additional address information of the corresponding endpoint.

    5.3.1.  Token

       The Token is used to match a response with a request.  The token
       value is a sequence of 0 to 8 bytes.  (Note that every message
       carries a token, even if it is of zero length.)  Every request
       carries a client-generated token that the server MUST echo (without
       modification) in any resulting response.

    Shelby, et al.               Standards Track                   [Page 34]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       A token is intended for use as a client-local identifier for
       differentiating between concurrent requests (see Section 5.3); it
       could have been called a "request ID".

       The client SHOULD generate tokens in such a way that tokens currently
       in use for a given source/destination endpoint pair are unique.
       (Note that a client implementation can use the same token for any
       request if it uses a different endpoint each time, e.g., a different
       source port number.)  An empty token value is appropriate e.g., when
       no other tokens are in use to a destination, or when requests are
       made serially per destination and receive piggybacked responses.
       There are, however, multiple possible implementation strategies to
       fulfill this.

       A client sending a request without using Transport Layer Security
       (Section 9) SHOULD use a nontrivial, randomized token to guard
       against spoofing of responses (Section 11.4).  This protective use of
       tokens is the reason they are allowed to be up to 8 bytes in size.
       The actual size of the random component to be used for the Token
       depends on the security requirements of the client and the level of
       threat posed by spoofing of responses.  A client that is connected to
       the general Internet SHOULD use at least 32 bits of randomness,
       keeping in mind that not being directly connected to the Internet is
       not necessarily sufficient protection against spoofing.  (Note that
       the Message ID adds little in protection as it is usually
       sequentially assigned, i.e., guessable, and can be circumvented by
       spoofing a separate response.)  Clients that want to optimize the
       Token length may further want to detect the level of ongoing attacks
       (e.g., by tallying recent Token mismatches in incoming messages) and
       adjust the Token length upwards appropriately.  [RFC4086] discusses
       randomness requirements for security.

       An endpoint receiving a token it did not generate MUST treat the
       token as opaque and make no assumptions about its content or
       structure.

    5.3.2.  Request/Response Matching Rules

       The exact rules for matching a response to a request are as follows:

       1.  The source endpoint of the response MUST be the same as the
           destination endpoint of the original request.

       2.  In a piggybacked response, the Message ID of the Confirmable
           request and the Acknowledgement MUST match, and the tokens of the
           response and original request MUST match.  In a separate
           response, just the tokens of the response and original request
           MUST match.

    Shelby, et al.               Standards Track                   [Page 35]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       In case a message carrying a response is unexpected (the client is
       not waiting for a response from the identified endpoint, at the
       endpoint addressed, and/or with the given token), the response is
       rejected (Sections 4.2 and 4.3).

       Implementation Note:  A client that receives a response in a CON
          message may want to clean up the message state right after sending
          the ACK.  If that ACK is lost and the server retransmits the CON,
          the client may no longer have any state to which to correlate this
          response, making the retransmission an unexpected message; the
          client will likely send a Reset message so it does not receive any
          more retransmissions.  This behavior is normal and not an
          indication of an error.  (Clients that are not aggressively
          optimized in their state memory usage will still have message
          state that will identify the second CON as a retransmission.
          Clients that actually expect more messages from the server
          [OBSERVE] will have to keep state in any case.)

    5.4.  Options

       Both requests and responses may include a list of one or more
       options.  For example, the URI in a request is transported in several
       options, and metadata that would be carried in an HTTP header in HTTP
       is supplied as options as well.

       CoAP defines a single set of options that are used in both requests
       and responses:

       o  Content-Format

       o  ETag

       o  Location-Path

       o  Location-Query

       o  Max-Age

       o  Proxy-Uri

       o  Proxy-Scheme

       o  Uri-Host

       o  Uri-Path

       o  Uri-Port

    Shelby, et al.               Standards Track                   [Page 36]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       o  Uri-Query

       o  Accept

       o  If-Match

       o  If-None-Match

       o  Size1

       The semantics of these options along with their properties are
       defined in detail in Section 5.10.

       Not all options are defined for use with all methods and Response
       Codes.  The possible options for methods and Response Codes are
       defined in Sections 5.8 and 5.9, respectively.  In case an option is
       not defined for a Method or Response Code, it MUST NOT be included by
       a sender and MUST be treated like an unrecognized option by a
       recipient.

    5.4.1.  Critical/Elective

       Options fall into one of two classes: "critical" or "elective".  The
       difference between these is how an option unrecognized by an endpoint
       is handled:

       o  Upon reception, unrecognized options of class "elective" MUST be
          silently ignored.

       o  Unrecognized options of class "critical" that occur in a
          Confirmable request MUST cause the return of a 4.02 (Bad Option)
          response.  This response SHOULD include a diagnostic payload
          describing the unrecognized option(s) (see Section 5.5.2).

       o  Unrecognized options of class "critical" that occur in a
          Confirmable response, or piggybacked in an Acknowledgement, MUST
          cause the response to be rejected (Section 4.2).

       o  Unrecognized options of class "critical" that occur in a Non-
          confirmable message MUST cause the message to be rejected
          (Section 4.3).

       Note that, whether critical or elective, an option is never
       "mandatory" (it is always optional): these rules are defined in order
       to enable implementations to stop processing options they do not
       understand or implement.

    Shelby, et al.               Standards Track                   [Page 37]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       Critical/elective rules apply to non-proxying endpoints.  A proxy
       processes options based on Unsafe/Safe-to-Forward classes as defined
       in Section 5.7.

    5.4.2.  Proxy Unsafe or Safe-to-Forward and NoCacheKey

       In addition to an option being marked as critical or elective,
       options are also classified based on how a proxy is to deal with the
       option if it does not recognize it.  For this purpose, an option can
       either be considered Unsafe to forward (UnSafe is set) or Safe-to-
       Forward (UnSafe is clear).

       In addition, for an option that is marked Safe-to-Forward, the option
       number indicates whether or not it is intended to be part of the
       Cache-Key (Section 5.6) in a request.  If some of the NoCacheKey bits
       are 0, it is; if all NoCacheKey bits are 1, it is not (see
       Section 5.4.6).

       Note:  The Cache-Key indication is relevant only for proxies that do
          not implement the given option as a request option and instead
          rely on the Unsafe/Safe-to-Forward indication only.  For example,
          for ETag, actually using the request option as a part of the
          Cache-Key is grossly inefficient, but it is the best thing one can
          do if ETag is not implemented by a proxy, as the response is going
          to differ based on the presence of the request option.  A more
          useful proxy that does implement the ETag request option is not
          using ETag as a part of the Cache-Key.

          NoCacheKey is indicated in three bits so that only one out of
          eight codepoints is qualified as NoCacheKey, leaving seven out of
          eight codepoints for what appears to be the more likely case.

       Proxy behavior with regard to these classes is defined in
       Section 5.7.

    5.4.3.  Length

       Option values are defined to have a specific length, often in the
       form of an upper and lower bound.  If the length of an option value
       in a request is outside the defined range, that option MUST be
       treated like an unrecognized option (see Section 5.4.1).

    5.4.4.  Default Values

       Options may be defined to have a default value.  If the value of an
       option is intended to be this default value, the option SHOULD NOT be
       included in the message.  If the option is not present, the default
       value MUST be assumed.

    Shelby, et al.               Standards Track                   [Page 38]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       Where a critical option has a default value, this is chosen in such a
       way that the absence of the option in a message can be processed
       properly both by implementations unaware of the critical option and
       by implementations that interpret this absence as the presence of the
       default value for the option.

    5.4.5.  Repeatable Options

       The definition of some options specifies that those options are
       repeatable.  An option that is repeatable MAY be included one or more
       times in a message.  An option that is not repeatable MUST NOT be
       included more than once in a message.

       If a message includes an option with more occurrences than the option
       is defined for, each supernumerary option occurrence that appears
       subsequently in the message MUST be treated like an unrecognized
       option (see Section 5.4.1).

    5.4.6.  Option Numbers

       An Option is identified by an option number, which also provides some
       additional semantics information, e.g., odd numbers indicate a
       critical option, while even numbers indicate an elective option.
       Note that this is not just a convention, it is a feature of the
       protocol: Whether an option is elective or critical is entirely
       determined by whether its option number is even or odd.

       More generally speaking, an Option number is constructed with a bit
       mask to indicate if an option is Critical or Elective, Unsafe or
       Safe-to-Forward, and, in the case of Safe-to-Forward, to provide a
       Cache-Key indication as shown by the following figure.  In the
       following text, the bit mask is expressed as a single byte that is
       applied to the least significant byte of the option number in
       unsigned integer representation.  When bit 7 (the least significant
       bit) is 1, an option is Critical (and likewise Elective when 0).
       When bit 6 is 1, an option is Unsafe (and likewise Safe-to-Forward
       when 0).  When bit 6 is 0, i.e., the option is not Unsafe, it is not
       a Cache-Key (NoCacheKey) if and only if bits 3-5 are all set to 1;
       all other bit combinations mean that it indeed is a Cache-Key.  These
       classes of options are explained in the next sections.

                           0   1   2   3   4   5   6   7
                         +---+---+---+---+---+---+---+---+
                         |           | NoCacheKey| U | C |
                         +---+---+---+---+---+---+---+---+

              Figure 10: Option Number Mask (Least Significant Byte)

    Shelby, et al.               Standards Track                   [Page 39]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       An endpoint may use an equivalent of the C code in Figure 11 to
       derive the characteristics of an option number "onum".

       Critical = (onum & 1);
       UnSafe = (onum & 2);
       NoCacheKey = ((onum & 0x1e) == 0x1c);

           Figure 11: Determining Characteristics from an Option Number

       The option numbers for the options defined in this document are
       listed in the "CoAP Option Numbers" registry (Section 12.2).

    5.5.  Payloads and Representations

       Both requests and responses may include a payload, depending on the
       Method or Response Code, respectively.  If a Method or Response Code
       is not defined to have a payload, then a sender MUST NOT include one,
       and a recipient MUST ignore it.

    5.5.1.  Representation

       The payload of requests or of responses indicating success is
       typically a representation of a resource ("resource representation")
       or the result of the requested action ("action result").  Its format
       is specified by the Internet media type and content coding given by
       the Content-Format Option.  In the absence of this option, no default
       value is assumed, and the format will need to be inferred by the
       application (e.g., from the application context).  Payload "sniffing"
       SHOULD only be attempted if no content type is given.

       Implementation Note:  On a quality-of-implementation level, there is
          a strong expectation that a Content-Format indication will be
          provided with resource representations whenever possible.  This is
          not a "SHOULD" level requirement solely because it is not a
          protocol requirement, and it also would be difficult to outline
          exactly in what cases this expectation can be violated.

       For responses indicating a client or server error, the payload is
       considered a representation of the result of the requested action
       only if a Content-Format Option is given.  In the absence of this
       option, the payload is a Diagnostic Payload (Section 5.5.2).

    Shelby, et al.               Standards Track                   [Page 40]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    5.5.2.  Diagnostic Payload

       If no Content-Format option is given, the payload of responses
       indicating a client or server error is a brief human-readable
       diagnostic message, explaining the error situation.  This diagnostic
       message MUST be encoded using UTF-8 [RFC3629], more specifically
       using Net-Unicode form [RFC5198].

       The message is similar to the Reason-Phrase on an HTTP status line.
       It is not intended for end users but for software engineers that
       during debugging need to interpret it in the context of the present,
       English-language specification; therefore, no mechanism for language
       tagging is needed or provided.  In contrast to what is usual in HTTP,
       the payload SHOULD be empty if there is no additional information
       beyond the Response Code.

    5.5.3.  Selected Representation

       Not all responses carry a payload that provides a representation of
       the resource addressed by the request.  It is, however, sometimes
       useful to be able to refer to such a representation in relation to a
       response, independent of whether it actually was enclosed.

       We use the term "selected representation" to refer to the current
       representation of a target resource that would have been selected in
       a successful response if the corresponding request had used the
       method GET and excluded any conditional request options
       (Section 5.10.8).

       Certain response options provide metadata about the selected
       representation, which might differ from the representation included
       in the message for responses to some state-changing methods.  Of the
       response options defined in this specification, only the ETag
       response option (Section 5.10.6) is defined as metadata about the
       selected representation.

    5.5.4.  Content Negotiation

       A server may be able to supply a representation for a resource in one
       of multiple representation formats.  Without further information from
       the client, it will provide the representation in the format it
       prefers.

       By using the Accept Option (Section 5.10.4) in a request, the client
       can indicate which content-format it prefers to receive.

    Shelby, et al.               Standards Track                   [Page 41]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    5.6.  Caching

       CoAP endpoints MAY cache responses in order to reduce the response
       time and network bandwidth consumption on future, equivalent
       requests.

       The goal of caching in CoAP is to reuse a prior response message to
       satisfy a current request.  In some cases, a stored response can be
       reused without the need for a network request, reducing latency and
       network round-trips; a "freshness" mechanism is used for this purpose
       (see Section 5.6.1).  Even when a new request is required, it is
       often possible to reuse the payload of a prior response to satisfy
       the request, thereby reducing network bandwidth usage; a "validation"
       mechanism is used for this purpose (see Section 5.6.2).

       Unlike HTTP, the cacheability of CoAP responses does not depend on
       the request method, but it depends on the Response Code.  The
       cacheability of each Response Code is defined along the Response Code
       definitions in Section 5.9.  Response Codes that indicate success and
       are unrecognized by an endpoint MUST NOT be cached.

       For a presented request, a CoAP endpoint MUST NOT use a stored
       response, unless:

       o  the presented request method and that used to obtain the stored
          response match,

       o  all options match between those in the presented request and those
          of the request used to obtain the stored response (which includes
          the request URI), except that there is no need for a match of any
          request options marked as NoCacheKey (Section 5.4) or recognized
          by the Cache and fully interpreted with respect to its specified
          cache behavior (such as the ETag request option described in
          Section 5.10.6; see also Section 5.4.2), and

       o  the stored response is either fresh or successfully validated as
          defined below.

       The set of request options that is used for matching the cache entry
       is also collectively referred to as the "Cache-Key".  For URI schemes
       other than coap and coaps, matching of those options that constitute
       the request URI may be performed under rules specific to the URI
       scheme.

    Shelby, et al.               Standards Track                   [Page 42]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    5.6.1.  Freshness Model

       When a response is "fresh" in the cache, it can be used to satisfy
       subsequent requests without contacting the origin server, thereby
       improving efficiency.

       The mechanism for determining freshness is for an origin server to
       provide an explicit expiration time in the future, using the Max-Age
       Option (see Section 5.10.5).  The Max-Age Option indicates that the
       response is to be considered not fresh after its age is greater than
       the specified number of seconds.

       The Max-Age Option defaults to a value of 60.  Thus, if it is not
       present in a cacheable response, then the response is considered not
       fresh after its age is greater than 60 seconds.  If an origin server
       wishes to prevent caching, it MUST explicitly include a Max-Age
       Option with a value of zero seconds.

       If a client has a fresh stored response and makes a new request
       matching the request for that stored response, the new response
       invalidates the old response.

    5.6.2.  Validation Model

       When an endpoint has one or more stored responses for a GET request,
       but cannot use any of them (e.g., because they are not fresh), it can
       use the ETag Option (Section 5.10.6) in the GET request to give the
       origin server an opportunity both to select a stored response to be
       used, and to update its freshness.  This process is known as
       "validating" or "revalidating" the stored response.

       When sending such a request, the endpoint SHOULD add an ETag Option
       specifying the entity-tag of each stored response that is applicable.

       A 2.03 (Valid) response indicates the stored response identified by
       the entity-tag given in the response's ETag Option can be reused
       after updating it as described in Section 5.9.1.3.

       Any other Response Code indicates that none of the stored responses
       nominated in the request is suitable.  Instead, the response SHOULD
       be used to satisfy the request and MAY replace the stored response.

    Shelby, et al.               Standards Track                   [Page 43]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    5.7.  Proxying

       A proxy is a CoAP endpoint that can be tasked by CoAP clients to
       perform requests on their behalf.  This may be useful, for example,
       when the request could otherwise not be made, or to service the
       response from a cache in order to reduce response time and network
       bandwidth or energy consumption.

       In an overall architecture for a Constrained RESTful Environment,
       proxies can serve quite different purposes.  Proxies can be
       explicitly selected by clients, a role that we term "forward-proxy".
       Proxies can also be inserted to stand in for origin servers, a role
       that we term "reverse-proxy".  Orthogonal to this distinction, a
       proxy can map from a CoAP request to a CoAP request (CoAP-to-CoAP
       proxy) or translate from or to a different protocol ("cross-proxy").
       Full definitions of these terms are provided in Section 1.2.

       Notes:  The terminology in this specification has been selected to be
          culturally compatible with the terminology used in the wider web
          application environments, without necessarily matching it in every
          detail (which may not even be relevant to Constrained RESTful
          Environments).  Not too much semantics should be ascribed to the
          components of the terms (such as "forward", "reverse", or
          "cross").

          HTTP proxies, besides acting as HTTP proxies, often offer a
          transport-protocol proxying function ("CONNECT") to enable end-to-
          end transport layer security through the proxy.  No such function
          is defined for CoAP-to-CoAP proxies in this specification, as
          forwarding of UDP packets is unlikely to be of much value in
          Constrained RESTful Environments.  See also Section 10.2.7 for the
          cross-proxy case.

       When a client uses a proxy to make a request that will use a secure
       URI scheme (e.g., "coaps" or "https"), the request towards the proxy
       SHOULD be sent using DTLS except where equivalent lower-layer
       security is used for the leg between the client and the proxy.

    5.7.1.  Proxy Operation

       A proxy generally needs a way to determine potential request
       parameters for a request it places to a destination, based on the
       request it received from its client.  This way is fully specified for
       a forward-proxy but may depend on the specific configuration for a
       reverse-proxy.  In particular, the client of a reverse-proxy
       generally does not indicate a locator for the destination,

    Shelby, et al.               Standards Track                   [Page 44]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       necessitating some form of namespace translation in the reverse-
       proxy.  However, some aspects of the operation of proxies are common
       to all its forms.

       If a proxy does not employ a cache, then it simply forwards the
       translated request to the determined destination.  Otherwise, if it
       does employ a cache but does not have a stored response that matches
       the translated request and is considered fresh, then it needs to
       refresh its cache according to Section 5.6.  For options in the
       request that the proxy recognizes, it knows whether the option is
       intended to act as part of the key used in looking up the cached
       value or not.  For example, since requests for different Uri-Path
       values address different resources, Uri-Path values are always part
       of the Cache-Key, while, e.g., Token values are never part of the
       Cache-Key.  For options that the proxy does not recognize but that
       are marked Safe-to-Forward in the option number, the option also
       indicates whether it is to be included in the Cache-Key (NoCacheKey
       is not all set) or not (NoCacheKey is all set).  (Options that are
       unrecognized and marked Unsafe lead to 4.02 Bad Option.)

       If the request to the destination times out, then a 5.04 (Gateway
       Timeout) response MUST be returned.  If the request to the
       destination returns a response that cannot be processed by the proxy
       (e.g, due to unrecognized critical options or message format errors),
       then a 5.02 (Bad Gateway) response MUST be returned.  Otherwise, the
       proxy returns the response to the client.

       If a response is generated out of a cache, the generated (or implied)
       Max-Age Option MUST NOT extend the max-age originally set by the
       server, considering the time the resource representation spent in the
       cache.  For example, the Max-Age Option could be adjusted by the
       proxy for each response using the formula:

          proxy-max-age = original-max-age - cache-age

       For example, if a request is made to a proxied resource that was
       refreshed 20 seconds ago and had an original Max-Age of 60 seconds,
       then that resource's proxied max-age is now 40 seconds.  Considering
       potential network delays on the way from the origin server, a proxy
       should be conservative in the max-age values offered.

       All options present in a proxy request MUST be processed at the
       proxy.  Unsafe options in a request that are not recognized by the
       proxy MUST lead to a 4.02 (Bad Option) response being returned by the
       proxy.  A CoAP-to-CoAP proxy MUST forward to the origin server all
       Safe-to-Forward options that it does not recognize.  Similarly,

    Shelby, et al.               Standards Track                   [Page 45]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       Unsafe options in a response that are not recognized by the CoAP-to-
       CoAP proxy server MUST lead to a 5.02 (Bad Gateway) response.  Again,
       Safe-to-Forward options that are not recognized MUST be forwarded.

       Additional considerations for cross-protocol proxying between CoAP
       and HTTP are discussed in Section 10.

    5.7.2.  Forward-Proxies

       CoAP distinguishes between requests made (as if) to an origin server
       and requests made through a forward-proxy.  CoAP requests to a
       forward-proxy are made as normal Confirmable or Non-confirmable
       requests to the forward-proxy endpoint, but they specify the request
       URI in a different way: The request URI in a proxy request is
       specified as a string in the Proxy-Uri Option (see Section 5.10.2),
       while the request URI in a request to an origin server is split into
       the Uri-Host, Uri-Port, Uri-Path, and Uri-Query Options (see
       Section 5.10.1).  Alternatively, the URI in a proxy request can be
       assembled from a Proxy-Scheme option and the split options mentioned.

       When a proxy request is made to an endpoint and the endpoint is
       unwilling or unable to act as proxy for the request URI, it MUST
       return a 5.05 (Proxying Not Supported) response.  If the authority
       (host and port) is recognized as identifying the proxy endpoint
       itself (see Section 5.10.2), then the request MUST be treated as a
       local (non-proxied) request.

       Unless a proxy is configured to forward the proxy request to another
       proxy, it MUST translate the request as follows: the scheme of the
       request URI defines the outgoing protocol and its details (e.g., CoAP
       is used over UDP for the "coap" scheme and over DTLS for the "coaps"
       scheme.)  For a CoAP-to-CoAP proxy, the origin server's IP address
       and port are determined by the authority component of the request
       URI, and the request URI is decoded and split into the Uri-Host, Uri-
       Port, Uri-Path and Uri-Query Options.  This consumes the Proxy-Uri or
       Proxy-Scheme option, which is therefore not forwarded to the origin
       server.

    5.7.3.  Reverse-Proxies

       Reverse-proxies do not make use of the Proxy-Uri or Proxy-Scheme
       options but need to determine the destination (next hop) of a request
       from information in the request and information in their
       configuration.  For example, a reverse-proxy might offer various
       resources as if they were its own resources, after having learned of
       their existence through resource discovery.  The reverse-proxy is
       free to build a namespace for the URIs that identify these resources.
       A reverse-proxy may also build a namespace that gives the client more

    Shelby, et al.               Standards Track                   [Page 46]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       control over where the request goes, e.g., by embedding host
       identifiers and port numbers into the URI path of the resources
       offered.

       In processing the response, a reverse-proxy has to be careful that
       ETag option values from different sources are not mixed up on one
       resource offered to its clients.  In many cases, the ETag can be
       forwarded unchanged.  If the mapping from a resource offered by the
       reverse-proxy to resources offered by its various origin servers is
       not unique, the reverse-proxy may need to generate a new ETag, making
       sure the semantics of this option are properly preserved.

    5.8.  Method Definitions

       In this section, each method is defined along with its behavior.  A
       request with an unrecognized or unsupported Method Code MUST generate
       a 4.05 (Method Not Allowed) piggybacked response.

    5.8.1.  GET

       The GET method retrieves a representation for the information that
       currently corresponds to the resource identified by the request URI.
       If the request includes an Accept Option, that indicates the
       preferred content-format of a response.  If the request includes an
       ETag Option, the GET method requests that ETag be validated and that
       the representation be transferred only if validation failed.  Upon
       success, a 2.05 (Content) or 2.03 (Valid) Response Code SHOULD be
       present in the response.

       The GET method is safe and idempotent.

    5.8.2.  POST

       The POST method requests that the representation enclosed in the
       request be processed.  The actual function performed by the POST
       method is determined by the origin server and dependent on the target
       resource.  It usually results in a new resource being created or the
       target resource being updated.

       If a resource has been created on the server, the response returned
       by the server SHOULD have a 2.01 (Created) Response Code and SHOULD
       include the URI of the new resource in a sequence of one or more
       Location-Path and/or Location-Query Options (Section 5.10.7).  If the
       POST succeeds but does not result in a new resource being created on
       the server, the response SHOULD have a 2.04 (Changed) Response Code.
       If the POST succeeds and results in the target resource being
       deleted, the response SHOULD have a 2.02 (Deleted) Response Code.
       POST is neither safe nor idempotent.

    Shelby, et al.               Standards Track                   [Page 47]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    5.8.3.  PUT

       The PUT method requests that the resource identified by the request
       URI be updated or created with the enclosed representation.  The
       representation format is specified by the media type and content
       coding given in the Content-Format Option, if provided.

       If a resource exists at the request URI, the enclosed representation
       SHOULD be considered a modified version of that resource, and a 2.04
       (Changed) Response Code SHOULD be returned.  If no resource exists,
       then the server MAY create a new resource with that URI, resulting in
       a 2.01 (Created) Response Code.  If the resource could not be created
       or modified, then an appropriate error Response Code SHOULD be sent.

       Further restrictions to a PUT can be made by including the If-Match
       (see Section 5.10.8.1) or If-None-Match (see Section 5.10.8.2)
       options in the request.

       PUT is not safe but is idempotent.

    5.8.4.  DELETE

       The DELETE method requests that the resource identified by the
       request URI be deleted.  A 2.02 (Deleted) Response Code SHOULD be
       used on success or in case the resource did not exist before the
       request.

       DELETE is not safe but is idempotent.

    5.9.  Response Code Definitions

       Each Response Code is described below, including any options required
       in the response.  Where appropriate, some of the codes will be
       specified in regards to related Response Codes in HTTP [RFC2616];
       this does not mean that any such relationship modifies the HTTP
       mapping specified in Section 10.

    5.9.1.  Success 2.xx

       This class of Response Code indicates that the clients request was
       successfully received, understood, and accepted.

    5.9.1.1.  2.01 Created

       Like HTTP 201 "Created", but only used in response to POST and PUT
       requests.  The payload returned with the response, if any, is a
       representation of the action result.

    Shelby, et al.               Standards Track                   [Page 48]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       If the response includes one or more Location-Path and/or Location-
       Query Options, the values of these options specify the location at
       which the resource was created.  Otherwise, the resource was created
       at the request URI.  A cache receiving this response MUST mark any
       stored response for the created resource as not fresh.

       This response is not cacheable.

    5.9.1.2.  2.02 Deleted

       This Response Code is like HTTP 204 "No Content" but only used in
       response to requests that cause the resource to cease being
       available, such as DELETE and, in certain circumstances, POST.  The
       payload returned with the response, if any, is a representation of
       the action result.

       This response is not cacheable.  However, a cache MUST mark any
       stored response for the deleted resource as not fresh.

    5.9.1.3.  2.03 Valid

       This Response Code is related to HTTP 304 "Not Modified" but only
       used to indicate that the response identified by the entity-tag
       identified by the included ETag Option is valid.  Accordingly, the
       response MUST include an ETag Option and MUST NOT include a payload.

       When a cache that recognizes and processes the ETag response option
       receives a 2.03 (Valid) response, it MUST update the stored response
       with the value of the Max-Age Option included in the response
       (explicitly, or implicitly as a default value; see also
       Section 5.6.2).  For each type of Safe-to-Forward option present in
       the response, the (possibly empty) set of options of this type that
       are present in the stored response MUST be replaced with the set of
       options of this type in the response received.  (Unsafe options may
       trigger similar option-specific processing as defined by the option.)

    5.9.1.4.  2.04 Changed

       This Response Code is like HTTP 204 "No Content" but only used in
       response to POST and PUT requests.  The payload returned with the
       response, if any, is a representation of the action result.

       This response is not cacheable.  However, a cache MUST mark any
       stored response for the changed resource as not fresh.

    Shelby, et al.               Standards Track                   [Page 49]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    5.9.1.5.  2.05 Content

       This Response Code is like HTTP 200 "OK" but only used in response to
       GET requests.

       The payload returned with the response is a representation of the
       target resource.

       This response is cacheable: Caches can use the Max-Age Option to
       determine freshness (see Section 5.6.1) and (if present) the ETag
       Option for validation (see Section 5.6.2).

    5.9.2.  Client Error 4.xx

       This class of Response Code is intended for cases in which the client
       seems to have erred.  These Response Codes are applicable to any
       request method.

       The server SHOULD include a diagnostic payload under the conditions
       detailed in Section 5.5.2.

       Responses of this class are cacheable: Caches can use the Max-Age
       Option to determine freshness (see Section 5.6.1).  They cannot be
       validated.

    5.9.2.1.  4.00 Bad Request

       This Response Code is Like HTTP 400 "Bad Request".

    5.9.2.2.  4.01 Unauthorized

       The client is not authorized to perform the requested action.  The
       client SHOULD NOT repeat the request without first improving its
       authentication status to the server.  Which specific mechanism can be
       used for this is outside this document's scope; see also Section 9.

    5.9.2.3.  4.02 Bad Option

       The request could not be understood by the server due to one or more
       unrecognized or malformed options.  The client SHOULD NOT repeat the
       request without modification.

    5.9.2.4.  4.03 Forbidden

       This Response Code is like HTTP 403 "Forbidden".

    Shelby, et al.               Standards Track                   [Page 50]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    5.9.2.5.  4.04 Not Found

       This Response Code is like HTTP 404 "Not Found".

    5.9.2.6.  4.05 Method Not Allowed

       This Response Code is like HTTP 405 "Method Not Allowed" but with no
       parallel to the "Allow" header field.

    5.9.2.7.  4.06 Not Acceptable

       This Response Code is like HTTP 406 "Not Acceptable", but with no
       response entity.

    5.9.2.8.  4.12 Precondition Failed

       This Response Code is like HTTP 412 "Precondition Failed".

    5.9.2.9.  4.13 Request Entity Too Large

       This Response Code is like HTTP 413 "Request Entity Too Large".

       The response SHOULD include a Size1 Option (Section 5.10.9) to
       indicate the maximum size of request entity the server is able and
       willing to handle, unless the server is not in a position to make
       this information available.

    5.9.2.10.  4.15 Unsupported Content-Format

       This Response Code is like HTTP 415 "Unsupported Media Type".

    5.9.3.  Server Error 5.xx

       This class of Response Code indicates cases in which the server is
       aware that it has erred or is incapable of performing the request.
       These Response Codes are applicable to any request method.

       The server SHOULD include a diagnostic payload under the conditions
       detailed in Section 5.5.2.

       Responses of this class are cacheable: Caches can use the Max-Age
       Option to determine freshness (see Section 5.6.1).  They cannot be
       validated.

    5.9.3.1.  5.00 Internal Server Error

       This Response Code is like HTTP 500 "Internal Server Error".

    Shelby, et al.               Standards Track                   [Page 51]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    5.9.3.2.  5.01 Not Implemented

       This Response Code is like HTTP 501 "Not Implemented".

    5.9.3.3.  5.02 Bad Gateway

       This Response Code is like HTTP 502 "Bad Gateway".

    5.9.3.4.  5.03 Service Unavailable

       This Response Code is like HTTP 503 "Service Unavailable" but uses
       the Max-Age Option in place of the "Retry-After" header field to
       indicate the number of seconds after which to retry.

    5.9.3.5.  5.04 Gateway Timeout

       This Response Code is like HTTP 504 "Gateway Timeout".

    5.9.3.6.  5.05 Proxying Not Supported

       The server is unable or unwilling to act as a forward-proxy for the
       URI specified in the Proxy-Uri Option or using Proxy-Scheme (see
       Section 5.10.2).

    5.10.  Option Definitions

       The individual CoAP options are summarized in Table 4 and explained
       in the subsections of this section.

       In this table, the C, U, and N columns indicate the properties
       Critical, UnSafe, and NoCacheKey, respectively.  Since NoCacheKey
       only has a meaning for options that are Safe-to-Forward (not marked
       Unsafe), the column is filled with a dash for UnSafe options.

    Shelby, et al.               Standards Track                   [Page 52]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       +-----+---+---+---+---+----------------+--------+--------+----------+
       | No. | C | U | N | R | Name           | Format | Length | Default  |
       +-----+---+---+---+---+----------------+--------+--------+----------+
       |   1 | x |   |   | x | If-Match       | opaque | 0-8    | (none)   |
       |   3 | x | x | - |   | Uri-Host       | string | 1-255  | (see     |
       |     |   |   |   |   |                |        |        | below)   |
       |   4 |   |   |   | x | ETag           | opaque | 1-8    | (none)   |
       |   5 | x |   |   |   | If-None-Match  | empty  | 0      | (none)   |
       |   7 | x | x | - |   | Uri-Port       | uint   | 0-2    | (see     |
       |     |   |   |   |   |                |        |        | below)   |
       |   8 |   |   |   | x | Location-Path  | string | 0-255  | (none)   |
       |  11 | x | x | - | x | Uri-Path       | string | 0-255  | (none)   |
       |  12 |   |   |   |   | Content-Format | uint   | 0-2    | (none)   |
       |  14 |   | x | - |   | Max-Age        | uint   | 0-4    | 60       |
       |  15 | x | x | - | x | Uri-Query      | string | 0-255  | (none)   |
       |  17 | x |   |   |   | Accept         | uint   | 0-2    | (none)   |
       |  20 |   |   |   | x | Location-Query | string | 0-255  | (none)   |
       |  35 | x | x | - |   | Proxy-Uri      | string | 1-1034 | (none)   |
       |  39 | x | x | - |   | Proxy-Scheme   | string | 1-255  | (none)   |
       |  60 |   |   | x |   | Size1          | uint   | 0-4    | (none)   |
       +-----+---+---+---+---+----------------+--------+--------+----------+

                 C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable

                                 Table 4: Options

    5.10.1.  Uri-Host, Uri-Port, Uri-Path, and Uri-Query

       The Uri-Host, Uri-Port, Uri-Path, and Uri-Query Options are used to
       specify the target resource of a request to a CoAP origin server.
       The options encode the different components of the request URI in a
       way that no percent-encoding is visible in the option values and that
       the full URI can be reconstructed at any involved endpoint.  The
       syntax of CoAP URIs is defined in Section 6.

       The steps for parsing URIs into options is defined in Section 6.4.
       These steps result in zero or more Uri-Host, Uri-Port, Uri-Path, and
       Uri-Query Options being included in a request, where each option
       holds the following values:

       o  the Uri-Host Option specifies the Internet host of the resource
          being requested,

       o  the Uri-Port Option specifies the transport-layer port number of
          the resource,

       o  each Uri-Path Option specifies one segment of the absolute path to
          the resource, and

    Shelby, et al.               Standards Track                   [Page 53]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       o  each Uri-Query Option specifies one argument parameterizing the
          resource.

       Note: Fragments ([RFC3986], Section 3.5) are not part of the request
       URI and thus will not be transmitted in a CoAP request.

       The default value of the Uri-Host Option is the IP literal
       representing the destination IP address of the request message.
       Likewise, the default value of the Uri-Port Option is the destination
       UDP port.  The default values for the Uri-Host and Uri-Port Options
       are sufficient for requests to most servers.  Explicit Uri-Host and
       Uri-Port Options are typically used when an endpoint hosts multiple
       virtual servers.

       The Uri-Path and Uri-Query Option can contain any character sequence.
       No percent-encoding is performed.  The value of a Uri-Path Option
       MUST NOT be "." or ".." (as the request URI must be resolved before
       parsing it into options).

       The steps for constructing the request URI from the options are
       defined in Section 6.5.  Note that an implementation does not
       necessarily have to construct the URI; it can simply look up the
       target resource by examining the individual options.

       Examples can be found in Appendix B.

    5.10.2.  Proxy-Uri and Proxy-Scheme

       The Proxy-Uri Option is used to make a request to a forward-proxy
       (see Section 5.7).  The forward-proxy is requested to forward the
       request or service it from a valid cache and return the response.

       The option value is an absolute-URI ([RFC3986], Section 4.3).

       Note that the forward-proxy MAY forward the request on to another
       proxy or directly to the server specified by the absolute-URI.  In
       order to avoid request loops, a proxy MUST be able to recognize all
       of its server names, including any aliases, local variations, and the
       numeric IP addresses.

       An endpoint receiving a request with a Proxy-Uri Option that is
       unable or unwilling to act as a forward-proxy for the request MUST
       cause the return of a 5.05 (Proxying Not Supported) response.

       The Proxy-Uri Option MUST take precedence over any of the Uri-Host,
       Uri-Port, Uri-Path or Uri-Query options (each of which MUST NOT be
       included in a request containing the Proxy-Uri Option).

    Shelby, et al.               Standards Track                   [Page 54]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       As a special case to simplify many proxy clients, the absolute-URI
       can be constructed from the Uri-* options.  When a Proxy-Scheme
       Option is present, the absolute-URI is constructed as follows: a CoAP
       URI is constructed from the Uri-* options as defined in Section 6.5.
       In the resulting URI, the initial scheme up to, but not including,
       the following colon is then replaced by the content of the Proxy-
       Scheme Option.  Note that this case is only applicable if the
       components of the desired URI other than the scheme component
       actually can be expressed using Uri-* options; for example, to
       represent a URI with a userinfo component in the authority, only
       Proxy-Uri can be used.

    5.10.3.  Content-Format

       The Content-Format Option indicates the representation format of the
       message payload.  The representation format is given as a numeric
       Content-Format identifier that is defined in the "CoAP Content-
       Formats" registry (Section 12.3).  In the absence of the option, no
       default value is assumed, i.e., the representation format of any
       representation message payload is indeterminate (Section 5.5).

    5.10.4.  Accept

       The CoAP Accept option can be used to indicate which Content-Format
       is acceptable to the client.  The representation format is given as a
       numeric Content-Format identifier that is defined in the "CoAP
       Content-Formats" registry (Section 12.3).  If no Accept option is
       given, the client does not express a preference (thus no default
       value is assumed).  The client prefers the representation returned by
       the server to be in the Content-Format indicated.  The server returns
       the preferred Content-Format if available.  If the preferred Content-
       Format cannot be returned, then a 4.06 "Not Acceptable" MUST be sent
       as a response, unless another error code takes precedence for this
       response.

    5.10.5.  Max-Age

       The Max-Age Option indicates the maximum time a response may be
       cached before it is considered not fresh (see Section 5.6.1).

       The option value is an integer number of seconds between 0 and
       2**32-1 inclusive (about 136.1 years).  A default value of 60 seconds
       is assumed in the absence of the option in a response.

       The value is intended to be current at the time of transmission.
       Servers that provide resources with strict tolerances on the value of
       Max-Age SHOULD update the value before each retransmission.  (See
       also Section 5.7.1.)

    Shelby, et al.               Standards Track                   [Page 55]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    5.10.6.  ETag

       An entity-tag is intended for use as a resource-local identifier for
       differentiating between representations of the same resource that
       vary over time.  It is generated by the server providing the
       resource, which may generate it in any number of ways including a
       version, checksum, hash, or time.  An endpoint receiving an entity-
       tag MUST treat it as opaque and make no assumptions about its content
       or structure.  (Endpoints that generate an entity-tag are encouraged
       to use the most compact representation possible, in particular in
       regards to clients and intermediaries that may want to store multiple
       ETag values.)

    5.10.6.1.  ETag as a Response Option

       The ETag Option in a response provides the current value (i.e., after
       the request was processed) of the entity-tag for the "tagged
       representation".  If no Location-* options are present, the tagged
       representation is the selected representation (Section 5.5.3) of the
       target resource.  If one or more Location-* options are present and
       thus a location URI is indicated (Section 5.10.7), the tagged
       representation is the representation that would be retrieved by a GET
       request to the location URI.

       An ETag response option can be included with any response for which
       there is a tagged representation (e.g., it would not be meaningful in
       a 4.04 or 4.00 response).  The ETag Option MUST NOT occur more than
       once in a response.

       There is no default value for the ETag Option; if it is not present
       in a response, the server makes no statement about the entity-tag for
       the tagged representation.

    5.10.6.2.  ETag as a Request Option

       In a GET request, an endpoint that has one or more representations
       previously obtained from the resource, and has obtained ETag response
       options with these, can specify an instance of the ETag Option for
       one or more of these stored responses.

       A server can issue a 2.03 Valid response (Section 5.9.1.3) in place
       of a 2.05 Content response if one of the ETags given is the entity-
       tag for the current representation, i.e., is valid; the 2.03 Valid
       response then echoes this specific ETag in a response option.

       In effect, a client can determine if any of the stored
       representations is current (see Section 5.6.2) without needing to
       transfer them again.

    Shelby, et al.               Standards Track                   [Page 56]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       The ETag Option MAY occur zero, one, or multiple times in a request.

    5.10.7.  Location-Path and Location-Query

       The Location-Path and Location-Query Options together indicate a
       relative URI that consists either of an absolute path, a query
       string, or both.  A combination of these options is included in a
       2.01 (Created) response to indicate the location of the resource
       created as the result of a POST request (see Section 5.8.2).  The
       location is resolved relative to the request URI.

       If a response with one or more Location-Path and/or Location-Query
       Options passes through a cache that interprets these options and the
       implied URI identifies one or more currently stored responses, those
       entries MUST be marked as not fresh.

       Each Location-Path Option specifies one segment of the absolute path
       to the resource, and each Location-Query Option specifies one
       argument parameterizing the resource.  The Location-Path and
       Location-Query Option can contain any character sequence.  No
       percent-encoding is performed.  The value of a Location-Path Option
       MUST NOT be "." or "..".

       The steps for constructing the location URI from the options are
       analogous to Section 6.5, except that the first five steps are
       skipped and the result is a relative URI-reference, which is then
       interpreted relative to the request URI.  Note that the relative URI-
       reference constructed this way always includes an absolute path
       (e.g., leaving out Location-Path but supplying Location-Query means
       the path component in the URI is "/").

       The options that are used to compute the relative URI-reference are
       collectively called Location-* options.  Beyond Location-Path and
       Location-Query, more Location-* options may be defined in the future
       and have been reserved option numbers 128, 132, 136, and 140.  If any
       of these reserved option numbers occurs in addition to Location-Path
       and/or Location-Query and are not supported, then a 4.02 (Bad Option)
       error MUST be returned.

    5.10.8.  Conditional Request Options

       Conditional request options enable a client to ask the server to
       perform the request only if certain conditions specified by the
       option are fulfilled.

    Shelby, et al.               Standards Track                   [Page 57]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       For each of these options, if the condition given is not fulfilled,
       then the server MUST NOT perform the requested method.  Instead, the
       server MUST respond with the 4.12 (Precondition Failed) Response
       Code.

       If the condition is fulfilled, the server performs the request method
       as if the conditional request options were not present.

       If the request would, without the conditional request options, result
       in anything other than a 2.xx or 4.12 Response Code, then any
       conditional request options MAY be ignored.

    5.10.8.1.  If-Match

       The If-Match Option MAY be used to make a request conditional on the
       current existence or value of an ETag for one or more representations
       of the target resource.  If-Match is generally useful for resource
       update requests, such as PUT requests, as a means for protecting
       against accidental overwrites when multiple clients are acting in
       parallel on the same resource (i.e., the "lost update" problem).

       The value of an If-Match option is either an ETag or the empty
       string.  An If-Match option with an ETag matches a representation
       with that exact ETag.  An If-Match option with an empty value matches
       any existing representation (i.e., it places the precondition on the
       existence of any current representation for the target resource).

       The If-Match Option can occur multiple times.  If any of the options
       match, then the condition is fulfilled.

       If there is one or more If-Match Options, but none of the options
       match, then the condition is not fulfilled.

    5.10.8.2.  If-None-Match

       The If-None-Match Option MAY be used to make a request conditional on
       the nonexistence of the target resource.  If-None-Match is useful for
       resource creation requests, such as PUT requests, as a means for
       protecting against accidental overwrites when multiple clients are
       acting in parallel on the same resource.  The If-None-Match Option
       carries no value.

       If the target resource does exist, then the condition is not
       fulfilled.

       (It is not very useful to combine If-Match and If-None-Match options
       in one request, because the condition will then never be fulfilled.)

    Shelby, et al.               Standards Track                   [Page 58]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    5.10.9.  Size1 Option

       The Size1 option provides size information about the resource
       representation in a request.  The option value is an integer number
       of bytes.  Its main use is with block-wise transfers [BLOCK].  In the
       present specification, it is used in 4.13 responses (Section 5.9.2.9)
       to indicate the maximum size of request entity that the server is
       able and willing to handle.

    6.  CoAP URIs

       CoAP uses the "coap" and "coaps" URI schemes for identifying CoAP
       resources and providing a means of locating the resource.  Resources
       are organized hierarchically and governed by a potential CoAP origin
       server listening for CoAP requests ("coap") or DTLS-secured CoAP
       requests ("coaps") on a given UDP port.  The CoAP server is
       identified via the generic syntax's authority component, which
       includes a host component and optional UDP port number.  The
       remainder of the URI is considered to be identifying a resource that
       can be operated on by the methods defined by the CoAP protocol.  The
       "coap" and "coaps" URI schemes can thus be compared to the "http" and
       "https" URI schemes, respectively.

       The syntax of the "coap" and "coaps" URI schemes is specified in this
       section in Augmented Backus-Naur Form (ABNF) [RFC5234].  The
       definitions of "host", "port", "path-abempty", "query", "segment",
       "IP-literal", "IPv4address", and "reg-name" are adopted from
       [RFC3986].

       Implementation Note:  Unfortunately, over time, the URI format has
          acquired significant complexity.  Implementers are encouraged to
          examine [RFC3986] closely.  For example, the ABNF for IPv6
          addresses is more complicated than maybe expected.  Also,
          implementers should take care to perform the processing of
          percent-decoding or percent-encoding exactly once on the way from
          a URI to its decoded components or back.  Percent-encoding is
          crucial for data transparency but may lead to unusual results such
          as a slash character in a path component.

    6.1.  coap URI Scheme

       coap-URI = "coap:" "//" host [ ":" port ] path-abempty [ "?" query ]

       If the host component is provided as an IP-literal or IPv4address,
       then the CoAP server can be reached at that IP address.  If host is a
       registered name, then that name is considered an indirect identifier
       and the endpoint might use a name resolution service, such as DNS, to
       find the address of that host.  The host MUST NOT be empty; if a URI

    Shelby, et al.               Standards Track                   [Page 59]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       is received with a missing authority or an empty host, then it MUST
       be considered invalid.  The port subcomponent indicates the UDP port
       at which the CoAP server is located.  If it is empty or not given,
       then the default port 5683 is assumed.

       The path identifies a resource within the scope of the host and port.
       It consists of a sequence of path segments separated by a slash
       character (U+002F SOLIDUS "/").

       The query serves to further parameterize the resource.  It consists
       of a sequence of arguments separated by an ampersand character
       (U+0026 AMPERSAND "&").  An argument is often in the form of a
       "key=value" pair.

       The "coap" URI scheme supports the path prefix "/.well-known/"
       defined by [RFC5785] for "well-known locations" in the namespace of a
       host.  This enables discovery of policy or other information about a
       host ("site-wide metadata"), such as hosted resources (see
       Section 7).

       Application designers are encouraged to make use of short but
       descriptive URIs.  As the environments that CoAP is used in are
       usually constrained for bandwidth and energy, the trade-off between
       these two qualities should lean towards the shortness, without
       ignoring descriptiveness.

    6.2.  coaps URI Scheme

       coaps-URI = "coaps:" "//" host [ ":" port ] path-abempty
                   [ "?" query ]

       All of the requirements listed above for the "coap" scheme are also
       requirements for the "coaps" scheme, except that a default UDP port
       of 5684 is assumed if the port subcomponent is empty or not given,
       and the UDP datagrams MUST be secured through the use of DTLS as
       described in Section 9.1.

       Considerations for caching of responses to "coaps" identified
       requests are discussed in Section 11.2.

       Resources made available via the "coaps" scheme have no shared
       identity with the "coap" scheme even if their resource identifiers
       indicate the same authority (the same host listening to the same UDP
       port).  They are distinct namespaces and are considered to be
       distinct origin servers.

    Shelby, et al.               Standards Track                   [Page 60]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    6.3.  Normalization and Comparison Rules

       Since the "coap" and "coaps" schemes conform to the URI generic
       syntax, such URIs are normalized and compared according to the
       algorithm defined in [RFC3986], Section 6, using the defaults
       described above for each scheme.

       If the port is equal to the default port for a scheme, the normal
       form is to elide the port subcomponent.  Likewise, an empty path
       component is equivalent to an absolute path of "/", so the normal
       form is to provide a path of "/" instead.  The scheme and host are
       case insensitive and normally provided in lowercase; IP-literals are
       in recommended form [RFC5952]; all other components are compared in a
       case-sensitive manner.  Characters other than those in the "reserved"
       set are equivalent to their percent-encoded bytes (see [RFC3986],
       Section 2.1): the normal form is to not encode them.

       For example, the following three URIs are equivalent and cause the
       same options and option values to appear in the CoAP messages:

       coap://example.com:5683/~sensors/temp.xml
       coap://EXAMPLE.com/%7Esensors/temp.xml
       coap://EXAMPLE.com:/%7esensors/temp.xml

    6.4.  Decomposing URIs into Options

       The steps to parse a request's options from a string |url| are as
       follows.  These steps either result in zero or more of the Uri-Host,
       Uri-Port, Uri-Path, and Uri-Query Options being included in the
       request or they fail.

       1.  If the |url| string is not an absolute URI ([RFC3986]), then fail
           this algorithm.

       2.  Resolve the |url| string using the process of reference
           resolution defined by [RFC3986].  At this stage, the URL is in
           ASCII encoding [RFC0020], even though the decoded components will
           be interpreted in UTF-8 [RFC3629] after steps 5, 8, and 9.

           NOTE: It doesn't matter what it is resolved relative to, since we
           already know it is an absolute URL at this point.

       3.  If |url| does not have a <scheme> component whose value, when
           converted to ASCII lowercase, is "coap" or "coaps", then fail
           this algorithm.

       4.  If |url| has a <fragment> component, then fail this algorithm.

    Shelby, et al.               Standards Track                   [Page 61]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       5.  If the <host> component of |url| does not represent the request's
           destination IP address as an IP-literal or IPv4address, include a
           Uri-Host Option and let that option's value be the value of the
           <host> component of |url|, converted to ASCII lowercase, and then
           convert all percent-encodings ("%" followed by two hexadecimal
           digits) to the corresponding characters.

           NOTE: In the usual case where the request's destination IP
           address is derived from the host part, this ensures that a Uri-
           Host Option is only used for a <host> component of the form reg-
           name.

       6.  If |url| has a <port> component, then let |port| be that
           component's value interpreted as a decimal integer; otherwise,
           let |port| be the default port for the scheme.

       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|.

       8.  If the value of the <path> component of |url| is empty or
           consists of a single slash character (U+002F SOLIDUS "/"), then
           move to the next step.

           Otherwise, for each segment in the <path> component, include a
           Uri-Path Option and let that option's value be the segment (not
           including the delimiting slash characters) after converting each
           percent-encoding ("%" followed by two hexadecimal digits) to the
           corresponding byte.

       9.  If |url| has a <query> component, then, for each argument in the
           <query> component, include a Uri-Query Option and let that
           option's value be the argument (not including the question mark
           and the delimiting ampersand characters) after converting each
           percent-encoding to the corresponding byte.

       Note that these rules completely resolve any percent-encoding.

    6.5.  Composing URIs from Options

       The steps to construct a URI from a request's options are as follows.
       These steps either result in a URI or they fail.  In these steps,
       percent-encoding a character means replacing each of its
       (UTF-8-encoded) bytes by a "%" character followed by two hexadecimal
       digits representing the byte, where the digits A-F are in uppercase
       (as defined in Section 2.1 of [RFC3986]; to reduce variability, the
       hexadecimal notation for percent-encoding in CoAP URIs MUST use
       uppercase letters).  The definitions of "unreserved" and "sub-delims"
       are adopted from [RFC3986].

    Shelby, et al.               Standards Track                   [Page 62]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       1.   If the request is secured using DTLS, let |url| be the string
            "coaps://".  Otherwise, let |url| be the string "coap://".

       2.   If the request includes a Uri-Host Option, let |host| be that
            option's value, where any non-ASCII characters are replaced by
            their corresponding percent-encoding.  If |host| is not a valid
            reg-name or IP-literal or IPv4address, fail the algorithm.  If
            the request does not include a Uri-Host Option, let |host| be
            the IP-literal (making use of the conventions of [RFC5952]) or
            IPv4address representing the request's destination IP address.

       3.   Append |host| to |url|.

       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.

       5.   If |port| is not the default port for the scheme, then append a
            single U+003A COLON character (:) followed by the decimal
            representation of |port| to |url|.

       6.   Let |resource name| be the empty string.  For each Uri-Path
            Option in the request, append a single character U+002F SOLIDUS
            (/) followed by the option's value to |resource name|, after
            converting any character that is not either in the "unreserved"
            set, in the "sub-delims" set, a U+003A COLON (:) character, or a
            U+0040 COMMERCIAL AT (@) character to its percent-encoded form.

       7.   If |resource name| is the empty string, set it to a single
            character U+002F SOLIDUS (/).

       8.   For each Uri-Query Option in the request, append a single
            character U+003F QUESTION MARK (?) (first option) or U+0026
            AMPERSAND (&) (subsequent options) followed by the option's
            value to |resource name|, after converting any character that is
            not either in the "unreserved" set, in the "sub-delims" set
            (except U+0026 AMPERSAND (&)), a U+003A COLON (:), a U+0040
            COMMERCIAL AT (@), a U+002F SOLIDUS (/), or a U+003F QUESTION
            MARK (?) character to its percent-encoded form.

       9.   Append |resource name| to |url|.

       10.  Return |url|.

       Note that these steps have been designed to lead to a URI in normal
       form (see Section 6.3).

    Shelby, et al.               Standards Track                   [Page 63]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    7.  Discovery

    7.1.  Service Discovery

       As a part of discovering the services offered by a CoAP server, a
       client has to learn about the endpoint used by a server.

       A server is discovered by a client (knowing or) learning a URI that
       references a resource in the namespace of the server.  Alternatively,
       clients can use multicast CoAP (see Section 8) and the "All CoAP
       Nodes" multicast address to find CoAP servers.

       Unless the port subcomponent in a "coap" or "coaps" URI indicates the
       UDP port at which the CoAP server is located, the server is assumed
       to be reachable at the default port.

       The CoAP default port number 5683 MUST be supported by a server that
       offers resources for resource discovery (see Section 7.2 below) and
       SHOULD be supported for providing access to other resources.  The
       default port number 5684 for DTLS-secured CoAP MAY be supported by a
       server for resource discovery and for providing access to other
       resources.  In addition, other endpoints may be hosted at other
       ports, e.g., in the dynamic port space.

       Implementation Note:  When a CoAP server is hosted by a 6LoWPAN node,
          header compression efficiency is improved when it also supports a
          port number in the 61616-61631 compressed UDP port space defined
          in [RFC4944] and [RFC6282].  (Note that, as its UDP port differs
          from the default port, it is a different endpoint from the server
          at the default port.)

    7.2.  Resource Discovery

       The discovery of resources offered by a CoAP endpoint is extremely
       important in machine-to-machine applications where there are no
       humans in the loop and static interfaces result in fragility.  To
       maximize interoperability in a CoRE environment, a CoAP endpoint
       SHOULD support the CoRE Link Format of discoverable resources as
       described in [RFC6690], except where fully manual configuration is
       desired.  It is up to the server which resources are made
       discoverable (if any).

    7.2.1.  'ct' Attribute

       This section defines a new Web Linking [RFC5988] attribute for use
       with [RFC6690].  The Content-Format code "ct" attribute provides a
       hint about the Content-Formats this resource returns.  Note that this
       is only a hint, and it does not override the Content-Format Option of

    Shelby, et al.               Standards Track                   [Page 64]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       a CoAP response obtained by actually requesting the representation of
       the resource.  The value is in the CoAP identifier code format as a
       decimal ASCII integer and MUST be in the range of 0-65535 (16-bit
       unsigned integer).  For example, "application/xml" would be indicated
       as "ct=41".  If no Content-Format code attribute is present, then
       nothing about the type can be assumed.  The Content-Format code
       attribute MAY include a space-separated sequence of Content-Format
       codes, indicating that multiple content-formats are available.  The
       syntax of the attribute value is summarized in the production "ct-
       value" in Figure 12, where "cardinal", "SP", and "DQUOTE" are defined
       as in [RFC6690].

          ct-value =  cardinal
                   /  DQUOTE cardinal *( 1*SP cardinal ) DQUOTE

                                     Figure 12

    8.  Multicast CoAP

       CoAP supports making requests to an IP multicast group.  This is
       defined by a series of deltas to unicast CoAP.  A more general
       discussion of group communication with CoAP is in [GROUPCOMM].

       CoAP endpoints that offer services that they want other endpoints to
       be able to find using multicast service discovery join one or more of
       the appropriate all-CoAP-node multicast addresses (Section 12.8) and
       listen on the default CoAP port.  Note that an endpoint might receive
       multicast requests on other multicast addresses, including the all-
       nodes IPv6 address (or via broadcast on IPv4); an endpoint MUST
       therefore be prepared to receive such messages but MAY ignore them if
       multicast service discovery is not desired.

    8.1.  Messaging Layer

       A multicast request is characterized by being transported in a CoAP
       message that is addressed to an IP multicast address instead of a
       CoAP endpoint.  Such multicast requests MUST be Non-confirmable.

       A server SHOULD be aware that a request arrived via multicast, e.g.,
       by making use of modern APIs such as IPV6_RECVPKTINFO [RFC3542], if
       available.

       To avoid an implosion of error responses, when a server is aware that
       a request arrived via multicast, it MUST NOT return a Reset message
       in reply to a Non-confirmable message.  If it is not aware, it MAY
       return a Reset message in reply to a Non-confirmable message as
       usual.  Because such a Reset message will look identical to one for a

    Shelby, et al.               Standards Track                   [Page 65]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       unicast message from the sender, the sender MUST avoid using a
       Message ID that is also still active from this endpoint with any
       unicast endpoint that might receive the multicast message.

       At the time of writing, multicast messages can only be carried in UDP
       not in DTLS.  This means that the security modes defined for CoAP in
       this document are not applicable to multicast.

    8.2.  Request/Response Layer

       When a server is aware that a request arrived via multicast, the
       server MAY always ignore the request, in particular if it doesn't
       have anything useful to respond (e.g., if it only has an empty
       payload or an error response).  The decision for this may depend on
       the application.  (For example, in query filtering as described in
       [RFC6690], a server should not respond to a multicast request if the
       filter does not match.  More examples are in [GROUPCOMM].)

       If a server does decide to respond to a multicast request, it should
       not respond immediately.  Instead, it should pick a duration for the
       period of time during which it intends to respond.  For the purposes
       of this exposition, we call the length of this period the Leisure.
       The specific value of this Leisure may depend on the application or
       MAY be derived as described below.  The server SHOULD then pick a
       random point of time within the chosen leisure period to send back
       the unicast response to the multicast request.  If further responses
       need to be sent based on the same multicast address membership, a new
       leisure period starts at the earliest after the previous one
       finishes.

       To compute a value for Leisure, the server should have a group size
       estimate G, a target data transfer rate R (which both should be
       chosen conservatively), and an estimated response size S; a rough
       lower bound for Leisure can then be computed as

                              lb_Leisure = S * G / R

       For example, for a multicast request with link-local scope on a 2.4
       GHz IEEE 802.15.4 (6LoWPAN) network, G could be (relatively
       conservatively) set to 100, S to 100 bytes, and the target rate to 8
       kbit/s = 1 kB/s.  The resulting lower bound for the Leisure is 10
       seconds.

       If a CoAP endpoint does not have suitable data to compute a value for
       Leisure, it MAY resort to DEFAULT_LEISURE.

    Shelby, et al.               Standards Track                   [Page 66]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       When matching a response to a multicast request, only the token MUST
       match; the source endpoint of the response does not need to (and will
       not) be the same as the destination endpoint of the original request.

       For the purposes of interpreting the Location-* options and any links
       embedded in the representation, the request URI (i.e., the base URI
       relative to which the response is interpreted) is formed by replacing
       the multicast address in the Host component of the original request
       URI by the literal IP address of the endpoint actually responding.

    8.2.1.  Caching

       When a client makes a multicast request, it always makes a new
       request to the multicast group (since there may be new group members
       that joined meanwhile or ones that did not get the previous request).
       It MAY update a cache with the received responses.  Then, it uses
       both cached-still-fresh and new responses as the result of the
       request.

       A response received in reply to a GET request to a multicast group
       MAY be used to satisfy a subsequent request on the related unicast
       request URI.  The unicast request URI is obtained by replacing the
       authority part of the request URI with the transport-layer source
       address of the response message.

       A cache MAY revalidate a response by making a GET request on the
       related unicast request URI.

       A GET request to a multicast group MUST NOT contain an ETag option.
       A mechanism to suppress responses the client already has is left for
       further study.

    8.2.2.  Proxying

       When a forward-proxy receives a request with a Proxy-Uri or URI
       constructed from Proxy-Scheme that indicates a multicast address, the
       proxy obtains a set of responses as described above and sends all
       responses (both cached-still-fresh and new) back to the original
       client.

       This specification does not provide a way to indicate the unicast-
       modified request URI (base URI) in responses thus forwarded.
       Proxying multicast requests is discussed in more detail in
       [GROUPCOMM]; one proposal to address the base URI issue can be found
       in Section 3 of [CoAP-MISC].

    Shelby, et al.               Standards Track                   [Page 67]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    9.  Securing CoAP

       This section defines the DTLS binding for CoAP.

       During the provisioning phase, a CoAP device is provided with the
       security information that it needs, including keying materials and
       access control lists.  This specification defines provisioning for
       the RawPublicKey mode in Section 9.1.3.2.1.  At the end of the
       provisioning phase, the device will be in one of four security modes
       with the following information for the given mode.  The NoSec and
       RawPublicKey modes are mandatory to implement for this specification.

       NoSec:  There is no protocol-level security (DTLS is disabled).
          Alternative techniques to provide lower-layer security SHOULD be
          used when appropriate.  The use of IPsec is discussed in
          [IPsec-CoAP].  Certain link layers in use with constrained nodes
          also provide link-layer security, which may be appropriate with
          proper key management.

       PreSharedKey:  DTLS is enabled, there is a list of pre-shared keys
          [RFC4279], and each key includes a list of which nodes it can be
          used to communicate with as described in Section 9.1.3.1.  At the
          extreme, there may be one key for each node this CoAP node needs
          to communicate with (1:1 node/key ratio).  Conversely, if more
          than two entities share a specific pre-shared key, this key only
          enables the entities to authenticate as a member of that group and
          not as a specific peer.

       RawPublicKey:  DTLS is enabled and the device has an asymmetric key
          pair without a certificate (a raw public key) that is validated
          using an out-of-band mechanism [RFC7250] as described in
          Section 9.1.3.2.  The device also has an identity calculated from
          the public key and a list of identities of the nodes it can
          communicate with.

       Certificate:  DTLS is enabled and the device has an asymmetric key
          pair with an X.509 certificate [RFC5280] that binds it to its
          subject and is signed by some common trust root as described in
          Section 9.1.3.3.  The device also has a list of root trust anchors
          that can be used for validating a certificate.

       In the "NoSec" mode, the system simply sends the packets over normal
       UDP over IP and is indicated by the "coap" scheme and the 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; see Section 11.5 for an additional complication with this
       approach.

    Shelby, et al.               Standards Track                   [Page 68]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       The other three security modes are achieved using DTLS and are
       indicated by the "coaps" scheme and DTLS-secured CoAP default port.
       The result is a security association that can be used to authenticate
       (within the limits of the security model) and, based on this
       authentication, authorize the communication partner.  CoAP itself
       does not provide protocol primitives for authentication or
       authorization; where this is required, it can either be provided by
       communication security (i.e., IPsec or DTLS) or by object security
       (within the payload).  Devices that require authorization for certain
       operations are expected to require one of these two forms of
       security.  Necessarily, where an intermediary is involved,
       communication security only works when that intermediary is part of
       the trust relationships.  CoAP does not provide a way to forward
       different levels of authorization that clients may have with an
       intermediary to further intermediaries or origin servers -- it
       therefore may be required to perform all authorization at the first
       intermediary.

    9.1.  DTLS-Secured CoAP

       Just as HTTP is secured using Transport Layer Security (TLS) over
       TCP, CoAP is secured using Datagram TLS (DTLS) [RFC6347] over UDP
       (see Figure 13).  This section defines the CoAP binding to DTLS,
       along with the minimal mandatory-to-implement configurations
       appropriate for constrained environments.  The binding is defined by
       a series of deltas to unicast CoAP.  In practice, DTLS is TLS with
       added features to deal with the unreliable nature of the UDP
       transport.

                             +----------------------+
                             |      Application     |
                             +----------------------+
                             +----------------------+
                             |  Requests/Responses  |
                             |----------------------|  CoAP
                             |       Messages       |
                             +----------------------+
                             +----------------------+
                             |         DTLS         |
                             +----------------------+
                             +----------------------+
                             |          UDP         |
                             +----------------------+

                 Figure 13: Abstract Layering of DTLS-Secured CoAP

    Shelby, et al.               Standards Track                   [Page 69]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       In some constrained nodes (limited flash and/or RAM) and networks
       (limited bandwidth or high scalability requirements), and depending
       on the specific cipher suites in use, all modes of DTLS may not be
       applicable.  Some DTLS cipher suites can add significant
       implementation complexity as well as some initial handshake overhead
       needed when setting up the security association.  Once the initial
       handshake is completed, DTLS adds a limited per-datagram overhead of
       approximately 13 bytes, not including any initialization vectors/
       nonces (e.g., 8 bytes with TLS_PSK_WITH_AES_128_CCM_8 [RFC6655]),
       integrity check values (e.g., 8 bytes with TLS_PSK_WITH_AES_128_CCM_8
       [RFC6655]), and padding required by the cipher suite.  Whether the
       use of a given mode of DTLS is applicable for a CoAP-based
       application should be carefully weighed considering the specific
       cipher suites that may be applicable, whether the session maintenance
       makes it compatible with application flows, and whether sufficient
       resources are available on the constrained nodes and for the added
       network overhead.  (For some modes of using DTLS, this specification
       identifies a mandatory-to-implement cipher suite.  This is an
       implementation requirement to maximize interoperability in those
       cases where these cipher suites are indeed appropriate.  The specific
       security policies of an application may determine the actual set of
       cipher suites that can be used.)  DTLS is not applicable to group
       keying (multicast communication); however, it may be a component in a
       future group key management protocol.

    9.1.1.  Messaging Layer

       The endpoint acting as the CoAP client should also act as the DTLS
       client.  It should initiate a session to the server on the
       appropriate port.  When the DTLS handshake has finished, the client
       may initiate the first CoAP request.  All CoAP messages MUST be sent
       as DTLS "application data".

       The following rules are added for matching an Acknowledgement message
       or Reset message to a Confirmable message, or a Reset message to a
       Non-confirmable message: The DTLS session MUST be the same, and the
       epoch MUST be the same.

       A message is the same when it is sent within the same DTLS session
       and same epoch and has the same Message ID.

       Note: When a Confirmable message is retransmitted, a new DTLS
       sequence_number is used for each attempt, even though the CoAP
       Message ID stays the same.  So a recipient still has to perform
       deduplication as described in Section 4.5.  Retransmissions MUST NOT
       be performed across epochs.

    Shelby, et al.               Standards Track                   [Page 70]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       DTLS connections in RawPublicKey and Certificate mode are set up
       using mutual authentication so they can remain up and be reused for
       future message exchanges in either direction.  Devices can close a
       DTLS connection when they need to recover resources, but in general
       they should keep the connection up for as long as possible.  Closing
       the DTLS connection after every CoAP message exchange is very
       inefficient.

    9.1.2.  Request/Response Layer

       The following rules are added for matching a response to a request:
       The DTLS session MUST be the same, and the epoch MUST be the same.

       This means the response to a DTLS secured request MUST always be DTLS
       secured using the same security session and epoch.  Any attempt to
       supply a NoSec response to a DTLS request simply does not match the
       request and therefore MUST be rejected (unless it does match an
       unrelated NoSec request).

    9.1.3.  Endpoint Identity

       Devices SHOULD support the Server Name Indication (SNI) to indicate
       their authority in the SNI HostName field as defined in Section 3 of
       [RFC6066].  This is needed so that when a host that acts as a virtual
       server for multiple Authorities receives a new DTLS connection, it
       knows which keys to use for the DTLS session.

    9.1.3.1.  Pre-Shared Keys

       When forming a connection to a new node, the system selects an
       appropriate key based on which nodes it is trying to reach and then
       forms a DTLS session using a PSK (Pre-Shared Key) mode of DTLS.
       Implementations in these modes MUST support the mandatory-to-
       implement cipher suite TLS_PSK_WITH_AES_128_CCM_8 as specified in
       [RFC6655].

       Depending on the commissioning model, applications may need to define
       an application profile for identity hints (as required and detailed
       in Section 5.2 of [RFC4279]) to enable the use of PSK identity hints.

       The security considerations of Section 7 of [RFC4279] apply.  In
       particular, applications should carefully weigh whether or not they
       need Perfect Forward Secrecy (PFS) and select an appropriate cipher
       suite (Section 7.1 of [RFC4279]).  The entropy of the PSK must be
       sufficient to mitigate against brute-force and (where the PSK is not
       chosen randomly but by a human) dictionary attacks (Section 7.2 of
       [RFC4279]).  The cleartext communication of client identities may
       leak data or compromise privacy (Section 7.3 of [RFC4279]).

    Shelby, et al.               Standards Track                   [Page 71]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    9.1.3.2.  Raw Public Key Certificates

       In this mode, the device has an asymmetric key pair but without an
       X.509 certificate (called a raw public key); for example, the
       asymmetric key pair is generated by the manufacturer and installed on
       the device (see also Section 11.6).  A device MAY be configured with
       multiple raw public keys.  The type and length of the raw public key
       depends on the cipher suite used.  Implementations in RawPublicKey
       mode MUST support the mandatory-to-implement cipher suite
       TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as specified in [RFC7251],
       [RFC5246], and [RFC4492].  The key used MUST be ECDSA capable.  The
       curve secp256r1 MUST be supported [RFC4492]; this curve is equivalent
       to the NIST P-256 curve.  The hash algorithm is SHA-256.
       Implementations MUST use the Supported Elliptic Curves and Supported
       Point Formats Extensions [RFC4492]; the uncompressed point format
       MUST be supported; [RFC6090] can be used as an implementation method.
       Some guidance relevant to the implementation of this cipher suite can
       be found in [W3CXMLSEC].  The mechanism for using raw public keys
       with TLS is specified in [RFC7250].

       Implementation Note:  Specifically, this means the extensions listed
          in Figure 14 with at least the values listed will be present in
          the DTLS handshake.

       Extension: elliptic_curves
        Type: elliptic_curves (0x000a)
        Length: 4
        Elliptic Curves Length: 2
        Elliptic curves (1 curve)
          Elliptic curve: secp256r1 (0x0017)

       Extension: ec_point_formats
        Type: ec_point_formats (0x000b)
        Length: 2
        EC point formats Length: 1
        Elliptic curves point formats (1)
          EC point format: uncompressed (0)

       Extension: signature_algorithms
        Type: signature_algorithms (0x000d)
        Length: 4
        Data (4 bytes): 00 02 04 03
          HashAlgorithm: sha256 (4)
          SignatureAlgorithm: ecdsa (3)

                      Figure 14: DTLS Extensions Present for
                        TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8

    Shelby, et al.               Standards Track                   [Page 72]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    9.1.3.2.1.  Provisioning

       The RawPublicKey mode was designed to be easily provisioned in M2M
       deployments.  It is assumed that each device has an appropriate
       asymmetric public key pair installed.  An identifier is calculated by
       the endpoint from the public key as described in Section 2 of
       [RFC6920].  All implementations that support checking RawPublicKey
       identities MUST support at least the sha-256-120 mode (SHA-256
       truncated to 120 bits).  Implementations SHOULD also support longer
       length identifiers and MAY support shorter lengths.  Note that the
       shorter lengths provide less security against attacks, and their use
       is NOT RECOMMENDED.

       Depending on how identifiers are given to the system that verifies
       them, support for URI, binary, and/or human-speakable format
       [RFC6920] needs to be implemented.  All implementations SHOULD
       support the binary mode, and implementations that have a user
       interface SHOULD also support the human-speakable format.

       During provisioning, the identifier of each node is collected, for
       example, by reading a barcode on the outside of the device or by
       obtaining a pre-compiled list of the identifiers.  These identifiers
       are then installed in the corresponding endpoint, for example, an M2M
       data collection server.  The identifier is used for two purposes, to
       associate the endpoint with further device information and to perform
       access control.  During (initial and ongoing) provisioning, an access
       control list of identifiers with which the device may start DTLS
       sessions SHOULD also be installed and maintained.

    9.1.3.3.  X.509 Certificates

       Implementations in Certificate Mode MUST support the mandatory-to-
       implement cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as
       specified in [RFC7251], [RFC5246], and [RFC4492].  Namely, the
       certificate includes a SubjectPublicKeyInfo that indicates an
       algorithm of id-ecPublicKey with namedCurves secp256r1 [RFC5480]; the
       public key format is uncompressed [RFC5480]; the hash algorithm is
       SHA-256; if included, the key usage extension indicates
       digitalSignature.  Certificates MUST be signed with ECDSA using
       secp256r1, and the signature MUST use SHA-256.  The key used MUST be
       ECDSA capable.  The curve secp256r1 MUST be supported [RFC4492]; this
       curve is equivalent to the NIST P-256 curve.  The hash algorithm is
       SHA-256.  Implementations MUST use the Supported Elliptic Curves and
       Supported Point Formats Extensions [RFC4492]; the uncompressed point
       format MUST be supported; [RFC6090] can be used as an implementation
       method.

    Shelby, et al.               Standards Track                   [Page 73]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       The subject in the certificate would be built out of a long-term
       unique identifier for the device such as the EUI-64 [EUI64].  The
       subject could also be based on the Fully Qualified Domain Name (FQDN)
       that was used as the Host part of the CoAP URI.  However, the
       device's IP address should not typically be used as the subject, as
       it would change over time.  The discovery process used in the system
       would build up the mapping between IP addresses of the given devices
       and the subject for each device.  Some devices could have more than
       one subject and would need more than a single certificate.

       When a new connection is formed, the certificate from the remote
       device needs to be verified.  If the CoAP node has a source of
       absolute time, then the node SHOULD check that the validity dates of
       the certificate are within range.  The certificate MUST be validated
       as appropriate for the security requirements, using functionality
       equivalent to the algorithm specified in Section 6 of [RFC5280].  If
       the certificate contains a SubjectAltName, then the authority of the
       request URI MUST match at least one of the authorities of any CoAP
       URI found in a field of URI type in the SubjectAltName set.  If there
       is no SubjectAltName in the certificate, then the authority of the
       request URI MUST match the Common Name (CN) found in the certificate
       using the matching rules defined in [RFC3280] with the exception that
       certificates with wildcards are not allowed.

       CoRE support for certificate status checking requires further study.
       As a mapping of the Online Certificate Status Protocol (OCSP)
       [RFC6960] onto CoAP is not currently defined and OCSP may also not be
       easily applicable in all environments, an alternative approach may be
       using the TLS Certificate Status Request extension (Section 8 of
       [RFC6066]; also known as "OCSP stapling") or preferably the Multiple
       Certificate Status Extension ([RFC6961]), if available.

       If the system has a shared key in addition to the certificate, then a
       cipher suite that includes the shared key such as
       TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA [RFC5489] SHOULD be used.

    10.  Cross-Protocol Proxying between CoAP and HTTP

       CoAP supports a limited subset of HTTP functionality, and thus cross-
       protocol proxying to HTTP is straightforward.  There might be several
       reasons for proxying between CoAP and HTTP, for example, when
       designing a web interface for use over either protocol or when
       realizing a CoAP-HTTP proxy.  Likewise, CoAP could equally be proxied
       to other protocols such as XMPP [RFC6120] or SIP [RFC3264]; the
       definition of these mechanisms is out of scope for this
       specification.

    Shelby, et al.               Standards Track                   [Page 74]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       There are two possible directions to access a resource via a forward-
       proxy:

       CoAP-HTTP Proxying:  Enables CoAP clients to access resources on HTTP
          servers through an intermediary.  This is initiated by including
          the Proxy-Uri or Proxy-Scheme Option with an "http" or "https" URI
          in a CoAP request to a CoAP-HTTP proxy.

       HTTP-CoAP Proxying:  Enables HTTP clients to access resources on CoAP
          servers through an intermediary.  This is initiated by specifying
          a "coap" or "coaps" URI in the Request-Line of an HTTP request to
          an HTTP-CoAP proxy.

       Either way, only the request/response model of CoAP is mapped to
       HTTP.  The underlying model of Confirmable or Non-confirmable
       messages, etc., is invisible and MUST have no effect on a proxy
       function.  The following sections describe the handling of requests
       to a forward-proxy.  Reverse-proxies are not specified, as the proxy
       function is transparent to the client with the proxy acting as if it
       were the origin server.  However, similar considerations apply to
       reverse-proxies as to forward-proxies, and there generally will be an
       expectation that reverse-proxies operate in a similar way forward-
       proxies would.  As an implementation note, HTTP client libraries may
       make it hard to operate an HTTP-CoAP forward-proxy by not providing a
       way to put a CoAP URI on the HTTP Request-Line; reverse-proxying may
       therefore lead to wider applicability of a proxy.  A separate
       specification may define a convention for URIs operating such an
       HTTP-CoAP reverse-proxy [MAPPING].

    10.1.  CoAP-HTTP Proxying

       If a request contains a Proxy-Uri or Proxy-Scheme Option with an
       'http' or 'https' URI [RFC2616], then the receiving CoAP endpoint
       (called "the proxy" henceforth) is requested to perform the operation
       specified by the request method on the indicated HTTP resource and
       return the result to the client.  (See also Section 5.7 for how the
       request to the proxy is formulated, including security requirements.)

       This section specifies for any CoAP request the CoAP response that
       the proxy should return to the client.  How the proxy actually
       satisfies the request is an implementation detail, although the
       typical case is expected to be that the proxy translates and forwards
       the request to an HTTP origin server.

    Shelby, et al.               Standards Track                   [Page 75]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       Since HTTP and CoAP share the basic set of request methods,
       performing a CoAP request on an HTTP resource is not so different
       from performing it on a CoAP resource.  The meanings of the
       individual CoAP methods when performed on HTTP resources are
       explained in the subsections of this section.

       If the proxy is unable or unwilling to service a request with an HTTP
       URI, a 5.05 (Proxying Not Supported) response is returned to the
       client.  If the proxy services the request by interacting with a
       third party (such as the HTTP origin server) and is unable to obtain
       a result within a reasonable time frame, a 5.04 (Gateway Timeout)
       response is returned; if a result can be obtained but is not
       understood, a 5.02 (Bad Gateway) response is returned.

    10.1.1.  GET

       The GET method requests the proxy to return a representation of the
       HTTP resource identified by the request URI.

       Upon success, a 2.05 (Content) Response Code SHOULD be returned.  The
       payload of the response MUST be a representation of the target HTTP
       resource, and the Content-Format Option MUST be set accordingly.  The
       response MUST indicate a Max-Age value that is no greater than the
       remaining time the representation can be considered fresh.  If the
       HTTP entity has an entity-tag, the proxy SHOULD include an ETag
       Option in the response and process ETag Options in requests as
       described below.

       A client can influence the processing of a GET request by including
       the following option:

       Accept:  The request MAY include an Accept Option, identifying the
          preferred response content-format.

       ETag:  The request MAY include one or more ETag Options, identifying
          responses that the client has stored.  This requests the proxy to
          send a 2.03 (Valid) response whenever it would send a 2.05
          (Content) response with an entity-tag in the requested set
          otherwise.  Note that CoAP ETags are always strong ETags in the
          HTTP sense; CoAP does not have the equivalent of HTTP weak ETags,
          and there is no good way to make use of these in a cross-proxy.

    Shelby, et al.               Standards Track                   [Page 76]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    10.1.2.  PUT

       The PUT method requests the proxy to update or create the HTTP
       resource identified by the request URI with the enclosed
       representation.

       If a new resource is created at the request URI, a 2.01 (Created)
       response MUST be returned to the client.  If an existing resource is
       modified, a 2.04 (Changed) response MUST be returned to indicate
       successful completion of the request.

    10.1.3.  DELETE

       The DELETE method requests the proxy to delete the HTTP resource
       identified by the request URI at the HTTP origin server.

       A 2.02 (Deleted) response MUST be returned to the client upon success
       or if the resource does not exist at the time of the request.

    10.1.4.  POST

       The POST method requests the proxy to have the representation
       enclosed in the request be processed by the HTTP origin server.  The
       actual function performed by the POST method is determined by the
       origin server and dependent on the resource identified by the request
       URI.

       If the action performed by the POST method does not result in a
       resource that can be identified by a URI, a 2.04 (Changed) response
       MUST be returned to the client.  If a resource has been created on
       the origin server, a 2.01 (Created) response MUST be returned.

    10.2.  HTTP-CoAP Proxying

       If an HTTP request contains a Request-URI with a "coap" or "coaps"
       URI, then the receiving HTTP endpoint (called "the proxy" henceforth)
       is requested to perform the operation specified by the request method
       on the indicated CoAP resource and return the result to the client.

       This section specifies for any HTTP request the HTTP response that
       the proxy should return to the client.  Unless otherwise specified,
       all the statements made are RECOMMENDED behavior; some highly
       constrained implementations may need to resort to shortcuts.  How the
       proxy actually satisfies the request is an implementation detail,
       although the typical case is expected to be that the proxy translates
       and forwards the request to a CoAP origin server.  The meanings of
       the individual HTTP methods when performed on CoAP resources are
       explained in the subsections of this section.

    Shelby, et al.               Standards Track                   [Page 77]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       If the proxy is unable or unwilling to service a request with a CoAP
       URI, a 501 (Not Implemented) response is returned to the client.  If
       the proxy services the request by interacting with a third party
       (such as the CoAP origin server) and is unable to obtain a result
       within a reasonable time frame, a 504 (Gateway Timeout) response is
       returned; if a result can be obtained but is not understood, a 502
       (Bad Gateway) response is returned.

    10.2.1.  OPTIONS and TRACE

       As the OPTIONS and TRACE methods are not supported in CoAP, a 501
       (Not Implemented) error MUST be returned to the client.

    10.2.2.  GET

       The GET method requests the proxy to return a representation of the
       CoAP resource identified by the Request-URI.

       Upon success, a 200 (OK) response is returned.  The payload of the
       response MUST be a representation of the target CoAP resource, and
       the Content-Type and Content-Encoding header fields MUST be set
       accordingly.  The response MUST indicate a max-age directive that
       indicates a value no greater than the remaining time the
       representation can be considered fresh.  If the CoAP response has an
       ETag option, the proxy should include an ETag header field in the
       response.

       A client can influence the processing of a GET request by including
       the following options:

       Accept:  The most-preferred media type of the HTTP Accept header
          field in a request is mapped to a CoAP Accept option.  HTTP Accept
          media-type ranges, parameters, and extensions are not supported by
          the CoAP Accept option.  If the proxy cannot send a response that
          is acceptable according to the combined Accept field value, then
          the proxy sends a 406 (Not Acceptable) response.  The proxy MAY
          then retry the request with further media types from the HTTP
          Accept header field.

       Conditional GETs:  Conditional HTTP GET requests that include an "If-
          Match" or "If-None-Match" request-header field can be mapped to a
          corresponding CoAP request.  The "If-Modified-Since" and "If-
          Unmodified-Since" request-header fields are not directly supported
          by CoAP but are implemented locally by a caching proxy.

    Shelby, et al.               Standards Track                   [Page 78]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    10.2.3.  HEAD

       The HEAD method is identical to GET except that the server MUST NOT
       return a message-body in the response.

       Although there is no direct equivalent of HTTP's HEAD method in CoAP,
       an HTTP-CoAP proxy responds to HEAD requests for CoAP resources, and
       the HTTP headers are returned without a message-body.

       Implementation Note:  An HTTP-CoAP proxy may want to try using a
          block-wise transfer option [BLOCK] to minimize the amount of data
          actually transferred, but it needs to be prepared for the case
          that the origin server does not support block-wise transfers.

    10.2.4.  POST

       The POST method requests the proxy to have the representation
       enclosed in the request be processed by the CoAP origin server.  The
       actual function performed by the POST method is determined by the
       origin server and dependent on the resource identified by the request
       URI.

       If the action performed by the POST method does not result in a
       resource that can be identified by a URI, a 200 (OK) or 204 (No
       Content) response MUST be returned to the client.  If a resource has
       been created on the origin server, a 201 (Created) response MUST be
       returned.

       If any of the Location-* Options are present in the CoAP response, a
       Location header field constructed from the values of these options is
       returned.

    10.2.5.  PUT

       The PUT method requests the proxy to update or create the CoAP
       resource identified by the Request-URI with the enclosed
       representation.

       If a new resource is created at the Request-URI, a 201 (Created)
       response is returned to the client.  If an existing resource is
       modified, either the 200 (OK) or 204 (No Content) Response Codes is
       sent to indicate successful completion of the request.

    Shelby, et al.               Standards Track                   [Page 79]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    10.2.6.  DELETE

       The DELETE method requests the proxy to delete the CoAP resource
       identified by the Request-URI at the CoAP origin server.

       A successful response is 200 (OK) if the response includes an entity
       describing the status or 204 (No Content) if the action has been
       enacted but the response does not include an entity.

    10.2.7.  CONNECT

       This method cannot currently be satisfied by an HTTP-CoAP proxy
       function, as TLS to DTLS tunneling has not yet been specified.  For
       now, a 501 (Not Implemented) error is returned to the client.

    11.  Security Considerations

       This section analyzes the possible threats to the protocol.  It is
       meant to inform protocol and application developers about the
       security limitations of CoAP as described in this document.  As CoAP
       realizes a subset of the features in HTTP/1.1, the security
       considerations in Section 15 of [RFC2616] are also pertinent to CoAP.
       This section concentrates on describing limitations specific to CoAP.

    11.1.  Parsing the Protocol and Processing URIs

       A network-facing application can exhibit vulnerabilities in its
       processing logic for incoming packets.  Complex parsers are well-
       known as a likely source of such vulnerabilities, such as the ability
       to remotely crash a node, or even remotely execute arbitrary code on
       it.  CoAP attempts to narrow the opportunities for introducing such
       vulnerabilities by reducing parser complexity, by giving the entire
       range of encodable values a meaning where possible, and by
       aggressively reducing complexity that is often caused by unnecessary
       choice between multiple representations that mean the same thing.
       Much of the URI processing has been moved to the clients, further
       reducing the opportunities for introducing vulnerabilities into the
       servers.  Even so, the URI processing code in CoAP implementations is
       likely to be a large source of remaining vulnerabilities and should
       be implemented with special care.  CoAP access control
       implementations need to ensure they don't introduce vulnerabilities
       through discrepancies between the code deriving access control
       decisions from a URI and the code finally serving up the resource
       addressed by the URI.  The most complex parser remaining could be the
       one for the CoRE Link Format, although this also has been designed
       with a goal of reduced implementation complexity [RFC6690].  (See
       also Section 15.2 of [RFC2616].)

    Shelby, et al.               Standards Track                   [Page 80]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    11.2.  Proxying and Caching

       As mentioned in Section 15.7 of [RFC2616], proxies are by their very
       nature men-in-the-middle, breaking any IPsec or DTLS protection that
       a direct CoAP message exchange might have.  They are therefore
       interesting targets for breaking confidentiality or integrity of CoAP
       message exchanges.  As noted in [RFC2616], they are also interesting
       targets for breaking availability.

       The threat to confidentiality and integrity of request/response data
       is amplified where proxies also cache.  Note that CoAP does not
       define any of the cache-suppressing Cache-Control options that
       HTTP/1.1 provides to better protect sensitive data.

       For a caching implementation, any access control considerations that
       would apply to making the request that generated the cache entry also
       need to be applied to the value in the cache.  This is relevant for
       clients that implement multiple security domains, as well as for
       proxies that may serve multiple clients.  Also, a caching proxy MUST
       NOT make cached values available to requests that have lesser
       transport-security properties than those the proxy would require to
       perform request forwarding in the first place.

       Unlike the "coap" scheme, responses to "coaps" identified requests
       are never "public" and thus MUST NOT be reused for shared caching,
       unless the cache is able to make equivalent access control decisions
       to the ones that led to the cached entry.  They can, however, be
       reused in a private cache if the message is cacheable by default in
       CoAP.

       Finally, a proxy that fans out Separate Responses (as opposed to
       piggybacked Responses) to multiple original requesters may provide
       additional amplification (see Section 11.3).

    11.3.  Risk of Amplification

       CoAP servers generally reply to a request packet with a response
       packet.  This response packet may be significantly larger than the
       request packet.  An attacker might use CoAP nodes to turn a small
       attack packet into a larger attack packet, an approach known as
       amplification.  There is therefore a danger that CoAP nodes could
       become implicated in denial-of-service (DoS) attacks by using the
       amplifying properties of the protocol: an attacker that is attempting
       to overload a victim but is limited in the amount of traffic it can
       generate can use amplification to generate a larger amount of
       traffic.

    Shelby, et al.               Standards Track                   [Page 81]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       This is particularly a problem in nodes that enable NoSec access, are
       accessible from an attacker, and can access potential victims (e.g.,
       on the general Internet), as the UDP protocol provides no way to
       verify the source address given in the request packet.  An attacker
       need only place the IP address of the victim in the source address of
       a suitable request packet to generate a larger packet directed at the
       victim.

       As a mitigating factor, many constrained networks will only be able
       to generate a small amount of traffic, which may make CoAP nodes less
       attractive for this attack.  However, the limited capacity of the
       constrained network makes the network itself a likely victim of an
       amplification attack.

       Therefore, large amplification factors SHOULD NOT be provided in the
       response if the request is not authenticated.  A CoAP server can
       reduce the amount of amplification it provides to an attacker by
       using slicing/blocking modes of CoAP [BLOCK] and offering large
       resource representations only in relatively small slices.  For
       example, for a 1000-byte resource, a 10-byte request might result in
       an 80-byte response (with a 64-byte block) instead of a 1016-byte
       response, considerably reducing the amplification provided.

       CoAP also supports the use of multicast IP addresses in requests, an
       important requirement for M2M.  Multicast CoAP requests may be the
       source of accidental or deliberate DoS attacks, especially over
       constrained networks.  This specification attempts to reduce the
       amplification effects of multicast requests by limiting when a
       response is returned.  To limit the possibility of malicious use,
       CoAP servers SHOULD NOT accept multicast requests that can not be
       authenticated in some way, cryptographically or by some multicast
       boundary limiting the potential sources.  If possible, a CoAP server
       SHOULD limit the support for multicast requests to the specific
       resources where the feature is required.

       On some general-purpose operating systems providing a POSIX-style API
       [IEEE1003.1], it is not straightforward to find out whether a packet
       received was addressed to a multicast address.  While many
       implementations will know whether they have joined a multicast group,
       this creates a problem for packets addressed to multicast addresses
       of the form FF0x::1, which are received by every IPv6 node.
       Implementations SHOULD make use of modern APIs such as
       IPV6_RECVPKTINFO [RFC3542], if available, to make this determination.

    Shelby, et al.               Standards Track                   [Page 82]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    11.4.  IP Address Spoofing Attacks

       Due to the lack of a handshake in UDP, a rogue endpoint that is free
       to read and write messages carried by the constrained network (i.e.,
       NoSec or PreSharedKey deployments with a nodes/key ratio > 1:1), may
       easily attack a single endpoint, a group of endpoints, as well as the
       whole network, e.g., by:

       1.  spoofing a Reset message in response to a Confirmable message or
           Non-confirmable message, thus making an endpoint "deaf"; or

       2.  spoofing an ACK in response to a CON message, thus potentially
           preventing the sender of the CON message from retransmitting, and
           drowning out the actual response; or

       3.  spoofing the entire response with forged payload/options (this
           has different levels of impact: from single-response disruption,
           to much bolder attacks on the supporting infrastructure, e.g.,
           poisoning proxy caches, or tricking validation/lookup interfaces
           in resource directories and, more generally, any component that
           stores global network state and uses CoAP as the messaging
           facility to handle setting or updating state is a potential
           target.); or

       4.  spoofing a multicast request for a target node; this may result
           in network congestion/collapse, a DoS attack on the victim, or
           forced wake-up from sleeping; or

       5.  spoofing observe messages, etc.

       Response spoofing by off-path attackers can be detected and mitigated
       even without transport layer security by choosing a nontrivial,
       randomized token in the request (Section 5.3.1).  [RFC4086] discusses
       randomness requirements for security.

       In principle, other kinds of spoofing can be detected by CoAP only in
       case Confirmable message semantics is used, because of unexpected
       Acknowledgement or Reset messages coming from the deceived endpoint.
       But this imposes keeping track of the used Message IDs, which is not
       always possible, and moreover detection becomes available usually
       after the damage is already done.  This kind of attack can be
       prevented using security modes other than NoSec.

       With or without source address spoofing, a client can attempt to
       overload a server by sending requests, preferably complex ones, to a
       server; address spoofing makes tracing back, and blocking, this
       attack harder.  Given that the cost of a CON request is small, this
       attack can easily be executed.  Under this attack, a constrained node

    Shelby, et al.               Standards Track                   [Page 83]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       with limited total energy available may exhaust that energy much more
       quickly than planned (battery depletion attack).  Also, if the client
       uses a Confirmable message and the server responds with a Confirmable
       separate response to a (possibly spoofed) address that does not
       respond, the server will have to allocate buffer and retransmission
       logic for each response up to the exhaustion of MAX_TRANSMIT_SPAN,
       making it more likely that it runs out of resources for processing
       legitimate traffic.  The latter problem can be mitigated somewhat by
       limiting the rate of responses as discussed in Section 4.7.  An
       attacker could also spoof the address of a legitimate client; this
       might cause the server, if it uses separate responses, to block
       legitimate responses to that client because of NSTART=1.  All these
       attacks can be prevented using a security mode other than NoSec, thus
       leaving only attacks on the security protocol.

    11.5.  Cross-Protocol Attacks

       The ability to incite a CoAP endpoint to send packets to a fake
       source address can be used not only for amplification, but also for
       cross-protocol attacks against a victim listening to UDP packets at a
       given address (IP address and port).  This would occur as follows:

       o  The attacker sends a message to a CoAP endpoint with the given
          address as the fake source address.

       o  The CoAP endpoint replies with a message to the given source
          address.

       o  The victim at the given address receives a UDP packet that it
          interprets according to the rules of a different protocol.

       This may be used to circumvent firewall rules that prevent direct
       communication from the attacker to the victim but happen to allow
       communication from the CoAP endpoint (which may also host a valid
       role in the other protocol) to the victim.

       Also, CoAP endpoints may be the victim of a cross-protocol attack
       generated through an endpoint of another UDP-based protocol such as
       DNS.  In both cases, attacks are possible if the security properties
       of the endpoints rely on checking IP addresses (and firewalling off
       direct attacks sent from outside using fake IP addresses).  In
       general, because of their lack of context, UDP-based protocols are
       relatively easy targets for cross-protocol attacks.

       Finally, CoAP URIs transported by other means could be used to incite
       clients to send messages to endpoints of other protocols.

    Shelby, et al.               Standards Track                   [Page 84]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       One mitigation against cross-protocol attacks is strict checking of
       the syntax of packets received, combined with sufficient difference
       in syntax.  As an example, it might help if it were difficult to
       incite a DNS server to send a DNS response that would pass the checks
       of a CoAP endpoint.  Unfortunately, the first two bytes of a DNS
       reply are an ID that can be chosen by the attacker and that map into
       the interesting part of the CoAP header, and the next two bytes are
       then interpreted as CoAP's Message ID (i.e., any value is
       acceptable).  The DNS count words may be interpreted as multiple
       instances of a (nonexistent but elective) CoAP option 0, or possibly
       as a Token.  The echoed query finally may be manufactured by the
       attacker to achieve a desired effect on the CoAP endpoint; the
       response added by the server (if any) might then just be interpreted
       as added payload.

                                       1  1  1  1  1  1
         0  1  2  3  4  5  6  7  8  9  0  1  2  3  4  5
       +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
       |                      ID                       | T, TKL, code
       +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
       |QR|   Opcode  |AA|TC|RD|RA|   Z    |   RCODE   | Message ID
       +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
       |                    QDCOUNT                    | (options 0)
       +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
       |                    ANCOUNT                    | (options 0)
       +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
       |                    NSCOUNT                    | (options 0)
       +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
       |                    ARCOUNT                    | (options 0)
       +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+

         Figure 15: DNS Header ([RFC1035], Section 4.1.1) vs. CoAP Message

       In general, for any pair of protocols, one of the protocols can very
       well have been designed in a way that enables an attacker to cause
       the generation of replies that look like messages of the other
       protocol.  It is often much harder to ensure or prove the absence of
       viable attacks than to generate examples that may not yet completely
       enable an attack but might be further developed by more creative
       minds.  Cross-protocol attacks can therefore only be completely
       mitigated if endpoints don't authorize actions desired by an attacker
       just based on trusting the source IP address of a packet.
       Conversely, a NoSec environment that completely relies on a firewall
       for CoAP security not only needs to firewall off the CoAP endpoints
       but also all other endpoints that might be incited to send UDP
       messages to CoAP endpoints using some other UDP-based protocol.

    Shelby, et al.               Standards Track                   [Page 85]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       In addition to the considerations above, the security considerations
       for DTLS with respect to cross-protocol attacks apply.  For example,
       if the same DTLS security association ("connection") is used to carry
       data of multiple protocols, DTLS no longer provides protection
       against cross-protocol attacks between these protocols.

    11.6.  Constrained-Node Considerations

       Implementers on constrained nodes often find themselves without a
       good source of entropy [RFC4086].  If that is the case, the node MUST
       NOT be used for processes that require good entropy, such as key
       generation.  Instead, keys should be generated externally and added
       to the device during manufacturing or commissioning.

       Due to their low processing power, constrained nodes are particularly
       susceptible to timing attacks.  Special care must be taken in
       implementation of cryptographic primitives.

       Large numbers of constrained nodes will be installed in exposed
       environments and will have little resistance to tampering, including
       recovery of keying materials.  This needs to be considered when
       defining the scope of credentials assigned to them.  In particular,
       assigning a shared key to a group of nodes may make any single
       constrained node a target for subverting the entire group.

    12.  IANA Considerations

    12.1.  CoAP Code Registries

       This document defines two sub-registries for the values of the Code
       field in the CoAP header within the "Constrained RESTful Environments
       (CoRE) Parameters" registry, hereafter referred to as the "CoRE
       Parameters" registry.

       Values in the two sub-registries are eight-bit values notated as
       three decimal digits c.dd separated by a period between the first and
       the second digit; the first digit c is between 0 and 7 and denotes
       the code class; the second and third digits dd denote a decimal
       number between 00 and 31 for the detail.

    Shelby, et al.               Standards Track                   [Page 86]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       All Code values are assigned by sub-registries according to the
       following ranges:

       0.00      Indicates an Empty message (see Section 4.1).

       0.01-0.31 Indicates a request.  Values in this range are assigned by
                 the "CoAP Method Codes" sub-registry (see Section 12.1.1).

       1.00-1.31 Reserved

       2.00-5.31 Indicates a response.  Values in this range are assigned by
                 the "CoAP Response Codes" sub-registry (see
                 Section 12.1.2).

       6.00-7.31 Reserved

    12.1.1.  Method Codes

       The name of the sub-registry is "CoAP Method Codes".

       Each entry in the sub-registry must include the Method Code in the
       range 0.01-0.31, the name of the method, and a reference to the
       method's documentation.

       Initial entries in this sub-registry are as follows:

                           +------+--------+-----------+
                           | Code | Name   | Reference |
                           +------+--------+-----------+
                           | 0.01 | GET    | [RFC7252] |
                           | 0.02 | POST   | [RFC7252] |
                           | 0.03 | PUT    | [RFC7252] |
                           | 0.04 | DELETE | [RFC7252] |
                           +------+--------+-----------+

                            Table 5: CoAP Method Codes

       All other Method Codes are Unassigned.

       The IANA policy for future additions to this sub-registry is "IETF
       Review or IESG Approval" as described in [RFC5226].

       The documentation of a Method Code should specify the semantics of a
       request with that code, including the following properties:

       o  The Response Codes the method returns in the success case.

       o  Whether the method is idempotent, safe, or both.

    Shelby, et al.               Standards Track                   [Page 87]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    12.1.2.  Response Codes

       The name of the sub-registry is "CoAP Response Codes".

       Each entry in the sub-registry must include the Response Code in the
       range 2.00-5.31, a description of the Response Code, and a reference
       to the Response Code's documentation.

       Initial entries in this sub-registry are as follows:

                +------+------------------------------+-----------+
                | Code | Description                  | Reference |
                +------+------------------------------+-----------+
                | 2.01 | Created                      | [RFC7252] |
                | 2.02 | Deleted                      | [RFC7252] |
                | 2.03 | Valid                        | [RFC7252] |
                | 2.04 | Changed                      | [RFC7252] |
                | 2.05 | Content                      | [RFC7252] |
                | 4.00 | Bad Request                  | [RFC7252] |
                | 4.01 | Unauthorized                 | [RFC7252] |
                | 4.02 | Bad Option                   | [RFC7252] |
                | 4.03 | Forbidden                    | [RFC7252] |
                | 4.04 | Not Found                    | [RFC7252] |
                | 4.05 | Method Not Allowed           | [RFC7252] |
                | 4.06 | Not Acceptable               | [RFC7252] |
                | 4.12 | Precondition Failed          | [RFC7252] |
                | 4.13 | Request Entity Too Large     | [RFC7252] |
                | 4.15 | Unsupported Content-Format   | [RFC7252] |
                | 5.00 | Internal Server Error        | [RFC7252] |
                | 5.01 | Not Implemented              | [RFC7252] |
                | 5.02 | Bad Gateway                  | [RFC7252] |
                | 5.03 | Service Unavailable          | [RFC7252] |
                | 5.04 | Gateway Timeout              | [RFC7252] |
                | 5.05 | Proxying Not Supported       | [RFC7252] |
                +------+------------------------------+-----------+

                           Table 6: CoAP Response Codes

       The Response Codes 3.00-3.31 are Reserved for future use.  All other
       Response Codes are Unassigned.

       The IANA policy for future additions to this sub-registry is "IETF
       Review or IESG Approval" as described in [RFC5226].

    Shelby, et al.               Standards Track                   [Page 88]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       The documentation of a Response Code should specify the semantics of
       a response with that code, including the following properties:

       o  The methods the Response Code applies to.

       o  Whether payload is required, optional, or not allowed.

       o  The semantics of the payload.  For example, the payload of a 2.05
          (Content) response is a representation of the target resource; the
          payload in an error response is a human-readable diagnostic
          payload.

       o  The format of the payload.  For example, the format in a 2.05
          (Content) response is indicated by the Content-Format Option; the
          format of the payload in an error response is always Net-Unicode
          text.

       o  Whether the response is cacheable according to the freshness
          model.

       o  Whether the response is validatable according to the validation
          model.

       o  Whether the response causes a cache to mark responses stored for
          the request URI as not fresh.

    12.2.  CoAP Option Numbers Registry

       This document defines a sub-registry for the Option Numbers used in
       CoAP options within the "CoRE Parameters" registry.  The name of the
       sub-registry is "CoAP Option Numbers".

       Each entry in the sub-registry must include the Option Number, the
       name of the option, and a reference to the option's documentation.

    Shelby, et al.               Standards Track                   [Page 89]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       Initial entries in this sub-registry are as follows:

                     +--------+------------------+-----------+
                     | Number | Name             | Reference |
                     +--------+------------------+-----------+
                     |      0 | (Reserved)       | [RFC7252] |
                     |      1 | If-Match         | [RFC7252] |
                     |      3 | Uri-Host         | [RFC7252] |
                     |      4 | ETag             | [RFC7252] |
                     |      5 | If-None-Match    | [RFC7252] |
                     |      7 | Uri-Port         | [RFC7252] |
                     |      8 | Location-Path    | [RFC7252] |
                     |     11 | Uri-Path         | [RFC7252] |
                     |     12 | Content-Format   | [RFC7252] |
                     |     14 | Max-Age          | [RFC7252] |
                     |     15 | Uri-Query        | [RFC7252] |
                     |     17 | Accept           | [RFC7252] |
                     |     20 | Location-Query   | [RFC7252] |
                     |     35 | Proxy-Uri        | [RFC7252] |
                     |     39 | Proxy-Scheme     | [RFC7252] |
                     |     60 | Size1            | [RFC7252] |
                     |    128 | (Reserved)       | [RFC7252] |
                     |    132 | (Reserved)       | [RFC7252] |
                     |    136 | (Reserved)       | [RFC7252] |
                     |    140 | (Reserved)       | [RFC7252] |
                     +--------+------------------+-----------+

                           Table 7: CoAP Option Numbers

       The IANA policy for future additions to this sub-registry is split
       into three tiers as follows.  The range of 0..255 is reserved for
       options defined by the IETF (IETF Review or IESG Approval).  The
       range of 256..2047 is reserved for commonly used options with public
       specifications (Specification Required).  The range of 2048..64999 is
       for all other options including private or vendor-specific ones,
       which undergo a Designated Expert review to help ensure that the
       option semantics are defined correctly.  The option numbers between
       65000 and 65535 inclusive are reserved for experiments.  They are not
       meant for vendor-specific use of any kind and MUST NOT be used in
       operational deployments.

    Shelby, et al.               Standards Track                   [Page 90]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

              +-------------+---------------------------------------+
              |       Range | Registration Procedures               |
              +-------------+---------------------------------------+
              |       0-255 | IETF Review or IESG Approval          |
              |    256-2047 | Specification Required                |
              |  2048-64999 | Expert Review                         |
              | 65000-65535 | Experimental use (no operational use) |
              +-------------+---------------------------------------+

               Table 8: CoAP Option Numbers: Registration Procedures

       The documentation of an Option Number should specify the semantics of
       an option with that number, including the following properties:

       o  The meaning of the option in a request.

       o  The meaning of the option in a response.

       o  Whether the option is critical or elective, as determined by the
          Option Number.

       o  Whether the option is Safe-to-Forward, and, if yes, whether it is
          part of the Cache-Key, as determined by the Option Number (see
          Section 5.4.2).

       o  The format and length of the option's value.

       o  Whether the option must occur at most once or whether it can occur
          multiple times.

       o  The default value, if any.  For a critical option with a default
          value, a discussion on how the default value enables processing by
          implementations that do not support the critical option
          (Section 5.4.4).

    12.3.  CoAP Content-Formats Registry

       Internet media types are identified by a string, such as
       "application/xml" [RFC2046].  In order to minimize the overhead of
       using these media types to indicate the format of payloads, this
       document defines a sub-registry for a subset of Internet media types
       to be used in CoAP and assigns each, in combination with a content-
       coding, a numeric identifier.  The name of the sub-registry is "CoAP
       Content-Formats", within the "CoRE Parameters" registry.

    Shelby, et al.               Standards Track                   [Page 91]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       Each entry in the sub-registry must include the media type registered
       with IANA, the numeric identifier in the range 0-65535 to be used for
       that media type in CoAP, the content-coding associated with this
       identifier, and a reference to a document describing what a payload
       with that media type means semantically.

       CoAP does not include a separate way to convey content-encoding
       information with a request or response, and for that reason the
       content-encoding is also specified for each identifier (if any).  If
       multiple content-encodings will be used with a media type, then a
       separate Content-Format identifier for each is to be registered.
       Similarly, other parameters related to an Internet media type, such
       as level, can be defined for a CoAP Content-Format entry.

       Initial entries in this sub-registry are as follows:

       +--------------------------+----------+----+------------------------+
       | Media type               | Encoding | ID | Reference              |
       +--------------------------+----------+----+------------------------+
       | text/plain;              | -        |  0 | [RFC2046] [RFC3676]    |
       | charset=utf-8            |          |    | [RFC5147]              |
       | application/link-format  | -        | 40 | [RFC6690]              |
       | application/xml          | -        | 41 | [RFC3023]              |
       | application/octet-stream | -        | 42 | [RFC2045] [RFC2046]    |
       | application/exi          | -        | 47 | [REC-exi-20140211]     |
       | application/json         | -        | 50 | [RFC7159]              |
       +--------------------------+----------+----+------------------------+

                           Table 9: CoAP Content-Formats

       The identifiers between 65000 and 65535 inclusive are reserved for
       experiments.  They are not meant for vendor-specific use of any kind
       and MUST NOT be used in operational deployments.  The identifiers
       between 256 and 9999 are reserved for future use in IETF
       specifications (IETF Review or IESG Approval).  All other identifiers
       are Unassigned.

       Because the namespace of single-byte identifiers is so small, the
       IANA policy for future additions in the range 0-255 inclusive to the
       sub-registry is "Expert Review" as described in [RFC5226].  The IANA
       policy for additions in the range 10000-64999 inclusive is "First
       Come First Served" as described in [RFC5226].  This is summarized in
       the following table.

    Shelby, et al.               Standards Track                   [Page 92]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

              +-------------+---------------------------------------+
              |       Range | Registration Procedures               |
              +-------------+---------------------------------------+
              |       0-255 | Expert Review                         |
              |    256-9999 | IETF Review or IESG Approval          |
              | 10000-64999 | First Come First Served               |
              | 65000-65535 | Experimental use (no operational use) |
              +-------------+---------------------------------------+

              Table 10: CoAP Content-Formats: Registration Procedures

       In machine-to-machine applications, it is not expected that generic
       Internet media types such as text/plain, application/xml or
       application/octet-stream are useful for real applications in the long
       term.  It is recommended that M2M applications making use of CoAP
       request new Internet media types from IANA indicating semantic
       information about how to create or parse a payload.  For example, a
       Smart Energy application payload carried as XML might request a more
       specific type like application/se+xml or application/se-exi.

    12.4.  URI Scheme Registration

       This document contains the request for the registration of the
       Uniform Resource Identifier (URI) scheme "coap".  The registration
       request complies with [RFC4395].

       URI scheme name.
          coap

       Status.
          Permanent.

       URI scheme syntax.
          Defined in Section 6.1 of [RFC7252].

       URI scheme semantics.
          The "coap" URI scheme provides a way to identify resources that
          are potentially accessible over the Constrained Application
          Protocol (CoAP).  The resources can be located by contacting the
          governing CoAP server and operated on by sending CoAP requests to
          the server.  This scheme can thus be compared to the "http" URI
          scheme [RFC2616].  See Section 6 of [RFC7252] for the details of
          operation.

       Encoding considerations.
          The scheme encoding conforms to the encoding rules established for
          URIs in [RFC3986], i.e., internationalized and reserved characters
          are expressed using UTF-8-based percent-encoding.

    Shelby, et al.               Standards Track                   [Page 93]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       Applications/protocols that use this URI scheme name.
          The scheme is used by CoAP endpoints to access CoAP resources.

       Interoperability considerations.
          None.

       Security considerations.
          See Section 11.1 of [RFC7252].

       Contact.
          IETF Chair <chair@ietf.org>

       Author/Change controller.
          IESG <iesg@ietf.org>

       References.
          [RFC7252]

    12.5.  Secure URI Scheme Registration

       This document contains the request for the registration of the
       Uniform Resource Identifier (URI) scheme "coaps".  The registration
       request complies with [RFC4395].

       URI scheme name.
          coaps

       Status.
          Permanent.

       URI scheme syntax.
          Defined in Section 6.2 of [RFC7252].

       URI scheme semantics.
          The "coaps" URI scheme provides a way to identify resources that
          are potentially accessible over the Constrained Application
          Protocol (CoAP) using Datagram Transport Layer Security (DTLS) for
          transport security.  The resources can be located by contacting
          the governing CoAP server and operated on by sending CoAP requests
          to the server.  This scheme can thus be compared to the "https"
          URI scheme [RFC2616].  See Section 6 of [RFC7252] for the details
          of operation.

       Encoding considerations.
          The scheme encoding conforms to the encoding rules established for
          URIs in [RFC3986], i.e., internationalized and reserved characters
          are expressed using UTF-8-based percent-encoding.

    Shelby, et al.               Standards Track                   [Page 94]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       Applications/protocols that use this URI scheme name.
          The scheme is used by CoAP endpoints to access CoAP resources
          using DTLS.

       Interoperability considerations.
          None.

       Security considerations.
          See Section 11.1 of [RFC7252].

       Contact.
          IETF Chair <chair@ietf.org>

       Author/Change controller.
          IESG <iesg@ietf.org>

       References.
          [RFC7252]

    12.6.  Service Name and Port Number Registration

       One of the functions of CoAP is resource discovery: a CoAP client can
       ask a CoAP server about the resources offered by it (see Section 7).
       To enable resource discovery just based on the knowledge of an IP
       address, the CoAP port for resource discovery needs to be
       standardized.

       IANA has assigned the port number 5683 and the service name "coap",
       in accordance with [RFC6335].

       Besides unicast, CoAP can be used with both multicast and anycast.

       Service Name.
          coap

       Transport Protocol.
          udp

       Assignee.
          IESG <iesg@ietf.org>

       Contact.
          IETF Chair <chair@ietf.org>

       Description.
          Constrained Application Protocol (CoAP)

    Shelby, et al.               Standards Track                   [Page 95]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       Reference.
          [RFC7252]

       Port Number.
          5683

    12.7.  Secure Service Name and Port Number Registration

       CoAP resource discovery may also be provided using the DTLS-secured
       CoAP "coaps" scheme.  Thus, the CoAP port for secure resource
       discovery needs to be standardized.

       IANA has assigned the port number 5684 and the service name "coaps",
       in accordance with [RFC6335].

       Besides unicast, DTLS-secured CoAP can be used with anycast.

       Service Name.
          coaps

       Transport Protocol.
          udp

       Assignee.
          IESG <iesg@ietf.org>

       Contact.
          IETF Chair <chair@ietf.org>

       Description.
          DTLS-secured CoAP

       Reference.
          [RFC7252]

       Port Number.
          5684

    Shelby, et al.               Standards Track                   [Page 96]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    12.8.  Multicast Address Registration

       Section 8, "Multicast CoAP", defines the use of multicast.  IANA has
       assigned the following multicast addresses for use by CoAP nodes:

       IPv4  -- "All CoAP Nodes" address 224.0.1.187, from the "IPv4
          Multicast Address Space Registry".  As the address is used for
          discovery that may span beyond a single network, it has come from
          the Internetwork Control Block (224.0.1.x, RFC 5771).

       IPv6  -- "All CoAP Nodes" address FF0X::FD, from the "IPv6 Multicast
          Address Space Registry", in the "Variable Scope Multicast
          Addresses" space (RFC 3307).  Note that there is a distinct
          multicast address for each scope that interested CoAP nodes should
          listen to; CoAP needs the Link-Local and Site-Local scopes only.

    13.  Acknowledgements

       Brian Frank was a contributor to and coauthor of early versions of
       this specification.

       Special thanks to Peter Bigot, Esko Dijk, and Cullen Jennings for
       substantial contributions to the ideas and text in the document,
       along with countless detailed reviews and discussions.

       Thanks to Floris Van den Abeele, Anthony Baire, Ed Beroset, Berta
       Carballido, Angelo P. Castellani, Gilbert Clark, Robert Cragie,
       Pierre David, Esko Dijk, Lisa Dusseault, Mehmet Ersue, Thomas
       Fossati, Tobias Gondrom, Bert Greevenbosch, Tom Herbst, Jeroen
       Hoebeke, Richard Kelsey, Sye Loong Keoh, Ari Keranen, Matthias
       Kovatsch, Avi Lior, Stephan Lohse, Salvatore Loreto, Kerry Lynn,
       Andrew McGregor, Alexey Melnikov, Guido Moritz, Petri Mutka, Colin
       O'Flynn, Charles Palmer, Adriano Pezzuto, Thomas Poetsch, Robert
       Quattlebaum, Akbar Rahman, Eric Rescorla, Dan Romascanu, David Ryan,
       Peter Saint-Andre, Szymon Sasin, Michael Scharf, Dale Seed, Robby
       Simpson, Peter van der Stok, Michael Stuber, Linyi Tian, Gilman
       Tolle, Matthieu Vial, Maciej Wasilak, Fan Xianyou, and Alper Yegin
       for helpful comments and discussions that have shaped the document.
       Special thanks also to the responsible IETF area director at the time
       of completion, Barry Leiba, and the IESG reviewers, Adrian Farrel,
       Martin Stiemerling, Pete Resnick, Richard Barnes, Sean Turner,
       Spencer Dawkins, Stephen Farrell, and Ted Lemon, who contributed in-
       depth reviews.

       Some of the text has been borrowed from the working documents of the
       IETF HTTPBIS working group.

    Shelby, et al.               Standards Track                   [Page 97]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    14.  References

    14.1.  Normative References

       [RFC0768]  Postel, J., "User Datagram Protocol", STD 6, RFC 768,
                  August 1980.

       [RFC2045]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
                  Extensions (MIME) Part One: Format of Internet Message
                  Bodies", RFC 2045, November 1996.

       [RFC2046]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
                  Extensions (MIME) Part Two: Media Types", RFC 2046,
                  November 1996.

       [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
                  Requirement Levels", BCP 14, RFC 2119, March 1997.

       [RFC2616]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
                  Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
                  Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.

       [RFC3023]  Murata, M., St. Laurent, S., and D. Kohn, "XML Media
                  Types", RFC 3023, January 2001.

       [RFC3629]  Yergeau, F., "UTF-8, a transformation format of ISO
                  10646", STD 63, RFC 3629, November 2003.

       [RFC3676]  Gellens, R., "The Text/Plain Format and DelSp Parameters",
                  RFC 3676, February 2004.

       [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
                  Resource Identifier (URI): Generic Syntax", STD 66, RFC
                  3986, January 2005.

       [RFC4279]  Eronen, P. and H. Tschofenig, "Pre-Shared Key Ciphersuites
                  for Transport Layer Security (TLS)", RFC 4279, December
                  2005.

       [RFC4395]  Hansen, T., Hardie, T., and L. Masinter, "Guidelines and
                  Registration Procedures for New URI Schemes", BCP 35, RFC
                  4395, February 2006.

       [RFC5147]  Wilde, E. and M. Duerst, "URI Fragment Identifiers for the
                  text/plain Media Type", RFC 5147, April 2008.

       [RFC5198]  Klensin, J. and M. Padlipsky, "Unicode Format for Network
                  Interchange", RFC 5198, March 2008.

    Shelby, et al.               Standards Track                   [Page 98]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       [RFC5226]  Narten, T. and H. Alvestrand, "Guidelines for Writing an
                  IANA Considerations Section in RFCs", BCP 26, RFC 5226,
                  May 2008.

       [RFC5234]  Crocker, D. and P. Overell, "Augmented BNF for Syntax
                  Specifications: ABNF", STD 68, RFC 5234, January 2008.

       [RFC5246]  Dierks, T. and E. Rescorla, "The Transport Layer Security
                  (TLS) Protocol Version 1.2", RFC 5246, August 2008.

       [RFC5280]  Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
                  Housley, R., and W. Polk, "Internet X.509 Public Key
                  Infrastructure Certificate and Certificate Revocation List
                  (CRL) Profile", RFC 5280, May 2008.

       [RFC5480]  Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk,
                  "Elliptic Curve Cryptography Subject Public Key
                  Information", RFC 5480, March 2009.

       [RFC5785]  Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
                  Uniform Resource Identifiers (URIs)", RFC 5785, April
                  2010.

       [RFC5952]  Kawamura, S. and M. Kawashima, "A Recommendation for IPv6
                  Address Text Representation", RFC 5952, August 2010.

       [RFC5988]  Nottingham, M., "Web Linking", RFC 5988, October 2010.

       [RFC6066]  Eastlake, D., "Transport Layer Security (TLS) Extensions:
                  Extension Definitions", RFC 6066, January 2011.

       [RFC6347]  Rescorla, E. and N. Modadugu, "Datagram Transport Layer
                  Security Version 1.2", RFC 6347, January 2012.

       [RFC6690]  Shelby, Z., "Constrained RESTful Environments (CoRE) Link
                  Format", RFC 6690, August 2012.

       [RFC6920]  Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B.,
                  Keranen, A., and P. Hallam-Baker, "Naming Things with
                  Hashes", RFC 6920, April 2013.

       [RFC7250]  Wouters, P., Tschofenig, H., Gilmore, J., Weiler, S., and
                  T. Kivinen, "Using Raw Public Keys in Transport Layer
                  Security (TLS) and Datagram Transport Layer Security
                  (DTLS)", RFC 7250, June 2014.

    Shelby, et al.               Standards Track                   [Page 99]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       [RFC7251]  McGrew, D., Bailey, D., Campagna, M., and R. Dugal, "AES-
                  CCM Elliptic Curve Cryptography (ECC) Cipher Suites for
                  Transport Layer Security (TLS)", RFC 7251, June 2014.

    14.2.  Informative References

       [BLOCK]    Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP",
                  Work in Progress, October 2013.

       [CoAP-MISC]
                  Bormann, C. and K. Hartke, "Miscellaneous additions to
                  CoAP", Work in Progress, December 2013.

       [EUI64]    IEEE Standards Association, "Guidelines for 64-bit Global
                  Identifier (EUI-64 (TM))", Registration Authority
                  Tutorials, April 2010, <http://standards.ieee.org/regauth/
                  oui/tutorials/EUI64.html>.

       [GROUPCOMM]
                  Rahman, A. and E. Dijk, "Group Communication for CoAP",
                  Work in Progress, December 2013.

       [HHGTTG]   Adams, D., "The Hitchhiker's Guide to the Galaxy", Pan
                  Books ISBN 3320258648, 1979.

       [IEEE1003.1]
                  IEEE and The Open Group, "Portable Operating System
                  Interface (POSIX)", The Open Group Base Specifications
                  Issue 7, IEEE 1003.1, 2013 Edition,
                  <http://pubs.opengroup.org/onlinepubs/9699919799/>.

       [IPsec-CoAP]
                  Bormann, C., "Using CoAP with IPsec", Work in Progress,
                  December 2012.

       [MAPPING]  Castellani, A., Loreto, S., Rahman, A., Fossati, T., and
                  E. Dijk, "Guidelines for HTTP-CoAP Mapping
                  Implementations", Work in Progress, February 2014.

       [OBSERVE]  Hartke, K., "Observing Resources in CoAP", Work in
                  Progress, April 2014.

       [REC-exi-20140211]
                  Schneider, J., Kamiya, T., Peintner, D., and R. Kyusakov,
                  "Efficient XML Interchange (EXI) Format 1.0 (Second
                  Edition)", W3C Recommendation REC-exi-20140211, February
                  2014, <http://www.w3.org/TR/2014/REC-exi-20140211/>.

    Shelby, et al.               Standards Track                  [Page 100]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       [REST]     Fielding, R., "Architectural Styles and the Design of
                  Network-based Software Architectures", Ph.D. Dissertation,
                  University of California, Irvine, 2000,
                  <http://www.ics.uci.edu/~fielding/pubs/dissertation/
                  fielding_dissertation.pdf>.

       [RFC0020]  Cerf, V., "ASCII format for network interchange", RFC 20,
                  October 1969.

       [RFC0791]  Postel, J., "Internet Protocol", STD 5, RFC 791, September
                  1981.

       [RFC0792]  Postel, J., "Internet Control Message Protocol", STD 5,
                  RFC 792, September 1981.

       [RFC0793]  Postel, J., "Transmission Control Protocol", STD 7, RFC
                  793, September 1981.

       [RFC1035]  Mockapetris, P., "Domain names - implementation and
                  specification", STD 13, RFC 1035, November 1987.

       [RFC3264]  Rosenberg, J. and H. Schulzrinne, "An Offer/Answer Model
                  with Session Description Protocol (SDP)", RFC 3264, June
                  2002.

       [RFC3280]  Housley, R., Polk, W., Ford, W., and D. Solo, "Internet
                  X.509 Public Key Infrastructure Certificate and
                  Certificate Revocation List (CRL) Profile", RFC 3280,
                  April 2002.

       [RFC3542]  Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei,
                  "Advanced Sockets Application Program Interface (API) for
                  IPv6", RFC 3542, May 2003.

       [RFC3828]  Larzon, L-A., Degermark, M., Pink, S., Jonsson, L-E., and
                  G. Fairhurst, "The Lightweight User Datagram Protocol
                  (UDP-Lite)", RFC 3828, July 2004.

       [RFC4086]  Eastlake, D., Schiller, J., and S. Crocker, "Randomness
                  Requirements for Security", BCP 106, RFC 4086, June 2005.

       [RFC4443]  Conta, A., Deering, S., and M. Gupta, "Internet Control
                  Message Protocol (ICMPv6) for the Internet Protocol
                  Version 6 (IPv6) Specification", RFC 4443, March 2006.

       [RFC4492]  Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B.
                  Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites
                  for Transport Layer Security (TLS)", RFC 4492, May 2006.

    Shelby, et al.               Standards Track                  [Page 101]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       [RFC4821]  Mathis, M. and J. Heffner, "Packetization Layer Path MTU
                  Discovery", RFC 4821, March 2007.

       [RFC4944]  Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler,
                  "Transmission of IPv6 Packets over IEEE 802.15.4
                  Networks", RFC 4944, September 2007.

       [RFC5405]  Eggert, L. and G. Fairhurst, "Unicast UDP Usage Guidelines
                  for Application Designers", BCP 145, RFC 5405, November
                  2008.

       [RFC5489]  Badra, M. and I. Hajjeh, "ECDHE_PSK Cipher Suites for
                  Transport Layer Security (TLS)", RFC 5489, March 2009.

       [RFC6090]  McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic
                  Curve Cryptography Algorithms", RFC 6090, February 2011.

       [RFC6120]  Saint-Andre, P., "Extensible Messaging and Presence
                  Protocol (XMPP): Core", RFC 6120, March 2011.

       [RFC6282]  Hui, J. and P. Thubert, "Compression Format for IPv6
                  Datagrams over IEEE 802.15.4-Based Networks", RFC 6282,
                  September 2011.

       [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, August 2011.

       [RFC6655]  McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for
                  Transport Layer Security (TLS)", RFC 6655, July 2012.

       [RFC6936]  Fairhurst, G. and M. Westerlund, "Applicability Statement
                  for the Use of IPv6 UDP Datagrams with Zero Checksums",
                  RFC 6936, April 2013.

       [RFC6960]  Santesson, S., Myers, M., Ankney, R., Malpani, A.,
                  Galperin, S., and C. Adams, "X.509 Internet Public Key
                  Infrastructure Online Certificate Status Protocol - OCSP",
                  RFC 6960, June 2013.

       [RFC6961]  Pettersen, Y., "The Transport Layer Security (TLS)
                  Multiple Certificate Status Request Extension", RFC 6961,
                  June 2013.

       [RFC7159]  Bray, T., "The JavaScript Object Notation (JSON) Data
                  Interchange Format", RFC 7159, March 2014.

    Shelby, et al.               Standards Track                  [Page 102]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       [RFC7228]  Bormann, C., Ersue, M., and A. Keranen, "Terminology for
                  Constrained-Node Networks", RFC 7228, May 2014.

       [RTO-CONSIDER]
                  Allman, M., "Retransmission Timeout Considerations", Work
                  in Progress, May 2012.

       [W3CXMLSEC]
                  Wenning, R., "Report of the XML Security PAG", W3C XML
                  Security PAG, October 2012,
                  <http://www.w3.org/2011/xmlsec-pag/pagreport.html>.

    Shelby, et al.               Standards Track                  [Page 103]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

    Appendix A.  Examples

       This section gives a number of short examples with message flows for
       GET requests.  These examples demonstrate the basic operation, the
       operation in the presence of retransmissions, and multicast.

       Figure 16 shows a basic GET request causing a piggybacked response:
       The client sends a Confirmable GET request for the resource
       coap://server/temperature to the server with a Message ID of 0x7d34.
       The request includes one Uri-Path Option (Delta 0 + 11 = 11, Length
       11, Value "temperature"); the Token is left empty.  This request is a
       total of 16 bytes long.  A 2.05 (Content) response is returned in the
       Acknowledgement message that acknowledges the Confirmable request,
       echoing both the Message ID 0x7d34 and the empty Token value.  The
       response includes a Payload of "22.3 C" and is 11 bytes long.

       Client  Server
          |      |
          |      |
          +----->|     Header: GET (T=CON, Code=0.01, MID=0x7d34)
          | GET  |   Uri-Path: "temperature"
          |      |
          |      |
          |<-----+     Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d34)
          | 2.05 |    Payload: "22.3 C"
          |      |

        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
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       | 1 | 0 |   0   |     GET=1     |          MID=0x7d34           |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       |  11   |  11   |      "temperature" (11 B) ...
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

        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
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       | 1 | 2 |   0   |    2.05=69    |          MID=0x7d34           |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       |1 1 1 1 1 1 1 1|      "22.3 C" (6 B) ...
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

               Figure 16: Confirmable Request; Piggybacked Response

    Shelby, et al.               Standards Track                  [Page 104]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       Figure 17 shows a similar example, but with the inclusion of an non-
       empty Token (Value 0x20) in the request and the response, increasing
       the sizes to 17 and 12 bytes, respectively.

       Client  Server
          |      |
          |      |
          +----->|     Header: GET (T=CON, Code=0.01, MID=0x7d35)
          | GET  |      Token: 0x20
          |      |   Uri-Path: "temperature"
          |      |
          |      |
          |<-----+     Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d35)
          | 2.05 |      Token: 0x20
          |      |    Payload: "22.3 C"
          |      |

        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
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       | 1 | 0 |   1   |     GET=1     |          MID=0x7d35           |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       |     0x20      |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       |  11   |  11   |      "temperature" (11 B) ...
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

        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
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       | 1 | 2 |   1   |    2.05=69    |          MID=0x7d35           |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       |     0x20      |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       |1 1 1 1 1 1 1 1| "22.3 C" (6 B) ...
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

               Figure 17: Confirmable Request; Piggybacked Response

    Shelby, et al.               Standards Track                  [Page 105]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       In Figure 18, the Confirmable GET request is lost.  After ACK_TIMEOUT
       seconds, the client retransmits the request, resulting in a
       piggybacked response as in the previous example.

       Client  Server
          |      |
          |      |
          +----X |     Header: GET (T=CON, Code=0.01, MID=0x7d36)
          | GET  |      Token: 0x31
          |      |   Uri-Path: "temperature"
       TIMEOUT   |
          |      |
          +----->|     Header: GET (T=CON, Code=0.01, MID=0x7d36)
          | GET  |      Token: 0x31
          |      |   Uri-Path: "temperature"
          |      |
          |      |
          |<-----+     Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d36)
          | 2.05 |      Token: 0x31
          |      |    Payload: "22.3 C"
          |      |

       Figure 18: Confirmable Request (Retransmitted); Piggybacked Response

    Shelby, et al.               Standards Track                  [Page 106]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       In Figure 19, the first Acknowledgement message from the server to
       the client is lost.  After ACK_TIMEOUT seconds, the client
       retransmits the request.

       Client  Server
          |      |
          |      |
          +----->|     Header: GET (T=CON, Code=0.01, MID=0x7d37)
          | GET  |      Token: 0x42
          |      |   Uri-Path: "temperature"
          |      |
          |      |
          | X----+     Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d37)
          | 2.05 |      Token: 0x42
          |      |    Payload: "22.3 C"
       TIMEOUT   |
          |      |
          +----->|     Header: GET (T=CON, Code=0.01, MID=0x7d37)
          | GET  |      Token: 0x42
          |      |   Uri-Path: "temperature"
          |      |
          |      |
          |<-----+     Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d37)
          | 2.05 |      Token: 0x42
          |      |    Payload: "22.3 C"
          |      |

       Figure 19: Confirmable Request; Piggybacked Response (Retransmitted)

    Shelby, et al.               Standards Track                  [Page 107]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       In Figure 20, the server acknowledges the Confirmable request and
       sends a 2.05 (Content) response separately in a Confirmable message.
       Note that the Acknowledgement message and the Confirmable response do
       not necessarily arrive in the same order as they were sent.  The
       client acknowledges the Confirmable response.

       Client  Server
          |      |
          |      |
          +----->|     Header: GET (T=CON, Code=0.01, MID=0x7d38)
          | GET  |      Token: 0x53
          |      |   Uri-Path: "temperature"
          |      |
          |      |
          |<- - -+     Header: (T=ACK, Code=0.00, MID=0x7d38)
          |      |
          |      |
          |<-----+     Header: 2.05 Content (T=CON, Code=2.05, MID=0xad7b)
          | 2.05 |      Token: 0x53
          |      |    Payload: "22.3 C"
          |      |
          |      |
          +- - ->|     Header: (T=ACK, Code=0.00, MID=0xad7b)
          |      |

                 Figure 20: Confirmable Request; Separate Response

    Shelby, et al.               Standards Track                  [Page 108]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       Figure 21 shows an example where the client loses its state (e.g.,
       crashes and is rebooted) right after sending a Confirmable request,
       so the separate response arriving some time later comes unexpected.
       In this case, the client rejects the Confirmable response with a
       Reset message.  Note that the unexpected ACK is silently ignored.

       Client  Server
          |      |
          |      |
          +----->|     Header: GET (T=CON, Code=0.01, MID=0x7d39)
          | GET  |      Token: 0x64
          |      |   Uri-Path: "temperature"
        CRASH    |
          |      |
          |<- - -+     Header: (T=ACK, Code=0.00, MID=0x7d39)
          |      |
          |      |
          |<-----+     Header: 2.05 Content (T=CON, Code=2.05, MID=0xad7c)
          | 2.05 |      Token: 0x64
          |      |    Payload: "22.3 C"
          |      |
          |      |
          +- - ->|     Header: (T=RST, Code=0.00, MID=0xad7c)
          |      |

          Figure 21: Confirmable Request; Separate Response (Unexpected)

       Figure 22 shows a basic GET request where the request and the
       response are Non-confirmable, so both may be lost without notice.

       Client  Server
          |      |
          |      |
          +----->|     Header: GET (T=NON, Code=0.01, MID=0x7d40)
          | GET  |      Token: 0x75
          |      |   Uri-Path: "temperature"
          |      |
          |      |
          |<-----+     Header: 2.05 Content (T=NON, Code=2.05, MID=0xad7d)
          | 2.05 |      Token: 0x75
          |      |    Payload: "22.3 C"
          |      |

           Figure 22: Non-confirmable Request; Non-confirmable Response

    Shelby, et al.               Standards Track                  [Page 109]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       In Figure 23, the client sends a Non-confirmable GET request to a
       multicast address: all nodes in link-local scope.  There are 3
       servers on the link: A, B and C.  Servers A and B have a matching
       resource, therefore they send back a Non-confirmable 2.05 (Content)
       response.  The response sent by B is lost.  C does not have matching
       response, therefore it sends a Non-confirmable 4.04 (Not Found)
       response.

       Client  ff02::1  A  B  C
          |       |     |  |  |
          |       |     |  |  |
          +------>|     |  |  |  Header: GET (T=NON, Code=0.01, MID=0x7d41)
          |  GET  |     |  |  |   Token: 0x86
          |             |  |  |   Uri-Path: "temperature"
          |             |  |  |
          |             |  |  |
          |<------------+  |  |  Header: 2.05 (T=NON, Code=2.05, MID=0x60b1)
          |      2.05   |  |  |   Token: 0x86
          |             |  |  |   Payload: "22.3 C"
          |             |  |  |
          |             |  |  |
          |   X------------+  |  Header: 2.05 (T=NON, Code=2.05, MID=0x01a0)
          |      2.05   |  |  |   Token: 0x86
          |             |  |  |   Payload: "20.9 C"
          |             |  |  |
          |             |  |  |
          |<------------------+  Header: 4.04 (T=NON, Code=4.04, MID=0x952a)
          |      4.04   |  |  |   Token: 0x86
          |             |  |  |

          Figure 23: Non-confirmable Request (Multicast); Non-confirmable
                                     Response

    Appendix B.  URI Examples

       The following examples demonstrate different sets of Uri options, and
       the result after constructing an URI from them.  In addition to the
       options, Section 6.5 refers to the destination IP address and port,
       but not all paths of the algorithm cause the destination IP address
       and port to be included in the URI.

       o  Input:

             Destination IP Address = [2001:db8::2:1]
             Destination UDP Port = 5683

    Shelby, et al.               Standards Track                  [Page 110]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

          Output:

             coap://[2001:db8::2:1]/

       o  Input:

             Destination IP Address = [2001:db8::2:1]
             Destination UDP Port = 5683
             Uri-Host = "example.net"

          Output:

             coap://example.net/

       o  Input:

             Destination IP Address = [2001:db8::2:1]
             Destination UDP Port = 5683
             Uri-Host = "example.net"
             Uri-Path = ".well-known"
             Uri-Path = "core"

          Output:

             coap://example.net/.well-known/core

       o  Input:

             Destination IP Address = [2001:db8::2:1]
             Destination UDP Port = 5683
             Uri-Host = "xn--18j4d.example"
             Uri-Path = the string composed of the Unicode characters U+3053
             U+3093 U+306b U+3061 U+306f, usually represented in UTF-8 as
             E38193E38293E381ABE381A1E381AF hexadecimal

          Output:

             coap://xn--18j4d.example/
             %E3%81%93%E3%82%93%E3%81%AB%E3%81%A1%E3%81%AF

             (The line break has been inserted for readability; it is not
             part of the URI.)

    Shelby, et al.               Standards Track                  [Page 111]

    RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

       o  Input:

             Destination IP Address = 198.51.100.1
             Destination UDP Port = 61616
             Uri-Path = ""
             Uri-Path = "/"
             Uri-Path = ""
             Uri-Path = ""
             Uri-Query = "//"
             Uri-Query = "?&"

          Output:

             coap://198.51.100.1:61616//%2F//?%2F%2F&?%26

    Authors' Addresses

       Zach Shelby
       ARM
       150 Rose Orchard
       San Jose, CA  95134
       USA

       Phone: +1-408-203-9434
       EMail: zach.shelby@arm.com

       Klaus Hartke
       Universitaet Bremen TZI
       Postfach 330440
       Bremen  D-28359
       Germany

       Phone: +49-421-218-63905
       EMail: hartke@tzi.org

       Carsten Bormann
       Universitaet Bremen TZI
       Postfach 330440
       Bremen  D-28359
       Germany

       Phone: +49-421-218-63921
       EMail: cabo@tzi.org

    Shelby, et al.               Standards Track                  [Page 112]