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