idnits 2.17.1 draft-boucadair-tcpm-rst-diagnostic-payload-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (19 April 2022) is 735 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'ThisDocument' is mentioned on line 330, but not defined -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-tcpm-rfc793bis' -- Possible downref: Non-RFC (?) normative reference: ref. 'Private-Enterprise-Numbers' Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 tcpm M. Boucadair 3 Internet-Draft Orange 4 Intended status: Standards Track T. Reddy 5 Expires: 21 October 2022 Akamai 6 19 April 2022 8 TCP RST Diagnostic Payload 9 draft-boucadair-tcpm-rst-diagnostic-payload-04 11 Abstract 13 This document specifies a diagnostic payload format to be returned in 14 TCP RST segments. Such payloads are used to share with the endpoints 15 the reasons for which a TCP connection has been reset. This is meant 16 to ease diagnostic and troubleshooting. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at https://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on 21 October 2022. 35 Copyright Notice 37 Copyright (c) 2022 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 42 license-info) in effect on the date of publication of this document. 43 Please review these documents carefully, as they describe your rights 44 and restrictions with respect to this document. Code Components 45 extracted from this document must include Revised BSD License text as 46 described in Section 4.e of the Trust Legal Provisions and are 47 provided without warranty as described in the Revised BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 3. RST Diagnostic Payload . . . . . . . . . . . . . . . . . . . 3 54 4. Some Examples . . . . . . . . . . . . . . . . . . . . . . . . 4 55 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 56 5.1. RST Diagnostic Payload CBOR Key Values . . . . . . . . . 6 57 5.2. New Registry for TCP Failure Causes . . . . . . . . . . . 7 58 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 59 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 60 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 61 8.1. Normative References . . . . . . . . . . . . . . . . . . 9 62 8.2. Informative References . . . . . . . . . . . . . . . . . 10 63 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 65 1. Introduction 67 A TCP connection [I-D.ietf-tcpm-rfc793bis] can be reset by a peer for 68 various reasons, e.g., received data does not correspond to an active 69 connection. Also, a TCP connection can be reset by an on-path 70 service function (e.g., CGN [RFC6888], NAT64 [RFC6146], firewall) for 71 several reasons. Typically, a NAT function can generate an RST 72 segment to notify the peers upon the expiry of the lifetime of the 73 corresponding mapping entry or because an RST segment was received 74 from a peer (Section 2.2 of [RFC7857]). A TCP connection can also be 75 closed by a user or an application at any time. However, the peer 76 that receives an RST segment does not have any hint about the reason 77 that led to terminating the connection. Likewise, the application 78 that relies upon such a TCP connection may not easily identify the 79 reason for a connection closure. Troubleshooting such events at the 80 remote side of the connection that receives the RST segment may not 81 be trivial. 83 This document fills this void by specifying a format of the 84 diagnostic payload that is returned in an RST segment. Returning 85 such data is consistent with the provision in Section 3.5.3 of 86 [I-D.ietf-tcpm-rfc793bis] for RST segments. 88 This document does not change the conditions under which an RST 89 segment is generated (Section 3.5.2 of [I-D.ietf-tcpm-rfc793bis]). 91 The generic procedure for processing an RST segment is specified in 92 Section 3.5.3 of [I-D.ietf-tcpm-rfc793bis]. Only the deviations from 93 that procedure to insert and validate an enclosed diagnostic payload 94 is provided in Section 3. Section 4 provides a set of examples to 95 illustrate the use of TCP RST diagnostic payloads. 97 This document specifies the format and the overall approach to ease 98 maintaining the list of codes while allowing for adding new codes as 99 needed in the future and accommodating any existing vendor-specific 100 codes. An initial version of error codes is available in Table 1. 101 However, the authoritative source to retrieve the full list of error 102 codes is the IANA-maintained registry Section 5.2. 104 2. Terminology 106 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 107 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 108 "OPTIONAL" in this document are to be interpreted as described in BCP 109 14 [RFC2119][RFC8174] when, and only when, they appear in all 110 capitals, as shown here. 112 This document makes use of the terms defined in Section 4 of 113 [I-D.ietf-tcpm-rfc793bis]. 115 3. RST Diagnostic Payload 117 The RST diagnostic payload MUST be encoded using Concise Binary 118 Object Representation (CBOR) Sequence [RFC8742]. The Concise Data 119 Definition Language (CDDL) [RFC8610] for the diagnostic payload is as 120 follows: 122 ; This defines an array, the elements of which are to be used 123 ; in a CBOR Sequence. There is exactly one occurrence. 124 diagnostic-payload = [magic-cookie, reason] 125 ; Magic cookie to identify a payload that follows this specification 126 magic-cookie = 12345 127 ; Reset reason details: 128 reason= { 129 ? reason-code: uint, 130 ? pen:uint, 131 ? reason-description: tstr, 132 } 134 Figure 1: Structure of the RST Diagnostic Payload 136 The RST diagnostic payload comprises a magic cookie that is used to 137 unambiguously identify an RST payload that follows this 138 specification. It MUST be set to the RFC number to be assigned to 139 this document. 141 Note to the RFC Editor: Please replace "12345" with the RFC number 142 assigned to this document. 144 All parameters in the reason component of an RST diagnostic payload 145 are mapped to their CBOR key values as specified in Section 5.1. The 146 description of these parameters is as follows: 148 reason-code: This parameter takes a value from an available registry 149 such as the "TCP Failure Causes" registry (Section 5.2). 151 pen: Includes a Private Enterprise Number 152 [Private-Enterprise-Numbers]. This parameter MAY be included when 153 the reason code is not taken from the IANA-maintained registry 154 (Section 5.2), but from a vendor-specific registry. 156 reason-description: It includes a brief description of the reset 157 reason encoded as UTF-8 [RFC3629]. This parameter SHOULD NOT be 158 included if a reason code is supplied. This parameter is useful 159 only for reset reasons that are not yet registered or for 160 application-specific reasons. 162 At least one of "reason-code" and "reason-description" parameters 163 MUST be included in an RST diagnostic payload. The "pen" parameter 164 MUST be omitted if a reason code from the IANA-maintained registry 165 (Section 5.2) fits the reset case. 167 Malformed RST diagnostic payload messages that include the magic 168 cookie MUST be silently ignored by the receiver. 170 A peer that receives a valid diagnostic payload may pass the reset 171 reason information to the local application in addition to the 172 information (MUST-12) described in Section 3.6 of 173 [I-D.ietf-tcpm-rfc793bis]. That information may also be logged 174 locally, unless a local policy specifies otherwise. How the 175 information is passed to an application and how it is stored locally 176 is implementation specific. 178 4. Some Examples 180 To ease readability, the CBOR diagnostic notation (Section 8 of 181 [RFC8949]) with the parameter names rather than their CBOR key values 182 in Section 5.1 is used in Figures 3, 4, 5, and 6. 184 Figure 2 depicts an example of RST diagnostic payload that is 185 generated to inform the peer that the TCP connection is reset because 186 an ACK was received from that peer while the connection is still in 187 the LISTEN state (Section 3.10.7.2 of [I-D.ietf-tcpm-rfc793bis]). 189 19 3039 # unsigned(12345) 190 A1 # map(1) 191 01 # unsigned(1) 192 02 # unsigned(2) 194 Figure 2: An RST Diagnostic Payload with Reason Code (CBOR Encoding) 196 Figure 3 depicts the same RST diagnostic payload as the one shown in 197 Figure 2 but following the diagnostic notation. 199 [ 200 12345, 201 { 202 "reason-code": 2 203 } 204 ] 206 Figure 3: An RST Diagnostic Payload with Reason Code (Diagnostic 207 Notation) 209 Figure 4 shows an example of an RST diagnostic payload that includes 210 a free description to report a case that is not covered yet by the 211 IANA-maintained registry (Section 5.2). 213 [ 214 12345, 215 { 216 "reason-description": "brief human-readable description" 217 } 218 ] 220 Figure 4: An RST Diagnostic Payload with Reason Description 221 (Diagnostic Notation) 223 An RST diagnostic payload may also be sent by an on-path service 224 function. For example, the following diagnostic payload is returned 225 by a NAT upon expiry of the mapping entry to which the TCP connection 226 is bound (Figure 5). 228 [ 229 12345, 230 { 231 "reason-code": 8 232 } 233 ] 235 Figure 5: An RST Diagnostic Payload to Report Connection Timeout 236 (Diagnostic Notation) 238 Figure 6 illustrates the RST diagnostic payload that is returned by a 239 peer that resets a TCP connection for a reason code 1234 defined by a 240 vendor with the private enterprise number 32473. 242 [ 243 12345, 244 { 245 "reason-code": 1234, 246 "pen": 32473 247 } 248 ] 250 Figure 6: An RST Diagnostic Payload to Report Vendor-Specific 251 Reason Code (Diagnostic Notation) 253 Figure 6 uses the Enterprise Number 32473 defined for documentation 254 use [RFC5612]. 256 5. IANA Considerations 258 5.1. RST Diagnostic Payload CBOR Key Values 260 IANA is requested to create a new subregistry titled "RST Diagnostic 261 Payload CBOR Key Values" under the "Transmission Control Protocol 262 (TCP) Parameters" registry [IANA-TCP]. 264 The structure of this subregistry and the initial values are provided 265 below: 267 +--------------------+------+---------------+--------------+ 268 | Parameter Name | CBOR | CBOR Major | Reference | 269 | | Key | Type & | | 270 | | | Information | | 271 +====================+======+===============+==============+ 272 | reason-code | 1 | 0 unsigned |[ThisDocument]| 273 | pen | 2 | 0 unsigned |[ThisDocument]| 274 | reason-description | 3 | 3 text string |[ThisDocument]| 275 +====================+======+===============+==============+ 277 The key value MUST be an integer in the 1-255 range. 279 The assignment policy for this registry is "IETF Review" (Section 4.8 280 of [RFC8126]). 282 5.2. New Registry for TCP Failure Causes 284 This document requests IANA to create a new subregistry entitled "TCP 285 Failure Causes" under the "Transmission Control Protocol (TCP) 286 Parameters" registry [IANA-TCP]. 288 Values are taken from the 1-65535 range. 290 The assignment policy for this registry is "Expert Review" 291 (Section 4.5 of [RFC8126]). 293 The designated experts may approve registration once they checked 294 that the new requested code is not covered by an existing code and if 295 the provided reasoning to register the new code is acceptable. A 296 registration request may supply a pointer to a specification where 297 that code is defined. However, a registration may be accepted even 298 if no permanent and readily available public specification is 299 available. 301 The registry is initially populated with the following values: 303 +=======+========================+==============================+ 304 | Value | Description | Specification (if available) | 305 +=======+========================+==============================+ 306 | 1 | New data is received | Sections 3.6.1 and 3.10.7.1 | 307 | | after CLOSE is called | of [I-D.ietf-tcpm-rfc793bis] | 308 +-------+------------------------+------------------------------+ 309 | 2 | Received ACK while the | Section 3.10.7.2 of | 310 | | connection is still in | [I-D.ietf-tcpm-rfc793bis] | 311 | | the LISTEN state | | 312 +-------+------------------------+------------------------------+ 313 | 3 | Illegal Option | Section 3.1 of | 314 | | | [I-D.ietf-tcpm-rfc793bis] | 315 +-------+------------------------+------------------------------+ 316 | 4 | Malformed Message | [ThisDocument] | 317 +-------+------------------------+------------------------------+ 318 | 5 | Not Authorized | [ThisDocument] | 319 +-------+------------------------+------------------------------+ 320 | 6 | Resource Exceeded | [ThisDocument] | 321 +-------+------------------------+------------------------------+ 322 | 7 | Network Failure | [ThisDocument] | 323 +-------+------------------------+------------------------------+ 324 | 8 | Reset received from | [ThisDocument] | 325 | | the peer | | 326 +-------+------------------------+------------------------------+ 327 | 9 | Destination | [ThisDocument] | 328 | | Unreachable | | 329 +-------+------------------------+------------------------------+ 330 | 10 | Connection Timeout. | [ThisDocument] | 331 +-------+------------------------+------------------------------+ 332 | 11 | Too much outstanding | Section 3.6 of [RFC8684] | 333 | | data | | 334 +-------+------------------------+------------------------------+ 335 | 12 | Unacceptable | Section 3.6 of [RFC8684] | 336 | | performance | | 337 +-------+------------------------+------------------------------+ 338 | 12 | Middlebox interference | Section 3.6 of [RFC8684] | 339 +-------+------------------------+------------------------------+ 341 Table 1: Initial TCP Failure Causes 343 Note that codes 6-10 can be used by service functions such as 344 translators. 346 6. Security Considerations 348 [I-D.ietf-tcpm-rfc793bis] discusses TCP-related security 349 considerations. RST-specific attacks and their mitigations are 350 discussed in Section 3.10.7.3 of [I-D.ietf-tcpm-rfc793bis]. 352 In addition to these considerations, it is RECOMMENDED to control the 353 size of acceptable diagnostic payload and keep it as brief as 354 possible. The RECOMMENDED acceptable maximum size of the RST 355 diagnostic payload is 255 octets. 357 Also, it is RECOMMENDED to avoid leaking privacy-related information 358 as part of the diagnostic payload (e.g., including a description such 359 as "user X resets explicitly the connection" is not recommended). 360 The "reason-description" string, when present, should not include any 361 private information that an observer would not otherwise have access 362 to. 364 The presence of vendor-specific reason codes (Section 3) may be used 365 to fingerprint hosts. Such a concern does not apply if the reason 366 codes are taken from the IANA-maintained registry. Implementers are, 367 thus, encouraged to register new codes within IANA instead of 368 maintaining specific registries. 370 The reason description, when present, is not intended to be displayed 371 to end users, but to be consumed by applications. Such a description 372 may carry a malicious message to mislead the end-user. 374 7. Acknowledgements 376 The "diagnostic payload" name is inspired by Section 5.5.2 of 377 [RFC7252] that was cited by Carsten Bormann in the tcpm mailing list. 379 Thanks to Jon Shallow for the comments. 381 8. References 383 8.1. Normative References 385 [I-D.ietf-tcpm-rfc793bis] 386 Eddy, W. M., "Transmission Control Protocol (TCP) 387 Specification", Work in Progress, Internet-Draft, draft- 388 ietf-tcpm-rfc793bis-28, 7 March 2022, 389 . 392 [Private-Enterprise-Numbers] 393 "Private Enterprise Numbers", 4 May 2020, 394 . 396 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 397 Requirement Levels", BCP 14, RFC 2119, 398 DOI 10.17487/RFC2119, March 1997, 399 . 401 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 402 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 403 2003, . 405 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 406 Writing an IANA Considerations Section in RFCs", BCP 26, 407 RFC 8126, DOI 10.17487/RFC8126, June 2017, 408 . 410 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 411 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 412 May 2017, . 414 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 415 Definition Language (CDDL): A Notational Convention to 416 Express Concise Binary Object Representation (CBOR) and 417 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 418 June 2019, . 420 [RFC8684] Ford, A., Raiciu, C., Handley, M., Bonaventure, O., and C. 421 Paasch, "TCP Extensions for Multipath Operation with 422 Multiple Addresses", RFC 8684, DOI 10.17487/RFC8684, March 423 2020, . 425 [RFC8742] Bormann, C., "Concise Binary Object Representation (CBOR) 426 Sequences", RFC 8742, DOI 10.17487/RFC8742, February 2020, 427 . 429 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 430 Representation (CBOR)", STD 94, RFC 8949, 431 DOI 10.17487/RFC8949, December 2020, 432 . 434 8.2. Informative References 436 [IANA-TCP] IANA YANG, "Transmission Control Protocol (TCP) 437 Parameters", 438 . 441 [RFC5612] Eronen, P. and D. Harrington, "Enterprise Number for 442 Documentation Use", RFC 5612, DOI 10.17487/RFC5612, August 443 2009, . 445 [RFC6146] Bagnulo, M., Matthews, P., and I. van Beijnum, "Stateful 446 NAT64: Network Address and Protocol Translation from IPv6 447 Clients to IPv4 Servers", RFC 6146, DOI 10.17487/RFC6146, 448 April 2011, . 450 [RFC6888] Perreault, S., Ed., Yamagata, I., Miyakawa, S., Nakagawa, 451 A., and H. Ashida, "Common Requirements for Carrier-Grade 452 NATs (CGNs)", BCP 127, RFC 6888, DOI 10.17487/RFC6888, 453 April 2013, . 455 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 456 Application Protocol (CoAP)", RFC 7252, 457 DOI 10.17487/RFC7252, June 2014, 458 . 460 [RFC7857] Penno, R., Perreault, S., Boucadair, M., Ed., Sivakumar, 461 S., and K. Naito, "Updates to Network Address Translation 462 (NAT) Behavioral Requirements", BCP 127, RFC 7857, 463 DOI 10.17487/RFC7857, April 2016, 464 . 466 Authors' Addresses 468 Mohamed Boucadair 469 Orange 470 35000 Rennes 471 France 472 Email: mohamed.boucadair@orange.com 474 Tirumaleswar Reddy 475 Akamai 476 Embassy Golf Link Business Park 477 Bangalore 560071 478 Karnataka 479 India 480 Email: kondtir@gmail.com