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