idnits 2.17.1 draft-ietf-dots-rfc8782-bis-08.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 2758 has weird spacing: '...er-port ine...' == Line 2781 has weird spacing: '...er-port ine...' == Line 2788 has weird spacing: '...cl-name lea...' -- The document date (June 3, 2021) is 1057 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: 'RFCXXXX' is mentioned on line 4710, but not defined ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) ** Downref: Normative reference to an Informational RFC: RFC 7918 == Outdated reference: A later version (-17) exists of draft-ietf-core-comi-11 == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-15 == Outdated reference: A later version (-13) exists of draft-ietf-dots-multihoming-05 == Outdated reference: A later version (-25) exists of draft-ietf-dots-telemetry-15 -- Obsolete informational reference (is this intentional?): RFC 4960 (Obsoleted by RFC 9260) -- Obsolete informational reference (is this intentional?): RFC 8499 (Obsoleted by RFC 9499) -- Obsolete informational reference (is this intentional?): RFC 8782 (Obsoleted by RFC 9132) Summary: 5 errors (**), 0 flaws (~~), 9 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 DOTS M. Boucadair, Ed. 3 Internet-Draft Orange 4 Obsoletes: 8782 (if approved) J. Shallow 5 Intended status: Standards Track 6 Expires: December 5, 2021 T. Reddy.K 7 McAfee 8 June 3, 2021 10 Distributed Denial-of-Service Open Threat Signaling (DOTS) Signal 11 Channel Specification 12 draft-ietf-dots-rfc8782-bis-08 14 Abstract 16 This document specifies the Distributed Denial-of-Service Open Threat 17 Signaling (DOTS) signal channel, a protocol for signaling the need 18 for protection against Distributed Denial-of-Service (DDoS) attacks 19 to a server capable of enabling network traffic mitigation on behalf 20 of the requesting client. 22 A companion document defines the DOTS data channel, a separate 23 reliable communication layer for DOTS management and configuration 24 purposes. 26 This document obsoletes RFC 8782. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on December 5, 2021. 45 Copyright Notice 47 Copyright (c) 2021 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (https://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 63 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 3. Design Overview . . . . . . . . . . . . . . . . . . . . . . . 6 65 3.1. Backward Compatibility Considerations . . . . . . . . . . 9 66 4. DOTS Signal Channel: Messages & Behaviors . . . . . . . . . . 10 67 4.1. DOTS Server(s) Discovery . . . . . . . . . . . . . . . . 10 68 4.2. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . 10 69 4.3. Happy Eyeballs for DOTS Signal Channel . . . . . . . . . 11 70 4.4. DOTS Mitigation Methods . . . . . . . . . . . . . . . . . 13 71 4.4.1. Request Mitigation . . . . . . . . . . . . . . . . . 14 72 4.4.1.1. Building Mitigation Requests . . . . . . . . . . 14 73 4.4.1.2. Server-domain DOTS Gateways . . . . . . . . . . . 22 74 4.4.1.3. Processing Mitigation Requests . . . . . . . . . 24 75 4.4.2. Retrieve Information Related to a Mitigation . . . . 30 76 4.4.2.1. DOTS Servers Sending Mitigation Status . . . . . 36 77 4.4.2.2. DOTS Clients Polling for Mitigation Status . . . 38 78 4.4.3. Efficacy Update from DOTS Clients . . . . . . . . . . 39 79 4.4.4. Withdraw a Mitigation . . . . . . . . . . . . . . . . 41 80 4.5. DOTS Signal Channel Session Configuration . . . . . . . . 42 81 4.5.1. Discover Configuration Parameters . . . . . . . . . . 44 82 4.5.2. Convey DOTS Signal Channel Session Configuration . . 48 83 4.5.3. Configuration Freshness and Notifications . . . . . . 54 84 4.5.4. Delete DOTS Signal Channel Session Configuration . . 55 85 4.6. Redirected Signaling . . . . . . . . . . . . . . . . . . 56 86 4.7. Heartbeat Mechanism . . . . . . . . . . . . . . . . . . . 58 87 5. DOTS Signal Channel YANG Modules . . . . . . . . . . . . . . 61 88 5.1. Tree Structure . . . . . . . . . . . . . . . . . . . . . 61 89 5.2. IANA DOTS Signal Channel YANG Module . . . . . . . . . . 64 90 5.3. IETF DOTS Signal Channel YANG Module . . . . . . . . . . 68 91 6. YANG/JSON Mapping Parameters to CBOR . . . . . . . . . . . . 81 92 7. (D)TLS Protocol Profile and Performance Considerations . . . 85 93 7.1. (D)TLS Protocol Profile . . . . . . . . . . . . . . . . . 85 94 7.2. (D)TLS 1.3 Considerations . . . . . . . . . . . . . . . . 87 95 7.3. DTLS MTU and Fragmentation . . . . . . . . . . . . . . . 89 96 8. Mutual Authentication of DOTS Agents & Authorization of DOTS 97 Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 98 9. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 91 99 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 92 100 10.1. DOTS Signal Channel UDP and TCP Port Number . . . . . . 92 101 10.2. Well-Known 'dots' URI . . . . . . . . . . . . . . . . . 93 102 10.3. Media Type Registration . . . . . . . . . . . . . . . . 93 103 10.4. CoAP Content-Formats Registration . . . . . . . . . . . 94 104 10.5. CBOR Tag Registration . . . . . . . . . . . . . . . . . 95 105 10.6. DOTS Signal Channel Protocol Registry . . . . . . . . . 95 106 10.6.1. DOTS Signal Channel CBOR Key Values Subregistry . . 95 107 10.6.1.1. Registration Template . . . . . . . . . . . . . 95 108 10.6.1.2. Update Subregistry Content . . . . . . . . . . . 97 109 10.6.2. Status Codes Subregistry . . . . . . . . . . . . . . 97 110 10.6.3. Conflict Status Codes Subregistry . . . . . . . . . 99 111 10.6.4. Conflict Cause Codes Subregistry . . . . . . . . . . 100 112 10.6.5. Attack Status Codes Subregistry . . . . . . . . . . 101 113 10.7. DOTS Signal Channel YANG Modules . . . . . . . . . . . . 102 114 11. Security Considerations . . . . . . . . . . . . . . . . . . . 104 115 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 106 116 12.1. Normative References . . . . . . . . . . . . . . . . . . 106 117 12.2. Informative References . . . . . . . . . . . . . . . . . 109 118 Appendix A. Summary of Changes From RFC8782 . . . . . . . . . . 114 119 Appendix B. CUID Generation . . . . . . . . . . . . . . . . . . 115 120 Appendix C. Summary of Protocol Recommended/Default Values . . . 115 121 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 116 122 D.1. Acknowledgements from RFC8782 . . . . . . . . . . . . . . 116 123 Appendix E. Contributors . . . . . . . . . . . . . . . . . . . . 116 124 E.1. Authors of RFC8782 . . . . . . . . . . . . . . . . . . . 116 125 E.2. Contributors to RFC8782 . . . . . . . . . . . . . . . . . 117 126 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 118 128 1. Introduction 130 A Distributed Denial-of-Service (DDoS) attack is a distributed 131 attempt to make machines or network resources unavailable to their 132 intended users. In most cases, sufficient scale for an effective 133 attack can be achieved by compromising enough end hosts and using 134 those infected hosts to perpetrate and amplify the attack. The 135 victim in this attack can be an application server, a host, a router, 136 a firewall, or an entire network. 138 Network applications have finite resources like CPU cycles, the 139 number of processes or threads they can create and use, the maximum 140 number of simultaneous connections they can handle, the resources 141 assigned to the control plane, etc. When processing network traffic, 142 such applications are supposed to use these resources to provide the 143 intended functionality in the most efficient manner. However, a DDoS 144 attacker may be able to prevent an application from performing its 145 intended task by making the application exhaust its finite resources. 147 A TCP DDoS SYN flood [RFC4987], for example, is a memory-exhausting 148 attack while an ACK flood is a CPU-exhausting attack. Attacks on the 149 link are carried out by sending enough traffic so that the link 150 becomes congested, thereby likely causing packet loss for legitimate 151 traffic. Stateful firewalls can also be attacked by sending traffic 152 that causes the firewall to maintain an excessive number of states 153 that may jeopardize the firewall's operation overall, in addition to 154 likely performance impacts. The firewall then runs out of memory, 155 and it can no longer instantiate the states required to process 156 legitimate flows. Other possible DDoS attacks are discussed in 157 [RFC4732]. 159 In many cases, it may not be possible for network administrators to 160 determine the cause(s) of an attack. They may instead just realize 161 that certain resources seem to be under attack. This document 162 defines a lightweight protocol that allows a DOTS client to request 163 mitigation from one or more DOTS servers for protection against 164 detected, suspected, or anticipated attacks. This protocol enables 165 cooperation between DOTS agents to permit a highly automated network 166 defense that is robust, reliable, and secure. Note that "secure" 167 means the support of the features defined in Section 2.4 of 168 [RFC8612]. 170 In typical deployments, the DOTS client belongs to a different 171 administrative domain than the DOTS server. For example, the DOTS 172 client is embedded in a firewall protected services owned and 173 operated by a customer, while the DOTS server is owned and operated 174 by a different administrative entity (service provider, typically) 175 providing DDoS mitigation services. The latter might or might not 176 provide connectivity services to the network hosting the DOTS client. 178 The DOTS server may or may not be co-located with the DOTS mitigator. 179 In typical deployments, the DOTS server belongs to the same 180 administrative domain as the mitigator. The DOTS client can 181 communicate directly with a DOTS server or indirectly via a DOTS 182 gateway. 184 An example of a network diagram that illustrates a deployment of DOTS 185 agents is shown in Figure 1. In this example, a DOTS server is 186 operating on the access network. A DOTS client is located on the LAN 187 (Local Area Network), while a DOTS gateway is embedded in the CPE 188 (Customer Premises Equipment). 190 Network 191 Resource CPE Router Access Network __________ 192 +-------------+ +--------------+ +-------------+ / \ 193 | | | | | | | Internet | 194 | DOTS Client +---+ DOTS Gateway +---+ DOTS Server +----+ | 195 | | | | | | | | 196 +-------------+ +--------------+ +-------------+ \__________/ 198 Figure 1: Sample DOTS Deployment (1) 200 DOTS servers can also be reachable over the Internet, as depicted in 201 Figure 2. 203 Network DDoS Mitigation 204 Resource CPE Router _________ Service 205 +-------------+ +--------------+ / \ +-------------+ 206 | | | | | | | | 207 | DOTS Client +---+ DOTS Gateway +---+ Internet +---+ DOTS Server | 208 | | | | | | | | 209 +-------------+ +--------------+ \_________/ +-------------+ 211 Figure 2: Sample DOTS Deployment (2) 213 This document adheres to the DOTS architecture [RFC8811]. The 214 requirements for DOTS signal channel protocol are documented in 215 [RFC8612]. This document satisfies all the use cases discussed in 216 [RFC8903]. 218 This document focuses on the DOTS signal channel. This is a 219 companion document of the DOTS data channel specification [RFC8783] 220 that defines a configuration and a bulk data exchange mechanism 221 supporting the DOTS signal channel. 223 Backward compatibility (including upgrade) considerations are 224 discussed in Section 3.1. 226 2. Terminology 228 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 229 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 230 "OPTIONAL" in this document are to be interpreted as described in BCP 231 14 [RFC2119][RFC8174] when, and only when, they appear in all 232 capitals, as shown here. 234 (D)TLS is used for statements that apply to both Transport Layer 235 Security [RFC5246] [RFC8446] and Datagram Transport Layer Security 236 [RFC6347]. Specific terms are used for any statement that applies to 237 either protocol alone. 239 The reader should be familiar with the terms defined in [RFC8612] and 240 [RFC7252]. 242 The meaning of the symbols in YANG tree diagrams are defined in 243 [RFC8340] and [RFC8791]. 245 3. Design Overview 247 The DOTS signal channel is built on top of the Constrained 248 Application Protocol (CoAP) [RFC7252], a lightweight protocol 249 originally designed for constrained devices and networks. The many 250 features of CoAP (expectation of packet loss, support for 251 asynchronous Non-confirmable messaging, congestion control, small 252 message overhead limiting the need for fragmentation, use of minimal 253 resources, and support for (D)TLS) make it a good candidate upon 254 which to build the DOTS signaling mechanism. 256 DOTS clients and servers behave as CoAP endpoints. By default, a 257 DOTS client behaves as a CoAP client and a DOTS server behaves as 258 CoAP server. Nevertheless, a DOTS client (or server) behaves as a 259 CoAP server (or client) for specific operations such as DOTS 260 heartbeat operations (Section 4.7). 262 The DOTS signal channel is layered on existing standards (see 263 Figure 3). 265 +---------------------+ 266 | DOTS Signal Channel | 267 +---------------------+ 268 | CoAP | 269 +----------+----------+ 270 | TLS | DTLS | 271 +----------+----------+ 272 | TCP | UDP | 273 +----------+----------+ 274 | IP | 275 +---------------------+ 277 Figure 3: Abstract Layering of DOTS Signal Channel over CoAP over 278 (D)TLS 280 In some cases, a DOTS client and server may have a mutual agreement 281 to use a specific port number, such as by explicit configuration or 282 dynamic discovery [RFC8973]. Absent such mutual agreement, the DOTS 283 signal channel MUST run over port number 4646 as defined in 284 Section 10.1, for both UDP and TCP (that is, the DOTS server listens 285 on port number 4646). In order to use a distinct port number (as 286 opposed to 4646), DOTS clients and servers SHOULD support a 287 configurable parameter to supply the port number to use. 289 | Note: The rationale for not using the default port number 5684 290 | ((D)TLS CoAP) is to avoid the discovery of services and 291 | resources discussed in [RFC7252] and allow for differentiated 292 | behaviors in environments where both a DOTS gateway and an 293 | Internet of Things (IoT) gateway (e.g., Figure 3 of [RFC7452]) 294 | are co-located. 295 | 296 | Particularly, the use of a default port number is meant to 297 | simplify DOTS deployment in scenarios where no explicit IP 298 | address configuration is required. For example, the use of the 299 | default router as the DOTS server aims to ease DOTS deployment 300 | within LANs (in which CPEs embed a DOTS gateway as illustrated 301 | in Figures 1 and 2) without requiring a sophisticated discovery 302 | method and configuration tasks within the LAN. It is also 303 | possible to use anycast addresses for DOTS servers to simplify 304 | DOTS client configuration, including service discovery. In 305 | such an anycast-based scenario, a DOTS client initiating a DOTS 306 | session to the DOTS server anycast address may, for example, be 307 | (1) redirected to the DOTS server unicast address to be used by 308 | the DOTS client following the procedure discussed in 309 | Section 4.6 or (2) relayed to a unicast DOTS server. 311 The signal channel uses the "coaps" URI scheme defined in Section 6 312 of [RFC7252] and the "coaps+tcp" URI scheme defined in Section 8.2 of 313 [RFC8323] to identify DOTS server resources that are accessible using 314 CoAP over UDP secured with DTLS and CoAP over TCP secured with TLS, 315 respectively. 317 The DOTS signal channel can be established between two DOTS agents 318 prior to or during an attack. The DOTS signal channel is initiated 319 by the DOTS client. The DOTS client can then negotiate, configure, 320 and retrieve the DOTS signal channel session behavior with its DOTS 321 peer (Section 4.5). Once the signal channel is established, the DOTS 322 agents may periodically send heartbeats to keep the channel active 323 (Section 4.7). At any time, the DOTS client may send a mitigation 324 request message (Section 4.4) to a DOTS server over the active signal 325 channel. While mitigation is active (because of the higher 326 likelihood of packet loss during a DDoS attack), the DOTS server 327 periodically sends status messages to the client, including basic 328 mitigation feedback details. Mitigation remains active until the 329 DOTS client explicitly terminates mitigation or the mitigation 330 lifetime expires. Also, the DOTS server may rely on the signal 331 channel session loss to trigger mitigation for preconfigured 332 mitigation requests (if any). 334 DOTS signaling can use DTLS over UDP and TLS over TCP. Likewise, 335 DOTS requests may be sent using IPv4 or IPv6 transfer capabilities. 336 A Happy Eyeballs procedure for the DOTS signal channel is specified 337 in Section 4.3. 339 A DOTS client is entitled to access only the resources it creates. 340 In particular, a DOTS client cannot retrieve data related to 341 mitigation requests created by other DOTS clients of the same DOTS 342 client domain. 344 Messages exchanged between DOTS agents are serialized using Concise 345 Binary Object Representation (CBOR) [RFC8949], a binary encoding 346 scheme designed for small code and message size. CBOR-encoded 347 payloads are used to carry signal channel-specific payload messages 348 that convey request parameters and response information such as 349 errors. In order to allow the reusing of data models across 350 protocols, [RFC7951] specifies the JavaScript Object Notation (JSON) 351 encoding of YANG-modeled data. A similar effort for CBOR is defined 352 in [I-D.ietf-core-yang-cbor]. 354 DOTS agents determine that a CBOR data structure is a DOTS signal 355 channel object from the application context, such as from the port 356 number assigned to the DOTS signal channel. The other method DOTS 357 agents use to indicate that a CBOR data structure is a DOTS signal 358 channel object is the use of the "application/dots+cbor" content type 359 (Section 10.3). 361 This document specifies a YANG module for representing DOTS 362 mitigation scopes, DOTS signal channel session configuration data, 363 and DOTS redirected signaling (Section 5). All parameters in the 364 payload of the DOTS signal channel are mapped to CBOR types as 365 specified in Table 5 (Section 6). 367 In order to prevent fragmentation, DOTS agents must follow the 368 recommendations documented in Section 4.6 of [RFC7252]. Refer to 369 Section 7.3 for more details. 371 DOTS agents MUST support GET, PUT, and DELETE CoAP methods. The 372 payload included in CoAP responses with 2.xx Response Codes MUST be 373 of content type "application/dots+cbor". CoAP responses with 4.xx 374 and 5.xx error Response Codes MUST include a diagnostic payload 375 (Section 5.5.2 of [RFC7252]). The diagnostic payload may contain 376 additional information to aid troubleshooting. 378 In deployments where multiple DOTS clients are enabled in a single 379 network and administrative domain (called, DOTS client domain), the 380 DOTS server may detect conflicting mitigation requests from these 381 clients. This document does not aim to specify a comprehensive list 382 of conditions under which a DOTS server will characterize two 383 mitigation requests from distinct DOTS clients as conflicting, nor 384 does it recommend a DOTS server behavior for processing conflicting 385 mitigation requests. Those considerations are implementation and 386 deployment specific. Nevertheless, this document specifies the 387 mechanisms to notify DOTS clients when conflicts occur, including the 388 conflict cause (Section 4.4). 390 In deployments where one or more translators (e.g., Traditional NAT 391 [RFC3022], CGN [RFC6888], NAT64 [RFC6146], NPTv6 [RFC6296]) are 392 enabled between the client's network and the DOTS server, any DOTS 393 signal channel messages forwarded to a DOTS server MUST NOT include 394 internal IP addresses/prefixes and/or port numbers; instead, external 395 addresses/prefixes and/or port numbers as assigned by the translator 396 MUST be used. This document does not make any recommendations about 397 possible translator discovery mechanisms. The following are some 398 (non-exhaustive) deployment examples that may be considered: 400 o Port Control Protocol (PCP) [RFC6887] or Session Traversal 401 Utilities for NAT (STUN) [RFC8489] may be used by the client to 402 retrieve the external addresses/prefixes and/or port numbers. 403 Information retrieved by means of PCP or STUN will be used to feed 404 the DOTS signal channel messages that will be sent to a DOTS 405 server. 407 o A DOTS gateway may be co-located with the translator. The DOTS 408 gateway will need to update the DOTS messages based upon the local 409 translator's binding table. 411 3.1. Backward Compatibility Considerations 413 The main changes to [RFC8782] are listed in Appendix A. These 414 modifications are made with the constraint to avoid changes to the 415 mapping table defined in Table 5 of [RFC8782] (see also Section 6 of 416 the present document). 418 For both legacy [RFC8782] and implementations that follow the present 419 specification, a DOTS signal channel attribute will thus have the 420 same CBOR key value and CBOR major type. The only upgrade that is 421 required to [RFC8782] implementations is to handle the CBOR key value 422 range "128-255" as comprehension-optional instead of comprehension- 423 required. Note that this range is anticipated to be used by the DOTS 424 telemetry [I-D.ietf-dots-telemetry] in which the following means are 425 used to prevent message processing failure of a DOTS signal channel 426 message enriched with telemetry data: (1) DOTS agents use dedicated 427 (new) path suffixes (Section 5 of [I-D.ietf-dots-telemetry]) and (2) 428 a DOTS server won't include telemetry attributes in its responses 429 unless it is explicitly told to do so by a DOTS client (Section 6.1.2 430 of [I-D.ietf-dots-telemetry]). 432 Future DOTS extensions that request a CBOR value in the range 433 "128-255" MUST support means similar to the aforementioned DOTS 434 telemetry ones. 436 4. DOTS Signal Channel: Messages & Behaviors 438 4.1. DOTS Server(s) Discovery 440 This document assumes that DOTS clients are provisioned with the 441 reachability information of their DOTS server(s) using any of a 442 variety of means (e.g., local configuration or dynamic means such as 443 DHCP [RFC8973]). The description of such means is out of scope of 444 this document. 446 Likewise, it is out of the scope of this document to specify the 447 behavior to be followed by a DOTS client in order to send DOTS 448 requests when multiple DOTS servers are provisioned (e.g., contact 449 all DOTS servers, select one DOTS server among the list). Such 450 behavior is specified in other documents (e.g., 451 [I-D.ietf-dots-multihoming]). 453 4.2. CoAP URIs 455 The DOTS server MUST support the use of the path prefix of "/.well- 456 known/" as defined in [RFC8615] and the registered name of "dots". 457 Each DOTS operation is denoted by a path suffix that indicates the 458 intended operation. The operation path (Table 1) is appended to the 459 path prefix to form the URI used with a CoAP request to perform the 460 desired DOTS operation. 462 +-----------------------+----------------+-------------+ 463 | Operation | Operation Path | Details | 464 +=======================+================+=============+ 465 | Mitigation | /mitigate | Section 4.4 | 466 +-----------------------+----------------+-------------+ 467 | Session configuration | /config | Section 4.5 | 468 +-----------------------+----------------+-------------+ 469 | Heartbeat | /hb | Section 4.7 | 470 +-----------------------+----------------+-------------+ 472 Table 1: Operations and Corresponding URIs 474 4.3. Happy Eyeballs for DOTS Signal Channel 476 [RFC8612] mentions that DOTS agents will have to support both 477 connectionless and connection-oriented protocols. As such, the DOTS 478 signal channel is designed to operate with DTLS over UDP and TLS over 479 TCP. Further, a DOTS client may acquire a list of IPv4 and IPv6 480 addresses (Section 4.1), each of which can be used to contact the 481 DOTS server using UDP and TCP. If no list of IPv4 and IPv6 addresses 482 to contact the DOTS server is configured (or discovered), the DOTS 483 client adds the IPv4/IPv6 addresses of its default router to the 484 candidate list to contact the DOTS server. 486 The following specifies the procedure to follow to select the address 487 family and the transport protocol for sending DOTS signal channel 488 messages. 490 Such a procedure is needed to avoid experiencing long connection 491 delays. For example, if an IPv4 path to a DOTS server is functional, 492 but the DOTS server's IPv6 path is nonfunctional, a dual-stack DOTS 493 client may experience a significant connection delay compared to an 494 IPv4-only DOTS client in the same network conditions. The other 495 problem is that if a middlebox between the DOTS client and DOTS 496 server is configured to block UDP traffic, the DOTS client will fail 497 to establish a DTLS association with the DOTS server; consequently, 498 it will have to fall back to TLS over TCP, thereby incurring 499 significant connection delays. 501 To overcome these connection setup problems, the DOTS client attempts 502 to connect to its DOTS server(s) using both IPv6 and IPv4, and it 503 tries both DTLS over UDP and TLS over TCP following a DOTS Happy 504 Eyeballs approach. To some extent, this approach is similar to the 505 Happy Eyeballs mechanism defined in [RFC8305]. The connection 506 attempts are performed by the DOTS client when it initializes or, in 507 general, when it has to select an address family and transport to 508 contact its DOTS server. The results of the Happy Eyeballs procedure 509 are used by the DOTS client for sending its subsequent messages to 510 the DOTS server. The differences in behavior with respect to the 511 Happy Eyeballs mechanism [RFC8305] are listed below: 513 o The order of preference of the DOTS signal channel address family 514 and transport protocol (most preferred first) is the following: 515 UDP over IPv6, UDP over IPv4, TCP over IPv6, and finally TCP over 516 IPv4. This order adheres to the address preference order 517 specified in [RFC6724] and the DOTS signal channel preference that 518 promotes the use of UDP over TCP (to avoid TCP's head of line 519 blocking). 521 o After successfully establishing a connection, the DOTS client MUST 522 cache information regarding the outcome of each connection attempt 523 for a specific time period; it uses that information to avoid 524 thrashing the network with subsequent attempts. The cached 525 information is flushed when its age exceeds a specific time period 526 on the order of few minutes (e.g., 10 min). Typically, if the 527 DOTS client has to reestablish the connection with the same DOTS 528 server within a few seconds after the Happy Eyeballs mechanism is 529 completed, caching avoids thrashing the network especially in the 530 presence of DDoS attack traffic. 532 o If a DOTS signal channel session is established with TLS (but DTLS 533 failed), the DOTS client periodically repeats the mechanism to 534 discover whether DOTS signal channel messages with DTLS over UDP 535 become available from the DOTS server; this is so the DOTS client 536 can migrate the DOTS signal channel from TCP to UDP. Such probing 537 SHOULD NOT be done more frequently than every 24 hours and MUST 538 NOT be done more frequently than every 5 minutes. 540 When connection attempts are made during an attack, the DOTS client 541 SHOULD use a "Connection Attempt Delay" [RFC8305] set to 100 ms. 543 In Figure 4, the DOTS client proceeds with the connection attempts 544 following the rules in [RFC8305]. In this example, it is assumed 545 that the IPv6 path is broken and UDP traffic is dropped by a 546 middlebox, but this has little impact on the DOTS client because 547 there is not a long delay before using IPv4 and TCP. 549 +-----------+ +-----------+ 550 |DOTS Client| |DOTS Server| 551 +-----------+ +-----------+ 552 | | 553 T0 |--DTLS ClientHello, IPv6 ---->X | 554 T1 |--DTLS ClientHello, IPv4 ---->X | 555 T2 |--TCP SYN, IPv6-------------->X | 556 T3 |--TCP SYN, IPv4------------------------------------->| 557 |<-TCP SYNACK-----------------------------------------| 558 |--TCP ACK------------------------------------------->| 559 |<------------Establish TLS Session------------------>| 560 |----------------DOTS signal------------------------->| 561 | | 563 Note: 564 * Retransmission messages are not shown. 565 * T1-T0=T2-T1=T3-T2= Connection Attempt Delay. 567 Figure 4: DOTS Happy Eyeballs (Sample Flow) 569 A single DOTS signal channel between DOTS agents can be used to 570 exchange multiple DOTS signal messages. To reduce DOTS client and 571 DOTS server workload, DOTS clients SHOULD reuse the (D)TLS session. 573 4.4. DOTS Mitigation Methods 575 The following methods are used by a DOTS client to request, withdraw, 576 or retrieve the status of mitigation requests: 578 PUT: DOTS clients use the PUT method to request mitigation from a 579 DOTS server (Section 4.4.1). During active mitigation, DOTS 580 clients may use PUT requests to carry mitigation efficacy 581 updates to the DOTS server (Section 4.4.3). 583 GET: DOTS clients may use the GET method to retrieve the list of 584 its mitigations maintained by a DOTS server (Section 4.4.2) 585 or to receive asynchronous DOTS server status messages 586 (Section 4.4.2.1). 588 DELETE: DOTS clients use the DELETE method to withdraw a request for 589 mitigation from a DOTS server (Section 4.4.4). 591 Mitigation request and response messages are marked as Non- 592 confirmable messages (Section 2.2 of [RFC7252]). 594 DOTS agents MUST NOT send more than one UDP datagram per round-trip 595 time (RTT) to the peer DOTS agent on average following the data 596 transmission guidelines discussed in Section 3.1.3 of [RFC8085]. 598 Requests marked by the DOTS client as Non-confirmable messages are 599 sent at regular intervals until a response is received from the DOTS 600 server. If the DOTS client cannot maintain an RTT estimate, it MUST 601 NOT send more than one Non-confirmable request every 3 seconds, and 602 SHOULD use an even less aggressive rate whenever possible (case 2 in 603 Section 3.1.3 of [RFC8085]). Mitigation requests MUST NOT be delayed 604 because of checks on probing rate (Section 4.7 of [RFC7252]). 606 JSON encoding of YANG modeled data [RFC7951] is used to illustrate 607 the various methods defined in the following subsections. Also, the 608 examples use the Labels defined in Sections 10.6.2, 10.6.3, 10.6.4, 609 and 10.6.5. 611 The DOTS client MUST authenticate itself to the DOTS server 612 (Section 8). The DOTS server MAY use the algorithm presented in 613 Section 7 of [RFC7589] to derive the DOTS client identity or username 614 from the client certificate. The DOTS client identity allows the 615 DOTS server to accept mitigation requests with scopes that the DOTS 616 client is authorized to manage. 618 4.4.1. Request Mitigation 620 4.4.1.1. Building Mitigation Requests 622 When a DOTS client requires mitigation for some reason, the DOTS 623 client uses the CoAP PUT method to send a mitigation request to its 624 DOTS server(s) (Figures 5 and 6). 626 If a DOTS client is entitled to solicit the DOTS service, the DOTS 627 server enables mitigation on behalf of the DOTS client by 628 communicating the DOTS client's request to a mitigator (which may be 629 co-located with the DOTS server) and relaying the feedback of the 630 thus-selected mitigator to the requesting DOTS client. 632 Header: PUT (Code=0.03) 633 Uri-Path: ".well-known" 634 Uri-Path: "dots" 635 Uri-Path: "mitigate" 636 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 637 Uri-Path: "mid=123" 638 Content-Format: "application/dots+cbor" 640 { 641 ... 642 } 644 Figure 5: PUT to Convey DOTS Mitigation Requests 646 The order of the Uri-Path options is important as it defines the CoAP 647 resource. In particular, 'mid' MUST follow 'cuid'. 649 The additional Uri-Path parameters to those defined in Section 4.2 650 are as follows: 652 cuid: Stands for Client Unique Identifier. A globally unique 653 identifier that is meant to prevent collisions among DOTS 654 clients, especially those from the same domain. It MUST be 655 generated by DOTS clients. 657 For the reasons discussed in Appendix B, implementations SHOULD 658 set 'cuid' using the following procedure: first, the DOTS 659 client inputs one of the following into the SHA-256 [RFC6234] 660 cryptographic hash: the DER-encoded ASN.1 representation of the 661 Subject Public Key Info (SPKI) of its X.509 certificate 662 [RFC5280], its raw public key [RFC7250], the "Pre-Shared Key 663 (PSK) identity" it uses in the TLS 1.2 ClientKeyExchange 664 message, or the "identity" it uses in the "pre_shared_key" TLS 665 1.3 extension. Then, the output of the cryptographic hash 666 algorithm is truncated to 16 bytes; truncation is done by 667 stripping off the final 16 bytes. The truncated output is 668 base64url encoded (Section 5 of [RFC4648]) with the two 669 trailing "=" removed from the encoding, and the resulting value 670 used as the 'cuid'. 672 The 'cuid' is intended to be stable when communicating with a 673 given DOTS server, i.e., the 'cuid' used by a DOTS client 674 SHOULD NOT change over time. Distinct 'cuid' values MAY be 675 used by a single DOTS client per DOTS server. 677 If a DOTS client has to change its 'cuid' for some reason, it 678 MUST NOT do so when mitigations are still active for the old 679 'cuid'. The 'cuid' SHOULD be 22 characters to avoid DOTS 680 signal message fragmentation over UDP. Furthermore, if that 681 DOTS client created aliases and filtering entries at the DOTS 682 server by means of the DOTS data channel, it MUST delete all 683 the entries bound to the old 'cuid' and reinstall them using 684 the new 'cuid'. 686 DOTS servers MUST return 4.09 (Conflict) error code to a DOTS 687 peer to notify that the 'cuid' is already in use by another 688 DOTS client. Upon receipt of that error code, a new 'cuid' 689 MUST be generated by the DOTS peer (e.g., using [RFC4122]). 691 Client-domain DOTS gateways MUST handle 'cuid' collision 692 directly and it is RECOMMENDED that 'cuid' collision is handled 693 directly by server-domain DOTS gateways. 695 DOTS gateways MAY rewrite the 'cuid' used by peer DOTS clients. 696 Triggers for such rewriting are out of scope. 698 This is a mandatory Uri-Path parameter. 700 mid: Identifier for the mitigation request represented with an 701 integer. This identifier MUST be unique for each mitigation 702 request bound to the DOTS client, i.e., the 'mid' parameter 703 value in the mitigation request needs to be unique (per 'cuid' 704 and DOTS server) relative to the 'mid' parameter values of 705 active mitigation requests conveyed from the DOTS client to the 706 DOTS server. 708 In order to handle out-of-order delivery of mitigation 709 requests, 'mid' values MUST increase monotonically. 711 If the 'mid' value has reached 3/4 of (2^(32) - 1) (i.e., 712 3221225471) and no attack is detected, the DOTS client MUST 713 reset 'mid' to 0 to handle 'mid' rollover. If the DOTS client 714 maintains mitigation requests with preconfigured scopes, it 715 MUST recreate them with the 'mid' restarting at 0. 717 This identifier MUST be generated by the DOTS client. 719 This is a mandatory Uri-Path parameter. 721 'cuid' and 'mid' MUST NOT appear in the PUT request message body 722 (Figure 6). The schema in Figure 6 uses the types defined in 723 Section 6. Note that this figure (and other similar figures 724 depicting a schema) are non-normative sketches of the structure of 725 the message. 727 { 728 "ietf-dots-signal-channel:mitigation-scope": { 729 "scope": [ 730 { 731 "target-prefix": [ 732 "string" 733 ], 734 "target-port-range": [ 735 { 736 "lower-port": number, 737 "upper-port": number 738 } 739 ], 740 "target-protocol": [ 741 number 742 ], 743 "target-fqdn": [ 744 "string" 745 ], 746 "target-uri": [ 747 "string" 748 ], 749 "alias-name": [ 750 "string" 751 ], 752 "lifetime": number, 753 "trigger-mitigation": true|false 754 } 755 ] 756 } 757 } 759 Figure 6: PUT to Convey DOTS Mitigation Requests (Message Body 760 Schema) 762 The parameters in the CBOR body (Figure 6) of the PUT request are 763 described below: 765 target-prefix: A list of prefixes identifying resources under 766 attack. Prefixes are represented using Classless Inter-Domain 767 Routing (CIDR) notation [RFC4632]. 769 The prefix length must be less than or equal to 32 for IPv4 and 770 128 for IPv6. 772 The prefix list MUST NOT include broadcast, loopback, or multicast 773 addresses. These addresses are considered to be invalid values. 774 In addition, the DOTS server MUST validate that target prefixes 775 are within the scope of the DOTS client domain. Other validation 776 checks may be supported by DOTS servers. 778 This is an optional attribute. 780 target-port-range: A list of port numbers bound to resources under 781 attack. 783 A port range is defined by two bounds, a lower port number 784 ('lower-port') and an upper port number ('upper-port'). When only 785 'lower-port' is present, it represents a single port number. 787 For TCP, UDP, Stream Control Transmission Protocol (SCTP) 788 [RFC4960], or Datagram Congestion Control Protocol (DCCP) 789 [RFC4340], a range of ports can be, for example, 0-1023, 790 1024-65535, or 1024-49151. 792 This is an optional attribute. 794 target-protocol: A list of protocols involved in an attack. Values 795 are integers in the range of 0 to 255. See [IANA-Proto] for 796 common values. 798 If 'target-protocol' is not specified, then the request applies to 799 any protocol. 801 This is an optional attribute. 803 target-fqdn: A list of Fully Qualified Domain Names (FQDNs) 804 identifying resources under attack [RFC8499]. 806 How a name is passed to an underlying name resolution library is 807 implementation and deployment specific. Nevertheless, once the 808 name is resolved into one or multiple IP addresses, DOTS servers 809 MUST apply the same validation checks as those for 'target- 810 prefix'. These validation checks are reiterated by DOTS servers 811 each time a name is passed to an underlying name resolution 812 library (e.g., upon expiry of DNS TTL). 814 The use of FQDNs may be suboptimal because: 816 * It induces both an extra load and increased delays on the DOTS 817 server to handle and manage DNS resolution requests. 819 * It does not guarantee that the DOTS server will resolve a name 820 to the same IP addresses that the DOTS client does. 822 This is an optional attribute. 824 target-uri: A list of URIs [RFC3986] identifying resources under 825 attack. 827 The same validation checks used for 'target-fqdn' MUST be followed 828 by DOTS servers to validate a target URI. 830 This is an optional attribute. 832 alias-name: A list of aliases of resources for which the mitigation 833 is requested. Aliases can be created using the DOTS data channel 834 (Section 6.1 of [RFC8783]), direct configuration, or other means. 836 An alias is used in subsequent signal channel exchanges to refer 837 more efficiently to the resources under attack. 839 This is an optional attribute. 841 lifetime: Lifetime of the mitigation request in seconds. The 842 RECOMMENDED lifetime of a mitigation request is 3600 seconds: this 843 value was chosen to be long enough so that refreshing is not 844 typically a burden on the DOTS client, while still making the 845 request expire in a timely manner when the client has unexpectedly 846 quit. DOTS clients MUST include this parameter in their 847 mitigation requests. 849 A lifetime of '0' in a mitigation request is an invalid value. 851 A lifetime of negative one (-1) indicates indefinite lifetime for 852 the mitigation request. The DOTS server MAY refuse an indefinite 853 lifetime, for policy reasons; the granted lifetime value is 854 returned in the response. DOTS clients MUST be prepared to not be 855 granted mitigations with indefinite lifetimes. 857 The DOTS server MUST always indicate the actual lifetime in the 858 response and the remaining lifetime in status messages sent to the 859 DOTS client. 861 Upon the expiry of the negotiated lifetime (i.e., the remaining 862 lifetime reaches '0'), and if the request is not refreshed by the 863 DOTS client, the mitigation request is removed by the DOTS server. 864 The request can be refreshed by sending the same request again. 866 This is a mandatory attribute. 868 trigger-mitigation: If the parameter value is set to 'false', DDoS 869 mitigation will not be triggered for the mitigation request unless 870 the DOTS signal channel session is lost. 872 If the DOTS client ceases to respond to heartbeat messages, the 873 DOTS server can detect that the DOTS signal channel session is 874 lost. More details are discussed in Section 4.7. 876 The default value of the parameter is 'true' (that is, the 877 mitigation starts immediately). If 'trigger-mitigation' is not 878 present in a request, this is equivalent to receiving a request 879 with 'trigger-mitigation' set to 'true'. 881 This is an optional attribute. 883 Because of the complexity of handling partial failure cases, this 884 specification does not allow the inclusion of multiple mitigation 885 requests in the same PUT request. Concretely, a DOTS client MUST NOT 886 include multiple entries in the 'scope' array of the same PUT 887 request. 889 FQDN and URI mitigation scopes may be thought of as a form of scope 890 alias, in which the addresses associated with the domain name or URI 891 (as resolved by the DOTS server) represent the scope of the 892 mitigation. Particularly, the IP addresses to which the host 893 subcomponent of authority component of a URI resolves represent the 894 'target-prefix', the URI scheme represents the 'target-protocol', the 895 port subcomponent of authority component of a URI represents the 896 'target-port-range'. If the optional port information is not present 897 in the authority component, the default port defined for the URI 898 scheme represents the 'target-port'. 900 In the PUT request, at least one of the attributes 'target-prefix', 901 'target-fqdn','target-uri', or 'alias-name' MUST be present. 903 Attributes and Uri-Path parameters with empty values MUST NOT be 904 present in a request as an empty value will render the entire request 905 invalid. 907 Figure 7 shows a PUT request example to signal that servers 908 2001:db8:6401::1 and 2001:db8:6401::2 are receiving attack traffic on 909 TCP port numbers 80, 8080, and 443. The presence of 'cdid' indicates 910 that a server-domain DOTS gateway has modified the initial PUT 911 request sent by the DOTS client. Note that 'cdid' MUST NOT appear in 912 the PUT request message body. 914 Header: PUT (Code=0.03) 915 Uri-Path: ".well-known" 916 Uri-Path: "dots" 917 Uri-Path: "mitigate" 918 Uri-Path: "cdid=7eeaf349529eb55ed50113" 919 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 920 Uri-Path: "mid=123" 921 Content-Format: "application/dots+cbor" 923 { 924 "ietf-dots-signal-channel:mitigation-scope": { 925 "scope": [ 926 { 927 "target-prefix": [ 928 "2001:db8:6401::1/128", 929 "2001:db8:6401::2/128" 930 ], 931 "target-port-range": [ 932 { 933 "lower-port": 80 934 }, 935 { 936 "lower-port": 443 937 }, 938 { 939 "lower-port": 8080 940 } 941 ], 942 "target-protocol": [ 943 6 944 ], 945 "lifetime": 3600 946 } 947 ] 948 } 949 } 951 Figure 7: PUT for DOTS Mitigation Request (An Example) 953 The corresponding CBOR encoding format for the payload is shown in 954 Figure 8. 956 A1 # map(1) 957 01 # unsigned(1) 958 A1 # map(1) 959 02 # unsigned(2) 960 81 # array(1) 961 A4 # map(4) 962 06 # unsigned(6) 963 82 # array(2) 964 74 # text(20) 965 323030313A6462383A363430313A3A312F313238 966 74 # text(20) 967 323030313A6462383A363430313A3A322F313238 968 07 # unsigned(7) 969 83 # array(3) 970 A1 # map(1) 971 08 # unsigned(8) 972 18 50 # unsigned(80) 973 A1 # map(1) 974 08 # unsigned(8) 975 19 01BB # unsigned(443) 976 A1 # map(1) 977 08 # unsigned(8) 978 19 1F90 # unsigned(8080) 979 0A # unsigned(10) 980 81 # array(1) 981 06 # unsigned(6) 982 0E # unsigned(14) 983 19 0E10 # unsigned(3600) 985 Figure 8: PUT for DOTS Mitigation Request (CBOR) 987 4.4.1.2. Server-domain DOTS Gateways 989 In deployments where server-domain DOTS gateways are enabled, 990 identity information about the origin source client domain ('cdid') 991 SHOULD be propagated to the DOTS server. That information is meant 992 to assist the DOTS server in enforcing some policies such as grouping 993 DOTS clients that belong to the same DOTS domain, limiting the number 994 of DOTS requests, and identifying the mitigation scope. These 995 policies can be enforced per client, per client domain, or both. 996 Also, the identity information may be used for auditing and debugging 997 purposes. 999 Figure 9 shows an example of a request relayed by a server-domain 1000 DOTS gateway. 1002 Header: PUT (Code=0.03) 1003 Uri-Path: ".well-known" 1004 Uri-Path: "dots" 1005 Uri-Path: "mitigate" 1006 Uri-Path: "cdid=7eeaf349529eb55ed50113" 1007 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1008 Uri-Path: "mid=123" 1009 Content-Format: "application/dots+cbor" 1011 { 1012 ... 1013 } 1015 Figure 9: PUT for DOTS Mitigation Request as Relayed by a DOTS 1016 Gateway 1018 A server-domain DOTS gateway SHOULD add the following Uri-Path 1019 parameter: 1021 cdid: Stands for Client Domain Identifier. The 'cdid' is conveyed by 1022 a server-domain DOTS gateway to propagate the source domain 1023 identity from the gateway's client-facing side to the gateway's 1024 server-facing side, and from the gateway's server-facing side 1025 to the DOTS server. 'cdid' may be used by the final DOTS 1026 server for policy enforcement purposes (e.g., enforce a quota 1027 on filtering rules). These policies are deployment specific. 1029 Server-domain DOTS gateways SHOULD support a configuration 1030 option to instruct whether 'cdid' parameter is to be inserted. 1032 In order to accommodate deployments that require enforcing per- 1033 client policies, per-client domain policies, or a combination 1034 thereof, server-domain DOTS gateways instructed to insert the 1035 'cdid' parameter MUST supply the SPKI hash of the DOTS client 1036 X.509 certificate, the DOTS client raw public key, or the hash 1037 of the "PSK identity" in the 'cdid', following the same rules 1038 for generating the hash conveyed in 'cuid', which is then used 1039 by the ultimate DOTS server to determine the corresponding 1040 client's domain. The 'cdid' generated by a server-domain 1041 gateway is likely to be the same as the 'cuid' except the case 1042 in which the DOTS message was relayed by a client-domain DOTS 1043 gateway or the 'cuid' was generated by a rogue DOTS client. 1045 If a DOTS client is provisioned, for example, with distinct 1046 certificates to use to peer with distinct server-domain DOTS 1047 gateways that peer to the same DOTS server, distinct 'cdid' 1048 values may be supplied by the server-domain DOTS gateways to 1049 the server. The ultimate DOTS server MUST treat those 'cdid' 1050 values as equivalent. 1052 The 'cdid' attribute MUST NOT be generated and included by DOTS 1053 clients. 1055 DOTS servers MUST ignore 'cdid' attributes that are directly 1056 supplied by source DOTS clients or client-domain DOTS gateways. 1057 This implies that first server-domain DOTS gateways MUST strip 1058 'cdid' attributes supplied by DOTS clients. DOTS servers 1059 SHOULD support a configuration parameter to identify DOTS 1060 gateways that are trusted to supply 'cdid' attributes. 1062 Only single-valued 'cdid' are defined in this document. That 1063 is, only the first on-path server-domain DOTS gateway can 1064 insert a 'cdid' value. This specification does not allow 1065 multiple server-domain DOTS gateways, whenever involved in the 1066 path, to insert a 'cdid' value for each server-domain gateway. 1068 This is an optional Uri-Path. When present, 'cdid' MUST be 1069 positioned before 'cuid'. 1071 A DOTS gateway SHOULD add the CoAP Hop-Limit Option [RFC8768]. 1073 4.4.1.3. Processing Mitigation Requests 1075 The DOTS server couples the DOTS signal and data channel sessions 1076 using the DOTS client identity and optionally the 'cdid' parameter 1077 value, so the DOTS server can validate whether the aliases conveyed 1078 in the mitigation request were indeed created by the same DOTS client 1079 using the DOTS data channel session. If the aliases were not created 1080 by the DOTS client, the DOTS server MUST return 4.00 (Bad Request) in 1081 the response. 1083 The DOTS server couples the DOTS signal channel sessions using the 1084 DOTS client identity and optionally the 'cdid' parameter value, and 1085 the DOTS server uses 'mid' and 'cuid' Uri-Path parameter values to 1086 detect duplicate mitigation requests. If the mitigation request 1087 contains the 'alias-name' and other parameters identifying the target 1088 resources (such as 'target-prefix', 'target-port-range', 'target- 1089 fqdn', or 'target-uri'), the DOTS server appends the parameter values 1090 associated with the 'alias-name' with the corresponding parameter 1091 values in 'target-prefix', 'target-port-range', 'target-fqdn', or 1092 'target-uri'. 1094 The DOTS server indicates the result of processing the PUT request 1095 using CoAP Response Codes. CoAP 2.xx codes are success. CoAP 4.xx 1096 codes are some sort of invalid requests (client errors). CoAP 5.xx 1097 codes are returned if the DOTS server is in an error state or is 1098 currently unavailable to provide mitigation in response to the 1099 mitigation request from the DOTS client. 1101 Figure 10 shows an example response to a PUT request that is 1102 successfully processed by a DOTS server (i.e., CoAP 2.xx Response 1103 Codes). This version of the specification forbids 'cuid' and 'cdid' 1104 (if used) to be returned in a response message body. 1106 { 1107 "ietf-dots-signal-channel:mitigation-scope": { 1108 "scope": [ 1109 { 1110 "mid": 123, 1111 "lifetime": 3600 1112 } 1113 ] 1114 } 1115 } 1117 Figure 10: 2.xx Response Body 1119 If the request is missing a mandatory attribute, does not include 1120 'cuid' or 'mid' Uri-Path options, includes multiple 'scope' 1121 parameters, or contains invalid or unknown parameters, the DOTS 1122 server MUST reply with 4.00 (Bad Request). DOTS agents can safely 1123 ignore comprehension-optional parameters they don't understand 1124 (Section 10.6.1.1). 1126 A DOTS server that receives a mitigation request with a 'lifetime' 1127 set to '0' MUST reply with a 4.00 (Bad Request). 1129 If the DOTS server does not find the 'mid' parameter value conveyed 1130 in the PUT request in its configuration data, it MAY accept the 1131 mitigation request by sending back a 2.01 (Created) response to the 1132 DOTS client; the DOTS server will consequently try to mitigate the 1133 attack. A DOTS server MAY reject mitigation requests when it is near 1134 capacity or needs to rate-limit a particular client, for example. 1136 The relative order of two mitigation requests with the same 'trigger- 1137 mitigation' type from a DOTS client is determined by comparing their 1138 respective 'mid' values. If two mitigation requests with the same 1139 'trigger-mitigation' type have overlapping mitigation scopes, the 1140 mitigation request with the highest numeric 'mid' value will override 1141 the other mitigation request. Two mitigation requests from a DOTS 1142 client have overlapping scopes if there is a common IP address, IP 1143 prefix, FQDN, URI, or alias. To avoid maintaining a long list of 1144 overlapping mitigation requests (i.e., requests with the same 1145 'trigger-mitigation' type and overlapping scopes) from a DOTS client 1146 and to avoid error-prone provisioning of mitigation requests from a 1147 DOTS client, the overlapped lower numeric 'mid' MUST be automatically 1148 deleted and no longer available at the DOTS server. For example, if 1149 the DOTS server receives a mitigation request that overlaps with an 1150 existing mitigation with a higher numeric 'mid', the DOTS server 1151 rejects the request by returning 4.09 (Conflict) to the DOTS client. 1152 The response MUST include enough information for a DOTS client to 1153 recognize the source of the conflict as described below in the 1154 'conflict-information' subtree (Section 5.1) with only the relevant 1155 nodes listed: 1157 conflict-information: Indicates that a mitigation request is 1158 conflicting with another mitigation request. This attribute has 1159 the following structure: 1161 conflict-cause: Indicates the cause of the conflict. The 1162 following value MUST be returned: 1164 1: Overlapping targets. 'conflict-scope' provides more details 1165 about the conflicting target clauses. 1167 conflict-scope: Characterizes the exact conflict scope. It may 1168 include a list of IP addresses, a list of prefixes, a list of 1169 target protocols, a list of FQDNs, a list of URIs, a list of 1170 aliases, or a 'mid'. A list of port numbers may also be 1171 included if there is a common IP address, IP prefix, FQDN, URI, 1172 or alias. 1174 If the DOTS server receives a mitigation request that overlaps with 1175 an active mitigation request, but both have distinct 'trigger- 1176 mitigation' types, the DOTS server SHOULD deactivate (absent explicit 1177 policy/configuration otherwise) the mitigation request with 'trigger- 1178 mitigation' set to 'false'. Particularly, if the mitigation request 1179 with 'trigger-mitigation' set to 'false' is active, the DOTS server 1180 withdraws the mitigation request (i.e., status code is set to '7' as 1181 defined in Table 3) and transitions the status of the mitigation 1182 request to '8'. 1184 Upon DOTS signal channel session loss with a peer DOTS client, the 1185 DOTS server SHOULD withdraw (absent explicit policy/configuration 1186 otherwise) any active mitigation requests that overlap with 1187 mitigation requests having 'trigger-mitigation' set to 'false' from 1188 that DOTS client, as the loss of the session implicitly activates 1189 these preconfigured mitigation requests, and they take precedence. 1190 Note that the active-but-terminating period is not observed for 1191 mitigations withdrawn at the initiative of the DOTS server. 1193 DOTS clients may adopt various strategies for setting the scopes of 1194 immediate and preconfigured mitigation requests to avoid potential 1195 conflicts. For example, a DOTS client may tweak preconfigured scopes 1196 so that the scope of any overlapping immediate mitigation request 1197 will be a subset of the preconfigured scopes. Also, if an immediate 1198 mitigation request overlaps with any of the preconfigured scopes, the 1199 DOTS client sets the scope of the overlapping immediate mitigation 1200 request to be a subset of the preconfigured scopes, so as to get a 1201 broad mitigation when the DOTS signal channel collapses and to 1202 maximize the chance of recovery. 1204 If the request conflicts with an existing mitigation request from a 1205 different DOTS client, the DOTS server may return 2.01 (Created) or 1206 4.09 (Conflict) to the requesting DOTS client. If the DOTS server 1207 decides to maintain the new mitigation request, the DOTS server 1208 returns 2.01 (Created) to the requesting DOTS client. If the DOTS 1209 server decides to reject the new mitigation request, the DOTS server 1210 returns 4.09 (Conflict) to the requesting DOTS client. For both 2.01 1211 (Created) and 4.09 (Conflict) responses, the response MUST include 1212 enough information for a DOTS client to recognize the source of the 1213 conflict as described below: 1215 conflict-information: Indicates that a mitigation request is 1216 conflicting with another mitigation request(s) from other DOTS 1217 client(s). This attribute has the following structure: 1219 conflict-status: Indicates the status of a conflicting mitigation 1220 request. The following values are defined: 1222 1: DOTS server has detected conflicting mitigation requests 1223 from different DOTS clients. This mitigation request is 1224 currently inactive until the conflicts are resolved. 1225 Another mitigation request is active. 1227 2: DOTS server has detected conflicting mitigation requests 1228 from different DOTS clients. This mitigation request is 1229 currently active. 1231 3: DOTS server has detected conflicting mitigation requests 1232 from different DOTS clients. All conflicting mitigation 1233 requests are inactive. 1235 conflict-cause: Indicates the cause of the conflict. The 1236 following values are defined: 1238 1: Overlapping targets. 'conflict-scope' provides more details 1239 about the conflicting target clauses. 1241 2: Conflicts with an existing accept-list. This code is 1242 returned when the DDoS mitigation detects source addresses/ 1243 prefixes in the accept-listed ACLs are attacking the 1244 target. 1246 3: CUID Collision. This code is returned when a DOTS client 1247 uses a 'cuid' that is already used by another DOTS client. 1248 This code is an indication that the request has been 1249 rejected and a new request with a new 'cuid' is to be re- 1250 sent by the DOTS client (see the example shown in 1251 Figure 11). Note that 'conflict-status', 'conflict-scope', 1252 and 'retry-timer' MUST NOT be returned in the error 1253 response. 1255 conflict-scope: Characterizes the exact conflict scope. It may 1256 include a list of IP addresses, a list of prefixes, a list of 1257 target protocols, a list of FQDNs, a list of URIs, a list of 1258 aliases, or references to conflicting ACLs (by an 'acl-name', 1259 typically [RFC8783]). A list of port numbers may also be 1260 included if there is a common IP address, IP prefix, FQDN, URI, 1261 or alias. 1263 retry-timer: Indicates, in seconds, the time after which the DOTS 1264 client may reissue the same request. The DOTS server returns 1265 'retry-timer' only to DOTS client(s) for which a mitigation 1266 request is deactivated. Any retransmission of the same 1267 mitigation request before the expiry of this timer is likely to 1268 be rejected by the DOTS server for the same reasons. 1270 The 'retry-timer' SHOULD be equal to the lifetime of the active 1271 mitigation request resulting in the deactivation of the 1272 conflicting mitigation request. 1274 If the DOTS server decides to maintain a state for the 1275 deactivated mitigation request, the DOTS server updates the 1276 lifetime of the deactivated mitigation request to 'retry-timer 1277 + 45 seconds' (that is, this mitigation request remains 1278 deactivated for the entire duration of 'retry-timer + 45 1279 seconds') so that the DOTS client can refresh the deactivated 1280 mitigation request after 'retry-timer' seconds, but before the 1281 expiry of the lifetime, and check if the conflict is resolved. 1283 (1) Request with a conflicting 'cuid' 1285 Header: PUT (Code=0.03) 1286 Uri-Path: ".well-known" 1287 Uri-Path: "dots" 1288 Uri-Path: "mitigate" 1289 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1290 Uri-Path: "mid=12" 1292 (2) Message body of the 4.09 (Conflict) response 1293 from the DOTS server 1295 { 1296 "ietf-dots-signal-channel:mitigation-scope": { 1297 "scope": [ 1298 { 1299 "conflict-information": { 1300 "conflict-cause": "cuid-collision" 1301 } 1302 } 1303 ] 1304 } 1305 } 1307 (3) Request with a new 'cuid' 1309 Header: PUT (Code=0.03) 1310 Uri-Path: ".well-known" 1311 Uri-Path: "dots" 1312 Uri-Path: "mitigate" 1313 Uri-Path: "cuid=f30d281ce6b64fc5a0b91e" 1314 Uri-Path: "mid=12" 1316 Figure 11: Example of Generating a New 'cuid' 1318 As an active attack evolves, DOTS clients can adjust the scope of 1319 requested mitigation as necessary, by refining the scope of resources 1320 requiring mitigation. This can be achieved by sending a PUT request 1321 with a new 'mid' value that will override the existing one with 1322 overlapping mitigation scopes. 1324 For a mitigation request to continue beyond the initial negotiated 1325 lifetime, the DOTS client has to refresh the current mitigation 1326 request by sending a new PUT request. This PUT request MUST use the 1327 same 'mid' value, and it MUST repeat all the other parameters as sent 1328 in the original mitigation request apart from a possible change to 1329 the 'lifetime' parameter value. In such a case, the DOTS server MAY 1330 update the mitigation request by setting the remaining lifetime to 1331 the newly negotiated lifetime, and a 2.04 (Changed) response is 1332 returned to indicate a successful update of the mitigation request. 1333 If this is not the case, the DOTS server MUST reject the request with 1334 a 4.00 (Bad Request). 1336 4.4.2. Retrieve Information Related to a Mitigation 1338 A GET request is used by a DOTS client to retrieve information 1339 (including status) of DOTS mitigations from a DOTS server. 1341 'cuid' is a mandatory Uri-Path parameter for GET requests. 1343 Uri-Path parameters with empty values MUST NOT be present in a 1344 request. 1346 The same considerations for manipulating the 'cdid' parameter by 1347 server-domain DOTS gateways specified in Section 4.4.1 MUST be 1348 followed for GET requests. 1350 The 'c' Uri-Query option is used to control selection of 1351 configuration and non-configuration data nodes. Concretely, the 'c' 1352 (content) parameter and its permitted values defined in Table 2 1353 [I-D.ietf-core-comi] can be used to retrieve non-configuration data 1354 (attack mitigation status), configuration data, or both. The DOTS 1355 server MAY support this optional filtering capability. It can safely 1356 ignore it if not supported. If the DOTS client supports the optional 1357 filtering capability, it SHOULD use "c=n" query (to get back only the 1358 dynamically changing data) or "c=c" query (to get back the static 1359 configuration values) when the DDoS attack is active to limit the 1360 size of the response. 1362 +-------+-----------------------------------------------------+ 1363 | Value | Description | 1364 +=======+=====================================================+ 1365 | c | Return only configuration descendant data nodes | 1366 +-------+-----------------------------------------------------+ 1367 | n | Return only non-configuration descendant data nodes | 1368 +-------+-----------------------------------------------------+ 1369 | a | Return all descendant data nodes | 1370 +-------+-----------------------------------------------------+ 1372 Table 2: Permitted Values of the 'c' Parameter 1374 The DOTS client can use block-wise transfer [RFC7959] to get the list 1375 of all its mitigations maintained by a DOTS server, it can send a 1376 Block2 Option in a GET request with NUM = 0 to aid in limiting the 1377 size of the response. If the representation of all the active 1378 mitigation requests associated with the DOTS client does not fit 1379 within a single datagram, the DOTS server MUST use the Block2 Option 1380 with NUM = 0 in the GET response. The Size2 Option may be conveyed 1381 in the response to indicate the total size of the resource 1382 representation. The DOTS client retrieves the rest of the 1383 representation by sending additional GET requests with Block2 Options 1384 containing NUM values greater than zero. The DOTS client MUST adhere 1385 to the block size preferences indicated by the DOTS server in the 1386 response. If the DOTS server uses the Block2 Option in the GET 1387 response, and the response is for a dynamically changing resource 1388 (e.g., "c=n" or "c=a" query), the DOTS server MUST include the ETag 1389 Option in the response. The DOTS client MUST include the same ETag 1390 value in subsequent GET requests to retrieve the rest of the 1391 representation. 1393 The following examples illustrate how a DOTS client retrieves active 1394 mitigation requests from a DOTS server. In particular: 1396 o Figure 12 shows the example of a GET request to retrieve all DOTS 1397 mitigation requests signaled by a DOTS client. 1399 o Figure 13 shows the example of a GET request to retrieve a 1400 specific DOTS mitigation request signaled by a DOTS client. The 1401 configuration data to be reported in the response is formatted in 1402 the same order as it was processed by the DOTS server in the 1403 original mitigation request. 1405 These two examples assume the default of "c=a"; that is, the DOTS 1406 client asks for all data to be reported by the DOTS server. 1408 Header: GET (Code=0.01) 1409 Uri-Path: ".well-known" 1410 Uri-Path: "dots" 1411 Uri-Path: "mitigate" 1412 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1413 Observe: 0 1415 Figure 12: GET to Retrieve All DOTS Mitigation Requests 1417 Header: GET (Code=0.01) 1418 Uri-Path: ".well-known" 1419 Uri-Path: "dots" 1420 Uri-Path: "mitigate" 1421 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1422 Uri-Path: "mid=12332" 1423 Observe: 0 1425 Figure 13: GET to Retrieve a Specific DOTS Mitigation Request 1427 If the DOTS server does not find the 'mid' Uri-Path value conveyed in 1428 the GET request in its configuration data for the requesting DOTS 1429 client, it MUST respond with a 4.04 (Not Found) error Response Code. 1430 Likewise, the same error MUST be returned as a response to a request 1431 to retrieve all mitigation records (i.e., 'mid' Uri-Path is not 1432 defined) of a given DOTS client if the DOTS server does not find any 1433 mitigation record for that DOTS client. As a reminder, a DOTS client 1434 is identified by its identity (e.g., client certificate, 'cuid') and 1435 optionally the 'cdid'. 1437 Figure 14 shows a response example of all active mitigation requests 1438 associated with the DOTS client as maintained by the DOTS server. 1439 The response indicates the mitigation status of each mitigation 1440 request. 1442 { 1443 "ietf-dots-signal-channel:mitigation-scope": { 1444 "scope": [ 1445 { 1446 "mid": 12332, 1447 "mitigation-start": "1507818434", 1448 "target-prefix": [ 1449 "2001:db8:6401::1/128", 1450 "2001:db8:6401::2/128" 1451 ], 1452 "target-protocol": [ 1453 17 1454 ], 1455 "lifetime": 1756, 1456 "status": "attack-successfully-mitigated", 1457 "bytes-dropped": "134334555", 1458 "bps-dropped": "43344", 1459 "pkts-dropped": "333334444", 1460 "pps-dropped": "432432" 1461 }, 1462 { 1463 "mid": 12333, 1464 "mitigation-start": "1507818393", 1465 "target-prefix": [ 1466 "2001:db8:6401::1/128", 1467 "2001:db8:6401::2/128" 1468 ], 1469 "target-protocol": [ 1470 6 1471 ], 1472 "lifetime": 1755, 1473 "status": "attack-stopped", 1474 "bytes-dropped": "0", 1475 "bps-dropped": "0", 1476 "pkts-dropped": "0", 1477 "pps-dropped": "0" 1478 } 1479 ] 1480 } 1481 } 1483 Figure 14: Response Body to a GET Request 1485 The mitigation status parameters are described below: 1487 mitigation-start: Mitigation start time is expressed in seconds 1488 relative to 1970-01-01T00:00Z in UTC time (Section 3.4.1 of 1490 [RFC8949]). The CBOR encoding is modified so that the leading tag 1491 1 (epoch-based date/time) MUST be omitted. 1493 This is a mandatory attribute when an attack mitigation is active. 1494 Particularly, 'mitigation-start' is not returned for a mitigation 1495 with 'status' code set to 8. 1497 lifetime: The remaining lifetime of the mitigation request, in 1498 seconds. 1500 This is a mandatory attribute. 1502 status: Status of attack mitigation. The various possible values of 1503 'status' parameter are explained in Table 3. 1505 This is a mandatory attribute. 1507 bytes-dropped: The total dropped byte count for the mitigation 1508 request since the attack mitigation was triggered. The count 1509 wraps around when it reaches the maximum value of unsigned 1510 integer64. 1512 This is an optional attribute. 1514 bps-dropped: The average number of dropped bytes per second for the 1515 mitigation request since the attack mitigation was triggered. 1516 This average SHOULD be over five-minute intervals (that is, 1517 measuring bytes into five-minute buckets and then averaging these 1518 buckets over the time since the mitigation was triggered). 1520 This is an optional attribute. 1522 pkts-dropped: The total number of dropped packet count for the 1523 mitigation request since the attack mitigation was triggered. The 1524 count wraps around when it reaches the maximum value of unsigned 1525 integer64. 1527 This is an optional attribute. 1529 pps-dropped: The average number of dropped packets per second for 1530 the mitigation request since the attack mitigation was triggered. 1531 This average SHOULD be over five-minute intervals (that is, 1532 measuring packets into five-minute buckets and then averaging 1533 these buckets over the time since the mitigation was triggered). 1535 This is an optional attribute. 1537 +-----------+----------------------------------------------------+ 1538 | Parameter | Description | 1539 | Value | | 1540 +===========+====================================================+ 1541 | 1 | Attack mitigation setup is in progress (e.g., | 1542 | | changing the network path to redirect the inbound | 1543 | | traffic to a DOTS mitigator). | 1544 +-----------+----------------------------------------------------+ 1545 | 2 | Attack is being successfully mitigated (e.g., | 1546 | | traffic is redirected to a DDoS mitigator and | 1547 | | attack traffic is dropped). | 1548 +-----------+----------------------------------------------------+ 1549 | 3 | Attack has stopped and the DOTS client can | 1550 | | withdraw the mitigation request. This status code | 1551 | | will be transmitted for immediate mitigation | 1552 | | requests till the mitigation is withdrawn or the | 1553 | | lifetime expires. For mitigation requests with | 1554 | | preconfigured scopes (i.e., 'trigger-mitigation' | 1555 | | set to 'false'), this status code will be | 1556 | | transmitted four times and then transition to "8". | 1557 +-----------+----------------------------------------------------+ 1558 | 4 | Attack has exceeded the mitigation provider | 1559 | | capability. | 1560 +-----------+----------------------------------------------------+ 1561 | 5 | DOTS client has withdrawn the mitigation request | 1562 | | and the mitigation is active but terminating. | 1563 +-----------+----------------------------------------------------+ 1564 | 6 | Attack mitigation is now terminated. | 1565 +-----------+----------------------------------------------------+ 1566 | 7 | Attack mitigation is withdrawn (by the DOTS | 1567 | | server). If a mitigation request with 'trigger- | 1568 | | mitigation' set to 'false' is withdrawn because it | 1569 | | overlaps with an immediate mitigation request, | 1570 | | this status code will be transmitted four times | 1571 | | and then transition to "8" for the mitigation | 1572 | | request with preconfigured scopes. | 1573 +-----------+----------------------------------------------------+ 1574 | 8 | Attack mitigation will be triggered for the | 1575 | | mitigation request only when the DOTS signal | 1576 | | channel session is lost. | 1577 +-----------+----------------------------------------------------+ 1579 Table 3: Values of 'status' Parameter 1581 4.4.2.1. DOTS Servers Sending Mitigation Status 1583 The Observe Option defined in [RFC7641] extends the CoAP core 1584 protocol with a mechanism for a CoAP client to "observe" a resource 1585 on a CoAP server: the client retrieves a representation of the 1586 resource and requests this representation be updated by the server as 1587 long as the client is interested in the resource. DOTS 1588 implementations MUST support the Observe Option for both 'mitigate' 1589 and 'config' (Section 4.2). 1591 A DOTS client conveys the Observe Option set to '0' in the GET 1592 request to receive asynchronous notifications of attack mitigation 1593 status from the DOTS server. 1595 Unidirectional mitigation notifications within the bidirectional 1596 signal channel enables asynchronous notifications between the agents. 1597 [RFC7641] indicates that (1) a notification can be sent in a 1598 Confirmable or a Non-confirmable message, and (2) the message type 1599 used is typically application dependent and may be determined by the 1600 server for each notification individually. For the DOTS server 1601 application, the message type MUST always be set to Non-confirmable 1602 even if the underlying CoAP library elects a notification to be sent 1603 in a Confirmable message. This overrides the behavior defined in 1604 Section 4.5 of [RFC7641] to send a Confirmable message instead of a 1605 Non-confirmable message at least every 24 hours for the following 1606 reasons: First, the DOTS signal channel uses a heartbeat mechanism to 1607 determine if the DOTS client is alive. Second, Confirmable messages 1608 are not suitable during an attack. 1610 Due to the higher likelihood of packet loss during a DDoS attack, the 1611 DOTS server periodically sends attack mitigation status to the DOTS 1612 client and also notifies the DOTS client whenever the status of the 1613 attack mitigation changes. If the DOTS server cannot maintain an RTT 1614 estimate, it MUST NOT send more than one asynchronous notification 1615 every 3 seconds, and SHOULD use an even less aggressive rate whenever 1616 possible (case 2 in Section 3.1.3 of [RFC8085]). 1618 When conflicting requests are detected, the DOTS server enforces the 1619 corresponding policy (e.g., accept all requests, reject all requests, 1620 accept only one request but reject all the others). It is assumed 1621 that this policy is supplied by the DOTS server administrator or that 1622 it is a default behavior of the DOTS server implementation. Then, 1623 the DOTS server sends a notification message(s) to the DOTS client(s) 1624 at the origin of the conflict (refer to the conflict parameters 1625 defined in Section 4.4.1). A conflict notification message includes 1626 information about the conflict cause, scope, and the status of the 1627 mitigation request(s). For example: 1629 o A notification message with 'status' code set to '7 (Attack 1630 mitigation is withdrawn)' and 'conflict-status' set to '1' is sent 1631 to a DOTS client to indicate that an active mitigation request is 1632 deactivated because a conflict is detected. 1634 o A notification message with 'status' code set to '1 (Attack 1635 mitigation is in progress)' and 'conflict-status' set to '2' is 1636 sent to a DOTS client to indicate that this mitigation request is 1637 in progress, but a conflict is detected. 1639 Upon receipt of a conflict notification message indicating that a 1640 mitigation request is deactivated because of a conflict, a DOTS 1641 client MUST NOT resend the same mitigation request before the expiry 1642 of 'retry-timer'. It is also recommended that DOTS clients support 1643 the means to alert administrators about mitigation conflicts. 1645 A DOTS client that is no longer interested in receiving notifications 1646 from the DOTS server can simply "forget" the observation. When the 1647 DOTS server sends the next notification, the DOTS client will not 1648 recognize the token in the message and, thus, will return a Reset 1649 message. This causes the DOTS server to remove the associated entry. 1650 Alternatively, the DOTS client can explicitly de-register itself by 1651 issuing a GET request that has the Token field set to the token of 1652 the observation to be canceled and includes an Observe Option with 1653 the value set to '1' (de-register). The latter is more deterministic 1654 and, thus, is RECOMMENDED. 1656 Figure 15 shows an example of a DOTS client requesting a DOTS server 1657 to send notifications related to a mitigation request. Note that for 1658 mitigations with preconfigured scopes (i.e., 'trigger-mitigation' set 1659 to 'false'), the state will need to transition from 3 (attack- 1660 stopped) to 8 (attack-mitigation-signal-loss). 1662 +-----------+ +-----------+ 1663 |DOTS Client| |DOTS Server| 1664 +-----------+ +-----------+ 1665 | | 1666 | GET / | 1667 | Token: 0x4a | Registration 1668 | Observe: 0 | 1669 +----------------------------------------->| 1670 | | 1671 | 2.05 Content | 1672 | Token: 0x4a | Notification of 1673 | Observe: 12 | the current state 1674 | status: "attack-mitigation-in-progress" | 1675 |<-----------------------------------------+ 1676 | | 1677 | 2.05 Content | 1678 | Token: 0x4a | Notification upon 1679 | Observe: 44 | a state change 1680 | status: "attack-successfully-mitigated" | 1681 |<-----------------------------------------+ 1682 | | 1683 | 2.05 Content | 1684 | Token: 0x4a | Notification upon 1685 | Observe: 60 | a state change 1686 | status: "attack-stopped" | 1687 |<-----------------------------------------+ 1688 | | 1689 ... 1691 Figure 15: Notifications of Attack Mitigation Status 1693 4.4.2.2. DOTS Clients Polling for Mitigation Status 1695 The DOTS client can send the GET request at frequent intervals 1696 without the Observe Option to retrieve the configuration data of the 1697 mitigation request and non-configuration data (i.e., the attack 1698 status). DOTS clients MAY be configured with a policy indicating the 1699 frequency of polling DOTS servers to get the mitigation status. This 1700 frequency MUST NOT be more than one UDP datagram per RTT as discussed 1701 in Section 3.1.3 of [RFC8085]. 1703 If the DOTS server has been able to mitigate the attack and the 1704 attack has stopped, the DOTS server indicates as such in the status. 1705 In such case, the DOTS client withdraws the mitigation request by 1706 issuing a DELETE request for this mitigation request (Section 4.4.4). 1708 A DOTS client SHOULD react to the status of the attack per the 1709 information sent by the DOTS server rather than performing its own 1710 detection that the attack has been mitigated. This ensures that the 1711 DOTS client does not withdraw a mitigation request prematurely 1712 because it is possible that the DOTS client does not sense the DDoS 1713 attack on its resources, but the DOTS server could be actively 1714 mitigating the attack because the attack is not completely averted. 1716 4.4.3. Efficacy Update from DOTS Clients 1718 While DDoS mitigation is in progress, due to the likelihood of packet 1719 loss, a DOTS client MAY periodically transmit DOTS mitigation 1720 efficacy updates to the relevant DOTS server. A PUT request is used 1721 to convey the mitigation efficacy update to the DOTS server. This 1722 PUT request is treated as a refresh of the current mitigation. 1724 The 'attack-status' parameter is a mandatory attribute when 1725 performing an efficacy update. The various possible values contained 1726 in the 'attack-status' parameter are described in Table 4. 1728 +-----------+-------------------------------------+ 1729 | Parameter | Description | 1730 | Value | | 1731 +===========+=====================================+ 1732 | 1 | The DOTS client determines that it | 1733 | | is still under attack. | 1734 +-----------+-------------------------------------+ 1735 | 2 | The DOTS client determines that the | 1736 | | attack is successfully mitigated | 1737 | | (e.g., attack traffic is not seen). | 1738 +-----------+-------------------------------------+ 1740 Table 4: Values of 'attack-status' Parameter 1742 The PUT request used for the efficacy update MUST include all the 1743 parameters used in the PUT request to carry the DOTS mitigation 1744 request (Section 4.4.1) unchanged apart from the 'lifetime' parameter 1745 value. If this is not the case, the DOTS server MUST reject the 1746 request with a 4.00 (Bad Request). 1748 The If-Match Option (Section 5.10.8.1 of [RFC7252]) with an empty 1749 value is used to make the PUT request conditional on the current 1750 existence of the mitigation request. If UDP is used as transport, 1751 CoAP requests may arrive out of order. For example, the DOTS client 1752 may send a PUT request to convey an efficacy update to the DOTS 1753 server followed by a DELETE request to withdraw the mitigation 1754 request, but the DELETE request arrives at the DOTS server before the 1755 PUT request. To handle out-of-order delivery of requests, if an If- 1756 Match Option is present in the PUT request and the 'mid' in the 1757 request matches a mitigation request from that DOTS client, the 1758 request is processed by the DOTS server. If no match is found, the 1759 PUT request is silently ignored by the DOTS server. 1761 An example of an efficacy update message, which includes an If-Match 1762 Option with an empty value, is depicted in Figure 16. 1764 Header: PUT (Code=0.03) 1765 Uri-Path: ".well-known" 1766 Uri-Path: "dots" 1767 Uri-Path: "mitigate" 1768 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1769 Uri-Path: "mid=123" 1770 If-Match: 1771 Content-Format: "application/dots+cbor" 1773 { 1774 "ietf-dots-signal-channel:mitigation-scope": { 1775 "scope": [ 1776 { 1777 "target-prefix": [ 1778 "2001:db8:6401::1/128", 1779 "2001:db8:6401::2/128" 1780 ], 1781 "target-port-range": [ 1782 { 1783 "lower-port": 80 1784 }, 1785 { 1786 "lower-port": 443 1787 }, 1788 { 1789 "lower-port": 8080 1790 } 1791 ], 1792 "target-protocol": [ 1793 6 1794 ], 1795 "attack-status": "under-attack" 1796 } 1797 ] 1798 } 1799 } 1801 Figure 16: An Example of Efficacy Update 1803 The DOTS server indicates the result of processing a PUT request 1804 using CoAP Response Codes. The Response Code 2.04 (Changed) is 1805 returned if the DOTS server has accepted the mitigation efficacy 1806 update. The error Response Code 5.03 (Service Unavailable) is 1807 returned if the DOTS server has erred or is incapable of performing 1808 the mitigation. As specified in [RFC7252], 5.03 uses Max-Age Option 1809 to indicate the number of seconds after which to retry. 1811 4.4.4. Withdraw a Mitigation 1813 DELETE requests are used to withdraw DOTS mitigation requests from 1814 DOTS servers (Figure 17). 1816 'cuid' and 'mid' are mandatory Uri-Path parameters for DELETE 1817 requests. 1819 The same considerations for manipulating 'cdid' parameter by DOTS 1820 gateways, as specified in Section 4.4.1, MUST be followed for DELETE 1821 requests. Uri-Path parameters with empty values MUST NOT be present 1822 in a request. 1824 Header: DELETE (Code=0.04) 1825 Uri-Path: ".well-known" 1826 Uri-Path: "dots" 1827 Uri-Path: "mitigate" 1828 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1829 Uri-Path: "mid=123" 1831 Figure 17: Withdraw a DOTS Mitigation 1833 If the DELETE request does not include 'cuid' and 'mid' parameters, 1834 the DOTS server MUST reply with a 4.00 (Bad Request). 1836 Once the request is validated, the DOTS server immediately 1837 acknowledges a DOTS client's request to withdraw the DOTS mitigation 1838 request using 2.02 (Deleted) Response Code with no response payload. 1839 A 2.02 (Deleted) Response Code is returned even if the 'mid' 1840 parameter value conveyed in the DELETE request does not exist in its 1841 configuration data before the request. 1843 If the DOTS server finds the 'mid' parameter value conveyed in the 1844 DELETE request in its configuration data for the DOTS client, then to 1845 protect against route or DNS flapping caused by a DOTS client rapidly 1846 removing a mitigation, and to dampen the effect of oscillating 1847 attacks, the DOTS server MAY allow mitigation to continue for a 1848 limited period after acknowledging a DOTS client's withdrawal of a 1849 mitigation request. During this period, the DOTS server status 1850 messages SHOULD indicate that mitigation is active but terminating 1851 (Section 4.4.2). 1853 The initial active-but-terminating period SHOULD be sufficiently long 1854 to absorb latency incurred by route propagation. The active-but- 1855 terminating period SHOULD be set by default to 120 seconds. If the 1856 client requests mitigation again before the initial active-but- 1857 terminating period elapses, the DOTS server MAY exponentially 1858 increase (the base of the exponent is 2) the active-but-terminating 1859 period up to a maximum of 300 seconds (5 minutes). 1861 Once the active-but-terminating period elapses, the DOTS server MUST 1862 treat the mitigation as terminated. 1864 If a mitigation is triggered due to a signal channel loss, the DOTS 1865 server relies upon normal triggers to stop that mitigation 1866 (typically, receipt of a valid DELETE request, expiry of the 1867 mitigation lifetime, or scrubbing the traffic to the attack target). 1868 In particular, the DOTS server MUST NOT consider the signal channel 1869 recovery as a trigger to stop the mitigation. 1871 4.5. DOTS Signal Channel Session Configuration 1873 A DOTS client can negotiate, configure, and retrieve the DOTS signal 1874 channel session behavior with its DOTS peers. The DOTS signal 1875 channel can be used, for example, to configure the following: 1877 a. Heartbeat interval ('heartbeat-interval'): DOTS agents regularly 1878 send heartbeats to each other after mutual authentication is 1879 successfully completed in order to keep the DOTS signal channel 1880 open. Heartbeat messages are exchanged between DOTS agents every 1881 'heartbeat-interval' seconds to detect the current status of the 1882 DOTS signal channel session. 1884 b. Missing heartbeats allowed ('missing-hb-allowed'): This variable 1885 indicates the maximum number of consecutive heartbeat messages 1886 for which a DOTS agent did not receive a response before 1887 concluding that the session is disconnected or defunct. 1889 c. Acceptable probing rate ('probing-rate'): This parameter 1890 indicates the average data rate that must not be exceeded by a 1891 DOTS agent in sending to a peer DOTS agent that does not respond. 1893 d. Acceptable signal loss ratio: Maximum retransmissions ('max- 1894 retransmit'), retransmission timeout value ('ack-timeout'), and 1895 other message transmission parameters for Confirmable messages 1896 over the DOTS signal channel. 1898 When the DOTS signal channel is established over a reliable transport 1899 (e.g., TCP), there is no need for the reliability mechanisms provided 1900 by CoAP over UDP since the underlying TCP connection provides 1901 retransmissions and deduplication [RFC8323]. CoAP over reliable 1902 transports does not support Confirmable or Non-confirmable message 1903 types. As such, the transmission-related parameters ('missing-hb- 1904 allowed' and acceptable signal loss ratio) are negotiated only for 1905 DOTS over unreliable transports. 1907 The same or distinct configuration sets may be used during times when 1908 a mitigation is active ('mitigating-config') and when no mitigation 1909 is active ('idle-config'). This is particularly useful for DOTS 1910 servers that might want to reduce heartbeat frequency or cease 1911 heartbeat exchanges when an active DOTS client has not requested 1912 mitigation. If distinct configurations are used, DOTS agents MUST 1913 follow the appropriate configuration set as a function of the 1914 mitigation activity (e.g., if no mitigation request is active (also 1915 referred to as 'idle' time), values related to 'idle-config' must be 1916 followed). Additionally, DOTS agents MUST automatically switch to 1917 the other configuration upon a change in the mitigation activity 1918 (e.g., if an attack mitigation is launched after an 'idle' time, the 1919 DOTS agent switches from values related to 'idle-config' to values 1920 related to 'mitigating-config'). 1922 CoAP requests and responses are indicated for reliable delivery by 1923 marking them as Confirmable messages. DOTS signal channel session 1924 configuration requests and responses are marked as Confirmable 1925 messages. As explained in Section 2.1 of [RFC7252], a Confirmable 1926 message is retransmitted using a default timeout and exponential 1927 backoff between retransmissions, until the DOTS server sends an 1928 Acknowledgement message (ACK) with the same Message ID conveyed from 1929 the DOTS client. 1931 Message transmission parameters are defined in Section 4.8 of 1932 [RFC7252]. The DOTS server can either piggyback the response in the 1933 Acknowledgement message or, if the DOTS server cannot respond 1934 immediately to a request carried in a Confirmable message, it simply 1935 responds with an Empty Acknowledgement message so that the DOTS 1936 client can stop retransmitting the request. Empty Acknowledgement 1937 messages are explained in Section 2.2 of [RFC7252]. When the 1938 response is ready, the server sends it in a new Confirmable message, 1939 which, in turn, needs to be acknowledged by the DOTS client (see 1940 Sections 5.2.1 and 5.2.2 of [RFC7252]). Requests and responses 1941 exchanged between DOTS agents during 'idle' time, except heartbeat 1942 messages, are marked as Confirmable messages. 1944 | Implementation Note: A DOTS client that receives a response in 1945 | a Confirmable message may want to clean up the message state 1946 | right after sending the ACK. If that ACK is lost and the DOTS 1947 | server retransmits the Confirmable message, the DOTS client may 1948 | no longer have any state that would help it correlate this 1949 | response: from the DOTS client's standpoint, the retransmission 1950 | message is unexpected. The DOTS client will send a Reset 1951 | message so it does not receive any more retransmissions. This 1952 | behavior is normal and not an indication of an error (see 1953 | Section 5.3.2 of [RFC7252] for more details). 1955 4.5.1. Discover Configuration Parameters 1957 A GET request is used to obtain acceptable (e.g., minimum and maximum 1958 values) and current configuration parameters on the DOTS server for 1959 DOTS signal channel session configuration. This procedure occurs 1960 between a DOTS client and its immediate peer DOTS server. As such, 1961 this GET request MUST NOT be relayed by a DOTS gateway. 1963 Figure 18 shows how to obtain configuration parameters that the DOTS 1964 server will find acceptable. 1966 Header: GET (Code=0.01) 1967 Uri-Path: ".well-known" 1968 Uri-Path: "dots" 1969 Uri-Path: "config" 1971 Figure 18: GET to Retrieve Configuration 1973 The DOTS server in the 2.05 (Content) response conveys the current, 1974 minimum, and maximum attribute values acceptable by the DOTS server 1975 (Figure 19). 1977 { 1978 "ietf-dots-signal-channel:signal-config": { 1979 "mitigating-config": { 1980 "heartbeat-interval": { 1981 "max-value": number, 1982 "min-value": number, 1983 "current-value": number 1984 }, 1985 "missing-hb-allowed": { 1986 "max-value": number, 1987 "min-value": number, 1988 "current-value": number 1989 }, 1990 "probing-rate": { 1991 "max-value": number, 1992 "min-value": number, 1993 "current-value": number 1994 }, 1995 "max-retransmit": { 1996 "max-value": number, 1997 "min-value": number, 1998 "current-value": number 1999 }, 2000 "ack-timeout": { 2001 "max-value-decimal": "string", 2002 "min-value-decimal": "string", 2003 "current-value-decimal": "string" 2004 }, 2005 "ack-random-factor": { 2006 "max-value-decimal": "string", 2007 "min-value-decimal": "string", 2008 "current-value-decimal": "string" 2009 } 2010 }, 2011 "idle-config": { 2012 "heartbeat-interval": { 2013 "max-value": number, 2014 "min-value": number, 2015 "current-value": number 2016 }, 2017 "missing-hb-allowed": { 2018 "max-value": number, 2019 "min-value": number, 2020 "current-value": number 2021 }, 2022 "probing-rate": { 2023 "max-value": number, 2024 "min-value": number, 2025 "current-value": number 2026 }, 2027 "max-retransmit": { 2028 "max-value": number, 2029 "min-value": number, 2030 "current-value": number 2031 }, 2032 "ack-timeout": { 2033 "max-value-decimal": "string", 2034 "min-value-decimal": "string", 2035 "current-value-decimal": "string" 2036 }, 2037 "ack-random-factor": { 2038 "max-value-decimal": "string", 2039 "min-value-decimal": "string", 2040 "current-value-decimal": "string" 2041 } 2042 } 2043 } 2044 } 2046 Figure 19: GET Configuration Response Body Schema 2048 The parameters in Figure 19 are described below: 2050 mitigating-config: Set of configuration parameters to use when a 2051 mitigation is active. The following parameters may be included: 2053 heartbeat-interval: Time interval in seconds between two 2054 consecutive heartbeat messages. 2056 '0' is used to disable the heartbeat mechanism. 2058 This is an optional attribute. 2060 missing-hb-allowed: Maximum number of consecutive heartbeat 2061 messages for which the DOTS agent did not receive a response 2062 before concluding that the session is disconnected. 2064 This is an optional attribute. 2066 probing-rate: The average data rate, in bytes/second, that must 2067 not be exceeded by a DOTS agent in sending to a peer DOTS agent 2068 that does not respond (referred to as PROBING_RATE parameter in 2069 CoAP). 2071 This is an optional attribute. 2073 max-retransmit: Maximum number of retransmissions for a message 2074 (referred to as MAX_RETRANSMIT parameter in CoAP). 2076 This is an optional attribute. 2078 ack-timeout: Timeout value in seconds used to calculate the 2079 initial retransmission timeout value (referred to as 2080 ACK_TIMEOUT parameter in CoAP). 2082 This is an optional attribute. 2084 ack-random-factor: Random factor used to influence the timing of 2085 retransmissions (referred to as ACK_RANDOM_FACTOR parameter in 2086 CoAP). 2088 This is an optional attribute. 2090 idle-config: Set of configuration parameters to use when no 2091 mitigation is active. This attribute has the same structure as 2092 'mitigating-config'. 2094 Figure 20 shows an example of acceptable and current configuration 2095 parameters on a DOTS server for DOTS signal channel session 2096 configuration. The same acceptable configuration is used during 2097 mitigation and idle times. 2099 { 2100 "ietf-dots-signal-channel:signal-config": { 2101 "mitigating-config": { 2102 "heartbeat-interval": { 2103 "max-value": 240, 2104 "min-value": 15, 2105 "current-value": 30 2106 }, 2107 "missing-hb-allowed": { 2108 "max-value": 20, 2109 "min-value": 3, 2110 "current-value": 15 2111 }, 2112 "probing-rate": { 2113 "max-value": 20, 2114 "min-value": 5, 2115 "current-value": 15 2116 }, 2117 "max-retransmit": { 2118 "max-value": 15, 2119 "min-value": 2, 2120 "current-value": 3 2121 }, 2122 "ack-timeout": { 2123 "max-value-decimal": "30.00", 2124 "min-value-decimal": "1.00", 2125 "current-value-decimal": "2.00" 2126 }, 2127 "ack-random-factor": { 2128 "max-value-decimal": "4.00", 2129 "min-value-decimal": "1.10", 2130 "current-value-decimal": "1.50" 2131 } 2132 }, 2133 "idle-config": { 2134 "heartbeat-interval": { 2135 "max-value": 240, 2136 "min-value": 15, 2137 "current-value": 30 2138 }, 2139 "missing-hb-allowed": { 2140 "max-value": 20, 2141 "min-value": 3, 2142 "current-value": 15 2143 }, 2144 "probing-rate": { 2145 "max-value": 20, 2146 "min-value": 5, 2147 "current-value": 15 2148 }, 2149 "max-retransmit": { 2150 "max-value": 15, 2151 "min-value": 2, 2152 "current-value": 3 2153 }, 2154 "ack-timeout": { 2155 "max-value-decimal": "30.00", 2156 "min-value-decimal": "1.00", 2157 "current-value-decimal": "2.00" 2158 }, 2159 "ack-random-factor": { 2160 "max-value-decimal": "4.00", 2161 "min-value-decimal": "1.10", 2162 "current-value-decimal": "1.50" 2163 } 2164 } 2165 } 2166 } 2168 Figure 20: Example of a Configuration Response Body 2170 4.5.2. Convey DOTS Signal Channel Session Configuration 2172 A PUT request (Figures 21 and 22) is used to convey the configuration 2173 parameters for the signal channel (e.g., heartbeat interval, maximum 2174 retransmissions). Message transmission parameters for CoAP are 2175 defined in Section 4.8 of [RFC7252]. The RECOMMENDED values of 2176 transmission parameter values are 'ack-timeout' (2 seconds), 'max- 2177 retransmit' (3), and 'ack-random-factor' (1.5). In addition to those 2178 parameters, the RECOMMENDED specific DOTS transmission parameter 2179 values are 'heartbeat-interval' (30 seconds) and 'missing-hb-allowed' 2180 (15). 2182 | Note: 'heartbeat-interval' should be tweaked to also assist 2183 | DOTS messages for NAT traversal (SIG-011 of [RFC8612]). 2184 | According to [RFC8085], heartbeat messages must not be sent 2185 | more frequently than once every 15 seconds and should use 2186 | longer intervals when possible. Furthermore, [RFC4787] 2187 | recommends that NATs use a state timeout of 2 minutes or 2188 | longer, but experience shows that sending packets every 15 to 2189 | 30 seconds is necessary to prevent the majority of middleboxes 2190 | from losing state for UDP flows. From that standpoint, the 2191 | RECOMMENDED minimum 'heartbeat-interval' is 15 seconds and the 2192 | RECOMMENDED maximum 'heartbeat-interval' is 240 seconds. The 2193 | recommended value of 30 seconds is selected to anticipate the 2194 | expiry of NAT state. 2195 | 2196 | A 'heartbeat-interval' of 30 seconds may be considered to be 2197 | too chatty in some deployments. For such deployments, DOTS 2198 | agents may negotiate longer 'heartbeat-interval' values to 2199 | prevent any network overload with too frequent heartbeats. 2200 | 2201 | Different heartbeat intervals can be defined for 'mitigating- 2202 | config' and 'idle-config' to reduce being too chatty during 2203 | idle times. If there is an on-path translator between the DOTS 2204 | client (standalone or part of a DOTS gateway) and the DOTS 2205 | server, the 'mitigating-config' 'heartbeat-interval' has to be 2206 | smaller than the translator session timeout. It is recommended 2207 | that the 'idle-config' 'heartbeat-interval' also be smaller 2208 | than the translator session timeout to prevent translator 2209 | traversal issues or that it be disabled entirely. Means to 2210 | discover the lifetime assigned by a translator are out of 2211 | scope. 2212 | 2213 | Given that the size of the heartbeat request cannot exceed 2214 | ('heartbeat-interval' * 'probing-rate') bytes, 'probing-rate' 2215 | should be set appropriately to avoid slowing down heartbeat 2216 | exchanges. For example, 'probing-rate' may be set to 2 * 2217 | ("size of encrypted DOTS heartbeat request"/'heartbeat- 2218 | interval') or (("size of encrypted DOTS heartbeat request" + 2219 | "average size of an encrypted mitigation request")/'heartbeat- 2220 | interval'). Absent any explicit configuration or inability to 2221 | dynamically adjust 'probing-rate' values (Section 4.8.1 of 2222 | [RFC7252]), DOTS agents use 5 bytes/second as a default 2223 | 'probing-rate' value. 2225 If the DOTS agent wishes to change the default values of message 2226 transmission parameters, it SHOULD follow the guidance given in 2227 Section 4.8.1 of [RFC7252]. The DOTS agents MUST use the negotiated 2228 values for message transmission parameters and default values for 2229 non-negotiated message transmission parameters. 2231 The signal channel session configuration is applicable to a single 2232 DOTS signal channel session between DOTS agents, so the 'cuid' Uri- 2233 Path MUST NOT be used. 2235 Header: PUT (Code=0.03) 2236 Uri-Path: ".well-known" 2237 Uri-Path: "dots" 2238 Uri-Path: "config" 2239 Uri-Path: "sid=123" 2240 Content-Format: "application/dots+cbor" 2242 { 2243 ... 2244 } 2246 Figure 21: PUT to Convey the DOTS Signal Channel Session 2247 Configuration Data 2249 The additional Uri-Path parameter to those defined in Table 1 is as 2250 follows: 2252 sid: Session Identifier is an identifier for the DOTS signal channel 2253 session configuration data represented as an integer. This 2254 identifier MUST be generated by DOTS clients. 'sid' values MUST 2255 increase monotonically (when a new PUT is generated by a DOTS 2256 client to convey the configuration parameters for the signal 2257 channel). 2259 This is a mandatory attribute. 2261 { 2262 "ietf-dots-signal-channel:signal-config": { 2263 "mitigating-config": { 2264 "heartbeat-interval": { 2265 "current-value": number 2266 }, 2267 "missing-hb-allowed": { 2268 "current-value": number 2269 }, 2270 "probing-rate": { 2271 "current-value": number 2272 }, 2273 "max-retransmit": { 2274 "current-value": number 2275 }, 2276 "ack-timeout": { 2277 "current-value-decimal": "string" 2278 }, 2279 "ack-random-factor": { 2280 "current-value-decimal": "string" 2281 } 2282 }, 2283 "idle-config": { 2284 "heartbeat-interval": { 2285 "current-value": number 2286 }, 2287 "missing-hb-allowed": { 2288 "current-value": number 2289 }, 2290 "probing-rate": { 2291 "current-value": number 2292 }, 2293 "max-retransmit": { 2294 "current-value": number 2295 }, 2296 "ack-timeout": { 2297 "current-value-decimal": "string" 2298 }, 2299 "ack-random-factor": { 2300 "current-value-decimal": "string" 2301 } 2302 } 2303 } 2304 } 2306 Figure 22: PUT to Convey the DOTS Signal Channel Session 2307 Configuration Data (Message Body Schema) 2309 The meaning of the parameters in the CBOR body (Figure 22) is defined 2310 in Section 4.5.1. 2312 At least one of the attributes 'heartbeat-interval', 'missing-hb- 2313 allowed', 'probing-rate', 'max-retransmit', 'ack-timeout', and 'ack- 2314 random-factor' MUST be present in the PUT request. Note that 2315 'heartbeat-interval', 'missing-hb-allowed', 'probing-rate', 'max- 2316 retransmit', 'ack-timeout', and 'ack-random-factor', if present, do 2317 not need to be provided for both 'mitigating-config', and 'idle- 2318 config' in a PUT request. A request does not need to include both 2319 'mitigating-config' and 'idle-config' attributes. 2321 The PUT request with a higher numeric 'sid' value overrides the DOTS 2322 signal channel session configuration data installed by a PUT request 2323 with a lower numeric 'sid' value. That is, the configuration 2324 parameters that are included in the PUT request with a higher numeric 2325 'sid' value will be used instead of the DOTS server's defaults. To 2326 avoid maintaining a long list of 'sid' requests from a DOTS client, 2327 the lower numeric 'sid' MUST be automatically deleted and no longer 2328 available at the DOTS server. 2330 Figure 23 shows a PUT request example to convey the configuration 2331 parameters for the DOTS signal channel. In this example, the 2332 heartbeat mechanism is disabled when no mitigation is active, while 2333 the heartbeat interval is set to '30' when a mitigation is active. 2335 Header: PUT (Code=0.03) 2336 Uri-Path: ".well-known" 2337 Uri-Path: "dots" 2338 Uri-Path: "config" 2339 Uri-Path: "sid=123" 2340 Content-Format: "application/dots+cbor" 2342 { 2343 "ietf-dots-signal-channel:signal-config": { 2344 "mitigating-config": { 2345 "heartbeat-interval": { 2346 "current-value": 30 2347 }, 2348 "missing-hb-allowed": { 2349 "current-value": 15 2350 }, 2351 "probing-rate": { 2352 "current-value": 15 2353 }, 2354 "max-retransmit": { 2355 "current-value": 3 2356 }, 2357 "ack-timeout": { 2358 "current-value-decimal": "2.00" 2359 }, 2360 "ack-random-factor": { 2361 "current-value-decimal": "1.50" 2362 } 2363 }, 2364 "idle-config": { 2365 "heartbeat-interval": { 2366 "current-value": 0 2367 }, 2368 "max-retransmit": { 2369 "current-value": 3 2370 }, 2371 "ack-timeout": { 2372 "current-value-decimal": "2.00" 2373 }, 2374 "ack-random-factor": { 2375 "current-value-decimal": "1.50" 2376 } 2377 } 2378 } 2379 } 2381 Figure 23: PUT to Convey the Configuration Parameters 2383 The DOTS server indicates the result of processing the PUT request 2384 using CoAP Response Codes: 2386 o If the request is missing a mandatory attribute, does not include 2387 a 'sid' Uri-Path, or contains one or more invalid or unknown 2388 parameters, 4.00 (Bad Request) MUST be returned in the response. 2390 o If the DOTS server does not find the 'sid' parameter value 2391 conveyed in the PUT request in its configuration data and if the 2392 DOTS server has accepted the configuration parameters, then a 2393 Response Code 2.01 (Created) MUST be returned in the response. 2395 o If the DOTS server finds the 'sid' parameter value conveyed in the 2396 PUT request in its configuration data and if the DOTS server has 2397 accepted the updated configuration parameters, 2.04 (Changed) MUST 2398 be returned in the response. 2400 o If any of the 'heartbeat-interval', 'missing-hb-allowed', 2401 'probing-rate', 'max-retransmit', 'target-protocol', 'ack- 2402 timeout', and 'ack-random-factor' attribute values are not 2403 acceptable to the DOTS server, 4.22 (Unprocessable Entity) MUST be 2404 returned in the response. Upon receipt of this error code, the 2405 DOTS client SHOULD retrieve the maximum and minimum attribute 2406 values acceptable to the DOTS server (Section 4.5.1). 2408 The DOTS client may retry and send the PUT request with updated 2409 attribute values acceptable to the DOTS server. 2411 A DOTS client may issue a GET message for 'config' with a 'sid' Uri- 2412 Path parameter to retrieve the negotiated configuration. The 2413 response does not need to include 'sid' in its message body. 2415 4.5.3. Configuration Freshness and Notifications 2417 Max-Age Option (Section 5.10.5 of [RFC7252]) SHOULD be returned by a 2418 DOTS server to associate a validity time with a configuration it 2419 sends. This feature forces the client to retrieve the updated 2420 configuration data if a change occurs at the DOTS server side. For 2421 example, the new configuration may instruct a DOTS client to cease 2422 heartbeats or reduce heartbeat frequency. 2424 It is NOT RECOMMENDED to return a Max-Age Option set to 0. 2426 Returning a Max-Age Option set to 2^(32)-1 is equivalent to 2427 associating an infinite lifetime with the configuration. 2429 If a non-zero value of Max-Age Option is received by a DOTS client, 2430 it MUST issue a GET request with a 'sid' Uri-Path parameter to 2431 retrieve the current and acceptable configuration before the expiry 2432 of the value enclosed in the Max-Age Option. This request is 2433 considered by the client and the server to be a means to refresh the 2434 configuration parameters for the signal channel. When a DDoS attack 2435 is active, refresh requests MUST NOT be sent by DOTS clients, and the 2436 DOTS server MUST NOT terminate the (D)TLS session after the expiry of 2437 the value returned in Max-Age Option. 2439 If Max-Age Option is not returned in a response, the DOTS client 2440 initiates GET requests to refresh the configuration parameters each 2441 60 seconds (Section 5.10.5 of [RFC7252]). To prevent such overload, 2442 it is RECOMMENDED that DOTS servers return a Max-Age Option in GET 2443 responses. Considerations related to which value to use and how such 2444 a value is set are implementation and deployment specific. 2446 If an Observe Option set to 0 is included in the configuration 2447 request, the DOTS server sends notifications of any configuration 2448 change (Section 4.2 of [RFC7641]). 2450 If a DOTS server detects that a misbehaving DOTS client does not 2451 contact the DOTS server after the expiry of Max-Age to retrieve the 2452 signal channel configuration data, it MAY terminate the (D)TLS 2453 session. A (D)TLS session is terminated by the receipt of an 2454 authenticated message that closes the connection (e.g., a fatal alert 2455 (Section 6 of [RFC8446])). 2457 4.5.4. Delete DOTS Signal Channel Session Configuration 2459 A DELETE request is used to delete the installed DOTS signal channel 2460 session configuration data (Figure 24). 2462 Header: DELETE (Code=0.04) 2463 Uri-Path: ".well-known" 2464 Uri-Path: "dots" 2465 Uri-Path: "config" 2466 Uri-Path: "sid=123" 2468 Figure 24: Delete Configuration 2470 The DOTS server resets the DOTS signal channel session configuration 2471 back to the default values and acknowledges a DOTS client's request 2472 to remove the DOTS signal channel session configuration using 2.02 2473 (Deleted) Response Code. 2475 Upon bootstrapping or reboot, a DOTS client MAY send a DELETE request 2476 to set the configuration parameters to default values. Such a 2477 request does not include any 'sid'. 2479 4.6. Redirected Signaling 2481 Redirected DOTS signaling is discussed in detail in Section 3.2.2 of 2482 [RFC8811]. 2484 To redirect a DOTS client to an alternative DOTS server, the DOTS 2485 server can return the error Response Code 5.03 (Service Unavailable) 2486 in response to a request from the DOTS client or convey the error 2487 Response Code 5.03 in a unidirectional notification response to the 2488 client. 2490 The DOTS server in the error response conveys the alternate DOTS 2491 server's FQDN, and the alternate DOTS server's IP address(es) values 2492 in the CBOR body (Figure 25). 2494 { 2495 "ietf-dots-signal-channel:redirected-signal": { 2496 "alt-server": "string", 2497 "alt-server-record": [ 2498 "string" 2499 ] 2500 } 2501 } 2503 Figure 25: Redirected Server Error Response Body Schema 2505 The parameters are described below: 2507 alt-server: FQDN of an alternate DOTS server. 2509 This is a mandatory attribute. 2511 alt-server-record: A list of IP addresses of an alternate DOTS 2512 server. 2514 This is an optional attribute. 2516 The DOTS server returns the Time to Live (TTL) of the alternate DOTS 2517 server in a Max-Age Option. That is, the time interval that the 2518 alternate DOTS server may be cached for use by a DOTS client. A Max- 2519 Age Option set to 2^(32)-1 is equivalent to receiving an infinite 2520 TTL. This value means that the alternate DOTS server is to be used 2521 until the alternate DOTS server redirects the traffic with another 2522 5.03 response that conveys an alternate server's FQDN. 2524 A Max-Age Option set to '0' may be returned for redirecting 2525 mitigation requests. Such a value means that the redirection applies 2526 only for the mitigation request in progress. Returning short TTL in 2527 a Max-Age Option may adversely impact DOTS clients on slow links. 2528 Returning short values should be avoided under such conditions. 2530 If the alternate DOTS server TTL has expired, the DOTS client MUST 2531 use the DOTS server(s) that was provisioned using means discussed in 2532 Section 4.1. This fallback mechanism is triggered immediately upon 2533 expiry of the TTL, except when a DDoS attack is active. 2535 Requests issued by misbehaving DOTS clients that do not honor the TTL 2536 conveyed in the Max-Age Option or react to explicit redirect messages 2537 MAY be rejected by DOTS servers. 2539 Figure 26 shows a 5.03 response example to convey the DOTS alternate 2540 server 'alt-server.example' together with its IP addresses 2541 2001:db8:6401::1 and 2001:db8:6401::2. 2543 { 2544 "ietf-dots-signal-channel:redirected-signal": { 2545 "alt-server": "alt-server.example", 2546 "alt-server-record": [ 2547 "2001:db8:6401::1", 2548 "2001:db8:6401::2" 2549 ] 2550 } 2551 } 2553 Figure 26: Example of Redirected Server Error Response Body 2555 When the DOTS client receives a 5.03 response with an alternate 2556 server included, it considers the current request to have failed, but 2557 it SHOULD try resending the request to the alternate DOTS server. 2558 During a DDoS attack, the DNS server may be the target of another 2559 DDoS attack, the alternate DOTS server's IP addresses conveyed in the 2560 5.03 response help the DOTS client skip the DNS lookup of the 2561 alternate DOTS server, at the cost of trusting the first DOTS server 2562 to provide accurate information. The DOTS client can then try to 2563 establish a UDP or a TCP session with the alternate DOTS server 2564 (Section 4.3). Note that state synchronization (e.g., signal session 2565 configuration, aliases) is assumed to be in place between the 2566 original and alternate DOTS servers; such synchronization means are 2567 out of scope. If session configuration refresh is needed while 2568 redirection is in place, the DOTS client follows the procedure 2569 defined in Section 4.5.3. In 'idle' time and under some conditions 2570 (e.g., infinite configuration lifetime, infinite redirection TTL, and 2571 failure to refresh the configuration), the DOTS client follows the 2572 procedure defined in Section 4.5.2 to negotiate the DOTS signal 2573 channel session configuration with the alternate server. The DOTS 2574 client MAY implement a method to construct IPv4-embedded IPv6 2575 addresses [RFC6052]; this is required to handle the scenario where an 2576 IPv6-only DOTS client communicates with an IPv4-only alternate DOTS 2577 server. 2579 If the DOTS client has been redirected to a DOTS server with which it 2580 has already communicated within the last five (5) minutes, it MUST 2581 ignore the redirection and try to contact other DOTS servers listed 2582 in the local configuration or discovered using dynamic means such as 2583 DHCP or SRV procedures [RFC8973]. It is RECOMMENDED that DOTS 2584 clients support the means to alert administrators about redirect 2585 loops. 2587 4.7. Heartbeat Mechanism 2589 To provide an indication of signal health and to distinguish an 2590 'idle' signal channel from a 'disconnected' or 'defunct' session, the 2591 DOTS agent sends a heartbeat over the signal channel to maintain its 2592 half of the channel (also, aligned with the "consents" recommendation 2593 in Section 6 of [RFC8085]). The DOTS agent similarly expects a 2594 heartbeat from its peer DOTS agent, and it may consider a session 2595 terminated in the prolonged absence of a peer agent heartbeat. 2596 Concretely, while the communication between the DOTS agents is 2597 otherwise quiescent, the DOTS client will probe the DOTS server to 2598 ensure it has maintained cryptographic state and vice versa. Such 2599 probes can also keep the bindings of firewalls and/or stateful 2600 translators alive. This probing reduces the frequency of 2601 establishing a new handshake when a DOTS signal needs to be conveyed 2602 to the DOTS server. 2604 | Implementation Note: Given that CoAP roles can be multiplexed 2605 | over the same session as discussed in [RFC7252] and are already 2606 | supported by CoAP implementations, both the DOTS client and 2607 | server can send DOTS heartbeat requests. 2609 The DOTS heartbeat mechanism uses Non-confirmable PUT requests 2610 (Figure 27) with an expected 2.04 (Changed) Response Code 2611 (Figure 28). This procedure occurs between a DOTS agent and its 2612 immediate peer DOTS agent. As such, this PUT request MUST NOT be 2613 relayed by a DOTS gateway. The PUT request used for DOTS heartbeat 2614 MUST NOT have a 'cuid', 'cdid', or 'mid' Uri-Path. 2616 Header: PUT (Code=0.03) 2617 Uri-Path: ".well-known" 2618 Uri-Path: "dots" 2619 Uri-Path: "hb" 2620 Content-Format: "application/dots+cbor" 2622 { 2623 "ietf-dots-signal-channel:heartbeat": { 2624 "peer-hb-status": true 2625 } 2626 } 2628 Figure 27: PUT to Check Peer DOTS Agent Is Responding 2630 The mandatory 'peer-hb-status' attribute is set to 'true' (or 2631 'false') to indicate that a DOTS agent is (or is not) receiving 2632 heartbeat messages from its peer in the last (2 * 'heartbeat- 2633 interval') period. Such information can be used by a peer DOTS agent 2634 to detect or confirm connectivity issues and react accordingly. For 2635 example, if a DOTS client receives a 2.04 response for its heartbeat 2636 messages but no server-initiated heartbeat messages, the DOTS client 2637 sets 'peer-hb-status' to 'false' in its next heartbeat message. Upon 2638 receipt of this message, the DOTS server then will need to try 2639 another strategy for sending the heartbeats (e.g., adjust the 2640 heartbeat interval or send a server-initiated heartbeat immediately 2641 after receiving a client-initiated heartbeat message). 2643 Header: (Code=2.04) 2645 Figure 28: Response to a DOTS Heartbeat Request (with an Empty Body) 2647 DOTS servers MAY trigger their heartbeat requests immediately after 2648 receiving heartbeat probes from peer DOTS clients. It is the 2649 responsibility of DOTS clients to ensure that on-path translators/ 2650 firewalls are maintaining a binding so that the same external IP 2651 address and/or port number is retained for the DOTS signal channel 2652 session. 2654 Under normal traffic conditions (i.e., no attack is ongoing), if a 2655 DOTS agent does not receive any response from the peer DOTS agent for 2656 'missing-hb-allowed' number of consecutive heartbeat messages, it 2657 concludes that the DOTS signal channel session is disconnected. The 2658 DOTS client MUST then try to reestablish the DOTS signal channel 2659 session, preferably by resuming the (D)TLS session. 2661 | Note: If a new DOTS signal channel session cannot be 2662 | established, the DOTS client SHOULD NOT retry to establish the 2663 | DOTS signal channel session more frequently than every 300 2664 | seconds (5 minutes) and MUST NOT retry more frequently than 2665 | every 60 seconds (1 minute). It is recommended that DOTS 2666 | clients support the means to alert administrators about the 2667 | failure to establish a (D)TLS session. 2669 In case of a massive DDoS attack that saturates the incoming link(s) 2670 to the DOTS client, all traffic from the DOTS server to the DOTS 2671 client will likely be dropped, although the DOTS server receives 2672 heartbeat requests in addition to DOTS messages sent by the DOTS 2673 client. In this scenario, DOTS clients MUST behave differently to 2674 handle message transmission and DOTS signal channel session 2675 liveliness during link saturation: 2677 The DOTS client MUST NOT consider the DOTS signal channel session 2678 terminated even after a maximum 'missing-hb-allowed' threshold is 2679 reached. The DOTS client SHOULD keep on using the current DOTS 2680 signal channel session to send heartbeat requests over it, so that 2681 the DOTS server knows the DOTS client has not disconnected the 2682 DOTS signal channel session. 2684 After the maximum 'missing-hb-allowed' threshold is reached, the 2685 DOTS client SHOULD try to establish a new DOTS signal channel 2686 session. The DOTS client SHOULD send mitigation requests over the 2687 current DOTS signal channel session and, in parallel, send the 2688 mitigation requests over the new DOTS signal channel session. 2689 This may be handled, for example, by resumption of the (D)TLS 2690 session or using 0-RTT mode in DTLS 1.3 to piggyback the 2691 mitigation request in the ClientHello message. 2693 As soon as the link is no longer saturated, if traffic from the 2694 DOTS server reaches the DOTS client over the current DOTS signal 2695 channel session, the DOTS client can stop the new DOTS signal 2696 channel session attempt or if a new DOTS signal channel session is 2697 successful then disconnect the current DOTS signal channel 2698 session. 2700 If the DOTS server receives traffic from the peer DOTS client (e.g., 2701 peer DOTS client-initiated heartbeats) but the maximum 'missing-hb- 2702 allowed' threshold is reached, the DOTS server MUST NOT consider the 2703 DOTS signal channel session disconnected. The DOTS server MUST keep 2704 on using the current DOTS signal channel session so that the DOTS 2705 client can send mitigation requests over the current DOTS signal 2706 channel session. In this case, the DOTS server can identify that the 2707 DOTS client is under attack and that the inbound link to the DOTS 2708 client (domain) is saturated. Furthermore, if the DOTS server does 2709 not receive a mitigation request from the DOTS client, it implies 2710 that the DOTS client has not detected the attack or, if an attack 2711 mitigation is in progress, it implies that the applied DDoS 2712 mitigation actions are not yet effectively handling the DDoS attack 2713 volume. 2715 If the DOTS server does not receive any traffic from the peer DOTS 2716 client during the time span required to exhaust the maximum 'missing- 2717 hb-allowed' threshold, the DOTS server concludes the session is 2718 disconnected. The DOTS server can then trigger preconfigured 2719 mitigation requests for this DOTS client (if any). 2721 In DOTS over TCP, the sender of a DOTS heartbeat message has to allow 2722 up to 'heartbeat-interval' seconds when waiting for a heartbeat 2723 reply. When a failure is detected by a DOTS client, it proceeds with 2724 the session recovery, following the same approach as the one used for 2725 unreliable transports. 2727 5. DOTS Signal Channel YANG Modules 2729 This document defines a YANG module [RFC7950] for DOTS mitigation 2730 scope, DOTS signal channel session configuration data, DOTS 2731 redirection signaling, and DOTS heartbeats. 2733 This YANG module is not intended to be used via NETCONF/RESTCONF for 2734 DOTS server management purposes; such a module is out of the scope of 2735 this document. It serves only to provide abstract data structures. 2736 This document uses the "structure" extension specified in [RFC8791]. 2738 A companion YANG module is defined to include a collection of types 2739 defined by IANA: "iana-dots-signal-channel" (Section 5.2). 2741 5.1. Tree Structure 2743 This document defines the YANG module "ietf-dots-signal-channel", 2744 which has the following tree structure. A DOTS signal message can be 2745 a mitigation, a configuration, a redirect, or a heartbeat message. 2747 This tree structure obsoletes the one described in Section 5.1 of 2748 [RFC8782]. 2750 module: ietf-dots-signal-channel 2752 structure dots-signal: 2753 +-- (message-type)? 2754 +--:(mitigation-scope) 2755 | +-- scope* [] 2756 | +-- target-prefix* inet:ip-prefix 2757 | +-- target-port-range* [lower-port] 2758 | | +-- lower-port inet:port-number 2759 | | +-- upper-port? inet:port-number 2760 | +-- target-protocol* uint8 2761 | +-- target-fqdn* inet:domain-name 2762 | +-- target-uri* inet:uri 2763 | +-- alias-name* string 2764 | +-- lifetime? union 2765 | +-- trigger-mitigation? boolean 2766 | +-- (direction)? 2767 | +--:(server-to-client-only) 2768 | | +-- mid? uint32 2769 | | +-- mitigation-start? uint64 2770 | | +-- status? 2771 | | | iana-dots-signal:status 2772 | | +-- conflict-information 2773 | | | +-- conflict-status? 2774 | | | | iana-dots-signal:conflict-status 2775 | | | +-- conflict-cause? 2776 | | | | iana-dots-signal:conflict-cause 2777 | | | +-- retry-timer? uint32 2778 | | | +-- conflict-scope 2779 | | | +-- target-prefix* inet:ip-prefix 2780 | | | +-- target-port-range* [lower-port] 2781 | | | | +-- lower-port inet:port-number 2782 | | | | +-- upper-port? inet:port-number 2783 | | | +-- target-protocol* uint8 2784 | | | +-- target-fqdn* inet:domain-name 2785 | | | +-- target-uri* inet:uri 2786 | | | +-- alias-name* string 2787 | | | +-- acl-list* [acl-name] 2788 | | | | +-- acl-name leafref 2789 | | | | +-- acl-type? leafref 2790 | | | +-- mid? uint32 2791 | | +-- bytes-dropped? 2792 | | | yang:zero-based-counter64 2793 | | +-- bps-dropped? yang:gauge64 2794 | | +-- pkts-dropped? 2795 | | | yang:zero-based-counter64 2796 | | +-- pps-dropped? yang:gauge64 2797 | +--:(client-to-server-only) 2798 | +-- attack-status? 2799 | iana-dots-signal:attack-status 2800 +--:(signal-config) 2801 | +-- mitigating-config 2802 | | +-- heartbeat-interval 2803 | | | +-- (direction)? 2804 | | | | +--:(server-to-client-only) 2805 | | | | +-- max-value? uint16 2806 | | | | +-- min-value? uint16 2807 | | | +-- current-value? uint16 2808 | | +-- missing-hb-allowed 2809 | | | +-- (direction)? 2810 | | | | +--:(server-to-client-only) 2811 | | | | +-- max-value? uint16 2812 | | | | +-- min-value? uint16 2813 | | | +-- current-value? uint16 2814 | | +-- probing-rate 2815 | | | +-- (direction)? 2816 | | | | +--:(server-to-client-only) 2817 | | | | +-- max-value? uint16 2818 | | | | +-- min-value? uint16 2819 | | | +-- current-value? uint16 2820 | | +-- max-retransmit 2821 | | | +-- (direction)? 2822 | | | | +--:(server-to-client-only) 2823 | | | | +-- max-value? uint16 2824 | | | | +-- min-value? uint16 2825 | | | +-- current-value? uint16 2826 | | +-- ack-timeout 2827 | | | +-- (direction)? 2828 | | | | +--:(server-to-client-only) 2829 | | | | +-- max-value-decimal? decimal64 2830 | | | | +-- min-value-decimal? decimal64 2831 | | | +-- current-value-decimal? decimal64 2832 | | +-- ack-random-factor 2833 | | +-- (direction)? 2834 | | | +--:(server-to-client-only) 2835 | | | +-- max-value-decimal? decimal64 2836 | | | +-- min-value-decimal? decimal64 2837 | | +-- current-value-decimal? decimal64 2838 | +-- idle-config 2839 | +-- heartbeat-interval 2840 | | +-- (direction)? 2841 | | | +--:(server-to-client-only) 2842 | | | +-- max-value? uint16 2843 | | | +-- min-value? uint16 2844 | | +-- current-value? uint16 2845 | +-- missing-hb-allowed 2846 | | +-- (direction)? 2847 | | | +--:(server-to-client-only) 2848 | | | +-- max-value? uint16 2849 | | | +-- min-value? uint16 2850 | | +-- current-value? uint16 2851 | +-- probing-rate 2852 | | +-- (direction)? 2853 | | | +--:(server-to-client-only) 2854 | | | +-- max-value? uint16 2855 | | | +-- min-value? uint16 2856 | | +-- current-value? uint16 2857 | +-- max-retransmit 2858 | | +-- (direction)? 2859 | | | +--:(server-to-client-only) 2860 | | | +-- max-value? uint16 2861 | | | +-- min-value? uint16 2862 | | +-- current-value? uint16 2863 | +-- ack-timeout 2864 | | +-- (direction)? 2865 | | | +--:(server-to-client-only) 2866 | | | +-- max-value-decimal? decimal64 2867 | | | +-- min-value-decimal? decimal64 2868 | | +-- current-value-decimal? decimal64 2869 | +-- ack-random-factor 2870 | +-- (direction)? 2871 | | +--:(server-to-client-only) 2872 | | +-- max-value-decimal? decimal64 2873 | | +-- min-value-decimal? decimal64 2874 | +-- current-value-decimal? decimal64 2875 +--:(redirected-signal) 2876 | +-- (direction)? 2877 | +--:(server-to-client-only) 2878 | +-- alt-server inet:domain-name 2879 | +-- alt-server-record* inet:ip-address 2880 +--:(heartbeat) 2881 +-- peer-hb-status boolean 2883 5.2. IANA DOTS Signal Channel YANG Module 2885 This version obsoletes the version described in Section 5.2 of 2886 [RFC8782]. 2888 file "iana-dots-signal-channel@2020-09-24.yang" 2889 module iana-dots-signal-channel { 2890 yang-version 1.1; 2891 namespace "urn:ietf:params:xml:ns:yang:iana-dots-signal-channel"; 2892 prefix iana-dots-signal; 2894 organization 2895 "IANA"; 2896 contact 2897 "Internet Assigned Numbers Authority 2898 Postal: ICANN 2899 12025 Waterfront Drive, Suite 300 2900 Los Angeles, CA 90094-2536 2901 United States of America 2902 Tel: +1 310 301 5800 2903 "; 2904 description 2905 "This module contains a collection of YANG data types defined 2906 by IANA and used for DOTS signal channel protocol. 2908 Copyright (c) 2021 IETF Trust and the persons identified as 2909 authors of the code. All rights reserved. 2911 Redistribution and use in source and binary forms, with or 2912 without modification, is permitted pursuant to, and subject 2913 to the license terms contained in, the Simplified BSD License 2914 set forth in Section 4.c of the IETF Trust's Legal Provisions 2915 Relating to IETF Documents 2916 (http://trustee.ietf.org/license-info). 2918 This version of this YANG module is part of RFC 8782; see 2919 the RFC itself for full legal notices."; 2921 revision 2020-09-24 { 2922 description 2923 "Updated the prefix used for the module."; 2924 reference 2925 "RFC XXXX: Distributed Denial-of-Service Open Threat 2926 Signaling (DOTS) Signal Channel Specification"; 2927 } 2929 revision 2020-05-28 { 2930 description 2931 "Initial revision."; 2932 reference 2933 "RFC 8782: Distributed Denial-of-Service Open Threat 2934 Signaling (DOTS) Signal Channel Specification"; 2935 } 2937 typedef status { 2938 type enumeration { 2939 enum attack-mitigation-in-progress { 2940 value 1; 2941 description 2942 "Attack mitigation setup is in progress (e.g., changing 2943 the network path to reroute the inbound traffic 2944 to DOTS mitigator)."; 2945 } 2946 enum attack-successfully-mitigated { 2947 value 2; 2948 description 2949 "Attack is being successfully mitigated (e.g., traffic 2950 is redirected to a DDoS mitigator and attack 2951 traffic is dropped or blackholed)."; 2952 } 2953 enum attack-stopped { 2954 value 3; 2955 description 2956 "Attack has stopped and the DOTS client can 2957 withdraw the mitigation request."; 2958 } 2959 enum attack-exceeded-capability { 2960 value 4; 2961 description 2962 "Attack has exceeded the mitigation provider 2963 capability."; 2964 } 2965 enum dots-client-withdrawn-mitigation { 2966 value 5; 2967 description 2968 "DOTS client has withdrawn the mitigation 2969 request and the mitigation is active but 2970 terminating."; 2971 } 2972 enum attack-mitigation-terminated { 2973 value 6; 2974 description 2975 "Attack mitigation is now terminated."; 2976 } 2977 enum attack-mitigation-withdrawn { 2978 value 7; 2979 description 2980 "Attack mitigation is withdrawn."; 2981 } 2982 enum attack-mitigation-signal-loss { 2983 value 8; 2984 description 2985 "Attack mitigation will be triggered 2986 for the mitigation request only when 2987 the DOTS signal channel session is lost."; 2988 } 2989 } 2990 description 2991 "Enumeration for status reported by the DOTS server."; 2992 } 2993 typedef conflict-status { 2994 type enumeration { 2995 enum request-inactive-other-active { 2996 value 1; 2997 description 2998 "DOTS Server has detected conflicting mitigation 2999 requests from different DOTS clients. 3000 This mitigation request is currently inactive 3001 until the conflicts are resolved. Another 3002 mitigation request is active."; 3003 } 3004 enum request-active { 3005 value 2; 3006 description 3007 "DOTS Server has detected conflicting mitigation 3008 requests from different DOTS clients. 3009 This mitigation request is currently active."; 3010 } 3011 enum all-requests-inactive { 3012 value 3; 3013 description 3014 "DOTS Server has detected conflicting mitigation 3015 requests from different DOTS clients. All 3016 conflicting mitigation requests are inactive."; 3017 } 3018 } 3019 description 3020 "Enumeration for conflict status."; 3021 } 3023 typedef conflict-cause { 3024 type enumeration { 3025 enum overlapping-targets { 3026 value 1; 3027 description 3028 "Overlapping targets. conflict-scope provides 3029 more details about the exact conflict."; 3030 } 3031 enum conflict-with-acceptlist { 3032 value 2; 3033 description 3034 "Conflicts with an existing accept-list. 3036 This code is returned when the DDoS mitigation 3037 detects that some of the source addresses/prefixes 3038 listed in the accept-list ACLs are actually 3039 attacking the target."; 3040 } 3041 enum cuid-collision { 3042 value 3; 3043 description 3044 "Conflicts with the cuid used by another 3045 DOTS client."; 3046 } 3047 } 3048 description 3049 "Enumeration for conflict causes."; 3050 } 3052 typedef attack-status { 3053 type enumeration { 3054 enum under-attack { 3055 value 1; 3056 description 3057 "The DOTS client determines that it is still under 3058 attack."; 3059 } 3060 enum attack-successfully-mitigated { 3061 value 2; 3062 description 3063 "The DOTS client determines that the attack is 3064 successfully mitigated."; 3065 } 3066 } 3067 description 3068 "Enumeration for attack status codes."; 3069 } 3070 } 3071 3073 5.3. IETF DOTS Signal Channel YANG Module 3075 This module uses the common YANG types defined in [RFC6991] and types 3076 defined in [RFC8783]. 3078 This version obsoletes the version described in Section 5.3 of 3079 [RFC8782]. 3081 file "ietf-dots-signal-channel@2021-03-02.yang" 3082 module ietf-dots-signal-channel { 3083 yang-version 1.1; 3084 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel"; 3085 prefix dots-signal; 3087 import ietf-inet-types { 3088 prefix inet; 3089 reference 3090 "Section 4 of RFC 6991"; 3091 } 3092 import ietf-yang-types { 3093 prefix yang; 3094 reference 3095 "Section 3 of RFC 6991"; 3096 } 3097 import ietf-dots-data-channel { 3098 prefix data-channel; 3099 reference 3100 "RFC 8783: Distributed Denial-of-Service Open Threat Signaling 3101 (DOTS) Data Channel Specification"; 3102 } 3103 import iana-dots-signal-channel { 3104 prefix iana-dots-signal; 3105 reference 3106 "RFC XXXX: Distributed Denial-of-Service Open Threat Signaling 3107 (DOTS) Signal Channel Specification"; 3108 } 3109 import ietf-yang-structure-ext { 3110 prefix sx; 3111 reference 3112 "RFC 8791: YANG Data Structure Extensions"; 3113 } 3115 organization 3116 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 3117 contact 3118 "WG Web: 3119 WG List: 3121 Editor: Mohamed Boucadair 3122 3124 Editor: Jon Shallow 3125 3127 Author: Konda, Tirumaleswar Reddy.K 3128 3130 Author: Prashanth Patil 3131 3133 Author: Andrew Mortensen 3134 3136 Author: Nik Teague 3137 "; 3138 description 3139 "This module contains YANG definition for the signaling 3140 messages exchanged between a DOTS client and a DOTS server. 3142 Copyright (c) 2021 IETF Trust and the persons identified as 3143 authors of the code. All rights reserved. 3145 Redistribution and use in source and binary forms, with or 3146 without modification, is permitted pursuant to, and subject 3147 to the license terms contained in, the Simplified BSD License 3148 set forth in Section 4.c of the IETF Trust's Legal Provisions 3149 Relating to IETF Documents 3150 (http://trustee.ietf.org/license-info). 3152 This version of this YANG module is part of RFC XXXX; see 3153 the RFC itself for full legal notices."; 3155 revision 2021-03-02 { 3156 description 3157 "Updated revision to comply with RFC8791. 3159 This version is not backward compatible with the version 3160 published in RFC 8782."; 3161 reference 3162 "RFC XXXX: Distributed Denial-of-Service Open Threat 3163 Signaling (DOTS) Signal Channel Specification"; 3164 } 3165 revision 2020-05-28 { 3166 description 3167 "Initial revision."; 3168 reference 3169 "RFC 8782: Distributed Denial-of-Service Open Threat 3170 Signaling (DOTS) Signal Channel Specification"; 3171 } 3173 /* 3174 * Groupings 3175 */ 3177 grouping mitigation-scope { 3178 description 3179 "Specifies the scope of the mitigation request."; 3180 list scope { 3181 description 3182 "The scope of the request."; 3183 uses data-channel:target; 3184 leaf-list alias-name { 3185 type string; 3186 description 3187 "An alias name that points to a resource."; 3188 } 3189 leaf lifetime { 3190 type union { 3191 type uint32; 3192 type int32 { 3193 range "-1"; 3194 } 3195 } 3196 units "seconds"; 3197 default "3600"; 3198 description 3199 "Indicates the lifetime of the mitigation request. 3201 A lifetime of '0' in a mitigation request is an 3202 invalid value. 3204 A lifetime of negative one (-1) indicates indefinite 3205 lifetime for the mitigation request. 3207 Lifetime is mandatory in a mitigation request. 3209 The DOTS server must always indicate the actual lifetime 3210 in the response to an accepted mitigation request and the 3211 remaining lifetime in status messages sent to the 3212 DOTS client."; 3213 } 3214 leaf trigger-mitigation { 3215 type boolean; 3216 default "true"; 3217 description 3218 "If set to 'false', DDoS mitigation will not be 3219 triggered unless the DOTS signal channel 3220 session is lost."; 3221 } 3222 choice direction { 3223 description 3224 "Indicates the communication direction in which the 3225 data nodes can be included."; 3226 case server-to-client-only { 3227 description 3228 "These data nodes appear only in a mitigation message 3229 sent from the server to the client."; 3230 leaf mid { 3231 type uint32; 3232 description 3233 "Mitigation request identifier. 3235 This identifier must be unique for each mitigation 3236 request bound to the DOTS client."; 3237 } 3238 leaf mitigation-start { 3239 type uint64; 3240 description 3241 "Mitigation start time is represented in seconds 3242 relative to 1970-01-01T00:00:00Z in UTC time. 3244 This is a mandatory attribute when an attack mitigation 3245 is active. It must not be returned for a 3246 mitigation with 'status' code set to 8."; 3247 } 3248 leaf status { 3249 type iana-dots-signal:status; 3250 description 3251 "Indicates the status of a mitigation request. 3252 It must be included in responses only. 3254 This is a mandatory attribute if a mitigation 3255 request is accepted and processed by the server."; 3256 } 3257 container conflict-information { 3258 description 3259 "Indicates that a conflict is detected."; 3260 leaf conflict-status { 3261 type iana-dots-signal:conflict-status; 3262 description 3263 "Indicates the conflict status."; 3264 } 3265 leaf conflict-cause { 3266 type iana-dots-signal:conflict-cause; 3267 description 3268 "Indicates the cause of the conflict."; 3269 } 3270 leaf retry-timer { 3271 type uint32; 3272 units "seconds"; 3273 description 3274 "The DOTS client must not resend the 3275 same request that has a conflict before the expiry of 3276 this timer."; 3277 } 3278 container conflict-scope { 3279 description 3280 "Provides more information about the conflict scope."; 3282 uses data-channel:target { 3283 when "/dots-signal/scope/conflict-information/" 3284 + "conflict-cause = 'overlapping-targets'"; 3285 } 3286 leaf-list alias-name { 3287 when "../../conflict-cause = 'overlapping-targets'"; 3288 type string; 3289 description 3290 "Conflicting alias-name."; 3291 } 3292 list acl-list { 3293 when "../../conflict-cause =" 3294 + " 'conflict-with-acceptlist'"; 3295 key "acl-name"; 3296 description 3297 "List of conflicting ACLs as defined in the DOTS data 3298 channel. These ACLs are uniquely defined by 3299 cuid and acl-name."; 3300 leaf acl-name { 3301 type leafref { 3302 path "/data-channel:dots-data" 3303 + "/data-channel:dots-client/data-channel:acls" 3304 + "/data-channel:acl/data-channel:name"; 3305 } 3306 description 3307 "Reference to the conflicting ACL name bound to 3308 a DOTS client."; 3309 } 3310 leaf acl-type { 3311 type leafref { 3312 path "/data-channel:dots-data" 3313 + "/data-channel:dots-client/data-channel:acls" 3314 + "/data-channel:acl/data-channel:type"; 3315 } 3316 description 3317 "Reference to the conflicting ACL type bound to 3318 a DOTS client."; 3319 } 3320 } 3321 leaf mid { 3322 when "../../conflict-cause = 'overlapping-targets'"; 3323 type uint32; 3324 description 3325 "Reference to the conflicting 'mid' bound to 3326 the same DOTS client."; 3327 } 3328 } 3329 } 3330 leaf bytes-dropped { 3331 type yang:zero-based-counter64; 3332 units "bytes"; 3333 description 3334 "The total dropped byte count for the mitigation 3335 request since the attack mitigation was triggered. 3336 The count wraps around when it reaches the maximum value 3337 of counter64 for dropped bytes."; 3338 } 3339 leaf bps-dropped { 3340 type yang:gauge64; 3341 units "bytes per second"; 3342 description 3343 "The average number of dropped bytes per second for 3344 the mitigation request since the attack 3345 mitigation was triggered. This should be over 3346 five-minute intervals (that is, measuring bytes 3347 into five-minute buckets and then averaging these 3348 buckets over the time since the mitigation was 3349 triggered)."; 3350 } 3351 leaf pkts-dropped { 3352 type yang:zero-based-counter64; 3353 description 3354 "The total number of dropped packet count for the 3355 mitigation request since the attack mitigation was 3356 triggered. The count wraps around when it reaches 3357 the maximum value of counter64 for dropped packets."; 3358 } 3359 leaf pps-dropped { 3360 type yang:gauge64; 3361 units "packets per second"; 3362 description 3363 "The average number of dropped packets per second 3364 for the mitigation request since the attack 3365 mitigation was triggered. This should be over 3366 five-minute intervals (that is, measuring packets 3367 into five-minute buckets and then averaging these 3368 buckets over the time since the mitigation was 3369 triggered)."; 3370 } 3371 } 3372 case client-to-server-only { 3373 description 3374 "These data nodes appear only in a mitigation message 3375 sent from the client to the server."; 3376 leaf attack-status { 3377 type iana-dots-signal:attack-status; 3378 description 3379 "Indicates the status of an attack as seen by the 3380 DOTS client. 3382 This is a mandatory attribute when a client 3383 performs an efficacy update."; 3384 } 3385 } 3386 } 3387 } 3388 } 3390 grouping config-parameters { 3391 description 3392 "Subset of DOTS signal channel session configuration."; 3393 container heartbeat-interval { 3394 description 3395 "DOTS agents regularly send heartbeats to each other 3396 after mutual authentication is successfully 3397 completed in order to keep the DOTS signal channel 3398 open."; 3399 choice direction { 3400 description 3401 "Indicates the communication direction in which the 3402 data nodes can be included."; 3403 case server-to-client-only { 3404 description 3405 "These data nodes appear only in a mitigation message 3406 sent from the server to the client."; 3407 leaf max-value { 3408 type uint16; 3409 units "seconds"; 3410 description 3411 "Maximum acceptable heartbeat-interval value."; 3412 } 3413 leaf min-value { 3414 type uint16; 3415 units "seconds"; 3416 description 3417 "Minimum acceptable heartbeat-interval value."; 3418 } 3419 } 3420 } 3421 leaf current-value { 3422 type uint16; 3423 units "seconds"; 3424 default "30"; 3425 description 3426 "Current heartbeat-interval value. 3428 '0' means that heartbeat mechanism is deactivated."; 3429 } 3430 } 3431 container missing-hb-allowed { 3432 description 3433 "Maximum number of missing heartbeats allowed."; 3434 choice direction { 3435 description 3436 "Indicates the communication direction in which the 3437 data nodes can be included."; 3438 case server-to-client-only { 3439 description 3440 "These data nodes appear only in a mitigation message 3441 sent from the server to the client."; 3442 leaf max-value { 3443 type uint16; 3444 description 3445 "Maximum acceptable missing-hb-allowed value."; 3446 } 3447 leaf min-value { 3448 type uint16; 3449 description 3450 "Minimum acceptable missing-hb-allowed value."; 3451 } 3452 } 3453 } 3454 leaf current-value { 3455 type uint16; 3456 default "15"; 3457 description 3458 "Current missing-hb-allowed value."; 3459 } 3460 } 3461 container probing-rate { 3462 description 3463 "The limit for sending Non-confirmable messages with 3464 no response."; 3465 choice direction { 3466 description 3467 "Indicates the communication direction in which the 3468 data nodes can be included."; 3469 case server-to-client-only { 3470 description 3471 "These data nodes appear only in a mitigation message 3472 sent from the server to the client."; 3473 leaf max-value { 3474 type uint16; 3475 units "byte/second"; 3476 description 3477 "Maximum acceptable probing-rate value."; 3478 } 3479 leaf min-value { 3480 type uint16; 3481 units "byte/second"; 3482 description 3483 "Minimum acceptable probing-rate value."; 3484 } 3485 } 3486 } 3487 leaf current-value { 3488 type uint16; 3489 units "byte/second"; 3490 default "5"; 3491 description 3492 "Current probing-rate value."; 3493 } 3494 } 3495 container max-retransmit { 3496 description 3497 "Maximum number of retransmissions of a Confirmable 3498 message."; 3499 choice direction { 3500 description 3501 "Indicates the communication direction in which the 3502 data nodes can be included."; 3503 case server-to-client-only { 3504 description 3505 "These data nodes appear only in a mitigation message 3506 sent from the server to the client."; 3507 leaf max-value { 3508 type uint16; 3509 description 3510 "Maximum acceptable max-retransmit value."; 3511 } 3512 leaf min-value { 3513 type uint16; 3514 description 3515 "Minimum acceptable max-retransmit value."; 3516 } 3517 } 3518 } 3519 leaf current-value { 3520 type uint16; 3521 default "3"; 3522 description 3523 "Current max-retransmit value."; 3524 } 3525 } 3526 container ack-timeout { 3527 description 3528 "Initial retransmission timeout value."; 3529 choice direction { 3530 description 3531 "Indicates the communication direction in which the 3532 data nodes can be included."; 3533 case server-to-client-only { 3534 description 3535 "These data nodes appear only in a mitigation message 3536 sent from the server to the client."; 3537 leaf max-value-decimal { 3538 type decimal64 { 3539 fraction-digits 2; 3540 } 3541 units "seconds"; 3542 description 3543 "Maximum ack-timeout value."; 3544 } 3545 leaf min-value-decimal { 3546 type decimal64 { 3547 fraction-digits 2; 3548 } 3549 units "seconds"; 3550 description 3551 "Minimum ack-timeout value."; 3552 } 3553 } 3554 } 3555 leaf current-value-decimal { 3556 type decimal64 { 3557 fraction-digits 2; 3558 } 3559 units "seconds"; 3560 default "2"; 3561 description 3562 "Current ack-timeout value."; 3563 } 3564 } 3565 container ack-random-factor { 3566 description 3567 "Random factor used to influence the timing of 3568 retransmissions."; 3569 choice direction { 3570 description 3571 "Indicates the communication direction in which the 3572 data nodes can be included."; 3573 case server-to-client-only { 3574 description 3575 "These data nodes appear only in a mitigation message 3576 sent from the server to the client."; 3577 leaf max-value-decimal { 3578 type decimal64 { 3579 fraction-digits 2; 3580 } 3581 description 3582 "Maximum acceptable ack-random-factor value."; 3583 } 3584 leaf min-value-decimal { 3585 type decimal64 { 3586 fraction-digits 2; 3587 } 3588 description 3589 "Minimum acceptable ack-random-factor value."; 3590 } 3591 } 3592 } 3593 leaf current-value-decimal { 3594 type decimal64 { 3595 fraction-digits 2; 3596 } 3597 default "1.5"; 3598 description 3599 "Current ack-random-factor value."; 3600 } 3601 } 3602 } 3604 grouping signal-config { 3605 description 3606 "DOTS signal channel session configuration."; 3607 container mitigating-config { 3608 description 3609 "Configuration parameters to use when a mitigation 3610 is active."; 3611 uses config-parameters; 3612 } 3613 container idle-config { 3614 description 3615 "Configuration parameters to use when no mitigation 3616 is active."; 3617 uses config-parameters; 3619 } 3620 } 3622 grouping redirected-signal { 3623 description 3624 "Grouping for the redirected signaling."; 3625 choice direction { 3626 description 3627 "Indicates the communication direction in which the 3628 data nodes can be included."; 3629 case server-to-client-only { 3630 description 3631 "These data nodes appear only in a mitigation message 3632 sent from the server to the client."; 3633 leaf alt-server { 3634 type inet:domain-name; 3635 mandatory true; 3636 description 3637 "FQDN of an alternate server."; 3638 } 3639 leaf-list alt-server-record { 3640 type inet:ip-address; 3641 description 3642 "List of records for the alternate server."; 3643 } 3644 } 3645 } 3646 } 3648 /* 3649 * DOTS Signal Channel Structure 3650 */ 3652 sx:structure dots-signal { 3653 description 3654 "Main structure for DOTS signal message. 3656 A DOTS signal message can be a mitigation, a configuration, 3657 a redirected, or a heartbeat signal message."; 3658 choice message-type { 3659 description 3660 "Can be a mitigation, a configuration, a redirect, or 3661 a heartbeat message."; 3662 case mitigation-scope { 3663 description 3664 "Mitigation scope of a mitigation message."; 3665 uses mitigation-scope; 3666 } 3667 case signal-config { 3668 description 3669 "Configuration message."; 3670 uses signal-config; 3671 } 3672 case redirected-signal { 3673 description 3674 "Redirected signaling."; 3675 uses redirected-signal; 3676 } 3677 case heartbeat { 3678 description 3679 "DOTS heartbeats."; 3680 leaf peer-hb-status { 3681 type boolean; 3682 mandatory true; 3683 description 3684 "Indicates whether a DOTS agent receives heartbeats 3685 from its peer. The value is set to 'true' if the 3686 DOTS agent is receiving heartbeat messages 3687 from its peer."; 3688 } 3689 } 3690 } 3691 } 3692 } 3693 3695 6. YANG/JSON Mapping Parameters to CBOR 3697 All parameters in the payload of the DOTS signal channel MUST be 3698 mapped to CBOR types as shown in Table 5 and are assigned an integer 3699 key to save space. 3701 Note: Implementers must check that the mapping output provided by 3702 their YANG-to-CBOR encoding schemes is aligned with the content of 3703 Table 5. For example, some CBOR and JSON types for enumerations 3704 and the 64-bit quantities can differ depending on the encoder 3705 used. 3707 The CBOR key values are divided into two types: comprehension- 3708 required and comprehension-optional. DOTS agents can safely ignore 3709 comprehension-optional values they don't understand, but they cannot 3710 successfully process a request if it contains comprehension-required 3711 values that are not understood. The 4.00 response SHOULD include a 3712 diagnostic payload describing the unknown comprehension-required CBOR 3713 key values. The initial set of CBOR key values defined in this 3714 specification are of type comprehension-required. 3716 +---------------------+--------------+------+-------------+--------+ 3717 | Parameter Name | YANG Type | CBOR | CBOR Major | JSON | 3718 | | | Key | Type & | Type | 3719 | | | | Information | | 3720 +=====================+==============+======+=============+========+ 3721 | ietf-dots-signal- | container | 1 | 5 map | Object | 3722 | channel:mitigation- | | | | | 3723 | scope | | | | | 3724 +---------------------+--------------+------+-------------+--------+ 3725 | scope | list | 2 | 4 array | Array | 3726 +---------------------+--------------+------+-------------+--------+ 3727 | cdid | string | 3 | 3 text | String | 3728 | | | | string | | 3729 +---------------------+--------------+------+-------------+--------+ 3730 | cuid | string | 4 | 3 text | String | 3731 | | | | string | | 3732 +---------------------+--------------+------+-------------+--------+ 3733 | mid | uint32 | 5 | 0 unsigned | Number | 3734 +---------------------+--------------+------+-------------+--------+ 3735 | target-prefix | leaf-list | 6 | 4 array | Array | 3736 | +--------------+------+-------------+--------+ 3737 | | inet:ip- | | 3 text | String | 3738 | | prefix | | string | | 3739 +---------------------+--------------+------+-------------+--------+ 3740 | target-port-range | list | 7 | 4 array | Array | 3741 +---------------------+--------------+------+-------------+--------+ 3742 | lower-port | inet:port- | 8 | 0 unsigned | Number | 3743 | | number | | | | 3744 +---------------------+--------------+------+-------------+--------+ 3745 | upper-port | inet:port- | 9 | 0 unsigned | Number | 3746 | | number | | | | 3747 +---------------------+--------------+------+-------------+--------+ 3748 | target-protocol | leaf-list | 10 | 4 array | Array | 3749 | +--------------+------+-------------+--------+ 3750 | | uint8 | | 0 unsigned | Number | 3751 +---------------------+--------------+------+-------------+--------+ 3752 | target-fqdn | leaf-list | 11 | 4 array | Array | 3753 | +--------------+------+-------------+--------+ 3754 | | inet:domain- | | 3 text | String | 3755 | | name | | string | | 3756 +---------------------+--------------+------+-------------+--------+ 3757 | target-uri | leaf-list | 12 | 4 array | Array | 3758 | +--------------+------+-------------+--------+ 3759 | | inet:uri | | 3 text | String | 3760 | | | | string | | 3761 +---------------------+--------------+------+-------------+--------+ 3762 | alias-name | leaf-list | 13 | 4 array | Array | 3763 | +--------------+------+-------------+--------+ 3764 | | string | | 3 text | String | 3765 | | | | string | | 3766 +---------------------+--------------+------+-------------+--------+ 3767 | lifetime | union | 14 | 0 unsigned | Number | 3768 | | | +-------------+--------+ 3769 | | | | 1 negative | Number | 3770 +---------------------+--------------+------+-------------+--------+ 3771 | mitigation-start | uint64 | 15 | 0 unsigned | String | 3772 +---------------------+--------------+------+-------------+--------+ 3773 | status | enumeration | 16 | 0 unsigned | String | 3774 +---------------------+--------------+------+-------------+--------+ 3775 | conflict- | container | 17 | 5 map | Object | 3776 | information | | | | | 3777 +---------------------+--------------+------+-------------+--------+ 3778 | conflict-status | enumeration | 18 | 0 unsigned | String | 3779 +---------------------+--------------+------+-------------+--------+ 3780 | conflict-cause | enumeration | 19 | 0 unsigned | String | 3781 +---------------------+--------------+------+-------------+--------+ 3782 | retry-timer | uint32 | 20 | 0 unsigned | String | 3783 +---------------------+--------------+------+-------------+--------+ 3784 | conflict-scope | container | 21 | 5 map | Object | 3785 +---------------------+--------------+------+-------------+--------+ 3786 | acl-list | list | 22 | 4 array | Array | 3787 +---------------------+--------------+------+-------------+--------+ 3788 | acl-name | leafref | 23 | 3 text | String | 3789 | | | | string | | 3790 +---------------------+--------------+------+-------------+--------+ 3791 | acl-type | leafref | 24 | 3 text | String | 3792 | | | | string | | 3793 +---------------------+--------------+------+-------------+--------+ 3794 | bytes-dropped | yang:zero- | 25 | 0 unsigned | String | 3795 | | based- | | | | 3796 | | counter64 | | | | 3797 +---------------------+--------------+------+-------------+--------+ 3798 | bps-dropped | yang:gauge64 | 26 | 0 unsigned | String | 3799 +---------------------+--------------+------+-------------+--------+ 3800 | pkts-dropped | yang:zero- | 27 | 0 unsigned | String | 3801 | | based- | | | | 3802 | | counter64 | | | | 3803 +---------------------+--------------+------+-------------+--------+ 3804 | pps-dropped | yang:gauge64 | 28 | 0 unsigned | String | 3805 +---------------------+--------------+------+-------------+--------+ 3806 | attack-status | enumeration | 29 | 0 unsigned | String | 3807 +---------------------+--------------+------+-------------+--------+ 3808 | ietf-dots-signal- | container | 30 | 5 map | Object | 3809 | channel:signal- | | | | | 3810 | config | | | | | 3811 +---------------------+--------------+------+-------------+--------+ 3812 | sid | uint32 | 31 | 0 unsigned | Number | 3813 +---------------------+--------------+------+-------------+--------+ 3814 | mitigating-config | container | 32 | 5 map | Object | 3815 +---------------------+--------------+------+-------------+--------+ 3816 | heartbeat-interval | container | 33 | 5 map | Object | 3817 +---------------------+--------------+------+-------------+--------+ 3818 | max-value | uint16 | 34 | 0 unsigned | Number | 3819 +---------------------+--------------+------+-------------+--------+ 3820 | min-value | uint16 | 35 | 0 unsigned | Number | 3821 +---------------------+--------------+------+-------------+--------+ 3822 | current-value | uint16 | 36 | 0 unsigned | Number | 3823 +---------------------+--------------+------+-------------+--------+ 3824 | missing-hb-allowed | container | 37 | 5 map | Object | 3825 +---------------------+--------------+------+-------------+--------+ 3826 | max-retransmit | container | 38 | 5 map | Object | 3827 +---------------------+--------------+------+-------------+--------+ 3828 | ack-timeout | container | 39 | 5 map | Object | 3829 +---------------------+--------------+------+-------------+--------+ 3830 | ack-random-factor | container | 40 | 5 map | Object | 3831 +---------------------+--------------+------+-------------+--------+ 3832 | max-value-decimal | decimal64 | 41 | 6 tag 4 | String | 3833 | | | | [-2, | | 3834 | | | | integer] | | 3835 +---------------------+--------------+------+-------------+--------+ 3836 | min-value-decimal | decimal64 | 42 | 6 tag 4 | String | 3837 | | | | [-2, | | 3838 | | | | integer] | | 3839 +---------------------+--------------+------+-------------+--------+ 3840 | current-value- | decimal64 | 43 | 6 tag 4 | String | 3841 | decimal | | | [-2, | | 3842 | | | | integer] | | 3843 +---------------------+--------------+------+-------------+--------+ 3844 | idle-config | container | 44 | 5 map | Object | 3845 +---------------------+--------------+------+-------------+--------+ 3846 | trigger-mitigation | boolean | 45 | 7 bits 20 | False | 3847 | | | +-------------+--------+ 3848 | | | | 7 bits 21 | True | 3849 +---------------------+--------------+------+-------------+--------+ 3850 | ietf-dots-signal- | container | 46 | 5 map | Object | 3851 | channel:redirected- | | | | | 3852 | signal | | | | | 3853 +---------------------+--------------+------+-------------+--------+ 3854 | alt-server | inet:domain- | 47 | 3 text | String | 3855 | | name | | string | | 3856 +---------------------+--------------+------+-------------+--------+ 3857 | alt-server-record | leaf-list | 48 | 4 array | Array | 3858 | +--------------+------+-------------+--------+ 3859 | | inet:ip- | | 3 text | String | 3860 | | address | | string | | 3861 +---------------------+--------------+------+-------------+--------+ 3862 | ietf-dots-signal- | container | 49 | 5 map | Object | 3863 | channel:heartbeat | | | | | 3864 +---------------------+--------------+------+-------------+--------+ 3865 | probing-rate | container | 50 | 5 map | Object | 3866 +---------------------+--------------+------+-------------+--------+ 3867 | peer-hb-status | boolean | 51 | 7 bits 20 | False | 3868 | | | +-------------+--------+ 3869 | | | | 7 bits 21 | True | 3870 +---------------------+--------------+------+-------------+--------+ 3872 Table 5: CBOR Key Values Used in DOTS Signal Channel Messages & 3873 Their Mappings to JSON and YANG 3875 7. (D)TLS Protocol Profile and Performance Considerations 3877 7.1. (D)TLS Protocol Profile 3879 This section defines the (D)TLS protocol profile of DOTS signal 3880 channel over (D)TLS and DOTS data channel over TLS. 3882 There are known attacks on (D)TLS, such as man-in-the-middle and 3883 protocol downgrade attacks. These are general attacks on (D)TLS and, 3884 as such, they are not specific to DOTS over (D)TLS; refer to the 3885 (D)TLS RFCs for discussion of these security issues. DOTS agents 3886 MUST adhere to the (D)TLS implementation recommendations and security 3887 considerations of [RFC7525] except with respect to (D)TLS version. 3888 Because DOTS signal channel encryption relying upon (D)TLS is 3889 virtually a greenfield deployment, DOTS agents MUST implement only 3890 (D)TLS 1.2 or later. 3892 When a DOTS client is configured with a domain name of the DOTS 3893 server, and it connects to its configured DOTS server, the server may 3894 present it with a PKIX certificate. In order to ensure proper 3895 authentication, a DOTS client MUST verify the entire certification 3896 path per [RFC5280]. Additionally, the DOTS client MUST use [RFC6125] 3897 validation techniques to compare the domain name with the certificate 3898 provided. Certification authorities that issue DOTS server 3899 certificates SHOULD support the DNS-ID and SRV-ID identifier types. 3900 DOTS servers SHOULD prefer the use of DNS-ID and SRV-ID over CN-ID 3901 identifier types in certificate requests (as described in Section 2.3 3902 of [RFC6125]), and the wildcard character '*' SHOULD NOT be included 3903 in the presented identifier. DOTS doesn't use URI-IDs for server 3904 identity verification. 3906 A key challenge to deploying DOTS is the provisioning of DOTS 3907 clients, including the distribution of keying material to DOTS 3908 clients to enable the required mutual authentication of DOTS agents. 3909 Enrollment over Secure Transport (EST) [RFC7030] defines a method of 3910 certificate enrollment by which domains operating DOTS servers may 3911 provide DOTS clients with all the necessary cryptographic keying 3912 material, including a private key and a certificate, to authenticate 3913 themselves. One deployment option is to have DOTS clients behave as 3914 EST clients for certificate enrollment from an EST server provisioned 3915 by the mitigation provider. This document does not specify which EST 3916 or other mechanism the DOTS client uses to achieve initial 3917 enrollment. 3919 The Server Name Indication (SNI) extension [RFC6066] defines a 3920 mechanism for a client to tell a (D)TLS server the name of the server 3921 it wants to contact. This is a useful extension for hosting 3922 environments where multiple virtual servers are reachable over a 3923 single IP address. The DOTS client may or may not know if it is 3924 interacting with a DOTS server in a virtual server hosting 3925 environment, so the DOTS client SHOULD include the DOTS server FQDN 3926 in the SNI extension. 3928 Implementations compliant with this profile MUST implement all of the 3929 following items: 3931 o DTLS record replay detection (Section 3.3 of [RFC6347]) or an 3932 equivalent mechanism to protect against replay attacks. 3934 o DTLS session resumption without server-side state to resume 3935 session and convey the DOTS signal. 3937 o At least one of raw public keys [RFC7250] or PSK handshake 3938 [RFC4279] with (EC)DHE key exchange. This reduces the size of the 3939 ServerHello. Also, this can be used by DOTS agents that cannot 3940 obtain certificates. 3942 Implementations compliant with this profile SHOULD implement all of 3943 the following items to reduce the delay required to deliver a DOTS 3944 signal channel message: 3946 o TLS False Start [RFC7918], which reduces round-trips by allowing 3947 the TLS client's second flight of messages (ChangeCipherSpec) to 3948 also contain the DOTS signal. TLS False Start is formally defined 3949 for use with TLS, but the same technique is applicable to DTLS as 3950 well. 3952 o Cached Information Extension [RFC7924] which avoids transmitting 3953 the server's certificate and certificate chain if the client has 3954 cached that information from a previous TLS handshake. 3956 Compared to UDP, DOTS signal channel over TCP requires an additional 3957 round-trip time (RTT) of latency to establish a TCP connection. DOTS 3958 implementations are encouraged to implement TCP Fast Open [RFC7413] 3959 to eliminate that RTT. 3961 7.2. (D)TLS 1.3 Considerations 3963 TLS 1.3 provides useful latency improvements for connection 3964 establishment over TLS 1.2. The DTLS 1.3 protocol 3965 [I-D.ietf-tls-dtls13] is based upon the TLS 1.3 protocol and provides 3966 equivalent security guarantees. (D)TLS 1.3 provides two basic 3967 handshake modes the DOTS signal channel can take advantage of: 3969 o A full handshake mode in which a DOTS client can send a DOTS 3970 mitigation request message after one round trip and the DOTS 3971 server immediately responds with a DOTS mitigation response. This 3972 assumes no packet loss is experienced. 3974 o 0-RTT mode in which the DOTS client can authenticate itself and 3975 send DOTS mitigation request messages in the first message, thus 3976 reducing handshake latency. 0-RTT only works if the DOTS client 3977 has previously communicated with that DOTS server, which is very 3978 likely with the DOTS signal channel. 3980 The DOTS client has to establish a (D)TLS session with the DOTS 3981 server during 'idle' time and share a PSK. 3983 During a DDoS attack, the DOTS client can use the (D)TLS session to 3984 convey the DOTS mitigation request message and, if there is no 3985 response from the server after multiple retries, the DOTS client can 3986 resume the (D)TLS session in 0-RTT mode using PSK. 3988 DOTS servers that support (D)TLS 1.3 MAY allow DOTS clients to send 3989 early data (0-RTT). DOTS clients MUST NOT send "CoAP Ping" as early 3990 data; such messages MUST be rejected by DOTS servers. Section 8 of 3991 [RFC8446] discusses some mechanisms to implement in order to limit 3992 the impact of replay attacks on 0-RTT data. If the DOTS server 3993 accepts 0-RTT, it MUST implement one of these mechanisms to prevent 3994 replay at the TLS layer. A DOTS server can reject 0-RTT by sending a 3995 TLS HelloRetryRequest. 3997 The DOTS signal channel messages sent as early data by the DOTS 3998 client are idempotent requests. As a reminder, the Message ID 3999 (Section 3 of [RFC7252]) is changed each time a new CoAP request is 4000 sent, and the Token (Section 5.3.1 of [RFC7252]) is randomized in 4001 each CoAP request. The DOTS server(s) MUST use the Message ID and 4002 the Token in the DOTS signal channel message to detect replay of 4003 early data at the application layer and accept 0-RTT data at most 4004 once from the same DOTS client. This anti-replay defense requires 4005 sharing the Message ID and the Token in the 0-RTT data between DOTS 4006 servers in the DOTS server domain. DOTS servers do not rely on 4007 transport coordinates to identify DOTS peers. As specified in 4008 Section 4.4.1, DOTS servers couple the DOTS signal channel sessions 4009 using the DOTS client identity and optionally the 'cdid' parameter 4010 value. Furthermore, the 'mid' value is monotonically increased by 4011 the DOTS client for each mitigation request, thus attackers that 4012 replay mitigation requests with lower numeric 'mid' values and 4013 overlapping scopes with mitigation requests having higher numeric 4014 'mid' values will be rejected systematically by the DOTS server. 4015 Likewise, the 'sid' value is monotonically increased by the DOTS 4016 client for each configuration request (Section 4.5.2); attackers 4017 replaying configuration requests with lower numeric 'sid' values will 4018 be rejected by the DOTS server if it maintains a higher numeric 'sid' 4019 value for this DOTS client. 4021 Owing to the aforementioned protections, all DOTS signal channel 4022 requests are safe to transmit in TLS 1.3 as early data. Refer to 4023 [I-D.boucadair-dots-earlydata] for more details. 4025 A simplified TLS 1.3 handshake with 0-RTT DOTS mitigation request 4026 message exchange is shown in Figure 29. 4028 DOTS Client DOTS Server 4030 ClientHello 4031 (0-RTT DOTS signal message) 4032 --------> 4033 ServerHello 4034 {EncryptedExtensions} 4035 {Finished} 4036 <-------- [DOTS signal message] 4037 (end_of_early_data) 4038 {Finished} --------> 4039 [DOTS signal message] <-------> [DOTS signal message] 4041 Note that: 4042 () Indicates messages protected 0-RTT keys 4043 {} Indicates messages protected using handshake keys 4044 [] Indicates messages protected using 1-RTT keys 4046 Figure 29: A Simplified TLS 1.3 Handshake with 0-RTT 4048 7.3. DTLS MTU and Fragmentation 4050 To avoid DOTS signal message fragmentation and the subsequent 4051 decreased probability of message delivery, the DLTS records need to 4052 fit within a single datagram [RFC6347]. DTLS handles fragmentation 4053 and reassembly only for handshake messages and not for the 4054 application data (Section 4.1.1 of [RFC6347]). If the path MTU 4055 (PMTU) cannot be discovered, DOTS agents MUST assume a PMTU of 1280 4056 bytes, as IPv6 requires that every link in the Internet have an MTU 4057 of 1280 octets or greater as specified in [RFC8200]. If IPv4 support 4058 on legacy or otherwise unusual networks is a consideration and the 4059 PMTU is unknown, DOTS implementations MAY assume a PMTU of 576 bytes 4060 for IPv4 datagrams (see Section 3.3.3 of [RFC1122]). 4062 The DOTS client must consider the amount of record expansion expected 4063 by the DTLS processing when calculating the size of the CoAP message 4064 that fits within the PMTU. PMTU MUST be greater than or equal to 4065 [CoAP message size + DTLS 1.2 overhead of 13 octets + authentication 4066 overhead of the negotiated DTLS cipher suite + block padding] 4067 (Section 4.1.1.1 of [RFC6347]). If the total request size exceeds 4068 the PMTU, then the DOTS client MUST split the DOTS signal into 4069 separate messages; for example, the list of addresses in the 'target- 4070 prefix' parameter could be split into multiple lists and each list 4071 conveyed in a new PUT request. 4073 | Implementation Note: DOTS choice of message size parameters 4074 | works well with IPv6 and with most of today's IPv4 paths. 4075 | However, with IPv4, it is harder to safely make sure that there 4076 | is no IP fragmentation. If the IPv4 PMTU is unknown, 4077 | implementations may want to limit themselves to more 4078 | conservative IPv4 datagram sizes such as 576 bytes, per 4079 | [RFC0791]. 4081 8. Mutual Authentication of DOTS Agents & Authorization of DOTS Clients 4083 (D)TLS based upon client certificates can be used for mutual 4084 authentication between DOTS agents. If, for example, a DOTS gateway 4085 is involved, DOTS clients and DOTS gateways must perform mutual 4086 authentication; only authorized DOTS clients are allowed to send DOTS 4087 signals to a DOTS gateway. The DOTS gateway and the DOTS server must 4088 perform mutual authentication; a DOTS server only allows DOTS signal 4089 channel messages from an authorized DOTS gateway, thereby creating a 4090 two-link chain of transitive authentication between the DOTS client 4091 and the DOTS server. 4093 The DOTS server should support certificate-based client 4094 authentication. The DOTS client should respond to the DOTS server's 4095 TLS CertificateRequest message with the PKIX certificate held by the 4096 DOTS client. DOTS client certificate validation must be performed 4097 per [RFC5280], and the DOTS client certificate must conform to the 4098 [RFC5280] certificate profile. If a DOTS client does not support TLS 4099 client certificate authentication, it must support client 4100 authentication based on pre-shared key or raw public key. 4102 +---------------------------------------------+ 4103 | example.com domain +---------+ | 4104 | | AAA | | 4105 | +---------------+ | Server | | 4106 | | Application | +------+--+ | 4107 | | server +<---------------+ ^ | 4108 | | (DOTS client) | | | | 4109 | +---------------+ | | | 4110 | V V | example.net domain 4111 | +-----+----+--+ | +---------------+ 4112 | +--------------+ | | | | | 4113 | | Guest +<----x---->+ DOTS +<----->+ DOTS | 4114 | | (DOTS client)| | gateway | | | server | 4115 | +--------------+ | | | | | 4116 | +----+--------+ | +---------------+ 4117 | ^ | 4118 | | | 4119 | +----------------+ | | 4120 | | DDoS detector | | | 4121 | | (DOTS client) +<-------------+ | 4122 | +----------------+ | 4123 +---------------------------------------------+ 4125 Figure 30: Example of Authentication and Authorization of DOTS Agents 4127 In the example depicted in Figure 30, the DOTS gateway and DOTS 4128 clients within the 'example.com' domain proceed with mutual 4129 authentication. After the DOTS gateway validates the identity of a 4130 DOTS client, it communicates with the AAA server in the 'example.com' 4131 domain to determine if the DOTS client is authorized to request DDoS 4132 mitigation. If the DOTS client is not authorized, a 4.01 4133 (Unauthorized) is returned in the response to the DOTS client. In 4134 this example, the DOTS gateway only allows the application server and 4135 DDoS attack detector to request DDoS mitigation, but does not permit 4136 the user of type 'guest' to request DDoS mitigation. 4138 Also, DOTS gateways and servers located in different domains must 4139 perform mutual authentication (e.g., using certificates). A DOTS 4140 server will only allow a DOTS gateway with a certificate for a 4141 particular domain to request mitigation for that domain. In 4142 reference to Figure 30, the DOTS server only allows the DOTS gateway 4143 to request mitigation for the 'example.com' domain and not for other 4144 domains. 4146 9. Error Handling 4148 This section is a summary of the Error Code responses that can be 4149 returned by a DOTS server. These error responses must contain a CoAP 4150 4.xx or 5.xx Response Code. 4152 In general, there may be an additional plain text diagnostic payload 4153 (Section 5.5.2 of [RFC7252]) to help troubleshooting in the body of 4154 the response unless detailed otherwise. 4156 Errors returned by a DOTS server can be broken into two categories, 4157 those associated with CoAP itself and those generated during the 4158 validation of the provided data by the DOTS server. 4160 The following list of common CoAP errors that are implemented by DOTS 4161 servers. This list is not exhaustive; other errors defined by CoAP 4162 and associated RFCs may be applicable. 4164 4.00 (Bad Request) is returned by the DOTS server when the DOTS 4165 client has sent a request that violates the DOTS protocol 4166 (Section 4). 4168 4.01 (Unauthorized) is returned by the DOTS server when the DOTS 4169 client is not authorized to access the DOTS server (Section 4). 4171 4.02 (Bad Option) is returned by the DOTS server when one or more 4172 CoAP options are unknown or malformed by the CoAP layer [RFC7252]. 4174 4.04 (Not Found) is returned by the DOTS server when the DOTS client 4175 is requesting a 'mid' or 'sid' that is not valid (Section 4). 4177 4.05 (Method Not Allowed) is returned by the DOTS server when the 4178 DOTS client is requesting a resource by a method (e.g., GET) that 4179 is not supported by the DOTS server [RFC7252]. 4181 4.08 (Request Entity Incomplete) is returned by the DOTS server if 4182 one or multiple blocks of a block transfer request is missing 4183 [RFC7959]. 4185 4.09 (Conflict) is returned by the DOTS server if the DOTS server 4186 detects that a request conflicts with a previous request. The 4187 response body is formatted using "application/dots+cbor", and 4188 contains the "conflict-clause" (Section 4.4). 4190 4.13 (Request Entity Too Large) may be returned by the DOTS server 4191 during a block transfer request [RFC7959]. 4193 4.15 (Unsupported Content-Format) is returned by the DOTS server 4194 when the Content-Format is used but the request is not formatted 4195 as "application/dots+cbor" (Section 4). 4197 4.22 (Unprocessable Entity) is returned by the DOTS server when one 4198 or more session configuration parameters are not valid 4199 (Section 4.5). 4201 5.03 (Service Unavailable) is returned by the DOTS server if the 4202 DOTS server is unable to handle the request (Section 4). An 4203 example is the DOTS server needs to redirect the DOTS client to 4204 use an alternate DOTS server (Section 4.6). The response body is 4205 formatted using "application/dots+cbor", and contains how to 4206 handle the 5.03 Response Code. 4208 5.08 (Hop Limit Reached) is returned by the DOTS server if there is 4209 a data path loop through upstream DOTS gateways. The response 4210 body is formatted using plain text and contains a list of servers 4211 that are in the data path loop [RFC8768]. 4213 10. IANA Considerations 4215 10.1. DOTS Signal Channel UDP and TCP Port Number 4217 IANA has assigned the port number 4646 (the ASCII decimal value for 4218 ".." (DOTS)) to the DOTS signal channel protocol for both UDP and TCP 4219 from the "Service Name and Transport Protocol Port Number Registry" 4220 available at . 4223 IANA is requested to update these entries with the RFC number to be 4224 assigned to this document: 4226 Service Name: dots-signal 4227 Port Number: 4646 4228 Transport Protocol: TCP 4229 Description: Distributed Denial-of-Service Open Threat Signaling 4230 (DOTS) Signal Channel 4231 Assignee: IESG 4232 Contact: IETF Chair 4233 Registration Date: 2020-01-16 4234 Reference: [RFCXXXX] 4236 Service Name: dots-signal 4237 Port Number: 4646 4238 Transport Protocol: UDP 4239 Description: Distributed Denial-of-Service Open Threat Signaling 4240 (DOTS) Signal Channel 4241 Assignee: IESG 4242 Contact: IETF Chair 4243 Registration Date: 2020-01-16 4244 Reference: [RFCXXXX] 4246 10.2. Well-Known 'dots' URI 4248 IANA is requested to update the 'dots' well-known URI (Table 6) entry 4249 in the Well- Known URIs registry [URI] as follows: 4251 +------------+------------+-----------+-----------+-------------+ 4252 | URI Suffix | Change | Reference | Status | Related | 4253 | | Controller | | | information | 4254 +============+============+===========+===========+=============+ 4255 | dots | IETF | [RFCXXXX] | permanent | None | 4256 +------------+------------+-----------+-----------+-------------+ 4258 Table 6: 'dots' Well-Known URI 4260 10.3. Media Type Registration 4262 IANA is requested to update the "application/dots+cbor" media type in 4263 the "Media Types" registry [IANA-MediaTypes] in the manner described 4264 in [RFC6838], which can be used to indicate that the content is a 4265 DOTS signal channel object: 4267 Type name: application 4269 Subtype name: dots+cbor 4271 Required parameters: N/A 4273 Optional parameters: N/A 4275 Encoding considerations: binary 4277 Security considerations: See the Security Considerations section of 4278 [RFCXXXX]. 4280 Interoperability considerations: N/A 4282 Published specification: [RFCXXXX] 4284 Applications that use this media type: DOTS agents sending DOTS 4285 messages over CoAP over (D)TLS. 4287 Fragment identifier considerations: N/A 4289 Additional information: 4291 Deprecated alias names for this type: N/A 4292 Magic number(s): N/A 4293 File extension(s): N/A 4294 Macintosh file type code(s): N/A 4296 Person & email address to contact for further information: IESG, 4297 iesg@ietf.org 4299 Intended usage: COMMON 4301 Restrictions on usage: none 4303 Author: See Authors' Addresses section. 4305 Change controller: IESG 4307 Provisional registration? No 4309 10.4. CoAP Content-Formats Registration 4311 IANA is requested to update the CoAP Content-Format ID for the 4312 "application/ dots+cbor" media type in the "CoAP Content-Formats" 4313 registry [IANA-CoAP-Content-Formats]: 4315 o Media Type: application/dots+cbor 4316 o Encoding: - 4317 o Id: 271 4318 o Reference: [RFCXXXX] 4320 10.5. CBOR Tag Registration 4322 This section defines the DOTS CBOR tag as another means for 4323 applications to declare that a CBOR data structure is a DOTS signal 4324 channel object. Its use is optional and is intended for use in cases 4325 in which this information would not otherwise be known. The DOTS 4326 CBOR tag is not required for DOTS signal channel protocol version 4327 specified in this document. If present, the DOTS tag MUST prefix a 4328 DOTS signal channel object. 4330 IANA is requested to update the DOTS signal channel CBOR tag in the 4331 "CBOR Tags" registry [IANA-CBOR-Tags]: 4333 * Tag: 271 4334 * Data Item: DDoS Open Threat Signaling (DOTS) signal channel object 4335 * Semantics: DDoS Open Threat Signaling (DOTS) signal channel 4336 object, as defined in [RFCXXXX] 4337 * Reference: [RFCXXXX] 4339 10.6. DOTS Signal Channel Protocol Registry 4341 The following sections update the "Distributed Denial-of- Service 4342 Open Threat Signaling (DOTS) Signal Channel" subregistries 4343 [REG-DOTS]. 4345 10.6.1. DOTS Signal Channel CBOR Key Values Subregistry 4347 The structure of this subregistry is provided in Section 10.6.1.1. 4349 10.6.1.1. Registration Template 4351 This specification requests IANA to update the allocation policy of 4352 "DOTS Signal Channel CBOR Key Values" registry as follows: 4354 Parameter name: 4355 Parameter name as used in the DOTS signal channel. 4357 CBOR Key Value: 4358 Key value for the parameter. The key value MUST be an integer in 4359 the 1-65535 range. 4361 OLD: 4362 +-------------+-------------------------+------------------------+ 4363 | Range | Registration Procedures | Note | 4364 +=============+=========================+========================+ 4365 | 1-16383 | IETF Review | comprehension-required | 4366 | 16384-32767 | Specification Required | comprehension-optional | 4367 | 32768-49151 | IETF Review | comprehension-optional | 4368 | 49152-65535 | Private Use | comprehension-optional | 4369 +-------------+-------------------------+------------------------+ 4371 NEW: 4372 +-------------+-------------------------+------------------------+ 4373 | Range | Registration Procedures | Note | 4374 +=============+=========================+========================+ 4375 | 1-127 | IETF Review | comprehension-required | 4376 | 128-255 | IETF Review | comprehension-optional | 4377 | 256-16383 | IETF Review | comprehension-required | 4378 | 16384-32767 | Specification Required | comprehension-optional | 4379 | 32768-49151 | IETF Review | comprehension-optional | 4380 | 49152-65535 | Private Use | comprehension-optional | 4381 +-------------+-------------------------+------------------------+ 4383 Registration requests for the 16384-32767 range are evaluated 4384 after a three-week review period on the dots-signal-reg- 4385 review@ietf.org mailing list, on the advice of one or more 4386 Designated Experts. However, to allow for the allocation of 4387 values prior to publication, the Designated Experts may approve 4388 registration once they are satisfied that such a specification 4389 will be published. New registration requests should be sent in 4390 the form of an email to the review mailing list; the request 4391 should use an appropriate subject (e.g., "Request to register CBOR 4392 Key Value for DOTS: example"). IANA will only accept new 4393 registrations from the Designated Experts, and it will check that 4394 review was requested on the mailing list in accordance with these 4395 procedures. 4397 Within the review period, the Designated Experts will either 4398 approve or deny the registration request, communicating this 4399 decision to the review list and IANA. Denials should include an 4400 explanation and, if applicable, suggestions as to how to make the 4401 request successful. Registration requests that are undetermined 4402 for a period longer than 21 days can be brought to the IESG's 4403 attention (using the iesg@ietf.org mailing list) for resolution. 4405 Criteria that should be applied by the Designated Experts include 4406 determining whether the proposed registration duplicates existing 4407 functionality, whether it is likely to be of general applicability 4408 or whether it is useful only for a single use case, and whether 4409 the registration description is clear. IANA must only accept 4410 registry updates to the 16384-32767 range from the Designated 4411 Experts and should direct all requests for registration to the 4412 review mailing list. It is suggested that multiple Designated 4413 Experts be appointed. In cases where a registration decision 4414 could be perceived as creating a conflict of interest for a 4415 particular Expert, that Expert should defer to the judgment of the 4416 other Experts. 4418 CBOR Major Type: 4419 CBOR Major type and optional tag for the parameter. 4421 Change Controller: 4422 For Standards Track RFCs, list the "IESG". For others, give the 4423 name of the responsible party. Other details (e.g., email 4424 address) may also be included. 4426 Specification Document(s): 4427 Reference to the document or documents that specify the parameter, 4428 preferably including URIs that can be used to retrieve copies of 4429 the documents. An indication of the relevant sections may also be 4430 included but is not required. 4432 10.6.1.2. Update Subregistry Content 4434 IANA is requested to update entries in the "0-51" and "49152-65535" 4435 ranges from the "DOTS Signal Channel CBOR Key Values" registry with 4436 the RFC number to be assigned to this document. 4438 10.6.2. Status Codes Subregistry 4440 IANA is requested to update these entries from the "DOTS Signal 4441 Channel Status Codes" registry with the RFC number to be assigned to 4442 this document: 4444 +--------------+---------------+----------------------+-----------+ 4445 | Code | Label | Description | Reference | 4446 +==============+===============+======================+===========+ 4447 | 0 | Reserved | | [RFCXXXX] | 4448 +--------------+---------------+----------------------+-----------+ 4449 | 1 | attack- | Attack mitigation | [RFCXXXX] | 4450 | | mitigation- | setup is in progress | | 4451 | | in-progress | (e.g., changing the | | 4452 | | | network path to | | 4453 | | | redirect the inbound | | 4454 | | | traffic to a DOTS | | 4455 | | | mitigator). | | 4456 +--------------+---------------+----------------------+-----------+ 4457 | 2 | attack- | Attack is being | [RFCXXXX] | 4458 | | successfully- | successfully | | 4459 | | mitigated | mitigated (e.g., | | 4460 | | | traffic is | | 4461 | | | redirected to a DDoS | | 4462 | | | mitigator and attack | | 4463 | | | traffic is dropped). | | 4464 +--------------+---------------+----------------------+-----------+ 4465 | 3 | attack- | Attack has stopped | [RFCXXXX] | 4466 | | stopped | and the DOTS client | | 4467 | | | can withdraw the | | 4468 | | | mitigation request. | | 4469 +--------------+---------------+----------------------+-----------+ 4470 | 4 | attack- | Attack has exceeded | [RFCXXXX] | 4471 | | exceeded- | the mitigation | | 4472 | | capability | provider capability. | | 4473 +--------------+---------------+----------------------+-----------+ 4474 | 5 | dots-client- | DOTS client has | [RFCXXXX] | 4475 | | withdrawn- | withdrawn the | | 4476 | | mitigation | mitigation request | | 4477 | | | and the mitigation | | 4478 | | | is active but | | 4479 | | | terminating. | | 4480 +--------------+---------------+----------------------+-----------+ 4481 | 6 | attack- | Attack mitigation is | [RFCXXXX] | 4482 | | mitigation- | now terminated. | | 4483 | | terminated | | | 4484 +--------------+---------------+----------------------+-----------+ 4485 | 7 | attack- | Attack mitigation is | [RFCXXXX] | 4486 | | mitigation- | withdrawn. | | 4487 | | withdrawn | | | 4488 +--------------+---------------+----------------------+-----------+ 4489 | 8 | attack- | Attack mitigation | [RFCXXXX] | 4490 | | mitigation- | will be triggered | | 4491 | | signal-loss | for the mitigation | | 4492 | | | request only when | | 4493 | | | the DOTS signal | | 4494 | | | channel session is | | 4495 | | | lost. | | 4496 +--------------+---------------+----------------------+-----------+ 4497 | 9-2147483647 | Unassigned | | | 4498 +--------------+---------------+----------------------+-----------+ 4500 Table 7: Initial DOTS Signal Channel Status Codes 4502 New codes can be assigned via Standards Action [RFC8126]. 4504 10.6.3. Conflict Status Codes Subregistry 4506 IANA is requested to update these entries from the "DOTS Signal 4507 Channel Conflict Status Codes" registry with the RFC number to be 4508 assigned to this document: 4510 +--------------+-------------------+--------------------+-----------+ 4511 | Code | Label | Description | Reference | 4512 +==============+===================+====================+===========+ 4513 | 0 | Reserved | | [RFCXXXX] | 4514 +--------------+-------------------+--------------------+-----------+ 4515 | 1 | request-inactive- | DOTS server | [RFCXXXX] | 4516 | | other-active | has detected | | 4517 | | | conflicting | | 4518 | | | mitigation | | 4519 | | | requests from | | 4520 | | | different DOTS | | 4521 | | | clients. This | | 4522 | | | mitigation | | 4523 | | | request is | | 4524 | | | currently | | 4525 | | | inactive until | | 4526 | | | the conflicts | | 4527 | | | are resolved. | | 4528 | | | Another | | 4529 | | | mitigation | | 4530 | | | request is | | 4531 | | | active. | | 4532 +--------------+-------------------+--------------------+-----------+ 4533 | 2 | request-active | DOTS server | [RFCXXXX] | 4534 | | | has detected | | 4535 | | | conflicting | | 4536 | | | mitigation | | 4537 | | | requests from | | 4538 | | | different DOTS | | 4539 | | | clients. This | | 4540 | | | mitigation | | 4541 | | | request is | | 4542 | | | currently | | 4543 | | | active. | | 4544 +--------------+-------------------+--------------------+-----------+ 4545 | 3 | all-requests- | DOTS server | [RFCXXXX] | 4546 | | inactive | has detected | | 4547 | | | conflicting | | 4548 | | | mitigation | | 4549 | | | requests from | | 4550 | | | different DOTS | | 4551 | | | clients. All | | 4552 | | | conflicting | | 4553 | | | mitigation | | 4554 | | | requests are | | 4555 | | | inactive. | | 4556 +--------------+-------------------+--------------------+-----------+ 4557 | 4-2147483647 | Unassigned | | | 4558 +--------------+-------------------+--------------------+-----------+ 4560 Table 8: Initial DOTS Signal Channel Conflict Status Codes 4562 New codes can be assigned via Standards Action [RFC8126]. 4564 10.6.4. Conflict Cause Codes Subregistry 4566 IANA is requested to update these entries from the "DOTS Signal 4567 Channel Conflict Cause Codes" registry with the RFC number to be 4568 assigned to this document: 4570 +--------------+---------------------+----------------+-----------+ 4571 | Code | Label | Description | Reference | 4572 +==============+=====================+================+===========+ 4573 | 0 | Reserved | | [RFCXXXX] | 4574 +--------------+---------------------+----------------+-----------+ 4575 | 1 | overlapping-targets | Overlapping | [RFCXXXX] | 4576 | | | targets. | | 4577 +--------------+---------------------+----------------+-----------+ 4578 | 2 | conflict-with- | Conflicts with | [RFCXXXX] | 4579 | | acceptlist | an existing | | 4580 | | | accept-list. | | 4581 | | | This code is | | 4582 | | | returned when | | 4583 | | | the DDoS | | 4584 | | | mitigation | | 4585 | | | detects source | | 4586 | | | addresses/ | | 4587 | | | prefixes in | | 4588 | | | the accept- | | 4589 | | | listed ACLs | | 4590 | | | are attacking | | 4591 | | | the target. | | 4592 +--------------+---------------------+----------------+-----------+ 4593 | 3 | cuid-collision | CUID | [RFCXXXX] | 4594 | | | Collision. | | 4595 | | | This code is | | 4596 | | | returned when | | 4597 | | | a DOTS client | | 4598 | | | uses a 'cuid' | | 4599 | | | that is | | 4600 | | | already used | | 4601 | | | by another | | 4602 | | | DOTS client. | | 4603 +--------------+---------------------+----------------+-----------+ 4604 | 4-2147483647 | Unassigned | | | 4605 +--------------+---------------------+----------------+-----------+ 4607 Table 9: Initial DOTS Signal Channel Conflict Cause Codes 4609 New codes can be assigned via Standards Action [RFC8126]. 4611 10.6.5. Attack Status Codes Subregistry 4613 IANA is requested to update these entries from the "DOTS Signal 4614 Channel Attack Status Codes" registry with the RFC number to be 4615 assigned to this document: 4617 +--------------+----------------------+-----------------+-----------+ 4618 | Code | Label | Description | Reference | 4619 +==============+======================+=================+===========+ 4620 | 0 | Reserved | | [RFCXXXX] | 4621 +--------------+----------------------+-----------------+-----------+ 4622 | 1 | under-attack | The DOTS | [RFCXXXX] | 4623 | | | client | | 4624 | | | determines | | 4625 | | | that it is | | 4626 | | | still under | | 4627 | | | attack. | | 4628 +--------------+----------------------+-----------------+-----------+ 4629 | 2 | attack-successfully- | The DOTS | [RFCXXXX] | 4630 | | mitigated | client | | 4631 | | | determines | | 4632 | | | that the | | 4633 | | | attack is | | 4634 | | | successfully | | 4635 | | | mitigated. | | 4636 +--------------+----------------------+-----------------+-----------+ 4637 | 3-2147483647 | Unassigned | | | 4638 +--------------+----------------------+-----------------+-----------+ 4640 Table 10: Initial DOTS Signal Channel Attack Status Codes 4642 New codes can be assigned via Standards Action [RFC8126]. 4644 10.7. DOTS Signal Channel YANG Modules 4646 IANA already registered the following URIs in the "ns" subregistry 4647 within the "IETF XML Registry" [RFC3688]: 4649 URI: urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel 4650 Registrant Contact: The IESG. 4651 XML: N/A; the requested URI is an XML namespace. 4653 URI: urn:ietf:params:xml:ns:yang:iana-dots-signal-channel 4654 Registrant Contact: IANA. 4655 XML: N/A; the requested URI is an XML namespace. 4657 This document requests IANA to update the following YANG modules in 4658 the "YANG Module Names" subregistry [RFC6020] within the "YANG 4659 Parameters" registry. 4661 Name: ietf-dots-signal-channel 4662 Maintained by IANA: N 4663 Namespace: urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel 4664 Prefix: dots-signal 4665 Reference: RFCXXXX 4667 Name: iana-dots-signal-channel 4668 Maintained by IANA: Y 4669 Namespace: urn:ietf:params:xml:ns:yang:iana-dots-signal-channel 4670 Prefix: iana-dots-signal 4671 Reference: RFCXXXX 4673 This document defines the initial version of the IANA-maintained 4674 iana-dots-signal-channel YANG module. IANA is requested to maintain 4675 this note: 4677 Status, conflict status, conflict cause, and attack status values 4678 must not be directly added to the iana-dots-signal-channel YANG 4679 module. They must instead be respectively added to the "DOTS 4680 Status Codes", "DOTS Conflict Status Codes", "DOTS Conflict Cause 4681 Codes", and "DOTS Attack Status Codes" registries. 4683 When a 'status', 'conflict-status', 'conflict-cause', or 'attack- 4684 status' value is respectively added to the "DOTS Status Codes", "DOTS 4685 Conflict Status Codes", "DOTS Conflict Cause Codes", or "DOTS Attack 4686 Status Codes" registry, a new "enum" statement must be added to the 4687 iana-dots-signal-channel YANG module. The following "enum" 4688 statement, and substatements thereof, should be defined: 4690 "enum": Replicates the label from the registry. 4692 "value": Contains the IANA-assigned value corresponding to the 4693 'status', 'conflict-status', 'conflict-cause', or 4694 'attack-status'. 4696 "description": Replicates the description from the registry. 4698 "reference": Replicates the reference from the registry and adds 4699 the title of the document. 4701 When the iana-dots-signal-channel YANG module is updated, a new 4702 "revision" statement must be added in front of the existing revision 4703 statements. 4705 IANA is requested to update this note of "DOTS Status Codes", "DOTS 4706 Conflict Status Codes", "DOTS Conflict Cause Codes", and "DOTS Attack 4707 Status Codes" registries: 4709 When this registry is modified, the YANG module iana-dots-signal- 4710 channel must be updated as defined in [RFCXXXX]. 4712 11. Security Considerations 4714 High-level DOTS security considerations are documented in [RFC8612] 4715 and [RFC8811]. 4717 Authenticated encryption MUST be used for data confidentiality and 4718 message integrity. The interaction between the DOTS agents requires 4719 Datagram Transport Layer Security (DTLS) or Transport Layer Security 4720 (TLS) with a cipher suite offering confidentiality protection, and 4721 the guidance given in [RFC7525] MUST be followed to avoid attacks on 4722 (D)TLS. The (D)TLS protocol profile used for the DOTS signal channel 4723 is specified in Section 7. 4725 If TCP is used between DOTS agents, an attacker may be able to inject 4726 RST packets, bogus application segments, etc., regardless of whether 4727 TLS authentication is used. Because the application data is TLS 4728 protected, this will not result in the application receiving bogus 4729 data, but it will constitute a DoS on the connection. This attack 4730 can be countered by using TCP Authentication Option (TCP-AO) 4731 [RFC5925]. Although not widely adopted, if TCP-AO is used, then any 4732 bogus packets injected by an attacker will be rejected by the TCP-AO 4733 integrity check and therefore will never reach the TLS layer. 4735 If the 'cuid' is guessable, a misbehaving DOTS client from within the 4736 client's domain can use the 'cuid' of another DOTS client of the 4737 domain to delete or alter active mitigations. For this attack to 4738 succeed, the misbehaving client's messages need to pass the security 4739 validation checks by the DOTS server and, if the communication 4740 involves a client-domain DOTS gateway, the security checks of that 4741 gateway. 4743 A similar attack can be achieved by a compromised DOTS client that 4744 can sniff the TLS 1.2 handshake, use the client certificate to 4745 identify the 'cuid' used by another DOTS client. This attack is not 4746 possible if algorithms such as version 4 Universally Unique 4747 IDentifiers (UUIDs) in Section 4.4 of [RFC4122] are used to generate 4748 the 'cuid' because such UUIDs are not a deterministic function of the 4749 client certificate. Likewise, this attack is not possible with TLS 4750 1.3 because most of the TLS handshake is encrypted and the client 4751 certificate is not visible to eavesdroppers. 4753 A compromised DOTS client can collude with a DDoS attacker to send a 4754 mitigation request for a target resource, get the mitigation efficacy 4755 from the DOTS server, and convey the mitigation efficacy to the DDoS 4756 attacker to possibly change the DDoS attack strategy. Obviously, 4757 signaling an attack by the compromised DOTS client to the DOTS server 4758 will trigger attack mitigation. This attack can be prevented by 4759 monitoring and auditing DOTS clients to detect misbehavior and to 4760 deter misuse, and by only authorizing the DOTS client to request 4761 mitigation for specific target resources (e.g., an application server 4762 is authorized to request mitigation for its IP addresses, but a DDoS 4763 mitigator can request mitigation for any target resource in the 4764 network). Furthermore, DOTS clients are typically co-located on 4765 network security services (e.g., firewall), and a compromised 4766 security service potentially can do a lot more damage to the network. 4768 Rate-limiting DOTS requests, including those with new 'cuid' values, 4769 from the same DOTS client defend against DoS attacks that would 4770 result in varying the 'cuid' to exhaust DOTS server resources. Rate- 4771 limit policies SHOULD be enforced on DOTS gateways (if deployed) and 4772 DOTS servers. 4774 In order to prevent leaking internal information outside a client's 4775 domain, DOTS gateways located in the client domain SHOULD NOT reveal 4776 the identification information that pertains to internal DOTS clients 4777 (e.g., source IP address, client's hostname) unless explicitly 4778 configured to do so. 4780 DOTS servers MUST verify that requesting DOTS clients are entitled to 4781 trigger actions on a given IP prefix. A DOTS server MUST NOT 4782 authorize actions due to a DOTS client request unless those actions 4783 are limited to that DOTS client's domain IP resources. The exact 4784 mechanism for the DOTS servers to validate that the target prefixes 4785 are within the scope of the DOTS client domain is deployment 4786 specific. 4788 The presence of DOTS gateways may lead to infinite forwarding loops, 4789 which is undesirable. To prevent and detect such loops, this 4790 document uses the Hop-Limit Option. 4792 When FQDNs are used as targets, the DOTS server MUST rely upon DNS 4793 privacy-enabling protocols (e.g., DNS over TLS [RFC7858] or DNS over 4794 HTTPS (DoH) [RFC8484]) to prevent eavesdroppers from possibly 4795 identifying the target resources protected by the DDoS mitigation 4796 service to ensure the target FQDN resolution is authentic (e.g., 4797 DNSSEC [RFC4034]). 4799 CoAP-specific security considerations are discussed in Section 11 of 4800 [RFC7252], while CBOR-related security considerations are discussed 4801 in Section 10 of [RFC8949]. 4803 This document defines YANG data structures that are meant to be used 4804 as an abstract representation of DOTS signal channel messages. As 4805 such, the "ietf-dots-signal-channel" module does not introduce any 4806 new vulnerabilities beyond those specified above. 4808 12. References 4810 12.1. Normative References 4812 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 4813 DOI 10.17487/RFC0791, September 1981, 4814 . 4816 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 4817 Communication Layers", STD 3, RFC 1122, 4818 DOI 10.17487/RFC1122, October 1989, 4819 . 4821 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4822 Requirement Levels", BCP 14, RFC 2119, 4823 DOI 10.17487/RFC2119, March 1997, 4824 . 4826 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 4827 DOI 10.17487/RFC3688, January 2004, 4828 . 4830 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 4831 Resource Identifier (URI): Generic Syntax", STD 66, 4832 RFC 3986, DOI 10.17487/RFC3986, January 2005, 4833 . 4835 [RFC4279] Eronen, P., Ed. and H. Tschofenig, Ed., "Pre-Shared Key 4836 Ciphersuites for Transport Layer Security (TLS)", 4837 RFC 4279, DOI 10.17487/RFC4279, December 2005, 4838 . 4840 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 4841 (CIDR): The Internet Address Assignment and Aggregation 4842 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 4843 2006, . 4845 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 4846 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 4847 . 4849 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 4850 (TLS) Protocol Version 1.2", RFC 5246, 4851 DOI 10.17487/RFC5246, August 2008, 4852 . 4854 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 4855 Housley, R., and W. Polk, "Internet X.509 Public Key 4856 Infrastructure Certificate and Certificate Revocation List 4857 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 4858 . 4860 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 4861 the Network Configuration Protocol (NETCONF)", RFC 6020, 4862 DOI 10.17487/RFC6020, October 2010, 4863 . 4865 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 4866 Extensions: Extension Definitions", RFC 6066, 4867 DOI 10.17487/RFC6066, January 2011, 4868 . 4870 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 4871 Verification of Domain-Based Application Service Identity 4872 within Internet Public Key Infrastructure Using X.509 4873 (PKIX) Certificates in the Context of Transport Layer 4874 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 4875 2011, . 4877 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 4878 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 4879 January 2012, . 4881 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 4882 RFC 6991, DOI 10.17487/RFC6991, July 2013, 4883 . 4885 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 4886 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 4887 Transport Layer Security (TLS) and Datagram Transport 4888 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 4889 June 2014, . 4891 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 4892 Application Protocol (CoAP)", RFC 7252, 4893 DOI 10.17487/RFC7252, June 2014, 4894 . 4896 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 4897 "Recommendations for Secure Use of Transport Layer 4898 Security (TLS) and Datagram Transport Layer Security 4899 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 4900 2015, . 4902 [RFC7641] Hartke, K., "Observing Resources in the Constrained 4903 Application Protocol (CoAP)", RFC 7641, 4904 DOI 10.17487/RFC7641, September 2015, 4905 . 4907 [RFC7918] Langley, A., Modadugu, N., and B. Moeller, "Transport 4908 Layer Security (TLS) False Start", RFC 7918, 4909 DOI 10.17487/RFC7918, August 2016, 4910 . 4912 [RFC7924] Santesson, S. and H. Tschofenig, "Transport Layer Security 4913 (TLS) Cached Information Extension", RFC 7924, 4914 DOI 10.17487/RFC7924, July 2016, 4915 . 4917 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 4918 RFC 7950, DOI 10.17487/RFC7950, August 2016, 4919 . 4921 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 4922 the Constrained Application Protocol (CoAP)", RFC 7959, 4923 DOI 10.17487/RFC7959, August 2016, 4924 . 4926 [RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 4927 Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, 4928 March 2017, . 4930 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 4931 Writing an IANA Considerations Section in RFCs", BCP 26, 4932 RFC 8126, DOI 10.17487/RFC8126, June 2017, 4933 . 4935 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 4936 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 4937 May 2017, . 4939 [RFC8200] Deering, S. and R. Hinden, "Internet Protocol, Version 6 4940 (IPv6) Specification", STD 86, RFC 8200, 4941 DOI 10.17487/RFC8200, July 2017, 4942 . 4944 [RFC8305] Schinazi, D. and T. Pauly, "Happy Eyeballs Version 2: 4945 Better Connectivity Using Concurrency", RFC 8305, 4946 DOI 10.17487/RFC8305, December 2017, 4947 . 4949 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 4950 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 4951 Application Protocol) over TCP, TLS, and WebSockets", 4952 RFC 8323, DOI 10.17487/RFC8323, February 2018, 4953 . 4955 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 4956 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 4957 . 4959 [RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers 4960 (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, 4961 . 4963 [RFC8768] Boucadair, M., Reddy.K, T., and J. Shallow, "Constrained 4964 Application Protocol (CoAP) Hop-Limit Option", RFC 8768, 4965 DOI 10.17487/RFC8768, March 2020, 4966 . 4968 [RFC8783] Boucadair, M., Ed. and T. Reddy.K, Ed., "Distributed 4969 Denial-of-Service Open Threat Signaling (DOTS) Data 4970 Channel Specification", RFC 8783, DOI 10.17487/RFC8783, 4971 May 2020, . 4973 [RFC8791] Bierman, A., Bjoerklund, M., and K. Watsen, "YANG Data 4974 Structure Extensions", RFC 8791, DOI 10.17487/RFC8791, 4975 June 2020, . 4977 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 4978 Representation (CBOR)", STD 94, RFC 8949, 4979 DOI 10.17487/RFC8949, December 2020, 4980 . 4982 12.2. Informative References 4984 [I-D.boucadair-dots-earlydata] 4985 Boucadair, M. and T. Reddy, "Using Early Data in DOTS", 4986 draft-boucadair-dots-earlydata-00 (work in progress), 4987 January 2019. 4989 [I-D.ietf-core-comi] 4990 Veillette, M., Stok, P. V. D., Pelov, A., Bierman, A., and 4991 I. Petrov, "CoAP Management Interface (CORECONF)", draft- 4992 ietf-core-comi-11 (work in progress), January 2021. 4994 [I-D.ietf-core-yang-cbor] 4995 Veillette, M., Petrov, I., and A. Pelov, "CBOR Encoding of 4996 Data Modeled with YANG", draft-ietf-core-yang-cbor-15 4997 (work in progress), January 2021. 4999 [I-D.ietf-dots-multihoming] 5000 Boucadair, M., Reddy, T., and W. Pan, "Multi-homing 5001 Deployment Considerations for Distributed-Denial-of- 5002 Service Open Threat Signaling (DOTS)", draft-ietf-dots- 5003 multihoming-05 (work in progress), November 2020. 5005 [I-D.ietf-dots-telemetry] 5006 Boucadair, M., Reddy, T., Doron, E., Chen, M., and J. 5007 Shallow, "Distributed Denial-of-Service Open Threat 5008 Signaling (DOTS) Telemetry", draft-ietf-dots-telemetry-15 5009 (work in progress), December 2020. 5011 [I-D.ietf-tls-dtls13] 5012 Rescorla, E., Tschofenig, H., and N. Modadugu, "The 5013 Datagram Transport Layer Security (DTLS) Protocol Version 5014 1.3", draft-ietf-tls-dtls13-43 (work in progress), April 5015 2021. 5017 [IANA-CBOR-Tags] 5018 IANA, "Concise Binary Object Representation (CBOR) Tags", 5019 . 5022 [IANA-CoAP-Content-Formats] 5023 IANA, "CoAP Content-Formats", 5024 . 5027 [IANA-MediaTypes] 5028 IANA, "Media Types", 5029 . 5031 [IANA-Proto] 5032 IANA, "Protocol Numbers", 2011, 5033 . 5035 [REG-DOTS] 5036 IANA, "Distributed Denial-of-Service Open Threat Signaling 5037 (DOTS) Signal Channel", 5038 . 5040 [RFC3022] Srisuresh, P. and K. Egevang, "Traditional IP Network 5041 Address Translator (Traditional NAT)", RFC 3022, 5042 DOI 10.17487/RFC3022, January 2001, 5043 . 5045 [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. 5046 Rose, "Resource Records for the DNS Security Extensions", 5047 RFC 4034, DOI 10.17487/RFC4034, March 2005, 5048 . 5050 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 5051 Unique IDentifier (UUID) URN Namespace", RFC 4122, 5052 DOI 10.17487/RFC4122, July 2005, 5053 . 5055 [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram 5056 Congestion Control Protocol (DCCP)", RFC 4340, 5057 DOI 10.17487/RFC4340, March 2006, 5058 . 5060 [RFC4732] Handley, M., Ed., Rescorla, E., Ed., and IAB, "Internet 5061 Denial-of-Service Considerations", RFC 4732, 5062 DOI 10.17487/RFC4732, December 2006, 5063 . 5065 [RFC4787] Audet, F., Ed. and C. Jennings, "Network Address 5066 Translation (NAT) Behavioral Requirements for Unicast 5067 UDP", BCP 127, RFC 4787, DOI 10.17487/RFC4787, January 5068 2007, . 5070 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 5071 RFC 4960, DOI 10.17487/RFC4960, September 2007, 5072 . 5074 [RFC4987] Eddy, W., "TCP SYN Flooding Attacks and Common 5075 Mitigations", RFC 4987, DOI 10.17487/RFC4987, August 2007, 5076 . 5078 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 5079 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 5080 June 2010, . 5082 [RFC6052] Bao, C., Huitema, C., Bagnulo, M., Boucadair, M., and X. 5083 Li, "IPv6 Addressing of IPv4/IPv6 Translators", RFC 6052, 5084 DOI 10.17487/RFC6052, October 2010, 5085 . 5087 [RFC6146] Bagnulo, M., Matthews, P., and I. van Beijnum, "Stateful 5088 NAT64: Network Address and Protocol Translation from IPv6 5089 Clients to IPv4 Servers", RFC 6146, DOI 10.17487/RFC6146, 5090 April 2011, . 5092 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 5093 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 5094 DOI 10.17487/RFC6234, May 2011, 5095 . 5097 [RFC6296] Wasserman, M. and F. Baker, "IPv6-to-IPv6 Network Prefix 5098 Translation", RFC 6296, DOI 10.17487/RFC6296, June 2011, 5099 . 5101 [RFC6724] Thaler, D., Ed., Draves, R., Matsumoto, A., and T. Chown, 5102 "Default Address Selection for Internet Protocol Version 6 5103 (IPv6)", RFC 6724, DOI 10.17487/RFC6724, September 2012, 5104 . 5106 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 5107 Specifications and Registration Procedures", BCP 13, 5108 RFC 6838, DOI 10.17487/RFC6838, January 2013, 5109 . 5111 [RFC6887] Wing, D., Ed., Cheshire, S., Boucadair, M., Penno, R., and 5112 P. Selkirk, "Port Control Protocol (PCP)", RFC 6887, 5113 DOI 10.17487/RFC6887, April 2013, 5114 . 5116 [RFC6888] Perreault, S., Ed., Yamagata, I., Miyakawa, S., Nakagawa, 5117 A., and H. Ashida, "Common Requirements for Carrier-Grade 5118 NATs (CGNs)", BCP 127, RFC 6888, DOI 10.17487/RFC6888, 5119 April 2013, . 5121 [RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed., 5122 "Enrollment over Secure Transport", RFC 7030, 5123 DOI 10.17487/RFC7030, October 2013, 5124 . 5126 [RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 5127 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 5128 . 5130 [RFC7452] Tschofenig, H., Arkko, J., Thaler, D., and D. McPherson, 5131 "Architectural Considerations in Smart Object Networking", 5132 RFC 7452, DOI 10.17487/RFC7452, March 2015, 5133 . 5135 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 5136 NETCONF Protocol over Transport Layer Security (TLS) with 5137 Mutual X.509 Authentication", RFC 7589, 5138 DOI 10.17487/RFC7589, June 2015, 5139 . 5141 [RFC7858] Hu, Z., Zhu, L., Heidemann, J., Mankin, A., Wessels, D., 5142 and P. Hoffman, "Specification for DNS over Transport 5143 Layer Security (TLS)", RFC 7858, DOI 10.17487/RFC7858, May 5144 2016, . 5146 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 5147 RFC 7951, DOI 10.17487/RFC7951, August 2016, 5148 . 5150 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 5151 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 5152 . 5154 [RFC8484] Hoffman, P. and P. McManus, "DNS Queries over HTTPS 5155 (DoH)", RFC 8484, DOI 10.17487/RFC8484, October 2018, 5156 . 5158 [RFC8489] Petit-Huguenin, M., Salgueiro, G., Rosenberg, J., Wing, 5159 D., Mahy, R., and P. Matthews, "Session Traversal 5160 Utilities for NAT (STUN)", RFC 8489, DOI 10.17487/RFC8489, 5161 February 2020, . 5163 [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 5164 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 5165 January 2019, . 5167 [RFC8612] Mortensen, A., Reddy, T., and R. Moskowitz, "DDoS Open 5168 Threat Signaling (DOTS) Requirements", RFC 8612, 5169 DOI 10.17487/RFC8612, May 2019, 5170 . 5172 [RFC8782] Reddy.K, T., Ed., Boucadair, M., Ed., Patil, P., 5173 Mortensen, A., and N. Teague, "Distributed Denial-of- 5174 Service Open Threat Signaling (DOTS) Signal Channel 5175 Specification", RFC 8782, DOI 10.17487/RFC8782, May 2020, 5176 . 5178 [RFC8811] Mortensen, A., Ed., Reddy.K, T., Ed., Andreasen, F., 5179 Teague, N., and R. Compton, "DDoS Open Threat Signaling 5180 (DOTS) Architecture", RFC 8811, DOI 10.17487/RFC8811, 5181 August 2020, . 5183 [RFC8903] Dobbins, R., Migault, D., Moskowitz, R., Teague, N., Xia, 5184 L., and K. Nishizuka, "Use Cases for DDoS Open Threat 5185 Signaling", RFC 8903, DOI 10.17487/RFC8903, May 2021, 5186 . 5188 [RFC8973] Boucadair, M. and T. Reddy.K, "DDoS Open Threat Signaling 5189 (DOTS) Agent Discovery", RFC 8973, DOI 10.17487/RFC8973, 5190 January 2021, . 5192 [URI] IANA, "Well-Known URIs", 5193 . 5196 Appendix A. Summary of Changes From RFC8782 5198 The main changes compared to [RFC8782] are as follows: 5200 o Update the "ietf-dots-signal-channel" YANG module (Section 5.3) 5201 and the tree structure (Section 5.1) to follow the new YANG data 5202 structure specified in [RFC8791]. In particular: 5204 * Add in 'choice' to indicate the communication direction in 5205 which a data node applies. If no 'choice' is indicated, a data 5206 node can appear in both directions (i.e., from DOTS clients to 5207 DOTS servers and vice versa). 5209 * Remove 'config' clauses. Note that 'config' statements will be 5210 ignored (if present) anyway according to Section 4 of 5211 [RFC8791]. This supersedes the references to the use of 'ro' 5212 and 'rw' which are now covered by 'choice' above. 5214 * Remove 'cuid', 'cdid', and 'sid' data nodes from the structure 5215 because these data nodes are included as Uri-Path options, not 5216 within the message body. 5218 * Remove the list keys for the mitigation scope message type 5219 (i.e., 'cuid' and 'mid'). 'mid' is not indicated as a key 5220 because it is included as Uri-Path option for requests and in 5221 the message body for responses. Note that Section 4 of 5222 [RFC8791] specifies that a list does not require to have a key 5223 statement defined. 5225 o Add a new section with a summary of the error code responses that 5226 can be returned by a DOTS server (Section 9). 5228 o Update the IANA section to allocate a new range for comprehension- 5229 optional attributes (Section 10.6.1.1). This modification is 5230 motivated by the need to allow for compact DOTS signal messages 5231 that include a long list of comprehension-optional attributes, 5232 e.g., DOTS telemetry messages [I-D.ietf-dots-telemetry]. 5234 o Add Appendix C to list recommended/default values of key DOTS 5235 signal channel parameters. 5237 o Add subsections to Section 4.4.1 for better readability. 5239 Appendix B. CUID Generation 5241 The document recommends the use of SPKI to generate the 'cuid'. This 5242 design choice is motivated by the following reasons: 5244 o SPKI is globally unique. 5246 o It is deterministic. 5248 o It allows the avoidance of extra cycles that may be induced by 5249 'cuid' collision. 5251 o DOTS clients do not need to store the 'cuid' in a persistent 5252 storage. 5254 o It allows the detection of compromised DOTS clients that do not 5255 adhere to the 'cuid' generation algorithm. 5257 Appendix C. Summary of Protocol Recommended/Default Values 5259 +--------------------------------+---------------------------+ 5260 | Parameter | Recommended/Default Value | 5261 +--------------------------------+---------------------------+ 5262 | Port number | 4646 (tcp/udp) | 5263 | lifetime | 3600 seconds | 5264 | active-but-terminating | 120 seconds | 5265 | maximum active-but-terminating | 300 seconds | 5266 | heartbeat-interval | 30 seconds | 5267 | minimum 'heartbeat-interval' | 15 seconds | 5268 | maximum 'heartbeat-interval' | 240 seconds | 5269 | missing-hb-allowed | 15 | 5270 | max-retransmit | 3 | 5271 | ack-timeout | 2 seconds | 5272 | ack-random-factor | 1.5 | 5273 | probing-rate | 5 bytes/second | 5274 | trigger-mitigation | true | 5275 +--------------------------------+---------------------------+ 5277 Appendix D. Acknowledgements 5279 Many thanks to Martin Bjoerklund for the suggestion to use RFC8791. 5281 Thanks to Valery Smyslov for the comments, guidance, and support. 5283 Thanks to Ebben Aries for the yangdoctors review, Dan Romascanu for 5284 the opsdir review, Michael Tuexen for the tsv-art review, Dale Worley 5285 for the genart review, and Donald Eastlake for the secdir review. 5287 Thanks to Benjamin Kaduk for the AD review. 5289 Thanks to Martin Duke, Lars Eggert, Erik Kline, Murray Kucherawy, 5290 Eric Vyncke, and Robert Wilton for the IESG review. 5292 D.1. Acknowledgements from RFC8782 5294 Thanks to Christian Jacquenet, Roland Dobbins, Roman Danyliw, Michael 5295 Richardson, Ehud Doron, Kaname Nishizuka, Dave Dolson, Liang Xia, 5296 Gilbert Clark, Xialiang Frank, Jim Schaad, Klaus Hartke, Nesredien 5297 Suleiman, Stephen Farrell, and Yoshifumi Nishida for the discussion 5298 and comments. 5300 The authors would like to give special thanks to Kaname Nishizuka and 5301 Jon Shallow for their efforts in implementing the protocol and 5302 performing interop testing at IETF Hackathons. 5304 Thanks to the core WG for the recommendations on Hop-Limit and 5305 redirect signaling. 5307 Special thanks to Benjamin Kaduk for the detailed AD review. 5309 Thanks to Alexey Melnikov, Adam Roach, Suresh Krishnan, Mirja 5310 Kuehlewind, and Alissa Cooper for the review. 5312 Thanks to Carsten Bormann for his review of the DOTS heartbeat 5313 mechanism. 5315 Appendix E. Contributors 5317 E.1. Authors of RFC8782 5319 The authors of RFC8782 are listed below: 5321 Tirumaleswar Reddy.K (editor) 5322 McAfee, Inc. 5323 Embassy Golf Link Business Park 5324 Bangalore 560071 5325 Karnataka 5326 India 5328 Email: kondtir@gmail.com 5330 Mohamed Boucadair (editor) 5331 Orange 5332 35000 Rennes 5333 France 5335 Email: mohamed.boucadair@orange.com 5337 Prashanth Patil 5338 Cisco Systems, Inc. 5340 Email: praspati@cisco.com 5342 Andrew Mortensen 5343 Arbor Networks, Inc. 5344 2727 S. State Street 5345 Ann Arbor, MI 48104 5346 United States of America 5348 Email: andrew@moretension.com 5350 Nik Teague 5351 Iron Mountain Data Centers 5352 United Kingdom 5354 Email: nteague@ironmountain.co.uk 5356 E.2. Contributors to RFC8782 5358 The following individuals have contributed to RFC8782: 5360 Jon Shallow 5361 NCC Group 5363 Email: jon.shallow@nccgroup.trust 5365 Mike Geller 5366 Cisco Systems, Inc. 5367 FL 33309 5368 United States of America 5370 Email: mgeller@cisco.com 5372 Robert Moskowitz 5373 HTT Consulting 5374 Oak Park, MI 42837 5375 United States of America 5377 Email: rgm@htt-consult.com 5379 Authors' Addresses 5381 Mohamed Boucadair (editor) 5382 Orange 5383 Rennes 35000 5384 France 5386 Email: mohamed.boucadair@orange.com 5388 Jon Shallow 5389 United Kingdom 5391 Email: supjps-ietf@jpshallow.com 5393 Tirumaleswar Reddy.K 5394 McAfee, Inc. 5395 Embassy Golf Link Business Park 5396 Bangalore, Karnataka 560071 5397 India 5399 Email: kondtir@gmail.com