RFC 8768

Constrained Application Protocol (CoAP) Hop-Limit Option

📅 published March 2020, from ietf

RFC 8768: Constrained Application Protocol (CoAP) Hop-Limit Option ✨

okay bestie, this one is about stopping CoAP messages from going around in circles forever 🔁💀

  • Stream: Internet Engineering Task Force (IETF) 🌸
  • Request for Comments: 8768
  • Category: Standards Track 👑
  • ISSN: 2070-1721
  • Authors: M. Boucadair (Orange), T. Reddy.K (McAfee), J. Shallow
  • Date: March 2020 📅
  • Obsoletes / Updates: the title block doesn't list anything it obsoletes or updates, so nothing gets replaced or changed here 🙌

Abstract

So, CoAP proxies can end up in infinite forwarding loops, and that is literally not a vibe 😭 To stop those loops from happening and to catch them when they do, this document specifies the Hop-Limit CoAP option 🦋

Status of This Memo

This is an Internet Standards Track document 🎀

This document comes from the IETF. It reflects what the IETF community agreed on, it went through public review, and the Internet Engineering Steering Group (IESG) approved it for publication. If you want more on Internet Standards, check out Section 2 of RFC 7841 🧚

For the latest status of this document, any errata, and where to send feedback, head to https://www.rfc-editor.org/info/rfc8768 💅

Copyright (c) 2020 IETF Trust and the persons identified as the document authors. All rights reserved. 💜

This document is covered by BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents, which are at https://trustee.ietf.org/license-info and apply as of the publication date. Read them closely, because they spell out what you can and can't do with this document 📜 Any Code Components you pull out of this document have to include the Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions. They come with no warranty, as described in the Simplified BSD License ⚖️

Table of Contents

   1.  Introduction
     1.1.  Intended Usage
   2.  Terminology
   3.  Hop-Limit Option
   4.  Debugging and Troubleshooting
   5.  HTTP Mapping Considerations
   6.  IANA Considerations
     6.1.  CoAP Response Code
     6.2.  CoAP Option Number
   7.  Security Considerations
   8.  References
     8.1.  Normative References
     8.2.  Informative References
   Acknowledgements
   Authors' Addresses

1. Introduction 🌷

More and more apps are using the Constrained Application Protocol (CoAP) [RFC7252] to talk between application agents, and it's giving main character energy 💖 For example, [DOTS-SIG-CHANNEL] spells out how CoAP gets used as a signaling protocol between domains that are dealing with distributed denial-of-service (DDoS) attacks and the providers who do DDoS mitigation. In those setups, a CoAP client can talk straight to a server, or it can go through proxies first 🫶

When there are multiple proxies in the mix, infinite forwarding loops can happen (for example, a routing misconfiguration or conflicting policies). To stop those loops, this document defines a brand-new CoAP option called Hop-Limit (Section 3) 🔥 It also defines a new CoAP Response Code (Section 6.1) so loops can be reported along with useful diagnostic info, which makes troubleshooting way less painful (Section 4) ✨

1.1. Intended Usage

The Hop-Limit option was first designed for one specific use case [DOTS-SIG-CHANNEL]. But its intended usage is general, so it's not just for that one scenario 🦋

New CoAP proxies MUST implement this option and have it enabled by default.

Heads up: a server that gets requests both through proxies and straight from clients might see requests that look the same but do or don't include the Hop-Limit option. Servers that do internal caching should also implement this option, since understanding Hop-Limit will boost caching efficiency 📈🍓

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 BCP 14 [RFC2119] [RFC8174], but only when they show up in all capitals, exactly like that 💅

You should be familiar with the terms and concepts defined in [RFC7252] 📚

3. Hop-Limit Option 🎀

The properties of the Hop-Limit option are in Table 1. This table follows the formatting used in Table 4 of [RFC7252] (Section 5.10). The C, U, N, and R columns cover the properties Critical, Unsafe, NoCacheKey, and Repeatable, which are defined in Section 5.4 of [RFC7252]. None of those properties are marked for the Hop-Limit option 🙈

    +--------+---+---+---+---+-----------+--------+--------+---------+
    | Number | C | U | N | R | Name      | Format | Length | Default |
    +========+===+===+===+===+===========+========+========+=========+
    | 16     |   |   |   |   | Hop-Limit | uint   | 1      | 16      |
    +--------+---+---+---+---+-----------+--------+--------+---------+

                Table 1: CoAP Hop-Limit Option Properties

So the Hop-Limit option (Section 6.2) is an elective option that catches and blocks infinite loops of CoAP requests whenever proxies are involved 🔁 It isn't repeatable. That means any request carrying more than one Hop-Limit option MUST be handled using the procedure in Section 5.4.5 of [RFC7252] 💀

The value of Hop-Limit is an unsigned integer (see Section 3.2 of [RFC7252]). It MUST be between 1 and 255 inclusive. Any CoAP request that comes in with a Hop-Limit set to '0' or to something bigger than '255' MUST be rejected by a CoAP server/proxy with 4.00 (Bad Request) ❌

