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