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