Hop-Limit is safe to forward. A CoAP proxy that doesn't understand it should still forward it on 🫶 The option also counts as part of the cache key, so a proxy that doesn't understand Hop-Limit must follow the caching recommendations in Section 5.7.1 of [RFC7252]. Just know that loops made up only of proxies like that won't get detected. The good news is that having those proxies around won't stop loop detection, as long as at least one CoAP proxy that supports Hop-Limit is part of the loop ✨

A CoAP proxy that understands Hop-Limit SHOULD be told, through a configuration parameter, to insert a Hop-Limit option whenever it relays a request that doesn't already have one 🌈

The initial Hop-Limit value should be configurable. If nobody explicitly gives an initial value, the default initial Hop-Limit value of 16 MUST be used. The reason 16 works: in most cases it's big enough that a request won't get dropped on a network with no loops, but it's not so big that it eats up proxy resources when a loop does happen 🧠 It can still be configured for weird topologies. Lower values should be used carefully, and only in networks where the CoAP client (or the proxy) that inserts the Hop-Limit option knows the topology 👀

Forwarding errors can happen if the Hop-Limit values are too small, so proxies sitting on the edges of an administrative domain MAY be told to remove or rewrite the Hop-Limit value in incoming requests. In other words, they can ignore the Hop-Limit value they received in a request 🧹 This should be done with caution. If proxy-forwarded traffic keeps crossing that domain boundary in a loop, the rewriting can make loop detection through Hop-Limit useless 😬

Otherwise, a CoAP proxy that understands Hop-Limit MUST decrement the option's value by 1 before forwarding it 📉 A CoAP proxy that understands Hop-Limit MUST NOT use a stored 5.08 (Hop Limit Reached) error response unless the Hop-Limit value in the incoming request is smaller than or equal to the Hop-Limit value in the request that was used to get the stored response. If that isn't the case, the CoAP proxy follows the behavior in Section 5.6 of [RFC7252] 🔍

Note: If a request with a given Hop-Limit value failed to reach a server because the hop limit ran out, then the same failure will show up if a smaller Hop-Limit value gets used instead.

CoAP requests MUST NOT be forwarded if the Hop-Limit option is '0' after the decrement 🛑 Requests that can't be forwarded because the Hop-Limit ran out SHOULD be logged, and a 5.08 (Hop Limit Reached) error response SHOULD be sent back to the CoAP peer. It is RECOMMENDED that CoAP implementations offer ways to alert administrators about loop errors, so they can take the right action 🚨

4. Debugging and Troubleshooting 🔧

To make debugging easier, a CoAP proxy that detects a loop puts an identifier for itself in the diagnostic payload, under the conditions described in Section 5.5.2 of [RFC7252] 🕵️‍♀️ That identifier MUST NOT include any space character (ASCII value 32). Some examples are a proxy name (e.g., p11.example.net), a proxy alias (e.g., myproxyalias), or an IP address (e.g., 2001:db8::1) 💜

Each intermediate proxy that helps relay a 5.08 (Hop Limit Reached) error message adds its own identifier to the front of the diagnostic payload, followed by a space as the separator 🧁 Only one identifier per proxy should show up in the diagnostic payload. This keeps the 5.08 (Hop Limit Reached) error message from growing too big, makes it easier to line up with the hop count, and shows whether a given proxy helped forward the 5.08 error message. An intermediate proxy only adds its identifier if there's enough room, as determined by the Path MTU (Section 4.6 of [RFC7252]). If there isn't enough room, the intermediate proxy forwards the 5.08 (Hop Limit Reached) error message to the next hop without changing the diagnostic payload 📦

An intermediate proxy MUST NOT forward a 5.08 (Hop Limit Reached) error message if it finds that its own identifier is already in the diagnostic payload. Messages like that SHOULD be logged, and appropriate alerts SHOULD be sent to the administrators 🚨🫶

5. HTTP Mapping Considerations ✨

okay so this section is all about how HTTP and CoAP talk to each other through proxies, and it's giving very precise bestie energy 💅 The basic must-follow rules for HTTP/CoAP mappings live in Section 10 of [RFC7252] 🎀, and the implementation tips are elaborated in [RFC8075] 🌸.

By default, the HTTP-to-CoAP Proxy inserts a Hop-Limit option following the guidelines in Section 3 🦋 The HTTP-to-CoAP Proxy may be instructed by policy to insert a Hop-Limit option only if a Via (Section 5.7.1 of [RFC7230]) or CDN-Loop header field [RFC8586] is present in the HTTP request. ngl that's a very chill policy option 🫶

The HTTP-to-CoAP Proxy uses 508 (Loop Detected) as the HTTP response status code to map 5.08 (Hop Limit Reached) 💀 Furthermore, it maps the diagnostic payload of 5.08 (Hop Limit Reached) as per Section 6.6 of [RFC8075] ✨

