idnits 2.17.1 draft-boucadair-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 : ---------------------------------------------------------------------------- No issues found here. 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 2715 has weird spacing: '...er-port ine...' == Line 2722 has weird spacing: '...cl-name lea...' -- The document date (August 3, 2020) is 1355 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 4729, but not defined == Missing Reference: 'RFCXXXx' is mentioned on line 4174, but not defined == Missing Reference: 'RFXXXX' is mentioned on line 4232, but not defined ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) ** Downref: Normative reference to an Informational RFC: RFC 7918 == Outdated reference: A later version (-17) exists of draft-ietf-core-comi-10 == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-13 == Outdated reference: A later version (-13) exists of draft-ietf-dots-multihoming-04 == Outdated reference: A later version (-15) exists of draft-ietf-dots-server-discovery-10 == Outdated reference: A later version (-25) exists of draft-ietf-dots-telemetry-10 == Outdated reference: A later version (-43) exists of draft-ietf-tls-dtls13-38 -- Obsolete informational reference (is this intentional?): RFC 4960 (Obsoleted by RFC 9260) -- Obsolete informational reference (is this intentional?): RFC 8499 (Obsoleted by RFC 9499) -- Obsolete informational reference (is this intentional?): RFC 8782 (Obsoleted by RFC 9132) Summary: 6 errors (**), 0 flaws (~~), 13 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 DOTS M. Boucadair, Ed. 3 Internet-Draft Orange 4 Obsoletes: 8782 (if approved) J. Shallow 5 Intended status: Standards Track 6 Expires: February 4, 2021 T. Reddy.K 7 McAfee 8 August 3, 2020 10 Distributed Denial-of-Service Open Threat Signaling (DOTS) Signal 11 Channel Specification 12 draft-boucadair-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 February 4, 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 . . . . . . . . . . . . 80 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 . . . . . . . . . . . . . . . . 85 91 7.3. DTLS MTU and Fragmentation . . . . . . . . . . . . . . . 87 92 8. Mutual Authentication of DOTS Agents & Authorization of DOTS 93 Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 94 9. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 90 95 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 91 96 10.1. DOTS Signal Channel UDP and TCP Port Number . . . . . . 91 97 10.2. Well-Known 'dots' URI . . . . . . . . . . . . . . . . . 92 98 10.3. Media Type Registration . . . . . . . . . . . . . . . . 92 99 10.4. CoAP Content-Formats Registration . . . . . . . . . . . 93 100 10.5. CBOR Tag Registration . . . . . . . . . . . . . . . . . 94 101 10.6. DOTS Signal Channel Protocol Registry . . . . . . . . . 94 102 10.6.1. DOTS Signal Channel CBOR Key Values Subregistry . . 94 103 10.6.1.1. Registration Template . . . . . . . . . . . . . 94 104 10.6.1.2. Update Subregistry Content . . . . . . . . . . . 96 105 10.6.2. Status Codes Subregistry . . . . . . . . . . . . . . 99 106 10.6.3. Conflict Status Codes Subregistry . . . . . . . . . 100 107 10.6.4. Conflict Cause Codes Subregistry . . . . . . . . . . 101 108 10.6.5. Attack Status Codes Subregistry . . . . . . . . . . 102 109 10.7. DOTS Signal Channel YANG Modules . . . . . . . . . . . . 103 110 11. Security Considerations . . . . . . . . . . . . . . . . . . . 105 111 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 107 112 12.1. Normative References . . . . . . . . . . . . . . . . . . 107 113 12.2. Informative References . . . . . . . . . . . . . . . . . 110 114 Appendix A. Summary of Changes From RFC8782 . . . . . . . . . . 115 115 Appendix B. CUID Generation . . . . . . . . . . . . . . . . . . 116 116 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 116 117 C.1. Acknowledgements from RFC8782 . . . . . . . . . . . . . . 116 118 Appendix D. Contributors . . . . . . . . . . . . . . . . . . . . 117 119 D.1. Authors of RFC8782 . . . . . . . . . . . . . . . . . . . 117 120 D.2. Contributors to RFC8782 . . . . . . . . . . . . . . . . . 118 121 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 119 123 1. Introduction 125 A Distributed Denial-of-Service (DDoS) attack is a distributed 126 attempt to make machines or network resources unavailable to their 127 intended users. In most cases, sufficient scale for an effective 128 attack can be achieved by compromising enough end hosts and using 129 those infected hosts to perpetrate and amplify the attack. The 130 victim in this attack can be an application server, a host, a router, 131 a firewall, or an entire network. 133 Network applications have finite resources like CPU cycles, the 134 number of processes or threads they can create and use, the maximum 135 number of simultaneous connections they can handle, the resources 136 assigned to the control plane, etc. When processing network traffic, 137 such applications are supposed to use these resources to provide the 138 intended functionality in the most efficient manner. However, a DDoS 139 attacker may be able to prevent an application from performing its 140 intended task by making the application exhaust its finite resources. 142 A TCP DDoS SYN flood [RFC4987], for example, is a memory-exhausting 143 attack while an ACK flood is a CPU-exhausting attack. Attacks on the 144 link are carried out by sending enough traffic so that the link 145 becomes congested, thereby likely causing packet loss for legitimate 146 traffic. Stateful firewalls can also be attacked by sending traffic 147 that causes the firewall to maintain an excessive number of states 148 that may jeopardize the firewall's operation overall, in addition to 149 likely performance impacts. The firewall then runs out of memory, 150 and it can no longer instantiate the states required to process 151 legitimate flows. Other possible DDoS attacks are discussed in 152 [RFC4732]. 154 In many cases, it may not be possible for network administrators to 155 determine the cause(s) of an attack. They may instead just realize 156 that certain resources seem to be under attack. This document 157 defines a lightweight protocol that allows a DOTS client to request 158 mitigation from one or more DOTS servers for protection against 159 detected, suspected, or anticipated attacks. This protocol enables 160 cooperation between DOTS agents to permit a highly automated network 161 defense that is robust, reliable, and secure. Note that "secure" 162 means the support of the features defined in Section 2.4 of 163 [RFC8612]. 165 An example of a network diagram that illustrates a deployment of DOTS 166 agents is shown in Figure 1. In this example, a DOTS server is 167 operating on the access network. A DOTS client is located on the LAN 168 (Local Area Network), while a DOTS gateway is embedded in the CPE 169 (Customer Premises Equipment). 171 Network 172 Resource CPE Router Access Network __________ 173 +-----------+ +--------------+ +-------------+ / \ 174 | |___| |____| |___ | Internet | 175 |DOTS Client| | DOTS Gateway | | DOTS Server | | | 176 | | | | | | | | 177 +-----------+ +--------------+ +-------------+ \__________/ 179 Figure 1: Sample DOTS Deployment (1) 181 DOTS servers can also be reachable over the Internet, as depicted in 182 Figure 2. 184 Network DDoS Mitigation 185 Resource CPE Router __________ Service 186 +-----------+ +--------------+ / \ +-------------+ 187 | |___| |____| |___ | | 188 |DOTS Client| | DOTS Gateway | | Internet | | DOTS Server | 189 | | | | | | | | 190 +-----------+ +--------------+ \__________/ +-------------+ 192 Figure 2: Sample DOTS Deployment (2) 194 In typical deployments, the DOTS client belongs to a different 195 administrative domain than the DOTS server. For example, the DOTS 196 client is embedded in a firewall protecting services owned and 197 operated by a customer, while the DOTS server is owned and operated 198 by a different administrative entity (service provider, typically) 199 providing DDoS mitigation services. The latter might or might not 200 provide connectivity services to the network hosting the DOTS client. 202 The DOTS server may (not) be co-located with the DOTS mitigator. In 203 typical deployments, the DOTS server belongs to the same 204 administrative domain as the mitigator. The DOTS client can 205 communicate directly with a DOTS server or indirectly via a DOTS 206 gateway. 208 This document adheres to the DOTS architecture 209 [I-D.ietf-dots-architecture]. The requirements for DOTS signal 210 channel protocol are documented in [RFC8612]. This document 211 satisfies all the use cases discussed in [I-D.ietf-dots-use-cases]. 213 This document focuses on the DOTS signal channel. This is a 214 companion document of the DOTS data channel specification [RFC8783] 215 that defines a configuration and a bulk data exchange mechanism 216 supporting the DOTS signal channel. 218 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 (or 128) for IPv4 (or 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 [I-D.ietf-dots-architecture]. 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? int32 2700 | +-- trigger-mitigation? boolean 2701 | +-- (direction)? 2702 | +--:(server-to-client-only) 2703 | +-- mid? uint32 2704 | +-- mitigation-start? uint64 2705 | +-- status? iana-signal:status 2706 | +-- conflict-information 2707 | | +-- conflict-status? 2708 | | | iana-signal:conflict-status 2709 | | +-- conflict-cause? 2710 | | | iana-signal:conflict-cause 2711 | | +-- retry-timer? uint32 2712 | | +-- conflict-scope 2713 | | +-- target-prefix* inet:ip-prefix 2714 | | +-- target-port-range* [lower-port] 2715 | | | +-- lower-port inet:port-number 2716 | | | +-- upper-port? inet:port-number 2717 | | +-- target-protocol* uint8 2718 | | +-- target-fqdn* inet:domain-name 2719 | | +-- target-uri* inet:uri 2720 | | +-- alias-name* string 2721 | | +-- acl-list* [acl-name] 2722 | | | +-- acl-name leafref 2723 | | | +-- acl-type? leafref 2724 | | +-- mid? uint32 2725 | +-- bytes-dropped? 2726 | | yang:zero-based-counter64 2727 | +-- bps-dropped? yang:gauge64 2728 | +-- pkts-dropped? 2729 | | yang:zero-based-counter64 2730 | +-- pps-dropped? yang:gauge64 2731 | +-- attack-status? 2732 | iana-signal:attack-status 2733 +--:(signal-config) 2734 | +-- mitigating-config 2735 | | +-- heartbeat-interval 2736 | | | +-- (direction)? 2737 | | | | +--:(server-to-client-only) 2738 | | | | +-- max-value? uint16 2739 | | | | +-- min-value? uint16 2740 | | | +-- current-value? uint16 2741 | | +-- missing-hb-allowed 2742 | | | +-- (direction)? 2743 | | | | +--:(server-to-client-only) 2744 | | | | +-- max-value? uint16 2745 | | | | +-- min-value? uint16 2746 | | | +-- current-value? uint16 2747 | | +-- probing-rate 2748 | | | +-- (direction)? 2749 | | | | +--:(server-to-client-only) 2750 | | | | +-- max-value? uint16 2751 | | | | +-- min-value? uint16 2752 | | | +-- current-value? uint16 2753 | | +-- max-retransmit 2754 | | | +-- (direction)? 2755 | | | | +--:(server-to-client-only) 2756 | | | | +-- max-value? uint16 2757 | | | | +-- min-value? uint16 2758 | | | +-- current-value? uint16 2759 | | +-- ack-timeout 2760 | | | +-- (direction)? 2761 | | | | +--:(server-to-client-only) 2762 | | | | +-- max-value-decimal? decimal64 2763 | | | | +-- min-value-decimal? decimal64 2764 | | | +-- current-value-decimal? decimal64 2765 | | +-- ack-random-factor 2766 | | +-- (direction)? 2767 | | | +--:(server-to-client-only) 2768 | | | +-- max-value-decimal? decimal64 2769 | | | +-- min-value-decimal? decimal64 2770 | | +-- current-value-decimal? decimal64 2771 | +-- idle-config 2772 | +-- heartbeat-interval 2773 | | +-- (direction)? 2774 | | | +--:(server-to-client-only) 2775 | | | +-- max-value? uint16 2776 | | | +-- min-value? uint16 2777 | | +-- current-value? uint16 2778 | +-- missing-hb-allowed 2779 | | +-- (direction)? 2780 | | | +--:(server-to-client-only) 2781 | | | +-- max-value? uint16 2782 | | | +-- min-value? uint16 2783 | | +-- current-value? uint16 2784 | +-- probing-rate 2785 | | +-- (direction)? 2786 | | | +--:(server-to-client-only) 2787 | | | +-- max-value? uint16 2788 | | | +-- min-value? uint16 2789 | | +-- current-value? uint16 2790 | +-- max-retransmit 2791 | | +-- (direction)? 2792 | | | +--:(server-to-client-only) 2793 | | | +-- max-value? uint16 2794 | | | +-- min-value? uint16 2795 | | +-- current-value? uint16 2796 | +-- ack-timeout 2797 | | +-- (direction)? 2798 | | | +--:(server-to-client-only) 2799 | | | +-- max-value-decimal? decimal64 2800 | | | +-- min-value-decimal? decimal64 2801 | | +-- current-value-decimal? decimal64 2802 | +-- ack-random-factor 2803 | +-- (direction)? 2804 | | +--:(server-to-client-only) 2805 | | +-- max-value-decimal? decimal64 2806 | | +-- min-value-decimal? decimal64 2807 | +-- current-value-decimal? decimal64 2808 +--:(redirected-signal) 2809 | +-- (direction)? 2810 | +--:(server-to-client-only) 2811 | +-- alt-server string 2812 | +-- alt-server-record* inet:ip-address 2813 +--:(heartbeat) 2814 +-- peer-hb-status boolean 2816 5.2. IANA DOTS Signal Channel YANG Module 2818 file "iana-dots-signal-channel@2020-05-28.yang" 2819 module iana-dots-signal-channel { 2820 yang-version 1.1; 2821 namespace "urn:ietf:params:xml:ns:yang:iana-dots-signal-channel"; 2822 prefix iana-signal; 2824 organization 2825 "IANA"; 2826 contact 2827 "Internet Assigned Numbers Authority 2829 Postal: ICANN 2830 12025 Waterfront Drive, Suite 300 2831 Los Angeles, CA 90094-2536 2832 United States of America 2833 Tel: +1 310 301 5800 2834 "; 2835 description 2836 "This module contains a collection of YANG data types defined 2837 by IANA and used for DOTS signal channel protocol. 2839 Copyright (c) 2020 IETF Trust and the persons identified as 2840 authors of the code. All rights reserved. 2842 Redistribution and use in source and binary forms, with or 2843 without modification, is permitted pursuant to, and subject 2844 to the license terms contained in, the Simplified BSD License 2845 set forth in Section 4.c of the IETF Trust's Legal Provisions 2846 Relating to IETF Documents 2847 (http://trustee.ietf.org/license-info). 2848 This version of this YANG module is part of RFC 8782; see 2849 the RFC itself for full legal notices."; 2851 revision 2020-05-28 { 2852 description 2853 "Initial revision."; 2854 reference 2855 "RFC 8782: Distributed Denial-of-Service Open Threat 2856 Signaling (DOTS) Signal Channel Specification"; 2857 } 2859 typedef status { 2860 type enumeration { 2861 enum attack-mitigation-in-progress { 2862 value 1; 2863 description 2864 "Attack mitigation setup is in progress (e.g., changing 2865 the network path to reroute the inbound traffic 2866 to DOTS mitigator)."; 2867 } 2868 enum attack-successfully-mitigated { 2869 value 2; 2870 description 2871 "Attack is being successfully mitigated (e.g., traffic 2872 is redirected to a DDoS mitigator and attack 2873 traffic is dropped or blackholed)."; 2874 } 2875 enum attack-stopped { 2876 value 3; 2877 description 2878 "Attack has stopped and the DOTS client can 2879 withdraw the mitigation request."; 2880 } 2881 enum attack-exceeded-capability { 2882 value 4; 2883 description 2884 "Attack has exceeded the mitigation provider 2885 capability."; 2886 } 2887 enum dots-client-withdrawn-mitigation { 2888 value 5; 2889 description 2890 "DOTS client has withdrawn the mitigation 2891 request and the mitigation is active but 2892 terminating."; 2893 } 2894 enum attack-mitigation-terminated { 2895 value 6; 2896 description 2897 "Attack mitigation is now terminated."; 2898 } 2899 enum attack-mitigation-withdrawn { 2900 value 7; 2901 description 2902 "Attack mitigation is withdrawn."; 2903 } 2904 enum attack-mitigation-signal-loss { 2905 value 8; 2906 description 2907 "Attack mitigation will be triggered 2908 for the mitigation request only when 2909 the DOTS signal channel session is lost."; 2910 } 2911 } 2912 description 2913 "Enumeration for status reported by the DOTS server."; 2914 } 2916 typedef conflict-status { 2917 type enumeration { 2918 enum request-inactive-other-active { 2919 value 1; 2920 description 2921 "DOTS Server has detected conflicting mitigation 2922 requests from different DOTS clients. 2923 This mitigation request is currently inactive 2924 until the conflicts are resolved. Another 2925 mitigation request is active."; 2926 } 2927 enum request-active { 2928 value 2; 2929 description 2930 "DOTS Server has detected conflicting mitigation 2931 requests from different DOTS clients. 2932 This mitigation request is currently active."; 2933 } 2934 enum all-requests-inactive { 2935 value 3; 2936 description 2937 "DOTS Server has detected conflicting mitigation 2938 requests from different DOTS clients. All 2939 conflicting mitigation requests are inactive."; 2940 } 2941 } 2942 description 2943 "Enumeration for conflict status."; 2945 } 2947 typedef conflict-cause { 2948 type enumeration { 2949 enum overlapping-targets { 2950 value 1; 2951 description 2952 "Overlapping targets. conflict-scope provides 2953 more details about the exact conflict."; 2954 } 2955 enum conflict-with-acceptlist { 2956 value 2; 2957 description 2958 "Conflicts with an existing accept-list. 2960 This code is returned when the DDoS mitigation 2961 detects that some of the source addresses/prefixes 2962 listed in the accept-list ACLs are actually 2963 attacking the target."; 2964 } 2965 enum cuid-collision { 2966 value 3; 2967 description 2968 "Conflicts with the cuid used by another 2969 DOTS client."; 2970 } 2971 } 2972 description 2973 "Enumeration for conflict causes."; 2974 } 2976 typedef attack-status { 2977 type enumeration { 2978 enum under-attack { 2979 value 1; 2980 description 2981 "The DOTS client determines that it is still under 2982 attack."; 2983 } 2984 enum attack-successfully-mitigated { 2985 value 2; 2986 description 2987 "The DOTS client determines that the attack is 2988 successfully mitigated."; 2989 } 2990 } 2991 description 2992 "Enumeration for attack status codes."; 2994 } 2995 } 2996 2998 5.3. IETF DOTS Signal Channel YANG Module 3000 This module uses the common YANG types defined in [RFC6991] and types 3001 defined in [RFC8783]. 3003 This version obsoletes the version described in Section 5.3 of 3004 [RFC8782]. 3006 file "ietf-dots-signal-channel@2020-07-02.yang" 3007 module ietf-dots-signal-channel { 3008 yang-version 1.1; 3009 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel"; 3010 prefix signal; 3012 import ietf-inet-types { 3013 prefix inet; 3014 reference 3015 "Section 4 of RFC 6991"; 3016 } 3017 import ietf-yang-types { 3018 prefix yang; 3019 reference 3020 "Section 3 of RFC 6991"; 3021 } 3022 import ietf-dots-data-channel { 3023 prefix ietf-data; 3024 reference 3025 "RFC 8783: Distributed Denial-of-Service Open Threat Signaling 3026 (DOTS) Data Channel Specification"; 3027 } 3028 import iana-dots-signal-channel { 3029 prefix iana-signal; 3030 reference 3031 "RFC 8782: Distributed Denial-of-Service Open Threat Signaling 3032 (DOTS) Signal Channel Specification"; 3033 } 3034 import ietf-yang-structure-ext { 3035 prefix sx; 3036 reference 3037 "RFC 8791: YANG Data Structure Extensions"; 3038 } 3040 organization 3041 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 3043 contact 3044 "WG Web: 3045 WG List: 3047 Editor: Mohamed Boucadair 3048 3050 Editor: Jon Shallow 3051 3053 Author: Konda, Tirumaleswar Reddy.K 3054 3056 Author: Prashanth Patil 3057 3059 Author: Andrew Mortensen 3060 3062 Author: Nik Teague 3063 "; 3064 description 3065 "This module contains YANG definition for the signaling 3066 messages exchanged between a DOTS client and a DOTS server. 3068 Copyright (c) 2020 IETF Trust and the persons identified as 3069 authors of the code. All rights reserved. 3071 Redistribution and use in source and binary forms, with or 3072 without modification, is permitted pursuant to, and subject 3073 to the license terms contained in, the Simplified BSD License 3074 set forth in Section 4.c of the IETF Trust's Legal Provisions 3075 Relating to IETF Documents 3076 (http://trustee.ietf.org/license-info). 3078 This version of this YANG module is part of RFC XXXX; see 3079 the RFC itself for full legal notices."; 3081 revision 2020-07-02 { 3082 description 3083 "Updated revision to comply with RFC8791."; 3084 reference 3085 "RFC xxxx: A YANG Data Model for Distributed Denial-of-Service 3086 Open Threat Signaling (DOTS) Signal Channel"; 3087 } 3088 revision 2020-05-28 { 3089 description 3090 "Initial revision."; 3092 reference 3093 "RFC 8782: Distributed Denial-of-Service Open Threat 3094 Signaling (DOTS) Signal Channel Specification"; 3095 } 3097 /* 3098 * Groupings 3099 */ 3101 grouping mitigation-scope { 3102 description 3103 "Specifies the scope of the mitigation request."; 3104 list scope { 3105 description 3106 "The scope of the request."; 3107 uses ietf-data:target; 3108 leaf-list alias-name { 3109 type string; 3110 description 3111 "An alias name that points to a resource."; 3112 } 3113 leaf lifetime { 3114 type int32; 3115 units "seconds"; 3116 default "3600"; 3117 description 3118 "Indicates the lifetime of the mitigation request. 3120 A lifetime of '0' in a mitigation request is an 3121 invalid value. 3123 A lifetime of negative one (-1) indicates indefinite 3124 lifetime for the mitigation request."; 3125 } 3126 leaf trigger-mitigation { 3127 type boolean; 3128 default "true"; 3129 description 3130 "If set to 'false', DDoS mitigation will not be 3131 triggered unless the DOTS signal channel 3132 session is lost."; 3133 } 3134 choice direction { 3135 description 3136 "Indicates the communication direction in which the 3137 data nodes can be included."; 3138 case server-to-client-only { 3139 description 3140 "These data nodes appear only in a mitigation message 3141 sent from the server to the client."; 3142 leaf mid { 3143 type uint32; 3144 description 3145 "Mitigation request identifier. 3147 This identifier must be unique for each mitigation 3148 request bound to the DOTS client."; 3149 } 3150 leaf mitigation-start { 3151 type uint64; 3152 description 3153 "Mitigation start time is represented in seconds 3154 relative to 1970-01-01T00:00:00Z in UTC time."; 3155 } 3156 leaf status { 3157 type iana-signal:status; 3158 description 3159 "Indicates the status of a mitigation request. 3160 It must be included in responses only."; 3161 } 3162 container conflict-information { 3163 description 3164 "Indicates that a conflict is detected. 3165 Must only be used for responses."; 3166 leaf conflict-status { 3167 type iana-signal:conflict-status; 3168 description 3169 "Indicates the conflict status."; 3170 } 3171 leaf conflict-cause { 3172 type iana-signal:conflict-cause; 3173 description 3174 "Indicates the cause of the conflict."; 3175 } 3176 leaf retry-timer { 3177 type uint32; 3178 units "seconds"; 3179 description 3180 "The DOTS client must not resend the 3181 same request that has a conflict before the expiry of 3182 this timer."; 3183 } 3184 container conflict-scope { 3185 description 3186 "Provides more information about the conflict scope."; 3187 uses ietf-data:target { 3188 when "/dots-signal/scope/conflict-information/" 3189 + "conflict-cause = 'overlapping-targets'"; 3190 } 3191 leaf-list alias-name { 3192 when "../../conflict-cause = 'overlapping-targets'"; 3193 type string; 3194 description 3195 "Conflicting alias-name."; 3196 } 3197 list acl-list { 3198 when "../../conflict-cause =" 3199 + " 'conflict-with-acceptlist'"; 3200 key "acl-name"; 3201 description 3202 "List of conflicting ACLs as defined in the DOTS data 3203 channel. These ACLs are uniquely defined by 3204 cuid and acl-name."; 3205 leaf acl-name { 3206 type leafref { 3207 path "/ietf-data:dots-data/ietf-data:dots-client/" 3208 + "ietf-data:acls/ietf-data:acl/ietf-data:name"; 3209 } 3210 description 3211 "Reference to the conflicting ACL name bound to 3212 a DOTS client."; 3213 } 3214 leaf acl-type { 3215 type leafref { 3216 path "/ietf-data:dots-data/ietf-data:dots-client/" 3217 + "ietf-data:acls/ietf-data:acl/ietf-data:type"; 3218 } 3219 description 3220 "Reference to the conflicting ACL type bound to 3221 a DOTS client."; 3222 } 3223 } 3224 leaf mid { 3225 when "../../conflict-cause = 'overlapping-targets'"; 3226 type uint32; 3227 description 3228 "Reference to the conflicting 'mid' bound to 3229 the same DOTS client."; 3230 } 3231 } 3232 } 3233 leaf bytes-dropped { 3234 type yang:zero-based-counter64; 3235 units "bytes"; 3236 description 3237 "The total dropped byte count for the mitigation 3238 request since the attack mitigation was triggered. 3239 The count wraps around when it reaches the maximum value 3240 of counter64 for dropped bytes."; 3241 } 3242 leaf bps-dropped { 3243 type yang:gauge64; 3244 description 3245 "The average number of dropped bits per second for 3246 the mitigation request since the attack 3247 mitigation was triggered. This should be over 3248 five-minute intervals (that is, measuring bytes 3249 into five-minute buckets and then averaging these 3250 buckets over the time since the mitigation was 3251 triggered)."; 3252 } 3253 leaf pkts-dropped { 3254 type yang:zero-based-counter64; 3255 description 3256 "The total number of dropped packet count for the 3257 mitigation request since the attack mitigation was 3258 triggered. The count wraps around when it reaches 3259 the maximum value of counter64 for dropped packets."; 3260 } 3261 leaf pps-dropped { 3262 type yang:gauge64; 3263 description 3264 "The average number of dropped packets per second 3265 for the mitigation request since the attack 3266 mitigation was triggered. This should be over 3267 five-minute intervals (that is, measuring packets 3268 into five-minute buckets and then averaging these 3269 buckets over the time since the mitigation was 3270 triggered)."; 3271 } 3272 leaf attack-status { 3273 type iana-signal:attack-status; 3274 description 3275 "Indicates the status of an attack as seen by the 3276 DOTS client."; 3277 } 3278 } 3279 } 3280 } 3281 } 3283 grouping config-parameters { 3284 description 3285 "Subset of DOTS signal channel session configuration."; 3286 container heartbeat-interval { 3287 description 3288 "DOTS agents regularly send heartbeats to each other 3289 after mutual authentication is successfully 3290 completed in order to keep the DOTS signal channel 3291 open."; 3292 choice direction { 3293 description 3294 "Indicates the communication direction in which the 3295 data nodes can be included."; 3296 case server-to-client-only { 3297 description 3298 "These data nodes appear only in a mitigation message 3299 sent from the server to the client."; 3300 leaf max-value { 3301 type uint16; 3302 units "seconds"; 3303 description 3304 "Maximum acceptable heartbeat-interval value."; 3305 } 3306 leaf min-value { 3307 type uint16; 3308 units "seconds"; 3309 description 3310 "Minimum acceptable heartbeat-interval value."; 3311 } 3312 } 3313 } 3314 leaf current-value { 3315 type uint16; 3316 units "seconds"; 3317 default "30"; 3318 description 3319 "Current heartbeat-interval value. 3321 '0' means that heartbeat mechanism is deactivated."; 3322 } 3323 } 3324 container missing-hb-allowed { 3325 description 3326 "Maximum number of missing heartbeats allowed."; 3327 choice direction { 3328 description 3329 "Indicates the communication direction in which the 3330 data nodes can be included."; 3331 case server-to-client-only { 3332 description 3333 "These data nodes appear only in a mitigation message 3334 sent from the server to the client."; 3335 leaf max-value { 3336 type uint16; 3337 description 3338 "Maximum acceptable missing-hb-allowed value."; 3339 } 3340 leaf min-value { 3341 type uint16; 3342 description 3343 "Minimum acceptable missing-hb-allowed value."; 3344 } 3345 } 3346 } 3347 leaf current-value { 3348 type uint16; 3349 default "15"; 3350 description 3351 "Current missing-hb-allowed value."; 3352 } 3353 } 3354 container probing-rate { 3355 description 3356 "The limit for sending Non-confirmable messages with 3357 no response."; 3358 choice direction { 3359 description 3360 "Indicates the communication direction in which the 3361 data nodes can be included."; 3362 case server-to-client-only { 3363 description 3364 "These data nodes appear only in a mitigation message 3365 sent from the server to the client."; 3366 leaf max-value { 3367 type uint16; 3368 units "byte/second"; 3369 description 3370 "Maximum acceptable probing-rate value."; 3371 } 3372 leaf min-value { 3373 type uint16; 3374 units "byte/second"; 3375 description 3376 "Minimum acceptable probing-rate value."; 3377 } 3378 } 3379 } 3380 leaf current-value { 3381 type uint16; 3382 units "byte/second"; 3383 default "5"; 3384 description 3385 "Current probing-rate value."; 3386 } 3387 } 3388 container max-retransmit { 3389 description 3390 "Maximum number of retransmissions of a Confirmable 3391 message."; 3392 choice direction { 3393 description 3394 "Indicates the communication direction in which the 3395 data nodes can be included."; 3396 case server-to-client-only { 3397 description 3398 "These data nodes appear only in a mitigation message 3399 sent from the server to the client."; 3400 leaf max-value { 3401 type uint16; 3402 description 3403 "Maximum acceptable max-retransmit value."; 3404 } 3405 leaf min-value { 3406 type uint16; 3407 description 3408 "Minimum acceptable max-retransmit value."; 3409 } 3410 } 3411 } 3412 leaf current-value { 3413 type uint16; 3414 default "3"; 3415 description 3416 "Current max-retransmit value."; 3417 } 3418 } 3419 container ack-timeout { 3420 description 3421 "Initial retransmission timeout value."; 3422 choice direction { 3423 description 3424 "Indicates the communication direction in which the 3425 data nodes can be included."; 3426 case server-to-client-only { 3427 description 3428 "These data nodes appear only in a mitigation message 3429 sent from the server to the client."; 3430 leaf max-value-decimal { 3431 type decimal64 { 3432 fraction-digits 2; 3433 } 3434 units "seconds"; 3435 description 3436 "Maximum ack-timeout value."; 3437 } 3438 leaf min-value-decimal { 3439 type decimal64 { 3440 fraction-digits 2; 3441 } 3442 units "seconds"; 3443 description 3444 "Minimum ack-timeout value."; 3445 } 3446 } 3447 } 3448 leaf current-value-decimal { 3449 type decimal64 { 3450 fraction-digits 2; 3451 } 3452 units "seconds"; 3453 default "2"; 3454 description 3455 "Current ack-timeout value."; 3456 } 3457 } 3458 container ack-random-factor { 3459 description 3460 "Random factor used to influence the timing of 3461 retransmissions."; 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 description 3475 "Maximum acceptable ack-random-factor value."; 3477 } 3478 leaf min-value-decimal { 3479 type decimal64 { 3480 fraction-digits 2; 3481 } 3482 description 3483 "Minimum acceptable ack-random-factor value."; 3484 } 3485 } 3486 } 3487 leaf current-value-decimal { 3488 type decimal64 { 3489 fraction-digits 2; 3490 } 3491 default "1.5"; 3492 description 3493 "Current ack-random-factor value."; 3494 } 3495 } 3496 } 3498 grouping signal-config { 3499 description 3500 "DOTS signal channel session configuration."; 3501 container mitigating-config { 3502 description 3503 "Configuration parameters to use when a mitigation 3504 is active."; 3505 uses config-parameters; 3506 } 3507 container idle-config { 3508 description 3509 "Configuration parameters to use when no mitigation 3510 is active."; 3511 uses config-parameters; 3512 } 3513 } 3515 grouping redirected-signal { 3516 description 3517 "Grouping for the redirected signaling."; 3518 choice direction { 3519 description 3520 "Indicates the communication direction in which the 3521 data nodes can be included."; 3522 case server-to-client-only { 3523 description 3524 "These data nodes appear only in a mitigation message 3525 sent from the server to the client."; 3526 leaf alt-server { 3527 type string; 3528 mandatory true; 3529 description 3530 "FQDN of an alternate server."; 3531 } 3532 leaf-list alt-server-record { 3533 type inet:ip-address; 3534 description 3535 "List of records for the alternate server."; 3536 } 3537 } 3538 } 3539 } 3541 /* 3542 * DOTS Signal Channel Structure 3543 */ 3545 sx:structure dots-signal { 3546 description 3547 "Main structure for DOTS signal message. 3549 A DOTS signal message can be a mitigation, a configuration, 3550 or a redirected signal message."; 3551 choice message-type { 3552 description 3553 "Can be a mitigation, a configuration, or a redirect 3554 message."; 3555 case mitigation-scope { 3556 description 3557 "Mitigation scope of a mitigation message."; 3558 uses mitigation-scope; 3559 } 3560 case signal-config { 3561 description 3562 "Configuration message."; 3563 uses signal-config; 3564 } 3565 case redirected-signal { 3566 description 3567 "Redirected signaling."; 3568 uses redirected-signal; 3569 } 3570 case heartbeat { 3571 description 3572 "DOTS heartbeats."; 3574 leaf peer-hb-status { 3575 type boolean; 3576 mandatory true; 3577 description 3578 "Indicates whether a DOTS agent receives heartbeats 3579 from its peer. The value is set to 'true' if the 3580 DOTS agent is receiving heartbeat messages 3581 from its peer."; 3582 } 3583 } 3584 } 3585 } 3586 } 3587 3589 6. YANG/JSON Mapping Parameters to CBOR 3591 All parameters in the payload of the DOTS signal channel MUST be 3592 mapped to CBOR types as shown in Table 5 and are assigned an integer 3593 key to save space. 3595 Note: Implementers must check that the mapping output provided by 3596 their YANG-to-CBOR encoding schemes is aligned with the content of 3597 Table 5. For example, some CBOR and JSON types for enumerations 3598 and the 64-bit quantities can differ depending on the encoder 3599 used. 3601 The CBOR key values are divided into two types: comprehension- 3602 required and comprehension-optional. DOTS agents can safely ignore 3603 comprehension-optional values they don't understand, but they cannot 3604 successfully process a request if it contains comprehension-required 3605 values that are not understood. The 4.00 response SHOULD include a 3606 diagnostic payload describing the unknown comprehension-required CBOR 3607 key values. The initial set of CBOR key values defined in this 3608 specification are of type comprehension-required. 3610 +---------------------+--------------+------+-------------+--------+ 3611 | Parameter Name | YANG Type | CBOR | CBOR Major | JSON | 3612 | | | Key | Type & | Type | 3613 | | | | Information | | 3614 +=====================+==============+======+=============+========+ 3615 | ietf-dots-signal- | container | 1 | 5 map | Object | 3616 | channel:mitigation- | | | | | 3617 | scope | | | | | 3618 +---------------------+--------------+------+-------------+--------+ 3619 | scope | list | 2 | 4 array | Array | 3620 +---------------------+--------------+------+-------------+--------+ 3621 | cdid | string | 3 | 3 text | String | 3622 | | | | string | | 3623 +---------------------+--------------+------+-------------+--------+ 3624 | cuid | string | 4 | 3 text | String | 3625 | | | | string | | 3626 +---------------------+--------------+------+-------------+--------+ 3627 | mid | uint32 | 5 | 0 unsigned | Number | 3628 +---------------------+--------------+------+-------------+--------+ 3629 | target-prefix | leaf-list | 6 | 4 array | Array | 3630 | +--------------+------+-------------+--------+ 3631 | | inet:ip- | | 3 text | String | 3632 | | prefix | | string | | 3633 +---------------------+--------------+------+-------------+--------+ 3634 | target-port-range | list | 7 | 4 array | Array | 3635 +---------------------+--------------+------+-------------+--------+ 3636 | lower-port | inet:port- | 8 | 0 unsigned | Number | 3637 | | number | | | | 3638 +---------------------+--------------+------+-------------+--------+ 3639 | upper-port | inet:port- | 9 | 0 unsigned | Number | 3640 | | number | | | | 3641 +---------------------+--------------+------+-------------+--------+ 3642 | target-protocol | leaf-list | 10 | 4 array | Array | 3643 | +--------------+------+-------------+--------+ 3644 | | uint8 | | 0 unsigned | Number | 3645 +---------------------+--------------+------+-------------+--------+ 3646 | target-fqdn | leaf-list | 11 | 4 array | Array | 3647 | +--------------+------+-------------+--------+ 3648 | | inet:domain- | | 3 text | String | 3649 | | name | | string | | 3650 +---------------------+--------------+------+-------------+--------+ 3651 | target-uri | leaf-list | 12 | 4 array | Array | 3652 | +--------------+------+-------------+--------+ 3653 | | inet:uri | | 3 text | String | 3654 | | | | string | | 3655 +---------------------+--------------+------+-------------+--------+ 3656 | alias-name | leaf-list | 13 | 4 array | Array | 3657 | +--------------+------+-------------+--------+ 3658 | | string | | 3 text | String | 3659 | | | | string | | 3660 +---------------------+--------------+------+-------------+--------+ 3661 | lifetime | int32 | 14 | 0 unsigned | Number | 3662 | | | +-------------+--------+ 3663 | | | | 1 negative | Number | 3664 +---------------------+--------------+------+-------------+--------+ 3665 | mitigation-start | uint64 | 15 | 0 unsigned | String | 3666 +---------------------+--------------+------+-------------+--------+ 3667 | status | enumeration | 16 | 0 unsigned | String | 3668 +---------------------+--------------+------+-------------+--------+ 3669 | conflict- | container | 17 | 5 map | Object | 3670 | information | | | | | 3671 +---------------------+--------------+------+-------------+--------+ 3672 | conflict-status | enumeration | 18 | 0 unsigned | String | 3673 +---------------------+--------------+------+-------------+--------+ 3674 | conflict-cause | enumeration | 19 | 0 unsigned | String | 3675 +---------------------+--------------+------+-------------+--------+ 3676 | retry-timer | uint32 | 20 | 0 unsigned | String | 3677 +---------------------+--------------+------+-------------+--------+ 3678 | conflict-scope | container | 21 | 5 map | Object | 3679 +---------------------+--------------+------+-------------+--------+ 3680 | acl-list | list | 22 | 4 array | Array | 3681 +---------------------+--------------+------+-------------+--------+ 3682 | acl-name | leafref | 23 | 3 text | String | 3683 | | | | string | | 3684 +---------------------+--------------+------+-------------+--------+ 3685 | acl-type | leafref | 24 | 3 text | String | 3686 | | | | string | | 3687 +---------------------+--------------+------+-------------+--------+ 3688 | bytes-dropped | yang:zero- | 25 | 0 unsigned | String | 3689 | | based- | | | | 3690 | | counter64 | | | | 3691 +---------------------+--------------+------+-------------+--------+ 3692 | bps-dropped | yang:gauge64 | 26 | 0 unsigned | String | 3693 +---------------------+--------------+------+-------------+--------+ 3694 | pkts-dropped | yang:zero- | 27 | 0 unsigned | String | 3695 | | based- | | | | 3696 | | counter64 | | | | 3697 +---------------------+--------------+------+-------------+--------+ 3698 | pps-dropped | yang:gauge64 | 28 | 0 unsigned | String | 3699 +---------------------+--------------+------+-------------+--------+ 3700 | attack-status | enumeration | 29 | 0 unsigned | String | 3701 +---------------------+--------------+------+-------------+--------+ 3702 | ietf-dots-signal- | container | 30 | 5 map | Object | 3703 | channel:signal- | | | | | 3704 | config | | | | | 3705 +---------------------+--------------+------+-------------+--------+ 3706 | sid | uint32 | 31 | 0 unsigned | Number | 3707 +---------------------+--------------+------+-------------+--------+ 3708 | mitigating-config | container | 32 | 5 map | Object | 3709 +---------------------+--------------+------+-------------+--------+ 3710 | heartbeat-interval | container | 33 | 5 map | Object | 3711 +---------------------+--------------+------+-------------+--------+ 3712 | max-value | uint16 | 34 | 0 unsigned | Number | 3713 +---------------------+--------------+------+-------------+--------+ 3714 | min-value | uint16 | 35 | 0 unsigned | Number | 3715 +---------------------+--------------+------+-------------+--------+ 3716 | current-value | uint16 | 36 | 0 unsigned | Number | 3717 +---------------------+--------------+------+-------------+--------+ 3718 | missing-hb-allowed | container | 37 | 5 map | Object | 3719 +---------------------+--------------+------+-------------+--------+ 3720 | max-retransmit | container | 38 | 5 map | Object | 3721 +---------------------+--------------+------+-------------+--------+ 3722 | ack-timeout | container | 39 | 5 map | Object | 3723 +---------------------+--------------+------+-------------+--------+ 3724 | ack-random-factor | container | 40 | 5 map | Object | 3725 +---------------------+--------------+------+-------------+--------+ 3726 | max-value-decimal | decimal64 | 41 | 6 tag 4 | String | 3727 | | | | [-2, | | 3728 | | | | integer] | | 3729 +---------------------+--------------+------+-------------+--------+ 3730 | min-value-decimal | decimal64 | 42 | 6 tag 4 | String | 3731 | | | | [-2, | | 3732 | | | | integer] | | 3733 +---------------------+--------------+------+-------------+--------+ 3734 | current-value- | decimal64 | 43 | 6 tag 4 | String | 3735 | decimal | | | [-2, | | 3736 | | | | integer] | | 3737 +---------------------+--------------+------+-------------+--------+ 3738 | idle-config | container | 44 | 5 map | Object | 3739 +---------------------+--------------+------+-------------+--------+ 3740 | trigger-mitigation | boolean | 45 | 7 bits 20 | False | 3741 | | | +-------------+--------+ 3742 | | | | 7 bits 21 | True | 3743 +---------------------+--------------+------+-------------+--------+ 3744 | ietf-dots-signal- | container | 46 | 5 map | Object | 3745 | channel:redirected- | | | | | 3746 | signal | | | | | 3747 +---------------------+--------------+------+-------------+--------+ 3748 | alt-server | string | 47 | 3 text | String | 3749 | | | | string | | 3750 +---------------------+--------------+------+-------------+--------+ 3751 | alt-server-record | leaf-list | 48 | 4 array | Array | 3752 | +--------------+------+-------------+--------+ 3753 | | inet:ip- | | 3 text | String | 3754 | | address | | string | | 3755 +---------------------+--------------+------+-------------+--------+ 3756 | ietf-dots-signal- | container | 49 | 5 map | Object | 3757 | channel:heartbeat | | | | | 3758 +---------------------+--------------+------+-------------+--------+ 3759 | probing-rate | container | 50 | 5 map | Object | 3760 +---------------------+--------------+------+-------------+--------+ 3761 | peer-hb-status | boolean | 51 | 7 bits 20 | False | 3762 | | | +-------------+--------+ 3763 | | | | 7 bits 21 | True | 3764 +---------------------+--------------+------+-------------+--------+ 3765 Table 5: CBOR Key Values Used in DOTS Signal Channel Messages & 3766 Their Mappings to JSON and YANG 3768 7. (D)TLS Protocol Profile and Performance Considerations 3770 7.1. (D)TLS Protocol Profile 3772 This section defines the (D)TLS protocol profile of DOTS signal 3773 channel over (D)TLS and DOTS data channel over TLS. 3775 There are known attacks on (D)TLS, such as man-in-the-middle and 3776 protocol downgrade attacks. These are general attacks on (D)TLS and, 3777 as such, they are not specific to DOTS over (D)TLS; refer to the 3778 (D)TLS RFCs for discussion of these security issues. DOTS agents 3779 MUST adhere to the (D)TLS implementation recommendations and security 3780 considerations of [RFC7525] except with respect to (D)TLS version. 3781 Because DOTS signal channel encryption relying upon (D)TLS is 3782 virtually a greenfield deployment, DOTS agents MUST implement only 3783 (D)TLS 1.2 or later. 3785 When a DOTS client is configured with a domain name of the DOTS 3786 server, and it connects to its configured DOTS server, the server may 3787 present it with a PKIX certificate. In order to ensure proper 3788 authentication, a DOTS client MUST verify the entire certification 3789 path per [RFC5280]. Additionally, the DOTS client MUST use [RFC6125] 3790 validation techniques to compare the domain name with the certificate 3791 provided. Certification authorities that issue DOTS server 3792 certificates SHOULD support the DNS-ID and SRV-ID identifier types. 3793 DOTS servers SHOULD prefer the use of DNS-ID and SRV-ID over CN-ID 3794 identifier types in certificate requests (as described in Section 2.3 3795 of [RFC6125]), and the wildcard character '*' SHOULD NOT be included 3796 in the presented identifier. DOTS doesn't use URI-IDs for server 3797 identity verification. 3799 A key challenge to deploying DOTS is the provisioning of DOTS 3800 clients, including the distribution of keying material to DOTS 3801 clients to enable the required mutual authentication of DOTS agents. 3802 Enrollment over Secure Transport (EST) [RFC7030] defines a method of 3803 certificate enrollment by which domains operating DOTS servers may 3804 provide DOTS clients with all the necessary cryptographic keying 3805 material, including a private key and a certificate, to authenticate 3806 themselves. One deployment option is to have DOTS clients behave as 3807 EST clients for certificate enrollment from an EST server provisioned 3808 by the mitigation provider. This document does not specify which EST 3809 or other mechanism the DOTS client uses to achieve initial 3810 enrollment. 3812 The Server Name Indication (SNI) extension [RFC6066] defines a 3813 mechanism for a client to tell a (D)TLS server the name of the server 3814 it wants to contact. This is a useful extension for hosting 3815 environments where multiple virtual servers are reachable over a 3816 single IP address. The DOTS client may or may not know if it is 3817 interacting with a DOTS server in a virtual server hosting 3818 environment, so the DOTS client SHOULD include the DOTS server FQDN 3819 in the SNI extension. 3821 Implementations compliant with this profile MUST implement all of the 3822 following items: 3824 o DTLS record replay detection (Section 3.3 of [RFC6347]) or an 3825 equivalent mechanism to protect against replay attacks. 3827 o DTLS session resumption without server-side state to resume 3828 session and convey the DOTS signal. 3830 o At least one of raw public keys [RFC7250] or PSK handshake 3831 [RFC4279] with (EC)DHE key exchange. This reduces the size of the 3832 ServerHello. Also, this can be used by DOTS agents that cannot 3833 obtain certificates. 3835 Implementations compliant with this profile SHOULD implement all of 3836 the following items to reduce the delay required to deliver a DOTS 3837 signal channel message: 3839 o TLS False Start [RFC7918], which reduces round-trips by allowing 3840 the TLS client's second flight of messages (ChangeCipherSpec) to 3841 also contain the DOTS signal. TLS False Start is formally defined 3842 for use with TLS, but the same technique is applicable to DTLS as 3843 well. 3845 o Cached Information Extension [RFC7924] which avoids transmitting 3846 the server's certificate and certificate chain if the client has 3847 cached that information from a previous TLS handshake. 3849 Compared to UDP, DOTS signal channel over TCP requires an additional 3850 round-trip time (RTT) of latency to establish a TCP connection. DOTS 3851 implementations are encouraged to implement TCP Fast Open [RFC7413] 3852 to eliminate that RTT. 3854 7.2. (D)TLS 1.3 Considerations 3856 TLS 1.3 provides critical latency improvements for connection 3857 establishment over TLS 1.2. The DTLS 1.3 protocol 3858 [I-D.ietf-tls-dtls13] is based upon the TLS 1.3 protocol and provides 3859 equivalent security guarantees. (D)TLS 1.3 provides two basic 3860 handshake modes the DOTS signal channel can take advantage of: 3862 o A full handshake mode in which a DOTS client can send a DOTS 3863 mitigation request message after one round trip and the DOTS 3864 server immediately responds with a DOTS mitigation response. This 3865 assumes no packet loss is experienced. 3867 o 0-RTT mode in which the DOTS client can authenticate itself and 3868 send DOTS mitigation request messages in the first message, thus 3869 reducing handshake latency. 0-RTT only works if the DOTS client 3870 has previously communicated with that DOTS server, which is very 3871 likely with the DOTS signal channel. 3873 The DOTS client has to establish a (D)TLS session with the DOTS 3874 server during 'idle' time and share a PSK. 3876 During a DDoS attack, the DOTS client can use the (D)TLS session to 3877 convey the DOTS mitigation request message and, if there is no 3878 response from the server after multiple retries, the DOTS client can 3879 resume the (D)TLS session in 0-RTT mode using PSK. 3881 DOTS servers that support (D)TLS 1.3 MAY allow DOTS clients to send 3882 early data (0-RTT). DOTS clients MUST NOT send "CoAP Ping" as early 3883 data; such messages MUST be rejected by DOTS servers. Section 8 of 3884 [RFC8446] discusses some mechanisms to implement in order to limit 3885 the impact of replay attacks on 0-RTT data. If the DOTS server 3886 accepts 0-RTT, it MUST implement one of these mechanisms to prevent 3887 replay at the TLS layer. A DOTS server can reject 0-RTT by sending a 3888 TLS HelloRetryRequest. 3890 The DOTS signal channel messages sent as early data by the DOTS 3891 client are idempotent requests. As a reminder, the Message ID 3892 (Section 3 of [RFC7252]) is changed each time a new CoAP request is 3893 sent, and the Token (Section 5.3.1 of [RFC7252]) is randomized in 3894 each CoAP request. The DOTS server(s) MUST use the Message ID and 3895 the Token in the DOTS signal channel message to detect replay of 3896 early data at the application layer and accept 0-RTT data at most 3897 once from the same DOTS client. This anti-replay defense requires 3898 sharing the Message ID and the Token in the 0-RTT data between DOTS 3899 servers in the DOTS server domain. DOTS servers do not rely on 3900 transport coordinates to identify DOTS peers. As specified in 3901 Section 4.4.1, DOTS servers couple the DOTS signal channel sessions 3902 using the DOTS client identity and optionally the 'cdid' parameter 3903 value. Furthermore, the 'mid' value is monotonically increased by 3904 the DOTS client for each mitigation request, thus attackers that 3905 replay mitigation requests with lower numeric 'mid' values and 3906 overlapping scopes with mitigation requests having higher numeric 3907 'mid' values will be rejected systematically by the DOTS server. 3908 Likewise, the 'sid' value is monotonically increased by the DOTS 3909 client for each configuration request (Section 4.5.2); attackers 3910 replaying configuration requests with lower numeric 'sid' values will 3911 be rejected by the DOTS server if it maintains a higher numeric 'sid' 3912 value for this DOTS client. 3914 Owing to the aforementioned protections, all DOTS signal channel 3915 requests are safe to transmit in TLS 1.3 as early data. Refer to 3916 [I-D.boucadair-dots-earlydata] for more details. 3918 A simplified TLS 1.3 handshake with 0-RTT DOTS mitigation request 3919 message exchange is shown in Figure 29. 3921 DOTS Client DOTS Server 3923 ClientHello 3924 (0-RTT DOTS signal message) 3925 --------> 3926 ServerHello 3927 {EncryptedExtensions} 3928 {Finished} 3929 <-------- [DOTS signal message] 3930 (end_of_early_data) 3931 {Finished} --------> 3932 [DOTS signal message] <-------> [DOTS signal message] 3934 Note that: 3935 () Indicates messages protected 0-RTT keys 3936 {} Indicates messages protected using handshake keys 3937 [] Indicates messages protected using 1-RTT keys 3939 Figure 29: A Simplified TLS 1.3 Handshake with 0-RTT 3941 7.3. DTLS MTU and Fragmentation 3943 To avoid DOTS signal message fragmentation and the subsequent 3944 decreased probability of message delivery, DOTS agents MUST ensure 3945 that the DTLS record fits within a single datagram. As a reminder, 3946 DTLS handles fragmentation and reassembly only for handshake messages 3947 and not for the application data (Section 4.1.1 of [RFC6347]). If 3948 the path MTU (PMTU) cannot be discovered, DOTS agents MUST assume a 3949 PMTU of 1280 bytes, as IPv6 requires that every link in the Internet 3950 have an MTU of 1280 octets or greater as specified in [RFC8200]. If 3951 IPv4 support on legacy or otherwise unusual networks is a 3952 consideration and the PMTU is unknown, DOTS implementations MAY 3953 assume a PMTU of 576 bytes for IPv4 datagrams, as every IPv4 host 3954 must be capable of receiving a packet whose length is equal to 576 3955 bytes as discussed in [RFC0791] and [RFC1122]. 3957 The DOTS client must consider the amount of record expansion expected 3958 by the DTLS processing when calculating the size of the CoAP message 3959 that fits within the PMTU. PMTU MUST be greater than or equal to 3960 [CoAP message size + DTLS 1.2 overhead of 13 octets + authentication 3961 overhead of the negotiated DTLS cipher suite + block padding] 3962 (Section 4.1.1.1 of [RFC6347]). If the total request size exceeds 3963 the PMTU, then the DOTS client MUST split the DOTS signal into 3964 separate messages; for example, the list of addresses in the 'target- 3965 prefix' parameter could be split into multiple lists and each list 3966 conveyed in a new PUT request. 3968 | Implementation Note: DOTS choice of message size parameters 3969 | works well with IPv6 and with most of today's IPv4 paths. 3970 | However, with IPv4, it is harder to safely make sure that there 3971 | is no IP fragmentation. If the IPv4 PMTU is unknown, 3972 | implementations may want to limit themselves to more 3973 | conservative IPv4 datagram sizes such as 576 bytes, per 3974 | [RFC0791]. 3976 8. Mutual Authentication of DOTS Agents & Authorization of DOTS Clients 3978 (D)TLS based upon client certificates can be used for mutual 3979 authentication between DOTS agents. If, for example, a DOTS gateway 3980 is involved, DOTS clients and DOTS gateways must perform mutual 3981 authentication; only authorized DOTS clients are allowed to send DOTS 3982 signals to a DOTS gateway. The DOTS gateway and the DOTS server must 3983 perform mutual authentication; a DOTS server only allows DOTS signal 3984 channel messages from an authorized DOTS gateway, thereby creating a 3985 two-link chain of transitive authentication between the DOTS client 3986 and the DOTS server. 3988 The DOTS server should support certificate-based client 3989 authentication. The DOTS client should respond to the DOTS server's 3990 TLS CertificateRequest message with the PKIX certificate held by the 3991 DOTS client. DOTS client certificate validation must be performed 3992 per [RFC5280], and the DOTS client certificate must conform to the 3993 [RFC5280] certificate profile. If a DOTS client does not support TLS 3994 client certificate authentication, it must support client 3995 authentication based on pre-shared key or raw public key. 3997 +---------------------------------------------+ 3998 | example.com domain +---------+ | 3999 | | AAA | | 4000 | +---------------+ | Server | | 4001 | | Application | +------+--+ | 4002 | | server +<---------------+ ^ | 4003 | | (DOTS client) | | | | 4004 | +---------------+ | | | 4005 | V V | example.net domain 4006 | +-----+----+--+ | +---------------+ 4007 | +--------------+ | | | | | 4008 | | Guest +<----x---->+ DOTS +<----->+ DOTS | 4009 | | (DOTS client)| | gateway | | | server | 4010 | +--------------+ | | | | | 4011 | +----+--------+ | +---------------+ 4012 | ^ | 4013 | | | 4014 | +----------------+ | | 4015 | | DDoS detector | | | 4016 | | (DOTS client) +<-------------+ | 4017 | +----------------+ | 4018 +---------------------------------------------+ 4020 Figure 30: Example of Authentication and Authorization of DOTS Agents 4022 In the example depicted in Figure 30, the DOTS gateway and DOTS 4023 clients within the 'example.com' domain mutually authenticate. After 4024 the DOTS gateway validates the identity of a DOTS client, it 4025 communicates with the AAA server in the 'example.com' domain to 4026 determine if the DOTS client is authorized to request DDoS 4027 mitigation. If the DOTS client is not authorized, a 4.01 4028 (Unauthorized) is returned in the response to the DOTS client. In 4029 this example, the DOTS gateway only allows the application server and 4030 DDoS attack detector to request DDoS mitigation, but does not permit 4031 the user of type 'guest' to request DDoS mitigation. 4033 Also, DOTS gateways and servers located in different domains must 4034 perform mutual authentication (e.g., using certificates). A DOTS 4035 server will only allow a DOTS gateway with a certificate for a 4036 particular domain to request mitigation for that domain. In 4037 reference to Figure 30, the DOTS server only allows the DOTS gateway 4038 to request mitigation for the 'example.com' domain and not for other 4039 domains. 4041 9. Error Handling 4043 This section is a summary of the Error Code responses that can be 4044 returned by a DOTS server. These error responses must contain a CoAP 4045 4.xx or 5.xx Response Code. 4047 In general, there may be an additional plain text diagnostic payload 4048 (Section 5.5.2 of [RFC7252]) to help troubleshooting in the body of 4049 the response unless detailed otherwise. 4051 Errors returned by a DOTS server can be broken into two categories, 4052 those associated with CoAP itself and those generated during the 4053 validation of the provided data by the DOTS server. 4055 The following list of common CoAP errors that are implemented by DOTS 4056 servers. This list is not exhaustive, other errors defined by CoAP 4057 and associated RFCs may be applicable. 4059 o 4.00 (Bad Request) is returned by the DOTS server when the DOTS 4060 client has sent a request that violates the DOTS protocol 4061 (Section 4). 4063 o 4.01 (Unauthorized) is returned by the DOTS server when the DOTS 4064 client is not authorized to access the DOTS server (Section 4). 4066 o 4.02 (Bad Option) is returned by the DOTS server when one or more 4067 CoAP options are unknown or malformed by the CoAP layer [RFC7252]. 4069 o 4.04 (Not Found) is returned by the DOTS server when the DOTS 4070 client is requesting a 'mid' or 'sid' that is not valid 4071 (Section 4). 4073 o 4.05 (Method Not Allowed) is returned by the DOTS server when the 4074 DOTS client is requesting a resource by a method (e.g., GET) that 4075 is not supported by the DOTS server [RFC7252]. 4077 o 4.08 (Request Entity Incomplete) is returned by the DOTS server if 4078 one or multiple blocks of a block transfer request is missing 4079 [RFC7959]. 4081 o 4.09 (Conflict) is returned by the DOTS server if the DOTS server 4082 detects that a request conflicts with a previous request. The 4083 response body is formatted using "application/dots+cbor", and 4084 contains the "conflict-clause" (Section 4.4). 4086 o 4.13 (Request Entity Too Large) may be returned by the DOTS server 4087 during a block transfer request [RFC7959]. 4089 o 4.15 (Unsupported Content-Format) is returned by the DOTS server 4090 when the Content-Format used in the request is not formatted as 4091 "application/dots+cbor" (Section 4). 4093 o 4.22 (Unprocessable Entity) is returned by the DOTS server when 4094 one or more session configuration parameters are not valid 4095 (Section 4.5). 4097 o 5.03 (Service Unavailable) is returned by the DOTS server if the 4098 DOTS server is unable to handle the request (Section 4). An 4099 example is the DOTS server needs to redirect the DOTS client to 4100 use an alternate DOTS server (Section 4.6). The response body is 4101 formatted using "application/dots+cbor", and contains how to 4102 handle the 5.03 Response Code. 4104 o 5.08 (Hop Limit Reached) is returned by the DOTS server if there 4105 is a data path loop through upstream DOTS gateways. The response 4106 body is formatted using plain text and contains a list of servers 4107 that are in the data path loop [RFC8768]. 4109 10. IANA Considerations 4111 10.1. DOTS Signal Channel UDP and TCP Port Number 4113 IANA has assigned the port number 4646 (the ASCII decimal value for 4114 ".." (DOTS)) to the DOTS signal channel protocol for both UDP and TCP 4115 from the "Service Name and Transport Protocol Port Number Registry" 4116 available at . 4119 IANA is requested to update these entries with the RFC number to be 4120 assigned to this docuement: 4122 Service Name: dots-signal 4123 Port Number: 4646 4124 Transport Protocol: TCP 4125 Description: Distributed Denial-of-Service Open Threat Signaling 4126 (DOTS) Signal Channel 4127 Assignee: IESG 4128 Contact: IETF Chair 4129 Registration Date: 2020-01-16 4130 Reference: [RFCXXXX] 4132 Service Name: dots-signal 4133 Port Number: 4646 4134 Transport Protocol: UDP 4135 Description: Distributed Denial-of-Service Open Threat Signaling 4136 (DOTS) Signal Channel 4137 Assignee: IESG 4138 Contact: IETF Chair 4139 Registration Date: 2020-01-16 4140 Reference: [RFCXXXX] 4142 10.2. Well-Known 'dots' URI 4144 IANA is requested to update the the 'dots' well-known URI (Table 6) 4145 entry in the Well- Known URIs registry [URI] as follows: 4147 +------------+------------+-----------+-----------+-------------+ 4148 | URI Suffix | Change | Reference | Status | Related | 4149 | | Controller | | | information | 4150 +============+============+===========+===========+=============+ 4151 | dots | IETF | [RFCXXXX] | permanent | None | 4152 +------------+------------+-----------+-----------+-------------+ 4154 Table 6: 'dots' Well-Known URI 4156 10.3. Media Type Registration 4158 IANA is requested to update the "application/dots+cbor" media type in 4159 the "Media Types" registry [IANA-MediaTypes] in the manner described 4160 in [RFC6838], which can be used to indicate that the content is a 4161 DOTS signal channel object: 4163 Type name: application 4165 Subtype name: dots+cbor 4167 Required parameters: N/A 4169 Optional parameters: N/A 4171 Encoding considerations: binary 4173 Security considerations: See the Security Considerations section of 4174 [RFCXXXx]. 4176 Interoperability considerations: N/A 4178 Published specification: [RFCXXXX] 4180 Applications that use this media type: DOTS agents sending DOTS 4181 messages over CoAP over (D)TLS. 4183 Fragment identifier considerations: N/A 4185 Additional information: 4187 Deprecated alias names for this type: N/A 4188 Magic number(s): N/A 4189 File extension(s): N/A 4190 Macintosh file type code(s): N/A 4192 Person & email address to contact for further information: IESG, 4193 iesg@ietf.org 4195 Intended usage: COMMON 4197 Restrictions on usage: none 4199 Author: See Authors' Addresses section. 4201 Change controller: IESG 4203 Provisional registration? No 4205 10.4. CoAP Content-Formats Registration 4207 IANA is requested to update the CoAP Content-Format ID for the 4208 "application/ dots+cbor" media type in the "CoAP Content-Formats" 4209 registry [IANA-CoAP-Content-Formats]: 4211 o Media Type: application/dots+cbor 4212 o Encoding: - 4213 o Id: 271 4214 o Reference: [RFCXXXX] 4216 10.5. CBOR Tag Registration 4218 This section defines the DOTS CBOR tag as another means for 4219 applications to declare that a CBOR data structure is a DOTS signal 4220 channel object. Its use is optional and is intended for use in cases 4221 in which this information would not otherwise be known. The DOTS 4222 CBOR tag is not required for DOTS signal channel protocol version 4223 specified in this document. If present, the DOTS tag MUST prefix a 4224 DOTS signal channel object. 4226 IANA is requested to update the DOTS signal channel CBOR tag in the 4227 "CBOR Tags" registry [IANA-CBOR-Tags]: 4229 * Tag: 271 4230 * Data Item: DDoS Open Threat Signaling (DOTS) signal channel object 4231 * Semantics: DDoS Open Threat Signaling (DOTS) signal channel 4232 object, as defined in [RFXXXX] 4233 * Reference: [RFCXXXX] 4235 10.6. DOTS Signal Channel Protocol Registry 4237 The following sections update the "Distributed Denial-of- Service 4238 Open Threat Signaling (DOTS) Signal Channel" subregistries 4239 [REG-DOTS]. 4241 10.6.1. DOTS Signal Channel CBOR Key Values Subregistry 4243 The structure of this subregistry is provided in Section 10.6.1.1. 4245 10.6.1.1. Registration Template 4247 This specification requests IANA to update the allocation policy of 4248 "DOTS Signal Channel CBOR Key Values" registry as follows: 4250 Parameter name: 4251 Parameter name as used in the DOTS signal channel. 4253 CBOR Key Value: 4254 Key value for the parameter. The key value MUST be an integer in 4255 the 1-65535 range. 4257 OLD: 4258 +-------------+-------------------------+------------------------+ 4259 | Range | Registration Procedures | Note | 4260 +=============+=========================+========================+ 4261 | 1-16383 | IETF Review | comprehension-required | 4262 | 16384-32767 | Specification Required | comprehension-optional | 4263 | 32768-49151 | IETF Review | comprehension-optional | 4264 | 49152-65535 | Private Use | comprehension-optional | 4265 +-------------+-------------------------+------------------------+ 4267 NEW: 4268 +-------------+-------------------------+------------------------+ 4269 | Range | Registration Procedures | Note | 4270 +=============+=========================+========================+ 4271 | 1-127 | IETF Review | comprehension-required | 4272 | 128-255 | IETF Review | comprehension-optional | 4273 | 256-16383 | IETF Review | comprehension-required | 4274 | 16384-32767 | Specification Required | comprehension-optional | 4275 | 32768-49151 | IETF Review | comprehension-optional | 4276 | 49152-65535 | Private Use | comprehension-optional | 4277 +-------------+-------------------------+------------------------+ 4279 Registration requests for the 16384-32767 range are evaluated 4280 after a three-week review period on the dots-signal-reg- 4281 review@ietf.org mailing list, on the advice of one or more 4282 Designated Experts. However, to allow for the allocation of 4283 values prior to publication, the Designated Experts may approve 4284 registration once they are satisfied that such a specification 4285 will be published. New registration requests should be sent in 4286 the form of an email to the review mailing list; the request 4287 should use an appropriate subject (e.g., "Request to register CBOR 4288 Key Value for DOTS: example"). IANA will only accept new 4289 registrations from the Designated Experts, and it will check that 4290 review was requested on the mailing list in accordance with these 4291 procedures. 4293 Within the review period, the Designated Experts will either 4294 approve or deny the registration request, communicating this 4295 decision to the review list and IANA. Denials should include an 4296 explanation and, if applicable, suggestions as to how to make the 4297 request successful. Registration requests that are undetermined 4298 for a period longer than 21 days can be brought to the IESG's 4299 attention (using the iesg@ietf.org mailing list) for resolution. 4301 Criteria that should be applied by the Designated Experts include 4302 determining whether the proposed registration duplicates existing 4303 functionality, whether it is likely to be of general applicability 4304 or whether it is useful only for a single use case, and whether 4305 the registration description is clear. IANA must only accept 4306 registry updates to the 16384-32767 range from the Designated 4307 Experts and should direct all requests for registration to the 4308 review mailing list. It is suggested that multiple Designated 4309 Experts be appointed. In cases where a registration decision 4310 could be perceived as creating a conflict of interest for a 4311 particular Expert, that Expert should defer to the judgment of the 4312 other Experts. 4314 CBOR Major Type: 4315 CBOR Major type and optional tag for the parameter. 4317 Change Controller: 4318 For Standards Track RFCs, list the "IESG". For others, give the 4319 name of the responsible party. Other details (e.g., email 4320 address) may also be included. 4322 Specification Document(s): 4323 Reference to the document or documents that specify the parameter, 4324 preferably including URIs that can be used to retrieve copies of 4325 the documents. An indication of the relevant sections may also be 4326 included but is not required. 4328 10.6.1.2. Update Subregistry Content 4330 IANA is requested to update these entries from the "DOTS Signal 4331 Channel CBOR Key Values" registry with the RFC number to be assigned 4332 to this document: 4334 +---------------------+------------+-----+----------+---------------+ 4335 | Parameter Name | CBOR Key |CBOR | Change | Specification | 4336 | | Value |Major|Controller| Document(s) | 4337 | | |Type | | | 4338 +=====================+============+=====+==========+===============+ 4339 | Reserved | 0 | | | [RFCXXXX] | 4340 +---------------------+------------+-----+----------+---------------+ 4341 | ietf-dots-signal- | 1 | 5 | IESG | [RFCXXXX] | 4342 | channel:mitigation- | | | | | 4343 | scope | | | | | 4344 +---------------------+------------+-----+----------+---------------+ 4345 | scope | 2 | 4 | IESG | [RFCXXXX] | 4346 +---------------------+------------+-----+----------+---------------+ 4347 | cdid | 3 | 3 | IESG | [RFCXXXX] | 4348 +---------------------+------------+-----+----------+---------------+ 4349 | cuid | 4 | 3 | IESG | [RFCXXXX] | 4350 +---------------------+------------+-----+----------+---------------+ 4351 | mid | 5 | 0 | IESG | [RFCXXXX] | 4352 +---------------------+------------+-----+----------+---------------+ 4353 | target-prefix | 6 | 4 | IESG | [RFCXXXX] | 4354 +---------------------+------------+-----+----------+---------------+ 4355 | target-port-range | 7 | 4 | IESG | [RFCXXXX] | 4356 +---------------------+------------+-----+----------+---------------+ 4357 | lower-port | 8 | 0 | IESG | [RFCXXXX] | 4358 +---------------------+------------+-----+----------+---------------+ 4359 | upper-port | 9 | 0 | IESG | [RFCXXXX] | 4360 +---------------------+------------+-----+----------+---------------+ 4361 | target-protocol | 10 | 4 | IESG | [RFCXXXX] | 4362 +---------------------+------------+-----+----------+---------------+ 4363 | target-fqdn | 11 | 4 | IESG | [RFCXXXX] | 4364 +---------------------+------------+-----+----------+---------------+ 4365 | target-uri | 12 | 4 | IESG | [RFCXXXX] | 4366 +---------------------+------------+-----+----------+---------------+ 4367 | alias-name | 13 | 4 | IESG | [RFCXXXX] | 4368 +---------------------+------------+-----+----------+---------------+ 4369 | lifetime | 14 | 0/1 | IESG | [RFCXXXX] | 4370 +---------------------+------------+-----+----------+---------------+ 4371 | mitigation-start | 15 | 0 | IESG | [RFCXXXX] | 4372 +---------------------+------------+-----+----------+---------------+ 4373 | status | 16 | 0 | IESG | [RFCXXXX] | 4374 +---------------------+------------+-----+----------+---------------+ 4375 |conflict-information | 17 | 5 | IESG | [RFCXXXX] | 4376 +---------------------+------------+-----+----------+---------------+ 4377 | conflict-status | 18 | 0 | IESG | [RFCXXXX] | 4378 +---------------------+------------+-----+----------+---------------+ 4379 | conflict-cause | 19 | 0 | IESG | [RFCXXXX] | 4380 +---------------------+------------+-----+----------+---------------+ 4381 | retry-timer | 20 | 0 | IESG | [RFCXXXX] | 4382 +---------------------+------------+-----+----------+---------------+ 4383 | conflict-scope | 21 | 5 | IESG | [RFCXXXX] | 4384 +---------------------+------------+-----+----------+---------------+ 4385 | acl-list | 22 | 4 | IESG | [RFCXXXX] | 4386 +---------------------+------------+-----+----------+---------------+ 4387 | acl-name | 23 | 3 | IESG | [RFCXXXX] | 4388 +---------------------+------------+-----+----------+---------------+ 4389 | acl-type | 24 | 3 | IESG | [RFCXXXX] | 4390 +---------------------+------------+-----+----------+---------------+ 4391 | bytes-dropped | 25 | 0 | IESG | [RFCXXXX] | 4392 +---------------------+------------+-----+----------+---------------+ 4393 | bps-dropped | 26 | 0 | IESG | [RFCXXXX] | 4394 +---------------------+------------+-----+----------+---------------+ 4395 | pkts-dropped | 27 | 0 | IESG | [RFCXXXX] | 4396 +---------------------+------------+-----+----------+---------------+ 4397 | pps-dropped | 28 | 0 | IESG | [RFCXXXX] | 4398 +---------------------+------------+-----+----------+---------------+ 4399 | attack-status | 29 | 0 | IESG | [RFCXXXX] | 4400 +---------------------+------------+-----+----------+---------------+ 4401 | ietf-dots-signal- | 30 | 5 | IESG | [RFCXXXX] | 4402 |channel:signal-config| | | | | 4403 +---------------------+------------+-----+----------+---------------+ 4404 | sid | 31 | 0 | IESG | [RFCXXXX] | 4405 +---------------------+------------+-----+----------+---------------+ 4406 | mitigating-config | 32 | 5 | IESG | [RFCXXXX] | 4407 +---------------------+------------+-----+----------+---------------+ 4408 | heartbeat-interval | 33 | 5 | IESG | [RFCXXXX] | 4409 +---------------------+------------+-----+----------+---------------+ 4410 | min-value | 34 | 0 | IESG | [RFCXXXX] | 4411 +---------------------+------------+-----+----------+---------------+ 4412 | max-value | 35 | 0 | IESG | [RFCXXXX] | 4413 +---------------------+------------+-----+----------+---------------+ 4414 | current-value | 36 | 0 | IESG | [RFCXXXX] | 4415 +---------------------+------------+-----+----------+---------------+ 4416 | missing-hb-allowed | 37 | 5 | IESG | [RFCXXXX] | 4417 +---------------------+------------+-----+----------+---------------+ 4418 | max-retransmit | 38 | 5 | IESG | [RFCXXXX] | 4419 +---------------------+------------+-----+----------+---------------+ 4420 | ack-timeout | 39 | 5 | IESG | [RFCXXXX] | 4421 +---------------------+------------+-----+----------+---------------+ 4422 | ack-random-factor | 40 | 5 | IESG | [RFCXXXX] | 4423 +---------------------+------------+-----+----------+---------------+ 4424 | min-value-decimal | 41 |6tag4| IESG | [RFCXXXX] | 4425 +---------------------+------------+-----+----------+---------------+ 4426 | max-value-decimal | 42 |6tag4| IESG | [RFCXXXX] | 4427 +---------------------+------------+-----+----------+---------------+ 4428 |current-value-decimal| 43 |6tag4| IESG | [RFCXXXX] | 4429 +---------------------+------------+-----+----------+---------------+ 4430 | idle-config | 44 | 5 | IESG | [RFCXXXX] | 4431 +---------------------+------------+-----+----------+---------------+ 4432 | trigger-mitigation | 45 | 7 | IESG | [RFCXXXX] | 4433 +---------------------+------------+-----+----------+---------------+ 4434 | ietf-dots-signal- | 46 | 5 | IESG | [RFCXXXX] | 4435 | channel:redirected- | | | | | 4436 | signal | | | | | 4437 +---------------------+------------+-----+----------+---------------+ 4438 | alt-server | 47 | 3 | IESG | [RFCXXXX] | 4439 +---------------------+------------+-----+----------+---------------+ 4440 | alt-server-record | 48 | 4 | IESG | [RFCXXXX] | 4441 +---------------------+------------+-----+----------+---------------+ 4442 | ietf-dots-signal- | 49 | 5 | IESG | [RFCXXXX] | 4443 | channel:heartbeat | | | | | 4444 +---------------------+------------+-----+----------+---------------+ 4445 | probing-rate | 50 | 5 | IESG | [RFCXXXX] | 4446 +---------------------+------------+-----+----------+---------------+ 4447 | peer-hb-status | 51 | 7 | IESG | [RFCXXXX] | 4448 +---------------------+------------+-----+----------+---------------+ 4449 | Unassigned | 52-49151 | | | | 4450 +---------------------+------------+-----+----------+---------------+ 4451 |Reserved for Private |49152-65535 | | | [RFCXXXX] | 4452 | Use | | | | | 4453 +---------------------+------------+-----+----------+---------------+ 4455 Table 6: Initial DOTS Signal Channel CBOR Key Values Registry 4457 10.6.2. Status Codes Subregistry 4459 IANA is requested to update these entries from the "DOTS Signal 4460 Channel Status Codes" registry with the RFC number to be assigned to 4461 this document: 4463 +--------------+---------------+----------------------+-----------+ 4464 | Code | Label | Description | Reference | 4465 +==============+===============+======================+===========+ 4466 | 0 | Reserved | | [RFCXXXX] | 4467 +--------------+---------------+----------------------+-----------+ 4468 | 1 | attack- | Attack mitigation | [RFCXXXX] | 4469 | | mitigation- | setup is in progress | | 4470 | | in-progress | (e.g., changing the | | 4471 | | | network path to | | 4472 | | | redirect the inbound | | 4473 | | | traffic to a DOTS | | 4474 | | | mitigator). | | 4475 +--------------+---------------+----------------------+-----------+ 4476 | 2 | attack- | Attack is being | [RFCXXXX] | 4477 | | successfully- | successfully | | 4478 | | mitigated | mitigated (e.g., | | 4479 | | | traffic is | | 4480 | | | redirected to a DDoS | | 4481 | | | mitigator and attack | | 4482 | | | traffic is dropped). | | 4483 +--------------+---------------+----------------------+-----------+ 4484 | 3 | attack- | Attack has stopped | [RFCXXXX] | 4485 | | stopped | and the DOTS client | | 4486 | | | can withdraw the | | 4487 | | | mitigation request. | | 4488 +--------------+---------------+----------------------+-----------+ 4489 | 4 | attack- | Attack has exceeded | [RFCXXXX] | 4490 | | exceeded- | the mitigation | | 4491 | | capability | provider capability. | | 4492 +--------------+---------------+----------------------+-----------+ 4493 | 5 | dots-client- | DOTS client has | [RFCXXXX] | 4494 | | withdrawn- | withdrawn the | | 4495 | | mitigation | mitigation request | | 4496 | | | and the mitigation | | 4497 | | | is active but | | 4498 | | | terminating. | | 4499 +--------------+---------------+----------------------+-----------+ 4500 | 6 | attack- | Attack mitigation is | [RFCXXXX] | 4501 | | mitigation- | now terminated. | | 4502 | | terminated | | | 4503 +--------------+---------------+----------------------+-----------+ 4504 | 7 | attack- | Attack mitigation is | [RFCXXXX] | 4505 | | mitigation- | withdrawn. | | 4506 | | withdrawn | | | 4507 +--------------+---------------+----------------------+-----------+ 4508 | 8 | attack- | Attack mitigation | [RFCXXXX] | 4509 | | mitigation- | will be triggered | | 4510 | | signal-loss | for the mitigation | | 4511 | | | request only when | | 4512 | | | the DOTS signal | | 4513 | | | channel session is | | 4514 | | | lost. | | 4515 +--------------+---------------+----------------------+-----------+ 4516 | 9-2147483647 | Unassigned | | | 4517 +--------------+---------------+----------------------+-----------+ 4519 Table 8: Initial DOTS Signal Channel Status Codes 4521 New codes can be assigned via Standards Action [RFC8126]. 4523 10.6.3. Conflict Status Codes Subregistry 4525 IANA is requested to update these entries from the "DOTS Signal 4526 Channel Conflict Status Codes" registry with the RFC number to be 4527 assigned to this document: 4529 +--------------+-------------------+--------------------+-----------+ 4530 | Code | Label | Description | Reference | 4531 +==============+===================+====================+===========+ 4532 | 0 | Reserved | | [RFCXXXX] | 4533 +--------------+-------------------+--------------------+-----------+ 4534 | 1 | request-inactive- | DOTS server | [RFCXXXX] | 4535 | | other-active | has detected | | 4536 | | | conflicting | | 4537 | | | mitigation | | 4538 | | | requests from | | 4539 | | | different DOTS | | 4540 | | | clients. This | | 4541 | | | mitigation | | 4542 | | | request is | | 4543 | | | currently | | 4544 | | | inactive until | | 4545 | | | the conflicts | | 4546 | | | are resolved. | | 4547 | | | Another | | 4548 | | | mitigation | | 4549 | | | request is | | 4550 | | | active. | | 4551 +--------------+-------------------+--------------------+-----------+ 4552 | 2 | request-active | DOTS server | [RFCXXXX] | 4553 | | | has detected | | 4554 | | | conflicting | | 4555 | | | mitigation | | 4556 | | | requests from | | 4557 | | | different DOTS | | 4558 | | | clients. This | | 4559 | | | mitigation | | 4560 | | | request is | | 4561 | | | currently | | 4562 | | | active. | | 4563 +--------------+-------------------+--------------------+-----------+ 4564 | 3 | all-requests- | DOTS server | [RFCXXXX] | 4565 | | inactive | has detected | | 4566 | | | conflicting | | 4567 | | | mitigation | | 4568 | | | requests from | | 4569 | | | different DOTS | | 4570 | | | clients. All | | 4571 | | | conflicting | | 4572 | | | mitigation | | 4573 | | | requests are | | 4574 | | | inactive. | | 4575 +--------------+-------------------+--------------------+-----------+ 4576 | 4-2147483647 | Unassigned | | | 4577 +--------------+-------------------+--------------------+-----------+ 4579 Table 9: Initial DOTS Signal Channel Conflict Status Codes 4581 New codes can be assigned via Standards Action [RFC8126]. 4583 10.6.4. Conflict Cause Codes Subregistry 4585 IANA is requested to update these entries from the "DOTS Signal 4586 Channel Conflict Cause Codes" registry with the RFC number to be 4587 assigned to this document: 4589 +--------------+---------------------+----------------+-----------+ 4590 | Code | Label | Description | Reference | 4591 +==============+=====================+================+===========+ 4592 | 0 | Reserved | | [RFCXXXX] | 4593 +--------------+---------------------+----------------+-----------+ 4594 | 1 | overlapping-targets | Overlapping | [RFCXXXX] | 4595 | | | targets. | | 4596 +--------------+---------------------+----------------+-----------+ 4597 | 2 | conflict-with- | Conflicts with | [RFCXXXX] | 4598 | | acceptlist | an existing | | 4599 | | | accept-list. | | 4600 | | | This code is | | 4601 | | | returned when | | 4602 | | | the DDoS | | 4603 | | | mitigation | | 4604 | | | detects source | | 4605 | | | addresses/ | | 4606 | | | prefixes in | | 4607 | | | the accept- | | 4608 | | | listed ACLs | | 4609 | | | are attacking | | 4610 | | | the target. | | 4611 +--------------+---------------------+----------------+-----------+ 4612 | 3 | cuid-collision | CUID | [RFCXXXX] | 4613 | | | Collision. | | 4614 | | | This code is | | 4615 | | | returned when | | 4616 | | | a DOTS client | | 4617 | | | uses a 'cuid' | | 4618 | | | that is | | 4619 | | | already used | | 4620 | | | by another | | 4621 | | | DOTS client. | | 4622 +--------------+---------------------+----------------+-----------+ 4623 | 4-2147483647 | Unassigned | | | 4624 +--------------+---------------------+----------------+-----------+ 4626 Table 10: Initial DOTS Signal Channel Conflict Cause Codes 4628 New codes can be assigned via Standards Action [RFC8126]. 4630 10.6.5. Attack Status Codes Subregistry 4632 IANA is requested to update these entries from the "DOTS Signal 4633 Channel Attack Status Codes" registry with the RFC number to be 4634 assigned to this document: 4636 +--------------+----------------------+-----------------+-----------+ 4637 | Code | Label | Description | Reference | 4638 +==============+======================+=================+===========+ 4639 | 0 | Reserved | | [RFCXXXX] | 4640 +--------------+----------------------+-----------------+-----------+ 4641 | 1 | under-attack | The DOTS | [RFCXXXX] | 4642 | | | client | | 4643 | | | determines | | 4644 | | | that it is | | 4645 | | | still under | | 4646 | | | attack. | | 4647 +--------------+----------------------+-----------------+-----------+ 4648 | 2 | attack-successfully- | The DOTS | [RFCXXXX] | 4649 | | mitigated | client | | 4650 | | | determines | | 4651 | | | that the | | 4652 | | | attack is | | 4653 | | | successfully | | 4654 | | | mitigated. | | 4655 +--------------+----------------------+-----------------+-----------+ 4656 | 3-2147483647 | Unassigned | | | 4657 +--------------+----------------------+-----------------+-----------+ 4659 Table 11: Initial DOTS Signal Channel Attack Status Codes 4661 New codes can be assigned via Standards Action [RFC8126]. 4663 10.7. DOTS Signal Channel YANG Modules 4665 This document requests IANA to register the following URIs in the 4666 "ns" subregistry within the "IETF XML Registry" [RFC3688]: 4668 URI: urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel 4669 Registrant Contact: The IESG. 4670 XML: N/A; the requested URI is an XML namespace. 4672 URI: urn:ietf:params:xml:ns:yang:iana-dots-signal-channel 4673 Registrant Contact: IANA. 4674 XML: N/A; the requested URI is an XML namespace. 4676 This document requests IANA to register the following YANG modules in 4677 the "YANG Module Names" subregistry [RFC6020] within the "YANG 4678 Parameters" registry. 4680 Name: ietf-dots-signal-channel 4681 Maintained by IANA: N 4682 Namespace: urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel 4683 Prefix: signal 4684 Reference: RFC8782 4686 Name: iana-dots-signal-channel 4687 Maintained by IANA: Y 4688 Namespace: urn:ietf:params:xml:ns:yang:iana-dots-signal-channel 4689 Prefix: iana-signal 4690 Reference: RFC8782 4692 This document defines the initial version of the IANA-maintained 4693 iana-dots-signal-channel YANG module. IANA is requested to maintain 4694 this note: 4696 Status, conflict status, conflict cause, and attack status values 4697 must not be directly added to the iana-dots-signal-channel YANG 4698 module. They must instead be respectively added to the "DOTS 4699 Status Codes", "DOTS Conflict Status Codes", "DOTS Conflict Cause 4700 Codes", and "DOTS Attack Status Codes" registries. 4702 When a 'status', 'conflict-status', 'conflict-cause', or 'attack- 4703 status' value is respectively added to the "DOTS Status Codes", "DOTS 4704 Conflict Status Codes", "DOTS Conflict Cause Codes", or "DOTS Attack 4705 Status Codes" registry, a new "enum" statement must be added to the 4706 iana-dots-signal-channel YANG module. The following "enum" 4707 statement, and substatements thereof, should be defined: 4709 "enum": Replicates the label from the registry. 4711 "value": Contains the IANA-assigned value corresponding to the 4712 'status', 'conflict-status', 'conflict-cause', or 4713 'attack-status'. 4715 "description": Replicates the description from the registry. 4717 "reference": Replicates the reference from the registry and adds 4718 the title of the document. 4720 When the iana-dots-signal-channel YANG module is updated, a new 4721 "revision" statement must be added in front of the existing revision 4722 statements. 4724 IANA is requested to update this note of "DOTS Status Codes", "DOTS 4725 Conflict Status Codes", "DOTS Conflict Cause Codes", and "DOTS Attack 4726 Status Codes" registries: 4728 When this registry is modified, the YANG module iana-dots-signal- 4729 channel must be updated as defined in [RFCXXXX]. 4731 11. Security Considerations 4733 High-level DOTS security considerations are documented in [RFC8612] 4734 and [I-D.ietf-dots-architecture]. 4736 Authenticated encryption MUST be used for data confidentiality and 4737 message integrity. The interaction between the DOTS agents requires 4738 Datagram Transport Layer Security (DTLS) or Transport Layer Security 4739 (TLS) with a cipher suite offering confidentiality protection, and 4740 the guidance given in [RFC7525] MUST be followed to avoid attacks on 4741 (D)TLS. The (D)TLS protocol profile used for the DOTS signal channel 4742 is specified in Section 7. 4744 If TCP is used between DOTS agents, an attacker may be able to inject 4745 RST packets, bogus application segments, etc., regardless of whether 4746 TLS authentication is used. Because the application data is TLS 4747 protected, this will not result in the application receiving bogus 4748 data, but it will constitute a DoS on the connection. This attack 4749 can be countered by using TCP Authentication Option (TCP-AO) 4750 [RFC5925]. Although not widely adopted, if TCP-AO is used, then any 4751 bogus packets injected by an attacker will be rejected by the TCP-AO 4752 integrity check and therefore will never reach the TLS layer. 4754 If the 'cuid' is guessable, a misbehaving DOTS client from within the 4755 client's domain can use the 'cuid' of another DOTS client of the 4756 domain to delete or alter active mitigations. For this attack vector 4757 to happen, the misbehaving client needs to pass the security 4758 validation checks by the DOTS server, and eventually the checks of a 4759 client-domain DOTS gateway. 4761 A similar attack can be achieved by a compromised DOTS client that 4762 can sniff the TLS 1.2 handshake, use the client certificate to 4763 identify the 'cuid' used by another DOTS client. This attack is not 4764 possible if algorithms such as version 4 Universally Unique 4765 IDentifiers (UUIDs) in Section 4.4 of [RFC4122] are used to generate 4766 the 'cuid' because such UUIDs are not a deterministic function of the 4767 client certificate. Likewise, this attack is not possible with TLS 4768 1.3 because most of the TLS handshake is encrypted and the client 4769 certificate is not visible to eavesdroppers. 4771 A compromised DOTS client can collude with a DDoS attacker to send 4772 mitigation request for a target resource, get the mitigation efficacy 4773 from the DOTS server, and convey the mitigation efficacy to the DDoS 4774 attacker to possibly change the DDoS attack strategy. Obviously, 4775 signaling an attack by the compromised DOTS client to the DOTS server 4776 will trigger attack mitigation. This attack can be prevented by 4777 monitoring and auditing DOTS clients to detect misbehavior and to 4778 deter misuse, and by only authorizing the DOTS client to request 4779 mitigation for specific target resources (e.g., an application server 4780 is authorized to request mitigation for its IP addresses, but a DDoS 4781 mitigator can request mitigation for any target resource in the 4782 network). Furthermore, DOTS clients are typically co-located on 4783 network security services (e.g., firewall), and a compromised 4784 security service potentially can do a lot more damage to the network. 4786 Rate-limiting DOTS requests, including those with new 'cuid' values, 4787 from the same DOTS client defend against DoS attacks that would 4788 result in varying the 'cuid' to exhaust DOTS server resources. Rate- 4789 limit policies SHOULD be enforced on DOTS gateways (if deployed) and 4790 DOTS servers. 4792 In order to prevent leaking internal information outside a client's 4793 domain, DOTS gateways located in the client domain SHOULD NOT reveal 4794 the identification information that pertains to internal DOTS clients 4795 (e.g., source IP address, client's hostname) unless explicitly 4796 configured to do so. 4798 DOTS servers MUST verify that requesting DOTS clients are entitled to 4799 trigger actions on a given IP prefix. That is, only actions on IP 4800 resources that belong to the DOTS client's domain MUST be authorized 4801 by a DOTS server. The exact mechanism for the DOTS servers to 4802 validate that the target prefixes are within the scope of the DOTS 4803 client domain is deployment specific. 4805 The presence of DOTS gateways may lead to infinite forwarding loops, 4806 which is undesirable. To prevent and detect such loops, this 4807 document uses the Hop-Limit Option. 4809 When FQDNs are used as targets, the DOTS server MUST rely upon DNS 4810 privacy-enabling protocols (e.g., DNS over TLS [RFC7858] or DNS over 4811 HTTPS (DoH) [RFC8484]) to prevent eavesdroppers from possibly 4812 identifying the target resources protected by the DDoS mitigation 4813 service to ensure the target FQDN resolution is authentic (e.g., 4814 DNSSEC [RFC4034]). 4816 CoAP-specific security considerations are discussed in Section 11 of 4817 [RFC7252], while CBOR-related security considerations are discussed 4818 in Section 8 of [RFC7049]. 4820 This document defines YANG data structures that are meant to be used 4821 as an abstract representation of DOTS signal channel messages. As 4822 such, the "ietf-dots-signal-channel" module does not introduce any 4823 new vulnerabilities beyond those specified above. 4825 12. References 4827 12.1. Normative References 4829 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 4830 DOI 10.17487/RFC0791, September 1981, 4831 . 4833 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 4834 Communication Layers", STD 3, RFC 1122, 4835 DOI 10.17487/RFC1122, October 1989, 4836 . 4838 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4839 Requirement Levels", BCP 14, RFC 2119, 4840 DOI 10.17487/RFC2119, March 1997, 4841 . 4843 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 4844 DOI 10.17487/RFC3688, January 2004, 4845 . 4847 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 4848 Resource Identifier (URI): Generic Syntax", STD 66, 4849 RFC 3986, DOI 10.17487/RFC3986, January 2005, 4850 . 4852 [RFC4279] Eronen, P., Ed. and H. Tschofenig, Ed., "Pre-Shared Key 4853 Ciphersuites for Transport Layer Security (TLS)", 4854 RFC 4279, DOI 10.17487/RFC4279, December 2005, 4855 . 4857 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 4858 (CIDR): The Internet Address Assignment and Aggregation 4859 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 4860 2006, . 4862 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 4863 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 4864 . 4866 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 4867 (TLS) Protocol Version 1.2", RFC 5246, 4868 DOI 10.17487/RFC5246, August 2008, 4869 . 4871 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 4872 Housley, R., and W. Polk, "Internet X.509 Public Key 4873 Infrastructure Certificate and Certificate Revocation List 4874 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 4875 . 4877 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 4878 the Network Configuration Protocol (NETCONF)", RFC 6020, 4879 DOI 10.17487/RFC6020, October 2010, 4880 . 4882 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 4883 Extensions: Extension Definitions", RFC 6066, 4884 DOI 10.17487/RFC6066, January 2011, 4885 . 4887 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 4888 Verification of Domain-Based Application Service Identity 4889 within Internet Public Key Infrastructure Using X.509 4890 (PKIX) Certificates in the Context of Transport Layer 4891 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 4892 2011, . 4894 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 4895 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 4896 January 2012, . 4898 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 4899 RFC 6991, DOI 10.17487/RFC6991, July 2013, 4900 . 4902 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 4903 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 4904 October 2013, . 4906 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 4907 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 4908 Transport Layer Security (TLS) and Datagram Transport 4909 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 4910 June 2014, . 4912 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 4913 Application Protocol (CoAP)", RFC 7252, 4914 DOI 10.17487/RFC7252, June 2014, 4915 . 4917 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 4918 "Recommendations for Secure Use of Transport Layer 4919 Security (TLS) and Datagram Transport Layer Security 4920 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 4921 2015, . 4923 [RFC7641] Hartke, K., "Observing Resources in the Constrained 4924 Application Protocol (CoAP)", RFC 7641, 4925 DOI 10.17487/RFC7641, September 2015, 4926 . 4928 [RFC7918] Langley, A., Modadugu, N., and B. Moeller, "Transport 4929 Layer Security (TLS) False Start", RFC 7918, 4930 DOI 10.17487/RFC7918, August 2016, 4931 . 4933 [RFC7924] Santesson, S. and H. Tschofenig, "Transport Layer Security 4934 (TLS) Cached Information Extension", RFC 7924, 4935 DOI 10.17487/RFC7924, July 2016, 4936 . 4938 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 4939 RFC 7950, DOI 10.17487/RFC7950, August 2016, 4940 . 4942 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 4943 the Constrained Application Protocol (CoAP)", RFC 7959, 4944 DOI 10.17487/RFC7959, August 2016, 4945 . 4947 [RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 4948 Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, 4949 March 2017, . 4951 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 4952 Writing an IANA Considerations Section in RFCs", BCP 26, 4953 RFC 8126, DOI 10.17487/RFC8126, June 2017, 4954 . 4956 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 4957 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 4958 May 2017, . 4960 [RFC8200] Deering, S. and R. Hinden, "Internet Protocol, Version 6 4961 (IPv6) Specification", STD 86, RFC 8200, 4962 DOI 10.17487/RFC8200, July 2017, 4963 . 4965 [RFC8305] Schinazi, D. and T. Pauly, "Happy Eyeballs Version 2: 4966 Better Connectivity Using Concurrency", RFC 8305, 4967 DOI 10.17487/RFC8305, December 2017, 4968 . 4970 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 4971 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 4972 Application Protocol) over TCP, TLS, and WebSockets", 4973 RFC 8323, DOI 10.17487/RFC8323, February 2018, 4974 . 4976 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 4977 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 4978 . 4980 [RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers 4981 (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, 4982 . 4984 [RFC8768] Boucadair, M., Reddy.K, T., and J. Shallow, "Constrained 4985 Application Protocol (CoAP) Hop-Limit Option", RFC 8768, 4986 DOI 10.17487/RFC8768, March 2020, 4987 . 4989 [RFC8783] Boucadair, M., Ed. and T. Reddy.K, Ed., "Distributed 4990 Denial-of-Service Open Threat Signaling (DOTS) Data 4991 Channel Specification", RFC 8783, DOI 10.17487/RFC8783, 4992 May 2020, . 4994 [RFC8791] Bierman, A., Bjoerklund, M., and K. Watsen, "YANG Data 4995 Structure Extensions", RFC 8791, DOI 10.17487/RFC8791, 4996 June 2020, . 4998 12.2. Informative References 5000 [I-D.boucadair-dots-earlydata] 5001 Boucadair, M. and R. K, "Using Early Data in DOTS", draft- 5002 boucadair-dots-earlydata-00 (work in progress), January 5003 2019. 5005 [I-D.ietf-core-comi] 5006 Veillette, M., Stok, P., Pelov, A., Bierman, A., and I. 5007 Petrov, "CoAP Management Interface (CORECONF)", draft- 5008 ietf-core-comi-10 (work in progress), July 2020. 5010 [I-D.ietf-core-yang-cbor] 5011 Veillette, M., Petrov, I., and A. Pelov, "CBOR Encoding of 5012 Data Modeled with YANG", draft-ietf-core-yang-cbor-13 5013 (work in progress), July 2020. 5015 [I-D.ietf-dots-architecture] 5016 Mortensen, A., Reddy.K, T., Andreasen, F., Teague, N., and 5017 R. Compton, "Distributed-Denial-of-Service Open Threat 5018 Signaling (DOTS) Architecture", draft-ietf-dots- 5019 architecture-18 (work in progress), March 2020. 5021 [I-D.ietf-dots-multihoming] 5022 Boucadair, M., Reddy.K, T., and W. Pan, "Multi-homing 5023 Deployment Considerations for Distributed-Denial-of- 5024 Service Open Threat Signaling (DOTS)", draft-ietf-dots- 5025 multihoming-04 (work in progress), May 2020. 5027 [I-D.ietf-dots-server-discovery] 5028 Boucadair, M. and T. Reddy.K, "Distributed-Denial-of- 5029 Service Open Threat Signaling (DOTS) Agent Discovery", 5030 draft-ietf-dots-server-discovery-10 (work in progress), 5031 February 2020. 5033 [I-D.ietf-dots-telemetry] 5034 Boucadair, M., Reddy.K, T., Doron, E., chenmeiling, c., 5035 and J. Shallow, "Distributed Denial-of-Service Open Threat 5036 Signaling (DOTS) Telemetry", draft-ietf-dots-telemetry-10 5037 (work in progress), July 2020. 5039 [I-D.ietf-dots-use-cases] 5040 Dobbins, R., Migault, D., Moskowitz, R., Teague, N., Xia, 5041 L., and K. Nishizuka, "Use cases for DDoS Open Threat 5042 Signaling", draft-ietf-dots-use-cases-25 (work in 5043 progress), July 2020. 5045 [I-D.ietf-tls-dtls13] 5046 Rescorla, E., Tschofenig, H., and N. Modadugu, "The 5047 Datagram Transport Layer Security (DTLS) Protocol Version 5048 1.3", draft-ietf-tls-dtls13-38 (work in progress), May 5049 2020. 5051 [IANA-CBOR-Tags] 5052 IANA, "Concise Binary Object Representation (CBOR) Tags", 5053 . 5056 [IANA-CoAP-Content-Formats] 5057 IANA, "CoAP Content-Formats", 5058 . 5061 [IANA-MediaTypes] 5062 IANA, "Media Types", 5063 . 5065 [IANA-Proto] 5066 IANA, "Protocol Numbers", 2011, 5067 . 5069 [REG-DOTS] 5070 IANA, "Distributed Denial-of-Service Open Threat Signaling 5071 (DOTS) Signal Channel", 5072 . 5074 [RFC3022] Srisuresh, P. and K. Egevang, "Traditional IP Network 5075 Address Translator (Traditional NAT)", RFC 3022, 5076 DOI 10.17487/RFC3022, January 2001, 5077 . 5079 [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. 5080 Rose, "Resource Records for the DNS Security Extensions", 5081 RFC 4034, DOI 10.17487/RFC4034, March 2005, 5082 . 5084 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 5085 Unique IDentifier (UUID) URN Namespace", RFC 4122, 5086 DOI 10.17487/RFC4122, July 2005, 5087 . 5089 [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram 5090 Congestion Control Protocol (DCCP)", RFC 4340, 5091 DOI 10.17487/RFC4340, March 2006, 5092 . 5094 [RFC4732] Handley, M., Ed., Rescorla, E., Ed., and IAB, "Internet 5095 Denial-of-Service Considerations", RFC 4732, 5096 DOI 10.17487/RFC4732, December 2006, 5097 . 5099 [RFC4787] Audet, F., Ed. and C. Jennings, "Network Address 5100 Translation (NAT) Behavioral Requirements for Unicast 5101 UDP", BCP 127, RFC 4787, DOI 10.17487/RFC4787, January 5102 2007, . 5104 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 5105 RFC 4960, DOI 10.17487/RFC4960, September 2007, 5106 . 5108 [RFC4987] Eddy, W., "TCP SYN Flooding Attacks and Common 5109 Mitigations", RFC 4987, DOI 10.17487/RFC4987, August 2007, 5110 . 5112 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 5113 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 5114 June 2010, . 5116 [RFC6052] Bao, C., Huitema, C., Bagnulo, M., Boucadair, M., and X. 5117 Li, "IPv6 Addressing of IPv4/IPv6 Translators", RFC 6052, 5118 DOI 10.17487/RFC6052, October 2010, 5119 . 5121 [RFC6146] Bagnulo, M., Matthews, P., and I. van Beijnum, "Stateful 5122 NAT64: Network Address and Protocol Translation from IPv6 5123 Clients to IPv4 Servers", RFC 6146, DOI 10.17487/RFC6146, 5124 April 2011, . 5126 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 5127 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 5128 DOI 10.17487/RFC6234, May 2011, 5129 . 5131 [RFC6296] Wasserman, M. and F. Baker, "IPv6-to-IPv6 Network Prefix 5132 Translation", RFC 6296, DOI 10.17487/RFC6296, June 2011, 5133 . 5135 [RFC6724] Thaler, D., Ed., Draves, R., Matsumoto, A., and T. Chown, 5136 "Default Address Selection for Internet Protocol Version 6 5137 (IPv6)", RFC 6724, DOI 10.17487/RFC6724, September 2012, 5138 . 5140 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 5141 Specifications and Registration Procedures", BCP 13, 5142 RFC 6838, DOI 10.17487/RFC6838, January 2013, 5143 . 5145 [RFC6887] Wing, D., Ed., Cheshire, S., Boucadair, M., Penno, R., and 5146 P. Selkirk, "Port Control Protocol (PCP)", RFC 6887, 5147 DOI 10.17487/RFC6887, April 2013, 5148 . 5150 [RFC6888] Perreault, S., Ed., Yamagata, I., Miyakawa, S., Nakagawa, 5151 A., and H. Ashida, "Common Requirements for Carrier-Grade 5152 NATs (CGNs)", BCP 127, RFC 6888, DOI 10.17487/RFC6888, 5153 April 2013, . 5155 [RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed., 5156 "Enrollment over Secure Transport", RFC 7030, 5157 DOI 10.17487/RFC7030, October 2013, 5158 . 5160 [RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 5161 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 5162 . 5164 [RFC7452] Tschofenig, H., Arkko, J., Thaler, D., and D. McPherson, 5165 "Architectural Considerations in Smart Object Networking", 5166 RFC 7452, DOI 10.17487/RFC7452, March 2015, 5167 . 5169 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 5170 NETCONF Protocol over Transport Layer Security (TLS) with 5171 Mutual X.509 Authentication", RFC 7589, 5172 DOI 10.17487/RFC7589, June 2015, 5173 . 5175 [RFC7858] Hu, Z., Zhu, L., Heidemann, J., Mankin, A., Wessels, D., 5176 and P. Hoffman, "Specification for DNS over Transport 5177 Layer Security (TLS)", RFC 7858, DOI 10.17487/RFC7858, May 5178 2016, . 5180 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 5181 RFC 7951, DOI 10.17487/RFC7951, August 2016, 5182 . 5184 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 5185 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 5186 . 5188 [RFC8484] Hoffman, P. and P. McManus, "DNS Queries over HTTPS 5189 (DoH)", RFC 8484, DOI 10.17487/RFC8484, October 2018, 5190 . 5192 [RFC8489] Petit-Huguenin, M., Salgueiro, G., Rosenberg, J., Wing, 5193 D., Mahy, R., and P. Matthews, "Session Traversal 5194 Utilities for NAT (STUN)", RFC 8489, DOI 10.17487/RFC8489, 5195 February 2020, . 5197 [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 5198 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 5199 January 2019, . 5201 [RFC8612] Mortensen, A., Reddy, T., and R. Moskowitz, "DDoS Open 5202 Threat Signaling (DOTS) Requirements", RFC 8612, 5203 DOI 10.17487/RFC8612, May 2019, 5204 . 5206 [RFC8782] Reddy.K, T., Ed., Boucadair, M., Ed., Patil, P., 5207 Mortensen, A., and N. Teague, "Distributed Denial-of- 5208 Service Open Threat Signaling (DOTS) Signal Channel 5209 Specification", RFC 8782, DOI 10.17487/RFC8782, May 2020, 5210 . 5212 [URI] IANA, "Well-Known URIs", 5213 . 5216 Appendix A. Summary of Changes From RFC8782 5218 The main changes compared to [RFC8782] are as follows: 5220 o Update the "ietf-dots-signal-channel" YANG module (Section 5.3) 5221 and the tree structure (Section 5.1) to follow the new YANG data 5222 structure specified in [RFC8791]. In particular: 5224 * Add in 'choice' to indicate the communication direction in 5225 which a data node applies. If no 'choice' is indicated, a data 5226 node can appear in both directions (i.e., from DOTS clients to 5227 DOTS servers and vice versa). 5229 * Remove 'config' clauses. Note that 'config' statements will be 5230 ignored (if present) anyway according to Section 4 of 5231 [RFC8791]. This supersedes the references to the use of 'ro' 5232 and 'rw' which are now covered by 'choice' above. 5234 * Remove 'cuid', 'cdid', and 'sid' data nodes from the structure 5235 because these data nodes are included as Uri-Path options, not 5236 within the message body. 5238 * Remove the list keys for the mitigation scope message type 5239 (i.e., 'cuid' and 'mid'). 'mid' is not indicated as a key 5240 because it is included as Uri-Path option for requests and in 5241 the message body for responses. Note that Section 4 of 5242 [RFC8791] specifies that a list does not require to have a key 5243 statement defined. 5245 o Add a new section with a summary of the error code responses that 5246 can be returned by a DOTS server (Section 9). 5248 o Update the IANA section to allocate a new range for comprehension- 5249 optional attributes (Section 10.6.1.1). This modification is 5250 motivated by the need to allow for compact DOTS signal messages 5251 that include a long list of comprehension-optional attributes, 5252 e.g., DOTS telemetry messages [I-D.ietf-dots-telemetry]. 5254 These modifications are made with the constraint to avoid changes to 5255 the mapping table defined in Table 5 (Section 6). A DOTS signal 5256 channel attribute that may be present in both requests and responses 5257 will thus have the same CBOR key value and CBOR major type. 5259 Appendix B. CUID Generation 5261 The document recommends the use of SPKI to generate the 'cuid'. This 5262 design choice is motivated by the following reasons: 5264 o SPKI is globally unique. 5266 o It is deterministic. 5268 o It allows the avoidance of extra cycles that may be induced by 5269 'cuid' collision. 5271 o DOTS clients do not need to store the 'cuid' in a persistent 5272 storage. 5274 o It allows the detection of compromised DOTS clients that do not 5275 adhere to the 'cuid' generation algorithm. 5277 Appendix C. Acknowledgements 5279 Many thanks to Martin Bjoerklund for the suggestion to use RFC8791. 5281 C.1. Acknowledgements from RFC8782 5283 Thanks to Christian Jacquenet, Roland Dobbins, Roman Danyliw, Michael 5284 Richardson, Ehud Doron, Kaname Nishizuka, Dave Dolson, Liang Xia, 5285 Gilbert Clark, Xialiang Frank, Jim Schaad, Klaus Hartke, Nesredien 5286 Suleiman, Stephen Farrell, and Yoshifumi Nishida for the discussion 5287 and comments. 5289 The authors would like to give special thanks to Kaname Nishizuka and 5290 Jon Shallow for their efforts in implementing the protocol and 5291 performing interop testing at IETF Hackathons. 5293 Thanks to the core WG for the recommendations on Hop-Limit and 5294 redirect signaling. 5296 Special thanks to Benjamin Kaduk for the detailed AD review. 5298 Thanks to Alexey Melnikov, Adam Roach, Suresh Krishnan, Mirja 5299 Kuehlewind, and Alissa Cooper for the review. 5301 Thanks to Carsten Bormann for his review of the DOTS heartbeat 5302 mechanism. 5304 Appendix D. Contributors 5306 D.1. Authors of RFC8782 5308 The authors of RFC8782 are listed below: 5310 Tirumaleswar Reddy.K (editor) 5311 McAfee, Inc. 5312 Embassy Golf Link Business Park 5313 Bangalore 560071 5314 Karnataka 5315 India 5317 Email: kondtir@gmail.com 5319 Mohamed Boucadair (editor) 5320 Orange 5321 35000 Rennes 5322 France 5324 Email: mohamed.boucadair@orange.com 5326 Prashanth Patil 5327 Cisco Systems, Inc. 5329 Email: praspati@cisco.com 5331 Andrew Mortensen 5332 Arbor Networks, Inc. 5333 2727 S. State Street 5334 Ann Arbor, MI 48104 5335 United States of America 5337 Email: andrew@moretension.com 5339 Nik Teague 5340 Iron Mountain Data Centers 5341 United Kingdom 5343 Email: nteague@ironmountain.co.uk 5345 D.2. Contributors to RFC8782 5347 The following individuals have contributed to RFC8782: 5349 Jon Shallow 5350 NCC Group 5352 Email: jon.shallow@nccgroup.trust 5354 Mike Geller 5355 Cisco Systems, Inc. 5356 FL 33309 5357 United States of America 5359 Email: mgeller@cisco.com 5361 Robert Moskowitz 5362 HTT Consulting 5363 Oak Park, MI 42837 5364 United States of America 5366 Email: rgm@htt-consult.com 5368 Authors' Addresses 5370 Mohamed Boucadair (editor) 5371 Orange 5372 Rennes 35000 5373 France 5375 Email: mohamed.boucadair@orange.com 5377 Jon Shallow 5378 United Kingdom 5380 Email: supjps-ietf@jpshallow.com 5382 Tirumaleswar Reddy.K 5383 McAfee, Inc. 5384 Embassy Golf Link Business Park 5385 Bangalore, Karnataka 560071 5386 India 5388 Email: kondtir@gmail.com