idnits 2.17.00 (12 Aug 2021) /tmp/idnits47648/draft-ietf-dots-signal-channel-30.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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFCXXXX]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 2437 has weird spacing: '...er-port ine...' -- The document date (March 5, 2019) is 1172 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 4051, but not defined ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Downref: Normative reference to an Informational RFC: RFC 7918 == Outdated reference: A later version (-11) exists of draft-ietf-core-comi-04 == Outdated reference: draft-ietf-core-hop-limit has been published as RFC 8768 == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-07 == Outdated reference: draft-ietf-dots-architecture has been published as RFC 8811 == Outdated reference: draft-ietf-dots-data-channel has been published as RFC 8783 == Outdated reference: draft-ietf-dots-requirements has been published as RFC 8612 == Outdated reference: draft-ietf-dots-use-cases has been published as RFC 8903 == Outdated reference: draft-ietf-tls-dtls13 has been published as RFC 9147 -- Obsolete informational reference (is this intentional?): RFC 5389 (Obsoleted by RFC 8489) Summary: 6 errors (**), 0 flaws (~~), 11 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 DOTS T. Reddy, Ed. 3 Internet-Draft McAfee 4 Intended status: Standards Track M. Boucadair, Ed. 5 Expires: September 6, 2019 Orange 6 P. Patil 7 Cisco 8 A. Mortensen 9 Arbor Networks, Inc. 10 N. Teague 11 Verisign, Inc. 12 March 5, 2019 14 Distributed Denial-of-Service Open Threat Signaling (DOTS) Signal 15 Channel Specification 16 draft-ietf-dots-signal-channel-30 18 Abstract 20 This document specifies the DOTS signal channel, a protocol for 21 signaling the need for protection against Distributed Denial-of- 22 Service (DDoS) attacks to a server capable of enabling network 23 traffic mitigation on behalf of the requesting client. 25 A companion document defines the DOTS data channel, a separate 26 reliable communication layer for DOTS management and configuration 27 purposes. 29 Editorial Note (To be removed by RFC Editor) 31 Please update these statements within the document with the RFC 32 number to be assigned to this document: 34 o "This version of this YANG module is part of RFC XXXX;" 36 o "RFC XXXX: Distributed Denial-of-Service Open Threat Signaling 37 (DOTS) Signal Channel Specification"; 39 o "| [RFCXXXX] |" 41 o reference: RFC XXXX 43 Please update this statement with the RFC number to be assigned to 44 the following documents: 46 o "RFC YYYY: Distributed Denial-of-Service Open Threat Signaling 47 (DOTS) Data Channel Specification (used to be I-D.ietf-dots-data- 48 channel) 50 Please update TBD/TBD1/TBD2 statements with the assignments made by 51 IANA to DOTS Signal Channel Protocol. 53 Also, please update the "revision" date of the YANG modules. 55 Status of This Memo 57 This Internet-Draft is submitted in full conformance with the 58 provisions of BCP 78 and BCP 79. 60 Internet-Drafts are working documents of the Internet Engineering 61 Task Force (IETF). Note that other groups may also distribute 62 working documents as Internet-Drafts. The list of current Internet- 63 Drafts is at https://datatracker.ietf.org/drafts/current/. 65 Internet-Drafts are draft documents valid for a maximum of six months 66 and may be updated, replaced, or obsoleted by other documents at any 67 time. It is inappropriate to use Internet-Drafts as reference 68 material or to cite them other than as "work in progress." 70 This Internet-Draft will expire on September 6, 2019. 72 Copyright Notice 74 Copyright (c) 2019 IETF Trust and the persons identified as the 75 document authors. All rights reserved. 77 This document is subject to BCP 78 and the IETF Trust's Legal 78 Provisions Relating to IETF Documents 79 (https://trustee.ietf.org/license-info) in effect on the date of 80 publication of this document. Please review these documents 81 carefully, as they describe your rights and restrictions with respect 82 to this document. Code Components extracted from this document must 83 include Simplified BSD License text as described in Section 4.e of 84 the Trust Legal Provisions and are provided without warranty as 85 described in the Simplified BSD License. 87 Table of Contents 89 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 90 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 91 3. Design Overview . . . . . . . . . . . . . . . . . . . . . . . 6 92 4. DOTS Signal Channel: Messages & Behaviors . . . . . . . . . . 9 93 4.1. DOTS Server(s) Discovery . . . . . . . . . . . . . . . . 9 94 4.2. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . 9 95 4.3. Happy Eyeballs for DOTS Signal Channel . . . . . . . . . 9 96 4.4. DOTS Mitigation Methods . . . . . . . . . . . . . . . . . 11 97 4.4.1. Request Mitigation . . . . . . . . . . . . . . . . . 12 98 4.4.2. Retrieve Information Related to a Mitigation . . . . 26 99 4.4.2.1. DOTS Servers Sending Mitigation Status . . . . . 31 100 4.4.2.2. DOTS Clients Polling for Mitigation Status . . . 34 101 4.4.3. Efficacy Update from DOTS Clients . . . . . . . . . . 35 102 4.4.4. Withdraw a Mitigation . . . . . . . . . . . . . . . . 37 103 4.5. DOTS Signal Channel Session Configuration . . . . . . . . 38 104 4.5.1. Discover Configuration Parameters . . . . . . . . . . 40 105 4.5.2. Convey DOTS Signal Channel Session Configuration . . 44 106 4.5.3. Configuration Freshness and Notifications . . . . . . 49 107 4.5.4. Delete DOTS Signal Channel Session Configuration . . 50 108 4.6. Redirected Signaling . . . . . . . . . . . . . . . . . . 51 109 4.7. Heartbeat Mechanism . . . . . . . . . . . . . . . . . . . 53 110 5. DOTS Signal Channel YANG Modules . . . . . . . . . . . . . . 54 111 5.1. Tree Structure . . . . . . . . . . . . . . . . . . . . . 54 112 5.2. IANA DOTS Signal Channel YANG Module . . . . . . . . . . 56 113 5.3. IETF DOTS Signal Channel YANG Module . . . . . . . . . . 60 114 6. YANG/JSON Mapping Parameters to CBOR . . . . . . . . . . . . 70 115 7. (D)TLS Protocol Profile and Performance Considerations . . . 73 116 7.1. (D)TLS Protocol Profile . . . . . . . . . . . . . . . . . 73 117 7.2. (D)TLS 1.3 Considerations . . . . . . . . . . . . . . . . 74 118 7.3. DTLS MTU and Fragmentation . . . . . . . . . . . . . . . 76 119 8. Mutual Authentication of DOTS Agents & Authorization of DOTS 120 Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 121 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 78 122 9.1. DOTS Signal Channel UDP and TCP Port Number . . . . . . . 78 123 9.2. Well-Known 'dots' URI . . . . . . . . . . . . . . . . . . 78 124 9.3. Media Type Registration . . . . . . . . . . . . . . . . . 79 125 9.4. CoAP Content-Formats Registration . . . . . . . . . . . . 79 126 9.5. CBOR Tag Registration . . . . . . . . . . . . . . . . . . 79 127 9.6. DOTS Signal Channel Protocol Registry . . . . . . . . . . 80 128 9.6.1. DOTS Signal Channel CBOR Key Values Sub-Registry . . 80 129 9.6.1.1. Registration Template . . . . . . . . . . . . . . 80 130 9.6.1.2. Initial Sub-Registry Content . . . . . . . . . . 82 131 9.6.2. Status Codes Sub-Registry . . . . . . . . . . . . . . 83 132 9.6.3. Conflict Status Codes Sub-Registry . . . . . . . . . 85 133 9.6.4. Conflict Cause Codes Sub-Registry . . . . . . . . . . 87 134 9.6.5. Attack Status Codes Sub-Registry . . . . . . . . . . 87 135 9.7. DOTS Signal Channel YANG Modules . . . . . . . . . . . . 88 136 10. Security Considerations . . . . . . . . . . . . . . . . . . . 89 137 11. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 91 138 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 91 139 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 91 140 13.1. Normative References . . . . . . . . . . . . . . . . . . 91 141 13.2. Informative References . . . . . . . . . . . . . . . . . 94 142 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 98 144 1. Introduction 146 A distributed denial-of-service (DDoS) attack is a distributed 147 attempt to make machines or network resources unavailable to their 148 intended users. In most cases, sufficient scale for an effective 149 attack can be achieved by compromising enough end-hosts and using 150 those infected hosts to perpetrate and amplify the attack. The 151 victim in this attack can be an application server, a host, a router, 152 a firewall, or an entire network. 154 Network applications have finite resources like CPU cycles, the 155 number of processes or threads they can create and use, the maximum 156 number of simultaneous connections they can handle, the limited 157 resources of the control plane, etc. When processing network 158 traffic, such applications are supposed to use these resources to 159 provide the intended functionality in the most efficient manner. 160 However, a DDoS attacker may be able to prevent an application from 161 performing its intended task by making the application exhaust its 162 finite resources. 164 A TCP DDoS SYN-flood [RFC4987], for example, is a memory-exhausting 165 attack while an ACK-flood is a CPU-exhausting attack. Attacks on the 166 link are carried out by sending enough traffic so that the link 167 becomes congested, thereby likely causing packet loss for legitimate 168 traffic. Stateful firewalls can also be attacked by sending traffic 169 that causes the firewall to maintain an excessive number of states 170 that may jeopardize the firewall's operation overall, besides likely 171 performance impacts. The firewall then runs out of memory, and can 172 no longer instantiate the states required to process legitimate 173 flows. Other possible DDoS attacks are discussed in [RFC4732]. 175 In many cases, it may not be possible for network administrators to 176 determine the cause(s) of an attack. They may instead just realize 177 that certain resources seem to be under attack. This document 178 defines a lightweight protocol that allows a DOTS client to request 179 mitigation from one or more DOTS servers for protection against 180 detected, suspected, or anticipated attacks. This protocol enables 181 cooperation between DOTS agents to permit a highly-automated network 182 defense that is robust, reliable, and secure. Note that "secure" 183 means the support of the features defined in Section 2.4 of 184 [I-D.ietf-dots-requirements]. 186 An example of a network diagram that illustrates a deployment of DOTS 187 agents is shown in Figure 1. In this example, a DOTS server is 188 operating on the access network. A DOTS client is located on the LAN 189 (Local Area Network), while a DOTS gateway is embedded in the CPE 190 (Customer Premises Equipment). 192 Network 193 Resource CPE router Access network __________ 194 +-----------+ +--------------+ +-------------+ / \ 195 | |___| |____| |___ | Internet | 196 |DOTS client| | DOTS gateway | | DOTS server | | | 197 | | | | | | | | 198 +-----------+ +--------------+ +-------------+ \__________/ 200 Figure 1: Sample DOTS Deployment (1) 202 DOTS servers can also be reachable over the Internet, as depicted in 203 Figure 2. 205 Network DDoS mitigation 206 Resource CPE router __________ service 207 +-----------+ +-------------+ / \ +-------------+ 208 | |___| |____| |___ | | 209 |DOTS client| |DOTS gateway | | Internet | | DOTS server | 210 | | | | | | | | 211 +-----------+ +-------------+ \__________/ +-------------+ 213 Figure 2: Sample DOTS Deployment (2) 215 In typical deployments, the DOTS client belongs to a different 216 administrative domain than the DOTS server. For example, the DOTS 217 client is embedded in a firewall protecting services owned and 218 operated by a customer, while the DOTS server is owned and operated 219 by a different administrative entity (service provider, typically) 220 providing DDoS mitigation services. The latter might or might not 221 provide connectivity services to the network hosting the DOTS client. 223 The DOTS server may (not) be co-located with the DOTS mitigator. In 224 typical deployments, the DOTS server belongs to the same 225 administrative domain as the mitigator. The DOTS client can 226 communicate directly with a DOTS server or indirectly via a DOTS 227 gateway. 229 The document adheres to the DOTS architecture 230 [I-D.ietf-dots-architecture]. The requirements for DOTS signal 231 channel protocol are documented in [I-D.ietf-dots-requirements]. 232 This document satisfies all the use cases discussed in 233 [I-D.ietf-dots-use-cases]. 235 This document focuses on the DOTS signal channel. This is a 236 companion document of the DOTS data channel specification 237 [I-D.ietf-dots-data-channel] that defines a configuration and a bulk 238 data exchange mechanism supporting the DOTS signal channel. 240 2. Terminology 242 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 243 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 244 "OPTIONAL" in this document are to be interpreted as described in BCP 245 14 [RFC2119][RFC8174] when, and only when, they appear in all 246 capitals, as shown here. 248 (D)TLS is used for statements that apply to both Transport Layer 249 Security [RFC5246][RFC8446] and Datagram Transport Layer Security 250 [RFC6347]. Specific terms are used for any statement that applies to 251 either protocol alone. 253 The reader should be familiar with the terms defined in 254 [I-D.ietf-dots-requirements]. 256 The meaning of the symbols in YANG tree diagrams is defined in 257 [RFC8340]. 259 3. Design Overview 261 The DOTS signal channel is built on top of the Constrained 262 Application Protocol (CoAP) [RFC7252], a lightweight protocol 263 originally designed for constrained devices and networks. The many 264 features of CoAP (expectation of packet loss, support for 265 asynchronous Non-confirmable messaging, congestion control, small 266 message overhead limiting the need for fragmentation, use of minimal 267 resources, and support for (D)TLS) makes it a good candidate to build 268 the DOTS signaling mechanism from. 270 The DOTS signal channel is layered on existing standards (Figure 3). 272 +---------------------+ 273 | DOTS Signal Channel | 274 +---------------------+ 275 | CoAP | 276 +----------+----------+ 277 | TLS | DTLS | 278 +----------+----------+ 279 | TCP | UDP | 280 +----------+----------+ 281 | IP | 282 +---------------------+ 284 Figure 3: Abstract Layering of DOTS Signal Channel over CoAP over 285 (D)TLS 287 By default, a DOTS signal channel MUST run over port number TBD as 288 defined in Section 9.1, for both UDP and TCP, unless the DOTS server 289 has a mutual agreement with its DOTS clients to use a different port 290 number. DOTS clients MAY alternatively support means to dynamically 291 discover the ports used by their DOTS servers (e.g., 292 [I-D.boucadair-dots-server-discovery]). In order to use a distinct 293 port number (as opposed to TBD), DOTS clients and servers SHOULD 294 support a configurable parameter to supply the port number to use. 295 The rationale for not using the default port number 5684 ((D)TLS 296 CoAP) is to allow for differentiated behaviors in environments where 297 both a DOTS gateway and an IoT gateway (e.g., Figure 3 of [RFC7452]) 298 are present. 300 The signal channel uses the "coaps" URI scheme defined in Section 6 301 of [RFC7252] and the "coaps+tcp" URI scheme defined in Section 8.2 of 302 [RFC8323] to identify DOTS server resources accessible using CoAP 303 over UDP secured with DTLS and CoAP over TCP secured with TLS, 304 respectively. 306 The signal channel is initiated by the DOTS client (Section 4.4). 307 Once the signal channel is established, the DOTS agents periodically 308 send heartbeats to keep the channel active (Section 4.7). At any 309 time, the DOTS client may send a mitigation request message to a DOTS 310 server over the active channel. While mitigation is active (because 311 of the higher likelihood of packet loss during a DDoS attack), the 312 DOTS server periodically sends status messages to the client, 313 including basic mitigation feedback details. Mitigation remains 314 active until the DOTS client explicitly terminates mitigation, or the 315 mitigation lifetime expires. 317 DOTS signaling can happen with DTLS over UDP and TLS over TCP. 318 Likewise, DOTS requests may be sent using IPv4 or IPv6 transfer 319 capabilities. A Happy Eyeballs procedure for DOTS signal channel is 320 specified in Section 4.3. 322 Messages exchanged between DOTS agents are serialized using Concise 323 Binary Object Representation (CBOR) [RFC7049], a binary encoding 324 scheme designed for small code and message size. CBOR-encoded 325 payloads are used to carry signal channel-specific payload messages 326 which convey request parameters and response information such as 327 errors. In order to allow reusing data models across protocols, 328 [RFC7951] specifies the JavaScript Object Notation (JSON) encoding of 329 YANG-modeled data. A similar effort for CBOR is defined in 330 [I-D.ietf-core-yang-cbor]. 332 DOTS agents primarily determine that a CBOR data structure is a DOTS 333 signal channel object from the application context, such as from the 334 port number assigned to the DOTS signal channel. The other method 335 DOTS agents use to indicate that a CBOR data structure is a DOTS 336 signal channel object is the use of the "application/dots+cbor" 337 content type (Section 9.3). 339 This document specifies a YANG module for representing DOTS 340 mitigation scopes, DOTS signal channel session configuration data, 341 and DOTS redirected signalling (Section 5). Representing these data 342 as CBOR data can either follow the rules in [I-D.ietf-core-yang-cbor] 343 or those in [RFC7951] combined with JSON/CBOR conversion rules in 344 [RFC7049]; both approaches produce a valid encoding. All parameters 345 in the payload of the DOTS signal channel are mapped to CBOR types as 346 specified in Section 6. 348 In order to prevent fragmentation, DOTS agents must follow the 349 recommendations documented in Section 4.6 of [RFC7252]. Refer to 350 Section 7.3 for more details. 352 DOTS agents MUST support GET, PUT, and DELETE CoAP methods. The 353 payload included in CoAP responses with 2.xx Response Codes MUST be 354 of content type "application/dots+cbor". CoAP responses with 4.xx 355 and 5.xx error Response Codes MUST include a diagnostic payload 356 (Section 5.5.2 of [RFC7252]). The Diagnostic Payload may contain 357 additional information to aid troubleshooting. 359 In deployments where multiple DOTS clients are enabled in a network 360 (owned and operated by the same entity), the DOTS server may detect 361 conflicting mitigation requests from these clients. This document 362 does not aim to specify a comprehensive list of conditions under 363 which a DOTS server will characterize two mitigation requests from 364 distinct DOTS clients as conflicting, nor recommend a DOTS server 365 behavior for processing conflicting mitigation requests. Those 366 considerations are implementation- and deployment-specific. 367 Nevertheless, the document specifies the mechanisms to notify DOTS 368 clients when conflicts occur, including the conflict cause 369 (Section 4.4). 371 In deployments where one or more translators (e.g., Traditional NAT 372 [RFC3022], CGN [RFC6888], NAT64 [RFC6146], NPTv6 [RFC6296]) are 373 enabled between the client's network and the DOTS server, DOTS signal 374 channel messages forwarded to a DOTS server MUST NOT include internal 375 IP addresses/prefixes and/or port numbers; external addresses/ 376 prefixes and/or port numbers as assigned by the translator MUST be 377 used instead. This document does not make any recommendation about 378 possible translator discovery mechanisms. The following are some 379 (non-exhaustive) deployment examples that may be considered: 381 o Port Control Protocol (PCP) [RFC6887] or Session Traversal 382 Utilities for NAT (STUN) [RFC5389] may be used to retrieve the 383 external addresses/prefixes and/or port numbers. Information 384 retrieved by means of PCP or STUN will be used to feed the DOTS 385 signal channel messages that will be sent to a DOTS server. 387 o A DOTS gateway may be co-located with the translator. The DOTS 388 gateway will need to update the DOTS messages, based upon the 389 local translator's binding table. 391 4. DOTS Signal Channel: Messages & Behaviors 393 4.1. DOTS Server(s) Discovery 395 This document assumes that DOTS clients are provisioned with the 396 reachability information of their DOTS server(s) using any of a 397 variety of means (e.g., local configuration, or dynamic means such as 398 DHCP). The description of such means is out of scope of this 399 document. 401 Likewise, it is out of scope of this document to specify the behavior 402 to be followed by a DOTS client to send DOTS requests when multiple 403 DOTS servers are provisioned (e.g., contact all DOTS servers, select 404 one DOTS server among the list). 406 4.2. CoAP URIs 408 The DOTS server MUST support the use of the path-prefix of "/.well- 409 known/" as defined in [RFC5785] and the registered name of "dots". 410 Each DOTS operation is indicated by a path-suffix that indicates the 411 intended operation. The operation path (Table 1) is appended to the 412 path-prefix to form the URI used with a CoAP request to perform the 413 desired DOTS operation. 415 +-----------------------+----------------+-------------+ 416 | Operation | Operation Path | Details | 417 +-----------------------+----------------+-------------+ 418 | Mitigation | /mitigate | Section 4.4 | 419 +-----------------------+----------------+-------------+ 420 | Session configuration | /config | Section 4.5 | 421 +-----------------------+----------------+-------------+ 423 Table 1: Operations and their Corresponding URIs 425 4.3. Happy Eyeballs for DOTS Signal Channel 427 [I-D.ietf-dots-requirements] mentions that DOTS agents will have to 428 support both connectionless and connection-oriented protocols. As 429 such, the DOTS signal channel is designed to operate with DTLS over 430 UDP and TLS over TCP. Further, a DOTS client may acquire a list of 431 IPv4 and IPv6 addresses (Section 4.1), each of which can be used to 432 contact the DOTS server using UDP and TCP. The following specifies 433 the procedure to follow to select the address family and the 434 transport protocol for sending DOTS signal channel messages. 436 Such procedure is needed to avoid experiencing long connection 437 delays. For example, if an IPv4 path to reach a DOTS server is 438 functional, but the DOTS server's IPv6 path is non-functional, a 439 dual-stack DOTS client may experience a significant connection delay 440 compared to an IPv4-only DOTS client, in the same network conditions. 441 The other problem is that if a middlebox between the DOTS client and 442 DOTS server is configured to block UDP traffic, the DOTS client will 443 fail to establish a DTLS association with the DOTS server and, as a 444 consequence, will have to fall back to TLS over TCP, thereby 445 incurring significant connection delays. 447 To overcome these connection setup problems, the DOTS client attempts 448 to connect to its DOTS server(s) using both IPv6 and IPv4, and tries 449 both DTLS over UDP and TLS over TCP in a manner similar to the Happy 450 Eyeballs mechanism [RFC8305]. These connection attempts are 451 performed by the DOTS client when it initializes, or in general when 452 it has to select an address family and transport to contact its DOTS 453 server. The results of the Happy Eyeballs procedure are used by the 454 DOTS client for sending its subsequent messages to the DOTS server. 455 Note that the DOTS client after successfully establishing a 456 connection MUST cache information regarding the outcome of each 457 connection attempt for a specific time period, and it uses that 458 information to avoid thrashing the network with subsequent attempts. 460 The order of preference of the DOTS signal channel address family and 461 transport protocol (most preferred first) is: UDP over IPv6, UDP over 462 IPv4, TCP over IPv6, and finally TCP over IPv4. This order adheres 463 to the address preference order specified in [RFC6724] and the DOTS 464 signal channel preference which privileges the use of UDP over TCP 465 (to avoid TCP's head of line blocking). 467 In reference to Figure 4, the DOTS client sends two TCP SYNs and two 468 DTLS ClientHello messages at the same time over IPv6 and IPv4. In 469 this example, it is assumed that the IPv6 path is broken and UDP 470 traffic is dropped by a middlebox but has little impact to the DOTS 471 client because there is no long delay before using IPv4 and TCP. The 472 DOTS client periodically repeats the mechanism to discover whether 473 DOTS signal channel messages with DTLS over UDP becomes available 474 from the DOTS server, so the DOTS client can migrate the DOTS signal 475 channel from TCP to UDP. Such probing SHOULD NOT be done more 476 frequently than every 24 hours and MUST NOT be done more frequently 477 than every 5 minutes. 479 A single DOTS signal channel between DOTS agents can be used to 480 exchange multiple DOTS signal messages. To reduce DOTS client and 481 DOTS server workload, DOTS clients SHOULD re-use the (D)TLS session. 483 +-----------+ +-----------+ 484 |DOTS client| |DOTS server| 485 +-----------+ +-----------+ 486 | | 487 |--DTLS ClientHello, IPv6 ---->X | 488 |--TCP SYN, IPv6-------------->X | 489 |--DTLS ClientHello, IPv4 ---->X | 490 |--TCP SYN, IPv4--------------------------------------->| 491 |--DTLS ClientHello, IPv6 ---->X | 492 |--TCP SYN, IPv6-------------->X | 493 |<-TCP SYNACK-------------------------------------------| 494 |--DTLS ClientHello, IPv4 ---->X | 495 |--TCP ACK--------------------------------------------->| 496 |<------------Establish TLS Session-------------------->| 497 |----------------DOTS signal--------------------------->| 498 | | 500 Figure 4: DOTS Happy Eyeballs (Sample Flow) 502 4.4. DOTS Mitigation Methods 504 The following methods are used by a DOTS client to request, withdraw, 505 or retrieve the status of mitigation requests: 507 PUT: DOTS clients use the PUT method to request mitigation from a 508 DOTS server (Section 4.4.1). During active mitigation, DOTS 509 clients may use PUT requests to carry mitigation efficacy 510 updates to the DOTS server (Section 4.4.3). 512 GET: DOTS clients may use the GET method to subscribe to DOTS 513 server status messages, or to retrieve the list of its 514 mitigations maintained by a DOTS server (Section 4.4.2). 516 DELETE: DOTS clients use the DELETE method to withdraw a request for 517 mitigation from a DOTS server (Section 4.4.4). 519 Mitigation request and response messages are marked as Non- 520 confirmable messages (Section 2.2 of [RFC7252]). 522 DOTS agents SHOULD follow the data transmission guidelines discussed 523 in Section 3.1.3 of [RFC8085] and control transmission behavior by 524 not sending more than one UDP datagram per round-trip time (RTT) to 525 the peer DOTS agent on average. 527 Requests marked by the DOTS client as Non-confirmable messages are 528 sent at regular intervals until a response is received from the DOTS 529 server. If the DOTS client cannot maintain an RTT estimate, it 530 SHOULD NOT send more than one Non-confirmable request every 3 531 seconds, and SHOULD use an even less aggressive rate whenever 532 possible (case 2 in Section 3.1.3 of [RFC8085]). 534 JSON diagnostic notation is used to illustrate the various methods 535 defined in the following sub-sections. Also, the examples use the 536 Labels defined in Sections 9.6.2, 9.6.3, 9.6.4, and 9.6.5. 538 4.4.1. Request Mitigation 540 When a DOTS client requires mitigation for some reason, the DOTS 541 client uses the CoAP PUT method to send a mitigation request to its 542 DOTS server(s) (Figures 5 and 6). 544 If a DOTS client is entitled to solicit the DOTS service, the DOTS 545 server enables mitigation on behalf of the DOTS client by 546 communicating the DOTS client's request to a mitigator (which may be 547 colocated with the DOTS server) and relaying the feedback of the 548 thus-selected mitigator to the requesting DOTS client. 550 Header: PUT (Code=0.03) 551 Uri-Path: ".well-known" 552 Uri-Path: "dots" 553 Uri-Path: "mitigate" 554 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 555 Uri-Path: "mid=123" 556 Content-Format: "application/dots+cbor" 557 { 558 ... 559 } 561 Figure 5: PUT to Convey DOTS Mitigation Requests 563 The order of the Uri-Path options is important as it defines the CoAP 564 resource. In particular, 'mid' MUST follow 'cuid'. 566 The additional Uri-Path parameters to those defined in Section 4.2 567 are as follows: 569 cuid: Stands for Client Unique Identifier. A globally unique 570 identifier that is meant to prevent collisions among DOTS clients, 571 especially those from the same domain. It MUST be generated by 572 DOTS clients. 574 Implementations SHOULD set 'cuid' to the output of a cryptographic 575 hash algorithm whose input is the Distinguished Encoding Rules 576 (DER)-encoded Abstract Syntax Notation One (ASN.1) representation 577 of the Subject Public Key Info (SPKI) of the DOTS client X.509 578 certificate [RFC5280], the DOTS client raw public key [RFC7250], 579 or the "Pre-Shared Key (PSK) identity" used by the DOTS client in 580 the TLS ClientKeyExchange message. In this version of the 581 specification, the cryptographic hash algorithm used is SHA-256 582 [RFC6234]. The output of the cryptographic hash algorithm is 583 truncated to 16 bytes; truncation is done by stripping off the 584 final 16 bytes. The truncated output is base64url encoded. 586 The 'cuid' is intended to be stable when communicating with a 587 given DOTS server, i.e., the 'cuid' used by a DOTS client SHOULD 588 NOT change over time. Distinct 'cuid' values MAY be used by a 589 single DOTS client per DOTS server. 591 DOTS servers MUST return 4.09 (Conflict) error code to a DOTS peer 592 to notify that the 'cuid' is already in-use by another DOTS 593 client. Upon receipt of that error code, a new 'cuid' MUST be 594 generated by the DOTS peer (e.g., using [RFC4122]). 596 Client-domain DOTS gateways MUST handle 'cuid' collision directly 597 and it is RECOMMENDED that 'cuid' collision is handled directly by 598 server-domain DOTS gateways. 600 DOTS gateways MAY rewrite the 'cuid' used by peer DOTS clients. 601 Triggers for such rewriting are out of scope. 603 This is a mandatory Uri-Path parameter. 605 mid: Identifier for the mitigation request represented with an 606 integer. This identifier MUST be unique for each mitigation 607 request bound to the DOTS client, i.e., the 'mid' parameter value 608 in the mitigation request needs to be unique (per 'cuid' and DOTS 609 server) relative to the 'mid' parameter values of active 610 mitigation requests conveyed from the DOTS client to the DOTS 611 server. 613 In order to handle out-of-order delivery of mitigation requests, 614 'mid' values MUST increase monotonically. 616 If the 'mid' value has reached 3/4 of (2**32 - 1) (i.e., 617 3221225471) and no attack is detected, the DOTS client MUST reset 618 'mid' to 0 to handle 'mid' rollover. If the DOTS client maintains 619 mitigation requests with pre-configured scopes, it MUST re-create 620 them with the 'mid' restarting at 0. 622 This identifier MUST be generated by the DOTS client. 624 This is a mandatory Uri-Path parameter. 626 'cuid' and 'mid' MUST NOT appear in the PUT request message body 627 (Figure 6). 629 Content-Format: "application/dots+cbor" 630 { 631 "ietf-dots-signal-channel:mitigation-scope": { 632 "scope": [ 633 { 634 "target-prefix": [ 635 "string" 636 ], 637 "target-port-range": [ 638 { 639 "lower-port": number, 640 "upper-port": number 641 } 642 ], 643 "target-protocol": [ 644 number 645 ], 646 "target-fqdn": [ 647 "string" 648 ], 649 "target-uri": [ 650 "string" 651 ], 652 "alias-name": [ 653 "string" 654 ], 655 "lifetime": number, 656 "trigger-mitigation": true|false 657 } 658 ] 659 } 660 } 662 Figure 6: PUT to Convey DOTS Mitigation Requests (Message Body 663 Schema) 665 The parameters in the CBOR body (Figure 6) of the PUT request are 666 described below: 668 target-prefix: A list of prefixes identifying resources under 669 attack. Prefixes are represented using Classless Inter-Domain 670 Routing (CIDR) notation [RFC4632]. 671 As a reminder, the prefix length must be less than or equal to 32 672 (resp. 128) for IPv4 (resp. IPv6). 674 The prefix list MUST NOT include broadcast, loopback, or multicast 675 addresses. These addresses are considered as invalid values. In 676 addition, the DOTS server MUST validate that target prefixes are 677 within the scope of the DOTS client domain. Other validation 678 checks may be supported by DOTS servers. 680 This is an optional attribute. 682 target-port-range: A list of port numbers bound to resources under 683 attack. 685 A port range is defined by two bounds, a lower port number (lower- 686 port) and an upper port number (upper-port). When only 'lower- 687 port' is present, it represents a single port number. 689 For TCP, UDP, Stream Control Transmission Protocol (SCTP) 690 [RFC4960], or Datagram Congestion Control Protocol (DCCP) 691 [RFC4340], a range of ports can be, for example, 0-1023, 692 1024-65535, or 1024-49151. 694 This is an optional attribute. 696 target-protocol: A list of protocols involved in an attack. Values 697 are taken from the IANA protocol registry [proto_numbers]. 699 If 'target-protocol' is not specified, then the request applies to 700 any protocol. 702 This is an optional attribute. 704 target-fqdn: A list of Fully Qualified Domain Names (FQDNs) 705 identifying resources under attack [RFC8499]. 707 How a name is passed to an underlying name resolution library is 708 implementation- and deployment-specific. Nevertheless, once the 709 name is resolved into one or multiple IP addresses, DOTS servers 710 MUST apply the same validation checks as those for 'target- 711 prefix'. 713 The use of FQDNs may be suboptimal because: 715 * It induces both an extra load and increased delays on the DOTS 716 server to handle and manage DNS resolution requests. 718 * It does not guarantee that the DOTS server will resolve a name 719 to the same IP addresses that the DOTS client does. 721 This is an optional attribute. 723 target-uri: A list of Uniform Resource Identifiers (URIs) [RFC3986] 724 identifying resources under attack. 726 The same validation checks used for 'target-fqdn' MUST be followed 727 by DOTS servers to validate a target URI. 729 This is an optional attribute. 731 alias-name: A list of aliases of resources for which the mitigation 732 is requested. Aliases can be created using the DOTS data channel 733 (Section 6.1 of [I-D.ietf-dots-data-channel]), direct 734 configuration, or other means. 736 An alias is used in subsequent signal channel exchanges to refer 737 more efficiently to the resources under attack. 739 This is an optional attribute. 741 lifetime: Lifetime of the mitigation request in seconds. The 742 RECOMMENDED lifetime of a mitigation request is 3600 seconds -- 743 this value was chosen to be long enough so that refreshing is not 744 typically a burden on the DOTS client, while still making the 745 request expire in a timely manner when the client has unexpectedly 746 quit. DOTS clients MUST include this parameter in their 747 mitigation requests. Upon the expiry of this lifetime, and if the 748 request is not refreshed, the mitigation request is removed. The 749 request can be refreshed by sending the same request again. 751 A lifetime of '0' in a mitigation request is an invalid value. 753 A lifetime of negative one (-1) indicates indefinite lifetime for 754 the mitigation request. The DOTS server MAY refuse indefinite 755 lifetime, for policy reasons; the granted lifetime value is 756 returned in the response. DOTS clients MUST be prepared to not be 757 granted mitigations with indefinite lifetimes. 759 The DOTS server MUST always indicate the actual lifetime in the 760 response and the remaining lifetime in status messages sent to the 761 DOTS client. 763 This is a mandatory attribute. 765 trigger-mitigation: If the parameter value is set to 'false', DDoS 766 mitigation will not be triggered for the mitigation request unless 767 the DOTS signal channel session is lost. 769 If the DOTS client ceases to respond to heartbeat messages, the 770 DOTS server can detect that the DOTS signal channel session is 771 lost. 773 The default value of the parameter is 'true' (that is, the 774 mitigation starts immediately). If 'trigger-mitigation' is not 775 present in a request, this is equivalent to receiving a request 776 with 'trigger-mitigation' set to 'true'. 778 This is an optional attribute. 780 In deployments where server-domain DOTS gateways are enabled, 781 identity information about the origin source client domain SHOULD be 782 propagated to the DOTS server. That information is meant to assist 783 the DOTS server to enforce some policies such as grouping DOTS 784 clients that belong to the same DOTS domain, limiting the number of 785 DOTS requests, and identifying the mitigation scope. These policies 786 can be enforced per-client, per-client domain, or both. Also, the 787 identity information may be used for auditing and debugging purposes. 789 Figure 7 shows an example of a request relayed by a server-domain 790 DOTS gateway. 792 Header: PUT (Code=0.03) 793 Uri-Path: ".well-known" 794 Uri-Path: "dots" 795 Uri-Path: "mitigate" 796 Uri-Path: "cdid=7eeaf349529eb55ed50113" 797 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 798 Uri-Path: "mid=123" 799 Content-Format: "application/dots+cbor" 800 { 801 ... 802 } 804 Figure 7: PUT for DOTS Mitigation Request as Relayed by a DOTS 805 Gateway 807 A server-domain DOTS gateway SHOULD add the following Uri-Path 808 parameter: 810 cdid: Stands for Client Domain Identifier. The 'cdid' is conveyed 811 by a server-domain DOTS gateway to propagate the source domain 812 identity from the gateway's client-facing-side to the gateway's 813 server-facing-side, and from the gateway's server-facing-side to 814 the DOTS server. 'cdid' may be used by the final DOTS server for 815 policy enforcement purposes (e.g., enforce a quota on filtering 816 rules). These policies are deployment-specific. 818 Server-domain DOTS gateways SHOULD support a configuration option 819 to instruct whether 'cdid' parameter is to be inserted. 821 In order to accommodate deployments that require enforcing per- 822 client policies, per-client domain policies, or a combination 823 thereof, server-domain DOTS gateways instructed to insert the 824 'cdid' parameter MUST supply the SPKI hash of the DOTS client 825 X.509 certificate, the DOTS client raw public key, or the hash of 826 the "PSK identity" in the 'cdid', following the same rules for 827 generating the hash conveyed in 'cuid', which is then used by the 828 ultimate DOTS server to determine the corresponding client's 829 domain. The 'cdid' generated by a server-domain gateway is likely 830 to be the same as the 'cuid' except if the DOTS message was 831 relayed by a client-domain DOTS gateway or the 'cuid' was 832 generated from a rogue DOTS client. 834 If a DOTS client is provisioned, for example, with distinct 835 certificates as a function of the peer server-domain DOTS gateway, 836 distinct 'cdid' values may be supplied by a server-domain DOTS 837 gateway. The ultimate DOTS server MUST treat those 'cdid' values 838 as equivalent. 840 The 'cdid' attribute MUST NOT be generated and included by DOTS 841 clients. 843 DOTS servers MUST ignore 'cdid' attributes that are directly 844 supplied by source DOTS clients or client-domain DOTS gateways. 845 This implies that first server-domain DOTS gateways MUST strip 846 'cdid' attributes supplied by DOTS clients. DOTS servers SHOULD 847 support a configuration parameter to identify DOTS gateways that 848 are trusted to supply 'cdid' attributes. 850 Only single-valued 'cdid' are defined in this document. 852 This is an optional Uri-Path. When present, 'cdid' MUST be 853 positioned before 'cuid'. 855 A DOTS gateway MAY add the CoAP Hop-Limit Option 856 [I-D.ietf-core-hop-limit]. 858 Because of the complexity to handle partial failure cases, this 859 specification does not allow for including multiple mitigation 860 requests in the same PUT request. Concretely, a DOTS client MUST NOT 861 include multiple entries in the 'scope' array of the same PUT 862 request. 864 FQDN and URI mitigation scopes may be thought of as a form of scope 865 alias, in which the addresses associated with the domain name or URI 866 (as resolved by the DOTS server) represent the full scope of the 867 mitigation. 869 In the PUT request at least one of the attributes 'target-prefix', 870 'target-fqdn','target-uri', or 'alias-name' MUST be present. 872 Attributes and Uri-Path parameters with empty values MUST NOT be 873 present in a request and render the entire request invalid. 875 Figure 8 shows a PUT request example to signal that TCP port numbers 876 80, 8080, and 443 used by 2001:db8:6401::1 and 2001:db8:6401::2 877 servers are under attack (illustrated in JSON diagnostic notation). 878 The presence of 'cdid' indicates that a server-domain DOTS gateway 879 has modified the initial PUT request sent by the DOTS client. Note 880 that 'cdid' MUST NOT appear in the PUT request message body. 882 Header: PUT (Code=0.03) 883 Uri-Path: ".well-known" 884 Uri-Path: "dots" 885 Uri-Path: "mitigate" 886 Uri-Path: "cdid=7eeaf349529eb55ed50113" 887 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 888 Uri-Path: "mid=123" 889 Content-Format: "application/dots+cbor" 890 { 891 "ietf-dots-signal-channel:mitigation-scope": { 892 "scope": [ 893 { 894 "target-prefix": [ 895 "2001:db8:6401::1/128", 896 "2001:db8:6401::2/128" 897 ], 898 "target-port-range": [ 899 { 900 "lower-port": 80 901 }, 902 { 903 "lower-port": 443 904 }, 905 { 906 "lower-port": 8080 907 } 908 ], 909 "target-protocol": [ 910 6 911 ], 912 "lifetime": 3600 913 } 914 ] 915 } 916 } 918 Figure 8: PUT for DOTS Mitigation Request (An Example) 920 The corresponding CBOR encoding format for the payload is shown in 921 Figure 9. 923 A1 # map(1) 924 01 # unsigned(1) 925 A1 # map(1) 926 02 # unsigned(2) 927 81 # array(1) 928 A3 # map(3) 929 06 # unsigned(6) 930 82 # array(2) 931 74 # text(20) 932 323030313A6462383A363430313A3A312F313238 933 74 # text(20) 934 323030313A6462383A363430313A3A322F313238 935 07 # unsigned(7) 936 83 # array(3) 937 A1 # map(1) 938 08 # unsigned(8) 939 18 50 # unsigned(80) 940 A1 # map(1) 941 08 # unsigned(8) 942 19 01BB # unsigned(443) 943 A1 # map(1) 944 08 # unsigned(8) 945 19 1F90 # unsigned(8080) 946 0A # unsigned(10) 947 81 # array(1) 948 06 # unsigned(6) 949 0E # unsigned(14) 950 19 0E10 # unsigned(3600) 952 Figure 9: PUT for DOTS Mitigation Request (CBOR) 954 In both DOTS signal and data channel sessions, the DOTS client MUST 955 authenticate itself to the DOTS server (Section 8). The DOTS server 956 MAY use the algorithm presented in Section 7 of [RFC7589] to derive 957 the DOTS client identity or username from the client certificate. 958 The DOTS client identity allows the DOTS server to accept mitigation 959 requests with scopes that the DOTS client is authorized to manage. 961 The DOTS server couples the DOTS signal and data channel sessions 962 using the DOTS client identity and optionally the 'cdid' parameter 963 value, so the DOTS server can validate whether the aliases conveyed 964 in the mitigation request were indeed created by the same DOTS client 965 using the DOTS data channel session. If the aliases were not created 966 by the DOTS client, the DOTS server MUST return 4.00 (Bad Request) in 967 the response. 969 The DOTS server couples the DOTS signal channel sessions using the 970 DOTS client identity and optionally the 'cdid' parameter value, and 971 the DOTS server uses 'mid' and 'cuid' Uri-Path parameter values to 972 detect duplicate mitigation requests. If the mitigation request 973 contains the 'alias-name' and other parameters identifying the target 974 resources (such as 'target-prefix', 'target-port-range', 'target- 975 fqdn', or 'target-uri'), the DOTS server appends the parameter values 976 in 'alias-name' with the corresponding parameter values in 'target- 977 prefix', 'target-port-range', 'target-fqdn', or 'target-uri'. 979 The DOTS server indicates the result of processing the PUT request 980 using CoAP response codes. CoAP 2.xx codes are success. CoAP 4.xx 981 codes are some sort of invalid requests (client errors). COAP 5.xx 982 codes are returned if the DOTS server is in an error state or is 983 currently unavailable to provide mitigation in response to the 984 mitigation request from the DOTS client. 986 Figure 10 shows an example response to a PUT request that is 987 successfully processed by a DOTS server (i.e., CoAP 2.xx response 988 codes). This version of the specification forbids 'cuid' and 'cdid' 989 (if used) to be returned in a response message body. 991 { 992 "ietf-dots-signal-channel:mitigation-scope": { 993 "scope": [ 994 { 995 "mid": 123, 996 "lifetime": 3600 997 } 998 ] 999 } 1000 } 1002 Figure 10: 2.xx Response Body 1004 If the request is missing a mandatory attribute, does not include 1005 'cuid' or 'mid' Uri-Path options, includes multiple 'scope' 1006 parameters, or contains invalid or unknown parameters, the DOTS 1007 server MUST reply with 4.00 (Bad Request). DOTS agents can safely 1008 ignore comprehension-optional parameters they don't understand. 1010 A DOTS server that receives a mitigation request with a lifetime set 1011 to '0' MUST reply with a 4.00 (Bad Request). 1013 If the DOTS server does not find the 'mid' parameter value conveyed 1014 in the PUT request in its configuration data, it MAY accept the 1015 mitigation request by sending back a 2.01 (Created) response to the 1016 DOTS client; the DOTS server will consequently try to mitigate the 1017 attack. A DOTS server could reject mitigation requests when it is 1018 near capacity or needs to rate-limit a particular client, for 1019 example. 1021 If the DOTS server finds the 'mid' parameter value conveyed in the 1022 PUT request in its configuration data bound to that DOTS client, it 1023 MAY update the mitigation request, and a 2.04 (Changed) response is 1024 returned to indicate a successful update of the mitigation request. 1026 The relative order of two mitigation requests, having the same 1027 'trigger-mitigation' type, from a DOTS client is determined by 1028 comparing their respective 'mid' values. If two mitigation requests 1029 with the same 'trigger-mitigation' type have overlapping mitigation 1030 scopes, the mitigation request with the highest numeric 'mid' value 1031 will override the other mitigation request. Two mitigation requests 1032 from a DOTS client have overlapping scopes if there is a common IP 1033 address, IP prefix, FQDN, URI, or alias-name. To avoid maintaining a 1034 long list of overlapping mitigation requests (i.e., requests with the 1035 same 'trigger-mitigation' type and overlapping scopes) from a DOTS 1036 client and avoid error-prone provisioning of mitigation requests from 1037 a DOTS client, the overlapped lower numeric 'mid' MUST be 1038 automatically deleted and no longer available at the DOTS server. 1039 For example, if the DOTS server receives a mitigation request which 1040 overlaps with an existing mitigation with a higher numeric 'mid', the 1041 DOTS server rejects the request by returning 4.09 (Conflict) to the 1042 DOTS client. The response includes enough information for a DOTS 1043 client to recognize the source of the conflict as described below in 1044 the 'conflict-information' subtree with only the relevant nodes 1045 listed: 1047 conflict-information: Indicates that a mitigation request is 1048 conflicting with another mitigation request. This optional 1049 attribute has the following structure: 1051 conflict-cause: Indicates the cause of the conflict. The 1052 following values are defined: 1054 1: Overlapping targets. 'conflict-scope' provides more details 1055 about the conflicting target clauses. 1057 conflict-scope: Characterizes the exact conflict scope. It may 1058 include a list of IP addresses, a list of prefixes, a list of 1059 port numbers, a list of target protocols, a list of FQDNs, a 1060 list of URIs, a list of alias-names, or a 'mid'. 1062 If the DOTS server receives a mitigation request which overlaps with 1063 an active mitigation request, but both having distinct 'trigger- 1064 mitigation' types, the DOTS server MUST deactivate (absent explicit 1065 policy/configuration otherwise) the mitigation request with 'trigger- 1066 mitigation' set to false. Particularly, if the mitigation request 1067 with 'trigger-mitigation' set to false is active, the DOTS server 1068 withdraws the mitigation request (i.e., status code is set to '7' as 1069 defined in Table 2) and transitions the status of the mitigation 1070 request to '8'. 1072 Upon DOTS signal channel session loss with a peer DOTS client, the 1073 DOTS server MUST withdraw (absent explicit policy/configuration 1074 otherwise) any active mitigation requests overlapping with mitigation 1075 requests having 'trigger-mitigation' set to false from that DOTS 1076 client, as the loss of the session implictily activates these 1077 preconfigured mitigation requests and they take precedence. Note 1078 that active-but-terminating period is not observed for mitigations 1079 withdrawn at the initiative of the DOTS server. 1081 DOTS clients may adopt various strategies for setting the scopes of 1082 immediate and pre-configured mitigation requests to avoid potential 1083 conflicts. For example, a DOTS client may tweak pre-configured 1084 scopes so that the scope of any overlapping immediate mitigation 1085 request will be a subset of the pre-configured scopes. Also, if an 1086 immediate mitigation request overlaps with any of the pre-configured 1087 scopes, the DOTS client sets the scope of the overlapping immediate 1088 mitigation request to be a subset of the pre-configured scopes, so as 1089 to get a broad mitigation when the DOTS signal channel collapses and 1090 maximize the chance of recovery. 1092 If the request is conflicting with an existing mitigation request 1093 from a different DOTS client, the DOTS server may return 2.01 1094 (Created) or 4.09 (Conflict) to the requesting DOTS client. If the 1095 DOTS server decides to maintain the new mitigation request, the DOTS 1096 server returns 2.01 (Created) to the requesting DOTS client. If the 1097 DOTS server decides to reject the new mitigation request, the DOTS 1098 server returns 4.09 (Conflict) to the requesting DOTS client. For 1099 both 2.01 (Created) and 4.09 (Conflict) responses, the response 1100 includes enough information for a DOTS client to recognize the source 1101 of the conflict as described below: 1103 conflict-information: Indicates that a mitigation request is 1104 conflicting with another mitigation request(s) from other DOTS 1105 client(s). This optional attribute has the following structure: 1107 conflict-status: Indicates the status of a conflicting mitigation 1108 request. The following values are defined: 1110 1: DOTS server has detected conflicting mitigation requests 1111 from different DOTS clients. This mitigation request is 1112 currently inactive until the conflicts are resolved. 1113 Another mitigation request is active. 1115 2: DOTS server has detected conflicting mitigation requests 1116 from different DOTS clients. This mitigation request is 1117 currently active. 1119 3: DOTS server has detected conflicting mitigation requests 1120 from different DOTS clients. All conflicting mitigation 1121 requests are inactive. 1123 conflict-cause: Indicates the cause of the conflict. The 1124 following values are defined: 1126 1: Overlapping targets. 'conflict-scope' provides more details 1127 about the conflicting target clauses. 1129 2: Conflicts with an existing accept-list. This code is 1130 returned when the DDoS mitigation detects source addresses/ 1131 prefixes in the accept-listed ACLs are attacking the 1132 target. 1134 3: CUID Collision. This code is returned when a DOTS client 1135 uses a 'cuid' that is already used by another DOTS client. 1136 This code is an indication that the request has been 1137 rejected and a new request with a new 'cuid' is to be re- 1138 sent by the DOTS client. Note that 'conflict-status', 1139 'conflict-scope', and 'retry-timer' MUST NOT be returned in 1140 the error response. 1142 conflict-scope: Characterizes the exact conflict scope. It may 1143 include a list of IP addresses, a list of prefixes, a list of 1144 port numbers, a list of target protocols, a list of FQDNs, a 1145 list of URIs, a list of alias-names, or references to 1146 conflicting ACLs (by an 'acl-name', typically 1147 [I-D.ietf-dots-data-channel]). 1149 retry-timer: Indicates, in seconds, the time after which the DOTS 1150 client may re-issue the same request. The DOTS server returns 1151 'retry-timer' only to DOTS client(s) for which a mitigation 1152 request is deactivated. Any retransmission of the same 1153 mitigation request before the expiry of this timer is likely to 1154 be rejected by the DOTS server for the same reasons. 1156 The retry-timer SHOULD be equal to the lifetime of the active 1157 mitigation request resulting in the deactivation of the 1158 conflicting mitigation request. The lifetime of the 1159 deactivated mitigation request will be updated to (retry-timer 1160 + 45 seconds), so the DOTS client can refresh the deactivated 1161 mitigation request after retry-timer seconds before expiry of 1162 lifetime and check if the conflict is resolved. 1164 As an active attack evolves, DOTS clients can adjust the scope of 1165 requested mitigation as necessary, by refining the scope of resources 1166 requiring mitigation. This can be achieved by sending a PUT request 1167 with a new 'mid' value that will override the existing one with 1168 overlapping mitigation scopes. 1170 For a mitigation request to continue beyond the initial negotiated 1171 lifetime, the DOTS client has to refresh the current mitigation 1172 request by sending a new PUT request. This PUT request MUST use the 1173 same 'mid' value, and MUST repeat all the other parameters as sent in 1174 the original mitigation request apart from a possible change to the 1175 lifetime parameter value. 1177 4.4.2. Retrieve Information Related to a Mitigation 1179 A GET request is used by a DOTS client to retrieve information 1180 (including status) of DOTS mitigations from a DOTS server. 1182 'cuid' is a mandatory Uri-Path parameter for GET requests. 1184 Uri-Path parameters with empty values MUST NOT be present in a 1185 request. 1187 The same considerations for manipulating 'cdid' parameter by server- 1188 domain DOTS gateways specified in Section 4.4.1 MUST be followed for 1189 GET requests. 1191 The 'c' (content) parameter and its permitted values defined in 1192 [I-D.ietf-core-comi] can be used to retrieve non-configuration data 1193 (attack mitigation status), configuration data, or both. The DOTS 1194 server MAY support this optional filtering capability. It can safely 1195 ignore it if not supported. If the DOTS client supports the optional 1196 filtering capability, it SHOULD use "c=n" query (to get back only the 1197 dynamically changing data) or "c=c" query (to get back the static 1198 configuration values) when the DDoS attack is active to limit the 1199 size of the response. 1201 The DOTS client can use Block-wise transfer [RFC7959] to get the list 1202 of all its mitigations maintained by a DOTS server, it can send 1203 Block2 Option in a GET request with NUM = 0 to aid in limiting the 1204 size of the response. If the representation of all the active 1205 mitigation requests associated with the DOTS client does not fit 1206 within a single datagram, the DOTS server MUST use the Block2 Option 1207 with NUM = 0 in the GET response. The Size2 Option may be conveyed 1208 in the response to indicate the total size of the resource 1209 representation. The DOTS client retrieves the rest of the 1210 representation by sending additional GET requests with Block2 Options 1211 containing NUM values greater than zero. The DOTS client MUST adhere 1212 to the block size preferences indicated by the DOTS server in the 1213 response. If the DOTS server uses the Block2 Option in the GET 1214 response and the response is for a dynamically changing resource 1215 (e.g. "c=n" or "c=a" query), the DOTS server MUST include the ETag 1216 Option in the response. The DOTS client MUST include the same ETag 1217 value in subsequent GET requests to retrieve the rest of the 1218 representation. 1220 The following examples illustrate how a DOTS client retrieves active 1221 mitigation requests from a DOTS server. In particular: 1223 o Figure 11 shows the example of a GET request to retrieve all DOTS 1224 mitigation requests signaled by a DOTS client. 1226 o Figure 12 shows the example of a GET request to retrieve a 1227 specific DOTS mitigation request signaled by a DOTS client. The 1228 configuration data to be reported in the response is formatted in 1229 the same order as was processed by the DOTS server in the original 1230 mitigation request. 1232 These two examples assume the default of "c=a"; that is, the DOTS 1233 client asks for all data to be reported by the DOTS server. 1235 Header: GET (Code=0.01) 1236 Uri-Path: ".well-known" 1237 Uri-Path: "dots" 1238 Uri-Path: "mitigate" 1239 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1240 Observe: 0 1242 Figure 11: GET to Retrieve all DOTS Mitigation Requests 1244 Header: GET (Code=0.01) 1245 Uri-Path: ".well-known" 1246 Uri-Path: "dots" 1247 Uri-Path: "mitigate" 1248 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1249 Uri-Path: "mid=12332" 1250 Observe: 0 1252 Figure 12: GET to Retrieve a Specific DOTS Mitigation Request 1254 If the DOTS server does not find the 'mid' Uri-Path value conveyed in 1255 the GET request in its configuration data for the requesting DOTS 1256 client, it MUST respond with a 4.04 (Not Found) error response code. 1257 Likewise, the same error MUST be returned as a response to a request 1258 to retrieve all mitigation records (i.e., 'mid' Uri-Path is not 1259 defined) of a given DOTS client if the DOTS server does not find any 1260 mitigation record for that DOTS client. As a reminder, a DOTS client 1261 is identified by its identity (e.g., client certificate, 'cuid') and 1262 optionally the 'cdid'. 1264 Figure 13 shows a response example of all active mitigation requests 1265 associated with the DOTS client as maintained by the DOTS server. 1266 The response indicates the mitigation status of each mitigation 1267 request. 1269 { 1270 "ietf-dots-signal-channel:mitigation-scope": { 1271 "scope": [ 1272 { 1273 "mid": 12332, 1274 "mitigation-start": "1507818434", 1275 "target-prefix": [ 1276 "2001:db8:6401::1/128", 1277 "2001:db8:6401::2/128" 1278 ], 1279 "target-protocol": [ 1280 17 1281 ], 1282 "lifetime": 1756, 1283 "status": "attack-successfully-mitigated", 1284 "bytes-dropped": "134334555", 1285 "bps-dropped": "43344", 1286 "pkts-dropped": "333334444", 1287 "pps-dropped": "432432" 1288 }, 1289 { 1290 "mid": 12333, 1291 "mitigation-start": "1507818393", 1292 "target-prefix": [ 1293 "2001:db8:6401::1/128", 1294 "2001:db8:6401::2/128" 1295 ], 1296 "target-protocol": [ 1297 6 1298 ], 1299 "lifetime": 1755, 1300 "status": "attack-stopped", 1301 "bytes-dropped": "0", 1302 "bps-dropped": "0", 1303 "pkts-dropped": "0", 1304 "pps-dropped": "0" 1305 } 1306 ] 1307 } 1308 } 1310 Figure 13: Response Body to a GET Request 1312 The mitigation status parameters are described below: 1314 mitigation-start: Mitigation start time is expressed in seconds 1315 relative to 1970-01-01T00:00Z in UTC time (Section 2.4.1 of 1317 [RFC7049]). The CBOR encoding is modified so that the leading tag 1318 1 (epoch-based date/time) MUST be omitted. 1320 This is a mandatory attribute when an attack mitigation is active. 1321 Particularly, 'mitigation-start' is not returned for a mitigation 1322 with 'status' code set to 8. 1324 lifetime: The remaining lifetime of the mitigation request, in 1325 seconds. 1327 This is a mandatory attribute. 1329 status: Status of attack mitigation. The various possible values of 1330 'status' parameter are explained in Table 2. 1332 This is a mandatory attribute. 1334 bytes-dropped: The total dropped byte count for the mitigation 1335 request since the attack mitigation is triggered. The count wraps 1336 around when it reaches the maximum value of unsigned integer64. 1338 This is an optional attribute. 1340 bps-dropped: The average number of dropped bytes per second for the 1341 mitigation request since the attack mitigation is triggered. This 1342 average SHOULD be over five-minute intervals. 1344 This is an optional attribute. 1346 pkts-dropped: The total number of dropped packet count for the 1347 mitigation request since the attack mitigation is triggered. The 1348 count wraps around when it reaches the maximum value of unsigned 1349 integer64. 1351 This is an optional attribute. 1353 pps-dropped: The average number of dropped packets per second for 1354 the mitigation request since the attack mitigation is triggered. 1355 This average SHOULD be over five-minute intervals. 1357 This is an optional attribute. 1359 +-----------+-------------------------------------------------------+ 1360 | Parameter | Description | 1361 | Value | | 1362 +-----------+-------------------------------------------------------+ 1363 | 1 | Attack mitigation setup is in progress (e.g., | 1364 | | changing the network path to redirect the inbound | 1365 | | traffic to a DOTS mitigator). | 1366 +-----------+-------------------------------------------------------+ 1367 | 2 | Attack is being successfully mitigated (e.g., traffic | 1368 | | is redirected to a DDoS mitigator and attack traffic | 1369 | | is dropped). | 1370 +-----------+-------------------------------------------------------+ 1371 | 3 | Attack has stopped and the DOTS client can withdraw | 1372 | | the mitigation request. This status code will be | 1373 | | transmitted for immediate mitigation requests till | 1374 | | the mitigation is withdrawn or the lifetime expires. | 1375 | | For mitigation requests with pre-configured scopes | 1376 | | (i.e., 'trigger-mitigation' set to 'false'), this | 1377 | | status code will be transmitted 4 times and then | 1378 | | transition to "8". | 1379 +-----------+-------------------------------------------------------+ 1380 | 4 | Attack has exceeded the mitigation provider | 1381 | | capability. | 1382 +-----------+-------------------------------------------------------+ 1383 | 5 | DOTS client has withdrawn the mitigation request and | 1384 | | the mitigation is active but terminating. | 1385 +-----------+-------------------------------------------------------+ 1386 | 6 | Attack mitigation is now terminated. | 1387 +-----------+-------------------------------------------------------+ 1388 | 7 | Attack mitigation is withdrawn (by the DOTS server). | 1389 | | If a mitigation request with 'trigger-mitigation' set | 1390 | | to false is withdrawn because it overlaps with an | 1391 | | immediate mitigation request, this status code will | 1392 | | be transmitted 4 times and then transition to "8" for | 1393 | | the mitigation request with pre-configured scopes. | 1394 +-----------+-------------------------------------------------------+ 1395 | 8 | Attack mitigation will be triggered for the | 1396 | | mitigation request only when the DOTS signal channel | 1397 | | session is lost. | 1398 +-----------+-------------------------------------------------------+ 1400 Table 2: Values of 'status' Parameter 1402 4.4.2.1. DOTS Servers Sending Mitigation Status 1404 The Observe Option defined in [RFC7641] extends the CoAP core 1405 protocol with a mechanism for a CoAP client to "observe" a resource 1406 on a CoAP server: The client retrieves a representation of the 1407 resource and requests this representation be updated by the server as 1408 long as the client is interested in the resource. DOTS 1409 implementations MUST use the Observe Option for both 'mitigate' and 1410 'config' (Section 4.2). 1412 A DOTS client conveys the Observe Option set to '0' in the GET 1413 request to receive asynchronous notifications of attack mitigation 1414 status from the DOTS server. 1416 Unidirectional mitigation notifications within the bidirectional 1417 signal channel enables asynchronous notifications between the agents. 1418 [RFC7641] indicates that (1) a notification can be sent in a 1419 Confirmable or a Non-confirmable message, and (2) the message type 1420 used is typically application dependent and may be determined by the 1421 server for each notification individually. For DOTS server 1422 application, the message type MUST always be set to Non-confirmable 1423 even if the underlying COAP library elects a notification to be sent 1424 in a Confirmable message. 1426 Due to the higher likelihood of packet loss during a DDoS attack, the 1427 DOTS server periodically sends attack mitigation status to the DOTS 1428 client and also notifies the DOTS client whenever the status of the 1429 attack mitigation changes. If the DOTS server cannot maintain an RTT 1430 estimate, it SHOULD NOT send more than one asynchronous notification 1431 every 3 seconds, and SHOULD use an even less aggressive rate whenever 1432 possible (case 2 in Section 3.1.3 of [RFC8085]). 1434 When conflicting requests are detected, the DOTS server enforces the 1435 corresponding policy (e.g., accept all requests, reject all requests, 1436 accept only one request but reject all the others, ...). It is 1437 assumed that this policy is supplied by the DOTS server administrator 1438 or it is a default behavior of the DOTS server implementation. Then, 1439 the DOTS server sends notification message(s) to the DOTS client(s) 1440 at the origin of the conflict (refer to the conflict parameters 1441 defined in Section 4.4.1). A conflict notification message includes 1442 information about the conflict cause, scope, and the status of the 1443 mitigation request(s). For example, 1445 o A notification message with 'status' code set to '7 (Attack 1446 mitigation is withdrawn)' and 'conflict-status' set to '1' is sent 1447 to a DOTS client to indicate that an active mitigation request is 1448 deactivated because a conflict is detected. 1450 o A notification message with 'status' code set to '1 (Attack 1451 mitigation is in progress)' and 'conflict-status' set to '2' is 1452 sent to a DOTS client to indicate that this mitigation request is 1453 in progress, but a conflict is detected. 1455 Upon receipt of a conflict notification message indicating that a 1456 mitigation request is deactivated because of a conflict, a DOTS 1457 client MUST NOT resend the same mitigation request before the expiry 1458 of 'retry-timer'. It is also recommended that DOTS clients support 1459 means to alert administrators about mitigation conflicts. 1461 A DOTS client that is no longer interested in receiving notifications 1462 from the DOTS server can simply "forget" the observation. When the 1463 DOTS server sends the next notification, the DOTS client will not 1464 recognize the token in the message and thus will return a Reset 1465 message. This causes the DOTS server to remove the associated entry. 1466 Alternatively, the DOTS client can explicitly deregister itself by 1467 issuing a GET request that has the Token field set to the token of 1468 the observation to be cancelled and includes an Observe Option with 1469 the value set to '1' (deregister). The latter is RECOMMENDED. 1471 Figure 14 shows an example of a DOTS client requesting a DOTS server 1472 to send notifications related to a mitigation request. Note that for 1473 mitigations with pre-configured scopes (i.e., 'trigger-mitigation' 1474 set to 'false'), the state will need to transition from 3 (attack- 1475 stopped) to 8 (attack-mitigation-signal-loss). 1477 +-----------+ +-----------+ 1478 |DOTS client| |DOTS server| 1479 +-----------+ +-----------+ 1480 | | 1481 | GET / | 1482 | Token: 0x4a | Registration 1483 | Observe: 0 | 1484 +----------------------------------------->| 1485 | | 1486 | 2.05 Content | 1487 | Token: 0x4a | Notification of 1488 | Observe: 12 | the current state 1489 | status: "attack-mitigation-in-progress" | 1490 | | 1491 |<-----------------------------------------+ 1492 | 2.05 Content | 1493 | Token: 0x4a | Notification upon 1494 | Observe: 44 | a state change 1495 | status: "attack-successfully-mitigated" | 1496 | | 1497 |<-----------------------------------------+ 1498 | 2.05 Content | 1499 | Token: 0x4a | Notification upon 1500 | Observe: 60 | a state change 1501 | status: "attack-stopped" | 1502 |<-----------------------------------------+ 1503 | | 1504 ... 1506 Figure 14: Notifications of Attack Mitigation Status 1508 4.4.2.2. DOTS Clients Polling for Mitigation Status 1510 The DOTS client can send the GET request at frequent intervals 1511 without the Observe Option to retrieve the configuration data of the 1512 mitigation request and non-configuration data (i.e., the attack 1513 status). The frequency of polling the DOTS server to get the 1514 mitigation status SHOULD follow the transmission guidelines in 1515 Section 3.1.3 of [RFC8085]. 1517 If the DOTS server has been able to mitigate the attack and the 1518 attack has stopped, the DOTS server indicates as such in the status. 1519 In such case, the DOTS client recalls the mitigation request by 1520 issuing a DELETE request for this mitigation request (Section 4.4.4). 1522 A DOTS client SHOULD react to the status of the attack as per the 1523 information sent by the DOTS server rather than performing its own 1524 detection that the attack has been mitigated. This ensures that the 1525 DOTS client does not recall a mitigation request prematurely because 1526 it is possible that the DOTS client does not sense the DDoS attack on 1527 its resources, but the DOTS server could be actively mitigating the 1528 attack because the attack is not completely averted. 1530 4.4.3. Efficacy Update from DOTS Clients 1532 While DDoS mitigation is in progress, due to the likelihood of packet 1533 loss, a DOTS client MAY periodically transmit DOTS mitigation 1534 efficacy updates to the relevant DOTS server. A PUT request is used 1535 to convey the mitigation efficacy update to the DOTS server. This 1536 PUT request is treated as a refresh of the current mitigation. 1538 The PUT request used for efficacy update MUST include all the 1539 parameters used in the PUT request to carry the DOTS mitigation 1540 request (Section 4.4.1) unchanged apart from the 'lifetime' parameter 1541 value. If this is not the case, the DOTS server MUST reject the 1542 request with a 4.00 (Bad Request). 1544 The If-Match Option (Section 5.10.8.1 of [RFC7252]) with an empty 1545 value is used to make the PUT request conditional on the current 1546 existence of the mitigation request. If UDP is used as transport, 1547 CoAP requests may arrive out-of-order. For example, the DOTS client 1548 may send a PUT request to convey an efficacy update to the DOTS 1549 server followed by a DELETE request to withdraw the mitigation 1550 request, but the DELETE request arrives at the DOTS server before the 1551 PUT request. To handle out-of-order delivery of requests, if an If- 1552 Match Option is present in the PUT request and the 'mid' in the 1553 request matches a mitigation request from that DOTS client, the 1554 request is processed by the DOTS server. If no match is found, the 1555 PUT request is silently ignored by the DOTS server. 1557 An example of an efficacy update message, which includes an If-Match 1558 Option with an empty value, is depicted in Figure 15. 1560 Header: PUT (Code=0.03) 1561 Uri-Path: ".well-known" 1562 Uri-Path: "dots" 1563 Uri-Path: "mitigate" 1564 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1565 Uri-Path: "mid=123" 1566 Content-Format: "application/dots+cbor" 1567 If-Match: 1568 { 1569 "ietf-dots-signal-channel:mitigation-scope": { 1570 "scope": [ 1571 { 1572 "target-prefix": [ 1573 "2001:db8:6401::1/128", 1574 "2001:db8:6401::2/128" 1575 ], 1576 "target-port-range": [ 1577 { 1578 "lower-port": 80 1579 }, 1580 { 1581 "lower-port": 443 1582 }, 1583 { 1584 "lower-port": 8080 1585 } 1586 ], 1587 "target-protocol": [ 1588 6 1589 ], 1590 "attack-status": "under-attack" 1591 } 1592 ] 1593 } 1594 } 1596 Figure 15: An Example of Efficacy Update 1598 The 'attack-status' parameter is a mandatory attribute when 1599 performing an efficacy update. The various possible values contained 1600 in the 'attack-status' parameter are described in Table 3. 1602 +-----------+-------------------------------------------------------+ 1603 | Parameter | Description | 1604 | value | | 1605 +-----------+-------------------------------------------------------+ 1606 | 1 | The DOTS client determines that it is still under | 1607 | | attack. | 1608 +-----------+-------------------------------------------------------+ 1609 | 2 | The DOTS client determines that the attack is | 1610 | | successfully mitigated (e.g., attack traffic is not | 1611 | | seen). | 1612 +-----------+-------------------------------------------------------+ 1614 Table 3: Values of 'attack-status' Parameter 1616 The DOTS server indicates the result of processing a PUT request 1617 using CoAP response codes. The response code 2.04 (Changed) is 1618 returned if the DOTS server has accepted the mitigation efficacy 1619 update. The error response code 5.03 (Service Unavailable) is 1620 returned if the DOTS server has erred or is incapable of performing 1621 the mitigation. As specified in [RFC7252], 5.03 uses Max-Age option 1622 to indicate the number of seconds after which to retry. 1624 4.4.4. Withdraw a Mitigation 1626 DELETE requests are used to withdraw DOTS mitigation requests from 1627 DOTS servers (Figure 16). 1629 'cuid' and 'mid' are mandatory Uri-Path parameters for DELETE 1630 requests. 1632 The same considerations for manipulating 'cdid' parameter by DOTS 1633 gateways, as specified in Section 4.4.1, MUST be followed for DELETE 1634 requests. Uri-Path parameters with empty values MUST NOT be present 1635 in a request. 1637 Header: DELETE (Code=0.04) 1638 Uri-Path: ".well-known" 1639 Uri-Path: "dots" 1640 Uri-Path: "mitigate" 1641 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1642 Uri-Path: "mid=123" 1644 Figure 16: Withdraw a DOTS Mitigation 1646 If the DELETE request does not include 'cuid' and 'mid' parameters, 1647 the DOTS server MUST reply with a 4.00 (Bad Request). 1649 Once the request is validated, the DOTS server immediately 1650 acknowledges a DOTS client's request to withdraw the DOTS signal 1651 using 2.02 (Deleted) response code with no response payload. A 2.02 1652 (Deleted) Response Code is returned even if the 'mid' parameter value 1653 conveyed in the DELETE request does not exist in its configuration 1654 data before the request. 1656 If the DOTS server finds the 'mid' parameter value conveyed in the 1657 DELETE request in its configuration data for the DOTS client, then to 1658 protect against route or DNS flapping caused by a DOTS client rapidly 1659 removing a mitigation, and to dampen the effect of oscillating 1660 attacks, the DOTS server MAY allow mitigation to continue for a 1661 limited period after acknowledging a DOTS client's withdrawal of a 1662 mitigation request. During this period, the DOTS server status 1663 messages SHOULD indicate that mitigation is active but terminating 1664 (Section 4.4.2). 1666 The initial active-but-terminating period SHOULD be sufficiently long 1667 to absorb latency incurred by route propagation. The active-but- 1668 terminating period SHOULD be set by default to 120 seconds. If the 1669 client requests mitigation again before the initial active-but- 1670 terminating period elapses, the DOTS server MAY exponentially 1671 increase (the base of the exponent is 2) the active-but-terminating 1672 period up to a maximum of 300 seconds (5 minutes). 1674 Once the active-but-terminating period elapses, the DOTS server MUST 1675 treat the mitigation as terminated, as the DOTS client is no longer 1676 responsible for the mitigation. For example, if there is a financial 1677 relationship between the DOTS client and server domains, the DOTS 1678 client stops incurring cost at this point. 1680 If a mitigation is triggered due to a signal channel loss, the DOTS 1681 server relies upon normal triggers to stop that mitigation 1682 (typically, receipt of a valid DELETE request, expiry of the 1683 mitigation lifetime, or scrubbing the traffic to the attack target). 1684 In particular, the DOTS server MUST NOT consider the signal channel 1685 recovery as a trigger to stop the mitigation. 1687 4.5. DOTS Signal Channel Session Configuration 1689 A DOTS client can negotiate, configure, and retrieve the DOTS signal 1690 channel session behavior with its DOTS peers. The DOTS signal 1691 channel can be used, for example, to configure the following: 1693 a. Heartbeat interval (heartbeat-interval): DOTS agents regularly 1694 send heartbeats (CoAP Ping/Pong) to each other after mutual 1695 authentication is successfully completed in order to keep the 1696 DOTS signal channel open. Heartbeat messages are exchanged 1697 between DOTS agents every 'heartbeat-interval' seconds to detect 1698 the current status of the DOTS signal channel session. 1700 b. Missing heartbeats allowed (missing-hb-allowed): This variable 1701 indicates the maximum number of consecutive heartbeat messages 1702 for which a DOTS agent did not receive a response before 1703 concluding that the session is disconnected or defunct. 1705 c. Acceptable signal loss ratio: Maximum retransmissions, 1706 retransmission timeout value, and other message transmission 1707 parameters for the DOTS signal channel. 1709 The same or distinct configuration sets may be used during times when 1710 a mitigation is active ('mitigating-config') and when no mitigation 1711 is active ('idle-config'). This is particularly useful for DOTS 1712 servers that might want to reduce heartbeat frequency or cease 1713 heartbeat exchanges when an active DOTS client has not requested 1714 mitigation. If distinct configurations are used, DOTS agents MUST 1715 follow the appropriate configuration set as a function of the 1716 mitigation activity (e.g., if no mitigation request is active (also 1717 referred to as 'idle' time), 'idle-config'-related values must be 1718 followed). Additionally, DOTS agents MUST automatically switch to 1719 the other configuration upon a change in the mitigation activity 1720 (e.g., if an attack mitigation is launched after an 'idle' time, the 1721 DOTS agent switches from 'idle-config' to 'mitigating-config'-related 1722 values). 1724 CoAP Requests and responses are indicated for reliable delivery by 1725 marking them as Confirmable messages. DOTS signal channel session 1726 configuration requests and responses are marked as Confirmable 1727 messages. As explained in Section 2.1 of [RFC7252], a Confirmable 1728 message is retransmitted using a default timeout and exponential 1729 back-off between retransmissions, until the DOTS server sends an 1730 Acknowledgement message (ACK) with the same Message ID conveyed from 1731 the DOTS client. 1733 Message transmission parameters are defined in Section 4.8 of 1734 [RFC7252]. The DOTS server can either piggyback the response in the 1735 acknowledgement message or, if the DOTS server cannot respond 1736 immediately to a request carried in a Confirmable message, it simply 1737 responds with an Empty Acknowledgement message so that the DOTS 1738 client can stop retransmitting the request. Empty Acknowledgement 1739 messages are explained in Section 2.2 of [RFC7252]. When the 1740 response is ready, the server sends it in a new Confirmable message 1741 which in turn needs to be acknowledged by the DOTS client (see 1742 Sections 5.2.1 and 5.2.2 of [RFC7252]). Requests and responses 1743 exchanged between DOTS agents during 'idle' time are marked as 1744 Confirmable messages. 1746 Implementation Note: A DOTS client that receives a response in a 1747 Confirmable message may want to clean up the message state right 1748 after sending the ACK. If that ACK is lost and the DOTS server 1749 retransmits the Confirmable message, the DOTS client may no longer 1750 have any state that would help it correlate this response: from 1751 the DOTS client's standpoint, the retransmission message is 1752 unexpected. The DOTS client will send a Reset message so it does 1753 not receive any more retransmissions. This behavior is normal and 1754 not an indication of an error (see Section 5.3.2 of [RFC7252] for 1755 more details). 1757 4.5.1. Discover Configuration Parameters 1759 A GET request is used to obtain acceptable (e.g., minimum and maximum 1760 values) and current configuration parameters on the DOTS server for 1761 DOTS signal channel session configuration. This procedure occurs 1762 between a DOTS client and its immediate peer DOTS server. As such, 1763 this GET request MUST NOT be relayed by a DOTS gateway. 1765 Figure 17 shows how to obtain acceptable configuration parameters for 1766 the DOTS server. 1768 Header: GET (Code=0.01) 1769 Uri-Path: ".well-known" 1770 Uri-Path: "dots" 1771 Uri-Path: "config" 1773 Figure 17: GET to Retrieve Configuration 1775 The DOTS server in the 2.05 (Content) response conveys the current, 1776 minimum, and maximum attribute values acceptable by the DOTS server 1777 (Figure 18). 1779 Content-Format: "application/dots+cbor" 1780 { 1781 "ietf-dots-signal-channel:signal-config": { 1782 "mitigating-config": { 1783 "heartbeat-interval": { 1784 "max-value": number, 1785 "min-value": number, 1786 "current-value": number 1787 }, 1788 "missing-hb-allowed": { 1789 "max-value": number, 1790 "min-value": number, 1791 "current-value": number 1792 }, 1793 "max-retransmit": { 1794 "max-value": number, 1795 "min-value": number, 1796 "current-value": number 1797 }, 1798 "ack-timeout": { 1799 "max-value-decimal": "string", 1800 "min-value-decimal": "string", 1801 "current-value-decimal": "string" 1802 }, 1803 "ack-random-factor": { 1804 "max-value-decimal": "string", 1805 "min-value-decimal": "string", 1806 "current-value-decimal": "string" 1807 } 1808 }, 1809 "idle-config": { 1810 "heartbeat-interval": { 1811 "max-value": number, 1812 "min-value": number, 1813 "current-value": number 1814 }, 1815 "missing-hb-allowed": { 1816 "max-value": number, 1817 "min-value": number, 1818 "current-value": number 1819 }, 1820 "max-retransmit": { 1821 "max-value": number, 1822 "min-value": number, 1823 "current-value": number 1824 }, 1825 "ack-timeout": { 1826 "max-value-decimal": "string", 1827 "min-value-decimal": "string", 1828 "current-value-decimal": "string" 1829 }, 1830 "ack-random-factor": { 1831 "max-value-decimal": "string", 1832 "min-value-decimal": "string", 1833 "current-value-decimal": "string" 1834 } 1835 } 1836 } 1837 } 1839 Figure 18: GET Configuration Response Body Schema 1841 The parameters in Figure 18 are described below: 1843 mitigating-config: Set of configuration parameters to use when a 1844 mitigation is active. The following parameters may be included: 1846 heartbeat-interval: Time interval in seconds between two 1847 consecutive heartbeat messages. 1849 '0' is used to disable the heartbeat mechanism. 1851 This is an optional attribute. 1853 missing-hb-allowed: Maximum number of consecutive heartbeat 1854 messages for which the DOTS agent did not receive a response 1855 before concluding that the session is disconnected. 1857 This is an optional attribute. 1859 max-retransmit: Maximum number of retransmissions for a message 1860 (referred to as MAX_RETRANSMIT parameter in CoAP). 1862 This is an optional attribute. 1864 ack-timeout: Timeout value in seconds used to calculate the 1865 initial retransmission timeout value (referred to as 1866 ACK_TIMEOUT parameter in CoAP). 1868 This is an optional attribute. 1870 ack-random-factor: Random factor used to influence the timing of 1871 retransmissions (referred to as ACK_RANDOM_FACTOR parameter in 1872 CoAP). 1874 This is an optional attribute. 1876 idle-config: Set of configuration parameters to use when no 1877 mitigation is active. This attribute has the same structure as 1878 'mitigating-config'. 1880 Figure 19 shows an example of acceptable and current configuration 1881 parameters on a DOTS server for DOTS signal channel session 1882 configuration. The same acceptable configuration is used during 1883 mitigation and idle times. 1885 Content-Format: "application/dots+cbor" 1886 { 1887 "ietf-dots-signal-channel:signal-config": { 1888 "mitigating-config": { 1889 "heartbeat-interval": { 1890 "max-value": 240, 1891 "min-value": 15, 1892 "current-value": 30 1893 }, 1894 "missing-hb-allowed": { 1895 "max-value": 9, 1896 "min-value": 3, 1897 "current-value": 5 1898 }, 1899 "max-retransmit": { 1900 "max-value": 15, 1901 "min-value": 2, 1902 "current-value": 3 1903 }, 1904 "ack-timeout": { 1905 "max-value-decimal": "30.00", 1906 "min-value-decimal": "1.00", 1907 "current-value-decimal": "2.00" 1908 }, 1909 "ack-random-factor": { 1910 "max-value-decimal": "4.00", 1911 "min-value-decimal": "1.10", 1912 "current-value-decimal": "1.50" 1913 } 1914 }, 1915 "idle-config": { 1916 "heartbeat-interval": { 1917 "max-value": 240, 1918 "min-value": 15, 1919 "current-value": 30 1920 }, 1921 "missing-hb-allowed": { 1922 "max-value": 9, 1923 "min-value": 3, 1924 "current-value": 5 1925 }, 1926 "max-retransmit": { 1927 "max-value": 15, 1928 "min-value": 2, 1929 "current-value": 3 1930 }, 1931 "ack-timeout": { 1932 "max-value-decimal": "30.00", 1933 "min-value-decimal": "1.00", 1934 "current-value-decimal": "2.00" 1935 }, 1936 "ack-random-factor": { 1937 "max-value-decimal": "4.00", 1938 "min-value-decimal": "1.10", 1939 "current-value-decimal": "1.50" 1940 } 1941 } 1942 } 1943 } 1945 Figure 19: Example of a Configuration Response Body 1947 4.5.2. Convey DOTS Signal Channel Session Configuration 1949 A PUT request (Figures 20 and 21) is used to convey the configuration 1950 parameters for the signal channel (e.g., heartbeat interval, maximum 1951 retransmissions). Message transmission parameters for CoAP are 1952 defined in Section 4.8 of [RFC7252]. The RECOMMENDED values of 1953 transmission parameter values are ack-timeout (2 seconds), max- 1954 retransmit (3), ack-random-factor (1.5). In addition to those 1955 parameters, the RECOMMENDED specific DOTS transmission parameter 1956 values are 'heartbeat-interval' (30 seconds) and 'missing-hb-allowed' 1957 (5). 1959 Note: heartbeat-interval should be tweaked to also assist DOTS 1960 messages for NAT traversal (SIG-011 of 1961 [I-D.ietf-dots-requirements]). According to [RFC8085], keepalive 1962 messages must not be sent more frequently than once every 15 1963 seconds and should use longer intervals when possible. 1964 Furthermore, [RFC4787] recommends NATs to use a state timeout of 2 1965 minutes or longer, but experience shows that sending packets every 1966 15 to 30 seconds is necessary to prevent the majority of 1967 middleboxes from losing state for UDP flows. From that 1968 standpoint, this specification recommends a minimum heartbeat- 1969 interval of 15 seconds and a maximum heartbeat-interval of 240 1970 seconds. The recommended value of 30 seconds is selected to 1971 anticipate the expiry of NAT state. 1973 A heartbeat-interval of 30 seconds may be considered as too chatty 1974 in some deployments. For such deployments, DOTS agents may 1975 negotiate longer heartbeat-interval values to prevent any network 1976 overload with too frequent keepalives. 1978 Different heartbeat intervals can be defined for 'mitigating- 1979 config' and 'idle-config' to reduce being too chatty during idle 1980 times. If there is an on-path translator between the DOTS client 1981 (standalone or part of a DOTS gateway) and the DOTS server, the 1982 'mitigating-config' heartbeat-interval has to be smaller than the 1983 translator session timeout. It is recommended that the 'idle- 1984 config' heartbeat-interval is also smaller than the translator 1985 session timeout to prevent translator traversal issues, or 1986 disabled entirely. Means to discover the lifetime assigned by a 1987 translator are out of scope. 1989 When a Confirmable "CoAP Ping" is sent, and if there is no response, 1990 the "CoAP Ping" is retransmitted max-retransmit number of times by 1991 the CoAP layer using an initial timeout set to a random duration 1992 between ack-timeout and (ack-timeout*ack-random-factor) and 1993 exponential back-off between retransmissions. By choosing the 1994 recommended transmission parameters, the "CoAP Ping" will timeout 1995 after 45 seconds. If the DOTS agent does not receive any response 1996 from the peer DOTS agent for 'missing-hb-allowed' number of 1997 consecutive "CoAP Ping" Confirmable messages, it concludes that the 1998 DOTS signal channel session is disconnected. A DOTS client MUST NOT 1999 transmit a "CoAP Ping" while waiting for the previous "CoAP Ping" 2000 response from the same DOTS server. 2002 If the DOTS agent wishes to change the default values of message 2003 transmission parameters, it SHOULD follow the guidance given in 2004 Section 4.8.1 of [RFC7252]. The DOTS agents MUST use the negotiated 2005 values for message transmission parameters and default values for 2006 non-negotiated message transmission parameters. 2008 The signal channel session configuration is applicable to a single 2009 DOTS signal channel session between DOTS agents, so the 'cuid' Uri- 2010 Path MUST NOT be used. 2012 Header: PUT (Code=0.03) 2013 Uri-Path: ".well-known" 2014 Uri-Path: "dots" 2015 Uri-Path: "config" 2016 Uri-Path: "sid=123" 2017 Content-Format: "application/dots+cbor" 2018 { 2019 ... 2020 } 2022 Figure 20: PUT to Convey the DOTS Signal Channel Session 2023 Configuration Data 2025 The additional Uri-Path parameter to those defined in Table 1 is as 2026 follows: 2028 sid: Session Identifier is an identifier for the DOTS signal channel 2029 session configuration data represented as an integer. This 2030 identifier MUST be generated by DOTS clients. 'sid' values MUST 2031 increase monotonically (when a new PUT is generated by a DOTS 2032 client to convey the configuration parameters for the signal 2033 channel). 2035 This is a mandatory attribute. 2037 Content-Format: "application/dots+cbor" 2038 { 2039 "ietf-dots-signal-channel:signal-config": { 2040 "mitigating-config": { 2041 "heartbeat-interval": { 2042 "current-value": number 2043 }, 2044 "missing-hb-allowed": { 2045 "current-value": number 2046 }, 2047 "max-retransmit": { 2048 "current-value": number 2049 }, 2050 "ack-timeout": { 2051 "current-value-decimal": "string" 2052 }, 2053 "ack-random-factor": { 2054 "current-value-decimal": "string" 2055 } 2056 }, 2057 "idle-config": { 2058 "heartbeat-interval": { 2059 "current-value": number 2060 }, 2061 "missing-hb-allowed": { 2062 "current-value": number 2063 }, 2064 "max-retransmit": { 2065 "current-value": number 2066 }, 2067 "ack-timeout": { 2068 "current-value-decimal": "string" 2069 }, 2070 "ack-random-factor": { 2071 "current-value-decimal": "string" 2072 } 2073 } 2074 } 2075 } 2077 Figure 21: PUT to Convey the DOTS Signal Channel Session 2078 Configuration Data (Message Body Schema) 2080 The meaning of the parameters in the CBOR body (Figure 21) is defined 2081 in Section 4.5.1. 2083 At least one of the attributes 'heartbeat-interval', 'missing-hb- 2084 allowed', 'max-retransmit', 'ack-timeout', and 'ack-random-factor' 2085 MUST be present in the PUT request. Note that 'heartbeat-interval', 2086 'missing-hb-allowed', 'max-retransmit', 'ack-timeout', and 'ack- 2087 random-factor', if present, do not need to be provided for both 2088 'mitigating-config', and 'idle-config' in a PUT request. 2090 The PUT request with a higher numeric 'sid' value overrides the DOTS 2091 signal channel session configuration data installed by a PUT request 2092 with a lower numeric 'sid' value. To avoid maintaining a long list 2093 of 'sid' requests from a DOTS client, the lower numeric 'sid' MUST be 2094 automatically deleted and no longer available at the DOTS server. 2096 Figure 22 shows a PUT request example to convey the configuration 2097 parameters for the DOTS signal channel. In this example, the 2098 heartbeat mechanism is disabled when no mitigation is active, while 2099 the heartbeat interval is set to '91' when a mitigation is active. 2101 Header: PUT (Code=0.03) 2102 Uri-Path: ".well-known" 2103 Uri-Path: "dots" 2104 Uri-Path: "config" 2105 Uri-Path: "sid=123" 2106 Content-Format: "application/dots+cbor" 2107 { 2108 "ietf-dots-signal-channel:signal-config": { 2109 "mitigating-config": { 2110 "heartbeat-interval": { 2111 "current-value": 91 2112 }, 2113 "missing-hb-allowed": { 2114 "current-value": 3 2115 }, 2116 "max-retransmit": { 2117 "current-value": 3 2118 }, 2119 "ack-timeout": { 2120 "current-value-decimal": "2.00" 2121 }, 2122 "ack-random-factor": { 2123 "current-value-decimal": "1.50" 2124 } 2125 }, 2126 "idle-config": { 2127 "heartbeat-interval": { 2128 "current-value": 0 2129 }, 2130 "max-retransmit": { 2131 "current-value": 3 2132 }, 2133 "ack-timeout": { 2134 "current-value-decimal": "2.00" 2135 }, 2136 "ack-random-factor": { 2137 "current-value-decimal": "1.50" 2138 } 2139 } 2140 } 2141 } 2143 Figure 22: PUT to Convey the Configuration Parameters 2145 The DOTS server indicates the result of processing the PUT request 2146 using CoAP response codes: 2148 o If the request is missing a mandatory attribute, does not include 2149 a 'sid' Uri-Path, or contains one or more invalid or unknown 2150 parameters, 4.00 (Bad Request) MUST be returned in the response. 2152 o If the DOTS server does not find the 'sid' parameter value 2153 conveyed in the PUT request in its configuration data and if the 2154 DOTS server has accepted the configuration parameters, then a 2155 response code 2.01 (Created) MUST be returned in the response. 2157 o If the DOTS server finds the 'sid' parameter value conveyed in the 2158 PUT request in its configuration data and if the DOTS server has 2159 accepted the updated configuration parameters, 2.04 (Changed) MUST 2160 be returned in the response. 2162 o If any of the 'heartbeat-interval', 'missing-hb-allowed', 'max- 2163 retransmit', 'target-protocol', 'ack-timeout', and 'ack-random- 2164 factor' attribute values are not acceptable to the DOTS server, 2165 4.22 (Unprocessable Entity) MUST be returned in the response. 2166 Upon receipt of this error code, the DOTS client SHOULD retrieve 2167 the maximum and minimum attribute values acceptable to the DOTS 2168 server (Section 4.5.1). 2170 The DOTS client may re-try and send the PUT request with updated 2171 attribute values acceptable to the DOTS server. 2173 A DOTS client may issue a GET message with 'sid' Uri-Path parameter 2174 to retrieve the negotiated configuration. The response does not need 2175 to include 'sid' in its message body. 2177 4.5.3. Configuration Freshness and Notifications 2179 Max-Age Option (Section 5.10.5 of [RFC7252]) SHOULD be returned by a 2180 DOTS server to associate a validity time with a configuration it 2181 sends. This feature allows the update of the configuration data if a 2182 change occurs at the DOTS server side. For example, the new 2183 configuration may instruct a DOTS client to cease heartbeats or 2184 reduce heartbeat frequency. 2186 It is NOT RECOMMENDED to return a Max-Age Option set to 0. 2188 Returning a Max-Age Option set to 2**32-1 is equivalent to 2189 associating an infinite lifetime with the configuration. 2191 If a non-zero value of Max-Age Option is received by a DOTS client, 2192 it MUST issue a GET request with 'sid' Uri-Path parameter to retrieve 2193 the current and acceptable configuration before the expiry of the 2194 value enclosed in the Max-Age option. This request is considered by 2195 the client and the server as a means to refresh the configuration 2196 parameters for the signal channel. When a DDoS attack is active, 2197 refresh requests MUST NOT be sent by DOTS clients and the DOTS server 2198 MUST NOT terminate the (D)TLS session after the expiry of the value 2199 returned in Max-Age Option. 2201 If Max-Age Option is not returned in a response, the DOTS client 2202 initiates GET requests to refresh the configuration parameters each 2203 60 seconds (Section 5.10.5 of [RFC7252]). To prevent such overload, 2204 it is RECOMMENDED that DOTS servers return a Max-Age Option in GET 2205 responses. Considerations related to which value to use and how such 2206 value is set, are implementation- and deployment-specific. 2208 If an Observe Option set to 0 is included in the configuration 2209 request, the DOTS server sends notifications of any configuration 2210 change (Section 4.2 of [RFC7641]). 2212 If a DOTS server detects that a misbehaving DOTS client does not 2213 contact the DOTS server after the expiry of Max-Age and retrieve the 2214 signal channel configuration data, it MAY terminate the (D)TLS 2215 session. A (D)TLS session is terminated by the receipt of an 2216 authenticated message that closes the connection (e.g., a fatal alert 2217 (Section 6 of [RFC8446])). 2219 4.5.4. Delete DOTS Signal Channel Session Configuration 2221 A DELETE request is used to delete the installed DOTS signal channel 2222 session configuration data (Figure 23). 2224 Header: DELETE (Code=0.04) 2225 Uri-Path: ".well-known" 2226 Uri-Path: "dots" 2227 Uri-Path: "config" 2228 Uri-Path: "sid=123" 2230 Figure 23: Delete Configuration 2232 The DOTS server resets the DOTS signal channel session configuration 2233 back to the default values and acknowledges a DOTS client's request 2234 to remove the DOTS signal channel session configuration using 2.02 2235 (Deleted) response code. 2237 Upon bootstrapping or reboot, a DOTS client MAY send a DELETE request 2238 to set the configuration parameters to default values. Such a 2239 request does not include any 'sid'. 2241 4.6. Redirected Signaling 2243 Redirected DOTS signaling is discussed in detail in Section 3.2.2 of 2244 [I-D.ietf-dots-architecture]. 2246 If a DOTS server wants to redirect a DOTS client to an alternative 2247 DOTS server for a signal session, then the response code 5.03 2248 (Service Unavailable) will be returned in the response to the DOTS 2249 client. 2251 The DOTS server can return the error response code 5.03 in response 2252 to a request from the DOTS client or convey the error response code 2253 5.03 in a unidirectional notification response from the DOTS server. 2255 The DOTS server in the error response conveys the alternate DOTS 2256 server's FQDN, and the alternate DOTS server's IP address(es) values 2257 in the CBOR body (Figure 24). 2259 { 2260 "ietf-dots-signal-channel:redirected-signal": { 2261 "alt-server": "string", 2262 "alt-server-record": [ 2263 "string" 2264 ] 2265 } 2267 Figure 24: Redirected Server Error Response Body Schema 2269 The parameters are described below: 2271 alt-server: FQDN of an alternate DOTS server. 2273 This is a mandatory attribute. 2275 alt-server-record: A list of IP addresses of an alternate DOTS 2276 server. 2278 This is an optional attribute. 2280 The DOTS server returns the Time to live (TTL) of the alternate DOTS 2281 server in a Max-Age Option. That is, the time interval that the 2282 alternate DOTS server may be cached for use by a DOTS client. A Max- 2283 Age Option set to 2**32-1 is equivalent to receiving an infinite TTL. 2284 This value means that the alternate DOTS server is to be used until 2285 the alternate DOTS server redirects the traffic with another 5.03 2286 response which encloses an alternate server. 2288 A Max-Age Option set to '0' may be returned for redirecting 2289 mitigation requests. Such value means that the redirection applies 2290 only for the mitigation request in progress. Returning short TTL in 2291 a Max-Age Option may adversely impact DOTS clients on slow links. 2292 Returning short values should be avoided under such conditions. 2294 If the alternate DOTS server TTL has expired, the DOTS client MUST 2295 use the DOTS server(s), that was provisioned using means discussed in 2296 Section 4.1. This fall back mechanism is triggered immediately upon 2297 expiry of the TTL, except when a DDoS attack is active. 2299 Requests issued by misbehaving DOTS clients which do not honor the 2300 TTL conveyed in the Max-Age Option or react to explicit re-direct 2301 messages can be rejected by DOTS servers. 2303 Figure 25 shows a 5.03 response example to convey the DOTS alternate 2304 server 'alt-server.example' together with its IP addresses 2305 2001:db8:6401::1 and 2001:db8:6401::2. 2307 { 2308 "ietf-dots-signal-channel:redirected-signal": { 2309 "alt-server": "alt-server.example", 2310 "alt-server-record": [ 2311 "2001:db8:6401::1", 2312 "2001:db8:6401::2" 2313 ] 2314 } 2316 Figure 25: Example of Redirected Server Error Response Body 2318 When the DOTS client receives 5.03 response with an alternate server 2319 included, it considers the current request as failed, but SHOULD try 2320 re-sending the request to the alternate DOTS server. During a DDoS 2321 attack, the DNS server may be the target of another DDoS attack, 2322 alternate DOTS server's IP addresses conveyed in the 5.03 response 2323 help the DOTS client skip DNS lookup of the alternate DOTS server, at 2324 the cost of trusting the first DOTS server to provide accurate 2325 information. The DOTS client can then try to establish a UDP or a 2326 TCP session with the alternate DOTS server. The DOTS client MAY 2327 implement a method to construct IPv4-embedded IPv6 addresses 2328 [RFC6052]; this is required to handle the scenario where an IPv6-only 2329 DOTS client communicates with an IPv4-only alternate DOTS server. 2331 If the DOTS client has been redirected to a DOTS server to which it 2332 has already communicated with within the last five (5) minutes, it 2333 MUST ignore the redirection and try to contact other DOTS servers 2334 listed in the local configuration or discovered using dynamic means 2335 such as DHCP or SRV procedures. It is RECOMMENDED that DOTS clients 2336 support means to alert administrators about redirect loops. 2338 4.7. Heartbeat Mechanism 2340 To provide an indication of signal health and distinguish an 'idle' 2341 signal channel from a 'disconnected' or 'defunct' session, the DOTS 2342 agent sends a heartbeat over the signal channel to maintain its half 2343 of the channel. The DOTS agent similarly expects a heartbeat from 2344 its peer DOTS agent, and may consider a session terminated in the 2345 prolonged absence of a peer agent heartbeat. Concretely, while the 2346 communication between the DOTS agents is otherwise quiescent, the 2347 DOTS client will probe the DOTS server to ensure it has maintained 2348 cryptographic state and vice versa. Such probes can also keep 2349 firewalls and/or stateful translators bindings alive. This probing 2350 reduces the frequency of establishing a new handshake when a DOTS 2351 signal needs to be conveyed to the DOTS server. 2353 DOTS servers MAY trigger their heartbeat requests immediately after 2354 receiving heartbeat probes from peer DOTS clients. As a reminder, it 2355 is the responsibility of DOTS clients to ensure that on-path 2356 translators/firewalls are maintaining a binding so that the same 2357 external IP address and/or port number is retained for the DOTS 2358 signal channel session. 2360 In case of a massive DDoS attack that saturates the incoming link(s) 2361 to the DOTS client, all traffic from the DOTS server to the DOTS 2362 client will likely be dropped, although the DOTS server receives 2363 heartbeat requests in addition to DOTS messages sent by the DOTS 2364 client. In this scenario, the DOTS agents MUST behave differently to 2365 handle message transmission and DOTS signal channel session 2366 liveliness during link saturation: 2368 o The DOTS client MUST NOT consider the DOTS signal channel session 2369 terminated even after a maximum 'missing-hb-allowed' threshold is 2370 reached. The DOTS client SHOULD keep on using the current DOTS 2371 signal channel session to send heartbeat requests over it, so that 2372 the DOTS server knows the DOTS client has not disconnected the 2373 DOTS signal channel session. 2375 After the maximum 'missing-hb-allowed' threshold is reached, the 2376 DOTS client SHOULD try to resume the (D)TLS session. The DOTS 2377 client SHOULD send mitigation requests over the current DOTS 2378 signal channel session, and in parallel, for example, try to 2379 resume the (D)TLS session or use 0-RTT mode in DTLS 1.3 to 2380 piggyback the mitigation request in the ClientHello message. 2382 As soon as the link is no longer saturated, if traffic from the 2383 DOTS server reaches the DOTS client over the current DOTS signal 2384 channel session, the DOTS client can stop (D)TLS session 2385 resumption or if (D)TLS session resumption is successful then 2386 disconnect the current DOTS signal channel session. 2388 o If the DOTS server does not receive any traffic from the peer DOTS 2389 client, then the DOTS server sends heartbeat requests to the DOTS 2390 client and after maximum 'missing-hb-allowed' threshold is 2391 reached, the DOTS server concludes the session is disconnected. 2393 In DOTS over UDP, heartbeat messages MUST be exchanged between the 2394 DOTS agents using the "CoAP Ping" mechanism defined in Section 4.2 of 2395 [RFC7252]. Concretely, the DOTS agent sends an Empty Confirmable 2396 message and the peer DOTS agent will respond by sending a Reset 2397 message. 2399 In DOTS over TCP, heartbeat messages MUST be exchanged between the 2400 DOTS agents using the Ping and Pong messages specified in Section 5.4 2401 of [RFC8323]. That is, the DOTS agent sends a Ping message and the 2402 peer DOTS agent would respond by sending a single Pong message. 2404 5. DOTS Signal Channel YANG Modules 2406 This document defines a YANG [RFC7950] module for DOTS mitigation 2407 scope, DOTS signal channel session configuration data, and DOTS 2408 redirection signalling. 2410 This YANG module (ietf-dots-signal-channel) defines the DOTS client 2411 interaction with the DOTS server as seen by the DOTS client. A DOTS 2412 server is allowed to update the non-configurable 'ro' entities in the 2413 responses. This YANG module is not intended to be used via NETCONF/ 2414 RESTCONF for DOTS server management purposes; such module is out of 2415 the scope of this document. It serves only to provide a data model 2416 and encoding, but not a management data model. 2418 A companion YANG module is defined to include a collection of types 2419 defined by IANA: "iana-dots-signal-channel" (Section 5.2). 2421 5.1. Tree Structure 2423 This document defines the YANG module "ietf-dots-signal-channel" 2424 (Section 5.3), which has the following tree structure. A DOTS signal 2425 message can either be a mitigation or a configuration message. 2427 module: ietf-dots-signal-channel 2428 +--rw dots-signal 2429 +--rw (message-type)? 2430 +--:(mitigation-scope) 2431 | +--rw scope* [cuid mid] 2432 | +--rw cdid? string 2433 | +--rw cuid string 2434 | +--rw mid uint32 2435 | +--rw target-prefix* inet:ip-prefix 2436 | +--rw target-port-range* [lower-port] 2437 | | +--rw lower-port inet:port-number 2438 | | +--rw upper-port? inet:port-number 2439 | +--rw target-protocol* uint8 2440 | +--rw target-fqdn* inet:domain-name 2441 | +--rw target-uri* inet:uri 2442 | +--rw alias-name* string 2443 | +--rw lifetime? int32 2444 | +--rw trigger-mitigation? boolean 2445 | +--ro mitigation-start? uint64 2446 | +--ro status? iana-signal:status 2447 | +--ro conflict-information 2448 | | +--ro conflict-status? iana-signal:conflict-status 2449 | | +--ro conflict-cause? iana-signal:conflict-cause 2450 | | +--ro retry-timer? uint32 2451 | | +--ro conflict-scope 2452 | | +--ro target-prefix* inet:ip-prefix 2453 | | +--ro target-port-range* [lower-port] 2454 | | | +--ro lower-port inet:port-number 2455 | | | +--ro upper-port? inet:port-number 2456 | | +--ro target-protocol* uint8 2457 | | +--ro target-fqdn* inet:domain-name 2458 | | +--ro target-uri* inet:uri 2459 | | +--ro alias-name* string 2460 | | +--ro acl-list* [acl-name] 2461 | | | +--ro acl-name 2462 | | | | -> /ietf-data:dots-data/dots-client/acls/ 2463 | | | | acl/name 2464 | | | +--ro acl-type? 2465 | | | -> /ietf-data:dots-data/dots-client/acls/ 2466 | | | acl/type 2467 | | +--ro mid? -> ../../../mid 2468 | +--ro bytes-dropped? yang:zero-based-counter64 2469 | +--ro bps-dropped? yang:zero-based-counter64 2470 | +--ro pkts-dropped? yang:zero-based-counter64 2471 | +--ro pps-dropped? yang:zero-based-counter64 2472 | +--rw attack-status? iana-signal:attack-status 2473 +--:(signal-config) 2474 | +--rw sid uint32 2475 | +--rw mitigating-config 2476 | | +--rw heartbeat-interval 2477 | | | +--ro max-value? uint16 2478 | | | +--ro min-value? uint16 2479 | | | +--rw current-value? uint16 2480 | | +--rw missing-hb-allowed 2481 | | | +--ro max-value? uint16 2482 | | | +--ro min-value? uint16 2483 | | | +--rw current-value? uint16 2484 | | +--rw max-retransmit 2485 | | | +--ro max-value? uint16 2486 | | | +--ro min-value? uint16 2487 | | | +--rw current-value? uint16 2488 | | +--rw ack-timeout 2489 | | | +--ro max-value-decimal? decimal64 2490 | | | +--ro min-value-decimal? decimal64 2491 | | | +--rw current-value-decimal? decimal64 2492 | | +--rw ack-random-factor 2493 | | +--ro max-value-decimal? decimal64 2494 | | +--ro min-value-decimal? decimal64 2495 | | +--rw current-value-decimal? decimal64 2496 | +--rw idle-config 2497 | +--rw heartbeat-interval 2498 | | +--ro max-value? uint16 2499 | | +--ro min-value? uint16 2500 | | +--rw current-value? uint16 2501 | +--rw missing-hb-allowed 2502 | | +--ro max-value? uint16 2503 | | +--ro min-value? uint16 2504 | | +--rw current-value? uint16 2505 | +--rw max-retransmit 2506 | | +--ro max-value? uint16 2507 | | +--ro min-value? uint16 2508 | | +--rw current-value? uint16 2509 | +--rw ack-timeout 2510 | | +--ro max-value-decimal? decimal64 2511 | | +--ro min-value-decimal? decimal64 2512 | | +--rw current-value-decimal? decimal64 2513 | +--rw ack-random-factor 2514 | +--ro max-value-decimal? decimal64 2515 | +--ro min-value-decimal? decimal64 2516 | +--rw current-value-decimal? decimal64 2517 +--:(redirected-signal) 2518 +--ro alt-server string 2519 +--ro alt-server-record* inet:ip-address 2521 5.2. IANA DOTS Signal Channel YANG Module 2523 file "iana-dots-signal-channel@2019-01-17.yang" 2524 module iana-dots-signal-channel { 2525 yang-version 1.1; 2526 namespace "urn:ietf:params:xml:ns:yang:iana-dots-signal-channel"; 2527 prefix iana-signal; 2529 organization 2530 "IANA"; 2531 contact 2532 "Internet Assigned Numbers Authority 2534 Postal: ICANN 2535 12025 Waterfront Drive, Suite 300 2536 Los Angeles, CA 90094-2536 2537 United States of America 2538 Tel: +1 310 301 5800 2539 "; 2540 description 2541 "This module contains a collection of YANG data types defined 2542 by IANA and used for DOTS signal channel protocol. 2544 Copyright (c) 2019 IETF Trust and the persons identified as 2545 authors of the code. All rights reserved. 2547 Redistribution and use in source and binary forms, with or 2548 without modification, is permitted pursuant to, and subject 2549 to the license terms contained in, the Simplified BSD License 2550 set forth in Section 4.c of the IETF Trust's Legal Provisions 2551 Relating to IETF Documents 2552 (http://trustee.ietf.org/license-info). 2554 This version of this YANG module is part of RFC XXXX; see 2555 the RFC itself for full legal notices."; 2557 revision 2019-01-17 { 2558 description 2559 "Initial revision."; 2560 reference 2561 "RFC XXXX: Distributed Denial-of-Service Open Threat 2562 Signaling (DOTS) Signal Channel Specification"; 2563 } 2565 typedef status { 2566 type enumeration { 2567 enum attack-mitigation-in-progress { 2568 value 1; 2569 description 2570 "Attack mitigation setup is in progress (e.g., changing 2571 the network path to re-route the inbound traffic 2572 to DOTS mitigator)."; 2573 } 2574 enum attack-successfully-mitigated { 2575 value 2; 2576 description 2577 "Attack is being successfully mitigated (e.g., traffic 2578 is redirected to a DDoS mitigator and attack 2579 traffic is dropped or blackholed)."; 2580 } 2581 enum attack-stopped { 2582 value 3; 2583 description 2584 "Attack has stopped and the DOTS client can 2585 withdraw the mitigation request."; 2586 } 2587 enum attack-exceeded-capability { 2588 value 4; 2589 description 2590 "Attack has exceeded the mitigation provider 2591 capability."; 2592 } 2593 enum dots-client-withdrawn-mitigation { 2594 value 5; 2595 description 2596 "DOTS client has withdrawn the mitigation 2597 request and the mitigation is active but 2598 terminating."; 2599 } 2600 enum attack-mitigation-terminated { 2601 value 6; 2602 description 2603 "Attack mitigation is now terminated."; 2604 } 2605 enum attack-mitigation-withdrawn { 2606 value 7; 2607 description 2608 "Attack mitigation is withdrawn."; 2609 } 2610 enum attack-mitigation-signal-loss { 2611 value 8; 2612 description 2613 "Attack mitigation will be triggered 2614 for the mitigation request only when 2615 the DOTS signal channel session is lost."; 2616 } 2617 } 2618 description 2619 "Enumeration for status reported by the DOTS server."; 2620 } 2621 typedef conflict-status { 2622 type enumeration { 2623 enum request-inactive-other-active { 2624 value 1; 2625 description 2626 "DOTS Server has detected conflicting mitigation 2627 requests from different DOTS clients. 2628 This mitigation request is currently inactive 2629 until the conflicts are resolved. Another 2630 mitigation request is active."; 2631 } 2632 enum request-active { 2633 value 2; 2634 description 2635 "DOTS Server has detected conflicting mitigation 2636 requests from different DOTS clients. 2637 This mitigation request is currently active."; 2638 } 2639 enum all-requests-inactive { 2640 value 3; 2641 description 2642 "DOTS Server has detected conflicting mitigation 2643 requests from different DOTS clients. All 2644 conflicting mitigation requests are inactive."; 2645 } 2646 } 2647 description 2648 "Enumeration for conflict status."; 2649 } 2651 typedef conflict-cause { 2652 type enumeration { 2653 enum overlapping-targets { 2654 value 1; 2655 description 2656 "Overlapping targets. conflict-scope provides 2657 more details about the exact conflict."; 2658 } 2659 enum conflict-with-acceptlist { 2660 value 2; 2661 description 2662 "Conflicts with an existing accept-list. 2664 This code is returned when the DDoS mitigation 2665 detects that some of the source addresses/prefixes 2666 listed in the accept-list ACLs are actually 2667 attacking the target."; 2668 } 2669 enum cuid-collision { 2670 value 3; 2671 description 2672 "Conflicts with the cuid used by another 2673 DOTS client."; 2674 } 2675 } 2676 description 2677 "Enumeration for conflict causes."; 2678 } 2680 typedef attack-status { 2681 type enumeration { 2682 enum under-attack { 2683 value 1; 2684 description 2685 "The DOTS client determines that it is still under 2686 attack."; 2687 } 2688 enum attack-successfully-mitigated { 2689 value 2; 2690 description 2691 "The DOTS client determines that the attack is 2692 successfully mitigated."; 2693 } 2694 } 2695 description 2696 "Enumeration for attack status codes."; 2697 } 2698 } 2699 2701 5.3. IETF DOTS Signal Channel YANG Module 2703 This module uses the common YANG types defined in [RFC6991] and types 2704 defined in [I-D.ietf-dots-data-channel]. 2706 file "ietf-dots-signal-channel@2019-01-17.yang" 2707 module ietf-dots-signal-channel { 2708 yang-version 1.1; 2709 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel"; 2710 prefix signal; 2712 import ietf-inet-types { 2713 prefix inet; 2714 reference "Section 4 of RFC 6991"; 2715 } 2716 import ietf-yang-types { 2717 prefix yang; 2718 reference "Section 3 of RFC 6991"; 2719 } 2720 import ietf-dots-data-channel { 2721 prefix ietf-data; 2722 reference 2723 "RFC YYYY: Distributed Denial-of-Service Open Threat Signaling 2724 (DOTS) Data Channel Specification"; 2725 } 2726 import iana-dots-signal-channel { 2727 prefix iana-signal; 2728 } 2730 organization 2731 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 2732 contact 2733 "WG Web: 2734 WG List: 2736 Editor: Konda, Tirumaleswar Reddy 2737 2739 Editor: Mohamed Boucadair 2740 2742 Author: Prashanth Patil 2743 2745 Author: Andrew Mortensen 2746 2748 Author: Nik Teague 2749 "; 2750 description 2751 "This module contains YANG definition for the signaling 2752 messages exchanged between a DOTS client and a DOTS server. 2754 Copyright (c) 2019 IETF Trust and the persons identified as 2755 authors of the code. All rights reserved. 2757 Redistribution and use in source and binary forms, with or 2758 without modification, is permitted pursuant to, and subject 2759 to the license terms contained in, the Simplified BSD License 2760 set forth in Section 4.c of the IETF Trust's Legal Provisions 2761 Relating to IETF Documents 2762 (http://trustee.ietf.org/license-info). 2764 This version of this YANG module is part of RFC XXXX; see 2765 the RFC itself for full legal notices."; 2767 revision 2019-01-17 { 2768 description 2769 "Initial revision."; 2770 reference 2771 "RFC XXXX: Distributed Denial-of-Service Open Threat 2772 Signaling (DOTS) Signal Channel Specification"; 2773 } 2775 /* 2776 * Groupings 2777 */ 2779 grouping mitigation-scope { 2780 description 2781 "Specifies the scope of the mitigation request."; 2782 list scope { 2783 key "cuid mid"; 2784 description 2785 "The scope of the request."; 2786 leaf cdid { 2787 type string; 2788 description 2789 "The cdid should be included by a server-domain 2790 DOTS gateway to propagate the client domain 2791 identification information from the 2792 gateway's client-facing-side to the gateway's 2793 server-facing-side, and from the gateway's 2794 server-facing-side to the DOTS server. 2796 It may be used by the final DOTS server 2797 for policy enforcement purposes."; 2798 } 2799 leaf cuid { 2800 type string; 2801 description 2802 "A unique identifier that is 2803 generated by a DOTS client to prevent 2804 request collisions. It is expected that the 2805 cuid will remain consistent throughout the 2806 lifetime of the DOTS client."; 2807 } 2808 leaf mid { 2809 type uint32; 2810 description 2811 "Mitigation request identifier. 2813 This identifier must be unique for each mitigation 2814 request bound to the DOTS client."; 2815 } 2816 uses ietf-data:target; 2817 leaf-list alias-name { 2818 type string; 2819 description 2820 "An alias name that points to a resource."; 2821 } 2822 leaf lifetime { 2823 type int32; 2824 units "seconds"; 2825 default "3600"; 2826 description 2827 "Indicates the lifetime of the mitigation request. 2829 A lifetime of '0' in a mitigation request is an 2830 invalid value. 2832 A lifetime of negative one (-1) indicates indefinite 2833 lifetime for the mitigation request."; 2834 } 2835 leaf trigger-mitigation { 2836 type boolean; 2837 default "true"; 2838 description 2839 "If set to 'false', DDoS mitigation will not be 2840 triggered unless the DOTS signal channel 2841 session is lost."; 2842 } 2843 leaf mitigation-start { 2844 type uint64; 2845 config false; 2846 description 2847 "Mitigation start time is represented in seconds 2848 relative to 1970-01-01T00:00:00Z in UTC time."; 2849 } 2850 leaf status { 2851 type iana-signal:status; 2852 config false; 2853 description 2854 "Indicates the status of a mitigation request. 2855 It must be included in responses only."; 2856 } 2857 container conflict-information { 2858 config false; 2859 description 2860 "Indicates that a conflict is detected. 2862 Must only be used for responses."; 2863 leaf conflict-status { 2864 type iana-signal:conflict-status; 2865 description 2866 "Indicates the conflict status."; 2867 } 2868 leaf conflict-cause { 2869 type iana-signal:conflict-cause; 2870 description 2871 "Indicates the cause of the conflict."; 2872 } 2873 leaf retry-timer { 2874 type uint32; 2875 units "seconds"; 2876 description 2877 "The DOTS client must not re-send the 2878 same request that has a conflict before the expiry of 2879 this timer."; 2880 } 2881 container conflict-scope { 2882 description 2883 "Provides more information about the conflict scope."; 2884 uses ietf-data:target { 2885 when "../conflict-cause = 'overlapping-targets'"; 2886 } 2887 leaf-list alias-name { 2888 when "../../conflict-cause = 'overlapping-targets'"; 2889 type string; 2890 description 2891 "Conflicting alias-name."; 2892 } 2893 list acl-list { 2894 when "../../conflict-cause = 'conflict-with-acceptlist'"; 2895 key "acl-name"; 2896 description 2897 "List of conflicting ACLs as defined in the DOTS data 2898 channel. These ACLs are uniquely defined by 2899 cuid and acl-name."; 2900 leaf acl-name { 2901 type leafref { 2902 path "/ietf-data:dots-data/ietf-data:dots-client/" 2903 +"ietf-data:acls/ietf-data:acl/ietf-data:name"; 2904 } 2905 description 2906 "Reference to the conflicting ACL name bound to 2907 a DOTS client."; 2908 } 2909 leaf acl-type { 2910 type leafref { 2911 path "/ietf-data:dots-data/ietf-data:dots-client/" 2912 +ietf-data:acls/ietf-data:acl/ietf-data:type"; 2913 } 2914 description 2915 "Reference to the conflicting ACL type bound to 2916 a DOTS client."; 2917 } 2918 } 2919 leaf mid { 2920 when "../../conflict-cause = 'overlapping-targets'"; 2921 type leafref { 2922 path "../../../mid"; 2923 } 2924 description 2925 "Reference to the conflicting 'mid' bound to 2926 the same DOTS client."; 2927 } 2928 } 2929 } 2930 leaf bytes-dropped { 2931 type yang:zero-based-counter64; 2932 units "bytes"; 2933 config false; 2934 description 2935 "The total dropped byte count for the mitigation 2936 request since the attack mitigation is triggered. 2937 The count wraps around when it reaches the maximum value 2938 of counter64 for dropped bytes."; 2939 } 2940 leaf bps-dropped { 2941 type yang:zero-based-counter64; 2942 config false; 2943 description 2944 "The average number of dropped bits per second for 2945 the mitigation request since the attack 2946 mitigation is triggered. This should be a 2947 five-minute average."; 2948 } 2949 leaf pkts-dropped { 2950 type yang:zero-based-counter64; 2951 config false; 2952 description 2953 "The total number of dropped packet count for the 2954 mitigation request since the attack mitigation is 2955 triggered. The count wraps around when it reaches 2956 the maximum value of counter64 for dropped packets."; 2957 } 2958 leaf pps-dropped { 2959 type yang:zero-based-counter64; 2960 config false; 2961 description 2962 "The average number of dropped packets per second 2963 for the mitigation request since the attack 2964 mitigation is triggered. This should be a 2965 five-minute average."; 2966 } 2967 leaf attack-status { 2968 type iana-signal:attack-status; 2969 description 2970 "Indicates the status of an attack as seen by the 2971 DOTS client."; 2972 } 2973 } 2974 } 2976 grouping config-parameters { 2977 description 2978 "Subset of DOTS signal channel session configuration."; 2979 container heartbeat-interval { 2980 description 2981 "DOTS agents regularly send heartbeats to each other 2982 after mutual authentication is successfully 2983 completed in order to keep the DOTS signal channel 2984 open."; 2985 leaf max-value { 2986 type uint16; 2987 units "seconds"; 2988 config false; 2989 description 2990 "Maximum acceptable heartbeat-interval value."; 2991 } 2992 leaf min-value { 2993 type uint16; 2994 units "seconds"; 2995 config false; 2996 description 2997 "Minimum acceptable heartbeat-interval value."; 2998 } 2999 leaf current-value { 3000 type uint16; 3001 units "seconds"; 3002 default "30"; 3003 description 3004 "Current heartbeat-interval value. 3006 '0' means that heartbeat mechanism is deactivated."; 3007 } 3008 } 3009 container missing-hb-allowed { 3010 description 3011 "Maximum number of missing heartbeats allowed."; 3012 leaf max-value { 3013 type uint16; 3014 config false; 3015 description 3016 "Maximum acceptable missing-hb-allowed value."; 3017 } 3018 leaf min-value { 3019 type uint16; 3020 config false; 3021 description 3022 "Minimum acceptable missing-hb-allowed value."; 3023 } 3024 leaf current-value { 3025 type uint16; 3026 default "5"; 3027 description 3028 "Current missing-hb-allowed value."; 3029 } 3030 } 3031 container max-retransmit { 3032 description 3033 "Maximum number of retransmissions of a Confirmable 3034 message."; 3035 leaf max-value { 3036 type uint16; 3037 config false; 3038 description 3039 "Maximum acceptable max-retransmit value."; 3040 } 3041 leaf min-value { 3042 type uint16; 3043 config false; 3044 description 3045 "Minimum acceptable max-retransmit value."; 3046 } 3047 leaf current-value { 3048 type uint16; 3049 default "3"; 3050 description 3051 "Current max-retransmit value."; 3052 } 3053 } 3054 container ack-timeout { 3055 description 3056 "Initial retransmission timeout value."; 3057 leaf max-value-decimal { 3058 type decimal64 { 3059 fraction-digits 2; 3060 } 3061 units "seconds"; 3062 config false; 3063 description 3064 "Maximum ack-timeout value."; 3065 } 3066 leaf min-value-decimal { 3067 type decimal64 { 3068 fraction-digits 2; 3069 } 3070 units "seconds"; 3071 config false; 3072 description 3073 "Minimum ack-timeout value."; 3074 } 3075 leaf current-value-decimal { 3076 type decimal64 { 3077 fraction-digits 2; 3078 } 3079 units "seconds"; 3080 default "2"; 3081 description 3082 "Current ack-timeout value."; 3083 } 3084 } 3085 container ack-random-factor { 3086 description 3087 "Random factor used to influence the timing of 3088 retransmissions."; 3089 leaf max-value-decimal { 3090 type decimal64 { 3091 fraction-digits 2; 3092 } 3093 config false; 3094 description 3095 "Maximum acceptable ack-random-factor value."; 3096 } 3097 leaf min-value-decimal { 3098 type decimal64 { 3099 fraction-digits 2; 3100 } 3101 config false; 3102 description 3103 "Minimum acceptable ack-random-factor value."; 3104 } 3105 leaf current-value-decimal { 3106 type decimal64 { 3107 fraction-digits 2; 3108 } 3109 default "1.5"; 3110 description 3111 "Current ack-random-factor value."; 3112 } 3113 } 3114 } 3116 grouping signal-config { 3117 description 3118 "DOTS signal channel session configuration."; 3119 leaf sid { 3120 type uint32; 3121 mandatory true; 3122 description 3123 "An identifier for the DOTS signal channel 3124 session configuration data."; 3125 } 3126 container mitigating-config { 3127 description 3128 "Configuration parameters to use when a mitigation 3129 is active."; 3130 uses config-parameters; 3131 } 3132 container idle-config { 3133 description 3134 "Configuration parameters to use when no mitigation 3135 is active."; 3136 uses config-parameters; 3137 } 3138 } 3140 grouping redirected-signal { 3141 description 3142 "Grouping for the redirected signaling."; 3143 leaf alt-server { 3144 type string; 3145 config false; 3146 mandatory true; 3147 description 3148 "FQDN of an alternate server."; 3149 } 3150 leaf-list alt-server-record { 3151 type inet:ip-address; 3152 config false; 3153 description 3154 "List of records for the alternate server."; 3155 } 3156 } 3158 /* 3159 * Main Container for DOTS Signal Channel 3160 */ 3162 container dots-signal { 3163 description 3164 "Main container for DOTS signal message. 3166 A DOTS signal message can be a mitigation, a configuration, 3167 or a redirected signal message."; 3168 choice message-type { 3169 description 3170 "Can be a mitigation, a configuration, or a redirect 3171 message."; 3172 case mitigation-scope { 3173 description 3174 "Mitigation scope of a mitigation message."; 3175 uses mitigation-scope; 3176 } 3177 case signal-config { 3178 description 3179 "Configuration message."; 3180 uses signal-config; 3181 } 3182 case redirected-signal { 3183 description 3184 "Redirected signaling."; 3185 uses redirected-signal; 3186 } 3187 } 3188 } 3189 } 3190 3192 6. YANG/JSON Mapping Parameters to CBOR 3194 All parameters in the payload of the DOTS signal channel MUST be 3195 mapped to CBOR types as shown in Table 4 and are assigned an integer 3196 key to save space. The CBOR key values are divided into two types: 3197 comprehension-required and comprehension-optional. DOTS agents can 3198 safely ignore comprehension-optional values they don't understand, 3199 but cannot successfully process a request if it contains 3200 comprehension-required values that are not understood. The 4.00 3201 response SHOULD include a diagnostic payload describing the unknown 3202 comprehension-required CBOR key values. The initial set of CBOR key 3203 values defined in this specification are of type comprehension- 3204 required. 3206 +----------------------+-------------+-----+---------------+--------+ 3207 | Parameter Name | YANG | CBOR| CBOR Major | JSON | 3208 | | Type | Key | Type & | Type | 3209 | | | | Information | | 3210 +----------------------+-------------+-----+---------------+--------+ 3211 | ietf-dots-signal-cha | | | | | 3212 | nnel:mitigation-scope| container | 1 | 5 map | Object | 3213 | scope | list | 2 | 4 array | Array | 3214 | cdid | string | 3 | 3 text string | String | 3215 | cuid | string | 4 | 3 text string | String | 3216 | mid | uint32 | 5 | 0 unsigned | Number | 3217 | target-prefix | leaf-list | 6 | 4 array | Array | 3218 | | inet: | | | | 3219 | | ip-prefix | | 3 text string | String | 3220 | target-port-range | list | 7 | 4 array | Array | 3221 | lower-port | inet: | | | | 3222 | | port-number| 8 | 0 unsigned | Number | 3223 | upper-port | inet: | | | | 3224 | | port-number| 9 | 0 unsigned | Number | 3225 | target-protocol | leaf-list | 10 | 4 array | Array | 3226 | | uint8 | | 0 unsigned | Number | 3227 | target-fqdn | leaf-list | 11 | 4 array | Array | 3228 | | inet: | | | | 3229 | | domain-name| | 3 text string | String | 3230 | target-uri | leaf-list | 12 | 4 array | Array | 3231 | | inet:uri | | 3 text string | String | 3232 | alias-name | leaf-list | 13 | 4 array | Array | 3233 | | string | | 3 text string | String | 3234 | lifetime | int32 | 14 | 0 unsigned | Number | 3235 | | | | 1 negative | Number | 3236 | mitigation-start | uint64 | 15 | 0 unsigned | String | 3237 | status | enumeration | 16 | 0 unsigned | String | 3238 | conflict-information | container | 17 | 5 map | Object | 3239 | conflict-status | enumeration | 18 | 0 unsigned | String | 3240 | conflict-cause | enumeration | 19 | 0 unsigned | String | 3241 | retry-timer | uint32 | 20 | 0 unsigned | Number | 3242 | conflict-scope | container | 21 | 5 map | Object | 3243 | acl-list | list | 22 | 4 array | Array | 3244 | acl-name | leafref | 23 | 3 text string | String | 3245 | acl-type | leafref | 24 | 3 text string | String | 3246 | bytes-dropped | yang:zero- | | | | 3247 | | based- | | | | 3248 | | counter64 | 25 | 0 unsigned | String | 3249 | bps-dropped | yang:zero- | | | | 3250 | | based- | | | | 3251 | | counter64 | 26 | 0 unsigned | String | 3252 | pkts-dropped | yang:zero- | | | | 3253 | | based- | | | | 3254 | | counter64 | 27 | 0 unsigned | String | 3255 | pps-dropped | yang:zero- | | | | 3256 | | based- | | | | 3257 | | counter64 | 28 | 0 unsigned | String | 3258 | attack-status | enumeration | 29 | 0 unsigned | String | 3259 | ietf-dots-signal- | | | | | 3260 | channel:signal-config| container | 30 | 5 map | Object | 3261 | sid | uint32 | 31 | 0 unsigned | Number | 3262 | mitigating-config | container | 32 | 5 map | Object | 3263 | heartbeat-interval | container | 33 | 5 map | Object | 3264 | max-value | uint16 | 34 | 0 unsigned | Number | 3265 | min-value | uint16 | 35 | 0 unsigned | Number | 3266 | current-value | uint16 | 36 | 0 unsigned | Number | 3267 | missing-hb-allowed | container | 37 | 5 map | Object | 3268 | max-retransmit | container | 38 | 5 map | Object | 3269 | ack-timeout | container | 39 | 5 map | Object | 3270 | ack-random-factor | container | 40 | 5 map | Object | 3271 | max-value-decimal | decimal64 | 41 | 6 tag 4 | | 3272 | | | | [-2, integer]| String | 3273 | min-value-decimal | decimal64 | 42 | 6 tag 4 | | 3274 | | | | [-2, integer]| String | 3275 | current-value-decimal| decimal64 | 43 | 6 tag 4 | | 3276 | | | | [-2, integer]| String | 3277 | idle-config | container | 44 | 5 map | Object | 3278 | trigger-mitigation | boolean | 45 | 7 bits 20 | False | 3279 | | | | 7 bits 21 | True | 3280 | ietf-dots-signal-cha | | | | | 3281 |nnel:redirected-signal| container | 46 | 5 map | Object | 3282 | alt-server | string | 47 | 3 text string | String | 3283 | alt-server-record | leaf-list | 48 | 4 array | Array | 3284 | | inet: | | | | 3285 | | ip-address | | 3 text string | String | 3286 +----------------------+-------------+-----+---------------+--------+ 3288 Table 4: CBOR Key Values Used in DOTS Signal Channel Messages & Their 3289 Mappings to JSON and YANG 3291 7. (D)TLS Protocol Profile and Performance Considerations 3293 7.1. (D)TLS Protocol Profile 3295 This section defines the (D)TLS protocol profile of DOTS signal 3296 channel over (D)TLS and DOTS data channel over TLS. 3298 There are known attacks on (D)TLS, such as man-in-the-middle and 3299 protocol downgrade attacks. These are general attacks on (D)TLS and, 3300 as such, they are not specific to DOTS over (D)TLS; refer to the 3301 (D)TLS RFCs for discussion of these security issues. DOTS agents 3302 MUST adhere to the (D)TLS implementation recommendations and security 3303 considerations of [RFC7525] except with respect to (D)TLS version. 3304 Since DOTS signal channel encryption relying upon (D)TLS is virtually 3305 a green-field deployment, DOTS agents MUST implement only (D)TLS 1.2 3306 or later. 3308 When a DOTS client is configured with a domain name of the DOTS 3309 server, and connects to its configured DOTS server, the server may 3310 present it with a PKIX certificate. In order to ensure proper 3311 authentication, a DOTS client MUST verify the entire certification 3312 path per [RFC5280]. The DOTS client additionally uses [RFC6125] 3313 validation techniques to compare the domain name with the certificate 3314 provided. 3316 A key challenge to deploying DOTS is the provisioning of DOTS 3317 clients, including the distribution of keying material to DOTS 3318 clients to enable the required mutual authentication of DOTS agents. 3319 Enrollment over Secure Transport (EST) [RFC7030] defines a method of 3320 certificate enrollment by which domains operating DOTS servers may 3321 provide DOTS clients with all the necessary cryptographic keying 3322 material, including a private key and a certificate to authenticate 3323 themselves. One deployment option is DOTS clients behave as EST 3324 clients for certificate enrollment from an EST server provisioned by 3325 the mitigation provider. This document does not specify which EST or 3326 other mechanism the DOTS client uses to achieve initial enrollment. 3328 The Server Name Indication (SNI) extension [RFC6066] defines a 3329 mechanism for a client to tell a (D)TLS server the name of the server 3330 it wants to contact. This is a useful extension for hosting 3331 environments where multiple virtual servers are reachable over a 3332 single IP address. The DOTS client may or may not know if it is 3333 interacting with a DOTS server in a virtual server hosting 3334 environment, so the DOTS client SHOULD include the DOTS server FQDN 3335 in the SNI extension. 3337 Implementations compliant with this profile MUST implement all of the 3338 following items: 3340 o DTLS record replay detection (Section 3.3 of [RFC6347]) or an 3341 equivalent mechanism to protect against replay attacks. 3343 o DTLS session resumption without server-side state to resume 3344 session and convey the DOTS signal. 3346 o At least one of raw public keys [RFC7250] or PSK handshake 3347 [RFC4279] with (EC)DHE key exchange which reduces the size of the 3348 ServerHello, and can be used by DOTS agents that cannot obtain 3349 certificates. 3351 Implementations compliant with this profile SHOULD implement all of 3352 the following items to reduce the delay required to deliver a DOTS 3353 signal channel message: 3355 o TLS False Start [RFC7918] which reduces round-trips by allowing 3356 the TLS client's second flight of messages (ChangeCipherSpec) to 3357 also contain the DOTS signal. TLS False Start is formally defined 3358 for use with TLS, but the same technique is applicable to DTLS as 3359 well. 3361 o Cached Information Extension [RFC7924] which avoids transmitting 3362 the server's certificate and certificate chain if the client has 3363 cached that information from a previous TLS handshake. 3365 Compared to UDP, DOTS signal channel over TCP requires an additional 3366 round-trip time (RTT) of latency to establish a TCP connection. DOTS 3367 implementations are encouraged to implement TCP Fast Open [RFC7413] 3368 to eliminate that RTT. 3370 7.2. (D)TLS 1.3 Considerations 3372 TLS 1.3 provides critical latency improvements for connection 3373 establishment over TLS 1.2. The DTLS 1.3 protocol 3374 [I-D.ietf-tls-dtls13] is based upon the TLS 1.3 protocol and provides 3375 equivalent security guarantees. (D)TLS 1.3 provides two basic 3376 handshake modes the DOTS signal channel can take advantage of: 3378 o A full handshake mode in which a DOTS client can send a DOTS 3379 mitigation request message after one round trip and the DOTS 3380 server immediately responds with a DOTS mitigation response. This 3381 assumes no packet loss is experienced. 3383 o 0-RTT mode in which the DOTS client can authenticate itself and 3384 send DOTS mitigation request messages in the first message, thus 3385 reducing handshake latency. 0-RTT only works if the DOTS client 3386 has previously communicated with that DOTS server, which is very 3387 likely with the DOTS signal channel. 3389 The DOTS client has to establish a (D)TLS session with the DOTS 3390 server during 'idle' time and share a PSK. 3392 During a DDoS attack, the DOTS client can use the (D)TLS session 3393 to convey the DOTS mitigation request message and, if there is no 3394 response from the server after multiple retries, the DOTS client 3395 can resume the (D)TLS session in 0-RTT mode using PSK. 3397 DOTS servers that support (D)TLS 1.3 MAY allow DOTS clients to 3398 send early data (0-RTT). DOTS clients MUST NOT send "CoAP Ping" 3399 as early data; such messages MUST be rejected by DOTS servers. 3400 Section 8 of [RFC8446] discusses some mechanisms to implement to 3401 limit the impact of replay attacks on 0-RTT data. If the DOTS 3402 server accepts 0-RTT, it MUST implement one of these mechanisms to 3403 prevent replay at the TLS layer. A DOTS server can reject 0-RTT 3404 by sending a TLS HelloRetryRequest. 3406 The DOTS signal channel messages sent as early data by the DOTS 3407 client are idempotent requests. As a reminder, the Message ID 3408 (Section 3 of [RFC7252]) is changed each time a new CoAP request 3409 is sent, and the Token (Section 5.3.1 of [RFC7252]) is randomized 3410 in each CoAP request. The DOTS server(s) MUST use the Message ID 3411 and the Token in the DOTS signal channel message to detect replay 3412 of early data at the application layer, and accept 0-RTT data at 3413 most once from the same DOTS client. This anti-replay defense 3414 requires sharing the Message ID and the Token in the 0-RTT data 3415 between DOTS servers in the DOTS server domain. DOTS servers do 3416 not rely on transport coordinates to identify DOTS peers. As 3417 specified in Section 4.4.1, DOTS servers couple the DOTS signal 3418 channel sessions using the DOTS client identity and optionally the 3419 'cdid' parameter value. Furthermore, 'mid' value is monotonically 3420 increased by the DOTS client for each mitigation request, 3421 attackers replaying mitigation requests with lower numeric 'mid' 3422 values and overlapping scopes with mitigation requests having 3423 higher numeric 'mid' values will be rejected systematically by the 3424 DOTS server. Likewise, 'sid' value is monotonically increased by 3425 the DOTS client for each configuration request (Section 4.5.2), 3426 attackers replaying configuration requests with lower numeric 3427 'sid' values will be rejected by the DOTS server if it maintains a 3428 higher numeric 'sid' value for this DOTS client. 3430 Owing to the aforementioned protections, all DOTS signal channel 3431 requests are safe to transmit in TLS 1.3 as early data. Refer to 3432 [I-D.boucadair-dots-earlydata] for more details. 3434 A simplified TLS 1.3 handshake with 0-RTT DOTS mitigation request 3435 message exchange is shown in Figure 26. 3437 DOTS Client DOTS Server 3439 ClientHello 3440 (0-RTT DOTS signal message) 3441 --------> 3442 ServerHello 3443 {EncryptedExtensions} 3444 {Finished} 3445 <-------- [DOTS signal message] 3446 (end_of_early_data) 3447 {Finished} --------> 3448 [DOTS signal message] <-------> [DOTS signal message] 3450 Note that: 3451 () Indicates messages protected 0-RTT keys 3452 {} Indicates messages protected using handshake keys 3453 [] Indicates messages protected using 1-RTT keys 3455 Figure 26: A Simplified TLS 1.3 Handshake with 0-RTT 3457 7.3. DTLS MTU and Fragmentation 3459 To avoid DOTS signal message fragmentation and the subsequent 3460 decreased probability of message delivery, DOTS agents MUST ensure 3461 that the DTLS record MUST fit within a single datagram. If the path 3462 MTU is not known to the DOTS server, an IP MTU of 1280 bytes SHOULD 3463 be assumed. The DOTS client must consider the amount of record 3464 expansion expected by the DTLS processing when calculating the size 3465 of CoAP message that fits within the path MTU. Path MTU MUST be 3466 greater than or equal to [CoAP message size + DTLS 1.2 overhead of 13 3467 octets + authentication overhead of the negotiated DTLS cipher suite 3468 + block padding] (Section 4.1.1.1 of [RFC6347]). If the total 3469 request size exceeds the path MTU then the DOTS client MUST split the 3470 DOTS signal into separate messages; for example, the list of 3471 addresses in the 'target-prefix' parameter could be split into 3472 multiple lists and each list conveyed in a new PUT request. 3474 Implementation Note: DOTS choice of message size parameters works 3475 well with IPv6 and with most of today's IPv4 paths. However, with 3476 IPv4, it is harder to safely make sure that there is no IP 3477 fragmentation. If the IPv4 path MTU is unknown, implementations may 3478 want to limit themselves to more conservative IPv4 datagram sizes 3479 such as 576 bytes, as per [RFC0791]. IP packets whose size does not 3480 exceed 576 bytes should never need to be fragmented: therefore, 3481 sending a maximum of 500 bytes of DOTS signal over a UDP datagram 3482 will generally avoid IP fragmentation. 3484 8. Mutual Authentication of DOTS Agents & Authorization of DOTS Clients 3486 (D)TLS based upon client certificate can be used for mutual 3487 authentication between DOTS agents. If, for example, a DOTS gateway 3488 is involved, DOTS clients and DOTS gateways must perform mutual 3489 authentication; only authorized DOTS clients are allowed to send DOTS 3490 signals to a DOTS gateway. The DOTS gateway and the DOTS server must 3491 perform mutual authentication; a DOTS server only allows DOTS signal 3492 channel messages from an authorized DOTS gateway, thereby creating a 3493 two-link chain of transitive authentication between the DOTS client 3494 and the DOTS server. 3496 The DOTS server should support certificate-based client 3497 authentication. The DOTS client should respond to the DOTS server's 3498 TLS CertificateRequest message with the PKIX certificate held by the 3499 DOTS client. DOTS client certificate validation must be performed as 3500 per [RFC5280] and the DOTS client certificate must conform to the 3501 [RFC5280] certificate profile. If a DOTS client does not support TLS 3502 client certificate authentication, it must support pre-shared key 3503 based or raw public key based client authentication. 3505 +-----------------------------------------------+ 3506 | example.com domain +---------+ | 3507 | | AAA | | 3508 | +---------------+ | Server | | 3509 | | Application | +------+--+ | 3510 | | server +<-----------------+ ^ | 3511 | | (DOTS client) | | | | 3512 | +---------------+ | | | 3513 | V V | example.net domain 3514 | +-----+----+--+ | +---------------+ 3515 | +--------------+ | | | | | 3516 | | Guest +<-----x----->+ DOTS +<------>+ DOTS | 3517 | | (DOTS client)| | gateway | | | server | 3518 | +--------------+ | | | | | 3519 | +----+--------+ | +---------------+ 3520 | ^ | 3521 | | | 3522 | +----------------+ | | 3523 | | DDoS detector | | | 3524 | | (DOTS client) +<---------------+ | 3525 | +----------------+ | 3526 +-----------------------------------------------+ 3528 Figure 27: Example of Authentication and Authorization of DOTS Agents 3530 In the example depicted in Figure 27, the DOTS gateway and DOTS 3531 clients within the 'example.com' domain mutually authenticate. After 3532 the DOTS gateway validates the identity of a DOTS client, it 3533 communicates with the AAA server in the 'example.com' domain to 3534 determine if the DOTS client is authorized to request DDoS 3535 mitigation. If the DOTS client is not authorized, a 4.01 3536 (Unauthorized) is returned in the response to the DOTS client. In 3537 this example, the DOTS gateway only allows the application server and 3538 DDoS attack detector to request DDoS mitigation, but does not permit 3539 the user of type 'guest' to request DDoS mitigation. 3541 Also, DOTS gateways and servers located in different domains must 3542 perform mutual authentication (e.g., using certificates). A DOTS 3543 server will only allow a DOTS gateway with a certificate for a 3544 particular domain to request mitigation for that domain. In 3545 reference to Figure 27, the DOTS server only allows the DOTS gateway 3546 to request mitigation for 'example.com' domain and not for other 3547 domains. 3549 9. IANA Considerations 3551 9.1. DOTS Signal Channel UDP and TCP Port Number 3553 IANA is requested to assign the port number TBD to the DOTS signal 3554 channel protocol for both UDP and TCP from the "Service Name and 3555 Transport Protocol Port Number Registry" available at 3556 https://www.iana.org/assignments/service-names-port-numbers/service- 3557 names-port-numbers.xhtml. 3559 The assignment of port number 4646 is strongly suggested, as 4646 is 3560 the ASCII decimal value for ".." (DOTS). 3562 9.2. Well-Known 'dots' URI 3564 This document requests IANA to register the 'dots' well-known URI 3565 (Table 5) in the Well-Known URIs registry 3566 (https://www.iana.org/assignments/well-known-uris/well-known- 3567 uris.xhtml) as defined by [RFC5785]: 3569 +----------+----------------+---------------------+-----------------+ 3570 | URI | Change | Specification | Related | 3571 | suffix | controller | document(s) | information | 3572 +----------+----------------+---------------------+-----------------+ 3573 | dots | IETF | [RFCXXXX] | None | 3574 +----------+----------------+---------------------+-----------------+ 3576 Table 5: 'dots' well-known URI 3578 9.3. Media Type Registration 3580 This document requests IANA to register the "application/dots+cbor" 3581 media type in the "Media Types" registry [IANA.MediaTypes] in the 3582 manner described in [RFC6838], which can be used to indicate that the 3583 content is a DOTS signal channel object: 3585 o Type name: application 3586 o Subtype name: dots+cbor 3587 o Required parameters: N/A 3588 o Optional parameters: N/A 3589 o Encoding considerations: binary 3590 o Security considerations: See the Security Considerations section 3591 of [RFCXXXX] 3592 o Interoperability considerations: N/A 3593 o Published specification: [RFCXXXX] 3594 o Applications that use this media type: DOTS agents sending DOTS 3595 messages over CoAP over (D)TLS. 3596 o Fragment identifier considerations: N/A 3597 o Additional information: 3599 Magic number(s): N/A 3600 File extension(s): N/A 3601 Macintosh file type code(s): N/A 3602 o Person & email address to contact for further information: 3603 IESG, iesg@ietf.org 3604 o Intended usage: COMMON 3605 o Restrictions on usage: none 3606 o Author: See Authors' Addresses section. 3607 o Change controller: IESG 3608 o Provisional registration? No 3610 9.4. CoAP Content-Formats Registration 3612 This document requests IANA to register the CoAP Content-Format ID 3613 for the "application/dots+cbor" media type in the "CoAP Content- 3614 Formats" registry [IANA.CoAP.Content-Formats] (0-255 range): 3616 o Media Type: application/dots+cbor 3617 o Encoding: - 3618 o Id: TBD1 3619 o Reference: [RFCXXXX] 3621 9.5. CBOR Tag Registration 3623 This section defines the DOTS CBOR tag as another means for 3624 applications to declare that a CBOR data structure is a DOTS signal 3625 channel object. Its use is optional and is intended for use in cases 3626 in which this information would not otherwise be known. DOTS CBOR 3627 tag is not required for DOTS signal channel protocol version 3628 specified in this document. If present, the DOTS tag MUST prefix a 3629 DOTS signal channel object. 3631 This document requests IANA to register the DOTS signal channel CBOR 3632 tag in the "CBOR Tags" registry [IANA.CBOR.Tags] using the 24-255 3633 range: 3635 o CBOR Tag: TBD2 (please assign the same value as the Content- 3636 Format) 3637 o Data Item: DDoS Open Threat Signaling (DOTS) signal channel object 3638 o Semantics: DDoS Open Threat Signaling (DOTS) signal channel 3639 object, as defined in [RFCXXXX] 3640 o Description of Semantics: [RFCXXXX] 3642 9.6. DOTS Signal Channel Protocol Registry 3644 The document requests IANA to create a new registry, entitled "DOTS 3645 Signal Channel Registry". The following sections define sub- 3646 registries. 3648 9.6.1. DOTS Signal Channel CBOR Key Values Sub-Registry 3650 The document requests IANA to create a new sub-registry, entitled 3651 "DOTS Signal Channel CBOR Key Values". 3653 The structure of this sub-registry is provided in Section 9.6.1.1. 3654 Section 9.6.1.2 provides how the registry is initially populated with 3655 the values in Table 4. 3657 9.6.1.1. Registration Template 3659 Parameter name: 3660 Parameter name as used in the DOTS signal channel. 3662 CBOR Key Value: 3663 Key value for the parameter. The key value MUST be an integer in 3664 the 1-65535 range. The key values of the comprehension-required 3665 range (0x0001 - 0x3FFF) and of the comprehension-optional range 3666 (0x8000 - 0xBFFF) are assigned by IETF Review (Section 4.8 of 3667 [RFC8126]). The key values of the comprehension-optional range 3668 (0x4000 - 0x7FFF) are assigned by Specification Required 3669 (Section 4.6 of [RFC8126]) and of the comprehension-optional range 3670 (0xC000 - 0xFFFF) are reserved for Private Use (Section 4.1 of 3671 [RFC8126]). 3673 Registration requests for the 0x4000 - 0x7FFF range are evaluated 3674 after a three-week review period on the dots-signal-reg- 3675 review@ietf.org mailing list, on the advice of one or more 3676 Designated Experts. However, to allow for the allocation of 3677 values prior to publication, the Designated Experts may approve 3678 registration once they are satisfied that such a specification 3679 will be published. New registration requests should be sent in 3680 the form of an email to the review mailing list; the request 3681 should use an appropriate subject (e.g., "Request to register CBOR 3682 Key Value for DOTS: example"). IANA will only accept new 3683 registrations from the Designated Experts, and will check that 3684 review was requested on the mailing list in accordance with these 3685 procedures. 3687 Within the review period, the Designated Experts will either 3688 approve or deny the registration request, communicating this 3689 decision to the review list and IANA. Denials should include an 3690 explanation and, if applicable, suggestions as to how to make the 3691 request successful. Registration requests that are undetermined 3692 for a period longer than 21 days can be brought to the IESG's 3693 attention (using the iesg@ietf.org mailing list) for resolution. 3695 Criteria that should be applied by the Designated Experts includes 3696 determining whether the proposed registration duplicates existing 3697 functionality, whether it is likely to be of general applicability 3698 or whether it is useful only for a single use case, and whether 3699 the registration description is clear. IANA must only accept 3700 registry updates to the 0x4000 - 0x7FFF range from the Designated 3701 Experts and should direct all requests for registration to the 3702 review mailing list. It is suggested that multiple Designated 3703 Experts be appointed. In cases where a registration decision 3704 could be perceived as creating a conflict of interest for a 3705 particular Expert, that Expert should defer to the judgment of the 3706 other Experts. 3708 CBOR Major Type: 3709 CBOR Major type and optional tag for the parameter. 3711 Change Controller: 3712 For Standards Track RFCs, list the "IESG". For others, give the 3713 name of the responsible party. Other details (e.g., email 3714 address) may also be included. 3716 Specification Document(s): 3717 Reference to the document or documents that specify the parameter, 3718 preferably including URIs that can be used to retrieve copies of 3719 the documents. An indication of the relevant sections may also be 3720 included but is not required. 3722 9.6.1.2. Initial Sub-Registry Content 3724 +----------------------+-------+-------+------------+---------------+ 3725 | Parameter Name | CBOR | CBOR | Change | Specification | 3726 | | Key | Major | Controller | Document(s) | 3727 | | Value | Type | | | 3728 +----------------------+-------+-------+------------+---------------+ 3729 | ietf-dots-signal-chan| 1 | 5 | IESG | [RFCXXXX] | 3730 | nel:mitigation-scope | | | | | 3731 | scope | 2 | 4 | IESG | [RFCXXXX] | 3732 | cdid | 3 | 3 | IESG | [RFCXXXX] | 3733 | cuid | 4 | 3 | IESG | [RFCXXXX] | 3734 | mid | 5 | 0 | IESG | [RFCXXXX] | 3735 | target-prefix | 6 | 4 | IESG | [RFCXXXX] | 3736 | target-port-range | 7 | 4 | IESG | [RFCXXXX] | 3737 | lower-port | 8 | 0 | IESG | [RFCXXXX] | 3738 | upper-port | 9 | 0 | IESG | [RFCXXXX] | 3739 | target-protocol | 10 | 4 | IESG | [RFCXXXX] | 3740 | target-fqdn | 11 | 4 | IESG | [RFCXXXX] | 3741 | target-uri | 12 | 4 | IESG | [RFCXXXX] | 3742 | alias-name | 13 | 4 | IESG | [RFCXXXX] | 3743 | lifetime | 14 | 0/1 | IESG | [RFCXXXX] | 3744 | mitigation-start | 15 | 0 | IESG | [RFCXXXX] | 3745 | status | 16 | 0 | IESG | [RFCXXXX] | 3746 | conflict-information | 17 | 5 | IESG | [RFCXXXX] | 3747 | conflict-status | 18 | 0 | IESG | [RFCXXXX] | 3748 | conflict-cause | 19 | 0 | IESG | [RFCXXXX] | 3749 | retry-timer | 20 | 0 | IESG | [RFCXXXX] | 3750 | conflict-scope | 21 | 5 | IESG | [RFCXXXX] | 3751 | acl-list | 22 | 4 | IESG | [RFCXXXX] | 3752 | acl-name | 23 | 3 | IESG | [RFCXXXX] | 3753 | acl-type | 24 | 3 | IESG | [RFCXXXX] | 3754 | bytes-dropped | 25 | 0 | IESG | [RFCXXXX] | 3755 | bps-dropped | 26 | 0 | IESG | [RFCXXXX] | 3756 | pkts-dropped | 27 | 0 | IESG | [RFCXXXX] | 3757 | pps-dropped | 28 | 0 | IESG | [RFCXXXX] | 3758 | attack-status | 29 | 0 | IESG | [RFCXXXX] | 3759 | ietf-dots-signal- | 30 | 5 | IESG | [RFCXXXX] | 3760 | channel:signal-config| | | | | 3761 | sid | 31 | 0 | IESG | [RFCXXXX] | 3762 | mitigating-config | 32 | 5 | IESG | [RFCXXXX] | 3763 | heartbeat-interval | 33 | 5 | IESG | [RFCXXXX] | 3764 | min-value | 34 | 0 | IESG | [RFCXXXX] | 3765 | max-value | 35 | 0 | IESG | [RFCXXXX] | 3766 | current-value | 36 | 0 | IESG | [RFCXXXX] | 3767 | missing-hb-allowed | 37 | 5 | IESG | [RFCXXXX] | 3768 | max-retransmit | 38 | 5 | IESG | [RFCXXXX] | 3769 | ack-timeout | 39 | 5 | IESG | [RFCXXXX] | 3770 | ack-random-factor | 40 | 5 | IESG | [RFCXXXX] | 3771 | min-value-decimal | 41 | 6tag4 | IESG | [RFCXXXX] | 3772 | max-value-decimal | 42 | 6tag4 | IESG | [RFCXXXX] | 3773 | current-value- | 43 | 6tag4 | IESG | [RFCXXXX] | 3774 | decimal | | | | | 3775 | idle-config | 44 | 5 | IESG | [RFCXXXX] | 3776 | trigger-mitigation | 45 | 7 | IESG | [RFCXXXX] | 3777 | ietf-dots-signal-chan| 46 | 5 | IESG | [RFCXXXX] | 3778 | nel:redirected-signal| | | | | 3779 | alt-server | 47 | 3 | IESG | [RFCXXXX] | 3780 | alt-server-record | 48 | 4 | IESG | [RFCXXXX] | 3781 +----------------------+-------+-------+------------+---------------+ 3783 Table 6: Initial DOTS Signal Channel CBOR Key Values Registry 3785 9.6.2. Status Codes Sub-Registry 3787 The document requests IANA to create a new sub-registry, entitled 3788 "DOTS Signal Channel Status Codes". Codes in this registry are used 3789 as valid values of 'status' parameter. 3791 The registry is initially populated with the following values: 3793 +-----+----------------------------------+--------------+-----------+ 3794 | Cod | Label | Description | Reference | 3795 | e | | | | 3796 +-----+----------------------------------+--------------+-----------+ 3797 | 1 | attack-mitigation-in-progress | Attack | [RFCXXXX] | 3798 | | | mitigation | | 3799 | | | setup is in | | 3800 | | | progress | | 3801 | | | (e.g., | | 3802 | | | changing the | | 3803 | | | network path | | 3804 | | | to redirect | | 3805 | | | the inbound | | 3806 | | | traffic to a | | 3807 | | | DOTS | | 3808 | | | mitigator). | | 3809 | 2 | attack-successfully-mitigated | Attack is | [RFCXXXX] | 3810 | | | being | | 3811 | | | successfully | | 3812 | | | mitigated | | 3813 | | | (e.g., | | 3814 | | | traffic is | | 3815 | | | redirected | | 3816 | | | to a DDoS | | 3817 | | | mitigator | | 3818 | | | and attack | | 3819 | | | traffic is | | 3820 | | | dropped). | | 3821 | 3 | attack-stopped | Attack has | [RFCXXXX] | 3822 | | | stopped and | | 3823 | | | the DOTS | | 3824 | | | client can | | 3825 | | | withdraw the | | 3826 | | | mitigation | | 3827 | | | request. | | 3828 | 4 | attack-exceeded-capability | Attack has | [RFCXXXX] | 3829 | | | exceeded the | | 3830 | | | mitigation | | 3831 | | | provider | | 3832 | | | capability. | | 3833 | 5 | dots-client-withdrawn-mitigation | DOTS client | [RFCXXXX] | 3834 | | | has | | 3835 | | | withdrawn | | 3836 | | | the | | 3837 | | | mitigation | | 3838 | | | request and | | 3839 | | | the | | 3840 | | | mitigation | | 3841 | | | is active | | 3842 | | | but | | 3843 | | | terminating. | | 3844 | 6 | attack-mitigation-terminated | Attack | [RFCXXXX] | 3845 | | | mitigation | | 3846 | | | is now | | 3847 | | | terminated. | | 3848 | 7 | attack-mitigation-withdrawn | Attack | [RFCXXXX] | 3849 | | | mitigation | | 3850 | | | is | | 3851 | | | withdrawn. | | 3852 | 8 | attack-mitigation-signal-loss | Attack | [RFCXXXX] | 3853 | | | mitigation | | 3854 | | | will be | | 3855 | | | triggered | | 3856 | | | for the | | 3857 | | | mitigation | | 3858 | | | request only | | 3859 | | | when the | | 3860 | | | DOTS signal | | 3861 | | | channel | | 3862 | | | session is | | 3863 | | | lost. | | 3864 +-----+----------------------------------+--------------+-----------+ 3865 New codes can be assigned via Standards Action [RFC8126]. 3867 9.6.3. Conflict Status Codes Sub-Registry 3869 The document requests IANA to create a new sub-registry, entitled 3870 "DOTS Signal Channel Conflict Status Codes". Codes in this registry 3871 are used as valid values of 'conflict-status' parameter. 3873 The registry is initially populated with the following values: 3875 +------+-------------------------------+----------------+-----------+ 3876 | Code | Label | Description | Reference | 3877 +------+-------------------------------+----------------+-----------+ 3878 | 1 | request-inactive-other-active | DOTS server | [RFCXXXX] | 3879 | | | has detected | | 3880 | | | conflicting | | 3881 | | | mitigation | | 3882 | | | requests from | | 3883 | | | different DOTS | | 3884 | | | clients. This | | 3885 | | | mitigation | | 3886 | | | request is | | 3887 | | | currently | | 3888 | | | inactive until | | 3889 | | | the conflicts | | 3890 | | | are resolved. | | 3891 | | | Another | | 3892 | | | mitigation | | 3893 | | | request is | | 3894 | | | active. | | 3895 | 2 | request-active | DOTS server | [RFCXXXX] | 3896 | | | has detected | | 3897 | | | conflicting | | 3898 | | | mitigation | | 3899 | | | requests from | | 3900 | | | different DOTS | | 3901 | | | clients. This | | 3902 | | | mitigation | | 3903 | | | request is | | 3904 | | | currently | | 3905 | | | active. | | 3906 | 3 | all-requests-inactive | DOTS server | [RFCXXXX] | 3907 | | | has detected | | 3908 | | | conflicting | | 3909 | | | mitigation | | 3910 | | | requests from | | 3911 | | | different DOTS | | 3912 | | | clients. All | | 3913 | | | conflicting | | 3914 | | | mitigation | | 3915 | | | requests are | | 3916 | | | inactive. | | 3917 +------+-------------------------------+----------------+-----------+ 3919 New codes can be assigned via Standards Action [RFC8126]. 3921 9.6.4. Conflict Cause Codes Sub-Registry 3923 The document requests IANA to create a new sub-registry, entitled 3924 "DOTS Signal Channel Conflict Cause Codes". Codes in this registry 3925 are used as valid values of 'conflict-cause' parameter. 3927 The registry is initially populated with the following values: 3929 +------+--------------------------+---------------------+-----------+ 3930 | Code | Label | Description | Reference | 3931 +------+--------------------------+---------------------+-----------+ 3932 | 1 | overlapping-targets | Overlapping | [RFCXXXX] | 3933 | | | targets. | | 3934 | 2 | conflict-with-acceptlist | Conflicts with an | [RFCXXXX] | 3935 | | | existing accept- | | 3936 | | | list. This code is | | 3937 | | | returned when the | | 3938 | | | DDoS mitigation | | 3939 | | | detects source | | 3940 | | | addresses/prefixes | | 3941 | | | in the accept- | | 3942 | | | listed ACLs are | | 3943 | | | attacking the | | 3944 | | | target. | | 3945 | 3 | cuid-collision | CUID Collision. | [RFCXXXX] | 3946 | | | This code is | | 3947 | | | returned when a | | 3948 | | | DOTS client uses a | | 3949 | | | 'cuid' that is | | 3950 | | | already used by | | 3951 | | | another DOTS | | 3952 | | | client. | | 3953 +------+--------------------------+---------------------+-----------+ 3955 New codes can be assigned via Standards Action [RFC8126]. 3957 9.6.5. Attack Status Codes Sub-Registry 3959 The document requests IANA to create a new sub-registry, entitled 3960 "DOTS Signal Channel Attack Status Codes". Codes in this registry 3961 are used as valid values of 'attack-status' parameter. 3963 The registry is initially populated with the following values: 3965 +------+-------------------------------+----------------+-----------+ 3966 | Code | Label | Description | Reference | 3967 +------+-------------------------------+----------------+-----------+ 3968 | 1 | under-attack | The DOTS | [RFCXXXX] | 3969 | | | client | | 3970 | | | determines | | 3971 | | | that it is | | 3972 | | | still under | | 3973 | | | attack. | | 3974 | 2 | attack-successfully-mitigated | The DOTS | [RFCXXXX] | 3975 | | | client | | 3976 | | | determines | | 3977 | | | that the | | 3978 | | | attack is | | 3979 | | | successfully | | 3980 | | | mitigated. | | 3981 +------+-------------------------------+----------------+-----------+ 3983 New codes can be assigned via Standards Action [RFC8126]. 3985 9.7. DOTS Signal Channel YANG Modules 3987 This document requests IANA to register the following URIs in the 3988 "ns" subregistry within the "IETF XML Registry" [RFC3688]: 3990 URI: urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel 3991 Registrant Contact: The IESG. 3992 XML: N/A; the requested URI is an XML namespace. 3994 URI: urn:ietf:params:xml:ns:yang:iana-dots-signal-channel 3995 Registrant Contact: IANA. 3996 XML: N/A; the requested URI is an XML namespace. 3998 This document requests IANA to register the following YANG modules in 3999 the "YANG Module Names" subregistry [RFC7950] within the "YANG 4000 Parameters" registry. 4002 name: ietf-signal 4003 namespace: urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel 4004 maintained by IANA: N 4005 prefix: signal 4006 reference: RFC XXXX 4008 name: iana-signal 4009 namespace: urn:ietf:params:xml:ns:yang:iana-dots-signal-channel 4010 maintained by IANA: Y 4011 prefix: iana-signal 4012 reference: RFC XXXX 4014 This document defines the initial version of the IANA-maintained 4015 iana-dots-signal-channel YANG module. IANA is requested to add this 4016 note: 4018 Status, conflict status, conflict cause, and attack status values 4019 must not be directly added to the iana-dots-signal-channel YANG 4020 module. They must instead be respectively added to the "DOTS 4021 Status Codes", "DOTS Conflict Status Codes", "DOTS Conflict Cause 4022 Codes", and "DOTS Attack Status Codes" registries. 4024 When a 'status', 'conflict-status', 'conflict-cause', or 'attack- 4025 status' value is respectively added to the "DOTS Status Codes", "DOTS 4026 Conflict Status Codes", "DOTS Conflict Cause Codes", or "DOTS Attack 4027 Status Codes" registry, a new "enum" statement must be added to the 4028 iana-dots-signal-channel YANG module. The following "enum" 4029 statement, and substatements thereof, should be defined: 4031 "enum": Replicates the label from the registry. 4033 "value": Contains the IANA-assigned value corresponding to the 4034 'status', 'conflict-status', 'conflict-cause', or 4035 'attack-status'. 4037 "description": Replicates the description from the registry. 4039 "reference": Replicates the reference from the registry and add the 4040 title of the document. 4042 When the iana-dots-signal-channel YANG module is updated, a new 4043 "revision" statement must be added in front of the existing revision 4044 statements. 4046 IANA is requested to add this note to "DOTS Status Codes", "DOTS 4047 Conflict Status Codes", "DOTS Conflict Cause Codes", and "DOTS Attack 4048 Status Codes" registries: 4050 When this registry is modified, the YANG module iana-dots-signal- 4051 channel must be updated as defined in [RFCXXXX]. 4053 10. Security Considerations 4055 High-level DOTS security considerations are documented in 4056 [I-D.ietf-dots-requirements] and [I-D.ietf-dots-architecture]. 4058 Authenticated encryption MUST be used for data confidentiality and 4059 message integrity. The interaction between the DOTS agents requires 4060 Datagram Transport Layer Security (DTLS) or Transport Layer Security 4061 (TLS) with a cipher suite offering confidentiality protection, and 4062 the guidance given in [RFC7525] MUST be followed to avoid attacks on 4063 (D)TLS. The (D)TLS protocol profile used for the DOTS signal channel 4064 is specified in Section 7. 4066 If TCP is used between DOTS agents, an attacker may be able to inject 4067 RST packets, bogus application segments, etc., regardless of whether 4068 TLS authentication is used. Because the application data is TLS 4069 protected, this will not result in the application receiving bogus 4070 data, but it will constitute a DoS on the connection. This attack 4071 can be countered by using TCP-AO [RFC5925]. If TCP-AO is used, then 4072 any bogus packets injected by an attacker will be rejected by the 4073 TCP-AO integrity check and therefore will never reach the TLS layer. 4075 An attack vector that can be achieved if the 'cuid' is guessable is a 4076 misbehaving DOTS client from within the client's domain which uses 4077 the 'cuid' of another DOTS client of the domain to delete or alter 4078 active mitigations. For this attack vector to happen, the 4079 misbehaving client needs to pass the security validation checks by 4080 the DOTS server, and eventually the checks of a client-domain DOTS 4081 gateway. 4083 A similar attack can be achieved by a compromised DOTS client which 4084 can sniff the TLS 1.2 handshake, use the client certificate to 4085 identify the 'cuid' used by another DOTS client. This attack is not 4086 possible with TLS 1.3 because most of the TLS handshake is encrypted 4087 and the client certificate is not visible to eavesdroppers. 4089 Rate-limiting DOTS requests, including those with new 'cuid' values, 4090 from the same DOTS client defends against DoS attacks that would 4091 result in varying the 'cuid' to exhaust DOTS server resources. Rate- 4092 limit policies SHOULD be enforced on DOTS gateways (if deployed) and 4093 DOTS servers. 4095 In order to prevent leaking internal information outside a client- 4096 domain, DOTS gateways located in the client-domain SHOULD NOT reveal 4097 the identification information that pertains to internal DOTS clients 4098 (e.g., source IP address, client's hostname) unless explicitly 4099 configured to do so. 4101 DOTS servers MUST verify that requesting DOTS clients are entitled to 4102 trigger actions on a given IP prefix. That is, only actions on IP 4103 resources that belong to the DOTS client' domain MUST be authorized 4104 by a DOTS server. The exact mechanism for the DOTS servers to 4105 validate that the target prefixes are within the scope of the DOTS 4106 client domain is deployment-specific. 4108 The presence of DOTS gateways may lead to infinite forwarding loops, 4109 which is undesirable. To prevent and detect such loops, this 4110 document uses the Hop-Limit Option. 4112 CoAP-specific security considerations are discussed in Section 11 of 4113 [RFC7252], while CBOR-related security considerations are discussed 4114 in Section 8 of [RFC7049]. 4116 11. Contributors 4118 The following individuals have contributed to this document: 4120 o Jon Shallow, NCC Group, Email: jon.shallow@nccgroup.trust 4122 o Mike Geller, Cisco Systems, Inc. 3250 Florida 33309 USA, Email: 4123 mgeller@cisco.com 4125 o Robert Moskowitz, HTT Consulting Oak Park, MI 42837 United States, 4126 Email: rgm@htt-consult.com 4128 o Dan Wing, Email: dwing-ietf@fuggles.com 4130 12. Acknowledgements 4132 Thanks to Christian Jacquenet, Roland Dobbins, Roman D. Danyliw, 4133 Michael Richardson, Ehud Doron, Kaname Nishizuka, Dave Dolson, Liang 4134 Xia, Gilbert Clark, Xialiang Frank, Jim Schaad, Klaus Hartke and 4135 Nesredien Suleiman for the discussion and comments. 4137 The authors would like to give special thanks to Kaname Nishizuka and 4138 Jon Shallow for their efforts in implementing the protocol and 4139 performing interop testing at IETF Hackathons. 4141 Thanks to the core WG for the recommendations on Hop-Limit and 4142 redirect signaling. 4144 Special thanks to Benjamin Kaduk for the detailed AD review. 4146 13. References 4148 13.1. Normative References 4150 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4151 Requirement Levels", BCP 14, RFC 2119, 4152 DOI 10.17487/RFC2119, March 1997, 4153 . 4155 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 4156 DOI 10.17487/RFC3688, January 2004, 4157 . 4159 [RFC4279] Eronen, P., Ed. and H. Tschofenig, Ed., "Pre-Shared Key 4160 Ciphersuites for Transport Layer Security (TLS)", 4161 RFC 4279, DOI 10.17487/RFC4279, December 2005, 4162 . 4164 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 4165 (CIDR): The Internet Address Assignment and Aggregation 4166 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 4167 2006, . 4169 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 4170 (TLS) Protocol Version 1.2", RFC 5246, 4171 DOI 10.17487/RFC5246, August 2008, 4172 . 4174 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 4175 Housley, R., and W. Polk, "Internet X.509 Public Key 4176 Infrastructure Certificate and Certificate Revocation List 4177 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 4178 . 4180 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 4181 Uniform Resource Identifiers (URIs)", RFC 5785, 4182 DOI 10.17487/RFC5785, April 2010, 4183 . 4185 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 4186 Extensions: Extension Definitions", RFC 6066, 4187 DOI 10.17487/RFC6066, January 2011, 4188 . 4190 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 4191 Verification of Domain-Based Application Service Identity 4192 within Internet Public Key Infrastructure Using X.509 4193 (PKIX) Certificates in the Context of Transport Layer 4194 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 4195 2011, . 4197 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 4198 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 4199 January 2012, . 4201 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 4202 RFC 6991, DOI 10.17487/RFC6991, July 2013, 4203 . 4205 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 4206 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 4207 October 2013, . 4209 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 4210 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 4211 Transport Layer Security (TLS) and Datagram Transport 4212 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 4213 June 2014, . 4215 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 4216 Application Protocol (CoAP)", RFC 7252, 4217 DOI 10.17487/RFC7252, June 2014, 4218 . 4220 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 4221 "Recommendations for Secure Use of Transport Layer 4222 Security (TLS) and Datagram Transport Layer Security 4223 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 4224 2015, . 4226 [RFC7641] Hartke, K., "Observing Resources in the Constrained 4227 Application Protocol (CoAP)", RFC 7641, 4228 DOI 10.17487/RFC7641, September 2015, 4229 . 4231 [RFC7918] Langley, A., Modadugu, N., and B. Moeller, "Transport 4232 Layer Security (TLS) False Start", RFC 7918, 4233 DOI 10.17487/RFC7918, August 2016, 4234 . 4236 [RFC7924] Santesson, S. and H. Tschofenig, "Transport Layer Security 4237 (TLS) Cached Information Extension", RFC 7924, 4238 DOI 10.17487/RFC7924, July 2016, 4239 . 4241 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 4242 RFC 7950, DOI 10.17487/RFC7950, August 2016, 4243 . 4245 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 4246 RFC 7951, DOI 10.17487/RFC7951, August 2016, 4247 . 4249 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 4250 the Constrained Application Protocol (CoAP)", RFC 7959, 4251 DOI 10.17487/RFC7959, August 2016, 4252 . 4254 [RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 4255 Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, 4256 March 2017, . 4258 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 4259 Writing an IANA Considerations Section in RFCs", BCP 26, 4260 RFC 8126, DOI 10.17487/RFC8126, June 2017, 4261 . 4263 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 4264 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 4265 May 2017, . 4267 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 4268 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 4269 Application Protocol) over TCP, TLS, and WebSockets", 4270 RFC 8323, DOI 10.17487/RFC8323, February 2018, 4271 . 4273 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 4274 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 4275 . 4277 13.2. Informative References 4279 [I-D.boucadair-dots-earlydata] 4280 Boucadair, M. and R. K, "Using Early Data in DOTS", draft- 4281 boucadair-dots-earlydata-00 (work in progress), January 4282 2019. 4284 [I-D.boucadair-dots-server-discovery] 4285 Boucadair, M., K, R., and P. Patil, "Distributed-Denial- 4286 of-Service Open Threat Signaling (DOTS) Server Discovery", 4287 draft-boucadair-dots-server-discovery-05 (work in 4288 progress), October 2018. 4290 [I-D.ietf-core-comi] 4291 Veillette, M., Stok, P., Pelov, A., and A. Bierman, "CoAP 4292 Management Interface", draft-ietf-core-comi-04 (work in 4293 progress), November 2018. 4295 [I-D.ietf-core-hop-limit] 4296 Boucadair, M., K, R., and J. Shallow, "Constrained 4297 Application Protocol (CoAP) Hop Limit Option", draft-ietf- 4298 core-hop-limit-02 (work in progress), December 2018. 4300 [I-D.ietf-core-yang-cbor] 4301 Veillette, M., Pelov, A., Somaraju, A., Turner, R., and A. 4302 Minaburo, "CBOR Encoding of Data Modeled with YANG", 4303 draft-ietf-core-yang-cbor-07 (work in progress), September 4304 2018. 4306 [I-D.ietf-dots-architecture] 4307 Mortensen, A., Andreasen, F., K, R., Teague, N., Compton, 4308 R., and c. christopher_gray3@cable.comcast.com, 4309 "Distributed-Denial-of-Service Open Threat Signaling 4310 (DOTS) Architecture", draft-ietf-dots-architecture-12 4311 (work in progress), February 2019. 4313 [I-D.ietf-dots-data-channel] 4314 Boucadair, M. and R. K, "Distributed Denial-of-Service 4315 Open Threat Signaling (DOTS) Data Channel Specification", 4316 draft-ietf-dots-data-channel-27 (work in progress), 4317 February 2019. 4319 [I-D.ietf-dots-requirements] 4320 Mortensen, A., K, R., and R. Moskowitz, "Distributed 4321 Denial of Service (DDoS) Open Threat Signaling 4322 Requirements", draft-ietf-dots-requirements-20 (work in 4323 progress), February 2019. 4325 [I-D.ietf-dots-use-cases] 4326 Dobbins, R., Migault, D., Fouant, S., Moskowitz, R., 4327 Teague, N., Xia, L., and K. Nishizuka, "Use cases for DDoS 4328 Open Threat Signaling", draft-ietf-dots-use-cases-17 (work 4329 in progress), January 2019. 4331 [I-D.ietf-tls-dtls13] 4332 Rescorla, E., Tschofenig, H., and N. Modadugu, "The 4333 Datagram Transport Layer Security (DTLS) Protocol Version 4334 1.3", draft-ietf-tls-dtls13-30 (work in progress), 4335 November 2018. 4337 [IANA.CBOR.Tags] 4338 IANA, "Concise Binary Object Representation (CBOR) Tags", 4339 . 4342 [IANA.CoAP.Content-Formats] 4343 IANA, "CoAP Content-Formats", 4344 . 4347 [IANA.MediaTypes] 4348 IANA, "Media Types", 4349 . 4351 [proto_numbers] 4352 "IANA, "Protocol Numbers"", 2011, 4353 . 4355 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 4356 DOI 10.17487/RFC0791, September 1981, 4357 . 4359 [RFC3022] Srisuresh, P. and K. Egevang, "Traditional IP Network 4360 Address Translator (Traditional NAT)", RFC 3022, 4361 DOI 10.17487/RFC3022, January 2001, 4362 . 4364 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 4365 Resource Identifier (URI): Generic Syntax", STD 66, 4366 RFC 3986, DOI 10.17487/RFC3986, January 2005, 4367 . 4369 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 4370 Unique IDentifier (UUID) URN Namespace", RFC 4122, 4371 DOI 10.17487/RFC4122, July 2005, 4372 . 4374 [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram 4375 Congestion Control Protocol (DCCP)", RFC 4340, 4376 DOI 10.17487/RFC4340, March 2006, 4377 . 4379 [RFC4732] Handley, M., Ed., Rescorla, E., Ed., and IAB, "Internet 4380 Denial-of-Service Considerations", RFC 4732, 4381 DOI 10.17487/RFC4732, December 2006, 4382 . 4384 [RFC4787] Audet, F., Ed. and C. Jennings, "Network Address 4385 Translation (NAT) Behavioral Requirements for Unicast 4386 UDP", BCP 127, RFC 4787, DOI 10.17487/RFC4787, January 4387 2007, . 4389 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 4390 RFC 4960, DOI 10.17487/RFC4960, September 2007, 4391 . 4393 [RFC4987] Eddy, W., "TCP SYN Flooding Attacks and Common 4394 Mitigations", RFC 4987, DOI 10.17487/RFC4987, August 2007, 4395 . 4397 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 4398 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 4399 DOI 10.17487/RFC5389, October 2008, 4400 . 4402 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 4403 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 4404 June 2010, . 4406 [RFC6052] Bao, C., Huitema, C., Bagnulo, M., Boucadair, M., and X. 4407 Li, "IPv6 Addressing of IPv4/IPv6 Translators", RFC 6052, 4408 DOI 10.17487/RFC6052, October 2010, 4409 . 4411 [RFC6146] Bagnulo, M., Matthews, P., and I. van Beijnum, "Stateful 4412 NAT64: Network Address and Protocol Translation from IPv6 4413 Clients to IPv4 Servers", RFC 6146, DOI 10.17487/RFC6146, 4414 April 2011, . 4416 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 4417 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 4418 DOI 10.17487/RFC6234, May 2011, 4419 . 4421 [RFC6296] Wasserman, M. and F. Baker, "IPv6-to-IPv6 Network Prefix 4422 Translation", RFC 6296, DOI 10.17487/RFC6296, June 2011, 4423 . 4425 [RFC6724] Thaler, D., Ed., Draves, R., Matsumoto, A., and T. Chown, 4426 "Default Address Selection for Internet Protocol Version 6 4427 (IPv6)", RFC 6724, DOI 10.17487/RFC6724, September 2012, 4428 . 4430 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 4431 Specifications and Registration Procedures", BCP 13, 4432 RFC 6838, DOI 10.17487/RFC6838, January 2013, 4433 . 4435 [RFC6887] Wing, D., Ed., Cheshire, S., Boucadair, M., Penno, R., and 4436 P. Selkirk, "Port Control Protocol (PCP)", RFC 6887, 4437 DOI 10.17487/RFC6887, April 2013, 4438 . 4440 [RFC6888] Perreault, S., Ed., Yamagata, I., Miyakawa, S., Nakagawa, 4441 A., and H. Ashida, "Common Requirements for Carrier-Grade 4442 NATs (CGNs)", BCP 127, RFC 6888, DOI 10.17487/RFC6888, 4443 April 2013, . 4445 [RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed., 4446 "Enrollment over Secure Transport", RFC 7030, 4447 DOI 10.17487/RFC7030, October 2013, 4448 . 4450 [RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 4451 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 4452 . 4454 [RFC7452] Tschofenig, H., Arkko, J., Thaler, D., and D. McPherson, 4455 "Architectural Considerations in Smart Object Networking", 4456 RFC 7452, DOI 10.17487/RFC7452, March 2015, 4457 . 4459 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 4460 NETCONF Protocol over Transport Layer Security (TLS) with 4461 Mutual X.509 Authentication", RFC 7589, 4462 DOI 10.17487/RFC7589, June 2015, 4463 . 4465 [RFC8305] Schinazi, D. and T. Pauly, "Happy Eyeballs Version 2: 4466 Better Connectivity Using Concurrency", RFC 8305, 4467 DOI 10.17487/RFC8305, December 2017, 4468 . 4470 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 4471 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 4472 . 4474 [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 4475 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 4476 January 2019, . 4478 Authors' Addresses 4479 Tirumaleswar Reddy (editor) 4480 McAfee, Inc. 4481 Embassy Golf Link Business Park 4482 Bangalore, Karnataka 560071 4483 India 4485 Email: kondtir@gmail.com 4487 Mohamed Boucadair (editor) 4488 Orange 4489 Rennes 35000 4490 France 4492 Email: mohamed.boucadair@orange.com 4494 Prashanth Patil 4495 Cisco Systems, Inc. 4497 Email: praspati@cisco.com 4499 Andrew Mortensen 4500 Arbor Networks, Inc. 4501 2727 S. State St 4502 Ann Arbor, MI 48104 4503 United States 4505 Email: andrew@moretension.com 4507 Nik Teague 4508 Verisign, Inc. 4509 United States 4511 Email: nteague@verisign.com