By default, the CoAP-to-HTTP Proxy inserts a Via header field in the HTTP request if the CoAP request includes a Hop-Limit option 🌈 The CoAP-to-HTTP Proxy may be instructed by policy to insert a CDN-Loop header field instead of the Via header field 🍓

The CoAP-to-HTTP Proxy maps the 508 (Loop Detected) HTTP response status code to 5.08 (Hop Limit Reached) 👑 Moreover, the CoAP-to-HTTP Proxy inserts its information following the guidelines in Section 4 💜

When both HTTP-to-CoAP and CoAP-to-HTTP proxies are involved, the loop detection may break if the proxy-forwarded traffic repeatedly crosses the HTTP-to-CoAP and CoAP-to-HTTP proxies. Nevertheless, if the loop is within the CoAP or HTTP legs, the loop detection is still functional 🙈

6. IANA Considerations 🧚

6.1. CoAP Response Code 🌸

IANA has registered the following entry in the "CoAP Response Codes" subregistry available at <https://www.iana.org/assignments/core-parameters>:

             +------+-------------------+-----------+
             | Code | Description       | Reference |
             +======+===================+===========+
             | 5.08 | Hop Limit Reached | RFC 8768  |
             +------+-------------------+-----------+

                   Table 2: CoAP Response Codes

6.2. CoAP Option Number 🦋

IANA has registered the following entry in the "CoAP Option Numbers" subregistry available at <https://www.iana.org/assignments/core-parameters>:

                +--------+-----------+-----------+
                | Number | Name      | Reference |
                +========+===========+===========+
                | 16     | Hop-Limit | RFC 8768  |
                +--------+-----------+-----------+

                   Table 3: CoAP Option Number

7. Security Considerations 🔥

Security considerations related to CoAP proxying are discussed in Section 11.2 of [RFC7252]. Please go read that bit, it's important 😭

A CoAP endpoint can probe the topology of a network into which it is making requests by tweaking the value of the Hop-Limit option 👀 Such probing is likely to fail if proxies at the boundaries of that network rewrite the value of Hop-Limit carried in received requests (see Section 3) 🛡️

The diagnostic payload of a 5.08 (Hop Limit Reached) error message may leak sensitive information revealing the topology of an administrative domain 💀 To prevent that, a CoAP proxy that is located at the boundary of an administrative domain MAY be instructed to strip the diagnostic payload or part of it before forwarding on the 5.08 (Hop Limit Reached) response 🙅‍♀️

8. References 📚

8.1. Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC7230]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
              Protocol (HTTP/1.1): Message Syntax and Routing",
              RFC 7230, DOI 10.17487/RFC7230, June 2014,
              <https://www.rfc-editor.org/info/rfc7230>.

   [RFC7252]  Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
              Application Protocol (CoAP)", RFC 7252,
              DOI 10.17487/RFC7252, June 2014,
              <https://www.rfc-editor.org/info/rfc7252>.

   [RFC8075]  Castellani, A., Loreto, S., Rahman, A., Fossati, T., and
              E. Dijk, "Guidelines for Mapping Implementations: HTTP to
              the Constrained Application Protocol (CoAP)", RFC 8075,
              DOI 10.17487/RFC8075, February 2017,
              <https://www.rfc-editor.org/info/rfc8075>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

8.2. Informative References

   [DOTS-SIG-CHANNEL]
              Reddy, T., Boucadair, M., Patil, P., Mortensen, A., and N.
              Teague, "Distributed Denial-of-Service Open Threat
              Signaling (DOTS) Signal Channel Specification", Work in
              Progress, Internet-Draft, draft-ietf-dots-signal-channel-
              41, 6 January 2020, <https://tools.ietf.org/html/draft-
              ietf-dots-signal-channel-41>.

   [RFC8586]  Ludin, S., Nottingham, M., and N. Sullivan, "Loop
              Detection in Content Delivery Networks (CDNs)", RFC 8586,
              DOI 10.17487/RFC8586, April 2019,
              <https://www.rfc-editor.org/info/rfc8586>.

Acknowledgements 🫶

This specification was part of [DOTS-SIG-CHANNEL]. Many thanks to those who reviewed DOTS specifications 💖

Thanks to Klaus Hartke, Carsten Bormann, Peter van der Stok, Jim Schaad, Jaime Jiménez, Roni Even, Scott Bradner, Thomas Fossati, Radia Perlman, Éric Vyncke, Suresh Krishnan, Roman Danyliw, Barry Leiba, Christer Holmberg, Benjamin Kaduk, and Adam Roach for their review and comments 🌟

Carsten Bormann provided the "Intended Usage" text 🍓

Authors' Addresses 🌈

Mohamed Boucadair
Orange
35000 Rennes
France

Email: mohamed.boucadair@orange.com


Tirumaleswar Reddy.K
McAfee, Inc.
Embassy Golf Link Business Park
Bangalore 560071
Karnataka
India

Email: kondtir@gmail.com


Jon Shallow
United Kingdom

Email: supjps-ietf@jpshallow.com
📦 where this page comes from