idnits 2.17.1 draft-ietf-dots-signal-channel-25.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFCXXXX]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 5, 2018) is 2060 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 3691, 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) == Outdated reference: A later version (-17) exists of draft-ietf-core-comi-03 == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-06 == Outdated reference: A later version (-18) exists of draft-ietf-dots-architecture-07 == Outdated reference: A later version (-31) exists of draft-ietf-dots-data-channel-19 == Outdated reference: A later version (-22) exists of draft-ietf-dots-requirements-15 == Outdated reference: A later version (-25) exists of draft-ietf-dots-use-cases-16 == Outdated reference: A later version (-43) exists of draft-ietf-tls-dtls13-28 -- Obsolete informational reference (is this intentional?): RFC 4960 (Obsoleted by RFC 9260) -- Obsolete informational reference (is this intentional?): RFC 5389 (Obsoleted by RFC 8489) Summary: 7 errors (**), 0 flaws (~~), 9 warnings (==), 3 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: March 9, 2019 Orange 6 P. Patil 7 Cisco 8 A. Mortensen 9 Arbor Networks, Inc. 10 N. Teague 11 Verisign, Inc. 12 September 5, 2018 14 Distributed Denial-of-Service Open Threat Signaling (DOTS) Signal 15 Channel Specification 16 draft-ietf-dots-signal-channel-25 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 TBD statements with the port number to be assigned to 44 DOTS Signal Channel Protocol. 46 Also, please update the "revision" date of the YANG module. 48 Status of This Memo 50 This Internet-Draft is submitted in full conformance with the 51 provisions of BCP 78 and BCP 79. 53 Internet-Drafts are working documents of the Internet Engineering 54 Task Force (IETF). Note that other groups may also distribute 55 working documents as Internet-Drafts. The list of current Internet- 56 Drafts is at https://datatracker.ietf.org/drafts/current/. 58 Internet-Drafts are draft documents valid for a maximum of six months 59 and may be updated, replaced, or obsoleted by other documents at any 60 time. It is inappropriate to use Internet-Drafts as reference 61 material or to cite them other than as "work in progress." 63 This Internet-Draft will expire on March 9, 2019. 65 Copyright Notice 67 Copyright (c) 2018 IETF Trust and the persons identified as the 68 document authors. All rights reserved. 70 This document is subject to BCP 78 and the IETF Trust's Legal 71 Provisions Relating to IETF Documents 72 (https://trustee.ietf.org/license-info) in effect on the date of 73 publication of this document. Please review these documents 74 carefully, as they describe your rights and restrictions with respect 75 to this document. Code Components extracted from this document must 76 include Simplified BSD License text as described in Section 4.e of 77 the Trust Legal Provisions and are provided without warranty as 78 described in the Simplified BSD License. 80 Table of Contents 82 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 83 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 84 3. Design Overview . . . . . . . . . . . . . . . . . . . . . . . 6 85 4. DOTS Signal Channel: Messages & Behaviors . . . . . . . . . . 8 86 4.1. DOTS Server(s) Discovery . . . . . . . . . . . . . . . . 8 87 4.2. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . 9 88 4.3. Happy Eyeballs for DOTS Signal Channel . . . . . . . . . 9 89 4.4. DOTS Mitigation Methods . . . . . . . . . . . . . . . . . 11 90 4.4.1. Request Mitigation . . . . . . . . . . . . . . . . . 11 91 4.4.2. Retrieve Information Related to a Mitigation . . . . 26 92 4.4.2.1. DOTS Servers Sending Mitigation Status . . . . . 30 93 4.4.2.2. DOTS Clients Polling for Mitigation Status . . . 33 94 4.4.3. Efficacy Update from DOTS Clients . . . . . . . . . . 34 95 4.4.4. Withdraw a Mitigation . . . . . . . . . . . . . . . . 36 97 4.5. DOTS Signal Channel Session Configuration . . . . . . . . 37 98 4.5.1. Discover Configuration Parameters . . . . . . . . . . 39 99 4.5.2. Convey DOTS Signal Channel Session Configuration . . 43 100 4.5.3. Configuration Freshness and Notifications . . . . . . 48 101 4.5.4. Delete DOTS Signal Channel Session Configuration . . 49 102 4.6. Redirected Signaling . . . . . . . . . . . . . . . . . . 50 103 4.7. Heartbeat Mechanism . . . . . . . . . . . . . . . . . . . 52 104 5. DOTS Signal Channel YANG Module . . . . . . . . . . . . . . . 53 105 5.1. Tree Structure . . . . . . . . . . . . . . . . . . . . . 53 106 5.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 55 107 6. Mapping Parameters to CBOR . . . . . . . . . . . . . . . . . 69 108 7. (D)TLS Protocol Profile and Performance Considerations . . . 71 109 7.1. (D)TLS Protocol Profile . . . . . . . . . . . . . . . . . 71 110 7.2. (D)TLS 1.3 Considerations . . . . . . . . . . . . . . . . 72 111 7.3. MTU and Fragmentation . . . . . . . . . . . . . . . . . . 73 112 8. Mutual Authentication of DOTS Agents & Authorization of DOTS 113 Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 114 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 76 115 9.1. DOTS Signal Channel UDP and TCP Port Number . . . . . . . 76 116 9.2. Well-Known 'dots' URI . . . . . . . . . . . . . . . . . . 76 117 9.3. DOTS Signal Channel CBOR Mappings Registry . . . . . . . 76 118 9.3.1. Registration Template . . . . . . . . . . . . . . . . 77 119 9.3.2. Initial Registry Content . . . . . . . . . . . . . . 78 120 9.4. Media Type Registration . . . . . . . . . . . . . . . . . 79 121 9.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 79 122 9.5. CoAP Content-Formats Registration . . . . . . . . . . . . 80 123 9.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 80 124 9.6. CBOR Tag registration . . . . . . . . . . . . . . . . . . 80 125 9.6.1. Registry Contents . . . . . . . . . . . . . . . . . . 80 126 9.7. DOTS Signal Channel YANG Module . . . . . . . . . . . . . 81 127 10. Security Considerations . . . . . . . . . . . . . . . . . . . 81 128 11. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 82 129 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 82 130 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 82 131 13.1. Normative References . . . . . . . . . . . . . . . . . . 82 132 13.2. Informative References . . . . . . . . . . . . . . . . . 85 133 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 89 135 1. Introduction 137 A distributed denial-of-service (DDoS) attack is an attempt to make 138 machines or network resources unavailable to their intended users. 139 In most cases, sufficient scale can be achieved by compromising 140 enough end-hosts and using those infected hosts to perpetrate and 141 amplify the attack. The victim in this attack can be an application 142 server, a host, a router, a firewall, or an entire network. 144 Network applications have finite resources like CPU cycles, the 145 number of processes or threads they can create and use, the maximum 146 number of simultaneous connections it can handle, the limited 147 resources of the control plane, etc. When processing network 148 traffic, such applications are supposed to use these resources to 149 offer the intended task in the most efficient manner. However, a 150 DDoS attacker may be able to prevent an application from performing 151 its intended task by making the application exhaust its finite 152 resources. 154 TCP DDoS SYN-flood, for example, is a memory-exhausting attack while 155 ACK-flood is a CPU-exhausting attack [RFC4987]. Attacks on the link 156 are carried out by sending enough traffic so that the link becomes 157 congested, thereby likely causing packet loss for legitimate traffic. 158 Stateful firewalls can also be attacked by sending traffic that 159 causes the firewall to maintain an excessive number of states that 160 may jeopardize the firewall's operation overall, besides likely 161 performance impacts. The firewall then runs out of memory, and can 162 no longer instantiate the states required to process legitimate 163 flows. Other possible DDoS attacks are discussed in [RFC4732]. 165 In many cases, it may not be possible for network administrators to 166 determine the cause(s) of an attack. They may instead just realize 167 that certain resources seem to be under attack. This document 168 defines a lightweight protocol that allows a DOTS client to request 169 mitigation from one or more DOTS servers for protection against 170 detected, suspected, or anticipated attacks. This protocol enables 171 cooperation between DOTS agents to permit a highly-automated network 172 defense that is robust, reliable, and secure. 174 An example of a network diagram that illustrates a deployment of DOTS 175 agents is shown in Figure 1. In this example, a DOTS server is 176 operating on the access network. A DOTS client is located on the LAN 177 (Local Area Network), while a DOTS gateway is embedded in the CPE 178 (Customer Premises Equipment). 180 Network 181 Resource CPE router Access network __________ 182 +-----------+ +--------------+ +-------------+ / \ 183 | |___| |____| |___ | Internet | 184 |DOTS client| | DOTS gateway | | DOTS server | | | 185 | | | | | | | | 186 +-----------+ +--------------+ +-------------+ \__________/ 188 Figure 1: Sample DOTS Deployment (1) 190 DOTS servers can also be reachable over the Internet, as depicted in 191 Figure 2. 193 Network DDoS mitigation 194 Resource CPE router __________ service 195 +-----------+ +-------------+ / \ +-------------+ 196 | |___| |____| |___ | | 197 |DOTS client| |DOTS gateway | | Internet | | DOTS server | 198 | | | | | | | | 199 +-----------+ +-------------+ \__________/ +-------------+ 201 Figure 2: Sample DOTS Deployment (2) 203 In typical deployments, the DOTS client belongs to a different 204 administrative domain than the DOTS server. For example, the DOTS 205 client is embedded in a firewall protecting services owned and 206 operated by a customer, while the DOTS server is owned and operated 207 by a different administrative entity (service provider, typically) 208 providing DDoS mitigation services. The latter might or might not 209 provide connectivity services to the network hosting the DOTS client. 211 The DOTS server may (not) be co-located with the DOTS mitigator. In 212 typical deployments, the DOTS server belongs to the same 213 administrative domain as the mitigator. The DOTS client can 214 communicate directly with a DOTS server or indirectly via a DOTS 215 gateway. 217 The document adheres to the DOTS architecture 218 [I-D.ietf-dots-architecture]. The requirements for DOTS signal 219 channel protocol are documented in [I-D.ietf-dots-requirements]. 220 This document satisfies all the use cases discussed in 221 [I-D.ietf-dots-use-cases]. 223 This document focuses on the DOTS signal channel. This is a 224 companion document of the DOTS data channel specification 225 [I-D.ietf-dots-data-channel] that defines a configuration and a bulk 226 data exchange mechanism supporting the DOTS signal channel. 228 2. Terminology 230 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 231 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 232 "OPTIONAL" in this document are to be interpreted as described in 233 [RFC2119]. 235 (D)TLS is used for statements that apply to both Transport Layer 236 Security [RFC5246][RFC8446] and Datagram Transport Layer Security 237 [RFC6347]. Specific terms are used for any statement that applies to 238 either protocol alone. 240 The reader should be familiar with the terms defined in 241 [I-D.ietf-dots-requirements]. 243 The meaning of the symbols in YANG tree diagrams is defined in 244 [RFC8340]. 246 3. Design Overview 248 The DOTS signal channel is built on top of the Constrained 249 Application Protocol (CoAP) [RFC7252], a lightweight protocol 250 originally designed for constrained devices and networks. The many 251 features of CoAP (expectation of packet loss, support for 252 asynchronous Non-confirmable messaging, congestion control, small 253 message overhead limiting the need for fragmentation, use of minimal 254 resources, and support for (D)TLS) makes it a good candidate to build 255 the DOTS signaling mechanism from. 257 The DOTS signal channel is layered on existing standards (Figure 3). 259 +---------------------+ 260 | DOTS Signal Channel | 261 +---------------------+ 262 | CoAP | 263 +----------+----------+ 264 | TLS | DTLS | 265 +----------+----------+ 266 | TCP | UDP | 267 +----------+----------+ 268 | IP | 269 +---------------------+ 271 Figure 3: Abstract Layering of DOTS Signal Channel over CoAP over 272 (D)TLS 274 By default, a DOTS signal channel MUST run over port number TBD as 275 defined in Section 9.1, for both UDP and TCP, unless the DOTS server 276 has a mutual agreement with its DOTS clients to use a different port 277 number. DOTS clients MAY alternatively support means to dynamically 278 discover the ports used by their DOTS servers. In order to use a 279 distinct port number (as opposed to TBD), DOTS clients and servers 280 SHOULD support a configurable parameter to supply the port number to 281 use. The rationale for not using the default port number 5684 282 ((D)TLS CoAP) is to allow for differentiated behaviors in 283 environments where both a DOTS gateway and an IoT gateway (e.g., 284 Figure 3 of [RFC7452]) are present. 286 The signal channel uses the "coaps" URI scheme defined in Section 6 287 of [RFC7252] and "coaps+tcp" URI scheme defined in Section 8.2 of 289 [RFC8323] to identify DOTS server resources accessible using CoAP 290 over UDP secured with DTLS and CoAP over TCP secured with TLS. 292 The signal channel is initiated by the DOTS client (Section 4.4). 293 Once the signal channel is established, the DOTS agents periodically 294 send heartbeats to keep the channel active (Section 4.7). At any 295 time, the DOTS client may send a mitigation request message to a DOTS 296 server over the active channel. While mitigation is active because 297 of the higher likelihood of packet loss during a DDoS attack, the 298 DOTS server periodically sends status messages to the client, 299 including basic mitigation feedback details. Mitigation remains 300 active until the DOTS client explicitly terminates mitigation, or the 301 mitigation lifetime expires. 303 DOTS signaling can happen with DTLS over UDP and TLS over TCP. 304 Likewise, DOTS requests may be sent using IPv4 or IPv6 transfer 305 capabilities. A Happy Eyeballs procedure for DOTS signal channel is 306 specified in Section 4.3. 308 Messages exchanged between DOTS agents are serialized using Concise 309 Binary Object Representation (CBOR) [RFC7049], a binary encoding 310 scheme designed for small code and message size. CBOR-encoded 311 payloads are used to carry signal channel-specific payload messages 312 which convey request parameters and response information such as 313 errors. In order to allow the use of the same data models, [RFC7951] 314 specifies the JavaScript Object Notation (JSON) encoding of YANG- 315 modeled data. A similar effort for CBOR is defined in 316 [I-D.ietf-core-yang-cbor]. 318 DOTS agents determine the CBOR data structure is a DOTS signal 319 channel object from the application context, such as from the port 320 number assigned to the DOTS signal channel. The other method DOTS 321 agents use to indicate that a CBOR data structure is a DOTS signal 322 channel object is the use of the "application/dots+cbor" content type 323 (Section 9.4). 325 From that standpoint, this document specifies a YANG module for 326 representing DOTS mitigation scopes, DOTS signal channel session 327 configuration data, and DOTS redirected signalling (Section 5). 328 Representing these data as CBOR data is assumed to follow the rules 329 in [I-D.ietf-core-yang-cbor] or those in [RFC7951] combined with 330 JSON/CBOR conversion rules in [RFC7049]. All parameters in the 331 payload of the DOTS signal channel are mapped to CBOR types as 332 specified in Section 6. 334 In order to prevent fragmentation, DOTS agents must follow the 335 recommendations documented in Section 4.6 of [RFC7252]. Refer to 336 Section 7.3 for more details. 338 DOTS agents MUST support GET, PUT, and DELETE CoAP methods. The 339 payload included in CoAP responses with 2.xx Response Codes MUST be 340 of content type "application/dots+cbor". CoAP responses with 4.xx 341 and 5.xx error Response Codes MUST include a diagnostic payload 342 (Section 5.5.2 of [RFC7252]). The Diagnostic Payload may contain 343 additional information to aid troubleshooting. 345 In deployments where multiple DOTS clients are enabled in a network 346 (owned and operated by the same entity), the DOTS server may detect 347 conflicting mitigation requests from these clients. This document 348 does not aim to specify a comprehensive list of conditions under 349 which a DOTS server will characterize two mitigation requests from 350 distinct DOTS clients as conflicting, nor recommend a DOTS server 351 behavior for processing conflicting mitigation requests. Those 352 considerations are implementation- and deployment-specific. 353 Nevertheless, the document specifies the mechanisms to notify DOTS 354 clients when conflicts occur, including the conflict cause 355 (Section 4.4). 357 In deployments where one or more translators (e.g., Traditional NAT 358 [RFC3022], CGN [RFC6888], NAT64 [RFC6146], NPTv6 [RFC6296]) are 359 enabled between the client's network and the DOTS server, DOTS signal 360 channel messages forwarded to a DOTS server MUST NOT include internal 361 IP addresses/prefixes and/or port numbers; external addresses/ 362 prefixes and/or port numbers as assigned by the translator MUST be 363 used instead. This document does not make any recommendation about 364 possible translator discovery mechanisms. The following are some 365 (non-exhaustive) deployment examples that may be considered: 367 o Port Control Protocol (PCP) [RFC6887] or Session Traversal 368 Utilities for NAT (STUN) [RFC5389] may be used to retrieve the 369 external addresses/prefixes and/or port numbers. Information 370 retrieved by means of PCP or STUN will be used to feed the DOTS 371 signal channel messages that will be sent to a DOTS server. 373 o A DOTS gateway may be co-located with the translator. The DOTS 374 gateway will need to update the DOTS messages, based upon the 375 local translator's binding table. 377 4. DOTS Signal Channel: Messages & Behaviors 379 4.1. DOTS Server(s) Discovery 381 This document assumes that DOTS clients are provisioned with the 382 reachability information of their DOTS server(s) using a variety of 383 means (e.g., local configuration, or dynamic means such as DHCP). 384 The description of such means is out of scope of this document. 386 Likewise, it is out of scope of this document to specify the behavior 387 to be followed by a DOTS client to send DOTS requests when multiple 388 DOTS servers are provisioned (e.g., contact all DOTS servers, select 389 one DOTS server among the list). 391 4.2. CoAP URIs 393 The DOTS server MUST support the use of the path-prefix of "/.well- 394 known/" as defined in [RFC5785] and the registered name of "dots". 395 Each DOTS operation is indicated by a path-suffix that indicates the 396 intended operation. The operation path (Table 1) is appended to the 397 path-prefix to form the URI used with a CoAP request to perform the 398 desired DOTS operation. 400 +-----------------------+----------------+-------------+ 401 | Operation | Operation Path | Details | 402 +-----------------------+----------------+-------------+ 403 | Mitigation | /v1.0/mitigate | Section 4.4 | 404 +-----------------------+----------------+-------------+ 405 | Session configuration | /v1.0/config | Section 4.5 | 406 +-----------------------+----------------+-------------+ 408 Table 1: Operations and their Corresponding URIs 410 4.3. Happy Eyeballs for DOTS Signal Channel 412 [I-D.ietf-dots-requirements] mentions that DOTS agents will have to 413 support both connectionless and connection-oriented protocols. As 414 such, the DOTS signal channel is designed to operate with DTLS over 415 UDP and TLS over TCP. Further, a DOTS client may acquire a list of 416 IPv4 and IPv6 addresses (Section 4.1), each of which can be used to 417 contact the DOTS server using UDP and TCP. The following specifies 418 the procedure to follow to select the address family and the 419 transport protocol for sending DOTS signal channel messages. 421 Such procedure is needed to avoid experiencing long connection 422 delays. For example, if an IPv4 path to reach a DOTS server is 423 found, but the DOTS server's IPv6 path is not working, a dual-stack 424 DOTS client may experience a significant connection delay compared to 425 an IPv4-only DOTS client. The other problem is that if a middlebox 426 between the DOTS client and DOTS server is configured to block UDP 427 traffic, the DOTS client will fail to establish a DTLS session with 428 the DOTS server and, as a consequence, will have to fall back to TLS 429 over TCP, thereby incurring significant connection delays. 431 To overcome these connection setup problems, the DOTS client attempts 432 to connect to its DOTS server(s) using both IPv6 and IPv4, and tries 433 both DTLS over UDP and TLS over TCP in a manner similar to the Happy 434 Eyeballs mechanism [RFC8305]. These connection attempts are 435 performed by the DOTS client when it initializes. The results of the 436 Happy Eyeballs procedure are used by the DOTS client for sending its 437 subsequent messages to the DOTS server. 439 The order of preference of the DOTS signal channel address family and 440 transport protocol (most preferred first) is: UDP over IPv6, UDP over 441 IPv4, TCP over IPv6, and finally TCP over IPv4. This order adheres 442 to the address preference order specified in [RFC6724] and the DOTS 443 signal channel preference which privileges the use of UDP over TCP 444 (to avoid TCP's head of line blocking). 446 In reference to Figure 4, the DOTS client sends two TCP SYNs and two 447 DTLS ClientHello messages at the same time over IPv6 and IPv4. In 448 this example, it is assumed that the IPv6 path is broken and UDP 449 traffic is dropped by a middlebox but has little impact to the DOTS 450 client because there is no long delay before using IPv4 and TCP. The 451 DOTS client repeats the mechanism to discover whether DOTS signal 452 channel messages with DTLS over UDP becomes available from the DOTS 453 server, so the DOTS client can migrate the DOTS signal channel from 454 TCP to UDP. Such probing SHOULD NOT be done more frequently than 455 every 24 hours and MUST NOT be done more frequently than every 5 456 minutes. 458 A single DOTS signal channel between DOTS agents can be used to 459 exchange multiple DOTS signal messages. To reduce DOTS client and 460 DOTS server workload, DOTS clients SHOULD re-use the (D)TLS session. 462 +-----------+ +-----------+ 463 |DOTS client| |DOTS server| 464 +-----------+ +-----------+ 465 | | 466 |--DTLS ClientHello, IPv6 ---->X | 467 |--TCP SYN, IPv6-------------->X | 468 |--DTLS ClientHello, IPv4 ---->X | 469 |--TCP SYN, IPv4--------------------------------------->| 470 |--DTLS ClientHello, IPv6 ---->X | 471 |--TCP SYN, IPv6-------------->X | 472 |<-TCP SYNACK-------------------------------------------| 473 |--DTLS ClientHello, IPv4 ---->X | 474 |--TCP ACK--------------------------------------------->| 475 |<------------Establish TLS Session-------------------->| 476 |----------------DOTS signal--------------------------->| 477 | | 479 Figure 4: DOTS Happy Eyeballs 481 4.4. DOTS Mitigation Methods 483 The following methods are used by a DOTS client to request, withdraw, 484 or retrieve the status of mitigation requests: 486 PUT: DOTS clients use the PUT method to request mitigation from a 487 DOTS server (Section 4.4.1). During active mitigation, DOTS 488 clients may use PUT requests to carry mitigation efficacy 489 updates to the DOTS server (Section 4.4.3). 491 GET: DOTS clients may use the GET method to subscribe to DOTS 492 server status messages, or to retrieve the list of its 493 mitigations maintained by a DOTS server (Section 4.4.2). 495 DELETE: DOTS clients use the DELETE method to withdraw a request for 496 mitigation from a DOTS server (Section 4.4.4). 498 Mitigation request and response messages are marked as Non- 499 confirmable messages (Section 2.2 of [RFC7252]). 501 DOTS agents SHOULD follow the data transmission guidelines discussed 502 in Section 3.1.3 of [RFC8085] and control transmission behavior by 503 not sending more than one UDP datagram per round-trip time (RTT) to 504 the peer DOTS agent on average. 506 Requests marked by the DOTS client as Non-confirmable messages are 507 sent at regular intervals until a response is received from the DOTS 508 server. If the DOTS client cannot maintain an RTT estimate, it 509 SHOULD NOT send more than one Non-confirmable request every 3 510 seconds, and SHOULD use an even less aggressive rate whenever 511 possible (case 2 in Section 3.1.3 of [RFC8085]). 513 4.4.1. Request Mitigation 515 When a DOTS client requires mitigation for some reason, the DOTS 516 client uses the CoAP PUT method to send a mitigation request to its 517 DOTS server(s) (Figure 5, illustrated in JSON diagnostic notation). 519 If a DOTS client is entitled to solicit the DOTS service, the DOTS 520 server can enable mitigation on behalf of the DOTS client by 521 communicating the DOTS client's request to a mitigator and relaying 522 the feedback of the thus-selected mitigator to the requesting DOTS 523 client. 525 Header: PUT (Code=0.03) 526 Uri-Path: ".well-known" 527 Uri-Path: "dots" 528 Uri-Path: "v1.0" 529 Uri-Path: "mitigate" 530 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 531 Uri-Path: "mid=123" 532 Content-Type: "application/dots+cbor" 533 { 534 "ietf-dots-signal-channel:mitigation-scope": { 535 "scope": [ 536 { 537 "target-prefix": [ 538 "string" 539 ], 540 "target-port-range": [ 541 { 542 "lower-port": integer, 543 "upper-port": integer 544 } 545 ], 546 "target-protocol": [ 547 integer 548 ], 549 "target-fqdn": [ 550 "string" 551 ], 552 "target-uri": [ 553 "string" 554 ], 555 "alias-name": [ 556 "string" 557 ], 558 "lifetime": integer, 559 "trigger-mitigation": boolean 560 } 561 ] 562 } 563 } 565 Figure 5: PUT to Convey DOTS Mitigation Requests 567 The Uri-Path option carries a major and minor version nomenclature to 568 manage versioning; DOTS signal channel in this specification uses 569 'v1' major version and '0' minor version. 571 The order of the Uri-Path options is important as it defines the CoAP 572 resource. In particular, 'mid' MUST follow 'cuid'. 574 The additional Uri-Path parameters to those defined in Section 4.2 575 are as follows: 577 cuid: Stands for Client Unique Identifier. A globally unique 578 identifier that is meant to prevent collisions among DOTS clients, 579 especially those from the same domain. It MUST be generated by 580 DOTS clients. 582 Implementations SHOULD use the output of a cryptographic hash 583 algorithm whose input is the Distinguished Encoding Rules (DER)- 584 encoded Abstract Syntax Notation One (ASN.1) representation of the 585 Subject Public Key Info (SPKI) of the DOTS client X.509 586 certificate [RFC5280], the DOTS client raw public key [RFC7250], 587 or the "Pre-Shared Key (PSK) identity" used by the DOTS client in 588 the TLS ClientKeyExchange message to set 'cuid'. In this version 589 of the specification, the cryptographic hash algorithm used is 590 SHA-256 [RFC6234]. The output of the cryptographic hash algorithm 591 is truncated to 16 bytes; truncation is done by stripping off the 592 final 16 bytes. The truncated output is base64url encoded. 594 The 'cuid' is intended to be stable when communicating with a 595 given DOTS server, i.e., the 'cuid' used by a DOTS client SHOULD 596 NOT change over time. Distinct 'cuid' values MAY be used per DOTS 597 server. 599 DOTS servers MUST return 4.09 (Conflict) error code to a DOTS peer 600 to notify that the 'cuid' is already in-use by another DOTS 601 client. Upon receipt of that error code, a new 'cuid' MUST be 602 generated by the DOTS peer. 604 Client-domain DOTS gateways MUST handle 'cuid' collision directly 605 and it is RECOMMENDED that 'cuid' collision is handled directly by 606 server-domain DOTS gateways. 608 DOTS gateways MAY rewrite the 'cuid' used by peer DOTS clients. 609 Triggers for such rewriting are out of scope. 611 This is a mandatory Uri-Path parameter. 613 mid: Identifier for the mitigation request represented with an 614 integer. This identifier MUST be unique for each mitigation 615 request bound to the DOTS client, i.e., the 'mid' parameter value 616 in the mitigation request needs to be unique relative to the 'mid' 617 parameter values of active mitigation requests conveyed from the 618 DOTS client to the DOTS server. 620 In order to handle out-of-order delivery of mitigation requests, 621 'mid' values MUST increase monotonically. 623 If the 'mid' value has reached 3/4 of (2**32 - 1) (i.e., 624 3221225471) and it is peace-time, the DOTS client MUST reset 'mid' 625 to 0 to handle 'mid' rollover. If the DOTS client maintains 626 mitigation requests with pre-configured scopes, it MUST re-create 627 them with the 'mid' restarting at 0. 629 This identifier MUST be generated by the DOTS client. 631 This is a mandatory Uri-Path parameter. 633 'cuid' and 'mid' MUST NOT appear in the PUT request message body. 635 The parameters in the CBOR body of the PUT request are described 636 below: 638 target-prefix: A list of prefixes identifying resources under 639 attack. Prefixes are represented using Classless Inter-Domain 640 Routing (CIDR) notation [RFC4632]. 641 As a reminder, the prefix length must be less than or equal to 32 642 (resp. 128) for IPv4 (resp. IPv6). 644 The prefix list MUST NOT include broadcast, loopback, or multicast 645 addresses. These addresses are considered as invalid values. In 646 addition, the DOTS server MUST validate that target prefixes are 647 within the scope of the DOTS client's domain. Other validation 648 checks may be supported by DOTS servers. 650 This is an optional attribute. 652 target-port-range: A list of port numbers bound to resources under 653 attack. 655 A port range is defined by two bounds, a lower port number (lower- 656 port) and an upper port number (upper-port). When only 'lower- 657 port' is present, it represents a single port number. 659 For TCP, UDP, Stream Control Transmission Protocol (SCTP) 660 [RFC4960], or Datagram Congestion Control Protocol (DCCP) 661 [RFC4340], a range of ports can be, for example, 0-1023, 662 1024-65535, or 1024-49151. 664 This is an optional attribute. 666 target-protocol: A list of protocols involved in an attack. Values 667 are taken from the IANA protocol registry [proto_numbers]. 669 The value '0' has a special meaning for 'all protocols'. 671 This is an optional attribute. 673 target-fqdn: A list of Fully Qualified Domain Names (FQDNs) 674 identifying resources under attack. An FQDN is the full name of a 675 resource, rather than just its hostname. For example, "venera" is 676 a hostname, and "venera.isi.edu" is an FQDN [RFC1983]. 678 How a name is passed to an underlying name resolution library is 679 implementation- and deployment-specific. Nevertheless, once the 680 name is resolved into one or multiple IP addresses, DOTS servers 681 MUST apply the same validation checks as those for 'target- 682 prefix'. 684 This is an optional attribute. 686 target-uri: A list of Uniform Resource Identifiers (URIs) [RFC3986] 687 identifying resources under attack. 689 The same validation checks used for 'target-fqdn' MUST be followed 690 by DOTS servers to validate a target URI. 692 This is an optional attribute. 694 alias-name: A list of aliases of resources for which the mitigation 695 is requested. Aliases can be created using the DOTS data channel 696 (Section 6.1 of [I-D.ietf-dots-data-channel]), direct 697 configuration, or other means. 699 An alias is used in subsequent signal channel exchanges to refer 700 more efficiently to the resources under attack. 702 This is an optional attribute. 704 lifetime: Lifetime of the mitigation request in seconds. The 705 RECOMMENDED lifetime of a mitigation request is 3600 seconds -- 706 this value was chosen to be long enough so that refreshing is not 707 typically a burden on the DOTS client, while expiring the request 708 where the client has unexpectedly quit in a timely manner. DOTS 709 clients MUST include this parameter in their mitigation requests. 710 Upon the expiry of this lifetime, and if the request is not 711 refreshed, the mitigation request is removed. The request can be 712 refreshed by sending the same request again. 714 A lifetime of '0' in a mitigation request is an invalid value. 716 A lifetime of negative one (-1) indicates indefinite lifetime for 717 the mitigation request. The DOTS server MAY refuse indefinite 718 lifetime, for policy reasons; the granted lifetime value is 719 returned in the response. DOTS clients MUST be prepared to not be 720 granted mitigations with indefinite lifetimes. 722 The DOTS server MUST always indicate the actual lifetime in the 723 response and the remaining lifetime in status messages sent to the 724 DOTS client. 726 This is a mandatory attribute. 728 trigger-mitigation: If the parameter value is set to 'false', DDoS 729 mitigation will not be triggered for the mitigation request unless 730 the DOTS signal channel session is lost. 732 If the DOTS client ceases to respond to heartbeat messages, the 733 DOTS server can detect that the DOTS session is lost. 735 The default value of the parameter is 'true' (that is, the 736 mitigation starts immediately). If 'trigger-mitigation' is not 737 present in a request, this is equivalent to receiving a request 738 with 'trigger-mitigation' set to 'true'. 740 This is an optional attribute. 742 In deployments where server-domain DOTS gateways are enabled, 743 identity information about the origin source client domain SHOULD be 744 supplied to the DOTS server. That information is meant to assist the 745 DOTS server to enforce some policies such as correlating DOTS clients 746 that belong to the same DOTS domain, limiting the number of DOTS 747 requests, and identifying the mitigation scope. These policies can 748 be enforced per-client, per-client domain, or both. Also, the 749 identity information may be used for auditing and debugging purposes. 751 Figure 6 shows an example of a request relayed by a server-domain 752 DOTS gateway. 754 Header: PUT (Code=0.03) 755 Uri-Path: ".well-known" 756 Uri-Path: "dots" 757 Uri-Path: "v1.0" 758 Uri-Path: "mitigate" 759 Uri-Path: "cdid=7eeaf349529eb55ed50113" 760 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 761 Uri-Path: "mid=123" 762 Content-Type: "application/dots+cbor" 763 { 764 "ietf-dots-signal-channel:mitigation-scope": { 765 "scope": [ 766 { 767 "target-prefix": [ 768 "string" 769 ], 770 "target-port-range": [ 771 { 772 "lower-port": integer, 773 "upper-port": integer 774 } 775 ], 776 "target-protocol": [ 777 integer 778 ], 779 "target-fqdn": [ 780 "string" 781 ], 782 "target-uri": [ 783 "string" 784 ], 785 "alias-name": [ 786 "string" 787 ], 788 "lifetime": integer 789 } 790 ] 791 } 792 } 794 Figure 6: PUT to Convey DOTS Mitigation Request as relayed by a 795 Server-Domain DOTS Gateway 797 A server-domain DOTS gateway SHOULD add the following Uri-Path 798 parameter: 800 cdid: Stands for Client Domain Identifier. The 'cdid' is conveyed 801 by a server-domain DOTS gateway to propagate the source domain 802 identity from the gateway's client-facing-side to the gateway's 803 server-facing-side, and from the gateway's server-facing-side to 804 the DOTS server. 'cdid' may be used by the final DOTS server for 805 policy enforcement purposes (e.g., enforce a quota on filtering 806 rules). These policies are deployment-specific. 808 Server-domain DOTS gateways SHOULD support a configuration option 809 to instruct whether 'cdid' parameter is to be inserted. 811 In order to accommodate deployments that require enforcing per- 812 client policies, per-client domain policies, or a combination 813 thereof, server-domain DOTS gateways MUST supply the SPKI hash of 814 the DOTS client X.509 certificate, the DOTS client raw public key, 815 or the hash of the "PSK identity" in the 'cdid', following the 816 same rules for generating the hash conveyed in 'cuid', which is 817 then used by the ultimate DOTS server to determine the 818 corresponding client's domain. The 'cdid' generated by a server- 819 domain gateway is likely to be the same as the 'cuid' except if 820 the DOTS message was relayed by a DOTS gateway or was generated 821 from a rogue DOTS client. 823 If a DOTS client is provisioned, for example, with distinct 824 certificates as a function of the peer server-domain DOTS gateway, 825 distinct 'cdid' values may be supplied by a server-domain DOTS 826 gateway. The ultimate DOTS server MUST treat those 'cdid' values 827 as equivalent. 829 The 'cdid' attribute MUST NOT be generated and included by DOTS 830 clients. 832 DOTS servers MUST ignore 'cdid' attributes that are directly 833 supplied by source DOTS clients or client-domain DOTS gateways. 834 This implies that first server-domain DOTS gateways MUST strip 835 'cdid' attributes supplied by DOTS clients. DOTS servers SHOULD 836 support a configuration parameter to identify DOTS gateways that 837 are trusted to supply 'cdid' attributes. 839 Only single-valued 'cdid' are defined in this document. 841 This is an optional Uri-Path. When present, 'cdid' MUST be 842 positioned before 'cuid'. 844 A DOTS gateway MAY add the CoAP Hop-Limit Option 845 [I-D.boucadair-core-hop-limit]. 847 Because of the complexity to handle partial failure cases, this 848 specification does not allow for including multiple mitigation 849 requests in the same PUT request. Concretely, a DOTS client MUST NOT 850 include multiple 'scope' parameters in the same PUT request. 852 FQDN and URI mitigation scopes may be thought of as a form of scope 853 alias, in which the addresses associated with the domain name or URI 854 represent the full scope of the mitigation. 856 In the PUT request at least one of the attributes 'target-prefix', 857 'target-fqdn','target-uri', or 'alias-name' MUST be present. 859 Attributes and Uri-Path parameters with empty values MUST NOT be 860 present in a request. 862 Figure 7 shows a PUT request example to signal that ports 80, 8080, 863 and 443 used by 2001:db8:6401::1 and 2001:db8:6401::2 servers are 864 under attack (illustrated in JSON diagnostic notation). The presence 865 of 'cdid' indicates that a server-domain DOTS gateway has modified 866 the initial PUT request sent by the DOTS client. Note that 'cdid' 867 MUST NOT appear in the PUT request message body. 869 Header: PUT (Code=0.03) 870 Uri-Path: ".well-known" 871 Uri-Path: "dots" 872 Uri-Path: "v1.0" 873 Uri-Path: "mitigate" 874 Uri-Path: "cdid=7eeaf349529eb55ed50113" 875 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 876 Uri-Path: "mid=123" 877 Content-Format: "application/dots+cbor" 878 { 879 "ietf-dots-signal-channel:mitigation-scope": { 880 "scope": [ 881 { 882 "target-prefix": [ 883 "2001:db8:6401::1/128", 884 "2001:db8:6401::2/128" 885 ], 886 "target-port-range": [ 887 { 888 "lower-port": 80 889 }, 890 { 891 "lower-port": 443 892 }, 893 { 894 "lower-port": 8080 895 } 896 ], 897 "target-protocol": [ 898 6 899 ], 900 "lifetime": 3600 901 } 902 ] 903 } 904 } 906 Figure 7: PUT for DOTS Mitigation Request 908 The corresponding CBOR encoding format is shown in Figure 8. 910 A1 # map(1) 911 01 # unsigned(1) 912 A1 # map(1) 913 02 # unsigned(2) 914 81 # array(1) 915 A3 # map(3) 916 06 # unsigned(6) 917 82 # array(2) 918 74 # text(20) 919 323030313A6462383A363430313A3A312F313238 920 74 # text(20) 921 323030313A6462383A363430313A3A322F313238 922 07 # unsigned(7) 923 83 # array(3) 924 A1 # map(1) 925 08 # unsigned(8) 926 18 50 # unsigned(80) 927 A1 # map(1) 928 08 # unsigned(8) 929 19 01BB # unsigned(443) 930 A1 # map(1) 931 08 # unsigned(8) 932 19 1F90 # unsigned(8080) 933 0A # unsigned(10) 934 81 # array(1) 935 06 # unsigned(6) 936 0E # unsigned(14) 937 19 0E10 # unsigned(3600) 939 Figure 8: PUT for DOTS Mitigation Request (CBOR) 941 In both DOTS signal and data channel sessions, the DOTS client MUST 942 authenticate itself to the DOTS server (Section 8). The DOTS server 943 MAY use the algorithm presented in Section 7 of [RFC7589] to derive 944 the DOTS client identity or username from the client certificate. 945 The DOTS client identity allows the DOTS server to accept mitigation 946 requests with scopes that the DOTS client is authorized to manage. 948 The DOTS server couples the DOTS signal and data channel sessions 949 using the DOTS client identity and optionally the 'cdid' parameter 950 value, so the DOTS server can validate whether the aliases conveyed 951 in the mitigation request were indeed created by the same DOTS client 952 using the DOTS data channel session. If the aliases were not created 953 by the DOTS client, the DOTS server MUST return 4.00 (Bad Request) in 954 the response. 956 The DOTS server couples the DOTS signal channel sessions using the 957 DOTS client identity and optionally the 'cdid' parameter value, and 958 the DOTS server uses 'mid' and 'cuid' Uri-Path parameter values to 959 detect duplicate mitigation requests. If the mitigation request 960 contains the 'alias-name' and other parameters identifying the target 961 resources (such as 'target-prefix', 'target-port-range', 'target- 962 fqdn', or 'target-uri'), the DOTS server appends the parameter values 963 in 'alias-name' with the corresponding parameter values in 'target- 964 prefix', 'target-port-range', 'target-fqdn', or 'target-uri'. 966 The DOTS server indicates the result of processing the PUT request 967 using CoAP response codes. CoAP 2.xx codes are success. CoAP 4.xx 968 codes are some sort of invalid requests (client errors). COAP 5.xx 969 codes are returned if the DOTS server has erred or is currently 970 unavailable to provide mitigation in response to the mitigation 971 request from the DOTS client. 973 Figure 9 shows an example response to a PUT request that is 974 successfully processed by a DOTS server (i.e., CoAP 2.xx response 975 codes). This version of the specification forbids 'cuid' and 'cdid' 976 (if used) to be returned in a response message body. 978 { 979 "ietf-dots-signal-channel:mitigation-scope": { 980 "scope": [ 981 { 982 "mid": 12332, 983 "lifetime": 3600 984 } 985 ] 986 } 987 } 989 Figure 9: 2.xx Response Body 991 If the request is missing a mandatory attribute, does not include 992 'cuid' or 'mid' Uri-Path options, includes multiple 'scope' 993 parameters, or contains invalid or unknown parameters, the DOTS 994 server MUST reply with 4.00 (Bad Request). DOTS agents can safely 995 ignore Vendor-Specific parameters they don't understand. 997 A DOTS server that receives a mitigation request with a lifetime set 998 to '0' MUST reply with a 4.00 (Bad Request). 1000 If the DOTS server does not find the 'mid' parameter value conveyed 1001 in the PUT request in its configuration data, it MAY accept the 1002 mitigation request by sending back a 2.01 (Created) response to the 1003 DOTS client; the DOTS server will consequently try to mitigate the 1004 attack. 1006 If the DOTS server finds the 'mid' parameter value conveyed in the 1007 PUT request in its configuration data bound to that DOTS client, it 1008 MAY update the mitigation request, and a 2.04 (Changed) response is 1009 returned to indicate a successful update of the mitigation request. 1011 The relative order of two mitigation requests, having the same 1012 'trigger-mitigation' type, from a DOTS client is determined by 1013 comparing their respective 'mid' values. If two mitigation requests 1014 with the same 'trigger-mitigation' type have overlapping mitigation 1015 scopes, the mitigation request with the highest numeric 'mid' value 1016 will override the other mitigation request. Two mitigation requests 1017 from a DOTS client have overlapping scopes if there is a common IP 1018 address, IP prefix, FQDN, URI, or alias-name. To avoid maintaining a 1019 long list of overlapping mitigation requests (i.e., requests with the 1020 same 'trigger-mitigation' type and overlapping scopes) from a DOTS 1021 client and avoid error-prone provisioning of mitigation requests from 1022 a DOTS client, the overlapped lower numeric 'mid' MUST be 1023 automatically deleted and no longer available at the DOTS server. 1024 For example, if the DOTS server receives a mitigation request which 1025 overlaps with an existing mitigation with a higher numeric 'mid', the 1026 DOTS server rejects the request by returning 4.09 (Conflict) to the 1027 DOTS client. The response includes enough information for a DOTS 1028 client to recognize the source of the conflict as described below: 1030 conflict-information: Indicates that a mitigation request is 1031 conflicting with another mitigation request. This optional 1032 attribute has the following structure: 1034 conflict-cause: Indicates the cause of the conflict. The 1035 following values are defined: 1037 1: Overlapping targets. 'conflict-scope' provides more details 1038 about the conflicting target clauses. 1040 conflict-scope: Indicates the conflict scope. It may include a 1041 list of IP addresses, a list of prefixes, a list of port 1042 numbers, a list of target protocols, a list of FQDNs, a list of 1043 URIs, a list of alias-names, or a 'mid'. 1045 If the DOTS server receives a mitigation request which overlaps with 1046 an active mitigation request, but both having distinct 'trigger- 1047 mitigation' types, the DOTS server MUST deactivate (absent explicit 1048 policy/configuration otherwise) the mitigation request with 'trigger- 1049 mitigation' set to false. Particularly, if the mitigation request 1050 with 'trigger-mitigation' set to false is active, the DOTS server 1051 withdraws the mitigation request (i.e., status code is set to '7' as 1052 defined in Table 2) and transitions the status of the mitigation 1053 request to '8'. 1055 Upon DOTS signal channel session loss with a peer DOTS client, the 1056 DOTS server MUST withdraw (absent explicit policy/configuration 1057 otherwise) any active mitigation requests overlapping with mitigation 1058 requests having 'trigger-mitigation' set to false from that DOTS 1059 client. Note that active-but-terminating period is not observed for 1060 mitigations withdrawn at the initiative of the DOTS server. 1062 DOTS clients may adopt various strategies for setting the scopes of 1063 immediate and pre-configured mitigation requests to avoid potential 1064 conflicts. For example, a DOTS client may tweak pre-configured 1065 scopes so that the scope of any overlapping immediate mitigation 1066 request will be a subset of the pre-configured scopes. Also, if an 1067 immediate mitigation request overlaps with any of the pre-configured 1068 scopes, the DOTS client sets the scope of the overlapping immediate 1069 mitigation request to be a subset of the pre-configured scopes. 1071 If the request is conflicting with an existing mitigation request 1072 from a different DOTS client, the DOTS server may return 2.01 1073 (Created) or 4.09 (Conflict) to the requesting DOTS client. If the 1074 DOTS server decides to maintain the new mitigation request, the DOTS 1075 server returns 2.01 (Created) to the requesting DOTS client. If the 1076 DOTS server decides to reject the new mitigation request, the DOTS 1077 server returns 4.09 (Conflict) to the requesting DOTS client. For 1078 both 2.01 (Created) and 4.09 (Conflict) responses, the response 1079 includes enough information for a DOTS client to recognize the source 1080 of the conflict as described below: 1082 conflict-information: Indicates that a mitigation request is 1083 conflicting with another mitigation request(s) from other DOTS 1084 client(s). This optional attribute has the following structure: 1086 conflict-status: Indicates the status of a conflicting mitigation 1087 request. The following values are defined: 1089 1: DOTS server has detected conflicting mitigation requests 1090 from different DOTS clients. This mitigation request is 1091 currently inactive until the conflicts are resolved. 1092 Another mitigation request is active. 1094 2: DOTS server has detected conflicting mitigation requests 1095 from different DOTS clients. This mitigation request is 1096 currently active. 1098 3: DOTS server has detected conflicting mitigation requests 1099 from different DOTS clients. All conflicting mitigation 1100 requests are inactive. 1102 conflict-cause: Indicates the cause of the conflict. The 1103 following values are defined: 1105 1: Overlapping targets. 'conflict-scope' provides more details 1106 about the conflicting target clauses. 1108 2: Conflicts with an existing white list. This code is 1109 returned when the DDoS mitigation detects source addresses/ 1110 prefixes in the white-listed ACLs are attacking the target. 1112 3: CUID Collision. This code is returned when a DOTS client 1113 uses a 'cuid' that is already used by another DOTS client. 1114 This code is an indication that the request has been 1115 rejected and a new request with a new 'cuid' is to be re- 1116 sent by the DOTS client. Note that 'conflict-status', 1117 'conflict-scope', and 'retry-timer' are not returned in the 1118 error response. 1120 conflict-scope: Indicates the conflict scope. It may include a 1121 list of IP addresses, a list of prefixes, a list of port 1122 numbers, a list of target protocols, a list of FQDNs, a list of 1123 URIs, a list of alias-names, or references to conflicting ACLs. 1125 retry-timer: Indicates, in seconds, the time after which the DOTS 1126 client may re-issue the same request. The DOTS server returns 1127 'retry-timer' only to DOTS client(s) for which a mitigation 1128 request is deactivated. Any retransmission of the same 1129 mitigation request before the expiry of this timer is likely to 1130 be rejected by the DOTS server for the same reasons. 1132 The retry-timer SHOULD be equal to the lifetime of the active 1133 mitigation request resulting in the deactivation of the 1134 conflicting mitigation request. The lifetime of the 1135 deactivated mitigation request will be updated to (retry-timer 1136 + 45 seconds), so the DOTS client can refresh the deactivated 1137 mitigation request after retry-timer seconds before expiry of 1138 lifetime and check if the conflict is resolved. 1140 As an active attack evolves, DOTS clients can adjust the scope of 1141 requested mitigation as necessary, by refining the scope of resources 1142 requiring mitigation. This can be achieved by sending a PUT request 1143 with a new 'mid' value that will override the existing one with 1144 overlapping mitigation scopes. 1146 For a mitigation request to continue beyond the initial negotiated 1147 lifetime, the DOTS client has to refresh the current mitigation 1148 request by sending a new PUT request. This PUT request MUST use the 1149 same 'mid' value, and MUST repeat all the other parameters as sent in 1150 the original mitigation request apart from a possible change to the 1151 lifetime parameter value. 1153 4.4.2. Retrieve Information Related to a Mitigation 1155 A GET request is used by a DOTS client to retrieve information 1156 (including status) of DOTS mitigations from a DOTS server. 1158 'cuid' is a mandatory Uri-Path parameter for GET requests. 1160 Uri-Path parameters with empty values MUST NOT be present in a 1161 request. 1163 The same considerations for manipulating 'cdid' parameter by server- 1164 domain DOTS gateways specified in Section 4.4.1 MUST be followed for 1165 GET requests. 1167 The 'c' (content) parameter and its permitted values defined in 1168 [I-D.ietf-core-comi] can be used to retrieve non-configuration data 1169 (attack mitigation status), configuration data, or both. The DOTS 1170 server MAY support this optional filtering capability. It can safely 1171 ignore it if not supported. If the DOTS client supports the optional 1172 filtering capability, it SHOULD use "c=n" query (to get back only the 1173 dynamically changing data) or "c=c" query (to get back the static 1174 configuration values) when the DDoS attack is active to limit the 1175 size of the response. 1177 The DOTS client can use Block-wise transfer [RFC7959] to get the list 1178 of all its mitigations maintained by a DOTS server, it can send 1179 Block2 Option in a GET request with NUM = 0 to aid in limiting the 1180 size of the response. If the representation of all the active 1181 mitigation requests associated with the DOTS client does not fit 1182 within a single datagram, the DOTS server MUST use the Block2 Option 1183 with NUM = 0 in the GET response. The Size2 Option may be conveyed 1184 in the response to indicate the total size of the resource 1185 representation. The DOTS client retrieves the rest of the 1186 representation by sending additional GET requests with Block2 Options 1187 containing NUM values greater than zero. The DOTS client MUST adhere 1188 to the block size preferences indicated by the DOTS server in the 1189 response. If the DOTS server uses the Block2 Option in the GET 1190 response and the response is for a dynamically changing resource 1191 (e.g. "c=n" or "c=a" query), the DOTS server MUST include the ETag 1192 Option in the response. The DOTS client MUST include the same ETag 1193 value in subsequent GET requests to retrieve the rest of the 1194 representation. 1196 The following examples illustrate how a DOTS client retrieves active 1197 mitigation requests from a DOTS server. In particular: 1199 o Figure 10 shows the example of a GET request to retrieve all DOTS 1200 mitigation requests signaled by a DOTS client. 1202 o Figure 11 shows the example of a GET request to retrieve a 1203 specific DOTS mitigation request signaled by a DOTS client. The 1204 configuration data to be reported in the response is formatted in 1205 the same order as was processed by the DOTS server in the original 1206 mitigation request. 1208 These two examples assume the default of "c=a"; that is, the DOTS 1209 client asks for all data to be reported by the DOTS server. 1211 Header: GET (Code=0.01) 1212 Uri-Path: ".well-known" 1213 Uri-Path: "dots" 1214 Uri-Path: "v1.0" 1215 Uri-Path: "mitigate" 1216 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1217 Observe: 0 1219 Figure 10: GET to Retrieve all DOTS Mitigation Requests 1221 Header: GET (Code=0.01) 1222 Uri-Path: ".well-known" 1223 Uri-Path: "dots" 1224 Uri-Path: "v1.0" 1225 Uri-Path: "mitigate" 1226 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1227 Uri-Path: "mid=12332" 1228 Observe: 0 1230 Figure 11: GET to Retrieve a Specific DOTS Mitigation Request 1232 If the DOTS server does not find the 'mid' Uri-Path value conveyed in 1233 the GET request in its configuration data for the requesting DOTS 1234 client, it MUST respond with a 4.04 (Not Found) error response code. 1235 Likewise, the same error MUST be returned as a response to a request 1236 to retrieve all mitigation records (i.e., 'mid' Uri-Path is not 1237 defined) of a given DOTS client if the DOTS server does not find any 1238 mitigation record for that DOTS client. As a reminder, a DOTS client 1239 is identified by its identity (e.g., client certificate, 'cuid') and 1240 optionally the 'cdid'. 1242 Figure 12 shows a response example of all active mitigation requests 1243 associated with the DOTS client as maintained by the DOTS server. 1244 The response indicates the mitigation status of each mitigation 1245 request. 1247 { 1248 "ietf-dots-signal-channel:mitigation-scope": { 1249 "scope": [ 1250 { 1251 "mid": 12332, 1252 "mitigation-start": "1507818434", 1253 "target-prefix": [ 1254 "2001:db8:6401::1/128", 1255 "2001:db8:6401::2/128" 1256 ], 1257 "target-protocol": [ 1258 17 1259 ], 1260 "lifetime": 1800, 1261 "status": "attack-successfully-mitigated", 1262 "bytes-dropped": "134334555", 1263 "bps-dropped": "43344", 1264 "pkts-dropped": "333334444", 1265 "pps-dropped": "432432" 1266 }, 1267 { 1268 "mid": 12333, 1269 "mitigation-start": "1507818393", 1270 "target-prefix": [ 1271 "2001:db8:6401::1/128", 1272 "2001:db8:6401::2/128" 1273 ], 1274 "target-protocol": [ 1275 6 1276 ], 1277 "lifetime": 1800, 1278 "status": "attack-stopped", 1279 "bytes-dropped": "0", 1280 "bps-dropped": "0", 1281 "pkts-dropped": "0", 1282 "pps-dropped": "0" 1283 } 1284 ] 1285 } 1286 } 1288 Figure 12: Response Body to a GET Request 1290 The mitigation status parameters are described below: 1292 mitigation-start: Mitigation start time is expressed in seconds 1293 relative to 1970-01-01T00:00Z in UTC time (Section 2.4.1 of 1295 [RFC7049]). The CBOR encoding is modified so that the leading tag 1296 1 (epoch-based date/time) MUST be omitted. 1298 This is a mandatory attribute when an attack mitigation is 1299 triggered. Particularly, 'mitigation-start' is not returned for a 1300 mitigation with 'status' code set to 8. 1302 lifetime: The remaining lifetime of the mitigation request, in 1303 seconds. 1305 This is a mandatory attribute. 1307 status: Status of attack mitigation. The various possible values of 1308 'status' parameter are explained in Table 2. 1310 This is a mandatory attribute. 1312 bytes-dropped: The total dropped byte count for the mitigation 1313 request since the attack mitigation is triggered. The count wraps 1314 around when it reaches the maximum value of unsigned integer64. 1316 This is an optional attribute. 1318 bps-dropped: The average number of dropped bytes per second for the 1319 mitigation request since the attack mitigation is triggered. This 1320 SHOULD be a five-minute average. 1322 This is an optional attribute. 1324 pkts-dropped: The total number of dropped packet count for the 1325 mitigation request since the attack mitigation is triggered. The 1326 count wraps around when it reaches the maximum value of unsigned 1327 integer64. 1329 This is an optional attribute. 1331 pps-dropped: The average number of dropped packets per second for 1332 the mitigation request since the attack mitigation is triggered. 1333 This SHOULD be a five-minute average. 1335 This is an optional attribute. 1337 +-----------+-------------------------------------------------------+ 1338 | Parameter | Description | 1339 | Value | | 1340 +-----------+-------------------------------------------------------+ 1341 | 1 | Attack mitigation setup is in progress (e.g., | 1342 | | changing the network path to redirect the inbound | 1343 | | traffic to a DOTS mitigator). | 1344 +-----------+-------------------------------------------------------+ 1345 | 2 | Attack is being successfully mitigated (e.g., traffic | 1346 | | is redirected to a DDoS mitigator and attack traffic | 1347 | | is dropped). | 1348 +-----------+-------------------------------------------------------+ 1349 | 3 | Attack has stopped and the DOTS client can withdraw | 1350 | | the mitigation request. This status code will be | 1351 | | transmitted for immediate mitigation requests till | 1352 | | the mitigation is withdrawn or the lifetime expires. | 1353 | | For mitigation requests with pre-configured scopes | 1354 | | (i.e., 'trigger-mitigation' set to 'false'), this | 1355 | | status code will be transmitted 4 times and then | 1356 | | transition to "8". | 1357 +-----------+-------------------------------------------------------+ 1358 | 4 | Attack has exceeded the mitigation provider | 1359 | | capability. | 1360 +-----------+-------------------------------------------------------+ 1361 | 5 | DOTS client has withdrawn the mitigation request and | 1362 | | the mitigation is active but terminating. | 1363 +-----------+-------------------------------------------------------+ 1364 | 6 | Attack mitigation is now terminated. | 1365 +-----------+-------------------------------------------------------+ 1366 | 7 | Attack mitigation is withdrawn. If a mitigation | 1367 | | request with 'trigger-mitigation' set to false is | 1368 | | withdrawn because it overlaps with an immediate | 1369 | | mitigation request, this status code will be | 1370 | | transmitted 4 times and then transition to "8" for | 1371 | | the mitigation request with pre-configured scopes. | 1372 +-----------+-------------------------------------------------------+ 1373 | 8 | Attack mitigation will be triggered for the | 1374 | | mitigation request only when the DOTS signal channel | 1375 | | session is lost. | 1376 +-----------+-------------------------------------------------------+ 1378 Table 2: Values of 'status' Parameter 1380 4.4.2.1. DOTS Servers Sending Mitigation Status 1382 The Observe Option defined in [RFC7641] extends the CoAP core 1383 protocol with a mechanism for a CoAP client to "observe" a resource 1384 on a CoAP server: The client retrieves a representation of the 1385 resource and requests this representation be updated by the server as 1386 long as the client is interested in the resource. DOTS 1387 implementations MUST use the Observe Option for both 'mitigate' and 1388 'config' (Section 4.2). 1390 A DOTS client conveys the Observe Option set to '0' in the GET 1391 request to receive asynchronous notifications of attack mitigation 1392 status from the DOTS server. 1394 Unidirectional mitigation notifications within the bidirectional 1395 signal channel enables asynchronous notifications between the agents. 1396 [RFC7641] indicates that (1) a notification can be sent in a 1397 Confirmable (CON) or a Non-confirmable (NON) message, and (2) the 1398 message type used is typically application dependent and may be 1399 determined by the server for each notification individually. For 1400 DOTS server application, the message type MUST always be set to Non- 1401 confirmable even if the underlying COAP library elects a notification 1402 to be sent in a Confirmable message. 1404 Due to the higher likelihood of packet loss during a DDoS attack, the 1405 DOTS server periodically sends attack mitigation status to the DOTS 1406 client and also notifies the DOTS client whenever the status of the 1407 attack mitigation changes. If the DOTS server cannot maintain an RTT 1408 estimate, it SHOULD NOT send more than one asynchronous notification 1409 every 3 seconds, and SHOULD use an even less aggressive rate whenever 1410 possible (case 2 in Section 3.1.3 of [RFC8085]). 1412 When conflicting requests are detected, the DOTS server enforces the 1413 corresponding policy (e.g., accept all requests, reject all requests, 1414 accept only one request but reject all the others, ...). It is 1415 assumed that this policy is supplied by the DOTS server administrator 1416 or it is a default behavior of the DOTS server implementation. Then, 1417 the DOTS server sends notification message(s) to the DOTS client(s) 1418 at the origin of the conflict (refer to the conflict parameters 1419 defined in Section 4.4.1). A conflict notification message includes 1420 information about the conflict cause, scope, and the status of the 1421 mitigation request(s). For example, 1423 o A notification message with 'status' code set to '7 (Attack 1424 mitigation is withdrawn)' and 'conflict-status' set to '1' is sent 1425 to a DOTS client to indicate that an active mitigation request is 1426 deactivated because a conflict is detected. 1428 o A notification message with 'status' code set to '1 (Attack 1429 mitigation is in progress)' and 'conflict-status' set to '2' is 1430 sent to a DOTS client to indicate that this mitigation request is 1431 in progress, but a conflict is detected. 1433 Upon receipt of a conflict notification message indicating that a 1434 mitigation request is deactivated because of a conflict, a DOTS 1435 client MUST NOT resend the same mitigation request before the expiry 1436 of 'retry-timer'. It is also recommended that DOTS clients support 1437 means to alert administrators about mitigation conflicts. 1439 A DOTS client that is no longer interested in receiving notifications 1440 from the DOTS server can simply "forget" the observation. When the 1441 DOTS server sends the next notification, the DOTS client will not 1442 recognize the token in the message and thus will return a Reset 1443 message. This causes the DOTS server to remove the associated entry. 1444 Alternatively, the DOTS client can explicitly deregister itself by 1445 issuing a GET request that has the Token field set to the token of 1446 the observation to be cancelled and includes an Observe Option with 1447 the value set to '1' (deregister). 1449 Figure 13 shows an example of a DOTS client requesting a DOTS server 1450 to send notifications related to a mitigation request. Note that for 1451 mitigations with pre-configured scopes (i.e., 'trigger-mitigation' 1452 set to 'false'), the state will need to transition from 3 (attack- 1453 stopped) to 8 (attack-mitigation-signal-loss). 1455 +-----------+ +-----------+ 1456 |DOTS client| |DOTS server| 1457 +-----------+ +-----------+ 1458 | | 1459 | GET / | 1460 | Token: 0x4a | Registration 1461 | Observe: 0 | 1462 +----------------------------------------->| 1463 | | 1464 | 2.05 Content | 1465 | Token: 0x4a | Notification of 1466 | Observe: 12 | the current state 1467 | status: "attack-mitigation-in-progress" | 1468 | | 1469 |<-----------------------------------------+ 1470 | 2.05 Content | 1471 | Token: 0x4a | Notification upon 1472 | Observe: 44 | a state change 1473 | status: "attack-successfully-mitigated" | 1474 | | 1475 |<-----------------------------------------+ 1476 | 2.05 Content | 1477 | Token: 0x4a | Notification upon 1478 | Observe: 60 | a state change 1479 | status: "attack-stopped" | 1480 |<-----------------------------------------+ 1481 | | 1482 ... 1484 Figure 13: Notifications of Attack Mitigation Status 1486 4.4.2.2. DOTS Clients Polling for Mitigation Status 1488 The DOTS client can send the GET request at frequent intervals 1489 without the Observe Option to retrieve the configuration data of the 1490 mitigation request and non-configuration data (i.e., the attack 1491 status). The frequency of polling the DOTS server to get the 1492 mitigation status SHOULD follow the transmission guidelines in 1493 Section 3.1.3 of [RFC8085]. 1495 If the DOTS server has been able to mitigate the attack and the 1496 attack has stopped, the DOTS server indicates as such in the status. 1497 In such case, the DOTS client recalls the mitigation request by 1498 issuing a DELETE request for this mitigation request (Section 4.4.4). 1500 A DOTS client SHOULD react to the status of the attack as per the 1501 information sent by the DOTS server rather than acknowledging by 1502 itself, using its own means, that the attack has been mitigated. 1504 This ensures that the DOTS client does not recall a mitigation 1505 request prematurely because it is possible that the DOTS client does 1506 not sense the DDoS attack on its resources, but the DOTS server could 1507 be actively mitigating the attack because the attack is not 1508 completely averted. 1510 4.4.3. Efficacy Update from DOTS Clients 1512 While DDoS mitigation is in progress, due to the likelihood of packet 1513 loss, a DOTS client MAY periodically transmit DOTS mitigation 1514 efficacy updates to the relevant DOTS server. A PUT request is used 1515 to convey the mitigation efficacy update to the DOTS server. This 1516 PUT request is treated as a refresh of the current mitigation. 1518 The PUT request used for efficacy update MUST include all the 1519 parameters used in the PUT request to carry the DOTS mitigation 1520 request (Section 4.4.1) unchanged apart from the 'lifetime' parameter 1521 value. If this is not the case, the DOTS server MUST reject the 1522 request with a 4.00 (Bad Request). 1524 The If-Match Option (Section 5.10.8.1 of [RFC7252]) with an empty 1525 value is used to make the PUT request conditional on the current 1526 existence of the mitigation request. If UDP is used as transport, 1527 CoAP requests may arrive out-of-order. For example, the DOTS client 1528 may send a PUT request to convey an efficacy update to the DOTS 1529 server followed by a DELETE request to withdraw the mitigation 1530 request, but the DELETE request arrives at the DOTS server before the 1531 PUT request. To handle out-of-order delivery of requests, if an If- 1532 Match Option is present in the PUT request and the 'mid' in the 1533 request matches a mitigation request from that DOTS client, the 1534 request is processed by the DOTS server. If no match is found, the 1535 PUT request is silently ignored by the DOTS server. 1537 An example of an efficacy update message, which includes an If-Match 1538 Option with an empty value, is depicted in Figure 14. 1540 Header: PUT (Code=0.03) 1541 Uri-Path: ".well-known" 1542 Uri-Path: "dots" 1543 Uri-Path: "v1.0" 1544 Uri-Path: "mitigate" 1545 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1546 Uri-Path: "mid=123" 1547 Content-Format: "application/dots+cbor" 1548 If-Match: 1549 { 1550 "ietf-dots-signal-channel:mitigation-scope": { 1551 "scope": [ 1552 { 1553 "target-prefix": [ 1554 "string" 1555 ], 1556 "target-port-range": [ 1557 { 1558 "lower-port": integer, 1559 "upper-port": integer 1560 } 1561 ], 1562 "target-protocol": [ 1563 integer 1564 ], 1565 "target-fqdn": [ 1566 "string" 1567 ], 1568 "target-uri": [ 1569 "string" 1570 ], 1571 "alias-name": [ 1572 "string" 1573 ], 1574 "lifetime": integer, 1575 "attack-status": integer 1576 } 1577 ] 1578 } 1579 } 1581 Figure 14: Efficacy Update 1583 The 'attack-status' parameter is a mandatory attribute when 1584 performing an efficacy update. The various possible values contained 1585 in the 'attack-status' parameter are described in Table 3. 1587 +-----------+-------------------------------------------------------+ 1588 | Parameter | Description | 1589 | value | | 1590 +-----------+-------------------------------------------------------+ 1591 | 1 | The DOTS client determines that it is still under | 1592 | | attack. | 1593 +-----------+-------------------------------------------------------+ 1594 | 2 | The DOTS client determines that the attack is | 1595 | | successfully mitigated (e.g., attack traffic is not | 1596 | | seen). | 1597 +-----------+-------------------------------------------------------+ 1599 Table 3: Values of 'attack-status' Parameter 1601 The DOTS server indicates the result of processing a PUT request 1602 using CoAP response codes. The response code 2.04 (Changed) is 1603 returned if the DOTS server has accepted the mitigation efficacy 1604 update. The error response code 5.03 (Service Unavailable) is 1605 returned if the DOTS server has erred or is incapable of performing 1606 the mitigation. 1608 4.4.4. Withdraw a Mitigation 1610 DELETE requests are used to withdraw DOTS mitigation requests from 1611 DOTS servers (Figure 15). 1613 'cuid' and 'mid' are mandatory Uri-Path parameters for DELETE 1614 requests. 1616 The same considerations for manipulating 'cdid' parameter by DOTS 1617 gateways, as specified in Section 4.4.1, MUST be followed for DELETE 1618 requests. Uri-Path parameters with empty values MUST NOT be present 1619 in a request. 1621 Header: DELETE (Code=0.04) 1622 Uri-Path: ".well-known" 1623 Uri-Path: "dots" 1624 Uri-Path: "v1.0" 1625 Uri-Path: "mitigate" 1626 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1627 Uri-Path: "mid=123" 1629 Figure 15: Withdraw a DOTS Mitigation 1631 If the DELETE request does not include 'cuid' and 'mid' parameters, 1632 the DOTS server MUST reply with a 4.00 (Bad Request). 1634 Once the request is validated, the DOTS server immediately 1635 acknowledges a DOTS client's request to withdraw the DOTS signal 1636 using 2.02 (Deleted) response code with no response payload. A 2.02 1637 (Deleted) Response Code is returned even if the 'mid' parameter value 1638 conveyed in the DELETE request does not exist in its configuration 1639 data before the request. 1641 If the DOTS server finds the 'mid' parameter value conveyed in the 1642 DELETE request in its configuration data for the DOTS client, then to 1643 protect against route or DNS flapping caused by a DOTS client rapidly 1644 removing a mitigation, and to dampen the effect of oscillating 1645 attacks, the DOTS server MAY allow mitigation to continue for a 1646 limited period after acknowledging a DOTS client's withdrawal of a 1647 mitigation request. During this period, the DOTS server status 1648 messages SHOULD indicate that mitigation is active but terminating 1649 (Section 4.4.2). 1651 The initial active-but-terminating period SHOULD be sufficiently long 1652 to absorb latency incurred by route propagation. The active-but- 1653 terminating period SHOULD be set by default to 120 seconds. If the 1654 client requests mitigation again before the initial active-but- 1655 terminating period elapses, the DOTS server MAY exponentially 1656 increase the active-but-terminating period up to a maximum of 300 1657 seconds (5 minutes). 1659 Once the active-but-terminating period elapses, the DOTS server MUST 1660 treat the mitigation as terminated, as the DOTS client is no longer 1661 responsible for the mitigation. For example, if there is a financial 1662 relationship between the DOTS client and server domains, the DOTS 1663 client stops incurring cost at this point. 1665 If a mitigation is triggered due to a signal channel loss, the DOTS 1666 server relies upon normal triggers to stop that mitigation 1667 (typically, receipt of a valid DELETE request, expiry of the 1668 mitigation lifetime, or observation of traffic to the attack target). 1669 In particular, the DOTS server MUST NOT consider the signal channel 1670 recovery as a trigger to stop the mitigation. 1672 4.5. DOTS Signal Channel Session Configuration 1674 A DOTS client can negotiate, configure, and retrieve the DOTS signal 1675 channel session behavior with its DOTS peers. The DOTS signal 1676 channel can be used, for example, to configure the following: 1678 a. Heartbeat interval (heartbeat-interval): DOTS agents regularly 1679 send heartbeats (CoAP Ping/Pong) to each other after mutual 1680 authentication is successfully completed in order to keep the 1681 DOTS signal channel open. Heartbeat messages are exchanged 1682 between DOTS agents every 'heartbeat-interval' seconds to detect 1683 the current status of the DOTS signal channel session. 1685 b. Missing heartbeats allowed (missing-hb-allowed): This variable 1686 indicates the maximum number of consecutive heartbeat messages 1687 for which a DOTS agent did not receive a response before 1688 concluding that the session is disconnected or defunct. 1690 c. Acceptable signal loss ratio: Maximum retransmissions, 1691 retransmission timeout value, and other message transmission 1692 parameters for the DOTS signal channel. 1694 The same or distinct configuration sets may be used during times when 1695 a mitigation is active ('mitigating-config') and when no mitigation 1696 is active ('idle-config'). This is particularly useful for DOTS 1697 servers that might want to reduce heartbeat frequency or cease 1698 heartbeat exchanges when an active DOTS client has not requested 1699 mitigation. If distinct configurations are used, DOTS agents MUST 1700 follow the appropriate configuration set as a function of the 1701 mitigation activity (e.g., if no mitigation request is active, 'idle- 1702 config'-related values must be followed). Additionally, DOTS agents 1703 MUST automatically switch to the other configuration upon a change in 1704 the mitigation activity (e.g., if an attack mitigation is launched 1705 after a peacetime, the DOTS agent switches from 'idle-config' to 1706 'mitigating-config'-related values). 1708 Requests and responses are deemed reliable by marking them as 1709 Confirmable messages. DOTS signal channel session configuration 1710 requests and responses are marked as Confirmable messages. As 1711 explained in Section 2.1 of [RFC7252], a Confirmable message is 1712 retransmitted using a default timeout and exponential back-off 1713 between retransmissions, until the DOTS server sends an 1714 Acknowledgement message (ACK) with the same Message ID conveyed from 1715 the DOTS client. 1717 Message transmission parameters are defined in Section 4.8 of 1718 [RFC7252]. The DOTS server can either piggyback the response in the 1719 acknowledgement message or, if the DOTS server cannot respond 1720 immediately to a request carried in a Confirmable message, it simply 1721 responds with an Empty Acknowledgement message so that the DOTS 1722 client can stop retransmitting the request. Empty Acknowledgement 1723 message is explained in Section 2.2 of [RFC7252]. When the response 1724 is ready, the server sends it in a new Confirmable message which in 1725 turn needs to be acknowledged by the DOTS client (see Sections 5.2.1 1726 and 5.2.2 of [RFC7252]). Requests and responses exchanged between 1727 DOTS agents during peacetime are marked as Confirmable messages. 1729 Implementation Note: A DOTS client that receives a response in a 1730 CON message may want to clean up the message state right after 1731 sending the ACK. If that ACK is lost and the DOTS server 1732 retransmits the CON, the DOTS client may no longer have any state 1733 that would help it correlate this response: from the DOTS client's 1734 standpoint, the retransmission message is unexpected. The DOTS 1735 client will send a Reset message so it does not receive any more 1736 retransmissions. This behavior is normal and not an indication of 1737 an error (see Section 5.3.2 of [RFC7252] for more details). 1739 4.5.1. Discover Configuration Parameters 1741 A GET request is used to obtain acceptable (e.g., minimum and maximum 1742 values) and current configuration parameters on the DOTS server for 1743 DOTS signal channel session configuration. This procedure occurs 1744 between a DOTS client and its immediate peer DOTS server. As such, 1745 this GET request MUST NOT be relayed by an on-path DOTS gateway. 1747 Figure 16 shows how to obtain acceptable configuration parameters for 1748 the DOTS server. 1750 Header: GET (Code=0.01) 1751 Uri-Path: ".well-known" 1752 Uri-Path: "dots" 1753 Uri-Path: "v1.0" 1754 Uri-Path: "config" 1756 Figure 16: GET to Retrieve Configuration 1758 The DOTS server in the 2.05 (Content) response conveys the current, 1759 minimum, and maximum attribute values acceptable by the DOTS server 1760 (Figure 17). 1762 Content-Format: "application/dots+cbor" 1763 { 1764 "ietf-dots-signal-channel:signal-config": { 1765 "mitigating-config": { 1766 "heartbeat-interval": { 1767 "max-value": integer, 1768 "min-value": integer, 1769 "current-value": integer 1770 }, 1771 "missing-hb-allowed": { 1772 "max-value": integer, 1773 "min-value": integer, 1774 "current-value": integer 1775 }, 1776 "max-retransmit": { 1777 "max-value": integer, 1778 "min-value": integer, 1779 "current-value": integer 1780 }, 1781 "ack-timeout": { 1782 "max-value-decimal": number, 1783 "min-value-decimal": number, 1784 "current-value-decimal": number 1785 }, 1786 "ack-random-factor": { 1787 "max-value-decimal": number, 1788 "min-value-decimal": number, 1789 "current-value-decimal": number 1790 } 1791 }, 1792 "idle-config": { 1793 "heartbeat-interval": { 1794 "max-value": integer, 1795 "min-value": integer, 1796 "current-value": integer 1797 }, 1798 "missing-hb-allowed": { 1799 "max-value": integer, 1800 "min-value": integer, 1801 "current-value": integer 1802 }, 1803 "max-retransmit": { 1804 "max-value": integer, 1805 "min-value": integer, 1806 "current-value": integer 1807 }, 1808 "ack-timeout": { 1809 "max-value-decimal": number, 1810 "min-value-decimal": number, 1811 "current-value-decimal": number 1812 }, 1813 "ack-random-factor": { 1814 "max-value-decimal": number, 1815 "min-value-decimal": number, 1816 "current-value-decimal": number 1817 } 1818 } 1819 } 1820 } 1822 Figure 17: GET Configuration Response Body 1824 The parameters in Figure 17 are described below: 1826 mitigating-config: Set of configuration parameters to use when a 1827 mitigation is active. The following parameters may be included: 1829 heartbeat-interval: Time interval in seconds between two 1830 consecutive heartbeat messages. 1832 '0' is used to disable the heartbeat mechanism. 1834 This is an optional attribute. 1836 missing-hb-allowed: Maximum number of consecutive heartbeat 1837 messages for which the DOTS agent did not receive a response 1838 before concluding that the session is disconnected. 1840 This is an optional attribute. 1842 max-retransmit: Maximum number of retransmissions for a message 1843 (referred to as MAX_RETRANSMIT parameter in CoAP). 1845 This is an optional attribute. 1847 ack-timeout: Timeout value in seconds used to calculate the 1848 initial retransmission timeout value (referred to as 1849 ACK_TIMEOUT parameter in CoAP). 1851 This is an optional attribute. 1853 ack-random-factor: Random factor used to influence the timing of 1854 retransmissions (referred to as ACK_RANDOM_FACTOR parameter in 1855 CoAP). 1857 This is an optional attribute. 1859 idle-config: Set of configuration parameters to use when no 1860 mitigation is active. This attribute has the same structure as 1861 'mitigating-config'. 1863 Figure 18 shows an example of acceptable and current configuration 1864 parameters on a DOTS server for DOTS signal channel session 1865 configuration. The same acceptable configuration is used during 1866 attack and peace times. 1868 Content-Format: "application/dots+cbor" 1869 { 1870 "ietf-dots-signal-channel:signal-config": { 1871 "mitigating-config": { 1872 "heartbeat-interval": { 1873 "max-value": 240, 1874 "min-value": 15, 1875 "current-value": 30 1876 }, 1877 "missing-hb-allowed": { 1878 "max-value": 9, 1879 "min-value": 3, 1880 "current-value": 5 1881 }, 1882 "max-retransmit": { 1883 "max-value": 15, 1884 "min-value": 2, 1885 "current-value": 3 1886 }, 1887 "ack-timeout": { 1888 "max-value-decimal": "30.0", 1889 "min-value-decimal": "1.0", 1890 "current-value-decimal": "2.0" 1891 }, 1892 "ack-random-factor": { 1893 "max-value-decimal": "4.0", 1894 "min-value-decimal": "1.1", 1895 "current-value-decimal": "1.5" 1896 } 1897 }, 1898 "idle-config": { 1899 "heartbeat-interval": { 1900 "max-value": 240, 1901 "min-value": 15, 1902 "current-value": 30 1903 }, 1904 "missing-hb-allowed": { 1905 "max-value": 9, 1906 "min-value": 3, 1907 "current-value": 5 1908 }, 1909 "max-retransmit": { 1910 "max-value": 15, 1911 "min-value": 2, 1912 "current-value": 3 1913 }, 1914 "ack-timeout": { 1915 "max-value-decimal": "30.0", 1916 "min-value-decimal": "1.0", 1917 "current-value-decimal": "2.0" 1918 }, 1919 "ack-random-factor": { 1920 "max-value-decimal": "4.0", 1921 "min-value-decimal": "1.1", 1922 "current-value-decimal": "1.5" 1923 } 1924 } 1925 } 1926 } 1928 Figure 18: Example of a Configuration Response Body 1930 4.5.2. Convey DOTS Signal Channel Session Configuration 1932 A PUT request is used to convey the configuration parameters for the 1933 signal channel (e.g., heartbeat interval, maximum retransmissions). 1934 Message transmission parameters for CoAP are defined in Section 4.8 1935 of [RFC7252]. The RECOMMENDED values of transmission parameter 1936 values are ack-timeout (2 seconds), max-retransmit (3), ack-random- 1937 factor (1.5). In addition to those parameters, the RECOMMENDED 1938 specific DOTS transmission parameter values are 'heartbeat-interval' 1939 (30 seconds) and 'missing-hb-allowed' (5). 1941 Note: heartbeat-interval should be tweaked to also assist DOTS 1942 messages for NAT traversal (SIG-011 of 1943 [I-D.ietf-dots-requirements]). According to [RFC8085], keepalive 1944 messages must not be sent more frequently than once every 15 1945 seconds and should use longer intervals when possible. 1946 Furthermore, [RFC4787] recommends NATs to use a state timeout of 2 1947 minutes or longer, but experience shows that sending packets every 1948 15 to 30 seconds is necessary to prevent the majority of 1949 middleboxes from losing state for UDP flows. From that 1950 standpoint, this specification recommends a minimum heartbeat- 1951 interval of 15 seconds and a maximum heartbeat-interval of 240 1952 seconds. The recommended value of 30 seconds is selected to 1953 anticipate the expiry of NAT state. 1955 A heartbeat-interval of 30 seconds may be considered as too chatty 1956 in some deployments. For such deployments, DOTS agents may 1957 negotiate longer heartbeat-interval values to prevent any network 1958 overload with too frequent keepalives. 1960 Different heartbeat intervals can be defined for 'mitigating- 1961 config' and 'idle-config' to reduce being too chatty during idle 1962 times. If there is an on-path translator between the DOTS client 1963 (standalone or part of a DOTS gateway) and the DOTS server, the 1964 'mitigating-config' heartbeat-interval has to be smaller than the 1965 translator session timeout. It is recommended that the 'idle- 1966 config' heartbeat-interval is also smaller than the translator 1967 session timeout to prevent translator traversal issues, or set to 1968 '0'. Means to discover the lifetime assigned by a translator are 1969 out of scope. 1971 When a Confirmable "CoAP Ping" is sent, and if there is no response, 1972 the "CoAP Ping" is retransmitted max-retransmit number of times by 1973 the CoAP layer using an initial timeout set to a random duration 1974 between ack-timeout and (ack-timeout*ack-random-factor) and 1975 exponential back-off between retransmissions. By choosing the 1976 recommended transmission parameters, the "CoAP Ping" will timeout 1977 after 45 seconds. If the DOTS agent does not receive any response 1978 from the peer DOTS agent for 'missing-hb-allowed' number of 1979 consecutive "CoAP Ping" Confirmable messages, it concludes that the 1980 DOTS signal channel session is disconnected. A DOTS client MUST NOT 1981 transmit a "CoAP Ping" while waiting for the previous "CoAP Ping" 1982 response from the same DOTS server. 1984 If the DOTS agent wishes to change the default values of message 1985 transmission parameters, it SHOULD follow the guidance given in 1986 Section 4.8.1 of [RFC7252]. The DOTS agents MUST use the negotiated 1987 values for message transmission parameters and default values for 1988 non-negotiated message transmission parameters. 1990 The signal channel session configuration is applicable to a single 1991 DOTS signal channel session between DOTS agents, so the 'cuid' Uri- 1992 Path MUST NOT be used. 1994 Header: PUT (Code=0.03) 1995 Uri-Path: ".well-known" 1996 Uri-Path: "dots" 1997 Uri-Path: "v1.0" 1998 Uri-Path: "config" 1999 Uri-Path: "sid=123" 2000 Content-Format: "application/dots+cbor" 2001 { 2002 "ietf-dots-signal-channel:signal-config": { 2003 "mitigating-config": { 2004 "heartbeat-interval": { 2005 "current-value": integer 2006 }, 2007 "missing-hb-allowed": { 2008 "current-value": integer 2009 }, 2010 "max-retransmit": { 2011 "current-value": integer 2012 }, 2013 "ack-timeout": { 2014 "current-value-decimal": number 2015 }, 2016 "ack-random-factor": { 2017 "current-value-decimal": number 2018 } 2019 }, 2020 "idle-config": { 2021 "heartbeat-interval": { 2022 "current-value": integer 2023 }, 2024 "missing-hb-allowed": { 2025 "current-value": integer 2026 }, 2027 "max-retransmit": { 2028 "current-value": integer 2029 }, 2030 "ack-timeout": { 2031 "current-value-decimal": number 2032 }, 2033 "ack-random-factor": { 2034 "current-value-decimal": number 2035 } 2036 } 2037 } 2038 } 2040 Figure 19: PUT to Convey the DOTS Signal Channel Session 2041 Configuration Data 2043 The additional Uri-Path parameter to those defined in Table 1 is as 2044 follows: 2046 sid: Session Identifier is an identifier for the DOTS signal channel 2047 session configuration data represented as an integer. This 2048 identifier MUST be generated by DOTS clients. 'sid' values MUST 2049 increase monotonically. 2051 This is a mandatory attribute. 2053 The meaning of the parameters in the CBOR body is defined in 2054 Section 4.5.1. 2056 At least one of the attributes 'heartbeat-interval', 'missing-hb- 2057 allowed', 'max-retransmit', 'ack-timeout', and 'ack-random-factor' 2058 MUST be present in the PUT request. Note that 'heartbeat-interval', 2059 'missing-hb-allowed', 'max-retransmit', 'ack-timeout', and 'ack- 2060 random-factor', if present, do not need to be provided for both 2061 'mitigating-config', and 'idle-config' in a PUT request. 2063 The PUT request with a higher numeric 'sid' value overrides the DOTS 2064 signal channel session configuration data installed by a PUT request 2065 with a lower numeric 'sid' value. To avoid maintaining a long list 2066 of 'sid' requests from a DOTS client, the lower numeric 'sid' MUST be 2067 automatically deleted and no longer available at the DOTS server. 2069 Figure 20 shows a PUT request example to convey the configuration 2070 parameters for the DOTS signal channel. In this example, the 2071 heartbeat mechanism is disabled when no mitigation is active, while 2072 the heartbeat interval is set to '91' when a mitigation is active. 2074 Header: PUT (Code=0.03) 2075 Uri-Path: ".well-known" 2076 Uri-Path: "dots" 2077 Uri-Path: "v1.0" 2078 Uri-Path: "config" 2079 Uri-Path: "sid=123" 2080 Content-Format: "application/dots+cbor" 2081 { 2082 "ietf-dots-signal-channel:signal-config": { 2083 "mitigating-config": { 2084 "heartbeat-interval": { 2085 "current-value": 91 2086 }, 2087 "missing-hb-allowed": { 2088 "current-value": 3 2089 }, 2090 "max-retransmit": { 2091 "current-value": 3 2092 }, 2093 "ack-timeout": { 2094 "current-value-decimal": "2.0" 2095 }, 2096 "ack-random-factor": { 2097 "current-value-decimal": "1.5" 2098 } 2099 }, 2100 "idle-config": { 2101 "heartbeat-interval": { 2102 "current-value": 0 2103 }, 2104 "max-retransmit": { 2105 "current-value": 3 2106 }, 2107 "ack-timeout": { 2108 "current-value-decimal": "2.0" 2109 }, 2110 "ack-random-factor": { 2111 "current-value-decimal": "1.5" 2112 } 2113 } 2114 } 2115 } 2117 Figure 20: PUT to Convey the Configuration Parameters 2119 The DOTS server indicates the result of processing the PUT request 2120 using CoAP response codes: 2122 o If the request is missing a mandatory attribute, does not include 2123 a 'sid' Uri-Path, or contains one or more invalid or unknown 2124 parameters, 4.00 (Bad Request) MUST be returned in the response. 2126 o If the DOTS server does not find the 'sid' parameter value 2127 conveyed in the PUT request in its configuration data and if the 2128 DOTS server has accepted the configuration parameters, then a 2129 response code 2.01 (Created) MUST be returned in the response. 2131 o If the DOTS server finds the 'sid' parameter value conveyed in the 2132 PUT request in its configuration data and if the DOTS server has 2133 accepted the updated configuration parameters, 2.04 (Changed) MUST 2134 be returned in the response. 2136 o If any of the 'heartbeat-interval', 'missing-hb-allowed', 'max- 2137 retransmit', 'target-protocol', 'ack-timeout', and 'ack-random- 2138 factor' attribute values are not acceptable to the DOTS server, 2139 4.22 (Unprocessable Entity) MUST be returned in the response. 2140 Upon receipt of this error code, the DOTS client SHOULD request 2141 the maximum and minimum attribute values acceptable to the DOTS 2142 server (Section 4.5.1). 2144 The DOTS client may re-try and send the PUT request with updated 2145 attribute values acceptable to the DOTS server. 2147 A DOTS client may issue a GET message with 'sid' Uri-Path parameter 2148 to retrieve the negotiated configuration. The response does not need 2149 to include 'sid' in its message body. 2151 4.5.3. Configuration Freshness and Notifications 2153 Max-Age Option (Section 5.10.5 of [RFC7252]) SHOULD be returned by a 2154 DOTS server to associate a validity time with a configuration it 2155 sends. This feature allows the update of the configuration data if a 2156 change occurs at the DOTS server side. For example, the new 2157 configuration may instruct a DOTS client to cease heartbeats or 2158 reduce heartbeat frequency. 2160 It is NOT RECOMMENDED to return a Max-Age Option set to 0. 2162 Returning a Max-Age Option set to 2**32-1 is equivalent to 2163 associating an infinite lifetime with the configuration. 2165 If a non-zero value of Max-Age Option is received by a DOTS client, 2166 it MUST issue a GET request with 'sid' Uri-Path parameter to retrieve 2167 the current and acceptable configuration before the expiry of the 2168 value enclosed in the Max-Age option. This request is considered by 2169 the client and the server as a means to refresh the configuration 2170 parameters for the signal channel. When a DDoS attack is active, 2171 refresh requests MUST NOT be sent by DOTS clients and the DOTS server 2172 MUST NOT terminate the (D)TLS session after the expiry of the value 2173 returned in Max-Age Option. 2175 If Max-Age Option is not returned in a response, the DOTS client 2176 initiates GET requests to refresh the configuration parameters each 2177 60 seconds (Section 5.10.5 of [RFC7252]). To prevent such overload, 2178 it is RECOMMENDED that DOTS servers return a Max-Age Option in GET 2179 responses. Considerations related to which value to use and how such 2180 value is set, are implementation- and deployment-specific. 2182 If an Observe Option set to 0 is included in the configuration 2183 request, the DOTS server sends notifications of any configuration 2184 change (Section 4.2 of [RFC7641]). 2186 If a DOTS server detects that a misbehaving DOTS client does not 2187 contact the DOTS server after the expiry of Max-Age, in order to 2188 retrieve the signal channel configuration data, it MAY terminate the 2189 (D)TLS session. A (D)TLS session is terminated by the receipt of an 2190 authenticated message that closes the connection (e.g., a fatal alert 2191 (Section 6 of [RFC8446])). 2193 4.5.4. Delete DOTS Signal Channel Session Configuration 2195 A DELETE request is used to delete the installed DOTS signal channel 2196 session configuration data (Figure 21). 2198 Header: DELETE (Code=0.04) 2199 Uri-Path: ".well-known" 2200 Uri-Path: "dots" 2201 Uri-Path: "v1.0" 2202 Uri-Path: "config" 2203 Uri-Path: "sid=123" 2205 Figure 21: Delete Configuration 2207 The DOTS server resets the DOTS signal channel session configuration 2208 back to the default values and acknowledges a DOTS client's request 2209 to remove the DOTS signal channel session configuration using 2.02 2210 (Deleted) response code. 2212 Upon bootstrapping or reboot, a DOTS client MAY send a DELETE request 2213 to set the configuration parameters to default values. Such a 2214 request does not include any 'sid'. 2216 4.6. Redirected Signaling 2218 Redirected DOTS signaling is discussed in detail in Section 3.2.2 of 2219 [I-D.ietf-dots-architecture]. 2221 If a DOTS server wants to redirect a DOTS client to an alternative 2222 DOTS server for a signal session, then the response code 5.03 2223 (Service Unavailable) will be returned in the response to the DOTS 2224 client. 2226 The DOTS server can return the error response code 5.03 in response 2227 to a request from the DOTS client or convey the error response code 2228 5.03 in a unidirectional notification response from the DOTS server. 2230 The DOTS server in the error response conveys the alternate DOTS 2231 server's FQDN, and the alternate DOTS server's IP address(es) values 2232 in the CBOR body (Figure 22). 2234 { 2235 "ietf-dots-signal-channel:redirected-signal": { 2236 "alt-server": "string", 2237 "alt-server-record": [ 2238 "string" 2239 ] 2240 } 2242 Figure 22: Redirected Server Error Response Body 2244 The parameters are described below: 2246 alt-server: FQDN of an alternate DOTS server. 2248 This is a mandatory attribute. 2250 alt-server-record: A list of IP addresses of an alternate DOTS 2251 server. 2253 This is an optional attribute. 2255 The DOTS server returns the Time to live (TTL) of the alternate DOTS 2256 server in a Max-Age Option. That is, the time interval that the 2257 alternate DOTS server may be cached for use by a DOTS client. A Max- 2258 Age Option set to 2**32-1 is equivalent to receiving an infinite TTL. 2259 This value means that the alternate DOTS server is to be used until 2260 the alternate DOTS server redirects the traffic with another 5.03 2261 response which encloses an alternate server. 2263 A Max-Age Option set to '0' may be returned for redirecting 2264 mitigation requests. Such value means that the redirection applies 2265 only for the mitigation request in progress. Returning short TTL in 2266 a Max-Age Option may adversely impact DOTS clients on slow links. 2267 Returning short values should be avoided under such conditions. 2269 If the alternate DOTS server TTL has expired, the DOTS client MUST 2270 use the DOTS server(s), that was provisioned using means discussed in 2271 Section 4.1. This fall back mechanism is triggered immediately upon 2272 expiry of the TTL, except when a DDoS attack is active. 2274 Requests issued by misbehaving DOTS clients which do not honor the 2275 TTL conveyed in the Max-Age Option or react to explicit re-direct 2276 messages can be rejected by DOTS servers. 2278 Figure 23 shows a 5.03 response example to convey the DOTS alternate 2279 server 'alt-server.example' together with its IP addresses 2280 2001:db8:6401::1 and 2001:db8:6401::2. 2282 { 2283 "ietf-dots-signal-channel:redirected-signal": { 2284 "alt-server": "alt-server.example", 2285 "alt-server-record": [ 2286 "2001:db8:6401::1", 2287 "2001:db8:6401::2" 2288 ] 2289 } 2291 Figure 23: Example of Redirected Server Error Response Body 2293 When the DOTS client receives 5.03 response with an alternate server 2294 included, it considers the current request as failed, but SHOULD try 2295 re-sending the request to the alternate DOTS server. During a DDoS 2296 attack, the DNS server may be the target of another DDoS attack, 2297 alternate DOTS server's IP addresses conveyed in the 5.03 response 2298 help the DOTS client skip DNS lookup of the alternate DOTS server. 2299 The DOTS client can then try to establish a UDP or a TCP session with 2300 the alternate DOTS server. The DOTS client MAY implement a method to 2301 construct IPv4-embedded IPv6 addresses [RFC6052]; this is required to 2302 handle the scenario where an IPv6-only DOTS client communicates with 2303 an IPv4-only alternate DOTS server. 2305 If the DOTS client has been redirected to a DOTS server to which it 2306 has already communicated with within the last five (5) minutes, it 2307 MUST ignore the redirection and try to contact other DOTS servers 2308 listed in the local configuration or discovered using dynamic means 2309 such as DHCP or SRV procedures. It is RECOMMENDED that DOTS clients 2310 support means to alert administrators about redirect loops. 2312 4.7. Heartbeat Mechanism 2314 To provide an indication of signal health and distinguish an 'idle' 2315 signal channel from a 'disconnected' or 'defunct' session, the DOTS 2316 agent sends a heartbeat over the signal channel to maintain its half 2317 of the channel. The DOTS agent similarly expects a heartbeat from 2318 its peer DOTS agent, and may consider a session terminated in the 2319 prolonged absence of a peer agent heartbeat. 2321 While the communication between the DOTS agents is quiescent, the 2322 DOTS client will probe the DOTS server to ensure it has maintained 2323 cryptographic state and vice versa. Such probes can also keep 2324 firewalls and/or stateful translators bindings alive. This probing 2325 reduces the frequency of establishing a new handshake when a DOTS 2326 signal needs to be conveyed to the DOTS server. 2328 DOTS servers MAY trigger their heartbeat requests immediately after 2329 receiving heartbeat probes from peer DOTS clients. As a reminder, it 2330 is the responsibility of DOTS clients to ensure that on-path 2331 translators/firewalls are maintaining a binding so that the same 2332 external IP address and/or port number is retained for the DOTS 2333 session. 2335 In case of a massive DDoS attack that saturates the incoming link(s) 2336 to the DOTS client, all traffic from the DOTS server to the DOTS 2337 client will likely be dropped, although the DOTS server receives 2338 heartbeat requests in addition to DOTS messages sent by the DOTS 2339 client. In this scenario, the DOTS agents MUST behave differently to 2340 handle message transmission and DOTS session liveliness during link 2341 saturation: 2343 o The DOTS client MUST NOT consider the DOTS session terminated even 2344 after a maximum 'missing-hb-allowed' threshold is reached. The 2345 DOTS client SHOULD keep on using the current DOTS session to send 2346 heartbeat requests over it, so that the DOTS server knows the DOTS 2347 client has not disconnected the DOTS session. 2349 After the maximum 'missing-hb-allowed' threshold is reached, the 2350 DOTS client SHOULD try to resume the (D)TLS session. The DOTS 2351 client SHOULD send mitigation requests over the current DOTS 2352 session, and in parallel, for example, try to resume the (D)TLS 2353 session or use 0-RTT mode in DTLS 1.3 to piggyback the mitigation 2354 request in the ClientHello message. 2356 As soon as the link is no longer saturated, if traffic from the 2357 DOTS server reaches the DOTS client over the current DOTS session, 2358 the DOTS client can stop (D)TLS session resumption or if (D)TLS 2359 session resumption is successful then disconnect the current DOTS 2360 session. 2362 o If the DOTS server does not receive any traffic from the peer DOTS 2363 client, then the DOTS server sends heartbeat requests to the DOTS 2364 client and after maximum 'missing-hb-allowed' threshold is 2365 reached, the DOTS server concludes the session is disconnected. 2367 In DOTS over UDP, heartbeat messages MUST be exchanged between the 2368 DOTS agents using the "CoAP Ping" mechanism defined in Section 4.2 of 2369 [RFC7252]. Concretely, the DOTS agent sends an Empty Confirmable 2370 message and the peer DOTS agent will respond by sending a Reset 2371 message. 2373 In DOTS over TCP, heartbeat messages MUST be exchanged between the 2374 DOTS agents using the Ping and Pong messages specified in Section 4.4 2375 of [RFC8323]. That is, the DOTS agent sends a Ping message and the 2376 peer DOTS agent would respond by sending a single Pong message. 2378 5. DOTS Signal Channel YANG Module 2380 This document defines a YANG [RFC7950] module for DOTS mitigation 2381 scope, DOTS signal channel session configuration data, and DOTS 2382 redirected signalling. 2384 This YANG module defines the DOTS client interaction with the DOTS 2385 server as seen by the DOTS client. A DOTS server is allowed to 2386 update the non-configurable 'ro' entities in the responses. This 2387 YANG module is not intended to be used for DOTS server management 2388 purposes. Such module is out of the scope of this document. 2390 5.1. Tree Structure 2392 This document defines the YANG module "ietf-dots-signal-channel" 2393 (Section 5.2), which has the following tree structure. A DOTS signal 2394 message can either be a mitigation or a configuration message. 2396 module: ietf-dots-signal-channel 2397 +--rw dots-signal 2398 +--rw (message-type)? 2399 +--:(mitigation-scope) 2400 | +--rw scope* [cuid mid] 2401 | +--rw cdid? string 2402 | +--rw cuid string 2403 | +--rw mid uint32 2404 | +--rw target-prefix* inet:ip-prefix 2405 | +--rw target-port-range* [lower-port upper-port] 2406 | | +--rw lower-port inet:port-number 2407 | | +--rw upper-port inet:port-number 2408 | +--rw target-protocol* uint8 2409 | +--rw target-fqdn* inet:domain-name 2410 | +--rw target-uri* inet:uri 2411 | +--rw alias-name* string 2412 | +--rw lifetime? int32 2413 | +--rw trigger-mitigation? boolean 2414 | +--ro mitigation-start? uint64 2415 | +--ro status? enumeration 2416 | +--ro conflict-information 2417 | | +--ro conflict-status? enumeration 2418 | | +--ro conflict-cause? enumeration 2419 | | +--ro retry-timer? uint32 2420 | | +--ro conflict-scope 2421 | | +--ro target-prefix* inet:ip-prefix 2422 | | +--ro target-port-range* [lower-port upper-port] 2423 | | | +--ro lower-port inet:port-number 2424 | | | +--ro upper-port inet:port-number 2425 | | +--ro target-protocol* uint8 2426 | | +--ro target-fqdn* inet:domain-name 2427 | | +--ro target-uri* inet:uri 2428 | | +--ro alias-name* string 2429 | | +--ro acl-list* [acl-name] 2430 | | | +--ro acl-name -> /ietf-acl:acls/acl/name 2431 | | | +--ro acl-type? -> /ietf-acl:acls/acl/type 2432 | | +--ro mid? -> ../../../mid 2433 | +--ro bytes-dropped? yang:zero-based-counter64 2434 | +--ro bps-dropped? yang:zero-based-counter64 2435 | +--ro pkts-dropped? yang:zero-based-counter64 2436 | +--ro pps-dropped? yang:zero-based-counter64 2437 | +--rw attack-status? enumeration 2438 +--:(signal-config) 2439 | +--rw sid uint32 2440 | +--rw mitigating-config 2441 | | +--rw heartbeat-interval 2442 | | | +--ro max-value? uint16 2443 | | | +--ro min-value? uint16 2444 | | | +--rw current-value? uint16 2445 | | +--rw missing-hb-allowed 2446 | | | +--ro max-value? uint16 2447 | | | +--ro min-value? uint16 2448 | | | +--rw current-value? uint16 2449 | | +--rw max-retransmit 2450 | | | +--ro max-value? uint16 2451 | | | +--ro min-value? uint16 2452 | | | +--rw current-value? uint16 2453 | | +--rw ack-timeout 2454 | | | +--ro max-value-decimal? decimal64 2455 | | | +--ro min-value-decimal? decimal64 2456 | | | +--rw current-value-decimal? decimal64 2457 | | +--rw ack-random-factor 2458 | | +--ro max-value-decimal? decimal64 2459 | | +--ro min-value-decimal? decimal64 2460 | | +--rw current-value-decimal? decimal64 2461 | +--rw idle-config 2462 | +--rw heartbeat-interval 2463 | | +--ro max-value? uint16 2464 | | +--ro min-value? uint16 2465 | | +--rw current-value? uint16 2466 | +--rw missing-hb-allowed 2467 | | +--ro max-value? uint16 2468 | | +--ro min-value? uint16 2469 | | +--rw current-value? uint16 2470 | +--rw max-retransmit 2471 | | +--ro max-value? uint16 2472 | | +--ro min-value? uint16 2473 | | +--rw current-value? uint16 2474 | +--rw ack-timeout 2475 | | +--ro max-value-decimal? decimal64 2476 | | +--ro min-value-decimal? decimal64 2477 | | +--rw current-value-decimal? decimal64 2478 | +--rw ack-random-factor 2479 | +--ro max-value-decimal? decimal64 2480 | +--ro min-value-decimal? decimal64 2481 | +--rw current-value-decimal? decimal64 2482 +--:(redirected-signal) 2483 +--ro alt-server string 2484 +--ro alt-server-record* inet:ip-address 2486 5.2. YANG Module 2488 file "ietf-dots-signal-channel@2018-08-16.yang" 2490 module ietf-dots-signal-channel { 2491 yang-version 1.1; 2492 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel"; 2493 prefix signal; 2495 import ietf-inet-types { 2496 prefix inet; 2497 } 2498 import ietf-yang-types { 2499 prefix yang; 2500 } 2501 import ietf-access-control-list { 2502 prefix ietf-acl; 2504 } 2506 organization 2507 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 2508 contact 2509 "WG Web: 2510 WG List: 2512 Editor: Konda, Tirumaleswar Reddy 2513 2515 Editor: Mohamed Boucadair 2516 2518 Author: Prashanth Patil 2519 2521 Author: Andrew Mortensen 2522 2524 Author: Nik Teague 2525 "; 2526 description 2527 "This module contains YANG definition for the signaling 2528 messages exchanged between a DOTS client and a DOTS server. 2530 Copyright (c) 2018 IETF Trust and the persons identified as 2531 authors of the code. All rights reserved. 2533 Redistribution and use in source and binary forms, with or 2534 without modification, is permitted pursuant to, and subject 2535 to the license terms contained in, the Simplified BSD License 2536 set forth in Section 4.c of the IETF Trust's Legal Provisions 2537 Relating to IETF Documents 2538 (http://trustee.ietf.org/license-info). 2540 This version of this YANG module is part of RFC XXXX; see 2541 the RFC itself for full legal notices."; 2543 revision 2018-08-16 { 2544 description 2545 "Initial revision."; 2546 reference 2547 "RFC XXXX: Distributed Denial-of-Service Open Threat 2548 Signaling (DOTS) Signal Channel Specification"; 2549 } 2551 /* 2552 * Groupings 2553 */ 2555 grouping target { 2556 description 2557 "Specifies the targets of the mitigation request."; 2558 leaf-list target-prefix { 2559 type inet:ip-prefix; 2560 description 2561 "IPv4 or IPv6 prefix identifying the target."; 2562 } 2563 list target-port-range { 2564 key "lower-port upper-port"; 2565 description 2566 "Port range. When only lower-port is 2567 present, it represents a single port number."; 2568 leaf lower-port { 2569 type inet:port-number; 2570 mandatory true; 2571 description 2572 "Lower port number of the port range."; 2573 } 2574 leaf upper-port { 2575 type inet:port-number; 2576 must ". >= ../lower-port" { 2577 error-message 2578 "The upper port number must be greater than 2579 or equal to lower port number."; 2580 } 2581 description 2582 "Upper port number of the port range."; 2583 } 2584 } 2585 leaf-list target-protocol { 2586 type uint8; 2587 description 2588 "Identifies the target protocol number. 2590 The value '0' means 'all protocols'. 2592 Values are taken from the IANA protocol registry: 2593 https://www.iana.org/assignments/protocol-numbers/ 2594 protocol-numbers.xhtml 2596 For example, 6 for TCP or 17 for UDP."; 2597 } 2598 leaf-list target-fqdn { 2599 type inet:domain-name; 2600 description 2601 "FQDN identifying the target."; 2602 } 2603 leaf-list target-uri { 2604 type inet:uri; 2605 description 2606 "URI identifying the target."; 2607 } 2608 } 2610 grouping mitigation-scope { 2611 description 2612 "Specifies the scope of the mitigation request."; 2613 list scope { 2614 key "cuid mid"; 2615 description 2616 "The scope of the request."; 2617 leaf cdid { 2618 type string; 2619 description 2620 "The cdid should be included by a server-domain 2621 DOTS gateway to propagate the client domain 2622 identification information from the 2623 gateway's client-facing-side to the gateway's 2624 server-facing-side, and from the gateway's 2625 server-facing-side to the DOTS server. 2627 It may be used by the final DOTS server 2628 for policy enforcement purposes."; 2629 } 2630 leaf cuid { 2631 type string; 2632 description 2633 "A unique identifier that is randomly 2634 generated by a DOTS client to prevent 2635 request collisions. It is expected that the 2636 cuid will remain consistent throughout the 2637 lifetime of the DOTS client."; 2638 } 2639 leaf mid { 2640 type uint32; 2641 description 2642 "Mitigation request identifier. 2644 This identifier must be unique for each mitigation 2645 request bound to the DOTS client."; 2646 } 2647 uses target; 2648 leaf-list alias-name { 2649 type string; 2650 description 2651 "An alias name that points to a resource."; 2652 } 2653 leaf lifetime { 2654 type int32; 2655 units "seconds"; 2656 default "3600"; 2657 description 2658 "Indicates the lifetime of the mitigation request. 2660 A lifetime of '0' in a mitigation request is an 2661 invalid value. 2663 A lifetime of negative one (-1) indicates indefinite 2664 lifetime for the mitigation request."; 2665 } 2666 leaf trigger-mitigation { 2667 type boolean; 2668 default "true"; 2669 description 2670 "If set to 'false', DDoS mitigation will not be 2671 triggered unless the DOTS signal channel 2672 session is lost."; 2673 } 2674 leaf mitigation-start { 2675 type uint64; 2676 config false; 2677 description 2678 "Mitigation start time is represented in seconds 2679 relative to 1970-01-01T00:00:00Z in UTC time."; 2680 } 2681 leaf status { 2682 type enumeration { 2683 enum "attack-mitigation-in-progress" { 2684 value 1; 2685 description 2686 "Attack mitigation setup is in progress (e.g., changing 2687 the network path to re-route the inbound traffic 2688 to DOTS mitigator)."; 2689 } 2690 enum "attack-successfully-mitigated" { 2691 value 2; 2692 description 2693 "Attack is being successfully mitigated (e.g., traffic 2694 is redirected to a DDoS mitigator and attack 2695 traffic is dropped or blackholed)."; 2697 } 2698 enum "attack-stopped" { 2699 value 3; 2700 description 2701 "Attack has stopped and the DOTS client can 2702 withdraw the mitigation request."; 2703 } 2704 enum "attack-exceeded-capability" { 2705 value 4; 2706 description 2707 "Attack has exceeded the mitigation provider 2708 capability."; 2709 } 2710 enum "dots-client-withdrawn-mitigation" { 2711 value 5; 2712 description 2713 "DOTS client has withdrawn the mitigation 2714 request and the mitigation is active but 2715 terminating."; 2716 } 2717 enum "attack-mitigation-terminated" { 2718 value 6; 2719 description 2720 "Attack mitigation is now terminated."; 2721 } 2722 enum "attack-mitigation-withdrawn" { 2723 value 7; 2724 description 2725 "Attack mitigation is withdrawn."; 2726 } 2727 enum "attack-mitigation-signal-loss" { 2728 value 8; 2729 description 2730 "Attack mitigation will be triggered 2731 for the mitigation request only when 2732 the DOTS signal channel session is lost."; 2733 } 2734 } 2735 config false; 2736 description 2737 "Indicates the status of a mitigation request. 2738 It must be included in responses only."; 2739 } 2740 container conflict-information { 2741 config false; 2742 description 2743 "Indicates that a conflict is detected. 2744 Must only be used for responses."; 2746 leaf conflict-status { 2747 type enumeration { 2748 enum "request-inactive-other-active" { 2749 value 1; 2750 description 2751 "DOTS Server has detected conflicting mitigation 2752 requests from different DOTS clients. 2753 This mitigation request is currently inactive 2754 until the conflicts are resolved. Another 2755 mitigation request is active."; 2756 } 2757 enum "request-active" { 2758 value 2; 2759 description 2760 "DOTS Server has detected conflicting mitigation 2761 requests from different DOTS clients. 2762 This mitigation request is currently active."; 2763 } 2764 enum "all-requests-inactive" { 2765 value 3; 2766 description 2767 "DOTS Server has detected conflicting mitigation 2768 requests from different DOTS clients. All 2769 conflicting mitigation requests are inactive."; 2770 } 2771 } 2772 description 2773 "Indicates the conflict status."; 2774 } 2775 leaf conflict-cause { 2776 type enumeration { 2777 enum "overlapping-targets" { 2778 value 1; 2779 description 2780 "Overlapping targets. conflict-scope provides 2781 more details about the exact conflict."; 2782 } 2783 enum "conflict-with-whitelist" { 2784 value 2; 2785 description 2786 "Conflicts with an existing white list. 2788 This code is returned when the DDoS mitigation 2789 detects that some of the source addresses/prefixes 2790 listed in the white list ACLs are actually 2791 attacking the target."; 2792 } 2793 enum "cuid-collision" { 2794 value 3; 2795 description 2796 "Conflicts with the cuid used by another 2797 DOTS client."; 2798 } 2799 } 2800 description 2801 "Indicates the cause of the conflict."; 2802 } 2803 leaf retry-timer { 2804 type uint32; 2805 units "seconds"; 2806 description 2807 "The DOTS client must not re-send the 2808 same request that has a conflict before the expiry of 2809 this timer."; 2810 } 2811 container conflict-scope { 2812 description 2813 "Provides more information about the conflict scope."; 2814 uses target { 2815 when "../conflict-cause = 'overlapping-targets'"; 2816 } 2817 leaf-list alias-name { 2818 when "../../conflict-cause = 'overlapping-targets'"; 2819 type string; 2820 description 2821 "Conflicting alias-name."; 2822 } 2823 list acl-list { 2824 when "../../conflict-cause = 'conflict-with-whitelist'"; 2825 key "acl-name"; 2826 description 2827 "List of conflicting ACLs as defined in the DOTS data 2828 channel. These ACLs are uniquely defined by 2829 cuid and acl-name."; 2830 leaf acl-name { 2831 type leafref { 2832 path "/ietf-acl:acls/ietf-acl:acl/" + 2833 "ietf-acl:name"; 2834 } 2835 description 2836 "Reference to the conflicting ACL name bound to 2837 a DOTS client."; 2838 } 2839 leaf acl-type { 2840 type leafref { 2841 path "/ietf-acl:acls/ietf-acl:acl/" + 2842 "ietf-acl:type"; 2843 } 2844 description 2845 "Reference to the conflicting ACL type bound to 2846 a DOTS client."; 2847 } 2848 } 2849 leaf mid { 2850 when "../../conflict-cause = 'overlapping-targets'"; 2851 type leafref { 2852 path "../../../mid"; 2853 } 2854 description 2855 "Reference to the conflicting 'mid' bound to 2856 the same DOTS client."; 2857 } 2858 } 2859 } 2860 leaf bytes-dropped { 2861 type yang:zero-based-counter64; 2862 units "bytes"; 2863 config false; 2864 description 2865 "The total dropped byte count for the mitigation 2866 request since the attack mitigation is triggered. 2867 The count wraps around when it reaches the maximum value 2868 of counter64 for dropped bytes."; 2869 } 2870 leaf bps-dropped { 2871 type yang:zero-based-counter64; 2872 config false; 2873 description 2874 "The average number of dropped bits per second for 2875 the mitigation request since the attack 2876 mitigation is triggered. This should be a 2877 five-minute average."; 2878 } 2879 leaf pkts-dropped { 2880 type yang:zero-based-counter64; 2881 config false; 2882 description 2883 "The total number of dropped packet count for the 2884 mitigation request since the attack mitigation is 2885 triggered. The count wraps around when it reaches 2886 the maximum value of counter64 for dropped packets."; 2887 } 2888 leaf pps-dropped { 2889 type yang:zero-based-counter64; 2890 config false; 2891 description 2892 "The average number of dropped packets per second 2893 for the mitigation request since the attack 2894 mitigation is triggered. This should be a 2895 five-minute average."; 2896 } 2897 leaf attack-status { 2898 type enumeration { 2899 enum "under-attack" { 2900 value 1; 2901 description 2902 "The DOTS client determines that it is still under 2903 attack."; 2904 } 2905 enum "attack-successfully-mitigated" { 2906 value 2; 2907 description 2908 "The DOTS client determines that the attack is 2909 successfully mitigated."; 2910 } 2911 } 2912 description 2913 "Indicates the status of an attack as seen by the 2914 DOTS client."; 2915 } 2916 } 2917 } 2919 grouping config-parameters { 2920 description 2921 "Subset of DOTS signal channel session configuration."; 2922 container heartbeat-interval { 2923 description 2924 "DOTS agents regularly send heartbeats to each other 2925 after mutual authentication is successfully 2926 completed in order to keep the DOTS signal channel 2927 open."; 2928 leaf max-value { 2929 type uint16; 2930 units "seconds"; 2931 config false; 2932 description 2933 "Maximum acceptable heartbeat-interval value."; 2934 } 2935 leaf min-value { 2936 type uint16; 2937 units "seconds"; 2938 config false; 2939 description 2940 "Minimum acceptable heartbeat-interval value."; 2941 } 2942 leaf current-value { 2943 type uint16; 2944 units "seconds"; 2945 default "30"; 2946 description 2947 "Current heartbeat-interval value. 2949 '0' means that heartbeat mechanism is deactivated."; 2950 } 2951 } 2952 container missing-hb-allowed { 2953 description 2954 "Maximum number of missing heartbeats allowed."; 2955 leaf max-value { 2956 type uint16; 2957 config false; 2958 description 2959 "Maximum acceptable missing-hb-allowed value."; 2960 } 2961 leaf min-value { 2962 type uint16; 2963 config false; 2964 description 2965 "Minimum acceptable missing-hb-allowed value."; 2966 } 2967 leaf current-value { 2968 type uint16; 2969 default "5"; 2970 description 2971 "Current missing-hb-allowed value."; 2972 } 2973 } 2974 container max-retransmit { 2975 description 2976 "Maximum number of retransmissions of a Confirmable 2977 message."; 2978 leaf max-value { 2979 type uint16; 2980 config false; 2981 description 2982 "Maximum acceptable max-retransmit value."; 2983 } 2984 leaf min-value { 2985 type uint16; 2986 config false; 2987 description 2988 "Minimum acceptable max-retransmit value."; 2989 } 2990 leaf current-value { 2991 type uint16; 2992 default "3"; 2993 description 2994 "Current max-retransmit value."; 2995 } 2996 } 2997 container ack-timeout { 2998 description 2999 "Initial retransmission timeout value."; 3000 leaf max-value-decimal { 3001 type decimal64 { 3002 fraction-digits 2; 3003 } 3004 units "seconds"; 3005 config false; 3006 description 3007 "Maximum ack-timeout value."; 3008 } 3009 leaf min-value-decimal { 3010 type decimal64 { 3011 fraction-digits 2; 3012 } 3013 units "seconds"; 3014 config false; 3015 description 3016 "Minimum ack-timeout value."; 3017 } 3018 leaf current-value-decimal { 3019 type decimal64 { 3020 fraction-digits 2; 3021 } 3022 units "seconds"; 3023 default "2"; 3024 description 3025 "Current ack-timeout value."; 3026 } 3027 } 3028 container ack-random-factor { 3029 description 3030 "Random factor used to influence the timing of 3031 retransmissions."; 3032 leaf max-value-decimal { 3033 type decimal64 { 3034 fraction-digits 2; 3035 } 3036 config false; 3037 description 3038 "Maximum acceptable ack-random-factor value."; 3039 } 3040 leaf min-value-decimal { 3041 type decimal64 { 3042 fraction-digits 2; 3043 } 3044 config false; 3045 description 3046 "Minimum acceptable ack-random-factor value."; 3047 } 3048 leaf current-value-decimal { 3049 type decimal64 { 3050 fraction-digits 2; 3051 } 3052 default "1.5"; 3053 description 3054 "Current ack-random-factor value."; 3055 } 3056 } 3057 } 3059 grouping signal-config { 3060 description 3061 "DOTS signal channel session configuration."; 3062 leaf sid { 3063 type uint32; 3064 mandatory true; 3065 description 3066 "An identifier for the DOTS signal channel 3067 session configuration data."; 3068 } 3069 container mitigating-config { 3070 description 3071 "Configuration parameters to use when a mitigation 3072 is active."; 3073 uses config-parameters; 3074 } 3075 container idle-config { 3076 description 3077 "Configuration parameters to use when no mitigation 3078 is active."; 3079 uses config-parameters; 3080 } 3081 } 3082 grouping redirected-signal { 3083 description 3084 "Grouping for the redirected signaling."; 3085 leaf alt-server { 3086 type string; 3087 config false; 3088 mandatory true; 3089 description 3090 "FQDN of an alternate server."; 3091 } 3092 leaf-list alt-server-record { 3093 type inet:ip-address; 3094 config false; 3095 description 3096 "List of records for the alternate server."; 3097 } 3098 } 3100 /* 3101 * Main Container for DOTS Signal Channel 3102 */ 3104 container dots-signal { 3105 description 3106 "Main container for DOTS signal message. 3108 A DOTS signal message can be a mitigation, a configuration, 3109 or a redirected signal message."; 3110 choice message-type { 3111 description 3112 "Can be a mitigation, a configuration, or a redirect 3113 message."; 3114 case mitigation-scope { 3115 description 3116 "Mitigation scope of a mitigation message."; 3117 uses mitigation-scope; 3118 } 3119 case signal-config { 3120 description 3121 "Configuration message."; 3122 uses signal-config; 3123 } 3124 case redirected-signal { 3125 description 3126 "Redirected signaling."; 3127 uses redirected-signal; 3128 } 3129 } 3131 } 3132 } 3133 3135 6. Mapping Parameters to CBOR 3137 All parameters in the payload of the DOTS signal channel MUST be 3138 mapped to CBOR types as shown in Table 4 and are assigned an integer 3139 key to save space. The CBOR key values are divided into two types: 3140 comprehension-required and comprehension-optional. DOTS agents can 3141 safely ignore comprehension-optional values they don't understand, 3142 but cannot successfully process a request if it contains 3143 comprehension-required values that are not understood. The 4.00 3144 response SHOULD include a diagnostic payload describing the unknown 3145 comprehension-required CBOR key values. The initial set of CBOR key 3146 values defined in this specification are of type comprehension- 3147 required. 3149 +----------------------+-------------+-----+---------------+--------+ 3150 | Parameter Name | YANG | CBOR| CBOR Major | JSON | 3151 | | Type | Key | Type & | Type | 3152 | | | | Information | | 3153 +----------------------+-------------+-----+---------------+--------+ 3154 | ietf-dots-signal-cha | | | | | 3155 | nnel:mitigation-scope| container | 1 | 5 map | Object | 3156 | scope | list | 2 | 4 array | Array | 3157 | cdid | string | 3 | 3 text string | String | 3158 | cuid | string | 4 | 3 text string | String | 3159 | mid | uint32 | 5 | 0 unsigned | Number | 3160 | target-prefix | leaf-list | 6 | 4 array | Array | 3161 | | inet: | | | | 3162 | | ip-prefix | | 3 text string | String | 3163 | target-port-range | list | 7 | 4 array | Array | 3164 | lower-port | inet: | | | | 3165 | | port-number| 8 | 0 unsigned | Number | 3166 | upper-port | inet: | | | | 3167 | | port-number| 9 | 0 unsigned | Number | 3168 | target-protocol | leaf-list | 10 | 4 array | Array | 3169 | | uint8 | | 0 unsigned | Number | 3170 | target-fqdn | leaf-list | 11 | 4 array | Array | 3171 | | inet: | | | | 3172 | | domain-name| | 3 text string | String | 3173 | target-uri | leaf-list | 12 | 4 array | Array | 3174 | | inet:uri | | 3 text string | String | 3175 | alias-name | leaf-list | 13 | 4 array | Array | 3176 | | string | | 3 text string | String | 3177 | lifetime | int32 | 14 | 0 unsigned | Number | 3178 | | | | 1 negative | Number | 3179 | mitigation-start | uint64 | 15 | 0 unsigned | String | 3180 | status | enumeration | 16 | 0 unsigned | String | 3181 | conflict-information | container | 17 | 5 map | Object | 3182 | conflict-status | enumeration | 18 | 0 unsigned | String | 3183 | conflict-cause | enumeration | 19 | 0 unsigned | String | 3184 | retry-timer | uint32 | 20 | 0 unsigned | Number | 3185 | conflict-scope | container | 21 | 5 map | Object | 3186 | acl-list | list | 22 | 4 array | Array | 3187 | acl-name | leafref | 23 | 3 text string | String | 3188 | acl-type | leafref | 24 | 3 text string | String | 3189 | bytes-dropped | yang:zero- | | | | 3190 | | based- | | | | 3191 | | counter64 | 25 | 0 unsigned | String | 3192 | bps-dropped | yang:zero- | | | | 3193 | | based- | | | | 3194 | | counter64 | 26 | 0 unsigned | String | 3195 | pkts-dropped | yang:zero- | | | | 3196 | | based- | | | | 3197 | | counter64 | 27 | 0 unsigned | String | 3198 | pps-dropped | yang:zero- | | | | 3199 | | based- | | | | 3200 | | counter64 | 28 | 0 unsigned | String | 3201 | attack-status | enumeration | 29 | 0 unsigned | String | 3202 | ietf-dots-signal- | | | | | 3203 | channel:signal-config| container | 30 | 5 map | Object | 3204 | sid | uint32 | 31 | 0 unsigned | Number | 3205 | mitigating-config | container | 32 | 5 map | Object | 3206 | heartbeat-interval | container | 33 | 5 map | Object | 3207 | max-value | uint16 | 34 | 0 unsigned | Number | 3208 | min-value | uint16 | 35 | 0 unsigned | Number | 3209 | current-value | uint16 | 36 | 0 unsigned | Number | 3210 | missing-hb-allowed | container | 37 | 5 map | Object | 3211 | max-retransmit | container | 38 | 5 map | Object | 3212 | ack-timeout | container | 39 | 5 map | Object | 3213 | ack-random-factor | container | 40 | 5 map | Object | 3214 | max-value-decimal | decimal64 | 41 | 6 tag 4 | | 3215 | | | | [-2, integer]| String | 3216 | min-value-decimal | decimal64 | 42 | 6 tag 4 | | 3217 | | | | [-2, integer]| String | 3218 | current-value-decimal| decimal64 | 43 | 6 tag 4 | | 3219 | | | | [-2, integer]| String | 3220 | idle-config | container | 44 | 5 map | Object | 3221 | trigger-mitigation | boolean | 45 | 7 bits 20 | False | 3222 | | | | 7 bits 21 | True | 3223 | ietf-dots-signal-cha | | | | | 3224 |nnel:redirected-signal| container | 46 | 5 map | Object | 3225 | alt-server | string | 47 | 3 text string | String | 3226 | alt-server-record | leaf-list | 48 | 4 array | Array | 3227 | | inet: | | | | 3228 | | ip-address | | 3 text string | String | 3229 +----------------------+-------------+-----+---------------+--------+ 3231 Table 4: CBOR Mappings Used in DOTS Signal Channel Messages 3233 7. (D)TLS Protocol Profile and Performance Considerations 3235 7.1. (D)TLS Protocol Profile 3237 This section defines the (D)TLS protocol profile of DOTS signal 3238 channel over (D)TLS and DOTS data channel over TLS. 3240 There are known attacks on (D)TLS, such as man-in-the-middle and 3241 protocol downgrade attacks. These are general attacks on (D)TLS and, 3242 as such, they are not specific to DOTS over (D)TLS; refer to the 3243 (D)TLS RFCs for discussion of these security issues. DOTS agents 3244 MUST adhere to the (D)TLS implementation recommendations and security 3245 considerations of [RFC7525] except with respect to (D)TLS version. 3246 Since DOTS signal channel encryption relies upon (D)TLS is virtually 3247 a green-field deployment, DOTS agents MUST implement only (D)TLS 1.2 3248 or later. 3250 When a DOTS client is configured with a domain name of the DOTS 3251 server, and connects to its configured DOTS server, the server may 3252 present it with a PKIX certificate. In order to ensure proper 3253 authentication, a DOTS client MUST verify the entire certification 3254 path per [RFC5280]. The DOTS client additionally uses [RFC6125] 3255 validation techniques to compare the domain name with the certificate 3256 provided. 3258 A key challenge to deploying DOTS is the provisioning of DOTS 3259 clients, including the distribution of keying material to DOTS 3260 clients to enable the required mutual authentication of DOTS agents. 3261 EST defines a method of certificate enrollment by which domains 3262 operating DOTS servers may provide DOTS clients with all the 3263 necessary cryptographic keying material, including a private key and 3264 a certificate to authenticate themselves. One deployment option is 3265 DOTS clients behave as EST clients for certificate enrollment from an 3266 EST server provisioned by the mitigation provider. This document 3267 does not specify which EST mechanism the DOTS client uses to achieve 3268 initial enrollment. 3270 The Server Name Indication (SNI) extension [RFC6066] defines a 3271 mechanism for a client to tell a (D)TLS server the name of the server 3272 it wants to contact. This is a useful extension for hosting 3273 environments where multiple virtual servers are reachable over a 3274 single IP address. The DOTS client may or may not know if it is 3275 interacting with a DOTS server in a virtual server hosting 3276 environment, so the DOTS client SHOULD include the DOTS server FQDN 3277 in the SNI extension. 3279 Implementations compliant with this profile MUST implement all of the 3280 following items: 3282 o DTLS record replay detection (Section 3.3 of [RFC6347]) to protect 3283 against replay attacks. 3285 o DTLS session resumption without server-side state to resume 3286 session and convey the DOTS signal. 3288 o Raw public keys [RFC7250] or PSK handshake [RFC4279] with (EC)DHE 3289 key exchange which reduces the size of the ServerHello, and can be 3290 used by DOTS agents that cannot obtain certificates. 3292 Implementations compliant with this profile SHOULD implement all of 3293 the following items to reduce the delay required to deliver a DOTS 3294 signal channel message: 3296 o TLS False Start [RFC7918] which reduces round-trips by allowing 3297 the TLS second flight of messages (ChangeCipherSpec) to also 3298 contain the DOTS signal. 3300 o Cached Information Extension [RFC7924] which avoids transmitting 3301 the server's certificate and certificate chain if the client has 3302 cached that information from a previous TLS handshake. 3304 o TCP Fast Open [RFC7413] can reduce the number of round-trips to 3305 convey DOTS signal channel message. 3307 7.2. (D)TLS 1.3 Considerations 3309 TLS 1.3 provides critical latency improvements for connection 3310 establishment over TLS 1.2. The DTLS 1.3 protocol 3311 [I-D.ietf-tls-dtls13] is based upon the TLS 1.3 protocol and provides 3312 equivalent security guarantees. (D)TLS 1.3 provides two basic 3313 handshake modes the DOTS signal channel can take advantage of: 3315 o A full handshake mode in which a DOTS client can send a DOTS 3316 mitigation request message after one round trip and the DOTS 3317 server immediately responds with a DOTS mitigation response. This 3318 assumes no packet loss is experienced. 3320 o 0-RTT mode in which the DOTS client can authenticate itself and 3321 send DOTS mitigation request messages in the first message, thus 3322 reducing handshake latency. 0-RTT only works if the DOTS client 3323 has previously communicated with that DOTS server, which is very 3324 likely with the DOTS signal channel. 3326 The DOTS client has to establish a (D)TLS session with the DOTS 3327 server during peacetime and share a PSK. 3329 During a DDoS attack, the DOTS client can use the (D)TLS session 3330 to convey the DOTS mitigation request message and, if there is no 3331 response from the server after multiple retries, the DOTS client 3332 can resume the (D)TLS session in 0-RTT mode using PSK. 3334 Section 8 of [RFC8446] discusses some mechanisms to implement to 3335 limit the impact of replay attacks on 0-RTT data. If the DOTS 3336 server accepts 0-RTT, it MUST implement one of these mechanisms. 3337 A DOTS server can reject 0-RTT by sending a TLS HelloRetryRequest. 3339 A simplified TLS 1.3 handshake with 0-RTT DOTS mitigation request 3340 message exchange is shown in Figure 24. 3342 DOTS Client DOTS Server 3344 ClientHello 3345 (Finished) 3346 (0-RTT DOTS signal message) 3347 (end_of_early_data) --------> 3348 ServerHello 3349 {EncryptedExtensions} 3350 {ServerConfiguration} 3351 {Certificate} 3352 {CertificateVerify} 3353 {Finished} 3354 <-------- [DOTS signal message] 3355 {Finished} --------> 3357 [DOTS signal message] <-------> [DOTS signal message] 3359 Figure 24: TLS 1.3 Handshake with 0-RTT 3361 7.3. MTU and Fragmentation 3363 To avoid DOTS signal message fragmentation and the subsequent 3364 decreased probability of message delivery, DOTS agents MUST ensure 3365 that the DTLS record MUST fit within a single datagram. If the path 3366 MTU is not known to the DOTS server, an IP MTU of 1280 bytes SHOULD 3367 be assumed. If UDP is used to convey the DOTS signal messages then 3368 the DOTS client must consider the amount of record expansion expected 3369 by the DTLS processing when calculating the size of CoAP message that 3370 fits within the path MTU. Path MTU MUST be greater than or equal to 3372 [CoAP message size + DTLS overhead of 13 octets + authentication 3373 overhead of the negotiated DTLS cipher suite + block padding] 3374 (Section 4.1.1.1 of [RFC6347]). If the request size exceeds the path 3375 MTU then the DOTS client MUST split the DOTS signal into separate 3376 messages, for example the list of addresses in the 'target-prefix' 3377 parameter could be split into multiple lists and each list conveyed 3378 in a new PUT request. 3380 Implementation Note: DOTS choice of message size parameters works 3381 well with IPv6 and with most of today's IPv4 paths. However, with 3382 IPv4, it is harder to safely make sure that there is no IP 3383 fragmentation. If IPv4 path MTU is unknown, implementations may want 3384 to limit themselves to more conservative IPv4 datagram sizes such as 3385 576 bytes, as per [RFC0791]. IP packets whose size does not exceed 3386 576 bytes should never need to be fragmented: therefore, sending a 3387 maximum of 500 bytes of DOTS signal over a UDP datagram will 3388 generally avoid IP fragmentation. 3390 8. Mutual Authentication of DOTS Agents & Authorization of DOTS Clients 3392 (D)TLS based upon client certificate can be used for mutual 3393 authentication between DOTS agents. If a DOTS gateway is involved, 3394 DOTS clients and DOTS gateways MUST perform mutual authentication; 3395 only authorized DOTS clients are allowed to send DOTS signals to a 3396 DOTS gateway. The DOTS gateway and the DOTS server MUST perform 3397 mutual authentication; a DOTS server only allows DOTS signal channel 3398 messages from an authorized DOTS gateway, thereby creating a two-link 3399 chain of transitive authentication between the DOTS client and the 3400 DOTS server. 3402 The DOTS server SHOULD support certificate-based client 3403 authentication. The DOTS client SHOULD respond to the DOTS server's 3404 TLS certificate request message with the PKIX certificate held by the 3405 DOTS client. DOTS client certificate validation MUST be performed as 3406 per [RFC5280] and the DOTS client certificate MUST conform to the 3407 [RFC5280] certificate profile. If a DOTS client does not support TLS 3408 client certificate authentication, it MUST support pre-shared key 3409 based or raw public key based client authentication. 3411 +-----------------------------------------------+ 3412 | example.com domain +---------+ | 3413 | | AAA | | 3414 | +---------------+ | Server | | 3415 | | Application | +------+--+ | 3416 | | server +<-----------------+ ^ | 3417 | | (DOTS client) | | | | 3418 | +---------------+ | | | 3419 | V V | example.net domain 3420 | +-----+----+--+ | +---------------+ 3421 | +--------------+ | | | | | 3422 | | Guest +<-----x----->+ DOTS +<------>+ DOTS | 3423 | | (DOTS client)| | gateway | | | server | 3424 | +--------------+ | | | | | 3425 | +----+--------+ | +---------------+ 3426 | ^ | 3427 | | | 3428 | +----------------+ | | 3429 | | DDoS detector | | | 3430 | | (DOTS client) +<---------------+ | 3431 | +----------------+ | 3432 +-----------------------------------------------+ 3434 Figure 25: Example of Authentication and Authorization of DOTS Agents 3436 In the example depicted in Figure 25, the DOTS gateway and DOTS 3437 clients within the 'example.com' domain mutually authenticate. After 3438 the DOTS gateway validates the identity of a DOTS client, it 3439 communicates with the AAA server in the 'example.com' domain to 3440 determine if the DOTS client is authorized to request DDoS 3441 mitigation. If the DOTS client is not authorized, a 4.01 3442 (Unauthorized) is returned in the response to the DOTS client. In 3443 this example, the DOTS gateway only allows the application server and 3444 DDoS attack detector to request DDoS mitigation, but does not permit 3445 the user of type 'guest' to request DDoS mitigation. 3447 Also, DOTS gateways and servers located in different domains MUST 3448 perform mutual authentication (e.g., using certificates). A DOTS 3449 server will only allow a DOTS gateway with a certificate for a 3450 particular domain to request mitigation for that domain. In 3451 reference to Figure 25, the DOTS server only allows the DOTS gateway 3452 to request mitigation for 'example.com' domain and not for other 3453 domains. 3455 9. IANA Considerations 3457 This specification registers a service port (Section 9.1), a URI 3458 suffix in the Well-Known URIs registry (Section 9.2), and a YANG 3459 module (Section 9.7). It also creates a registry for mappings to 3460 CBOR (Section 9.3). 3462 9.1. DOTS Signal Channel UDP and TCP Port Number 3464 IANA is requested to assign the port number TBD to the DOTS signal 3465 channel protocol for both UDP and TCP from the "Service Name and 3466 Transport Protocol Port Number Registry" available at 3467 https://www.iana.org/assignments/service-names-port-numbers/service- 3468 names-port-numbers.xhtml. 3470 The assignment of port number 4646 is strongly suggested, as 4646 is 3471 the ASCII decimal value for ".." (DOTS). 3473 9.2. Well-Known 'dots' URI 3475 This document requests IANA to register the 'dots' well-known URI 3476 (Table 5) in the Well-Known URIs registry 3477 (https://www.iana.org/assignments/well-known-uris/well-known- 3478 uris.xhtml) as defined by [RFC5785]: 3480 +----------+----------------+---------------------+-----------------+ 3481 | URI | Change | Specification | Related | 3482 | suffix | controller | document(s) | information | 3483 +----------+----------------+---------------------+-----------------+ 3484 | dots | IETF | [RFCXXXX] | None | 3485 +----------+----------------+---------------------+-----------------+ 3487 Table 5: 'dots' well-known URI 3489 9.3. DOTS Signal Channel CBOR Mappings Registry 3491 The DOTS signal channel protocol is extensible to support new 3492 parameters and instructions for doing it are discussed below: 3494 The document requests IANA to create a new registry, entitled "DOTS 3495 Signal Channel CBOR Mappings Registry". The structure of this 3496 registry is provided in Section 9.3.1. Registration requests are 3497 evaluated using the criteria described in the CBOR Key Value 3498 instructions in the registration template below after a three-week 3499 review period on the dots-signal-reg-review@ietf.org mailing list, on 3500 the advice of one or more Designated Experts [RFC8126]. However, to 3501 allow for the allocation of values prior to publication, the 3502 Designated Experts may approve registration once they are satisfied 3503 that such a specification will be published. [[ Note to the RFC 3504 Editor: The name of the mailing list should be determined in 3505 consultation with the IESG and IANA. Suggested name: dots-signal- 3506 reg-review@ietf.org. ]] 3508 Registration requests sent to the mailing list for review should use 3509 an appropriate subject (e.g., "Request to register parameter: 3510 example"). Registration requests that are undetermined for a period 3511 longer than 21 days can be brought to the IESG's attention (using the 3512 iesg@ietf.org mailing list) for resolution. 3514 Criteria that should be applied by the Designated Experts includes 3515 determining whether the proposed registration duplicates existing 3516 functionality, whether it is likely to be of general applicability or 3517 whether it is useful only for a single application, and whether the 3518 registration description is clear. 3520 IANA must only accept registry updates from the Designated Experts 3521 and should direct all requests for registration to the review mailing 3522 list. 3524 It is suggested that multiple Designated Experts be appointed who are 3525 able to represent the perspectives of different applications using 3526 this specification in order to enable broadly informed review of 3527 registration decisions. In cases where a registration decision could 3528 be perceived as creating a conflict of interest for a particular 3529 Expert, that Expert should defer to the judgment of the other 3530 Experts. 3532 The registry is initially populated with the values in Table 6. 3534 9.3.1. Registration Template 3536 Parameter name: 3537 Parameter name as used in the DOTS signal channel. 3539 CBOR Key Value: 3540 Key value for the parameter. The key value MUST be an integer in 3541 the 1-65535 range. The key values of the comprehension-required 3542 range (0x0001 - 0x3FFF) and of the comprehension-optional range 3543 (0x8000 - 0xBFFF) are assigned by IETF Review [RFC8126]. The key 3544 values of the comprehension-optional range (0x4000 - 0x7FFF) are 3545 assigned by Designated Expert [RFC8126] and of the comprehension- 3546 optional range (0xC000 - 0xFFFF) are reserved for Private Use 3547 [RFC8126]. 3549 CBOR Major Type: 3550 CBOR Major type and optional tag for the parameter. 3552 Change Controller: 3553 For Standards Track RFCs, list the "IESG". For others, give the 3554 name of the responsible party. Other details (e.g., postal 3555 address, email address, home page URI) may also be included. 3557 Specification Document(s): 3558 Reference to the document or documents that specify the parameter, 3559 preferably including URIs that can be used to retrieve copies of 3560 the documents. An indication of the relevant sections may also be 3561 included but is not required. 3563 9.3.2. Initial Registry Content 3565 +----------------------+-------+-------+------------+---------------+ 3566 | Parameter Name | CBOR | CBOR | Change | Specification | 3567 | | Key | Major | Controller | Document(s) | 3568 | | Value | Type | | | 3569 +----------------------+-------+-------+------------+---------------+ 3570 | ietf-dots-signal-chan| 1 | 5 | IESG | [RFCXXXX] | 3571 | nel:mitigation-scope | | | | | 3572 | scope | 2 | 4 | IESG | [RFCXXXX] | 3573 | cdid | 3 | 3 | IESG | [RFCXXXX] | 3574 | cuid | 4 | 3 | IESG | [RFCXXXX] | 3575 | mid | 5 | 0 | IESG | [RFCXXXX] | 3576 | target-prefix | 6 | 4 | IESG | [RFCXXXX] | 3577 | target-port-range | 7 | 4 | IESG | [RFCXXXX] | 3578 | lower-port | 8 | 0 | IESG | [RFCXXXX] | 3579 | upper-port | 9 | 0 | IESG | [RFCXXXX] | 3580 | target-protocol | 10 | 4 | IESG | [RFCXXXX] | 3581 | target-fqdn | 11 | 4 | IESG | [RFCXXXX] | 3582 | target-uri | 12 | 4 | IESG | [RFCXXXX] | 3583 | alias-name | 13 | 4 | IESG | [RFCXXXX] | 3584 | lifetime | 14 | 0/1 | IESG | [RFCXXXX] | 3585 | mitigation-start | 15 | 0 | IESG | [RFCXXXX] | 3586 | status | 16 | 0 | IESG | [RFCXXXX] | 3587 | conflict-information | 17 | 5 | IESG | [RFCXXXX] | 3588 | conflict-status | 18 | 0 | IESG | [RFCXXXX] | 3589 | conflict-cause | 19 | 0 | IESG | [RFCXXXX] | 3590 | retry-timer | 20 | 0 | IESG | [RFCXXXX] | 3591 | conflict-scope | 21 | 5 | IESG | [RFCXXXX] | 3592 | acl-list | 22 | 4 | IESG | [RFCXXXX] | 3593 | acl-name | 23 | 3 | IESG | [RFCXXXX] | 3594 | acl-type | 24 | 3 | IESG | [RFCXXXX] | 3595 | bytes-dropped | 25 | 0 | IESG | [RFCXXXX] | 3596 | bps-dropped | 26 | 0 | IESG | [RFCXXXX] | 3597 | pkts-dropped | 27 | 0 | IESG | [RFCXXXX] | 3598 | pps-dropped | 28 | 0 | IESG | [RFCXXXX] | 3599 | attack-status | 29 | 0 | IESG | [RFCXXXX] | 3600 | ietf-dots-signal- | 30 | 5 | IESG | [RFCXXXX] | 3601 | channel:signal-config| | | | | 3602 | sid | 31 | 0 | IESG | [RFCXXXX] | 3603 | mitigating-config | 32 | 5 | IESG | [RFCXXXX] | 3604 | heartbeat-interval | 33 | 5 | IESG | [RFCXXXX] | 3605 | min-value | 34 | 0 | IESG | [RFCXXXX] | 3606 | max-value | 35 | 0 | IESG | [RFCXXXX] | 3607 | current-value | 36 | 0 | IESG | [RFCXXXX] | 3608 | missing-hb-allowed | 37 | 5 | IESG | [RFCXXXX] | 3609 | max-retransmit | 38 | 5 | IESG | [RFCXXXX] | 3610 | ack-timeout | 39 | 5 | IESG | [RFCXXXX] | 3611 | ack-random-factor | 40 | 5 | IESG | [RFCXXXX] | 3612 | min-value-decimal | 41 | 6tag4 | IESG | [RFCXXXX] | 3613 | max-value-decimal | 42 | 6tag4 | IESG | [RFCXXXX] | 3614 | current-value- | 43 | 6tag4 | IESG | [RFCXXXX] | 3615 | decimal | | | | | 3616 | idle-config | 44 | 5 | IESG | [RFCXXXX] | 3617 | trigger-mitigation | 45 | 7 | IESG | [RFCXXXX] | 3618 | ietf-dots-signal-chan| 46 | 5 | IESG | [RFCXXXX] | 3619 | nel:redirected-signal| | | | | 3620 | alt-server | 47 | 3 | IESG | [RFCXXXX] | 3621 | alt-server-record | 48 | 4 | IESG | [RFCXXXX] | 3622 +----------------------+-------+-------+------------+---------------+ 3624 Table 6: Initial DOTS Signal Channel CBOR Mappings Registry 3626 9.4. Media Type Registration 3628 This section registers the "application/dots+cbor" media type in the 3629 "Media Types" registry [IANA.MediaTypes] in the manner described in 3630 RFC 6838 [RFC6838], which can be used to indicate that the content is 3631 a DOTS signal channel object. 3633 9.4.1. Registry Contents 3635 o Type name: application 3636 o Subtype name: dots+cbor 3637 o Required parameters: N/A 3638 o Optional parameters: N/A 3639 o Encoding considerations: binary 3640 o Security considerations: See the Security Considerations section 3641 of [RFCXXXX] 3642 o Interoperability considerations: N/A 3643 o Published specification: [RFCXXXX] 3644 o Applications that use this media type: DOTS agents sending DOTS 3645 messages over CoAP over (D)TLS. 3646 o Fragment identifier considerations: N/A 3647 o Additional information: 3649 Magic number(s): N/A 3650 File extension(s): N/A 3651 Macintosh file type code(s): N/A 3652 o Person & email address to contact for further information: 3653 IESG, iesg@ietf.org 3654 o Intended usage: COMMON 3655 o Restrictions on usage: none 3656 o Author: Tirumaleswar Reddy, kondtir@gmail.com 3657 o Change controller: IESG 3658 o Provisional registration? No 3660 9.5. CoAP Content-Formats Registration 3662 This section registers the CoAP Content-Format ID for the 3663 "application/dots+cbor" media type in the "CoAP Content-Formats" 3664 registry [IANA.CoAP.Content-Formats]. 3666 9.5.1. Registry Contents 3668 o Media Type: application/dots+cbor 3669 o Encoding: - 3670 o Id: TBD 3671 o Reference: [RFCXXXX] 3673 9.6. CBOR Tag registration 3675 This section defines the DOTS CBOR tag as another means for 3676 applications to declare that a CBOR data structure is a DOTS signal 3677 channel object. Its use is optional and is intended for use in cases 3678 in which this information would not otherwise be known. DOTS CBOR 3679 tag is not required for DOTS signal channel protocol version "v1.0". 3680 If present, the DOTS tag MUST prefix a DOTS signal channel object. 3682 This section registers the DOTS signal channel CBOR tag in the "CBOR 3683 Tags" registry [IANA.CBOR.Tags]. 3685 9.6.1. Registry Contents 3687 o CBOR Tag: TBD (please assign the same value as the Content-Format) 3688 o Data Item: DDoS Open Threat Signaling (DOTS) signal channel object 3689 o Semantics: DDoS Open Threat Signaling (DOTS) signal channel 3690 object, as defined in [RFCXXXX] 3691 o Description of Semantics: [RFCXXXX] 3692 o Point of Contact: Tirumaleswar Reddy, kondtir@gmail.com 3694 9.7. DOTS Signal Channel YANG Module 3696 This document requests IANA to register the following URI in the 3697 "IETF XML Registry" [RFC3688]: 3699 URI: urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel 3700 Registrant Contact: The IESG. 3701 XML: N/A; the requested URI is an XML namespace. 3703 This document requests IANA to register the following YANG module in 3704 the "YANG Module Names" registry [RFC7950]. 3706 name: ietf-signal 3707 namespace: urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel 3708 prefix: signal 3709 reference: RFC XXXX 3711 10. Security Considerations 3713 Authenticated encryption MUST be used for data confidentiality and 3714 message integrity. The interaction between the DOTS agents requires 3715 Datagram Transport Layer Security (DTLS) and Transport Layer Security 3716 (TLS) with a cipher suite offering confidentiality protection and the 3717 guidance given in [RFC7525] MUST be followed to avoid attacks on 3718 (D)TLS. The (D)TLS protocol profile for DOTS signal channel is 3719 specified in Section 7. 3721 If TCP is used between DOTS agents, an attacker may be able to inject 3722 RST packets, bogus application segments, etc., regardless of whether 3723 TLS authentication is used. Because the application data is TLS 3724 protected, this will not result in the application receiving bogus 3725 data, but it will constitute a DoS on the connection. This attack 3726 can be countered by using TCP-AO [RFC5925]. If TCP-AO is used, then 3727 any bogus packets injected by an attacker will be rejected by the 3728 TCP-AO integrity check and therefore will never reach the TLS layer. 3730 Rate-limiting DOTS requests, including those with new 'cuid' values, 3731 from the same DOTS client defends against DoS attacks that would 3732 result in varying the 'cuid' to exhaust DOTS server resources. Rate- 3733 limit policies SHOULD be enforced on DOTS gateways (if deployed) and 3734 DOTS servers. 3736 In order to prevent leaking internal information outside a client- 3737 domain, DOTS gateways located in the client-domain SHOULD NOT reveal 3738 the identification information that pertains to internal DOTS clients 3739 (e.g., source IP address, client's hostname) unless explicitly 3740 configured to do so. 3742 DOTS servers MUST verify that requesting DOTS clients are entitled to 3743 trigger actions on a given IP prefix. That is, only actions on IP 3744 resources that belong to the DOTS client' domain MUST be authorized 3745 by a DOTS server. The exact mechanism for the DOTS servers to 3746 validate that the target prefixes are within the scope of the DOTS 3747 client's domain is deployment-specific. 3749 The presence of DOTS gateways may lead to infinite forwarding loops, 3750 which is undesirable. To prevent and detect such loops, this 3751 document uses the Hop-Limit Option. 3753 CoAP-specific security considerations are discussed in Section 11 of 3754 [RFC7252], while CBOR-related security considerations are discussed 3755 in Section 8 of [RFC7049]. 3757 11. Contributors 3759 The following individuals have contributed to this document: 3761 o Jon Shallow, NCC Group, Email: jon.shallow@nccgroup.trust 3763 o Mike Geller, Cisco Systems, Inc. 3250 Florida 33309 USA, Email: 3764 mgeller@cisco.com 3766 o Robert Moskowitz, HTT Consulting Oak Park, MI 42837 United States, 3767 Email: rgm@htt-consult.com 3769 o Dan Wing, Email: dwing-ietf@fuggles.com 3771 12. Acknowledgements 3773 Thanks to Christian Jacquenet, Roland Dobbins, Roman D. Danyliw, 3774 Michael Richardson, Ehud Doron, Kaname Nishizuka, Dave Dolson, Liang 3775 Xia, Gilbert Clark, Xialiang Frank, Jim Schaad, Klaus Hartke and 3776 Nesredien Suleiman for the discussion and comments. 3778 Thanks to the core WG for the recommendations on Hop-Limit and 3779 redirect signaling. 3781 13. References 3783 13.1. Normative References 3785 [IANA.CBOR.Tags] 3786 IANA, "Concise Binary Object Representation (CBOR) Tags", 3787 . 3790 [IANA.CoAP.Content-Formats] 3791 IANA, "CoAP Content-Formats", 3792 . 3795 [IANA.MediaTypes] 3796 IANA, "Media Types", 3797 . 3799 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3800 Requirement Levels", BCP 14, RFC 2119, 3801 DOI 10.17487/RFC2119, March 1997, 3802 . 3804 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3805 DOI 10.17487/RFC3688, January 2004, 3806 . 3808 [RFC4279] Eronen, P., Ed. and H. Tschofenig, Ed., "Pre-Shared Key 3809 Ciphersuites for Transport Layer Security (TLS)", 3810 RFC 4279, DOI 10.17487/RFC4279, December 2005, 3811 . 3813 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3814 (TLS) Protocol Version 1.2", RFC 5246, 3815 DOI 10.17487/RFC5246, August 2008, 3816 . 3818 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3819 Housley, R., and W. Polk, "Internet X.509 Public Key 3820 Infrastructure Certificate and Certificate Revocation List 3821 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 3822 . 3824 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 3825 Uniform Resource Identifiers (URIs)", RFC 5785, 3826 DOI 10.17487/RFC5785, April 2010, 3827 . 3829 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 3830 Extensions: Extension Definitions", RFC 6066, 3831 DOI 10.17487/RFC6066, January 2011, 3832 . 3834 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 3835 Verification of Domain-Based Application Service Identity 3836 within Internet Public Key Infrastructure Using X.509 3837 (PKIX) Certificates in the Context of Transport Layer 3838 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 3839 2011, . 3841 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 3842 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 3843 January 2012, . 3845 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 3846 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 3847 October 2013, . 3849 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 3850 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 3851 Transport Layer Security (TLS) and Datagram Transport 3852 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 3853 June 2014, . 3855 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 3856 Application Protocol (CoAP)", RFC 7252, 3857 DOI 10.17487/RFC7252, June 2014, 3858 . 3860 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 3861 "Recommendations for Secure Use of Transport Layer 3862 Security (TLS) and Datagram Transport Layer Security 3863 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 3864 2015, . 3866 [RFC7641] Hartke, K., "Observing Resources in the Constrained 3867 Application Protocol (CoAP)", RFC 7641, 3868 DOI 10.17487/RFC7641, September 2015, 3869 . 3871 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 3872 RFC 7950, DOI 10.17487/RFC7950, August 2016, 3873 . 3875 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 3876 the Constrained Application Protocol (CoAP)", RFC 7959, 3877 DOI 10.17487/RFC7959, August 2016, 3878 . 3880 [RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 3881 Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, 3882 March 2017, . 3884 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 3885 Writing an IANA Considerations Section in RFCs", BCP 26, 3886 RFC 8126, DOI 10.17487/RFC8126, June 2017, 3887 . 3889 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 3890 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 3891 Application Protocol) over TCP, TLS, and WebSockets", 3892 RFC 8323, DOI 10.17487/RFC8323, February 2018, 3893 . 3895 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 3896 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 3897 . 3899 13.2. Informative References 3901 [I-D.boucadair-core-hop-limit] 3902 Boucadair, M., Reddy, T., and J. Shallow, "Constrained 3903 Application Protocol (CoAP) Hop Limit Option", draft- 3904 boucadair-core-hop-limit-00 (work in progress), August 3905 2018. 3907 [I-D.ietf-core-comi] 3908 Veillette, M., Stok, P., Pelov, A., and A. Bierman, "CoAP 3909 Management Interface", draft-ietf-core-comi-03 (work in 3910 progress), June 2018. 3912 [I-D.ietf-core-yang-cbor] 3913 Veillette, M., Pelov, A., Somaraju, A., Turner, R., and A. 3914 Minaburo, "CBOR Encoding of Data Modeled with YANG", 3915 draft-ietf-core-yang-cbor-06 (work in progress), February 3916 2018. 3918 [I-D.ietf-dots-architecture] 3919 Mortensen, A., Andreasen, F., Reddy, T., 3920 christopher_gray3@cable.comcast.com, c., Compton, R., and 3921 N. Teague, "Distributed-Denial-of-Service Open Threat 3922 Signaling (DOTS) Architecture", draft-ietf-dots- 3923 architecture-07 (work in progress), September 2018. 3925 [I-D.ietf-dots-data-channel] 3926 Boucadair, M., Reddy, T., Nishizuka, K., Xia, L., Patil, 3927 P., Mortensen, A., and N. Teague, "Distributed Denial-of- 3928 Service Open Threat Signaling (DOTS) Data Channel 3929 Specification", draft-ietf-dots-data-channel-19 (work in 3930 progress), September 2018. 3932 [I-D.ietf-dots-requirements] 3933 Mortensen, A., Moskowitz, R., and T. Reddy, "Distributed 3934 Denial of Service (DDoS) Open Threat Signaling 3935 Requirements", draft-ietf-dots-requirements-15 (work in 3936 progress), August 2018. 3938 [I-D.ietf-dots-use-cases] 3939 Dobbins, R., Migault, D., Fouant, S., Moskowitz, R., 3940 Teague, N., Xia, L., and K. Nishizuka, "Use cases for DDoS 3941 Open Threat Signaling", draft-ietf-dots-use-cases-16 (work 3942 in progress), July 2018. 3944 [I-D.ietf-tls-dtls13] 3945 Rescorla, E., Tschofenig, H., and N. Modadugu, "The 3946 Datagram Transport Layer Security (DTLS) Protocol Version 3947 1.3", draft-ietf-tls-dtls13-28 (work in progress), July 3948 2018. 3950 [proto_numbers] 3951 "IANA, "Protocol Numbers"", 2011, 3952 . 3954 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 3955 DOI 10.17487/RFC0791, September 1981, 3956 . 3958 [RFC1983] Malkin, G., Ed., "Internet Users' Glossary", FYI 18, 3959 RFC 1983, DOI 10.17487/RFC1983, August 1996, 3960 . 3962 [RFC3022] Srisuresh, P. and K. Egevang, "Traditional IP Network 3963 Address Translator (Traditional NAT)", RFC 3022, 3964 DOI 10.17487/RFC3022, January 2001, 3965 . 3967 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3968 Resource Identifier (URI): Generic Syntax", STD 66, 3969 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3970 . 3972 [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram 3973 Congestion Control Protocol (DCCP)", RFC 4340, 3974 DOI 10.17487/RFC4340, March 2006, 3975 . 3977 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 3978 (CIDR): The Internet Address Assignment and Aggregation 3979 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 3980 2006, . 3982 [RFC4732] Handley, M., Ed., Rescorla, E., Ed., and IAB, "Internet 3983 Denial-of-Service Considerations", RFC 4732, 3984 DOI 10.17487/RFC4732, December 2006, 3985 . 3987 [RFC4787] Audet, F., Ed. and C. Jennings, "Network Address 3988 Translation (NAT) Behavioral Requirements for Unicast 3989 UDP", BCP 127, RFC 4787, DOI 10.17487/RFC4787, January 3990 2007, . 3992 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 3993 RFC 4960, DOI 10.17487/RFC4960, September 2007, 3994 . 3996 [RFC4987] Eddy, W., "TCP SYN Flooding Attacks and Common 3997 Mitigations", RFC 4987, DOI 10.17487/RFC4987, August 2007, 3998 . 4000 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 4001 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 4002 DOI 10.17487/RFC5389, October 2008, 4003 . 4005 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 4006 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 4007 June 2010, . 4009 [RFC6052] Bao, C., Huitema, C., Bagnulo, M., Boucadair, M., and X. 4010 Li, "IPv6 Addressing of IPv4/IPv6 Translators", RFC 6052, 4011 DOI 10.17487/RFC6052, October 2010, 4012 . 4014 [RFC6146] Bagnulo, M., Matthews, P., and I. van Beijnum, "Stateful 4015 NAT64: Network Address and Protocol Translation from IPv6 4016 Clients to IPv4 Servers", RFC 6146, DOI 10.17487/RFC6146, 4017 April 2011, . 4019 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 4020 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 4021 DOI 10.17487/RFC6234, May 2011, 4022 . 4024 [RFC6296] Wasserman, M. and F. Baker, "IPv6-to-IPv6 Network Prefix 4025 Translation", RFC 6296, DOI 10.17487/RFC6296, June 2011, 4026 . 4028 [RFC6724] Thaler, D., Ed., Draves, R., Matsumoto, A., and T. Chown, 4029 "Default Address Selection for Internet Protocol Version 6 4030 (IPv6)", RFC 6724, DOI 10.17487/RFC6724, September 2012, 4031 . 4033 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 4034 Specifications and Registration Procedures", BCP 13, 4035 RFC 6838, DOI 10.17487/RFC6838, January 2013, 4036 . 4038 [RFC6887] Wing, D., Ed., Cheshire, S., Boucadair, M., Penno, R., and 4039 P. Selkirk, "Port Control Protocol (PCP)", RFC 6887, 4040 DOI 10.17487/RFC6887, April 2013, 4041 . 4043 [RFC6888] Perreault, S., Ed., Yamagata, I., Miyakawa, S., Nakagawa, 4044 A., and H. Ashida, "Common Requirements for Carrier-Grade 4045 NATs (CGNs)", BCP 127, RFC 6888, DOI 10.17487/RFC6888, 4046 April 2013, . 4048 [RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 4049 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 4050 . 4052 [RFC7452] Tschofenig, H., Arkko, J., Thaler, D., and D. McPherson, 4053 "Architectural Considerations in Smart Object Networking", 4054 RFC 7452, DOI 10.17487/RFC7452, March 2015, 4055 . 4057 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 4058 NETCONF Protocol over Transport Layer Security (TLS) with 4059 Mutual X.509 Authentication", RFC 7589, 4060 DOI 10.17487/RFC7589, June 2015, 4061 . 4063 [RFC7918] Langley, A., Modadugu, N., and B. Moeller, "Transport 4064 Layer Security (TLS) False Start", RFC 7918, 4065 DOI 10.17487/RFC7918, August 2016, 4066 . 4068 [RFC7924] Santesson, S. and H. Tschofenig, "Transport Layer Security 4069 (TLS) Cached Information Extension", RFC 7924, 4070 DOI 10.17487/RFC7924, July 2016, 4071 . 4073 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 4074 RFC 7951, DOI 10.17487/RFC7951, August 2016, 4075 . 4077 [RFC8305] Schinazi, D. and T. Pauly, "Happy Eyeballs Version 2: 4078 Better Connectivity Using Concurrency", RFC 8305, 4079 DOI 10.17487/RFC8305, December 2017, 4080 . 4082 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 4083 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 4084 . 4086 Authors' Addresses 4088 Tirumaleswar Reddy (editor) 4089 McAfee, Inc. 4090 Embassy Golf Link Business Park 4091 Bangalore, Karnataka 560071 4092 India 4094 Email: kondtir@gmail.com 4096 Mohamed Boucadair (editor) 4097 Orange 4098 Rennes 35000 4099 France 4101 Email: mohamed.boucadair@orange.com 4103 Prashanth Patil 4104 Cisco Systems, Inc. 4106 Email: praspati@cisco.com 4107 Andrew Mortensen 4108 Arbor Networks, Inc. 4109 2727 S. State St 4110 Ann Arbor, MI 48104 4111 United States 4113 Email: amortensen@arbor.net 4115 Nik Teague 4116 Verisign, Inc. 4117 United States 4119 Email: nteague@verisign.com