From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc8516.txt | 339 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 339 insertions(+) create mode 100644 doc/rfc/rfc8516.txt (limited to 'doc/rfc/rfc8516.txt') diff --git a/doc/rfc/rfc8516.txt b/doc/rfc/rfc8516.txt new file mode 100644 index 0000000..145b138 --- /dev/null +++ b/doc/rfc/rfc8516.txt @@ -0,0 +1,339 @@ + + + + + + +Internet Engineering Task Force (IETF) A. Keranen +Request for Comments: 8516 Ericsson +Category: Standards Track January 2019 +ISSN: 2070-1721 + + + "Too Many Requests" Response Code for + the Constrained Application Protocol + +Abstract + + A Constrained Application Protocol (CoAP) server can experience + temporary overload because one or more clients are sending requests + to the server at a higher rate than the server is capable or willing + to handle. This document defines a new CoAP response code for a + server to indicate that a client should reduce the rate of requests. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 7841. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + https://www.rfc-editor.org/info/rfc8516. + +Copyright Notice + + Copyright (c) 2019 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (https://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + + + + +Keranen Standards Track [Page 1] + +RFC 8516 "Too Many Requests" Response Code for CoAP January 2019 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 + 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 3. CoAP Server Behavior . . . . . . . . . . . . . . . . . . . . 3 + 4. CoAP Client Behavior . . . . . . . . . . . . . . . . . . . . 3 + 5. Security Considerations . . . . . . . . . . . . . . . . . . . 4 + 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4 + 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 5 + 7.1. Normative References . . . . . . . . . . . . . . . . . . 5 + 7.2. Informative References . . . . . . . . . . . . . . . . . 5 + Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 6 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6 + +1. Introduction + + The Constrained Application Protocol (CoAP) [RFC7252] response codes + are used by a CoAP server to indicate the result of an attempt to + understand and satisfy a request sent by a client. + + CoAP response codes are similar to the HTTP [RFC7230] status codes, + and many codes are shared with similar semantics by both CoAP and + HTTP. HTTP has the code "429" registered for "Too Many Requests" + [RFC6585]. This document registers a CoAP response code "4.29" for + similar purposes and uses the Max-Age option (see Section 5.10.5 of + [RFC7252]) to indicate a back-off period after which a client can try + the request again. + + While a server may not be able to respond to one kind of request, it + may be able to respond to a request of a different kind, even from + the same client. Therefore, the back-off period applies only to + similar requests. For the purpose of this response code, a request + is similar if it has the same method and Request-URI. Also, if a + client is sending a sequence of requests that are part of the same + series (e.g., a set of measurements to be processed by the server), + they can be considered similar even if request URIs are different. + Because request similarity is context-dependent, it is up to the + application logic to decide how the similarity of the requests should + be evaluated. + + The 4.29 code is similar to the 5.03 "Service Unavailable" [RFC7252] + code in that the 5.03 code can also be used by a server to signal an + overload situation. The 5.03 code also uses the Max-Age option to + indicate the time after which a client can retry. However, the 4.29 + code indicates that the too-frequent requests from the requesting + client are the reason for the overload. + + + + + +Keranen Standards Track [Page 2] + +RFC 8516 "Too Many Requests" Response Code for CoAP January 2019 + + +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] when, and only when, they appear in all + capitals, as shown here. + + Readers should also be familiar with the terms and concepts discussed + in [RFC7252]. + +3. CoAP Server Behavior + + If a CoAP server is unable to serve a client that is sending CoAP + request messages more often than the server is capable or willing to + handle, the server SHOULD respond to the request(s) with the response + code 4.29, "Too Many Requests". The Max-Age option is used to + indicate the number of seconds after which the server assumes it is + OK for the client to retry the request. + + An action result payload (see Section 5.5.1 of [RFC7252]) can be sent + by the server to give more guidance to the client, e.g., details of + the overload situation. + + The 4.29 response code is only returned to the client(s) sending + requests too frequently; if other clients are sending requests that + cannot be served due to server overload, the 5.03 response code is + more appropriate. + + If a client repeats a request that was answered with 4.29 before + Max-Age time has passed, it is possible that the client sent multiple + requests before receiving the first answer or that the client did not + recognize the response code. To slow down clients that do not + recognize the 4.29 code, the server MAY respond with a more generic + error code (e.g., 5.03). The server SHOULD rate-limit 4.29 replies + taking into account its usual load-shedding policies. However, any + such method that adds per-client state to the server may be + counterproductive to reducing the load. + +4. CoAP Client Behavior + + If a client receives the 4.29 response code from a CoAP server to a + request, it SHOULD NOT send a similar request to the server before + the time indicated in the Max-Age option has passed. If the 4.29 + response does not contain a Max-Age option, the default value (60 + seconds, as defined in Section 5.10.5 of [RFC7252]) is assumed. + + + + + +Keranen Standards Track [Page 3] + +RFC 8516 "Too Many Requests" Response Code for CoAP January 2019 + + + Note that a client may receive a 4.29 response code on a first + request to a server. This can happen, for example, if there is a + proxy on the path and the server replies based on the load from + multiple clients aggregated by the proxy, or if a client has + restarted recently and does not remember its recent requests. + + A client should not rely on a server being able to send the 4.29 + response code in an overload situation because an overloaded server + may not be able to reply at all to some requests. + +5. Security Considerations + + Security considerations of [RFC7252] apply to this response code + also. + + Replying to CoAP requests with a response code consumes resources + from a server. For a server under attack, it may be more appropriate + to simply drop requests without responding at all. However, dropping + requests is also likely to cause well-behaving clients to simply + retry the requests. + + As with any other CoAP reply, a client should trust this response + code only to the extent that it trusts the underlying security + mechanisms (e.g., DTLS [RFC6347]) for authentication and freshness. + If a CoAP reply with the "Too Many Requests" response code is not + authenticated and integrity protected, an attacker can attempt to + spoof a reply and make the client wait for an extended period of time + before trying again. + + If the response code is sent without encryption, it may leak + information about the server overload situation and client traffic + patterns. + +6. IANA Considerations + + IANA has registered the following response code in the "CoAP Response + Codes" subregistry within the "Constrained RESTful Environments + (CoRE) Parameters" registry: + + o Response Code: 4.29 + + o Description: Too Many Requests + + o Reference: RFC 8516 + + IANA has added this document as an additional reference for the + Max-Age option in the "CoAP Option Numbers" subregistry. + + + + +Keranen Standards Track [Page 4] + +RFC 8516 "Too Many Requests" Response Code for CoAP January 2019 + + +7. References + +7.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, + . + + [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained + Application Protocol (CoAP)", RFC 7252, + DOI 10.17487/RFC7252, June 2014, + . + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + +7.2. Informative References + + [CoAP-BROKER] + Koster, M., Keranen, A., and J. Jimenez, "Publish- + Subscribe Broker for the Constrained Application Protocol + (CoAP)", Work in Progress, draft-ietf-core-coap-pubsub-06, + January 2019. + + [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer + Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, + January 2012, . + + [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status + Codes", RFC 6585, DOI 10.17487/RFC6585, April 2012, + . + + [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, + . + + + + + + + + + + + + + +Keranen Standards Track [Page 5] + +RFC 8516 "Too Many Requests" Response Code for CoAP January 2019 + + +Acknowledgements + + This response code definition was originally part of the "Publish- + Subscribe Broker for CoAP" document [CoAP-BROKER]. The author would + like to thank Abhijan Bhattacharyya, Carsten Bormann, Daniel Migault, + Gyorgy Rethy, Jana Iyengar, Jim Schaad, Klaus Hartke, Mohit Sethi, + and Sandor Katona for their contributions and reviews. + +Author's Address + + Ari Keranen + Ericsson + Hirsalantie 11 + 02420 Jorvas + Finland + + Email: ari.keranen@ericsson.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Keranen Standards Track [Page 6] + -- cgit v1.2.3