idnits 2.17.1 draft-ietf-dots-signal-channel-28.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 ([I-D.ietf-dots-data-channel], [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 2436 has weird spacing: '...er-port ine...' -- The document date (January 29, 2019) is 1886 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 4032, 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 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) ** Downref: Normative reference to an Informational RFC: RFC 7918 == Outdated reference: A later version (-17) exists of draft-ietf-core-comi-04 == Outdated reference: A later version (-07) exists of draft-ietf-core-hop-limit-02 == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-07 == Outdated reference: A later version (-18) exists of draft-ietf-dots-architecture-10 == Outdated reference: A later version (-31) exists of draft-ietf-dots-data-channel-25 == Outdated reference: A later version (-22) exists of draft-ietf-dots-requirements-16 == Outdated reference: A later version (-25) exists of draft-ietf-dots-use-cases-17 == Outdated reference: A later version (-43) exists of draft-ietf-tls-dtls13-30 -- Obsolete informational reference (is this intentional?): RFC 4960 (Obsoleted by RFC 9260) -- Obsolete informational reference (is this intentional?): RFC 5389 (Obsoleted by RFC 8489) -- Obsolete informational reference (is this intentional?): RFC 8499 (Obsoleted by RFC 9499) Summary: 8 errors (**), 0 flaws (~~), 11 warnings (==), 4 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: August 2, 2019 Orange 6 P. Patil 7 Cisco 8 A. Mortensen 9 Arbor Networks, Inc. 10 N. Teague 11 Verisign, Inc. 12 January 29, 2019 14 Distributed Denial-of-Service Open Threat Signaling (DOTS) Signal 15 Channel Specification 16 draft-ietf-dots-signal-channel-28 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 48 [I-D.ietf-dots-data-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 August 2, 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's 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 exponent is 2) the active-but-terminating period up to 1672 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, 'idle- 1717 config'-related values must be followed). Additionally, DOTS agents 1718 MUST automatically switch to the other configuration upon a change in 1719 the mitigation activity (e.g., if an attack mitigation is launched 1720 after a peacetime, the DOTS agent switches from 'idle-config' to 1721 'mitigating-config'-related values). 1723 CoAP Requests and responses are indicated for reliable delivery by 1724 marking them as Confirmable messages. DOTS signal channel session 1725 configuration requests and responses are marked as Confirmable 1726 messages. As explained in Section 2.1 of [RFC7252], a Confirmable 1727 message is retransmitted using a default timeout and exponential 1728 back-off between retransmissions, until the DOTS server sends an 1729 Acknowledgement message (ACK) with the same Message ID conveyed from 1730 the DOTS client. 1732 Message transmission parameters are defined in Section 4.8 of 1733 [RFC7252]. The DOTS server can either piggyback the response in the 1734 acknowledgement message or, if the DOTS server cannot respond 1735 immediately to a request carried in a Confirmable message, it simply 1736 responds with an Empty Acknowledgement message so that the DOTS 1737 client can stop retransmitting the request. Empty Acknowledgement 1738 messages are explained in Section 2.2 of [RFC7252]. When the 1739 response is ready, the server sends it in a new Confirmable message 1740 which in turn needs to be acknowledged by the DOTS client (see 1741 Sections 5.2.1 and 5.2.2 of [RFC7252]). Requests and responses 1742 exchanged between DOTS agents during peacetime are marked as 1743 Confirmable messages. 1745 Implementation Note: A DOTS client that receives a response in a 1746 Confirmable message may want to clean up the message state right 1747 after sending the ACK. If that ACK is lost and the DOTS server 1748 retransmits the Confirmable message, the DOTS client may no longer 1749 have any state that would help it correlate this response: from 1750 the DOTS client's standpoint, the retransmission message is 1751 unexpected. The DOTS client will send a Reset message so it does 1752 not receive any more retransmissions. This behavior is normal and 1753 not an indication of an error (see Section 5.3.2 of [RFC7252] for 1754 more details). 1756 4.5.1. Discover Configuration Parameters 1758 A GET request is used to obtain acceptable (e.g., minimum and maximum 1759 values) and current configuration parameters on the DOTS server for 1760 DOTS signal channel session configuration. This procedure occurs 1761 between a DOTS client and its immediate peer DOTS server. As such, 1762 this GET request MUST NOT be relayed by a DOTS gateway. 1764 Figure 17 shows how to obtain acceptable configuration parameters for 1765 the DOTS server. 1767 Header: GET (Code=0.01) 1768 Uri-Path: ".well-known" 1769 Uri-Path: "dots" 1770 Uri-Path: "config" 1772 Figure 17: GET to Retrieve Configuration 1774 The DOTS server in the 2.05 (Content) response conveys the current, 1775 minimum, and maximum attribute values acceptable by the DOTS server 1776 (Figure 18). 1778 Content-Format: "application/dots+cbor" 1779 { 1780 "ietf-dots-signal-channel:signal-config": { 1781 "mitigating-config": { 1782 "heartbeat-interval": { 1783 "max-value": number, 1784 "min-value": number, 1785 "current-value": number 1786 }, 1787 "missing-hb-allowed": { 1788 "max-value": number, 1789 "min-value": number, 1790 "current-value": number 1791 }, 1792 "max-retransmit": { 1793 "max-value": number, 1794 "min-value": number, 1795 "current-value": number 1796 }, 1797 "ack-timeout": { 1798 "max-value-decimal": "string", 1799 "min-value-decimal": "string", 1800 "current-value-decimal": "string" 1801 }, 1802 "ack-random-factor": { 1803 "max-value-decimal": "string", 1804 "min-value-decimal": "string", 1805 "current-value-decimal": "string" 1806 } 1807 }, 1808 "idle-config": { 1809 "heartbeat-interval": { 1810 "max-value": number, 1811 "min-value": number, 1812 "current-value": number 1813 }, 1814 "missing-hb-allowed": { 1815 "max-value": number, 1816 "min-value": number, 1817 "current-value": number 1818 }, 1819 "max-retransmit": { 1820 "max-value": number, 1821 "min-value": number, 1822 "current-value": number 1823 }, 1824 "ack-timeout": { 1825 "max-value-decimal": "string", 1826 "min-value-decimal": "string", 1827 "current-value-decimal": "string" 1828 }, 1829 "ack-random-factor": { 1830 "max-value-decimal": "string", 1831 "min-value-decimal": "string", 1832 "current-value-decimal": "string" 1833 } 1834 } 1835 } 1836 } 1838 Figure 18: GET Configuration Response Body Schema 1840 The parameters in Figure 18 are described below: 1842 mitigating-config: Set of configuration parameters to use when a 1843 mitigation is active. The following parameters may be included: 1845 heartbeat-interval: Time interval in seconds between two 1846 consecutive heartbeat messages. 1848 '0' is used to disable the heartbeat mechanism. 1850 This is an optional attribute. 1852 missing-hb-allowed: Maximum number of consecutive heartbeat 1853 messages for which the DOTS agent did not receive a response 1854 before concluding that the session is disconnected. 1856 This is an optional attribute. 1858 max-retransmit: Maximum number of retransmissions for a message 1859 (referred to as MAX_RETRANSMIT parameter in CoAP). 1861 This is an optional attribute. 1863 ack-timeout: Timeout value in seconds used to calculate the 1864 initial retransmission timeout value (referred to as 1865 ACK_TIMEOUT parameter in CoAP). 1867 This is an optional attribute. 1869 ack-random-factor: Random factor used to influence the timing of 1870 retransmissions (referred to as ACK_RANDOM_FACTOR parameter in 1871 CoAP). 1873 This is an optional attribute. 1875 idle-config: Set of configuration parameters to use when no 1876 mitigation is active. This attribute has the same structure as 1877 'mitigating-config'. 1879 Figure 19 shows an example of acceptable and current configuration 1880 parameters on a DOTS server for DOTS signal channel session 1881 configuration. The same acceptable configuration is used during 1882 mitigation and idle times. 1884 Content-Format: "application/dots+cbor" 1885 { 1886 "ietf-dots-signal-channel:signal-config": { 1887 "mitigating-config": { 1888 "heartbeat-interval": { 1889 "max-value": 240, 1890 "min-value": 15, 1891 "current-value": 30 1892 }, 1893 "missing-hb-allowed": { 1894 "max-value": 9, 1895 "min-value": 3, 1896 "current-value": 5 1897 }, 1898 "max-retransmit": { 1899 "max-value": 15, 1900 "min-value": 2, 1901 "current-value": 3 1902 }, 1903 "ack-timeout": { 1904 "max-value-decimal": "30.00", 1905 "min-value-decimal": "1.00", 1906 "current-value-decimal": "2.00" 1907 }, 1908 "ack-random-factor": { 1909 "max-value-decimal": "4.00", 1910 "min-value-decimal": "1.10", 1911 "current-value-decimal": "1.50" 1912 } 1913 }, 1914 "idle-config": { 1915 "heartbeat-interval": { 1916 "max-value": 240, 1917 "min-value": 15, 1918 "current-value": 30 1919 }, 1920 "missing-hb-allowed": { 1921 "max-value": 9, 1922 "min-value": 3, 1923 "current-value": 5 1924 }, 1925 "max-retransmit": { 1926 "max-value": 15, 1927 "min-value": 2, 1928 "current-value": 3 1929 }, 1930 "ack-timeout": { 1931 "max-value-decimal": "30.00", 1932 "min-value-decimal": "1.00", 1933 "current-value-decimal": "2.00" 1934 }, 1935 "ack-random-factor": { 1936 "max-value-decimal": "4.00", 1937 "min-value-decimal": "1.10", 1938 "current-value-decimal": "1.50" 1939 } 1940 } 1941 } 1942 } 1944 Figure 19: Example of a Configuration Response Body 1946 4.5.2. Convey DOTS Signal Channel Session Configuration 1948 A PUT request (Figures 20 and 21) is used to convey the configuration 1949 parameters for the signal channel (e.g., heartbeat interval, maximum 1950 retransmissions). Message transmission parameters for CoAP are 1951 defined in Section 4.8 of [RFC7252]. The RECOMMENDED values of 1952 transmission parameter values are ack-timeout (2 seconds), max- 1953 retransmit (3), ack-random-factor (1.5). In addition to those 1954 parameters, the RECOMMENDED specific DOTS transmission parameter 1955 values are 'heartbeat-interval' (30 seconds) and 'missing-hb-allowed' 1956 (5). 1958 Note: heartbeat-interval should be tweaked to also assist DOTS 1959 messages for NAT traversal (SIG-011 of 1960 [I-D.ietf-dots-requirements]). According to [RFC8085], keepalive 1961 messages must not be sent more frequently than once every 15 1962 seconds and should use longer intervals when possible. 1963 Furthermore, [RFC4787] recommends NATs to use a state timeout of 2 1964 minutes or longer, but experience shows that sending packets every 1965 15 to 30 seconds is necessary to prevent the majority of 1966 middleboxes from losing state for UDP flows. From that 1967 standpoint, this specification recommends a minimum heartbeat- 1968 interval of 15 seconds and a maximum heartbeat-interval of 240 1969 seconds. The recommended value of 30 seconds is selected to 1970 anticipate the expiry of NAT state. 1972 A heartbeat-interval of 30 seconds may be considered as too chatty 1973 in some deployments. For such deployments, DOTS agents may 1974 negotiate longer heartbeat-interval values to prevent any network 1975 overload with too frequent keepalives. 1977 Different heartbeat intervals can be defined for 'mitigating- 1978 config' and 'idle-config' to reduce being too chatty during idle 1979 times. If there is an on-path translator between the DOTS client 1980 (standalone or part of a DOTS gateway) and the DOTS server, the 1981 'mitigating-config' heartbeat-interval has to be smaller than the 1982 translator session timeout. It is recommended that the 'idle- 1983 config' heartbeat-interval is also smaller than the translator 1984 session timeout to prevent translator traversal issues, or 1985 disabled entirely. Means to discover the lifetime assigned by a 1986 translator are out of scope. 1988 When a Confirmable "CoAP Ping" is sent, and if there is no response, 1989 the "CoAP Ping" is retransmitted max-retransmit number of times by 1990 the CoAP layer using an initial timeout set to a random duration 1991 between ack-timeout and (ack-timeout*ack-random-factor) and 1992 exponential back-off between retransmissions. By choosing the 1993 recommended transmission parameters, the "CoAP Ping" will timeout 1994 after 45 seconds. If the DOTS agent does not receive any response 1995 from the peer DOTS agent for 'missing-hb-allowed' number of 1996 consecutive "CoAP Ping" Confirmable messages, it concludes that the 1997 DOTS signal channel session is disconnected. A DOTS client MUST NOT 1998 transmit a "CoAP Ping" while waiting for the previous "CoAP Ping" 1999 response from the same DOTS server. 2001 If the DOTS agent wishes to change the default values of message 2002 transmission parameters, it SHOULD follow the guidance given in 2003 Section 4.8.1 of [RFC7252]. The DOTS agents MUST use the negotiated 2004 values for message transmission parameters and default values for 2005 non-negotiated message transmission parameters. 2007 The signal channel session configuration is applicable to a single 2008 DOTS signal channel session between DOTS agents, so the 'cuid' Uri- 2009 Path MUST NOT be used. 2011 Header: PUT (Code=0.03) 2012 Uri-Path: ".well-known" 2013 Uri-Path: "dots" 2014 Uri-Path: "config" 2015 Uri-Path: "sid=123" 2016 Content-Format: "application/dots+cbor" 2017 { 2018 ... 2019 } 2021 Figure 20: PUT to Convey the DOTS Signal Channel Session 2022 Configuration Data 2024 The additional Uri-Path parameter to those defined in Table 1 is as 2025 follows: 2027 sid: Session Identifier is an identifier for the DOTS signal channel 2028 session configuration data represented as an integer. This 2029 identifier MUST be generated by DOTS clients. 'sid' values MUST 2030 increase monotonically (when a new PUT is generated by a DOTS 2031 client to convey the configuration parameters for the signal 2032 channel). 2034 This is a mandatory attribute. 2036 Content-Format: "application/dots+cbor" 2037 { 2038 "ietf-dots-signal-channel:signal-config": { 2039 "mitigating-config": { 2040 "heartbeat-interval": { 2041 "current-value": number 2042 }, 2043 "missing-hb-allowed": { 2044 "current-value": number 2045 }, 2046 "max-retransmit": { 2047 "current-value": number 2048 }, 2049 "ack-timeout": { 2050 "current-value-decimal": "string" 2051 }, 2052 "ack-random-factor": { 2053 "current-value-decimal": "string" 2054 } 2055 }, 2056 "idle-config": { 2057 "heartbeat-interval": { 2058 "current-value": number 2059 }, 2060 "missing-hb-allowed": { 2061 "current-value": number 2062 }, 2063 "max-retransmit": { 2064 "current-value": number 2065 }, 2066 "ack-timeout": { 2067 "current-value-decimal": "string" 2068 }, 2069 "ack-random-factor": { 2070 "current-value-decimal": "string" 2071 } 2072 } 2073 } 2074 } 2076 Figure 21: PUT to Convey the DOTS Signal Channel Session 2077 Configuration Data (Message Body Schema) 2079 The meaning of the parameters in the CBOR body (Figure 21) is defined 2080 in Section 4.5.1. 2082 At least one of the attributes 'heartbeat-interval', 'missing-hb- 2083 allowed', 'max-retransmit', 'ack-timeout', and 'ack-random-factor' 2084 MUST be present in the PUT request. Note that 'heartbeat-interval', 2085 'missing-hb-allowed', 'max-retransmit', 'ack-timeout', and 'ack- 2086 random-factor', if present, do not need to be provided for both 2087 'mitigating-config', and 'idle-config' in a PUT request. 2089 The PUT request with a higher numeric 'sid' value overrides the DOTS 2090 signal channel session configuration data installed by a PUT request 2091 with a lower numeric 'sid' value. To avoid maintaining a long list 2092 of 'sid' requests from a DOTS client, the lower numeric 'sid' MUST be 2093 automatically deleted and no longer available at the DOTS server. 2095 Figure 22 shows a PUT request example to convey the configuration 2096 parameters for the DOTS signal channel. In this example, the 2097 heartbeat mechanism is disabled when no mitigation is active, while 2098 the heartbeat interval is set to '91' when a mitigation is active. 2100 Header: PUT (Code=0.03) 2101 Uri-Path: ".well-known" 2102 Uri-Path: "dots" 2103 Uri-Path: "config" 2104 Uri-Path: "sid=123" 2105 Content-Format: "application/dots+cbor" 2106 { 2107 "ietf-dots-signal-channel:signal-config": { 2108 "mitigating-config": { 2109 "heartbeat-interval": { 2110 "current-value": 91 2111 }, 2112 "missing-hb-allowed": { 2113 "current-value": 3 2114 }, 2115 "max-retransmit": { 2116 "current-value": 3 2117 }, 2118 "ack-timeout": { 2119 "current-value-decimal": "2.00" 2120 }, 2121 "ack-random-factor": { 2122 "current-value-decimal": "1.50" 2123 } 2124 }, 2125 "idle-config": { 2126 "heartbeat-interval": { 2127 "current-value": 0 2128 }, 2129 "max-retransmit": { 2130 "current-value": 3 2131 }, 2132 "ack-timeout": { 2133 "current-value-decimal": "2.00" 2134 }, 2135 "ack-random-factor": { 2136 "current-value-decimal": "1.50" 2137 } 2138 } 2139 } 2140 } 2142 Figure 22: PUT to Convey the Configuration Parameters 2144 The DOTS server indicates the result of processing the PUT request 2145 using CoAP response codes: 2147 o If the request is missing a mandatory attribute, does not include 2148 a 'sid' Uri-Path, or contains one or more invalid or unknown 2149 parameters, 4.00 (Bad Request) MUST be returned in the response. 2151 o If the DOTS server does not find the 'sid' parameter value 2152 conveyed in the PUT request in its configuration data and if the 2153 DOTS server has accepted the configuration parameters, then a 2154 response code 2.01 (Created) MUST be returned in the response. 2156 o If the DOTS server finds the 'sid' parameter value conveyed in the 2157 PUT request in its configuration data and if the DOTS server has 2158 accepted the updated configuration parameters, 2.04 (Changed) MUST 2159 be returned in the response. 2161 o If any of the 'heartbeat-interval', 'missing-hb-allowed', 'max- 2162 retransmit', 'target-protocol', 'ack-timeout', and 'ack-random- 2163 factor' attribute values are not acceptable to the DOTS server, 2164 4.22 (Unprocessable Entity) MUST be returned in the response. 2165 Upon receipt of this error code, the DOTS client SHOULD retrieve 2166 the maximum and minimum attribute values acceptable to the DOTS 2167 server (Section 4.5.1). 2169 The DOTS client may re-try and send the PUT request with updated 2170 attribute values acceptable to the DOTS server. 2172 A DOTS client may issue a GET message with 'sid' Uri-Path parameter 2173 to retrieve the negotiated configuration. The response does not need 2174 to include 'sid' in its message body. 2176 4.5.3. Configuration Freshness and Notifications 2178 Max-Age Option (Section 5.10.5 of [RFC7252]) SHOULD be returned by a 2179 DOTS server to associate a validity time with a configuration it 2180 sends. This feature allows the update of the configuration data if a 2181 change occurs at the DOTS server side. For example, the new 2182 configuration may instruct a DOTS client to cease heartbeats or 2183 reduce heartbeat frequency. 2185 It is NOT RECOMMENDED to return a Max-Age Option set to 0. 2187 Returning a Max-Age Option set to 2**32-1 is equivalent to 2188 associating an infinite lifetime with the configuration. 2190 If a non-zero value of Max-Age Option is received by a DOTS client, 2191 it MUST issue a GET request with 'sid' Uri-Path parameter to retrieve 2192 the current and acceptable configuration before the expiry of the 2193 value enclosed in the Max-Age option. This request is considered by 2194 the client and the server as a means to refresh the configuration 2195 parameters for the signal channel. When a DDoS attack is active, 2196 refresh requests MUST NOT be sent by DOTS clients and the DOTS server 2197 MUST NOT terminate the (D)TLS session after the expiry of the value 2198 returned in Max-Age Option. 2200 If Max-Age Option is not returned in a response, the DOTS client 2201 initiates GET requests to refresh the configuration parameters each 2202 60 seconds (Section 5.10.5 of [RFC7252]). To prevent such overload, 2203 it is RECOMMENDED that DOTS servers return a Max-Age Option in GET 2204 responses. Considerations related to which value to use and how such 2205 value is set, are implementation- and deployment-specific. 2207 If an Observe Option set to 0 is included in the configuration 2208 request, the DOTS server sends notifications of any configuration 2209 change (Section 4.2 of [RFC7641]). 2211 If a DOTS server detects that a misbehaving DOTS client does not 2212 contact the DOTS server after the expiry of Max-Age and retrieve the 2213 signal channel configuration data, it MAY terminate the (D)TLS 2214 session. A (D)TLS session is terminated by the receipt of an 2215 authenticated message that closes the connection (e.g., a fatal alert 2216 (Section 6 of [RFC8446])). 2218 4.5.4. Delete DOTS Signal Channel Session Configuration 2220 A DELETE request is used to delete the installed DOTS signal channel 2221 session configuration data (Figure 23). 2223 Header: DELETE (Code=0.04) 2224 Uri-Path: ".well-known" 2225 Uri-Path: "dots" 2226 Uri-Path: "config" 2227 Uri-Path: "sid=123" 2229 Figure 23: Delete Configuration 2231 The DOTS server resets the DOTS signal channel session configuration 2232 back to the default values and acknowledges a DOTS client's request 2233 to remove the DOTS signal channel session configuration using 2.02 2234 (Deleted) response code. 2236 Upon bootstrapping or reboot, a DOTS client MAY send a DELETE request 2237 to set the configuration parameters to default values. Such a 2238 request does not include any 'sid'. 2240 4.6. Redirected Signaling 2242 Redirected DOTS signaling is discussed in detail in Section 3.2.2 of 2243 [I-D.ietf-dots-architecture]. 2245 If a DOTS server wants to redirect a DOTS client to an alternative 2246 DOTS server for a signal session, then the response code 5.03 2247 (Service Unavailable) will be returned in the response to the DOTS 2248 client. 2250 The DOTS server can return the error response code 5.03 in response 2251 to a request from the DOTS client or convey the error response code 2252 5.03 in a unidirectional notification response from the DOTS server. 2254 The DOTS server in the error response conveys the alternate DOTS 2255 server's FQDN, and the alternate DOTS server's IP address(es) values 2256 in the CBOR body (Figure 24). 2258 { 2259 "ietf-dots-signal-channel:redirected-signal": { 2260 "alt-server": "string", 2261 "alt-server-record": [ 2262 "string" 2263 ] 2264 } 2266 Figure 24: Redirected Server Error Response Body Schema 2268 The parameters are described below: 2270 alt-server: FQDN of an alternate DOTS server. 2272 This is a mandatory attribute. 2274 alt-server-record: A list of IP addresses of an alternate DOTS 2275 server. 2277 This is an optional attribute. 2279 The DOTS server returns the Time to live (TTL) of the alternate DOTS 2280 server in a Max-Age Option. That is, the time interval that the 2281 alternate DOTS server may be cached for use by a DOTS client. A Max- 2282 Age Option set to 2**32-1 is equivalent to receiving an infinite TTL. 2283 This value means that the alternate DOTS server is to be used until 2284 the alternate DOTS server redirects the traffic with another 5.03 2285 response which encloses an alternate server. 2287 A Max-Age Option set to '0' may be returned for redirecting 2288 mitigation requests. Such value means that the redirection applies 2289 only for the mitigation request in progress. Returning short TTL in 2290 a Max-Age Option may adversely impact DOTS clients on slow links. 2291 Returning short values should be avoided under such conditions. 2293 If the alternate DOTS server TTL has expired, the DOTS client MUST 2294 use the DOTS server(s), that was provisioned using means discussed in 2295 Section 4.1. This fall back mechanism is triggered immediately upon 2296 expiry of the TTL, except when a DDoS attack is active. 2298 Requests issued by misbehaving DOTS clients which do not honor the 2299 TTL conveyed in the Max-Age Option or react to explicit re-direct 2300 messages can be rejected by DOTS servers. 2302 Figure 25 shows a 5.03 response example to convey the DOTS alternate 2303 server 'alt-server.example' together with its IP addresses 2304 2001:db8:6401::1 and 2001:db8:6401::2. 2306 { 2307 "ietf-dots-signal-channel:redirected-signal": { 2308 "alt-server": "alt-server.example", 2309 "alt-server-record": [ 2310 "2001:db8:6401::1", 2311 "2001:db8:6401::2" 2312 ] 2313 } 2315 Figure 25: Example of Redirected Server Error Response Body 2317 When the DOTS client receives 5.03 response with an alternate server 2318 included, it considers the current request as failed, but SHOULD try 2319 re-sending the request to the alternate DOTS server. During a DDoS 2320 attack, the DNS server may be the target of another DDoS attack, 2321 alternate DOTS server's IP addresses conveyed in the 5.03 response 2322 help the DOTS client skip DNS lookup of the alternate DOTS server, at 2323 the cost of trusting the first DOTS server to provide accurate 2324 information. The DOTS client can then try to establish a UDP or a 2325 TCP session with the alternate DOTS server. The DOTS client MAY 2326 implement a method to construct IPv4-embedded IPv6 addresses 2327 [RFC6052]; this is required to handle the scenario where an IPv6-only 2328 DOTS client communicates with an IPv4-only alternate DOTS server. 2330 If the DOTS client has been redirected to a DOTS server to which it 2331 has already communicated with within the last five (5) minutes, it 2332 MUST ignore the redirection and try to contact other DOTS servers 2333 listed in the local configuration or discovered using dynamic means 2334 such as DHCP or SRV procedures. It is RECOMMENDED that DOTS clients 2335 support means to alert administrators about redirect loops. 2337 4.7. Heartbeat Mechanism 2339 To provide an indication of signal health and distinguish an 'idle' 2340 signal channel from a 'disconnected' or 'defunct' session, the DOTS 2341 agent sends a heartbeat over the signal channel to maintain its half 2342 of the channel. The DOTS agent similarly expects a heartbeat from 2343 its peer DOTS agent, and may consider a session terminated in the 2344 prolonged absence of a peer agent heartbeat. Concretely, while the 2345 communication between the DOTS agents is otherwise quiescent, the 2346 DOTS client will probe the DOTS server to ensure it has maintained 2347 cryptographic state and vice versa. Such probes can also keep 2348 firewalls and/or stateful translators bindings alive. This probing 2349 reduces the frequency of establishing a new handshake when a DOTS 2350 signal needs to be conveyed to the DOTS server. 2352 DOTS servers MAY trigger their heartbeat requests immediately after 2353 receiving heartbeat probes from peer DOTS clients. As a reminder, it 2354 is the responsibility of DOTS clients to ensure that on-path 2355 translators/firewalls are maintaining a binding so that the same 2356 external IP address and/or port number is retained for the DOTS 2357 signal channel session. 2359 In case of a massive DDoS attack that saturates the incoming link(s) 2360 to the DOTS client, all traffic from the DOTS server to the DOTS 2361 client will likely be dropped, although the DOTS server receives 2362 heartbeat requests in addition to DOTS messages sent by the DOTS 2363 client. In this scenario, the DOTS agents MUST behave differently to 2364 handle message transmission and DOTS signal channel session 2365 liveliness during link saturation: 2367 o The DOTS client MUST NOT consider the DOTS signal channel session 2368 terminated even after a maximum 'missing-hb-allowed' threshold is 2369 reached. The DOTS client SHOULD keep on using the current DOTS 2370 signal channel session to send heartbeat requests over it, so that 2371 the DOTS server knows the DOTS client has not disconnected the 2372 DOTS signal channel session. 2374 After the maximum 'missing-hb-allowed' threshold is reached, the 2375 DOTS client SHOULD try to resume the (D)TLS session. The DOTS 2376 client SHOULD send mitigation requests over the current DOTS 2377 signal channel session, and in parallel, for example, try to 2378 resume the (D)TLS session or use 0-RTT mode in DTLS 1.3 to 2379 piggyback the mitigation request in the ClientHello message. 2381 As soon as the link is no longer saturated, if traffic from the 2382 DOTS server reaches the DOTS client over the current DOTS signal 2383 channel session, the DOTS client can stop (D)TLS session 2384 resumption or if (D)TLS session resumption is successful then 2385 disconnect the current DOTS signal channel session. 2387 o If the DOTS server does not receive any traffic from the peer DOTS 2388 client, then the DOTS server sends heartbeat requests to the DOTS 2389 client and after maximum 'missing-hb-allowed' threshold is 2390 reached, the DOTS server concludes the session is disconnected. 2392 In DOTS over UDP, heartbeat messages MUST be exchanged between the 2393 DOTS agents using the "CoAP Ping" mechanism defined in Section 4.2 of 2394 [RFC7252]. Concretely, the DOTS agent sends an Empty Confirmable 2395 message and the peer DOTS agent will respond by sending a Reset 2396 message. 2398 In DOTS over TCP, heartbeat messages MUST be exchanged between the 2399 DOTS agents using the Ping and Pong messages specified in Section 5.4 2400 of [RFC8323]. That is, the DOTS agent sends a Ping message and the 2401 peer DOTS agent would respond by sending a single Pong message. 2403 5. DOTS Signal Channel YANG Modules 2405 This document defines a YANG [RFC7950] module for DOTS mitigation 2406 scope, DOTS signal channel session configuration data, and DOTS 2407 redirection signalling. 2409 This YANG module (ietf-dots-signal-channel) defines the DOTS client 2410 interaction with the DOTS server as seen by the DOTS client. A DOTS 2411 server is allowed to update the non-configurable 'ro' entities in the 2412 responses. This YANG module is not intended to be used via NETCONF/ 2413 RESTCONF for DOTS server management purposes; such module is out of 2414 the scope of this document. It serves only to provide a data model 2415 and encoding, but not a management data model. 2417 A companion YANG module is defined to include a collection of types 2418 defined by IANA: "iana-dots-signal-channel" (Section 5.2). 2420 5.1. Tree Structure 2422 This document defines the YANG module "ietf-dots-signal-channel" 2423 (Section 5.3), which has the following tree structure. A DOTS signal 2424 message can either be a mitigation or a configuration message. 2426 module: ietf-dots-signal-channel 2427 +--rw dots-signal 2428 +--rw (message-type)? 2429 +--:(mitigation-scope) 2430 | +--rw scope* [cuid mid] 2431 | +--rw cdid? string 2432 | +--rw cuid string 2433 | +--rw mid uint32 2434 | +--rw target-prefix* inet:ip-prefix 2435 | +--rw target-port-range* [lower-port] 2436 | | +--rw lower-port inet:port-number 2437 | | +--rw upper-port? inet:port-number 2438 | +--rw target-protocol* uint8 2439 | +--rw target-fqdn* inet:domain-name 2440 | +--rw target-uri* inet:uri 2441 | +--rw alias-name* string 2442 | +--rw lifetime? int32 2443 | +--rw trigger-mitigation? boolean 2444 | +--ro mitigation-start? uint64 2445 | +--ro status? iana-signal:status 2446 | +--ro conflict-information 2447 | | +--ro conflict-status? iana-signal:conflict-status 2448 | | +--ro conflict-cause? iana-signal:conflict-cause 2449 | | +--ro retry-timer? uint32 2450 | | +--ro conflict-scope 2451 | | +--ro target-prefix* inet:ip-prefix 2452 | | +--ro target-port-range* [lower-port] 2453 | | | +--ro lower-port inet:port-number 2454 | | | +--ro upper-port? inet:port-number 2455 | | +--ro target-protocol* uint8 2456 | | +--ro target-fqdn* inet:domain-name 2457 | | +--ro target-uri* inet:uri 2458 | | +--ro alias-name* string 2459 | | +--ro acl-list* [acl-name] 2460 | | | +--ro acl-name 2461 | | | | -> /ietf-data:dots-data/dots-client/acls/ 2462 | | | | acl/name 2463 | | | +--ro acl-type? 2464 | | | -> /ietf-data:dots-data/dots-client/acls/ 2465 | | | acl/type 2466 | | +--ro mid? -> ../../../mid 2467 | +--ro bytes-dropped? yang:zero-based-counter64 2468 | +--ro bps-dropped? yang:zero-based-counter64 2469 | +--ro pkts-dropped? yang:zero-based-counter64 2470 | +--ro pps-dropped? yang:zero-based-counter64 2471 | +--rw attack-status? iana-signal:attack-status 2472 +--:(signal-config) 2473 | +--rw sid uint32 2474 | +--rw mitigating-config 2475 | | +--rw heartbeat-interval 2476 | | | +--ro max-value? uint16 2477 | | | +--ro min-value? uint16 2478 | | | +--rw current-value? uint16 2479 | | +--rw missing-hb-allowed 2480 | | | +--ro max-value? uint16 2481 | | | +--ro min-value? uint16 2482 | | | +--rw current-value? uint16 2483 | | +--rw max-retransmit 2484 | | | +--ro max-value? uint16 2485 | | | +--ro min-value? uint16 2486 | | | +--rw current-value? uint16 2487 | | +--rw ack-timeout 2488 | | | +--ro max-value-decimal? decimal64 2489 | | | +--ro min-value-decimal? decimal64 2490 | | | +--rw current-value-decimal? decimal64 2491 | | +--rw ack-random-factor 2492 | | +--ro max-value-decimal? decimal64 2493 | | +--ro min-value-decimal? decimal64 2494 | | +--rw current-value-decimal? decimal64 2495 | +--rw idle-config 2496 | +--rw heartbeat-interval 2497 | | +--ro max-value? uint16 2498 | | +--ro min-value? uint16 2499 | | +--rw current-value? uint16 2500 | +--rw missing-hb-allowed 2501 | | +--ro max-value? uint16 2502 | | +--ro min-value? uint16 2503 | | +--rw current-value? uint16 2504 | +--rw max-retransmit 2505 | | +--ro max-value? uint16 2506 | | +--ro min-value? uint16 2507 | | +--rw current-value? uint16 2508 | +--rw ack-timeout 2509 | | +--ro max-value-decimal? decimal64 2510 | | +--ro min-value-decimal? decimal64 2511 | | +--rw current-value-decimal? decimal64 2512 | +--rw ack-random-factor 2513 | +--ro max-value-decimal? decimal64 2514 | +--ro min-value-decimal? decimal64 2515 | +--rw current-value-decimal? decimal64 2516 +--:(redirected-signal) 2517 +--ro alt-server string 2518 +--ro alt-server-record* inet:ip-address 2520 5.2. IANA DOTS Signal Channel YANG Module 2522 file "iana-dots-signal-channel@2019-01-17.yang" 2523 module iana-dots-signal-channel { 2524 yang-version 1.1; 2525 namespace "urn:ietf:params:xml:ns:yang:iana-dots-signal-channel"; 2526 prefix iana-signal; 2528 organization 2529 "IANA"; 2530 contact 2531 "Internet Assigned Numbers Authority 2533 Postal: ICANN 2534 12025 Waterfront Drive, Suite 300 2535 Los Angeles, CA 90094-2536 2536 United States of America 2537 Tel: +1 310 301 5800 2538 "; 2539 description 2540 "This module contains a collection of YANG data types defined 2541 by IANA and used for DOTS signal channel protocol. 2543 Copyright (c) 2019 IETF Trust and the persons identified as 2544 authors of the code. All rights reserved. 2546 Redistribution and use in source and binary forms, with or 2547 without modification, is permitted pursuant to, and subject 2548 to the license terms contained in, the Simplified BSD License 2549 set forth in Section 4.c of the IETF Trust's Legal Provisions 2550 Relating to IETF Documents 2551 (http://trustee.ietf.org/license-info). 2553 This version of this YANG module is part of RFC XXXX; see 2554 the RFC itself for full legal notices."; 2556 revision 2019-01-17 { 2557 description 2558 "Initial revision."; 2559 reference 2560 "RFC XXXX: Distributed Denial-of-Service Open Threat 2561 Signaling (DOTS) Signal Channel Specification"; 2562 } 2564 typedef status { 2565 type enumeration { 2566 enum attack-mitigation-in-progress { 2567 value 1; 2568 description 2569 "Attack mitigation setup is in progress (e.g., changing 2570 the network path to re-route the inbound traffic 2571 to DOTS mitigator)."; 2572 } 2573 enum attack-successfully-mitigated { 2574 value 2; 2575 description 2576 "Attack is being successfully mitigated (e.g., traffic 2577 is redirected to a DDoS mitigator and attack 2578 traffic is dropped or blackholed)."; 2579 } 2580 enum attack-stopped { 2581 value 3; 2582 description 2583 "Attack has stopped and the DOTS client can 2584 withdraw the mitigation request."; 2585 } 2586 enum attack-exceeded-capability { 2587 value 4; 2588 description 2589 "Attack has exceeded the mitigation provider 2590 capability."; 2591 } 2592 enum dots-client-withdrawn-mitigation { 2593 value 5; 2594 description 2595 "DOTS client has withdrawn the mitigation 2596 request and the mitigation is active but 2597 terminating."; 2598 } 2599 enum attack-mitigation-terminated { 2600 value 6; 2601 description 2602 "Attack mitigation is now terminated."; 2603 } 2604 enum attack-mitigation-withdrawn { 2605 value 7; 2606 description 2607 "Attack mitigation is withdrawn."; 2608 } 2609 enum attack-mitigation-signal-loss { 2610 value 8; 2611 description 2612 "Attack mitigation will be triggered 2613 for the mitigation request only when 2614 the DOTS signal channel session is lost."; 2615 } 2616 } 2617 description 2618 "Enumeration for status reported by the DOTS server."; 2619 } 2620 typedef conflict-status { 2621 type enumeration { 2622 enum request-inactive-other-active { 2623 value 1; 2624 description 2625 "DOTS Server has detected conflicting mitigation 2626 requests from different DOTS clients. 2627 This mitigation request is currently inactive 2628 until the conflicts are resolved. Another 2629 mitigation request is active."; 2630 } 2631 enum request-active { 2632 value 2; 2633 description 2634 "DOTS Server has detected conflicting mitigation 2635 requests from different DOTS clients. 2636 This mitigation request is currently active."; 2637 } 2638 enum all-requests-inactive { 2639 value 3; 2640 description 2641 "DOTS Server has detected conflicting mitigation 2642 requests from different DOTS clients. All 2643 conflicting mitigation requests are inactive."; 2644 } 2645 } 2646 description 2647 "Enumeration for conflict status."; 2648 } 2650 typedef conflict-cause { 2651 type enumeration { 2652 enum overlapping-targets { 2653 value 1; 2654 description 2655 "Overlapping targets. conflict-scope provides 2656 more details about the exact conflict."; 2657 } 2658 enum conflict-with-acceptlist { 2659 value 2; 2660 description 2661 "Conflicts with an existing accept-list. 2663 This code is returned when the DDoS mitigation 2664 detects that some of the source addresses/prefixes 2665 listed in the accept-list ACLs are actually 2666 attacking the target."; 2667 } 2668 enum cuid-collision { 2669 value 3; 2670 description 2671 "Conflicts with the cuid used by another 2672 DOTS client."; 2673 } 2674 } 2675 description 2676 "Enumeration for conflict causes."; 2677 } 2679 typedef attack-status { 2680 type enumeration { 2681 enum under-attack { 2682 value 1; 2683 description 2684 "The DOTS client determines that it is still under 2685 attack."; 2686 } 2687 enum attack-successfully-mitigated { 2688 value 2; 2689 description 2690 "The DOTS client determines that the attack is 2691 successfully mitigated."; 2692 } 2693 } 2694 description 2695 "Enumeration for attack status codes."; 2696 } 2697 } 2698 2700 5.3. IETF DOTS Signal Channel YANG Module 2702 This module uses the common YANG types defined in [RFC6991] and types 2703 defined in [I-D.ietf-dots-data-channel]. 2705 file "ietf-dots-signal-channel@2019-01-17.yang" 2706 module ietf-dots-signal-channel { 2707 yang-version 1.1; 2708 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel"; 2709 prefix signal; 2711 import ietf-inet-types { 2712 prefix inet; 2713 reference "Section 4 of RFC 6991"; 2714 } 2715 import ietf-yang-types { 2716 prefix yang; 2717 reference "Section 3 of RFC 6991"; 2718 } 2719 import ietf-dots-data-channel { 2720 prefix ietf-data; 2721 reference 2722 "RFC YYYY: Distributed Denial-of-Service Open Threat Signaling 2723 (DOTS) Data Channel Specification"; 2724 } 2725 import iana-dots-signal-channel { 2726 prefix iana-signal; 2727 } 2729 organization 2730 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 2731 contact 2732 "WG Web: 2733 WG List: 2735 Editor: Konda, Tirumaleswar Reddy 2736 2738 Editor: Mohamed Boucadair 2739 2741 Author: Prashanth Patil 2742 2744 Author: Andrew Mortensen 2745 2747 Author: Nik Teague 2748 "; 2749 description 2750 "This module contains YANG definition for the signaling 2751 messages exchanged between a DOTS client and a DOTS server. 2753 Copyright (c) 2019 IETF Trust and the persons identified as 2754 authors of the code. All rights reserved. 2756 Redistribution and use in source and binary forms, with or 2757 without modification, is permitted pursuant to, and subject 2758 to the license terms contained in, the Simplified BSD License 2759 set forth in Section 4.c of the IETF Trust's Legal Provisions 2760 Relating to IETF Documents 2761 (http://trustee.ietf.org/license-info). 2763 This version of this YANG module is part of RFC XXXX; see 2764 the RFC itself for full legal notices."; 2766 revision 2019-01-17 { 2767 description 2768 "Initial revision."; 2769 reference 2770 "RFC XXXX: Distributed Denial-of-Service Open Threat 2771 Signaling (DOTS) Signal Channel Specification"; 2772 } 2774 /* 2775 * Groupings 2776 */ 2778 grouping mitigation-scope { 2779 description 2780 "Specifies the scope of the mitigation request."; 2781 list scope { 2782 key "cuid mid"; 2783 description 2784 "The scope of the request."; 2785 leaf cdid { 2786 type string; 2787 description 2788 "The cdid should be included by a server-domain 2789 DOTS gateway to propagate the client domain 2790 identification information from the 2791 gateway's client-facing-side to the gateway's 2792 server-facing-side, and from the gateway's 2793 server-facing-side to the DOTS server. 2795 It may be used by the final DOTS server 2796 for policy enforcement purposes."; 2797 } 2798 leaf cuid { 2799 type string; 2800 description 2801 "A unique identifier that is 2802 generated by a DOTS client to prevent 2803 request collisions. It is expected that the 2804 cuid will remain consistent throughout the 2805 lifetime of the DOTS client."; 2806 } 2807 leaf mid { 2808 type uint32; 2809 description 2810 "Mitigation request identifier. 2812 This identifier must be unique for each mitigation 2813 request bound to the DOTS client."; 2814 } 2815 uses ietf-data:target; 2816 leaf-list alias-name { 2817 type string; 2818 description 2819 "An alias name that points to a resource."; 2820 } 2821 leaf lifetime { 2822 type int32; 2823 units "seconds"; 2824 default "3600"; 2825 description 2826 "Indicates the lifetime of the mitigation request. 2828 A lifetime of '0' in a mitigation request is an 2829 invalid value. 2831 A lifetime of negative one (-1) indicates indefinite 2832 lifetime for the mitigation request."; 2833 } 2834 leaf trigger-mitigation { 2835 type boolean; 2836 default "true"; 2837 description 2838 "If set to 'false', DDoS mitigation will not be 2839 triggered unless the DOTS signal channel 2840 session is lost."; 2841 } 2842 leaf mitigation-start { 2843 type uint64; 2844 config false; 2845 description 2846 "Mitigation start time is represented in seconds 2847 relative to 1970-01-01T00:00:00Z in UTC time."; 2848 } 2849 leaf status { 2850 type iana-signal:status; 2851 config false; 2852 description 2853 "Indicates the status of a mitigation request. 2854 It must be included in responses only."; 2855 } 2856 container conflict-information { 2857 config false; 2858 description 2859 "Indicates that a conflict is detected. 2861 Must only be used for responses."; 2862 leaf conflict-status { 2863 type iana-signal:conflict-status; 2864 description 2865 "Indicates the conflict status."; 2866 } 2867 leaf conflict-cause { 2868 type iana-signal:conflict-cause; 2869 description 2870 "Indicates the cause of the conflict."; 2871 } 2872 leaf retry-timer { 2873 type uint32; 2874 units "seconds"; 2875 description 2876 "The DOTS client must not re-send the 2877 same request that has a conflict before the expiry of 2878 this timer."; 2879 } 2880 container conflict-scope { 2881 description 2882 "Provides more information about the conflict scope."; 2883 uses ietf-data:target { 2884 when "../conflict-cause = 'overlapping-targets'"; 2885 } 2886 leaf-list alias-name { 2887 when "../../conflict-cause = 'overlapping-targets'"; 2888 type string; 2889 description 2890 "Conflicting alias-name."; 2891 } 2892 list acl-list { 2893 when "../../conflict-cause = 'conflict-with-acceptlist'"; 2894 key "acl-name"; 2895 description 2896 "List of conflicting ACLs as defined in the DOTS data 2897 channel. These ACLs are uniquely defined by 2898 cuid and acl-name."; 2899 leaf acl-name { 2900 type leafref { 2901 path "/ietf-data:dots-data/ietf-data:dots-client/" 2902 +"ietf-data:acls/ietf-data:acl/ietf-data:name"; 2903 } 2904 description 2905 "Reference to the conflicting ACL name bound to 2906 a DOTS client."; 2907 } 2908 leaf acl-type { 2909 type leafref { 2910 path "/ietf-data:dots-data/ietf-data:dots-client/" 2911 +ietf-data:acls/ietf-data:acl/ietf-data:type"; 2912 } 2913 description 2914 "Reference to the conflicting ACL type bound to 2915 a DOTS client."; 2916 } 2917 } 2918 leaf mid { 2919 when "../../conflict-cause = 'overlapping-targets'"; 2920 type leafref { 2921 path "../../../mid"; 2922 } 2923 description 2924 "Reference to the conflicting 'mid' bound to 2925 the same DOTS client."; 2926 } 2927 } 2928 } 2929 leaf bytes-dropped { 2930 type yang:zero-based-counter64; 2931 units "bytes"; 2932 config false; 2933 description 2934 "The total dropped byte count for the mitigation 2935 request since the attack mitigation is triggered. 2936 The count wraps around when it reaches the maximum value 2937 of counter64 for dropped bytes."; 2938 } 2939 leaf bps-dropped { 2940 type yang:zero-based-counter64; 2941 config false; 2942 description 2943 "The average number of dropped bits per second for 2944 the mitigation request since the attack 2945 mitigation is triggered. This should be a 2946 five-minute average."; 2947 } 2948 leaf pkts-dropped { 2949 type yang:zero-based-counter64; 2950 config false; 2951 description 2952 "The total number of dropped packet count for the 2953 mitigation request since the attack mitigation is 2954 triggered. The count wraps around when it reaches 2955 the maximum value of counter64 for dropped packets."; 2956 } 2957 leaf pps-dropped { 2958 type yang:zero-based-counter64; 2959 config false; 2960 description 2961 "The average number of dropped packets per second 2962 for the mitigation request since the attack 2963 mitigation is triggered. This should be a 2964 five-minute average."; 2965 } 2966 leaf attack-status { 2967 type iana-signal:attack-status; 2968 description 2969 "Indicates the status of an attack as seen by the 2970 DOTS client."; 2971 } 2972 } 2973 } 2975 grouping config-parameters { 2976 description 2977 "Subset of DOTS signal channel session configuration."; 2978 container heartbeat-interval { 2979 description 2980 "DOTS agents regularly send heartbeats to each other 2981 after mutual authentication is successfully 2982 completed in order to keep the DOTS signal channel 2983 open."; 2984 leaf max-value { 2985 type uint16; 2986 units "seconds"; 2987 config false; 2988 description 2989 "Maximum acceptable heartbeat-interval value."; 2990 } 2991 leaf min-value { 2992 type uint16; 2993 units "seconds"; 2994 config false; 2995 description 2996 "Minimum acceptable heartbeat-interval value."; 2997 } 2998 leaf current-value { 2999 type uint16; 3000 units "seconds"; 3001 default "30"; 3002 description 3003 "Current heartbeat-interval value. 3005 '0' means that heartbeat mechanism is deactivated."; 3006 } 3007 } 3008 container missing-hb-allowed { 3009 description 3010 "Maximum number of missing heartbeats allowed."; 3011 leaf max-value { 3012 type uint16; 3013 config false; 3014 description 3015 "Maximum acceptable missing-hb-allowed value."; 3016 } 3017 leaf min-value { 3018 type uint16; 3019 config false; 3020 description 3021 "Minimum acceptable missing-hb-allowed value."; 3022 } 3023 leaf current-value { 3024 type uint16; 3025 default "5"; 3026 description 3027 "Current missing-hb-allowed value."; 3028 } 3029 } 3030 container max-retransmit { 3031 description 3032 "Maximum number of retransmissions of a Confirmable 3033 message."; 3034 leaf max-value { 3035 type uint16; 3036 config false; 3037 description 3038 "Maximum acceptable max-retransmit value."; 3039 } 3040 leaf min-value { 3041 type uint16; 3042 config false; 3043 description 3044 "Minimum acceptable max-retransmit value."; 3045 } 3046 leaf current-value { 3047 type uint16; 3048 default "3"; 3049 description 3050 "Current max-retransmit value."; 3051 } 3052 } 3053 container ack-timeout { 3054 description 3055 "Initial retransmission timeout value."; 3056 leaf max-value-decimal { 3057 type decimal64 { 3058 fraction-digits 2; 3059 } 3060 units "seconds"; 3061 config false; 3062 description 3063 "Maximum ack-timeout value."; 3064 } 3065 leaf min-value-decimal { 3066 type decimal64 { 3067 fraction-digits 2; 3068 } 3069 units "seconds"; 3070 config false; 3071 description 3072 "Minimum ack-timeout value."; 3073 } 3074 leaf current-value-decimal { 3075 type decimal64 { 3076 fraction-digits 2; 3077 } 3078 units "seconds"; 3079 default "2"; 3080 description 3081 "Current ack-timeout value."; 3082 } 3083 } 3084 container ack-random-factor { 3085 description 3086 "Random factor used to influence the timing of 3087 retransmissions."; 3088 leaf max-value-decimal { 3089 type decimal64 { 3090 fraction-digits 2; 3091 } 3092 config false; 3093 description 3094 "Maximum acceptable ack-random-factor value."; 3095 } 3096 leaf min-value-decimal { 3097 type decimal64 { 3098 fraction-digits 2; 3099 } 3100 config false; 3101 description 3102 "Minimum acceptable ack-random-factor value."; 3103 } 3104 leaf current-value-decimal { 3105 type decimal64 { 3106 fraction-digits 2; 3107 } 3108 default "1.5"; 3109 description 3110 "Current ack-random-factor value."; 3111 } 3112 } 3113 } 3115 grouping signal-config { 3116 description 3117 "DOTS signal channel session configuration."; 3118 leaf sid { 3119 type uint32; 3120 mandatory true; 3121 description 3122 "An identifier for the DOTS signal channel 3123 session configuration data."; 3124 } 3125 container mitigating-config { 3126 description 3127 "Configuration parameters to use when a mitigation 3128 is active."; 3129 uses config-parameters; 3130 } 3131 container idle-config { 3132 description 3133 "Configuration parameters to use when no mitigation 3134 is active."; 3135 uses config-parameters; 3136 } 3137 } 3139 grouping redirected-signal { 3140 description 3141 "Grouping for the redirected signaling."; 3142 leaf alt-server { 3143 type string; 3144 config false; 3145 mandatory true; 3146 description 3147 "FQDN of an alternate server."; 3148 } 3149 leaf-list alt-server-record { 3150 type inet:ip-address; 3151 config false; 3152 description 3153 "List of records for the alternate server."; 3154 } 3155 } 3157 /* 3158 * Main Container for DOTS Signal Channel 3159 */ 3161 container dots-signal { 3162 description 3163 "Main container for DOTS signal message. 3165 A DOTS signal message can be a mitigation, a configuration, 3166 or a redirected signal message."; 3167 choice message-type { 3168 description 3169 "Can be a mitigation, a configuration, or a redirect 3170 message."; 3171 case mitigation-scope { 3172 description 3173 "Mitigation scope of a mitigation message."; 3174 uses mitigation-scope; 3175 } 3176 case signal-config { 3177 description 3178 "Configuration message."; 3179 uses signal-config; 3180 } 3181 case redirected-signal { 3182 description 3183 "Redirected signaling."; 3184 uses redirected-signal; 3185 } 3186 } 3187 } 3188 } 3189 3191 6. YANG/JSON Mapping Parameters to CBOR 3193 All parameters in the payload of the DOTS signal channel MUST be 3194 mapped to CBOR types as shown in Table 4 and are assigned an integer 3195 key to save space. The CBOR key values are divided into two types: 3196 comprehension-required and comprehension-optional. DOTS agents can 3197 safely ignore comprehension-optional values they don't understand, 3198 but cannot successfully process a request if it contains 3199 comprehension-required values that are not understood. The 4.00 3200 response SHOULD include a diagnostic payload describing the unknown 3201 comprehension-required CBOR key values. The initial set of CBOR key 3202 values defined in this specification are of type comprehension- 3203 required. 3205 +----------------------+-------------+-----+---------------+--------+ 3206 | Parameter Name | YANG | CBOR| CBOR Major | JSON | 3207 | | Type | Key | Type & | Type | 3208 | | | | Information | | 3209 +----------------------+-------------+-----+---------------+--------+ 3210 | ietf-dots-signal-cha | | | | | 3211 | nnel:mitigation-scope| container | 1 | 5 map | Object | 3212 | scope | list | 2 | 4 array | Array | 3213 | cdid | string | 3 | 3 text string | String | 3214 | cuid | string | 4 | 3 text string | String | 3215 | mid | uint32 | 5 | 0 unsigned | Number | 3216 | target-prefix | leaf-list | 6 | 4 array | Array | 3217 | | inet: | | | | 3218 | | ip-prefix | | 3 text string | String | 3219 | target-port-range | list | 7 | 4 array | Array | 3220 | lower-port | inet: | | | | 3221 | | port-number| 8 | 0 unsigned | Number | 3222 | upper-port | inet: | | | | 3223 | | port-number| 9 | 0 unsigned | Number | 3224 | target-protocol | leaf-list | 10 | 4 array | Array | 3225 | | uint8 | | 0 unsigned | Number | 3226 | target-fqdn | leaf-list | 11 | 4 array | Array | 3227 | | inet: | | | | 3228 | | domain-name| | 3 text string | String | 3229 | target-uri | leaf-list | 12 | 4 array | Array | 3230 | | inet:uri | | 3 text string | String | 3231 | alias-name | leaf-list | 13 | 4 array | Array | 3232 | | string | | 3 text string | String | 3233 | lifetime | int32 | 14 | 0 unsigned | Number | 3234 | | | | 1 negative | Number | 3235 | mitigation-start | uint64 | 15 | 0 unsigned | String | 3236 | status | enumeration | 16 | 0 unsigned | String | 3237 | conflict-information | container | 17 | 5 map | Object | 3238 | conflict-status | enumeration | 18 | 0 unsigned | String | 3239 | conflict-cause | enumeration | 19 | 0 unsigned | String | 3240 | retry-timer | uint32 | 20 | 0 unsigned | Number | 3241 | conflict-scope | container | 21 | 5 map | Object | 3242 | acl-list | list | 22 | 4 array | Array | 3243 | acl-name | leafref | 23 | 3 text string | String | 3244 | acl-type | leafref | 24 | 3 text string | String | 3245 | bytes-dropped | yang:zero- | | | | 3246 | | based- | | | | 3247 | | counter64 | 25 | 0 unsigned | String | 3248 | bps-dropped | yang:zero- | | | | 3249 | | based- | | | | 3250 | | counter64 | 26 | 0 unsigned | String | 3251 | pkts-dropped | yang:zero- | | | | 3252 | | based- | | | | 3253 | | counter64 | 27 | 0 unsigned | String | 3254 | pps-dropped | yang:zero- | | | | 3255 | | based- | | | | 3256 | | counter64 | 28 | 0 unsigned | String | 3257 | attack-status | enumeration | 29 | 0 unsigned | String | 3258 | ietf-dots-signal- | | | | | 3259 | channel:signal-config| container | 30 | 5 map | Object | 3260 | sid | uint32 | 31 | 0 unsigned | Number | 3261 | mitigating-config | container | 32 | 5 map | Object | 3262 | heartbeat-interval | container | 33 | 5 map | Object | 3263 | max-value | uint16 | 34 | 0 unsigned | Number | 3264 | min-value | uint16 | 35 | 0 unsigned | Number | 3265 | current-value | uint16 | 36 | 0 unsigned | Number | 3266 | missing-hb-allowed | container | 37 | 5 map | Object | 3267 | max-retransmit | container | 38 | 5 map | Object | 3268 | ack-timeout | container | 39 | 5 map | Object | 3269 | ack-random-factor | container | 40 | 5 map | Object | 3270 | max-value-decimal | decimal64 | 41 | 6 tag 4 | | 3271 | | | | [-2, integer]| String | 3272 | min-value-decimal | decimal64 | 42 | 6 tag 4 | | 3273 | | | | [-2, integer]| String | 3274 | current-value-decimal| decimal64 | 43 | 6 tag 4 | | 3275 | | | | [-2, integer]| String | 3276 | idle-config | container | 44 | 5 map | Object | 3277 | trigger-mitigation | boolean | 45 | 7 bits 20 | False | 3278 | | | | 7 bits 21 | True | 3279 | ietf-dots-signal-cha | | | | | 3280 |nnel:redirected-signal| container | 46 | 5 map | Object | 3281 | alt-server | string | 47 | 3 text string | String | 3282 | alt-server-record | leaf-list | 48 | 4 array | Array | 3283 | | inet: | | | | 3284 | | ip-address | | 3 text string | String | 3285 +----------------------+-------------+-----+---------------+--------+ 3287 Table 4: CBOR Key Values Used in DOTS Signal Channel Messages & Their 3288 Mappings to JSON and YANG 3290 7. (D)TLS Protocol Profile and Performance Considerations 3292 7.1. (D)TLS Protocol Profile 3294 This section defines the (D)TLS protocol profile of DOTS signal 3295 channel over (D)TLS and DOTS data channel over TLS. 3297 There are known attacks on (D)TLS, such as man-in-the-middle and 3298 protocol downgrade attacks. These are general attacks on (D)TLS and, 3299 as such, they are not specific to DOTS over (D)TLS; refer to the 3300 (D)TLS RFCs for discussion of these security issues. DOTS agents 3301 MUST adhere to the (D)TLS implementation recommendations and security 3302 considerations of [RFC7525] except with respect to (D)TLS version. 3303 Since DOTS signal channel encryption relying upon (D)TLS is virtually 3304 a green-field deployment, DOTS agents MUST implement only (D)TLS 1.2 3305 or later. 3307 When a DOTS client is configured with a domain name of the DOTS 3308 server, and connects to its configured DOTS server, the server may 3309 present it with a PKIX certificate. In order to ensure proper 3310 authentication, a DOTS client MUST verify the entire certification 3311 path per [RFC5280]. The DOTS client additionally uses [RFC6125] 3312 validation techniques to compare the domain name with the certificate 3313 provided. 3315 A key challenge to deploying DOTS is the provisioning of DOTS 3316 clients, including the distribution of keying material to DOTS 3317 clients to enable the required mutual authentication of DOTS agents. 3318 Enrollment over Secure Transport (EST) [RFC7030] defines a method of 3319 certificate enrollment by which domains operating DOTS servers may 3320 provide DOTS clients with all the necessary cryptographic keying 3321 material, including a private key and a certificate to authenticate 3322 themselves. One deployment option is DOTS clients behave as EST 3323 clients for certificate enrollment from an EST server provisioned by 3324 the mitigation provider. This document does not specify which EST or 3325 other mechanism the DOTS client uses to achieve initial enrollment. 3327 The Server Name Indication (SNI) extension [RFC6066] defines a 3328 mechanism for a client to tell a (D)TLS server the name of the server 3329 it wants to contact. This is a useful extension for hosting 3330 environments where multiple virtual servers are reachable over a 3331 single IP address. The DOTS client may or may not know if it is 3332 interacting with a DOTS server in a virtual server hosting 3333 environment, so the DOTS client SHOULD include the DOTS server FQDN 3334 in the SNI extension. 3336 Implementations compliant with this profile MUST implement all of the 3337 following items: 3339 o DTLS record replay detection (Section 3.3 of [RFC6347]) or an 3340 equivalent mechanism to protect against replay attacks. 3342 o DTLS session resumption without server-side state to resume 3343 session and convey the DOTS signal. 3345 o At least one of raw public keys [RFC7250] or PSK handshake 3346 [RFC4279] with (EC)DHE key exchange which reduces the size of the 3347 ServerHello, and can be used by DOTS agents that cannot obtain 3348 certificates. 3350 Implementations compliant with this profile SHOULD implement all of 3351 the following items to reduce the delay required to deliver a DOTS 3352 signal channel message: 3354 o TLS False Start [RFC7918] which reduces round-trips by allowing 3355 the TLS client's second flight of messages (ChangeCipherSpec) to 3356 also contain the DOTS signal. TLS False Start is formally defined 3357 for use with TLS, but the same technique is applicable to DTLS as 3358 well. 3360 o Cached Information Extension [RFC7924] which avoids transmitting 3361 the server's certificate and certificate chain if the client has 3362 cached that information from a previous TLS handshake. 3364 Compared to UDP, DOTS signal channel over TCP requires an additional 3365 round-trip time (RTT) of latency to establish a TCP connection. DOTS 3366 implementations are encouraged to implement TCP Fast Open [RFC7413] 3367 to eliminate that RTT. 3369 7.2. (D)TLS 1.3 Considerations 3371 TLS 1.3 provides critical latency improvements for connection 3372 establishment over TLS 1.2. The DTLS 1.3 protocol 3373 [I-D.ietf-tls-dtls13] is based upon the TLS 1.3 protocol and provides 3374 equivalent security guarantees. (D)TLS 1.3 provides two basic 3375 handshake modes the DOTS signal channel can take advantage of: 3377 o A full handshake mode in which a DOTS client can send a DOTS 3378 mitigation request message after one round trip and the DOTS 3379 server immediately responds with a DOTS mitigation response. This 3380 assumes no packet loss is experienced. 3382 o 0-RTT mode in which the DOTS client can authenticate itself and 3383 send DOTS mitigation request messages in the first message, thus 3384 reducing handshake latency. 0-RTT only works if the DOTS client 3385 has previously communicated with that DOTS server, which is very 3386 likely with the DOTS signal channel. 3388 The DOTS client has to establish a (D)TLS session with the DOTS 3389 server during peacetime and share a PSK. 3391 During a DDoS attack, the DOTS client can use the (D)TLS session 3392 to convey the DOTS mitigation request message and, if there is no 3393 response from the server after multiple retries, the DOTS client 3394 can resume the (D)TLS session in 0-RTT mode using PSK. 3396 Section 8 of [RFC8446] discusses some mechanisms to implement to 3397 limit the impact of replay attacks on 0-RTT data. If the DOTS 3398 server accepts 0-RTT, it MUST implement one of these mechanisms. 3399 A DOTS server can reject 0-RTT by sending a TLS HelloRetryRequest. 3400 The DOTS signal channel messages sent as early data by the DOTS 3401 client are idempotent requests. As a reminder, Message ID 3402 (Section 3 of [RFC7252]) is changed each time a new CoAP request 3403 is sent, and the Token (Section 5.3.1 of [RFC7252]) is randomized 3404 in each CoAP request. The DOTS server(s) can use Message ID and 3405 Token in the DOTS signal channel message to detect replay of early 3406 data, and accept 0-RTT data at most once. Furthermore, 'mid' 3407 value is monotonically increased by the DOTS client for each 3408 mitigation request, attackers replaying mitigation requests with 3409 lower numeric 'mid' values and overlapping scopes with mitigation 3410 requests having higher numeric 'mid' values will be rejected 3411 systematically by the DOTS server. 3413 Owing to the aforementioned protections, especially those afforded 3414 by CoAP deduplication (Section 4.5 of [RFC7252]) and RFC 8446 3415 anti-replay mechanisms, all DOTS signal channel requests are safe 3416 to transmit in TLS 1.3 as early data. Refer to 3417 [I-D.boucadair-dots-earlydata] for more details. 3419 A simplified TLS 1.3 handshake with 0-RTT DOTS mitigation request 3420 message exchange is shown in Figure 26. 3422 DOTS Client DOTS Server 3424 ClientHello 3425 (0-RTT DOTS signal message) 3426 --------> 3427 ServerHello 3428 {EncryptedExtensions} 3429 {Finished} 3430 <-------- [DOTS signal message] 3431 (end_of_early_data) 3432 {Finished} --------> 3433 [DOTS signal message] <-------> [DOTS signal message] 3435 Note that: 3436 () Indicates messages protected 0-RTT keys 3437 {} Indicates messages protected using handshake keys 3438 [] Indicates messages protected using 1-RTT keys 3440 Figure 26: A Simplified TLS 1.3 Handshake with 0-RTT 3442 7.3. DTLS MTU and Fragmentation 3444 To avoid DOTS signal message fragmentation and the subsequent 3445 decreased probability of message delivery, DOTS agents MUST ensure 3446 that the DTLS record MUST fit within a single datagram. If the path 3447 MTU is not known to the DOTS server, an IP MTU of 1280 bytes SHOULD 3448 be assumed. The DOTS client must consider the amount of record 3449 expansion expected by the DTLS processing when calculating the size 3450 of CoAP message that fits within the path MTU. Path MTU MUST be 3451 greater than or equal to [CoAP message size + DTLS 1.2 overhead of 13 3452 octets + authentication overhead of the negotiated DTLS cipher suite 3453 + block padding] (Section 4.1.1.1 of [RFC6347]). If the total 3454 request size exceeds the path MTU then the DOTS client MUST split the 3455 DOTS signal into separate messages; for example, the list of 3456 addresses in the 'target-prefix' parameter could be split into 3457 multiple lists and each list conveyed in a new PUT request. 3459 Implementation Note: DOTS choice of message size parameters works 3460 well with IPv6 and with most of today's IPv4 paths. However, with 3461 IPv4, it is harder to safely make sure that there is no IP 3462 fragmentation. If the IPv4 path MTU is unknown, implementations may 3463 want to limit themselves to more conservative IPv4 datagram sizes 3464 such as 576 bytes, as per [RFC0791]. IP packets whose size does not 3465 exceed 576 bytes should never need to be fragmented: therefore, 3466 sending a maximum of 500 bytes of DOTS signal over a UDP datagram 3467 will generally avoid IP fragmentation. 3469 8. Mutual Authentication of DOTS Agents & Authorization of DOTS Clients 3471 (D)TLS based upon client certificate can be used for mutual 3472 authentication between DOTS agents. If, for example, a DOTS gateway 3473 is involved, DOTS clients and DOTS gateways must perform mutual 3474 authentication; only authorized DOTS clients are allowed to send DOTS 3475 signals to a DOTS gateway. The DOTS gateway and the DOTS server must 3476 perform mutual authentication; a DOTS server only allows DOTS signal 3477 channel messages from an authorized DOTS gateway, thereby creating a 3478 two-link chain of transitive authentication between the DOTS client 3479 and the DOTS server. 3481 The DOTS server should support certificate-based client 3482 authentication. The DOTS client should respond to the DOTS server's 3483 TLS CertificateRequest message with the PKIX certificate held by the 3484 DOTS client. DOTS client certificate validation must be performed as 3485 per [RFC5280] and the DOTS client certificate must conform to the 3486 [RFC5280] certificate profile. If a DOTS client does not support TLS 3487 client certificate authentication, it must support pre-shared key 3488 based or raw public key based client authentication. 3490 +-----------------------------------------------+ 3491 | example.com domain +---------+ | 3492 | | AAA | | 3493 | +---------------+ | Server | | 3494 | | Application | +------+--+ | 3495 | | server +<-----------------+ ^ | 3496 | | (DOTS client) | | | | 3497 | +---------------+ | | | 3498 | V V | example.net domain 3499 | +-----+----+--+ | +---------------+ 3500 | +--------------+ | | | | | 3501 | | Guest +<-----x----->+ DOTS +<------>+ DOTS | 3502 | | (DOTS client)| | gateway | | | server | 3503 | +--------------+ | | | | | 3504 | +----+--------+ | +---------------+ 3505 | ^ | 3506 | | | 3507 | +----------------+ | | 3508 | | DDoS detector | | | 3509 | | (DOTS client) +<---------------+ | 3510 | +----------------+ | 3511 +-----------------------------------------------+ 3513 Figure 27: Example of Authentication and Authorization of DOTS Agents 3515 In the example depicted in Figure 27, the DOTS gateway and DOTS 3516 clients within the 'example.com' domain mutually authenticate. After 3517 the DOTS gateway validates the identity of a DOTS client, it 3518 communicates with the AAA server in the 'example.com' domain to 3519 determine if the DOTS client is authorized to request DDoS 3520 mitigation. If the DOTS client is not authorized, a 4.01 3521 (Unauthorized) is returned in the response to the DOTS client. In 3522 this example, the DOTS gateway only allows the application server and 3523 DDoS attack detector to request DDoS mitigation, but does not permit 3524 the user of type 'guest' to request DDoS mitigation. 3526 Also, DOTS gateways and servers located in different domains must 3527 perform mutual authentication (e.g., using certificates). A DOTS 3528 server will only allow a DOTS gateway with a certificate for a 3529 particular domain to request mitigation for that domain. In 3530 reference to Figure 27, the DOTS server only allows the DOTS gateway 3531 to request mitigation for 'example.com' domain and not for other 3532 domains. 3534 9. IANA Considerations 3536 9.1. DOTS Signal Channel UDP and TCP Port Number 3538 IANA is requested to assign the port number TBD to the DOTS signal 3539 channel protocol for both UDP and TCP from the "Service Name and 3540 Transport Protocol Port Number Registry" available at 3541 https://www.iana.org/assignments/service-names-port-numbers/service- 3542 names-port-numbers.xhtml. 3544 The assignment of port number 4646 is strongly suggested, as 4646 is 3545 the ASCII decimal value for ".." (DOTS). 3547 9.2. Well-Known 'dots' URI 3549 This document requests IANA to register the 'dots' well-known URI 3550 (Table 5) in the Well-Known URIs registry 3551 (https://www.iana.org/assignments/well-known-uris/well-known- 3552 uris.xhtml) as defined by [RFC5785]: 3554 +----------+----------------+---------------------+-----------------+ 3555 | URI | Change | Specification | Related | 3556 | suffix | controller | document(s) | information | 3557 +----------+----------------+---------------------+-----------------+ 3558 | dots | IETF | [RFCXXXX] | None | 3559 +----------+----------------+---------------------+-----------------+ 3561 Table 5: 'dots' well-known URI 3563 9.3. Media Type Registration 3565 This document requests IANA to register the "application/dots+cbor" 3566 media type in the "Media Types" registry [IANA.MediaTypes] in the 3567 manner described in [RFC6838], which can be used to indicate that the 3568 content is a DOTS signal channel object: 3570 o Type name: application 3571 o Subtype name: dots+cbor 3572 o Required parameters: N/A 3573 o Optional parameters: N/A 3574 o Encoding considerations: binary 3575 o Security considerations: See the Security Considerations section 3576 of [RFCXXXX] 3577 o Interoperability considerations: N/A 3578 o Published specification: [RFCXXXX] 3579 o Applications that use this media type: DOTS agents sending DOTS 3580 messages over CoAP over (D)TLS. 3581 o Fragment identifier considerations: N/A 3582 o Additional information: 3584 Magic number(s): N/A 3585 File extension(s): N/A 3586 Macintosh file type code(s): N/A 3587 o Person & email address to contact for further information: 3588 IESG, iesg@ietf.org 3589 o Intended usage: COMMON 3590 o Restrictions on usage: none 3591 o Author: See Authors' Addresses section. 3592 o Change controller: IESG 3593 o Provisional registration? No 3595 9.4. CoAP Content-Formats Registration 3597 This document requests IANA to register the CoAP Content-Format ID 3598 for the "application/dots+cbor" media type in the "CoAP Content- 3599 Formats" registry [IANA.CoAP.Content-Formats] (0-255 range): 3601 o Media Type: application/dots+cbor 3602 o Encoding: - 3603 o Id: TBD1 3604 o Reference: [RFCXXXX] 3606 9.5. CBOR Tag Registration 3608 This section defines the DOTS CBOR tag as another means for 3609 applications to declare that a CBOR data structure is a DOTS signal 3610 channel object. Its use is optional and is intended for use in cases 3611 in which this information would not otherwise be known. DOTS CBOR 3612 tag is not required for DOTS signal channel protocol version 3613 specified in this document. If present, the DOTS tag MUST prefix a 3614 DOTS signal channel object. 3616 This document requests IANA to register the DOTS signal channel CBOR 3617 tag in the "CBOR Tags" registry [IANA.CBOR.Tags] using the 24-255 3618 range: 3620 o CBOR Tag: TBD2 (please assign the same value as the Content- 3621 Format) 3622 o Data Item: DDoS Open Threat Signaling (DOTS) signal channel object 3623 o Semantics: DDoS Open Threat Signaling (DOTS) signal channel 3624 object, as defined in [RFCXXXX] 3625 o Description of Semantics: [RFCXXXX] 3627 9.6. DOTS Signal Channel Protocol Registry 3629 The document requests IANA to create a new registry, entitled "DOTS 3630 Signal Channel Registry". The following sections define sub- 3631 registries. 3633 9.6.1. DOTS Signal Channel CBOR Key Values Sub-Registry 3635 The document requests IANA to create a new sub-registry, entitled 3636 "DOTS Signal Channel CBOR Key Values". 3638 The structure of this sub-registry is provided in Section 9.6.1.1. 3639 Section 9.6.1.2 provides how the registry is initially populated with 3640 the values in Table 4. 3642 9.6.1.1. Registration Template 3644 Parameter name: 3645 Parameter name as used in the DOTS signal channel. 3647 CBOR Key Value: 3648 Key value for the parameter. The key value MUST be an integer in 3649 the 1-65535 range. The key values of the comprehension-required 3650 range (0x0001 - 0x3FFF) and of the comprehension-optional range 3651 (0x8000 - 0xBFFF) are assigned by IETF Review (Section 4.8 of 3652 [RFC8126]). The key values of the comprehension-optional range 3653 (0x4000 - 0x7FFF) are assigned by Specification Required 3654 (Section 4.6 of [RFC8126]) and of the comprehension-optional range 3655 (0xC000 - 0xFFFF) are reserved for Private Use (Section 4.1 of 3656 [RFC8126]). 3658 Registration requests for the 0x4000 - 0x7FFF range are evaluated 3659 after a three-week review period on the dots-signal-reg- 3660 review@ietf.org mailing list, on the advice of one or more 3661 Designated Experts. However, to allow for the allocation of 3662 values prior to publication, the Designated Experts may approve 3663 registration once they are satisfied that such a specification 3664 will be published. Registration requests sent to the mailing list 3665 for review should use an appropriate subject (e.g., "Request to 3666 register CBOR Key Value: example"). 3668 Within the review period, the Designated Experts will either 3669 approve or deny the registration request, communicating this 3670 decision to the review list and IANA. Denials should include an 3671 explanation and, if applicable, suggestions as to how to make the 3672 request successful. Registration requests that are undetermined 3673 for a period longer than 21 days can be brought to the IESG's 3674 attention (using the iesg@ietf.org mailing list) for resolution. 3676 Criteria that should be applied by the Designated Experts includes 3677 determining whether the proposed registration duplicates existing 3678 functionality, whether it is likely to be of general applicability 3679 or whether it is useful only for a single use case, and whether 3680 the registration description is clear. IANA must only accept 3681 registry updates to the 0x4000 - 0x7FFF range from the Designated 3682 Experts and should direct all requests for registration to the 3683 review mailing list. It is suggested that multiple Designated 3684 Experts be appointed. In cases where a registration decision 3685 could be perceived as creating a conflict of interest for a 3686 particular Expert, that Expert should defer to the judgment of the 3687 other Experts. 3689 CBOR Major Type: 3690 CBOR Major type and optional tag for the parameter. 3692 Change Controller: 3693 For Standards Track RFCs, list the "IESG". For others, give the 3694 name of the responsible party. Other details (e.g., email 3695 address) may also be included. 3697 Specification Document(s): 3698 Reference to the document or documents that specify the parameter, 3699 preferably including URIs that can be used to retrieve copies of 3700 the documents. An indication of the relevant sections may also be 3701 included but is not required. 3703 9.6.1.2. Initial Sub-Registry Content 3705 +----------------------+-------+-------+------------+---------------+ 3706 | Parameter Name | CBOR | CBOR | Change | Specification | 3707 | | Key | Major | Controller | Document(s) | 3708 | | Value | Type | | | 3709 +----------------------+-------+-------+------------+---------------+ 3710 | ietf-dots-signal-chan| 1 | 5 | IESG | [RFCXXXX] | 3711 | nel:mitigation-scope | | | | | 3712 | scope | 2 | 4 | IESG | [RFCXXXX] | 3713 | cdid | 3 | 3 | IESG | [RFCXXXX] | 3714 | cuid | 4 | 3 | IESG | [RFCXXXX] | 3715 | mid | 5 | 0 | IESG | [RFCXXXX] | 3716 | target-prefix | 6 | 4 | IESG | [RFCXXXX] | 3717 | target-port-range | 7 | 4 | IESG | [RFCXXXX] | 3718 | lower-port | 8 | 0 | IESG | [RFCXXXX] | 3719 | upper-port | 9 | 0 | IESG | [RFCXXXX] | 3720 | target-protocol | 10 | 4 | IESG | [RFCXXXX] | 3721 | target-fqdn | 11 | 4 | IESG | [RFCXXXX] | 3722 | target-uri | 12 | 4 | IESG | [RFCXXXX] | 3723 | alias-name | 13 | 4 | IESG | [RFCXXXX] | 3724 | lifetime | 14 | 0/1 | IESG | [RFCXXXX] | 3725 | mitigation-start | 15 | 0 | IESG | [RFCXXXX] | 3726 | status | 16 | 0 | IESG | [RFCXXXX] | 3727 | conflict-information | 17 | 5 | IESG | [RFCXXXX] | 3728 | conflict-status | 18 | 0 | IESG | [RFCXXXX] | 3729 | conflict-cause | 19 | 0 | IESG | [RFCXXXX] | 3730 | retry-timer | 20 | 0 | IESG | [RFCXXXX] | 3731 | conflict-scope | 21 | 5 | IESG | [RFCXXXX] | 3732 | acl-list | 22 | 4 | IESG | [RFCXXXX] | 3733 | acl-name | 23 | 3 | IESG | [RFCXXXX] | 3734 | acl-type | 24 | 3 | IESG | [RFCXXXX] | 3735 | bytes-dropped | 25 | 0 | IESG | [RFCXXXX] | 3736 | bps-dropped | 26 | 0 | IESG | [RFCXXXX] | 3737 | pkts-dropped | 27 | 0 | IESG | [RFCXXXX] | 3738 | pps-dropped | 28 | 0 | IESG | [RFCXXXX] | 3739 | attack-status | 29 | 0 | IESG | [RFCXXXX] | 3740 | ietf-dots-signal- | 30 | 5 | IESG | [RFCXXXX] | 3741 | channel:signal-config| | | | | 3742 | sid | 31 | 0 | IESG | [RFCXXXX] | 3743 | mitigating-config | 32 | 5 | IESG | [RFCXXXX] | 3744 | heartbeat-interval | 33 | 5 | IESG | [RFCXXXX] | 3745 | min-value | 34 | 0 | IESG | [RFCXXXX] | 3746 | max-value | 35 | 0 | IESG | [RFCXXXX] | 3747 | current-value | 36 | 0 | IESG | [RFCXXXX] | 3748 | missing-hb-allowed | 37 | 5 | IESG | [RFCXXXX] | 3749 | max-retransmit | 38 | 5 | IESG | [RFCXXXX] | 3750 | ack-timeout | 39 | 5 | IESG | [RFCXXXX] | 3751 | ack-random-factor | 40 | 5 | IESG | [RFCXXXX] | 3752 | min-value-decimal | 41 | 6tag4 | IESG | [RFCXXXX] | 3753 | max-value-decimal | 42 | 6tag4 | IESG | [RFCXXXX] | 3754 | current-value- | 43 | 6tag4 | IESG | [RFCXXXX] | 3755 | decimal | | | | | 3756 | idle-config | 44 | 5 | IESG | [RFCXXXX] | 3757 | trigger-mitigation | 45 | 7 | IESG | [RFCXXXX] | 3758 | ietf-dots-signal-chan| 46 | 5 | IESG | [RFCXXXX] | 3759 | nel:redirected-signal| | | | | 3760 | alt-server | 47 | 3 | IESG | [RFCXXXX] | 3761 | alt-server-record | 48 | 4 | IESG | [RFCXXXX] | 3762 +----------------------+-------+-------+------------+---------------+ 3764 Table 6: Initial DOTS Signal Channel CBOR Key Values Registry 3766 9.6.2. Status Codes Sub-Registry 3768 The document requests IANA to create a new sub-registry, entitled 3769 "DOTS Signal Channel Status Codes". Codes in this registry are used 3770 as valid values of 'status' parameter. 3772 The registry is initially populated with the following values: 3774 +-----+----------------------------------+--------------+-----------+ 3775 | Cod | Label | Description | Reference | 3776 | e | | | | 3777 +-----+----------------------------------+--------------+-----------+ 3778 | 1 | attack-mitigation-in-progress | Attack | [RFCXXXX] | 3779 | | | mitigation | | 3780 | | | setup is in | | 3781 | | | progress | | 3782 | | | (e.g., | | 3783 | | | changing the | | 3784 | | | network path | | 3785 | | | to redirect | | 3786 | | | the inbound | | 3787 | | | traffic to a | | 3788 | | | DOTS | | 3789 | | | mitigator). | | 3790 | 2 | attack-successfully-mitigated | Attack is | [RFCXXXX] | 3791 | | | being | | 3792 | | | successfully | | 3793 | | | mitigated | | 3794 | | | (e.g., | | 3795 | | | traffic is | | 3796 | | | redirected | | 3797 | | | to a DDoS | | 3798 | | | mitigator | | 3799 | | | and attack | | 3800 | | | traffic is | | 3801 | | | dropped). | | 3802 | 3 | attack-stopped | Attack has | [RFCXXXX] | 3803 | | | stopped and | | 3804 | | | the DOTS | | 3805 | | | client can | | 3806 | | | withdraw the | | 3807 | | | mitigation | | 3808 | | | request. | | 3809 | 4 | attack-exceeded-capability | Attack has | [RFCXXXX] | 3810 | | | exceeded the | | 3811 | | | mitigation | | 3812 | | | provider | | 3813 | | | capability. | | 3814 | 5 | dots-client-withdrawn-mitigation | DOTS client | [RFCXXXX] | 3815 | | | has | | 3816 | | | withdrawn | | 3817 | | | the | | 3818 | | | mitigation | | 3819 | | | request and | | 3820 | | | the | | 3821 | | | mitigation | | 3822 | | | is active | | 3823 | | | but | | 3824 | | | terminating. | | 3825 | 6 | attack-mitigation-terminated | Attack | [RFCXXXX] | 3826 | | | mitigation | | 3827 | | | is now | | 3828 | | | terminated. | | 3829 | 7 | attack-mitigation-withdrawn | Attack | [RFCXXXX] | 3830 | | | mitigation | | 3831 | | | is | | 3832 | | | withdrawn. | | 3833 | 8 | attack-mitigation-signal-loss | Attack | [RFCXXXX] | 3834 | | | mitigation | | 3835 | | | will be | | 3836 | | | triggered | | 3837 | | | for the | | 3838 | | | mitigation | | 3839 | | | request only | | 3840 | | | when the | | 3841 | | | DOTS signal | | 3842 | | | channel | | 3843 | | | session is | | 3844 | | | lost. | | 3845 +-----+----------------------------------+--------------+-----------+ 3846 New codes can be assigned via Standards Action [RFC8126]. 3848 9.6.3. Conflict Status Codes Sub-Registry 3850 The document requests IANA to create a new sub-registry, entitled 3851 "DOTS Signal Channel Conflict Status Codes". Codes in this registry 3852 are used as valid values of 'conflict-status' parameter. 3854 The registry is initially populated with the following values: 3856 +------+-------------------------------+----------------+-----------+ 3857 | Code | Label | Description | Reference | 3858 +------+-------------------------------+----------------+-----------+ 3859 | 1 | request-inactive-other-active | DOTS server | [RFCXXXX] | 3860 | | | has detected | | 3861 | | | conflicting | | 3862 | | | mitigation | | 3863 | | | requests from | | 3864 | | | different DOTS | | 3865 | | | clients. This | | 3866 | | | mitigation | | 3867 | | | request is | | 3868 | | | currently | | 3869 | | | inactive until | | 3870 | | | the conflicts | | 3871 | | | are resolved. | | 3872 | | | Another | | 3873 | | | mitigation | | 3874 | | | request is | | 3875 | | | active. | | 3876 | 2 | request-active | DOTS server | [RFCXXXX] | 3877 | | | has detected | | 3878 | | | conflicting | | 3879 | | | mitigation | | 3880 | | | requests from | | 3881 | | | different DOTS | | 3882 | | | clients. This | | 3883 | | | mitigation | | 3884 | | | request is | | 3885 | | | currently | | 3886 | | | active. | | 3887 | 3 | all-requests-inactive | DOTS server | [RFCXXXX] | 3888 | | | has detected | | 3889 | | | conflicting | | 3890 | | | mitigation | | 3891 | | | requests from | | 3892 | | | different DOTS | | 3893 | | | clients. All | | 3894 | | | conflicting | | 3895 | | | mitigation | | 3896 | | | requests are | | 3897 | | | inactive. | | 3898 +------+-------------------------------+----------------+-----------+ 3900 New codes can be assigned via Standards Action [RFC8126]. 3902 9.6.4. Conflict Cause Codes Sub-Registry 3904 The document requests IANA to create a new sub-registry, entitled 3905 "DOTS Signal Channel Conflict Cause Codes". Codes in this registry 3906 are used as valid values of 'conflict-cause' parameter. 3908 The registry is initially populated with the following values: 3910 +------+--------------------------+---------------------+-----------+ 3911 | Code | Label | Description | Reference | 3912 +------+--------------------------+---------------------+-----------+ 3913 | 1 | overlapping-targets | Overlapping | [RFCXXXX] | 3914 | | | targets. | | 3915 | 2 | conflict-with-acceptlist | Conflicts with an | [RFCXXXX] | 3916 | | | existing accept- | | 3917 | | | list. This code is | | 3918 | | | returned when the | | 3919 | | | DDoS mitigation | | 3920 | | | detects source | | 3921 | | | addresses/prefixes | | 3922 | | | in the accept- | | 3923 | | | listed ACLs are | | 3924 | | | attacking the | | 3925 | | | target. | | 3926 | 3 | cuid-collision | CUID Collision. | [RFCXXXX] | 3927 | | | This code is | | 3928 | | | returned when a | | 3929 | | | DOTS client uses a | | 3930 | | | 'cuid' that is | | 3931 | | | already used by | | 3932 | | | another DOTS | | 3933 | | | client. | | 3934 +------+--------------------------+---------------------+-----------+ 3936 New codes can be assigned via Standards Action [RFC8126]. 3938 9.6.5. Attack Status Codes Sub-Registry 3940 The document requests IANA to create a new sub-registry, entitled 3941 "DOTS Signal Channel Attack Status Codes". Codes in this registry 3942 are used as valid values of 'attack-status' parameter. 3944 The registry is initially populated with the following values: 3946 +------+-------------------------------+----------------+-----------+ 3947 | Code | Label | Description | Reference | 3948 +------+-------------------------------+----------------+-----------+ 3949 | 1 | under-attack | The DOTS | [RFCXXXX] | 3950 | | | client | | 3951 | | | determines | | 3952 | | | that it is | | 3953 | | | still under | | 3954 | | | attack. | | 3955 | 2 | attack-successfully-mitigated | The DOTS | [RFCXXXX] | 3956 | | | client | | 3957 | | | determines | | 3958 | | | that the | | 3959 | | | attack is | | 3960 | | | successfully | | 3961 | | | mitigated. | | 3962 +------+-------------------------------+----------------+-----------+ 3964 New codes can be assigned via Standards Action [RFC8126]. 3966 9.7. DOTS Signal Channel YANG Modules 3968 This document requests IANA to register the following URIs in the 3969 "ns" subregistry within the "IETF XML Registry" [RFC3688]: 3971 URI: urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel 3972 Registrant Contact: The IESG. 3973 XML: N/A; the requested URI is an XML namespace. 3975 URI: urn:ietf:params:xml:ns:yang:iana-dots-signal-channel 3976 Registrant Contact: IANA. 3977 XML: N/A; the requested URI is an XML namespace. 3979 This document requests IANA to register the following YANG modules in 3980 the "YANG Module Names" subregistry [RFC7950] within the "YANG 3981 Parameters" registry. 3983 name: ietf-signal 3984 namespace: urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel 3985 maintained by IANA: N 3986 prefix: signal 3987 reference: RFC XXXX 3989 name: iana-signal 3990 namespace: urn:ietf:params:xml:ns:yang:iana-dots-signal-channel 3991 maintained by IANA: Y 3992 prefix: iana-signal 3993 reference: RFC XXXX 3995 This document defines the initial version of the IANA-maintained 3996 iana-dots-signal-channel YANG module. IANA is requested to add this 3997 note: 3999 Status, conflict status, conflict cause, and attack status values 4000 must not be directly added to the iana-dots-signal-channel YANG 4001 module. They must instead be respectively added to the "DOTS 4002 Status Codes", "DOTS Conflict Status Codes", "DOTS Conflict Cause 4003 Codes", and "DOTS Attack Status Codes" registries. 4005 When a 'status', 'conflict-status', 'conflict-cause', or 'attack- 4006 status' value is respectively added to the "DOTS Status Codes", "DOTS 4007 Conflict Status Codes", "DOTS Conflict Cause Codes", or "DOTS Attack 4008 Status Codes" registry, a new "enum" statement must be added to the 4009 iana-dots-signal-channel YANG module. The following "enum" 4010 statement, and substatements thereof, should be defined: 4012 "enum": Replicates the label from the registry. 4014 "value": Contains the IANA-assigned value corresponding to the 4015 'status', 'conflict-status', 'conflict-cause', or 4016 'attack-status'. 4018 "description": Replicates the description from the registry. 4020 "reference": Replicates the reference from the registry and add the 4021 title of the document. 4023 When the iana-dots-signal-channel YANG module is updated, a new 4024 "revision" statement must be added in front of the existing revision 4025 statements. 4027 IANA is requested to add this note to "DOTS Status Codes", "DOTS 4028 Conflict Status Codes", "DOTS Conflict Cause Codes", and "DOTS Attack 4029 Status Codes" registries: 4031 When this registry is modified, the YANG module iana-dots-signal- 4032 channel must be updated as defined in [RFCXXXX]. 4034 10. Security Considerations 4036 High-level DOTS security considerations are documented in 4037 [I-D.ietf-dots-requirements] and [I-D.ietf-dots-architecture]. 4039 Authenticated encryption MUST be used for data confidentiality and 4040 message integrity. The interaction between the DOTS agents requires 4041 Datagram Transport Layer Security (DTLS) or Transport Layer Security 4042 (TLS) with a cipher suite offering confidentiality protection, and 4043 the guidance given in [RFC7525] MUST be followed to avoid attacks on 4044 (D)TLS. The (D)TLS protocol profile used for the DOTS signal channel 4045 is specified in Section 7. 4047 If TCP is used between DOTS agents, an attacker may be able to inject 4048 RST packets, bogus application segments, etc., regardless of whether 4049 TLS authentication is used. Because the application data is TLS 4050 protected, this will not result in the application receiving bogus 4051 data, but it will constitute a DoS on the connection. This attack 4052 can be countered by using TCP-AO [RFC5925]. If TCP-AO is used, then 4053 any bogus packets injected by an attacker will be rejected by the 4054 TCP-AO integrity check and therefore will never reach the TLS layer. 4056 An attack vector that can be achieved if the 'cuid' is guessable is a 4057 misbehaving DOTS client from within the client's domain which uses 4058 the 'cuid' of another DOTS client of the domain to delete or alter 4059 active mitigations. For this attack vector to happen, the 4060 misbehaving client needs to pass the security validation checks by 4061 the DOTS server, and eventually the checks of a client-domain DOTS 4062 gateway. 4064 A similar attack can be achieved by a compromised DOTS client which 4065 can sniff the TLS 1.2 handshake, use the client certificate to 4066 identify the 'cuid' used by another DOTS client. This attack is not 4067 possible with TLS 1.3 because most of the TLS handshake is encrypted 4068 and the client certificate is not visible to eavesdroppers. 4070 Rate-limiting DOTS requests, including those with new 'cuid' values, 4071 from the same DOTS client defends against DoS attacks that would 4072 result in varying the 'cuid' to exhaust DOTS server resources. Rate- 4073 limit policies SHOULD be enforced on DOTS gateways (if deployed) and 4074 DOTS servers. 4076 In order to prevent leaking internal information outside a client- 4077 domain, DOTS gateways located in the client-domain SHOULD NOT reveal 4078 the identification information that pertains to internal DOTS clients 4079 (e.g., source IP address, client's hostname) unless explicitly 4080 configured to do so. 4082 DOTS servers MUST verify that requesting DOTS clients are entitled to 4083 trigger actions on a given IP prefix. That is, only actions on IP 4084 resources that belong to the DOTS client' domain MUST be authorized 4085 by a DOTS server. The exact mechanism for the DOTS servers to 4086 validate that the target prefixes are within the scope of the DOTS 4087 client's domain is deployment-specific. 4089 The presence of DOTS gateways may lead to infinite forwarding loops, 4090 which is undesirable. To prevent and detect such loops, this 4091 document uses the Hop-Limit Option. 4093 CoAP-specific security considerations are discussed in Section 11 of 4094 [RFC7252], while CBOR-related security considerations are discussed 4095 in Section 8 of [RFC7049]. 4097 11. Contributors 4099 The following individuals have contributed to this document: 4101 o Jon Shallow, NCC Group, Email: jon.shallow@nccgroup.trust 4103 o Mike Geller, Cisco Systems, Inc. 3250 Florida 33309 USA, Email: 4104 mgeller@cisco.com 4106 o Robert Moskowitz, HTT Consulting Oak Park, MI 42837 United States, 4107 Email: rgm@htt-consult.com 4109 o Dan Wing, Email: dwing-ietf@fuggles.com 4111 12. Acknowledgements 4113 Thanks to Christian Jacquenet, Roland Dobbins, Roman D. Danyliw, 4114 Michael Richardson, Ehud Doron, Kaname Nishizuka, Dave Dolson, Liang 4115 Xia, Gilbert Clark, Xialiang Frank, Jim Schaad, Klaus Hartke and 4116 Nesredien Suleiman for the discussion and comments. 4118 Thanks to the core WG for the recommendations on Hop-Limit and 4119 redirect signaling. 4121 Special thanks to Benjamin Kaduk for the detailed AD review. 4123 13. References 4125 13.1. Normative References 4127 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4128 Requirement Levels", BCP 14, RFC 2119, 4129 DOI 10.17487/RFC2119, March 1997, 4130 . 4132 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 4133 DOI 10.17487/RFC3688, January 2004, 4134 . 4136 [RFC4279] Eronen, P., Ed. and H. Tschofenig, Ed., "Pre-Shared Key 4137 Ciphersuites for Transport Layer Security (TLS)", 4138 RFC 4279, DOI 10.17487/RFC4279, December 2005, 4139 . 4141 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 4142 (CIDR): The Internet Address Assignment and Aggregation 4143 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 4144 2006, . 4146 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 4147 (TLS) Protocol Version 1.2", RFC 5246, 4148 DOI 10.17487/RFC5246, August 2008, 4149 . 4151 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 4152 Housley, R., and W. Polk, "Internet X.509 Public Key 4153 Infrastructure Certificate and Certificate Revocation List 4154 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 4155 . 4157 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 4158 Uniform Resource Identifiers (URIs)", RFC 5785, 4159 DOI 10.17487/RFC5785, April 2010, 4160 . 4162 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 4163 Extensions: Extension Definitions", RFC 6066, 4164 DOI 10.17487/RFC6066, January 2011, 4165 . 4167 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 4168 Verification of Domain-Based Application Service Identity 4169 within Internet Public Key Infrastructure Using X.509 4170 (PKIX) Certificates in the Context of Transport Layer 4171 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 4172 2011, . 4174 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 4175 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 4176 January 2012, . 4178 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 4179 RFC 6991, DOI 10.17487/RFC6991, July 2013, 4180 . 4182 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 4183 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 4184 October 2013, . 4186 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 4187 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 4188 Transport Layer Security (TLS) and Datagram Transport 4189 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 4190 June 2014, . 4192 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 4193 Application Protocol (CoAP)", RFC 7252, 4194 DOI 10.17487/RFC7252, June 2014, 4195 . 4197 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 4198 "Recommendations for Secure Use of Transport Layer 4199 Security (TLS) and Datagram Transport Layer Security 4200 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 4201 2015, . 4203 [RFC7641] Hartke, K., "Observing Resources in the Constrained 4204 Application Protocol (CoAP)", RFC 7641, 4205 DOI 10.17487/RFC7641, September 2015, 4206 . 4208 [RFC7918] Langley, A., Modadugu, N., and B. Moeller, "Transport 4209 Layer Security (TLS) False Start", RFC 7918, 4210 DOI 10.17487/RFC7918, August 2016, 4211 . 4213 [RFC7924] Santesson, S. and H. Tschofenig, "Transport Layer Security 4214 (TLS) Cached Information Extension", RFC 7924, 4215 DOI 10.17487/RFC7924, July 2016, 4216 . 4218 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 4219 RFC 7950, DOI 10.17487/RFC7950, August 2016, 4220 . 4222 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 4223 RFC 7951, DOI 10.17487/RFC7951, August 2016, 4224 . 4226 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 4227 the Constrained Application Protocol (CoAP)", RFC 7959, 4228 DOI 10.17487/RFC7959, August 2016, 4229 . 4231 [RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 4232 Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, 4233 March 2017, . 4235 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 4236 Writing an IANA Considerations Section in RFCs", BCP 26, 4237 RFC 8126, DOI 10.17487/RFC8126, June 2017, 4238 . 4240 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 4241 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 4242 May 2017, . 4244 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 4245 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 4246 Application Protocol) over TCP, TLS, and WebSockets", 4247 RFC 8323, DOI 10.17487/RFC8323, February 2018, 4248 . 4250 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 4251 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 4252 . 4254 13.2. Informative References 4256 [I-D.boucadair-dots-earlydata] 4257 Boucadair, M. and R. K, "Using Early Data in DOTS", draft- 4258 boucadair-dots-earlydata-00 (work in progress), January 4259 2019. 4261 [I-D.boucadair-dots-server-discovery] 4262 Boucadair, M., K, R., and P. Patil, "Distributed-Denial- 4263 of-Service Open Threat Signaling (DOTS) Server Discovery", 4264 draft-boucadair-dots-server-discovery-05 (work in 4265 progress), October 2018. 4267 [I-D.ietf-core-comi] 4268 Veillette, M., Stok, P., Pelov, A., and A. Bierman, "CoAP 4269 Management Interface", draft-ietf-core-comi-04 (work in 4270 progress), November 2018. 4272 [I-D.ietf-core-hop-limit] 4273 Boucadair, M., K, R., and J. Shallow, "Constrained 4274 Application Protocol (CoAP) Hop Limit Option", draft-ietf- 4275 core-hop-limit-02 (work in progress), December 2018. 4277 [I-D.ietf-core-yang-cbor] 4278 Veillette, M., Pelov, A., Somaraju, A., Turner, R., and A. 4279 Minaburo, "CBOR Encoding of Data Modeled with YANG", 4280 draft-ietf-core-yang-cbor-07 (work in progress), September 4281 2018. 4283 [I-D.ietf-dots-architecture] 4284 Mortensen, A., Andreasen, F., K, R., Teague, N., Compton, 4285 R., and c. christopher_gray3@cable.comcast.com, 4286 "Distributed-Denial-of-Service Open Threat Signaling 4287 (DOTS) Architecture", draft-ietf-dots-architecture-10 4288 (work in progress), December 2018. 4290 [I-D.ietf-dots-data-channel] 4291 Boucadair, M., K, R., Nishizuka, K., Xia, L., Patil, P., 4292 Mortensen, A., and N. Teague, "Distributed Denial-of- 4293 Service Open Threat Signaling (DOTS) Data Channel 4294 Specification", draft-ietf-dots-data-channel-25 (work in 4295 progress), January 2019. 4297 [I-D.ietf-dots-requirements] 4298 Mortensen, A., Moskowitz, R., and R. K, "Distributed 4299 Denial of Service (DDoS) Open Threat Signaling 4300 Requirements", draft-ietf-dots-requirements-16 (work in 4301 progress), October 2018. 4303 [I-D.ietf-dots-use-cases] 4304 Dobbins, R., Migault, D., Fouant, S., Moskowitz, R., 4305 Teague, N., Xia, L., and K. Nishizuka, "Use cases for DDoS 4306 Open Threat Signaling", draft-ietf-dots-use-cases-17 (work 4307 in progress), January 2019. 4309 [I-D.ietf-tls-dtls13] 4310 Rescorla, E., Tschofenig, H., and N. Modadugu, "The 4311 Datagram Transport Layer Security (DTLS) Protocol Version 4312 1.3", draft-ietf-tls-dtls13-30 (work in progress), 4313 November 2018. 4315 [IANA.CBOR.Tags] 4316 IANA, "Concise Binary Object Representation (CBOR) Tags", 4317 . 4320 [IANA.CoAP.Content-Formats] 4321 IANA, "CoAP Content-Formats", 4322 . 4325 [IANA.MediaTypes] 4326 IANA, "Media Types", 4327 . 4329 [proto_numbers] 4330 "IANA, "Protocol Numbers"", 2011, 4331 . 4333 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 4334 DOI 10.17487/RFC0791, September 1981, 4335 . 4337 [RFC3022] Srisuresh, P. and K. Egevang, "Traditional IP Network 4338 Address Translator (Traditional NAT)", RFC 3022, 4339 DOI 10.17487/RFC3022, January 2001, 4340 . 4342 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 4343 Resource Identifier (URI): Generic Syntax", STD 66, 4344 RFC 3986, DOI 10.17487/RFC3986, January 2005, 4345 . 4347 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 4348 Unique IDentifier (UUID) URN Namespace", RFC 4122, 4349 DOI 10.17487/RFC4122, July 2005, 4350 . 4352 [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram 4353 Congestion Control Protocol (DCCP)", RFC 4340, 4354 DOI 10.17487/RFC4340, March 2006, 4355 . 4357 [RFC4732] Handley, M., Ed., Rescorla, E., Ed., and IAB, "Internet 4358 Denial-of-Service Considerations", RFC 4732, 4359 DOI 10.17487/RFC4732, December 2006, 4360 . 4362 [RFC4787] Audet, F., Ed. and C. Jennings, "Network Address 4363 Translation (NAT) Behavioral Requirements for Unicast 4364 UDP", BCP 127, RFC 4787, DOI 10.17487/RFC4787, January 4365 2007, . 4367 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 4368 RFC 4960, DOI 10.17487/RFC4960, September 2007, 4369 . 4371 [RFC4987] Eddy, W., "TCP SYN Flooding Attacks and Common 4372 Mitigations", RFC 4987, DOI 10.17487/RFC4987, August 2007, 4373 . 4375 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 4376 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 4377 DOI 10.17487/RFC5389, October 2008, 4378 . 4380 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 4381 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 4382 June 2010, . 4384 [RFC6052] Bao, C., Huitema, C., Bagnulo, M., Boucadair, M., and X. 4385 Li, "IPv6 Addressing of IPv4/IPv6 Translators", RFC 6052, 4386 DOI 10.17487/RFC6052, October 2010, 4387 . 4389 [RFC6146] Bagnulo, M., Matthews, P., and I. van Beijnum, "Stateful 4390 NAT64: Network Address and Protocol Translation from IPv6 4391 Clients to IPv4 Servers", RFC 6146, DOI 10.17487/RFC6146, 4392 April 2011, . 4394 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 4395 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 4396 DOI 10.17487/RFC6234, May 2011, 4397 . 4399 [RFC6296] Wasserman, M. and F. Baker, "IPv6-to-IPv6 Network Prefix 4400 Translation", RFC 6296, DOI 10.17487/RFC6296, June 2011, 4401 . 4403 [RFC6724] Thaler, D., Ed., Draves, R., Matsumoto, A., and T. Chown, 4404 "Default Address Selection for Internet Protocol Version 6 4405 (IPv6)", RFC 6724, DOI 10.17487/RFC6724, September 2012, 4406 . 4408 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 4409 Specifications and Registration Procedures", BCP 13, 4410 RFC 6838, DOI 10.17487/RFC6838, January 2013, 4411 . 4413 [RFC6887] Wing, D., Ed., Cheshire, S., Boucadair, M., Penno, R., and 4414 P. Selkirk, "Port Control Protocol (PCP)", RFC 6887, 4415 DOI 10.17487/RFC6887, April 2013, 4416 . 4418 [RFC6888] Perreault, S., Ed., Yamagata, I., Miyakawa, S., Nakagawa, 4419 A., and H. Ashida, "Common Requirements for Carrier-Grade 4420 NATs (CGNs)", BCP 127, RFC 6888, DOI 10.17487/RFC6888, 4421 April 2013, . 4423 [RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed., 4424 "Enrollment over Secure Transport", RFC 7030, 4425 DOI 10.17487/RFC7030, October 2013, 4426 . 4428 [RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 4429 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 4430 . 4432 [RFC7452] Tschofenig, H., Arkko, J., Thaler, D., and D. McPherson, 4433 "Architectural Considerations in Smart Object Networking", 4434 RFC 7452, DOI 10.17487/RFC7452, March 2015, 4435 . 4437 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 4438 NETCONF Protocol over Transport Layer Security (TLS) with 4439 Mutual X.509 Authentication", RFC 7589, 4440 DOI 10.17487/RFC7589, June 2015, 4441 . 4443 [RFC8305] Schinazi, D. and T. Pauly, "Happy Eyeballs Version 2: 4444 Better Connectivity Using Concurrency", RFC 8305, 4445 DOI 10.17487/RFC8305, December 2017, 4446 . 4448 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 4449 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 4450 . 4452 [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 4453 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 4454 January 2019, . 4456 Authors' Addresses 4458 Tirumaleswar Reddy (editor) 4459 McAfee, Inc. 4460 Embassy Golf Link Business Park 4461 Bangalore, Karnataka 560071 4462 India 4464 Email: kondtir@gmail.com 4465 Mohamed Boucadair (editor) 4466 Orange 4467 Rennes 35000 4468 France 4470 Email: mohamed.boucadair@orange.com 4472 Prashanth Patil 4473 Cisco Systems, Inc. 4475 Email: praspati@cisco.com 4477 Andrew Mortensen 4478 Arbor Networks, Inc. 4479 2727 S. State St 4480 Ann Arbor, MI 48104 4481 United States 4483 Email: andrew@moretension.com 4485 Nik Teague 4486 Verisign, Inc. 4487 United States 4489 Email: nteague@verisign.com