idnits 2.17.1 draft-ietf-dots-signal-channel-17.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 == Line 2220 has weird spacing: '...er-port ine...' == Line 2221 has weird spacing: '...er-port ine...' == Line 2236 has weird spacing: '...er-port ine...' == Line 2237 has weird spacing: '...er-port ine...' == Line 2301 has weird spacing: '...ro addr ine...' -- The document date (January 22, 2018) is 2276 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 3422, but not defined ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Downref: Normative reference to an Informational RFC: RFC 6234 ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) == Outdated reference: A later version (-17) exists of draft-ietf-core-comi-02 == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-05 == Outdated reference: A later version (-18) exists of draft-ietf-dots-architecture-05 == Outdated reference: A later version (-31) exists of draft-ietf-dots-data-channel-11 == Outdated reference: A later version (-22) exists of draft-ietf-dots-requirements-10 == Outdated reference: A later version (-25) exists of draft-ietf-dots-use-cases-09 == Outdated reference: A later version (-06) exists of draft-ietf-netmod-yang-tree-diagrams-04 == Outdated reference: A later version (-43) exists of draft-ietf-tls-dtls13-22 == Outdated reference: A later version (-28) exists of draft-ietf-tls-tls13-23 -- Obsolete informational reference (is this intentional?): RFC 4960 (Obsoleted by RFC 9260) -- Obsolete informational reference (is this intentional?): RFC 5077 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 5389 (Obsoleted by RFC 8489) -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) Summary: 8 errors (**), 0 flaws (~~), 16 warnings (==), 5 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: July 26, 2018 Orange 6 P. Patil 7 Cisco 8 A. Mortensen 9 Arbor Networks, Inc. 10 N. Teague 11 Verisign, Inc. 12 January 22, 2018 14 Distributed Denial-of-Service Open Threat Signaling (DOTS) Signal 15 Channel Specification 16 draft-ietf-dots-signal-channel-17 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 with the RFC number to be assigned to 32 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"; 39 o "| 3.00 | Alternate server | [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 Status of This Memo 48 This Internet-Draft is submitted in full conformance with the 49 provisions of BCP 78 and BCP 79. 51 Internet-Drafts are working documents of the Internet Engineering 52 Task Force (IETF). Note that other groups may also distribute 53 working documents as Internet-Drafts. The list of current Internet- 54 Drafts is at https://datatracker.ietf.org/drafts/current/. 56 Internet-Drafts are draft documents valid for a maximum of six months 57 and may be updated, replaced, or obsoleted by other documents at any 58 time. It is inappropriate to use Internet-Drafts as reference 59 material or to cite them other than as "work in progress." 61 This Internet-Draft will expire on July 26, 2018. 63 Copyright Notice 65 Copyright (c) 2018 IETF Trust and the persons identified as the 66 document authors. All rights reserved. 68 This document is subject to BCP 78 and the IETF Trust's Legal 69 Provisions Relating to IETF Documents 70 (https://trustee.ietf.org/license-info) in effect on the date of 71 publication of this document. Please review these documents 72 carefully, as they describe your rights and restrictions with respect 73 to this document. Code Components extracted from this document must 74 include Simplified BSD License text as described in Section 4.e of 75 the Trust Legal Provisions and are provided without warranty as 76 described in the Simplified BSD License. 78 Table of Contents 80 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 81 2. Notational Conventions and Terminology . . . . . . . . . . . 5 82 3. Design Overview . . . . . . . . . . . . . . . . . . . . . . . 6 83 4. DOTS Signal Channel: Messages & Behaviors . . . . . . . . . . 8 84 4.1. DOTS Server(s) Discovery . . . . . . . . . . . . . . . . 8 85 4.2. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . 8 86 4.3. Happy Eyeballs for DOTS Signal Channel . . . . . . . . . 9 87 4.4. DOTS Mitigation Methods . . . . . . . . . . . . . . . . . 10 88 4.4.1. Request Mitigation . . . . . . . . . . . . . . . . . 11 89 4.4.2. Retrieve Information Related to a Mitigation . . . . 24 90 4.4.3. Efficacy Update from DOTS Clients . . . . . . . . . . 31 91 4.4.4. Withdraw a Mitigation . . . . . . . . . . . . . . . . 33 92 4.5. DOTS Signal Channel Session Configuration . . . . . . . . 34 93 4.5.1. Discover Configuration Parameters . . . . . . . . . . 36 94 4.5.2. Convey DOTS Signal Channel Session Configuration . . 41 95 4.5.3. Delete DOTS Signal Channel Session Configuration . . 45 96 4.6. Redirected Signaling . . . . . . . . . . . . . . . . . . 46 97 4.7. Heartbeat Mechanism . . . . . . . . . . . . . . . . . . . 47 98 5. DOTS Signal Channel YANG Module . . . . . . . . . . . . . . . 49 99 5.1. Tree Structure . . . . . . . . . . . . . . . . . . . . . 49 100 5.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 51 101 6. Mapping Parameters to CBOR . . . . . . . . . . . . . . . . . 65 102 7. (D)TLS Protocol Profile and Performance Considerations . . . 67 103 7.1. (D)TLS Protocol Profile . . . . . . . . . . . . . . . . . 67 104 7.2. (D)TLS 1.3 Considerations . . . . . . . . . . . . . . . . 68 105 7.3. MTU and Fragmentation . . . . . . . . . . . . . . . . . . 69 106 8. Mutual Authentication of DOTS Agents & Authorization of DOTS 107 Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 108 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 72 109 9.1. DOTS Signal Channel UDP and TCP Port Number . . . . . . . 72 110 9.2. Well-Known 'dots' URI . . . . . . . . . . . . . . . . . . 72 111 9.3. CoAP Response Code . . . . . . . . . . . . . . . . . . . 72 112 9.4. DOTS Signal Channel CBOR Mappings Registry . . . . . . . 73 113 9.4.1. Registration Template . . . . . . . . . . . . . . . . 73 114 9.4.2. Initial Registry Content . . . . . . . . . . . . . . 73 115 9.5. DOTS Signal Channel YANG Module . . . . . . . . . . . . . 75 116 10. Implementation Status . . . . . . . . . . . . . . . . . . . . 75 117 10.1. nttdots . . . . . . . . . . . . . . . . . . . . . . . . 76 118 11. Security Considerations . . . . . . . . . . . . . . . . . . . 76 119 12. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 77 120 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 77 121 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 78 122 14.1. Normative References . . . . . . . . . . . . . . . . . . 78 123 14.2. Informative References . . . . . . . . . . . . . . . . . 80 124 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 84 126 1. Introduction 128 A distributed denial-of-service (DDoS) attack is an attempt to make 129 machines or network resources unavailable to their intended users. 130 In most cases, sufficient scale can be achieved by compromising 131 enough end-hosts and using those infected hosts to perpetrate and 132 amplify the attack. The victim in this attack can be an application 133 server, a host, a router, a firewall, or an entire network. 135 Network applications have finite resources like CPU cycles, the 136 number of processes or threads they can create and use, the maximum 137 number of simultaneous connections it can handle, the limited 138 resources of the control plane, etc. When processing network 139 traffic, such applications are supposed to use these resources to 140 offer the intended task in the most efficient manner. However, a 141 DDoS attacker may be able to prevent an application from performing 142 its intended task by making the application exhaust its finite 143 resources. 145 TCP DDoS SYN-flood, for example, is a memory-exhausting attack while 146 ACK-flood is a CPU-exhausting attack [RFC4987]. Attacks on the link 147 are carried out by sending enough traffic so that the link becomes 148 congested, thereby likely causing packet loss for legitimate traffic. 149 Stateful firewalls can also be attacked by sending traffic that 150 causes the firewall to maintain an excessive number of states that 151 may jeopardize the firewall's operation overall, besides like 152 performance impacts. The firewall then runs out of memory, and can 153 no longer instantiate the states required to process legitimate 154 flows. Other possible DDoS attacks are discussed in [RFC4732]. 156 In many cases, it may not be possible for network administrators to 157 determine the cause(s) of an attack. They may instead just realize 158 that certain resources seem to be under attack. This document 159 defines a lightweight protocol that allows a DOTS client to request 160 mitigation from one or more DOTS servers for protection against 161 detected, suspected, or anticipated attacks. This protocol enables 162 cooperation between DOTS agents to permit a highly-automated network 163 defense that is robust, reliable, and secure. 165 An example of a network diagram that illustrates a deployment of DOTS 166 agents is shown in Figure 1. In this example, a DOTS server is 167 operating on the access network. A DOTS client is located on the LAN 168 (Local Area Network), while a DOTS gateway is embedded in the CPE 169 (Customer Premises Equipment). 171 Network 172 Resource CPE router Access network __________ 173 +-----------+ +--------------+ +-------------+ / \ 174 | |___| |____| |___ | Internet | 175 |DOTS client| | DOTS gateway | | DOTS server | | | 176 | | | | | | | | 177 +-----------+ +--------------+ +-------------+ \__________/ 179 Figure 1: Sample DOTS Deployment (1) 181 DOTS servers can also be reachable over the Internet, as depicted in 182 Figure 2. 184 Network DDoS mitigation 185 Resource CPE router __________ service 186 +-----------+ +-------------+ / \ +-------------+ 187 | |___| |____| |___ | | 188 |DOTS client| |DOTS gateway | | Internet | | DOTS server | 189 | | | | | | | | 190 +-----------+ +-------------+ \__________/ +-------------+ 192 Figure 2: Sample DOTS Deployment (2) 194 In typical deployments, the DOTS client belongs to a different 195 administrative domain than the DOTS server. For example, the DOTS 196 client is embedded in a firewall protecting services owned and 197 operated by a domain, while the DOTS server is owned and operated by 198 a different domain providing DDoS mitigation services. The latter 199 might or might not provide connectivity services to the network 200 hosting the DOTS client. 202 The DOTS server may (not) be co-located with the DOTS mitigator. In 203 typical deployments, the DOTS server belongs to the same 204 administrative domain as the mitigator. The DOTS client can 205 communicate directly with a DOTS server or indirectly via a DOTS 206 gateway. 208 The document adheres to the DOTS architecture 209 [I-D.ietf-dots-architecture]. The requirements for DOTS signal 210 channel protocol are documented in [I-D.ietf-dots-requirements]. 211 This document satisfies all the use cases discussed in 212 [I-D.ietf-dots-use-cases]. 214 This document focuses on the DOTS signal channel. This is a 215 companion document of the DOTS data channel specification 216 [I-D.ietf-dots-data-channel] that defines a configuration and a bulk 217 data exchange mechanism supporting the DOTS signal channel. 219 2. Notational Conventions and Terminology 221 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 222 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 223 "OPTIONAL" in this document are to be interpreted as described in 224 [RFC2119]. 226 (D)TLS is used for statements that apply to both Transport Layer 227 Security [RFC5246] and Datagram Transport Layer Security [RFC6347]. 228 Specific terms are used for any statement that applies to either 229 protocol alone. 231 The reader should be familiar with the terms defined in 232 [I-D.ietf-dots-architecture]. 234 The meaning of the symbols in YANG tree diagrams is defined in 235 [I-D.ietf-netmod-yang-tree-diagrams]. 237 3. Design Overview 239 The DOTS signal channel is built on top of the Constrained 240 Application Protocol (CoAP) [RFC7252], a lightweight protocol 241 originally designed for constrained devices and networks. The many 242 features of CoAP (expectation of packet loss, support for 243 asynchronous non-confirmable messaging, congestion control, small 244 message overhead limiting the need for fragmentation, use of minimal 245 resources, and support for (D)TLS) makes it a good candidate to build 246 the DOTS signaling mechanism from. 248 The DOTS signal channel is layered on existing standards (Figure 3). 250 +---------------------+ 251 | DOTS Signal Channel | 252 +---------------------+ 253 | CoAP | 254 +----------+----------+ 255 | TLS | DTLS | 256 +----------+----------+ 257 | TCP | UDP | 258 +----------+----------+ 259 | IP | 260 +---------------------+ 262 Figure 3: Abstract Layering of DOTS Signal Channel over CoAP over 263 (D)TLS 265 By default, a DOTS signal channel MUST run over port number TBD as 266 defined in Section 9.1, for both UDP and TCP, unless the DOTS server 267 has a mutual agreement with its DOTS clients to use a different port 268 number. DOTS clients may alternatively support means to dynamically 269 discover the ports used by their DOTS servers. In order to use a 270 distinct port number (as opposed to TBD), DOTS clients and servers 271 should support a configurable parameter to supply the port number to 272 use. The rationale for not using the default port number 5684 273 ((D)TLS CoAP) is to allow for differentiated behaviors in 274 environments where both a DOTS gateway and an IoT gateway (e.g., 275 Figure 3 of [RFC7452]) are present. 277 The signal channel is initiated by the DOTS client (Section 4.4). 278 Once the signal channel is established, the DOTS agents periodically 279 send heartbeats to keep the channel active (Section 4.7). At any 280 time, the DOTS client may send a mitigation request message to a DOTS 281 server over the active channel. While mitigation is active because 282 of the higher likelihood of packet loss during a DDoS attack, the 283 DOTS server periodically sends status messages to the client, 284 including basic mitigation feedback details. Mitigation remains 285 active until the DOTS client explicitly terminates mitigation, or the 286 mitigation lifetime expires. 288 DOTS signaling can happen with DTLS [RFC6347] over UDP and TLS 289 [RFC5246] over TCP. Likewise, DOTS requests may be sent using IPv4 290 or IPv6 transfer capabilities. A Happy Eyeballs procedure for DOTS 291 signal channel is specified in Section 4.3. 293 Messages exchanged between DOTS agents are serialized using Concise 294 Binary Object Representation (CBOR) [RFC7049], CBOR is a binary 295 encoding scheme designed for small code and message size. CBOR- 296 encoded payloads are used to carry signal channel-specific payload 297 messages which convey request parameters and response information 298 such as errors. In order to allow the use of the same data models, 299 [RFC7951] specifies the JSON encoding of YANG-modeled data. A 300 similar effort for CBOR is defined in [I-D.ietf-core-yang-cbor]. 302 From that standpoint, this document specifies a YANG module for 303 representing mitigation scopes and DOTS signal channel session 304 configuration data (Section 5). Representing these data as CBOR data 305 is assumed to follow the rules in [I-D.ietf-core-yang-cbor] or those 306 in [RFC7951] combined with JSON/CBOR conversion rules in [RFC7049]. 307 All parameters in the payload of the DOTS signal channel are mapped 308 to CBOR types as specified in Section 6. 310 In order to prevent fragmentation, DOTS agents must follow the 311 recommendations documented in Section 4.6 of [RFC7252]. Refer to 312 Section 7.3 for more details. 314 DOTS agents MUST support GET, PUT, and DELETE CoAP methods. The 315 payload included in CoAP responses with 2.xx and 3.xx Response Codes 316 MUST be of content type "application/cbor" (Section 5.5.1 of 317 [RFC7252]). CoAP responses with 4.xx and 5.xx error Response Codes 318 MUST include a diagnostic payload (Section 5.5.2 of [RFC7252]). The 319 Diagnostic Payload may contain additional information to aid 320 troubleshooting. 322 In deployments where multiple DOTS clients are enabled in a network 323 (owned and operated by the same entity), the DOTS server may detect 324 conflicting mitigation requests from these clients. This document 325 does not aim to specify a comprehensive list of conditions under 326 which a DOTS server will characterize two mitigation requests from 327 distinct DOTS clients as conflicting, nor recommend a DOTS server 328 behavior for processing conflicting mitigation requests. Those 329 considerations are implementation- and deployment-specific. 330 Nevertheless, the document specifies the mechanisms to notify DOTS 331 clients when conflicts occur, including the conflict cause 332 (Section 4.4). 334 In deployments where one or more translators (e.g., Traditional NAT 335 [RFC3022], CGN [RFC6888], NAT64 [RFC6146], NPTv6 [RFC6296]) are 336 enabled between the client's network and the DOTS server, DOTS signal 337 channel messages forwarded to a DOTS server must not include internal 338 IP addresses/prefixes and/or port numbers; external addresses/ 339 prefixes and/or port numbers as assigned by the translator must be 340 used instead. This document does not make any recommendation about 341 possible translator discovery mechanisms. The following are some 342 (non-exhaustive) deployment examples that may be considered: 344 o Port Control Protocol (PCP) [RFC6887] or Session Traversal 345 Utilities for NAT (STUN) [RFC5389] may be used to retrieve the 346 external addresses/prefixes and/or port numbers. Information 347 retrieved by means of PCP or STUN will be used to feed the DOTS 348 signal channel messages that will be sent to a DOTS server. 350 o A DOTS gateway may be co-located with the translator. The DOTS 351 gateway will need to update the DOTS messages, based upon the 352 local translator's binding table. 354 4. DOTS Signal Channel: Messages & Behaviors 356 4.1. DOTS Server(s) Discovery 358 This document assumes that DOTS clients are provisioned with the 359 reachability information of their DOTS server(s) using a variety of 360 means (e.g., local configuration, or dynamic means such as DHCP). 361 These means are out of scope of this document. 363 Likewise, it is out of scope of this document to specify the behavior 364 of a DOTS client when it sends requests (e.g., contact all servers, 365 select one server among the list) when multiple DOTS servers are 366 provisioned. 368 4.2. CoAP URIs 370 The DOTS server MUST support the use of the path-prefix of "/.well- 371 known/" as defined in [RFC5785] and the registered name of "dots". 372 Each DOTS operation is indicated by a path-suffix that indicates the 373 intended operation. The operation path (Table 1) is appended to the 374 path-prefix to form the URI used with a CoAP request to perform the 375 desired DOTS operation. 377 +-----------------------+----------------+-------------+ 378 | Operation | Operation Path | Details | 379 +-----------------------+----------------+-------------+ 380 | Mitigation | /v1/mitigate | Section 4.4 | 381 +-----------------------+----------------+-------------+ 382 | Session configuration | /v1/config | Section 4.5 | 383 +-----------------------+----------------+-------------+ 385 Table 1: Operations and their Corresponding URIs 387 4.3. Happy Eyeballs for DOTS Signal Channel 389 [I-D.ietf-dots-requirements] mentions that DOTS agents will have to 390 support both connectionless and connection-oriented protocols. As 391 such, the DOTS signal channel is designed to operate with DTLS over 392 UDP and TLS over TCP. Further, a DOTS client may acquire a list of 393 IPv4 and IPv6 addresses (Section 4.1), each of which can be used to 394 contact the DOTS server using UDP and TCP. The following specifies 395 the procedure to follow to select the address family and the 396 transport protocol for sending DOTS signal channel messages. 398 Such procedure is needed to avoid experiencing long connection 399 delays. For example, if an IPv4 path to reach a DOTS server is 400 found, but the DOTS server's IPv6 path is not working, a dual-stack 401 DOTS client may experience a significant connection delay compared to 402 an IPv4-only DOTS client. The other problem is that if a middlebox 403 between the DOTS client and DOTS server is configured to block UDP 404 traffic, the DOTS client will fail to establish a DTLS session with 405 the DOTS server and, as a consequence, will have to fall back to TLS 406 over TCP, thereby incurring significant connection delays. 408 To overcome these connection setup problems, the DOTS client attempts 409 to connect to its DOTS server(s) using both IPv6 and IPv4, and tries 410 both DTLS over UDP and TLS over TCP in a manner similar to the Happy 411 Eyeballs mechanism [RFC8305]. These connection attempts are 412 performed by the DOTS client when it initializes. The results of the 413 Happy Eyeballs procedure are used by the DOTS client for sending its 414 subsequent messages to the DOTS server. 416 The order of preference of DOTS signal channel address family and 417 transport protocol (most preferred first) is: UDP over IPv6, UDP over 418 IPv4, TCP over IPv6, and finally TCP over IPv4. This order adheres 419 to the address preference order specified in [RFC6724] and the DOTS 420 signal channel preference which privileges the use of UDP over TCP 421 (to avoid TCP's head of line blocking). 423 In reference to Figure 4, the DOTS client sends two TCP SYNs and two 424 DTLS ClientHello messages at the same time over IPv6 and IPv4. In 425 this example, it is assumed that the IPv6 path is broken and UDP 426 traffic is dropped by a middlebox but has little impact to the DOTS 427 client because there is no long delay before using IPv4 and TCP. The 428 DOTS client repeats the mechanism to discover whether DOTS signal 429 channel messages with DTLS over UDP becomes available from the DOTS 430 server, so the DOTS client can migrate the DOTS signal channel from 431 TCP to UDP. Such probing SHOULD NOT be done more frequently than 432 every 24 hours and MUST NOT be done more frequently than every 5 433 minutes. 435 +-----------+ +-----------+ 436 |DOTS client| |DOTS server| 437 +-----------+ +-----------+ 438 | | 439 |--DTLS ClientHello, IPv6 ---->X | 440 |--TCP SYN, IPv6-------------->X | 441 |--DTLS ClientHello, IPv4 ---->X | 442 |--TCP SYN, IPv4--------------------------------------->| 443 |--DTLS ClientHello, IPv6 ---->X | 444 |--TCP SYN, IPv6-------------->X | 445 |<-TCP SYNACK-------------------------------------------| 446 |--DTLS ClientHello, IPv4 ---->X | 447 |--TCP ACK--------------------------------------------->| 448 |<------------Establish TLS Session-------------------->| 449 |----------------DOTS signal--------------------------->| 450 | | 452 Figure 4: DOTS Happy Eyeballs 454 4.4. DOTS Mitigation Methods 456 The following methods are used by a DOTS client to request, withdraw, 457 or retrieve the status of mitigation requests: 459 PUT: DOTS clients use the PUT method to request mitigation from a 460 DOTS server (Section 4.4.1). During active mitigation, DOTS 461 clients may use PUT requests to carry mitigation efficacy 462 updates to the DOTS server (Section 4.4.3). 464 GET: DOTS clients may use the GET method to subscribe to DOTS 465 server status messages, or to retrieve the list of its 466 mitigations maintained by a DOTS server (Section 4.4.2). 468 DELETE: DOTS clients use the DELETE method to withdraw a request for 469 mitigation from a DOTS server (Section 4.4.4). 471 Mitigation request and response messages are marked as Non- 472 confirmable messages (Section 2.2 of [RFC7252]). 474 DOTS agents SHOULD follow the data transmission guidelines discussed 475 in Section 3.1.3 of [RFC8085] and control transmission behavior by 476 not sending more than one UDP datagram per RTT to the peer DOTS agent 477 on average. 479 Requests marked by the DOTS client as Non-confirmable messages are 480 sent at regular intervals until a response is received from the DOTS 481 server. If the DOTS client cannot maintain an RTT estimate, it 482 SHOULD NOT send more than one Non-confirmable request every 3 483 seconds, and SHOULD use an even less aggressive rate whenever 484 possible (case 2 in Section 3.1.3 of [RFC8085]). 486 4.4.1. Request Mitigation 488 When a DOTS client requires mitigation for some reason, the DOTS 489 client uses the CoAP PUT method to send a mitigation request to its 490 DOTS server(s) (Figure 5, illustrated in JSON diagnostic notation). 492 If this DOTS client is entitled to solicit the DOTS service, the DOTS 493 server can enable mitigation on behalf of the DOTS client by 494 communicating the DOTS client's request to the mitigator and relaying 495 selected mitigator feedback to the requesting DOTS client. 497 Header: PUT (Code=0.03) 498 Uri-Host: "host" 499 Uri-Path: ".well-known" 500 Uri-Path: "dots" 501 Uri-Path: "version" 502 Uri-Path: "mitigate" 503 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 504 Uri-Path: "mid=123" 505 Content-Type: "application/cbor" 506 { 507 "ietf-dots-signal-channel:mitigation-scope": { 508 "scope": [ 509 { 510 "target-prefix": [ 511 "string" 512 ], 513 "target-port-range": [ 514 { 515 "lower-port": integer, 516 "upper-port": integer 517 } 518 ], 519 "target-protocol": [ 520 integer 521 ], 522 "target-fqdn": [ 523 "string" 524 ], 525 "target-uri": [ 526 "string" 527 ], 528 "alias-name": [ 529 "string" 530 ], 531 "lifetime": integer 532 } 533 ] 534 } 535 } 537 Figure 5: PUT to Convey DOTS Mitigation Requests 539 The Uri-Path option carries a major and minor version nomenclature to 540 manage versioning; DOTS signal channel in this specification uses 541 'v1' major version. 543 The order of the Uri-Path options is important as it defines the CoAP 544 resource. In particular, 'mid' MUST follow 'cuid'. 546 The additional Uri-Path parameters to those defined in Section 4.2 547 are as follows: 549 cuid: Stands for Client Unique Identifier. A globally unique 550 identifier that is meant to prevent collisions among DOTS clients, 551 especially those from the same domain. It MUST be generated by 552 DOTS clients. 554 Implementations SHOULD use the output of a cryptographic hash 555 algorithm whose input is the DER-encoded ASN.1 representation of 556 the Subject Public Key Info (SPKI) of the DOTS client X.509 557 certificate [RFC5280], the DOTS client raw public key [RFC7250], 558 or the "PSK identity" used by the DOTS client in the TLS 559 ClientKeyExchange message to set 'cuid'. In this version of the 560 specification, the cryptographic hash algorithm used is SHA-256 561 [RFC6234]. The output of the cryptographic hash algorithm is 562 truncated to 16 bytes; truncation is done by stripping off the 563 final 16 bytes. The truncated output is base64url encoded. 565 The 'cuid' is intended to be stable when communicating with a 566 given DOTS server, i.e., the 'cuid' used by a DOTS client SHOULD 567 NOT change over time. Distinct 'cuid' values MAY be used per DOTS 568 server. 570 DOTS servers MUST return 4.09 (Conflict) error code to a DOTS peer 571 to notify that the 'cuid' is already in-use by another DOTS 572 client. Upon receipt of that error code, a new 'cuid' MUST be 573 generated by the DOTS peer. 575 Client-domain DOTS gateways MUST handle 'cuid' collision directly 576 and it is RECOMMENDED that 'cuid' collision is handled directly by 577 server-domain DOTS gateways. 579 DOTS gateways MAY rewrite the 'cuid' used by peer DOTS clients. 580 Triggers for such rewriting are out of scope. 582 This is a mandatory Uri-Path. 584 mid: Identifier for the mitigation request represented with an 585 integer. This identifier MUST be unique for each mitigation 586 request bound to the DOTS client, i.e., the 'mid' parameter value 587 in the mitigation request needs to be unique relative to the 'mid' 588 parameter values of active mitigation requests conveyed from the 589 DOTS client to the DOTS server. 591 This identifier MUST be generated by the DOTS client. This 592 document does not make any assumption about how this identifier is 593 generated. 595 This is a mandatory Uri-Path parameter. 597 The parameters in the CBOR body of the PUT request are described 598 below: 600 target-prefix: A list of prefixes identifying resources under 601 attack. Prefixes are represented using Classless Inter-Domain 602 Routing (CIDR) notation [RFC4632]. 603 As a reminder, the prefix length must be less than or equal to 32 604 (resp. 128) for IPv4 (resp. IPv6). 606 This is an optional attribute. 608 target-port-range: A list of port numbers bound to resources under 609 attack. 611 A port range is defined by two bounds, a lower port number (lower- 612 port) and an upper port number (upper-port). When only 'lower- 613 port' is present, it represents a single port number. 615 For TCP, UDP, Stream Control Transmission Protocol (SCTP) 616 [RFC4960], or Datagram Congestion Control Protocol (DCCP) 617 [RFC4340], a range of ports can be, for example, 0-1023, 618 1024-65535, or 1024-49151. 620 This is an optional attribute. 622 target-protocol: A list of protocols involved in an attack. Values 623 are taken from the IANA protocol registry [proto_numbers]. 625 The value '0' has a special meaning for 'all protocols'. 627 This is an optional attribute. 629 target-fqdn: A list of Fully Qualified Domain Names (FQDNs) 630 identifying resources under attack. An FQDN is the full name of a 631 resource, rather than just its hostname. For example, "venera" is 632 a hostname, and "venera.isi.edu" is an FQDN [RFC1983]. 634 This is an optional attribute. 636 target-uri: A list of Uniform Resource Identifiers (URIs) [RFC3986] 637 identifying resources under attack. 639 This is an optional attribute. 641 alias-name: A list of aliases of resources for which the mitigation 642 is requested. Aliases can be created using the DOTS data channel 643 (Section 6.1 of [I-D.ietf-dots-data-channel]), direct 644 configuration, or other means. 646 An alias is used in subsequent signal channel exchanges to refer 647 more efficiently to the resources under attack. 649 This is an optional attribute. 651 lifetime: Lifetime of the mitigation request in seconds. The 652 RECOMMENDED lifetime of a mitigation request is 3600 seconds (60 653 minutes) -- this value was chosen to be long enough so that 654 refreshing is not typically a burden on the DOTS client, while 655 expiring the request where the client has unexpectedly quit in a 656 timely manner. DOTS clients MUST include this parameter in their 657 mitigation requests. Upon the expiry of this lifetime, and if the 658 request is not refreshed, the mitigation request is removed. The 659 request can be refreshed by sending the same request again. 661 A lifetime of '0' in a mitigation request is an invalid value. 663 A lifetime of negative one (-1) indicates indefinite lifetime for 664 the mitigation request. The DOTS server MAY refuse indefinite 665 lifetime, for policy reasons; the granted lifetime value is 666 returned in the response. DOTS clients MUST be prepared to not be 667 granted mitigations with indefinite lifetimes. 669 The DOTS server MUST always indicate the actual lifetime in the 670 response and the remaining lifetime in status messages sent to the 671 DOTS client. 673 This is a mandatory attribute. 675 In deployments where server-domain DOTS gateways are enabled, 676 identity information about the origin source client domain SHOULD be 677 supplied to the DOTS server. That information is meant to assist the 678 DOTS server to enforce some policies. These policies can be enforced 679 per-client, per-client domain, or both. Figure 6 shows an example of 680 a request relayed by a server-domain DOTS gateway. 682 Header: PUT (Code=0.03) 683 Uri-Host: "host" 684 Uri-Path: ".well-known" 685 Uri-Path: "dots" 686 Uri-Path: "v1" 687 Uri-Path: "mitigate" 688 Uri-Path: "cdid=7eeaf349529eb55ed50113" 689 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 690 Uri-Path: "mid=123" 691 Content-Type: "application/cbor" 692 { 693 "ietf-dots-signal-channel:mitigation-scope": { 694 "scope": [ 695 { 696 "target-prefix": [ 697 "string" 698 ], 699 "target-port-range": [ 700 { 701 "lower-port": integer, 702 "upper-port": integer 703 } 704 ], 705 "target-protocol": [ 706 integer 707 ], 708 "target-fqdn": [ 709 "string" 710 ], 711 "target-uri": [ 712 "string" 713 ], 714 "alias-name": [ 715 "string" 716 ], 717 "lifetime": integer 718 } 719 ] 720 } 721 } 723 Figure 6: PUT to Convey DOTS Mitigation Request as relayed by a 724 Server-Domain DOTS Gateway 726 A server-domain DOTS gateway SHOULD add the following Uri-Path 727 parameter: 729 cdid: Stands for Client Domain IDentifier. The 'cdid' is conveyed 730 by a server-domain DOTS gateway to propagate the source domain 731 identity from the gateway's client-facing-side to the gateway's 732 server-facing-side, and from the gateway's server-facing-side to 733 the DOTS server. 'cdid' may be used by the final DOTS server for 734 policy enforcement purposes (e.g., enforce a quota on filtering 735 rules). These policies are deployment-specific. 737 Server-domain DOTS gateways SHOULD support a configuration option 738 to instruct whether 'cdid' parameter is to be inserted. 740 In order to accommodate deployments that require enforcing per- 741 client policies, per-client domain policies, or a combination 742 thereof, server-domain DOTS gateways MUST supply the SPKI hash of 743 the DOTS client X.509 certificate, the DOTS client raw public key, 744 or the hash of the "PSK identity" in the 'cdid', following the 745 same rules for generating the hash conveyed in 'cuid', which is 746 then used by the ultimate DOTS server to determine the 747 corresponding client's domain. 749 If a DOTS client is provisioned, for example, with distinct 750 certificates as a function of the peer server-domain DOTS gateway, 751 distinct 'cdid' values may be supplied by a server-domain DOTS 752 gateway. The ultimate DOTS server MUST treat those 'cdid' values 753 as equivalent. 755 The 'cdid' attribute MUST NOT be generated and included by DOTS 756 clients. 758 DOTS servers MUST ignore 'cdid' attributes that are directly 759 supplied by source DOTS clients or client-domain DOTS gateways. 760 This implies that first server-domain DOTS gateways MUST strip 761 'cdid' attributes supplied by DOTS clients. DOTS servers SHOULD 762 support a configuration parameter to identify DOTS gateways that 763 are trusted to supply 'cdid' attributes. 765 Only single-valued 'cdid' are defined in this document. 767 This is an optional Uri-Path. 769 The CBOR key values for the parameters are defined in Section 6. 770 Section 9 defines how the CBOR key values can be allocated for future 771 uses. 773 Because of the complexity to handle partial failure cases, this 774 specification does not allow for including multiple mitigation 775 requests in the same PUT request. Concretely, a DOTS client MUST NOT 776 include multiple 'scope' parameters in the same PUT request. 778 FQDN and URI mitigation scopes may be thought of as a form of scope 779 alias, in which the addresses to which the domain name or URI resolve 780 represent the full scope of the mitigation. 782 In the PUT request at least one of the attributes 'target-prefix', 783 'target-fqdn','target-uri', or 'alias-name' MUST be present. 785 Attributes and Uri-Path parameters with empty values MUST NOT be 786 present in a request. 788 The relative order of two mitigation requests from a DOTS client is 789 determined by comparing their respective 'mid' values. If two 790 mitigation requests have overlapping mitigation scopes, the 791 mitigation request with the highest numeric 'mid' value will override 792 the other mitigation request. Two mitigation requests from a DOTS 793 client are overlapping if there is a common IP address, IP prefix, 794 FQDN, URI, or alias-name. To avoid maintaining a long list of 795 overlapping mitigation requests from a DOTS client and avoid error- 796 prone provisioning of mitigation requests from a DOTS client, the 797 overlapped lower numeric 'mid' MUST be automatically deleted and no 798 longer available at the DOTS server. 800 Figure 7 shows a PUT request example to signal that ports 80, 8080, 801 and 443 used by 2001:db8:6401::1 and 2001:db8:6401::2 servers are 802 under attack (illustrated in JSON diagnostic notation). The presence 803 of 'cdid' indicates that a server-domain DOTS gateway has modified 804 the initial PUT request sent by the DOTS client. 806 Header: PUT (Code=0.03) 807 Uri-Host: "www.example.com" 808 Uri-Path: ".well-known" 809 Uri-Path: "dots" 810 Uri-Path: "v1" 811 Uri-Path: "mitigate" 812 Uri-Path: "cdid=7eeaf349529eb55ed50113" 813 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 814 Uri-Path: "mid=123" 815 Content-Format: "application/cbor" 816 { 817 "ietf-dots-signal-channel:mitigation-scope": { 818 "scope": [ 819 { 820 "target-prefix": [ 821 "2001:db8:6401::1/128", 822 "2001:db8:6401::2/128" 823 ], 824 "target-port-range": [ 825 { 826 "lower-port": 80 827 }, 828 { 829 "lower-port": 443 830 }, 831 { 832 "lower-port": 8080 833 } 834 ], 835 "target-protocol": [ 836 6 837 ] 838 } 839 ] 840 } 841 } 843 Figure 7: PUT for DOTS Mitigation Request 845 The corresponding CBOR encoding format is shown in Figure 8. 847 A1 # map(1) 848 01 # unsigned(1) 849 A1 # map(1) 850 02 # unsigned(2) 851 81 # array(1) 852 A3 # map(3) 853 18 23 # unsigned(35) 854 82 # array(2) 855 74 # text(20) 856 323030313A6462383A363430313A3A312F313238 # "2001:db8:6401::1/128" 857 74 # text(20) 858 323030313A6462383A363430313A3A322F313238 # "2001:db8:6401::2/128" 859 05 # unsigned(5) 860 83 # array(3) 861 A1 # map(1) 862 06 # unsigned(6) 863 18 50 # unsigned(80) 864 A1 # map(1) 865 06 # unsigned(6) 866 19 01BB # unsigned(443) 867 A1 # map(1) 868 06 # unsigned(6) 869 19 1F90 # unsigned(8080) 870 08 # unsigned(8) 871 81 # array(1) 872 06 # unsigned(6) 874 Figure 8: PUT for DOTS Mitigation Request (CBOR) 876 In both DOTS signal and data channel sessions, the DOTS client MUST 877 authenticate itself to the DOTS server (Section 8). The DOTS server 878 may use the algorithm presented in Section 7 of [RFC7589] to derive 879 the DOTS client identity or username from the client certificate. 880 The DOTS client identity allows the DOTS server to accept mitigation 881 requests with scopes that the DOTS client is authorized to manage. 883 The DOTS server couples the DOTS signal and data channel sessions 884 using the DOTS client identity (e.g., client certificate, 'cuid') and 885 optionally the 'cdid' parameter value, so the DOTS server can 886 validate whether the aliases conveyed in the mitigation request were 887 indeed created by the same DOTS client using the DOTS data channel 888 session. If the aliases were not created by the DOTS client, the 889 DOTS server MUST return 4.00 (Bad Request) in the response. 891 The DOTS server couples the DOTS signal channel sessions using the 892 DOTS client identity and optionally the 'cdid' parameter value, and 893 the DOTS server uses 'mid' and 'cuid' Uri-Path parameter values to 894 detect duplicate mitigation requests. If the mitigation request 895 contains the 'alias-name' and other parameters identifying the target 896 resources (such as 'target-prefix', 'target-port-range', 'target- 897 fqdn', or 'target-uri'), the DOTS server appends the parameter values 898 in 'alias-name' with the corresponding parameter values in 'target- 899 prefix', 'target-port-range', 'target-fqdn', or 'target-uri'. 901 The DOTS server indicates the result of processing the PUT request 902 using CoAP response codes. CoAP 2.xx codes are success. CoAP 4.xx 903 codes are some sort of invalid requests (client errors). COAP 5.xx 904 codes are returned if the DOTS server has erred or is currently 905 unavailable to provide mitigation in response to the mitigation 906 request from the DOTS client. 908 Figure 9 shows an example response to a PUT request that is 909 successfully processed by a DOTS server (i.e., CoAP 2.xx response 910 codes). This PUT request is assumed to be relayed by a server-domain 911 DOTS gateway. 913 { 914 "ietf-dots-signal-channel:mitigation-scope": { 915 "cdid": "7eeaf349529eb55ed50113", 916 "scope": [ 917 { 918 "mid": 12332, 919 "lifetime": 3600 920 } 921 ] 922 } 923 } 925 Figure 9: 2.xx Response Body 927 If the request is missing a mandatory attribute, does not include 928 'cuid' or 'mid' Uri-Path options, includes multiple 'scope' 929 parameters, or contains invalid or unknown parameters, the DOTS 930 server MUST reply with 4.00 (Bad Request). DOTS agents can safely 931 ignore Vendor-Specific parameters they don't understand. 933 A DOTS server that receives a mitigation request with a lifetime set 934 to '0' MUST reply with a 4.00 (Bad Request). 936 If the DOTS server does not find the 'mid' parameter value conveyed 937 in the PUT request in its configuration data, it MAY accept the 938 mitigation request by sending back a 2.01 (Created) response to the 939 DOTS client; the DOTS server will consequently try to mitigate the 940 attack. 942 If the DOTS server finds the 'mid' parameter value conveyed in the 943 PUT request in its configuration data bound to that DOTS client, it 944 MAY update the mitigation request, and a 2.04 (Changed) response is 945 returned to indicate a successful update of the mitigation request. 947 If the request is conflicting with an existing mitigation request 948 from a different DOTS client, and the DOTS server decides to maintain 949 the conflicting mitigation request, the DOTS server returns 4.09 950 (Conflict) [RFC8132] to the requesting DOTS client. The response 951 includes enough information for a DOTS client to recognize the source 952 of the conflict as described below: 954 conflict-information: Indicates that a mitigation request is 955 conflicting with another mitigation request(s) from other DOTS 956 client(s). This optional attribute has the following structure: 958 conflict-status: Indicates the status of a conflicting mitigation 959 request. The following values are defined: 961 1: DOTS server has detected conflicting mitigation requests 962 from different DOTS clients. This mitigation request is 963 currently inactive until the conflicts are resolved. 964 Another mitigation request is active. 966 2: DOTS server has detected conflicting mitigation requests 967 from different DOTS clients. This mitigation request is 968 currently active. 970 3: DOTS server has detected conflicting mitigation requests 971 from different DOTS clients. All conflicting mitigation 972 requests are inactive. 974 conflict-cause: Indicates the cause of the conflict. The 975 following values are defined: 977 1: Overlapping targets. 'conflict-scope' provides more details 978 about the conflicting target clauses. 980 2: Conflicts with an existing white list. This code is 981 returned when the DDoS mitigation detects source addresses/ 982 prefixes in the white-listed ACLs are attacking the target. 984 3: CUID Collision. This code is returned when a DOTS client 985 uses a 'cuid' that is already used by another DOTS client. 986 This code is an indication that the request has been 987 rejected and a new request with a new 'cuid' is to be re- 988 sent by the DOTS client. Note that 'conflict-status', 989 'conflict-scope', and 'retry-timer' are not returned in the 990 error response. 992 conflict-scope: Indicates the conflict scope. It may include a 993 list of IP addresses, a list of prefixes, a list of port 994 numbers, a list of target protocols, a list of FQDNs, a list of 995 URIs, a list of alias-names, or references to conflicting ACLs. 997 retry-timer: Indicates, in seconds, the time after which the DOTS 998 client may re-issue the same request. The DOTS server returns 999 'retry-timer' only to DOTS client(s) for which a mitigation 1000 request is deactivated. Any retransmission of the same 1001 mitigation request before the expiry of this timer is likely to 1002 be rejected by the DOTS server for the same reasons. 1004 The retry-timer SHOULD be equal to the lifetime of the active 1005 mitigation request resulting in the deactivation of the 1006 conflicting mitigation request. The lifetime of the 1007 deactivated mitigation request will be updated to (retry-timer 1008 + 45 seconds), so the DOTS client can refresh the deactivated 1009 mitigation request after retry-timer seconds before expiry of 1010 lifetime and check if the conflict is resolved. 1012 For a mitigation request to continue beyond the initial negotiated 1013 lifetime, the DOTS client has to refresh the current mitigation 1014 request by sending a new PUT request. This PUT request MUST use the 1015 same 'mid' value, and MUST repeat all the other parameters as sent in 1016 the original mitigation request apart from a possible change to the 1017 lifetime parameter value. 1019 The DOTS gateway that inserted a 'cdid' in a request, MUST strip the 1020 'cdid' parameter in the corresponding response before forwarding the 1021 response to the DOTS client. If we consider the example depicted in 1022 Figure 9, the message that will be relayed by the DOTS gateway is 1023 shown in Figure 10. 1025 { 1026 "ietf-dots-signal-channel:mitigation-scope": { 1027 "scope": [ 1028 { 1029 "mid": 12332, 1030 "lifetime": 3600 1031 } 1032 ] 1033 } 1034 } 1036 Figure 10: 2.xx Response Body Relayed by a DOTS Gateway 1038 4.4.2. Retrieve Information Related to a Mitigation 1040 A GET request is used by a DOTS client to retrieve information 1041 (including status) of DOTS mitigations from a DOTS server. 1043 'cuid' is a mandatory Uri-Query parameter for GET requests. 1045 Uri-Query parameters with empty values MUST NOT be present in a 1046 request. 1048 The same considerations for manipulating 'cdid' parameter by server- 1049 domain DOTS gateways specified in Section 4.4.1 MUST be followed for 1050 GET requests. 1052 If the DOTS server does not find the 'mid' Uri-Query value conveyed 1053 in the GET request in its configuration data for the requesting DOTS 1054 client, it MUST respond with a 4.04 (Not Found) error response code. 1055 Likewise, the same error MUST be returned as a response to a request 1056 to retrieve all mitigation records (i.e., 'mid' Uri-Query is not 1057 defined) of a given DOTS client if the DOTS server does not find any 1058 mitigation record for that DOTS client. As a reminder, a DOTS client 1059 is identified by its identity (e.g., client certificate, 'cuid') and 1060 optionally the 'cdid'. 1062 The 'c' (content) parameter and its permitted values defined in 1063 [I-D.ietf-core-comi] can be used to retrieve non-configuration data 1064 (attack mitigation status), configuration data, or both. The DOTS 1065 server may support this optional filtering capability. It can safely 1066 ignore it if not supported. 1068 The following examples illustrate how a DOTS client retrieves active 1069 mitigation requests from a DOTS server. In particular: 1071 o Figure 11 shows the example of a GET request to retrieve all DOTS 1072 mitigation requests signaled by a DOTS client. 1074 o Figure 12 shows the example of a GET request to retrieve a 1075 specific DOTS mitigation request signaled by a DOTS client. The 1076 configuration data to be reported in the response is formatted in 1077 the same order as was processed by the DOTS server in the original 1078 mitigation request. 1080 These two examples assume the default of "c=a"; that is, the DOTS 1081 client asks for all data to be reported by the DOTS server. 1083 Header: GET (Code=0.01) 1084 Uri-Host: "host" 1085 Uri-Path: ".well-known" 1086 Uri-Path: "dots" 1087 Uri-Path: "v1" 1088 Uri-Path: "mitigate" 1089 Uri-Query: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1090 Observe: 0 1092 Figure 11: GET to Retrieve all DOTS Mitigation Requests 1094 Header: GET (Code=0.01) 1095 Uri-Host: "host" 1096 Uri-Path: ".well-known" 1097 Uri-Path: "dots" 1098 Uri-Path: "v1" 1099 Uri-Path: "mitigate" 1100 Uri-Query: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1101 Uri-Query: "mid=12332" 1102 Observe: 0 1104 Figure 12: GET to Retrieve a Specific DOTS Mitigation Request 1106 Figure 13 shows a response example of all active mitigation requests 1107 associated with the DOTS client as maintained by the DOTS server. 1108 The response indicates the mitigation status of each mitigation 1109 request. 1111 { 1112 "ietf-dots-signal-channel:mitigation-scope": { 1113 "scope": [ 1114 { 1115 "mid": 12332, 1116 "mitigation-start": 1507818434, 1117 "target-prefix": [ 1118 "2001:db8:6401::1/128", 1119 "2001:db8:6401::2/128" 1120 ], 1121 "target-protocol": [ 1122 17 1123 ], 1124 "lifetime": 1800, 1125 "status": 2, 1126 "bytes-dropped": 134334555, 1127 "bps-dropped": 43344, 1128 "pkts-dropped": 333334444, 1129 "pps-dropped": 432432 1130 }, 1131 { 1132 "mid": 12333, 1133 "mitigation-start": 1507818393, 1134 "target-prefix": [ 1135 "2001:db8:6401::1/128", 1136 "2001:db8:6401::2/128" 1137 ], 1138 "target-protocol": [ 1139 6 1140 ], 1141 "lifetime": 1800, 1142 "status": 3, 1143 "bytes-dropped": 0, 1144 "bps-dropped": 0, 1145 "pkts-dropped": 0, 1146 "pps-dropped": 0 1147 } 1148 ] 1149 } 1150 } 1152 Figure 13: Response Body to a Get Request 1154 The mitigation status parameters are described below: 1156 mitigation-start: Mitigation start time is expressed in seconds 1157 relative to 1970-01-01T00:00Z in UTC time (Section 2.4.1 of 1159 [RFC7049]). The CBOR encoding is modified so that the leading tag 1160 1 (epoch-based date/time) MUST be omitted. 1162 This is a mandatory attribute. 1164 lifetime: The remaining lifetime of the mitigation request, in 1165 seconds. 1167 This is a mandatory attribute. 1169 status: Status of attack mitigation. The various possible values of 1170 'status' parameter are explained in Table 2. 1172 This is a mandatory attribute. 1174 bytes-dropped: The total dropped byte count for the mitigation 1175 request since the attack mitigation is triggered. The count wraps 1176 around when it reaches the maximum value of unsigned integer64. 1178 This is an optional attribute. 1180 bps-dropped: The average number of dropped bytes per second for the 1181 mitigation request since the attack mitigation is triggered. This 1182 SHOULD be a five-minute average. 1184 This is an optional attribute. 1186 pkts-dropped: The total number of dropped packet count for the 1187 mitigation request since the attack mitigation is triggered. The 1188 count wraps around when it reaches the maximum value of unsigned 1189 integer64. 1191 This is an optional attribute. 1193 pps-dropped: The average number of dropped packets per second for 1194 the mitigation request since the attack mitigation is triggered. 1195 This SHOULD be a five-minute average. 1197 This is an optional attribute. 1199 +-----------+-------------------------------------------------------+ 1200 | Parameter | Description | 1201 | Value | | 1202 +-----------+-------------------------------------------------------+ 1203 | 1 | Attack mitigation is in progress (e.g., changing the | 1204 | | network path to re-route the inbound traffic to DOTS | 1205 | | mitigator). | 1206 +-----------+-------------------------------------------------------+ 1207 | 2 | Attack is successfully mitigated (e.g., traffic is | 1208 | | redirected to a DDoS mitigator and attack traffic is | 1209 | | dropped). | 1210 +-----------+-------------------------------------------------------+ 1211 | 3 | Attack has stopped and the DOTS client can withdraw | 1212 | | the mitigation request. | 1213 +-----------+-------------------------------------------------------+ 1214 | 4 | Attack has exceeded the mitigation provider | 1215 | | capability. | 1216 +-----------+-------------------------------------------------------+ 1217 | 5 | DOTS client has withdrawn the mitigation request and | 1218 | | the mitigation is active but terminating. | 1219 +-----------+-------------------------------------------------------+ 1220 | 6 | Attack mitigation is now terminated. | 1221 +-----------+-------------------------------------------------------+ 1222 | 7 | Attack mitigation is withdrawn. | 1223 +-----------+-------------------------------------------------------+ 1224 | 8 | Attack mitigation is rejected. | 1225 +-----------+-------------------------------------------------------+ 1227 Table 2: Values of 'status' Parameter 1229 The Observe Option defined in [RFC7641] extends the CoAP core 1230 protocol with a mechanism for a CoAP client to "observe" a resource 1231 on a CoAP server: The client retrieves a representation of the 1232 resource and requests this representation be updated by the server as 1233 long as the client is interested in the resource. A DOTS client 1234 conveys the Observe Option set to '0' in the GET request to receive 1235 unsolicited notifications of attack mitigation status from the DOTS 1236 server. 1238 Unidirectional notifications within the bidirectional signal channel 1239 allows unsolicited message delivery, enabling asynchronous 1240 notifications between the agents. Due to the higher likelihood of 1241 packet loss during a DDoS attack, the DOTS server periodically sends 1242 attack mitigation status to the DOTS client and also notifies the 1243 DOTS client whenever the status of the attack mitigation changes. If 1244 the DOTS server cannot maintain an RTT estimate, it SHOULD NOT send 1245 more than one unsolicited notification every 3 seconds, and SHOULD 1246 use an even less aggressive rate whenever possible (case 2 in 1247 Section 3.1.3 of [RFC8085]). 1249 When conflicting requests are detected, the DOTS server enforces the 1250 corresponding policy (e.g., accept all requests, reject all requests, 1251 accept only one request but reject all the others, ...). It is 1252 assumed that this policy is supplied by the DOTS server administrator 1253 or it is a default behavior of the DOTS server implementation. Then, 1254 the DOTS server sends notification message(s) to the DOTS client(s) 1255 at the origin of the conflict (refer to the conflict parameters 1256 defined in Section 4.4.1). A conflict notification message includes 1257 information about the conflict cause, scope, and the status of the 1258 mitigation request(s). For example, 1260 o A notification message with 'status' code set to '8 (Attack 1261 mitigation is rejected)' and 'conflict-status' set to '1' is sent 1262 to a DOTS client to indicate that this mitigation request is 1263 rejected because a conflict is detected. 1265 o A notification message with 'status' code set to '7 (Attack 1266 mitigation is withdrawn)' and 'conflict-status' set to '1' is sent 1267 to a DOTS client to indicate that an active mitigation request is 1268 deactivated because a conflict is detected. 1270 o A notification message with 'status' code set to '1 (Attack 1271 mitigation is in progress)' and 'conflict-status' set to '2' is 1272 sent to a DOTS client to indicate that this mitigation request is 1273 in progress, but a conflict is detected. 1275 Upon receipt of a conflict notification message indicating that a 1276 mitigation request is deactivated because of a conflict, a DOTS 1277 client MUST NOT resend the same mitigation request before the expiry 1278 of 'retry-timer'. It is also recommended that DOTS clients support 1279 means to alert administrators about mitigation conflicts. 1281 A DOTS client that is no longer interested in receiving notifications 1282 from the DOTS server can simply "forget" the observation. When the 1283 DOTS server sends the next notification, the DOTS client will not 1284 recognize the token in the message and thus will return a Reset 1285 message. This causes the DOTS server to remove the associated entry. 1286 Alternatively, the DOTS client can explicitly deregister itself by 1287 issuing a GET request that has the Token field set to the token of 1288 the observation to be cancelled and includes an Observe Option with 1289 the value set to '1' (deregister). 1291 Figure 14 shows an example of a DOTS client requesting a DOTS server 1292 to send notifications related to a given mitigation request. 1294 +-----------+ +-----------+ 1295 |DOTS client| |DOTS server| 1296 +-----------+ +-----------+ 1297 | | 1298 | GET / | 1299 | Token: 0x4a | Registration 1300 | Observe: 0 | 1301 +---------------------------------->| 1302 | | 1303 | 2.05 Content | 1304 | Token: 0x4a | Notification of 1305 | Observe: 12 | the current state 1306 | status: "mitigation in progress" | 1307 | | 1308 |<----------------------------------+ 1309 | 2.05 Content | 1310 | Token: 0x4a | Notification upon 1311 | Observe: 44 | a state change 1312 | status: "mitigation complete" | 1313 | | 1314 |<----------------------------------+ 1315 | 2.05 Content | 1316 | Token: 0x4a | Notification upon 1317 | Observe: 60 | a state change 1318 | status: "attack stopped" | 1319 |<----------------------------------+ 1320 | | 1322 Figure 14: Notifications of Attack Mitigation Status 1324 4.4.2.1. DOTS Clients Polling for Mitigation Status 1326 The DOTS client can send the GET request at frequent intervals 1327 without the Observe Option to retrieve the configuration data of the 1328 mitigation request and non-configuration data (i.e., the attack 1329 status). The frequency of polling the DOTS server to get the 1330 mitigation status SHOULD follow the transmission guidelines in 1331 Section 3.1.3 of [RFC8085]. 1333 If the DOTS server has been able to mitigate the attack and the 1334 attack has stopped, the DOTS server indicates as such in the status. 1335 In such case, the DOTS client recalls the mitigation request by 1336 issuing a DELETE request for this mitigation request (Section 4.4.4). 1338 A DOTS client SHOULD react to the status of the attack as per the 1339 information sent by the DOTS server rather than acknowledging by 1340 itself, using its own means, that the attack has been mitigated. 1341 This ensures that the DOTS client does not recall a mitigation 1342 request prematurely because it is possible that the DOTS client does 1343 not sense the DDoS attack on its resources, but the DOTS server could 1344 be actively mitigating the attack because the attack is not 1345 completely averted. 1347 4.4.3. Efficacy Update from DOTS Clients 1349 While DDoS mitigation is active, due to the likelihood of packet 1350 loss, a DOTS client MAY periodically transmit DOTS mitigation 1351 efficacy updates to the relevant DOTS server. A PUT request is used 1352 to convey the mitigation efficacy update to the DOTS server. 1354 The PUT request used for efficacy update MUST include all the 1355 parameters used in the PUT request to carry the DOTS mitigation 1356 request (Section 4.4.1) unchanged apart from the 'lifetime' parameter 1357 value. If this is not the case, the DOTS server MUST reject the 1358 request with a 4.00 (Bad Request). 1360 The If-Match Option (Section 5.10.8.1 of [RFC7252]) with an empty 1361 value is used to make the PUT request conditional on the current 1362 existence of the mitigation request. If UDP is used as transport, 1363 CoAP requests may arrive out-of-order. For example, the DOTS client 1364 may send a PUT request to convey an efficacy update to the DOTS 1365 server followed by a DELETE request to withdraw the mitigation 1366 request, but the DELETE request arrives at the DOTS server before the 1367 PUT request. To handle out-of-order delivery of requests, if an If- 1368 Match Option is present in the PUT request and the 'mid' in the 1369 request matches a mitigation request from that DOTS client, the 1370 request is processed by the DOTS server. If no match is found, the 1371 PUT request is silently ignored by the DOTS server. 1373 An example of an efficacy update message, which includes an If-Match 1374 Option with an empty value, is depicted in Figure 15. 1376 Header: PUT (Code=0.03) 1377 Uri-Host: "host" 1378 Uri-Path: ".well-known" 1379 Uri-Path: "dots" 1380 Uri-Path: "v1" 1381 Uri-Path: "mitigate" 1382 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1383 Uri-Path: "mid=123" 1384 Content-Format: "application/cbor" 1385 If-Match: 1386 { 1387 "ietf-dots-signal-channel:mitigation-scope": { 1388 "scope": [ 1389 { 1390 "target-prefix": [ 1391 "string" 1392 ], 1393 "target-port-range": [ 1394 { 1395 "lower-port": integer, 1396 "upper-port": integer 1397 } 1398 ], 1399 "target-protocol": [ 1400 integer 1401 ], 1402 "target-fqdn": [ 1403 "string" 1404 ], 1405 "target-uri": [ 1406 "string" 1407 ], 1408 "alias-name": [ 1409 "string" 1410 ], 1411 "lifetime": integer, 1412 "attack-status": integer 1413 } 1414 ] 1415 } 1416 } 1418 Figure 15: Efficacy Update 1420 The 'attack-status' parameter is a mandatory attribute when 1421 performing an efficacy update. The various possible values contained 1422 in the 'attack-status' parameter are described in Table 3. 1424 +-----------+-------------------------------------------------------+ 1425 | Parameter | Description | 1426 | value | | 1427 +-----------+-------------------------------------------------------+ 1428 | 1 | The DOTS client determines that it is still under | 1429 | | attack. | 1430 +-----------+-------------------------------------------------------+ 1431 | 2 | The DOTS client determines that the attack is | 1432 | | successfully mitigated (e.g., attack traffic is not | 1433 | | seen). | 1434 +-----------+-------------------------------------------------------+ 1436 Table 3: Values of 'attack-status' Parameter 1438 The DOTS server indicates the result of processing a PUT request 1439 using CoAP response codes. The response code 2.04 (Changed) is 1440 returned if the DOTS server has accepted the mitigation efficacy 1441 update. The error response code 5.03 (Service Unavailable) is 1442 returned if the DOTS server has erred or is incapable of performing 1443 the mitigation. 1445 4.4.4. Withdraw a Mitigation 1447 DELETE requests are used to withdraw DOTS mitigation requests from 1448 DOTS servers (Figure 16). 1450 'cuid' and 'mid' are mandatory Uri-Query parameters for DELETE 1451 requests. 1453 The same considerations for manipulating 'cdid' parameter by DOTS 1454 gateways, as specified in Section 4.4.1, MUST be followed for DELETE 1455 requests. Uri-Query parameters with empty values MUST NOT be present 1456 in a request. 1458 Header: DELETE (Code=0.04) 1459 Uri-Host: "host" 1460 Uri-Path: ".well-known" 1461 Uri-Path: "dots" 1462 Uri-Path: "v1" 1463 Uri-Path: "mitigate" 1464 Uri-Query: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1465 Uri-Query: "mid=123" 1467 Figure 16: Withdraw a DOTS Mitigation 1469 If the DELETE request does not include 'cuid' and 'mid' parameters, 1470 the DOTS server MUST reply with a 4.00 (Bad Request). 1472 Once the request is validated, the DOTS server immediately 1473 acknowledges a DOTS client's request to withdraw the DOTS signal 1474 using 2.02 (Deleted) response code with no response payload. A 2.02 1475 (Deleted) Response Code is returned even if the 'mid' parameter value 1476 conveyed in the DELETE request does not exist in its configuration 1477 data before the request. 1479 If the DOTS server finds the 'mid' parameter value conveyed in the 1480 DELETE request in its configuration data for the DOTS client, then to 1481 protect against route or DNS flapping caused by a DOTS client rapidly 1482 removing a mitigation, and to dampen the effect of oscillating 1483 attacks, the DOTS server MAY allow mitigation to continue for a 1484 limited period after acknowledging a DOTS client's withdrawal of a 1485 mitigation request. During this period, the DOTS server status 1486 messages SHOULD indicate that mitigation is active but terminating 1487 (Section 4.4.2). 1489 The initial active-but-terminating period SHOULD be sufficiently long 1490 to absorb latency incurred by route propagation. The active-but- 1491 terminating period SHOULD be set by default to 120 seconds. If the 1492 client requests mitigation again before the initial active-but- 1493 terminating period elapses, the DOTS server MAY exponentially 1494 increase the active-but-terminating period up to a maximum of 300 1495 seconds (5 minutes). 1497 After the active-but-terminating period elapses, the DOTS server MUST 1498 treat the mitigation as terminated, as the DOTS client is no longer 1499 responsible for the mitigation. For example, if there is a financial 1500 relationship between the DOTS client and server domains, the DOTS 1501 client stops incurring cost at this point. 1503 4.5. DOTS Signal Channel Session Configuration 1505 A DOTS client can negotiate, configure, and retrieve the DOTS signal 1506 channel session behavior with its DOTS peers. The DOTS signal 1507 channel can be used, for example, to configure the following: 1509 a. Heartbeat interval (heartbeat-interval): DOTS agents regularly 1510 send heartbeats (CoAP Ping/Pong) to each other after mutual 1511 authentication is successfully completed in order to keep the 1512 DOTS signal channel open. Heartbeat messages are exchanged 1513 between DOTS agents every 'heartbeat-interval' seconds to detect 1514 the current status of the DOTS signal channel session. 1516 b. Missing heartbeats allowed (missing-hb-allowed): This variable 1517 indicates the maximum number of consecutive heartbeat messages 1518 for which a DOTS agent did not receive a response before 1519 concluding that the session is disconnected or defunct. 1521 c. Acceptable signal loss ratio: Maximum retransmissions, 1522 retransmission timeout value, and other message transmission 1523 parameters for the DOTS signal channel. 1525 The same or distinct configuration sets may be used during times when 1526 a mitigation is active ('mitigating-config') and when no mitigation 1527 is active ('idle-config'). This is particularly useful for DOTS 1528 servers that might want to reduce heartbeat frequency or cease 1529 heartbeat exchanges when an active DOTS client has not requested 1530 mitigation. If distinct configurations are used, DOTS agents MUST 1531 follow the appropriate configuration set as a function of the 1532 mitigation activity (e.g., if no mitigation request is active, 'idle- 1533 config'-related values must be followed). Additionally, DOTS agents 1534 MUST automatically switch to the other configuration upon a change in 1535 the mitigation activity (e.g., if an attack mitigation is launched 1536 after a peacetime, the DOTS agent switches from 'idle-config' to 1537 'mitigating-config'-related values). 1539 Requests and responses are deemed reliable by marking them as 1540 Confirmable (CON) messages. DOTS signal channel session 1541 configuration requests and responses are marked as Confirmable 1542 messages. As explained in Section 2.1 of [RFC7252], a Confirmable 1543 message is retransmitted using a default timeout and exponential 1544 back-off between retransmissions, until the DOTS server sends an 1545 Acknowledgement message (ACK) with the same Message ID conveyed from 1546 the DOTS client. 1548 Message transmission parameters are defined in Section 4.8 of 1549 [RFC7252]. The DOTS server can either piggyback the response in the 1550 acknowledgement message or, if the DOTS server cannot respond 1551 immediately to a request carried in a Confirmable message, it simply 1552 responds with an Empty Acknowledgement message so that the DOTS 1553 client can stop retransmitting the request. Empty Acknowledgement 1554 message is explained in Section 2.2 of [RFC7252]. When the response 1555 is ready, the server sends it in a new Confirmable message which in 1556 turn needs to be acknowledged by the DOTS client (see Sections 5.2.1 1557 and 5.2.2 of [RFC7252]). Requests and responses exchanged between 1558 DOTS agents during peacetime are marked as Confirmable messages. 1560 Implementation Note: A DOTS client that receives a response in a 1561 CON message may want to clean up the message state right after 1562 sending the ACK. If that ACK is lost and the DOTS server 1563 retransmits the CON, the DOTS client may no longer have any state 1564 that would help it correlate this response, thereby unexpecting 1565 the retransmission message. The DOTS client will send a Reset 1566 message so it does not receive any more retransmissions. This 1567 behavior is normal and not an indication of an error (see 1568 Section 5.3.2 of [RFC7252] for more details). 1570 4.5.1. Discover Configuration Parameters 1572 A GET request is used to obtain acceptable (e.g., minimum and maximum 1573 values) and current configuration parameters on the DOTS server for 1574 DOTS signal channel session configuration. This procedure occurs 1575 between a DOTS client and its immediate peer DOTS server. As such, 1576 this GET request MUST NOT be relayed by an on-path DOTS gateway. 1578 Figure 17 shows how to obtain acceptable configuration parameters for 1579 the DOTS server. 1581 Header: GET (Code=0.01) 1582 Uri-Host: "host" 1583 Uri-Path: ".well-known" 1584 Uri-Path: "dots" 1585 Uri-Path: "v1" 1586 Uri-Path: "config" 1588 Figure 17: GET to Retrieve Configuration 1590 The DOTS server in the 2.05 (Content) response conveys the current, 1591 minimum, and maximum attribute values acceptable by the DOTS server 1592 (Figure 18). 1594 Content-Format: "application/cbor" 1595 { 1596 "ietf-dots-signal-channel:signal-config": { 1597 "mitigating-config": { 1598 "heartbeat-interval": { 1599 "max-value": integer, 1600 "min-value": integer, 1601 "current-value": integer 1602 }, 1603 "missing-hb-allowed": { 1604 "max-value": integer, 1605 "min-value": integer, 1606 "current-value": integer 1607 }, 1608 "max-retransmit": { 1609 "max-value": integer, 1610 "min-value": integer, 1611 "current-value": integer 1612 }, 1613 "ack-timeout": { 1614 "max-value": integer, 1615 "min-value": integer, 1616 "current-value": integer 1617 }, 1618 "ack-random-factor": { 1619 "max-value-decimal": number, 1620 "min-value-decimal": number, 1621 "current-value-decimal": number 1622 } 1623 }, 1624 "idle-config": { 1625 "heartbeat-interval": { 1626 "max-value": integer, 1627 "min-value": integer, 1628 "current-value": integer 1629 }, 1630 "missing-hb-allowed": { 1631 "max-value": integer, 1632 "min-value": integer, 1633 "current-value": integer 1634 }, 1635 "max-retransmit": { 1636 "max-value": integer, 1637 "min-value": integer, 1638 "current-value": integer 1639 }, 1640 "ack-timeout": { 1641 "max-value": integer, 1642 "min-value": integer, 1643 "current-value": integer 1644 }, 1645 "ack-random-factor": { 1646 "max-value-decimal": number, 1647 "min-value-decimal": number, 1648 "current-value-decimal": number 1649 } 1650 }, 1651 "trigger-mitigation": boolean, 1652 "config-interval": integer 1653 } 1654 } 1656 Figure 18: GET Configuration Response Body 1658 The parameters in Figure 18 are described below: 1660 mitigation-config: Set of configuration parameters to use when a 1661 mitigation is active. The following parameters may be included: 1663 heartbeat-interval: Time interval in seconds between two 1664 consecutive heartbeat messages. 1666 '0' is used to disable the heartbeat mechanism. 1668 This is an optional attribute. 1670 missing-hb-allowed: Maximum number of consecutive heartbeat 1671 messages for which the DOTS agent did not receive a response 1672 before concluding that the session is disconnected. 1674 This is an optional attribute. 1676 max-retransmit: Maximum number of retransmissions for a message 1677 (referred to as MAX_RETRANSMIT parameter in CoAP). 1679 This is an optional attribute. 1681 ack-timeout: Timeout value in seconds used to calculate the 1682 initial retransmission timeout value (referred to as 1683 ACK_TIMEOUT parameter in CoAP). 1685 This is an optional attribute. 1687 ack-random-factor: Random factor used to influence the timing of 1688 retransmissions (referred to as ACK_RANDOM_FACTOR parameter in 1689 CoAP). 1691 This is an optional attribute. 1693 idle-config: Set of configuration parameters to use when no 1694 mitigation is active. This attribute has the same structure as 1695 'mitigating-config'. 1697 trigger-mitigation: If the parameter value is set to 'false', then 1698 DDoS mitigation is triggered only when the DOTS signal channel 1699 session is lost. Automated mitigation on loss of signal is 1700 discussed in Section 3.3.3 of [I-D.ietf-dots-architecture]. 1702 If the DOTS client ceases to respond to heartbeat messages, the 1703 DOTS server can detect that the DOTS session is lost. 1705 The default value of the parameter is 'true'. 1707 This is an optional attribute. 1709 config-interval: This parameter is returned to indicate the time 1710 interval expressed in seconds, which a DOTS agent must wait for 1711 before re-contacting its peer in order to retrieve the signal 1712 channel configuration data. This parameter is only valid for a 1713 GET response. It MUST NOT be used in a PUT request. 1715 '0' is used to disable this configuration refresh mechanism. 1717 If a non-zero value of 'config-interval' is received by a DOTS 1718 client, it has to issue a PUT request to refresh the configuration 1719 parameters for the signal channel before the expiry of 'config- 1720 interval'. When a DDoS attack is active, refresh requests MUST 1721 NOT be sent by DOTS clients and the DOTS server MUST NOT terminate 1722 the (D)TLS session after the expiry of 'config-interval'. 1724 This mechanism allows updating the configuration data if a change 1725 occurs at the DOTS server side. For example, the new 1726 configuration may instruct a DOTS client to cease heartbeats or 1727 reduce heartbeat frequency. 1729 If this parameter is not returned, this is equivalent to receiving 1730 a 'config-interval' value set to '0'. 1732 If a DOTS server detects that a misbehaving DOTS client does not 1733 contact the DOTS server after the expiry of 'config-interval', in 1734 order to retrieve the signal channel configuration data, it MAY 1735 terminate the (D)TLS session. A (D)TLS session is terminated by 1736 the receipt of an authenticated message that closes the connection 1737 (e.g., a fatal alert (Section 7.2 of [RFC5246])). 1739 This is an optional attribute. 1741 Figure 19 shows an example of acceptable and current configuration 1742 parameters on a DOTS server for DOTS signal channel session 1743 configuration. The same acceptable configuration is used during 1744 attack and peace times. 1746 Content-Format: "application/cbor" 1747 { 1748 "ietf-dots-signal-channel:signal-config": { 1749 "mitigating-config": { 1750 "heartbeat-interval": { 1751 "max-value": 240, 1752 "min-value": 15, 1753 "current-value": 30 1754 }, 1755 "missing-hb-allowed": { 1756 "max-value": 9, 1757 "min-value": 3, 1758 "current-value": 5 1759 }, 1760 "max-retransmit": { 1761 "max-value": 15, 1762 "min-value": 2, 1763 "current-value": 3 1764 }, 1765 "ack-timeout": { 1766 "max-value": 30, 1767 "min-value": 1, 1768 "current-value": 2 1769 }, 1770 "ack-random-factor": { 1771 "max-value-decimal": 4.0, 1772 "min-value-decimal": 1.1, 1773 "current-value-decimal": 1.5 1774 } 1775 }, 1776 "idle-config": { 1777 "heartbeat-interval": { 1778 "max-value": 240, 1779 "min-value": 15, 1780 "current-value": 30 1781 }, 1782 "missing-hb-allowed": { 1783 "max-value": 9, 1784 "min-value": 3, 1785 "current-value": 5 1786 }, 1787 "max-retransmit": { 1788 "max-value": 15, 1789 "min-value": 2, 1790 "current-value": 3 1791 }, 1792 "ack-timeout": { 1793 "max-value": 30, 1794 "min-value": 1, 1795 "current-value": 2 1796 }, 1797 "ack-random-factor": { 1798 "max-value-decimal": 4.0, 1799 "min-value-decimal": 1.1, 1800 "current-value-decimal": 1.5 1801 } 1802 }, 1803 "trigger-mitigation": true, 1804 "config-interval": 3600 1805 } 1806 } 1808 Figure 19: Example of a Configuration Response Body 1810 4.5.2. Convey DOTS Signal Channel Session Configuration 1812 A PUT request is used to convey the configuration parameters for the 1813 signal channel (e.g., heartbeat interval, maximum retransmissions). 1814 Message transmission parameters for CoAP are defined in Section 4.8 1815 of [RFC7252]. The RECOMMENDED values of transmission parameter 1816 values are ack-timeout (2 seconds), max-retransmit (3), ack-random- 1817 factor (1.5). In addition to those parameters, the RECOMMENDED 1818 specific DOTS transmission parameter values are 'heartbeat-interval' 1819 (30 seconds) and 'missing-hb-allowed' (5). 1821 Note: heartbeat-interval should be tweaked to also assist DOTS 1822 messages for NAT traversal (SIG-010 of 1823 [I-D.ietf-dots-requirements]). According to [RFC8085], keepalive 1824 messages must not be sent more frequently than once every 15 1825 seconds and should use longer intervals when possible. 1826 Furthermore, [RFC4787] recommends NATs to use a state timeout of 2 1827 minutes or longer, but experience shows that sending packets every 1828 15 to 30 seconds is necessary to prevent the majority of 1829 middleboxes from losing state for UDP flows. From that 1830 standpoint, this specification recommends a minimum heartbeat- 1831 interval of 15 seconds and a maximum heartbeat-interval of 240 1832 seconds. The recommended value of 30 seconds is selected to 1833 anticipate the expiry of NAT state. 1835 A heartbeat-interval of 30 seconds may be seen as too chatty in 1836 some deployments. For such deployments, DOTS agents may negotiate 1837 longer heartbeat-interval values to prevent any network overload 1838 with too frequent keepalives. 1840 Different heartbeat intervals can be defined for 'mitigation- 1841 config' and 'idle-config' to reduce being too chatty during idle 1842 times. If there is an on-path translator between the DOTS client 1843 (standalone or part of a DOTS gateway) and the DOTS server, the 1844 'mitigation-config' heartbeat-interval has to be smaller than the 1845 translator session timeout. It is recommended that the 'idle- 1846 config' heartbeat-interval is also smaller than the translator 1847 session timeout to prevent translator transversal issues, or set 1848 to '0'. Means to discover the lifetime assigned by a translator 1849 are out of scope. 1851 When a confirmable "CoAP Ping" is sent, and if there is no response, 1852 the "CoAP Ping" is retransmitted max-retransmit number of times by 1853 the CoAP layer using an initial timeout set to a random duration 1854 between ack-timeout and (ack-timeout*ack-random-factor) and 1855 exponential back-off between retransmissions. By choosing the 1856 recommended transmission parameters, the "CoAP Ping" will timeout 1857 after 45 seconds. If the DOTS agent does not receive any response 1858 from the peer DOTS agent for 'missing-hb-allowed' number of 1859 consecutive "CoAP Ping" confirmable messages, it concludes that the 1860 DOTS signal channel session is disconnected. A DOTS client MUST NOT 1861 transmit a "CoAP Ping" while waiting for the previous "CoAP Ping" 1862 response from the same DOTS server. 1864 If the DOTS agent wishes to change the default values of message 1865 transmission parameters, it should follow the guidance given in 1866 Section 4.8.1 of [RFC7252]. The DOTS agents MUST use the negotiated 1867 values for message transmission parameters and default values for 1868 non-negotiated message transmission parameters. 1870 The signal channel session configuration is applicable to a single 1871 DOTS signal channel session between DOTS agents, so the 'cuid' Uri- 1872 Path MUST NOT be used. 1874 Header: PUT (Code=0.03) 1875 Uri-Host: "host" 1876 Uri-Path: ".well-known" 1877 Uri-Path: "dots" 1878 Uri-Path: "v1" 1879 Uri-Path: "config" 1880 Uri-Path: "sid=123" 1881 Content-Format: "application/cbor" 1882 { 1883 "ietf-dots-signal-channel:signal-config": { 1884 "mitigating-config": { 1885 "heartbeat-interval": { 1886 "current-value": integer 1887 }, 1888 "missing-hb-allowed": { 1889 "current-value": integer 1890 }, 1891 "max-retransmit": { 1892 "current-value": integer 1893 }, 1894 "ack-timeout": { 1895 "current-value": integer 1896 }, 1897 "ack-random-factor": { 1898 "current-value-decimal": number 1899 } 1900 }, 1901 "idle-config": { 1902 "heartbeat-interval": { 1903 "current-value": integer 1904 }, 1905 "missing-hb-allowed": { 1906 "current-value": integer 1907 }, 1908 "max-retransmit": { 1909 "current-value": integer 1910 }, 1911 "ack-timeout": { 1912 "current-value": integer 1913 }, 1914 "ack-random-factor": { 1915 "current-value-decimal": number 1916 } 1917 }, 1918 "trigger-mitigation": boolean 1919 } 1920 } 1922 Figure 20: PUT to Convey the DOTS Signal Channel Session 1923 Configuration Data 1925 The additional Uri-Path parameter to those defined in Table 1 is as 1926 follows: 1928 sid: Session Identifier is an identifier for the DOTS signal channel 1929 session configuration data represented as an integer. This 1930 identifier MUST be generated by DOTS clients. This document does 1931 not make any assumption about how this identifier is generated. 1933 This is a mandatory attribute. 1935 The meaning of the parameters in the CBOR body is defined in 1936 Section 4.5.1. 1938 At least one of the attributes 'heartbeat-interval', 'missing-hb- 1939 allowed', 'max-retransmit', 'ack-timeout', 'ack-random-factor', and 1940 'trigger-mitigation' MUST be present in the PUT request. 1942 The PUT request with a higher numeric 'sid' value overrides the DOTS 1943 signal channel session configuration data installed by a PUT request 1944 with a lower numeric 'sid' value. To avoid maintaining a long list 1945 of 'sid' requests from a DOTS client, the lower numeric 'sid' MUST be 1946 automatically deleted and no longer available at the DOTS server. 1948 Figure 21 shows a PUT request example to convey the configuration 1949 parameters for the DOTS signal channel. In this example, heartbeat 1950 mechanism is disabled when no mitigation is active, while the 1951 heartbeat interval is set to '91' when a mitigation is active. 1953 Header: PUT (Code=0.03) 1954 Uri-Host: "www.example.com" 1955 Uri-Path: ".well-known" 1956 Uri-Path: "dots" 1957 Uri-Path: "v1" 1958 Uri-Path: "config" 1959 Uri-Path: "sid=123" 1960 Content-Format: "application/cbor" 1961 { 1962 "ietf-dots-signal-channel:signal-config": { 1963 "mitigating-config": { 1964 "heartbeat-interval": { 1965 "current-value": 91 1966 }, 1967 "missing-hb-allowed": { 1968 "current-value": 3 1969 }, 1970 "max-retransmit": { 1971 "current-value": 7 1972 }, 1973 "ack-timeout": { 1974 "current-value": 5 1975 }, 1976 "ack-random-factor": { 1977 "current-value-decimal": 1.5 1978 } 1979 }, 1980 "idle-config": { 1981 "heartbeat-interval": { 1982 "current-value": 0 1983 }, 1984 "max-retransmit": { 1985 "current-value": 7 1986 }, 1987 "ack-timeout": { 1988 "current-value": 5 1989 }, 1990 "ack-random-factor": { 1991 "current-value-decimal": 1.5 1992 } 1993 }, 1994 "trigger-mitigation": false 1995 } 1996 } 1998 Figure 21: PUT to Convey the Configuration Parameters 2000 The DOTS server indicates the result of processing the PUT request 2001 using CoAP response codes: 2003 o If the request is missing a mandatory attribute, does not include 2004 a 'sid' Uri-Path, or contains one or more invalid or unknown 2005 parameters, 4.00 (Bad Request) MUST be returned in the response. 2007 o If the DOTS server does not find the 'sid' parameter value 2008 conveyed in the PUT request in its configuration data and if the 2009 DOTS server has accepted the configuration parameters, then a 2010 response code 2.01 (Created) is returned in the response. 2012 o If the DOTS server finds the 'sid' parameter value conveyed in the 2013 PUT request in its configuration data and if the DOTS server has 2014 accepted the updated configuration parameters, 2.04 (Changed) MUST 2015 be returned in the response. 2017 o If any of the 'heartbeat-interval', 'missing-hb-allowed', 'max- 2018 retransmit', 'target-protocol', 'ack-timeout', and 'ack-random- 2019 factor' attribute values are not acceptable to the DOTS server, 2020 4.22 (Unprocessable Entity) MUST be returned in the response. 2021 Upon receipt of this error code, the DOTS client SHOULD request 2022 the maximum and minimum attribute values acceptable to the DOTS 2023 server (Section 4.5.1). 2025 The DOTS client may re-try and send the PUT request with updated 2026 attribute values acceptable to the DOTS server. 2028 4.5.3. Delete DOTS Signal Channel Session Configuration 2030 A DELETE request is used to delete the installed DOTS signal channel 2031 session configuration data (Figure 22). 2033 Header: DELETE (Code=0.04) 2034 Uri-Host: "host" 2035 Uri-Path: ".well-known" 2036 Uri-Path: "dots" 2037 Uri-Path: "v1" 2038 Uri-Path: "config" 2039 Uri-Query: "sid=123" 2041 Figure 22: DELETE Configuration 2043 The DOTS server resets the DOTS signal channel session configuration 2044 back to the default values and acknowledges a DOTS client's request 2045 to remove the DOTS signal channel session configuration using 2.02 2046 (Deleted) response code. 2048 Upon bootsrapping or reboot, a DOTS client MAY send a DELETE request 2049 to set the configuration parameters to default values. Such a 2050 request does not include any 'sid'. 2052 4.6. Redirected Signaling 2054 Redirected DOTS signaling is discussed in detail in Section 3.2.2 of 2055 [I-D.ietf-dots-architecture]. 2057 If a DOTS server wants to redirect a DOTS client to an alternative 2058 DOTS server for a signal session, then the response code 3.00 2059 (alternate server) will be returned in the response to the DOTS 2060 client. 2062 The DOTS server can return the error response code 3.00 in response 2063 to a PUT request from the DOTS client or convey the error response 2064 code 3.00 in a unidirectional notification response from the DOTS 2065 server. 2067 The DOTS server in the error response conveys the alternate DOTS 2068 server's FQDN, and the alternate DOTS server's IP address(es) and 2069 time to live values in the CBOR body (Figure 23). 2071 { 2072 "ietf-dots-signal-channel:redirected-signal": { 2073 "alt-server": "string", 2074 "alt-server-record": [ 2075 { 2076 "addr": "string", 2077 "ttl" : integer 2078 } 2079 ] 2080 } 2081 } 2083 Figure 23: Redirected Server Error Response Body 2085 The parameters are described below: 2087 alt-server: FQDN of an alternate DOTS server. 2089 addr: IP address of an alternate DOTS server. 2091 ttl: Time to live (TTL) represented as an integer number of seconds. 2093 Figure 24 shows a 3.00 response example to convey the DOTS alternate 2094 server 'alt-server.example', its IP addresses 2001:db8:6401::1 and 2095 2001:db8:6401::2, and TTL values 3600 and 1800. 2097 { 2098 "ietf-dots-signal-channel:redirected-signal": { 2099 "alt-server": "alt-server.example", 2100 "alt-server-record": [ 2101 { 2102 "ttl" : 3600, 2103 "addr": "2001:db8:6401::1" 2104 }, 2105 { 2106 "ttl" : 1800, 2107 "addr": "2001:db8:6401::2" 2108 } 2109 ] 2110 } 2111 } 2113 Figure 24: Example of Redirected Server Error Response Body 2115 When the DOTS client receives 3.00 response, it considers the current 2116 request as failed, but SHOULD try re-sending the request to the 2117 alternate DOTS server. During a DDoS attack, the DNS server may be 2118 the target of another DDoS attack, alternate DOTS server's IP 2119 addresses conveyed in the 3.00 response help the DOTS client skip DNS 2120 lookup of the alternate DOTS server. The DOTS client can then try to 2121 establish a UDP or a TCP session with the alternate DOTS server. The 2122 DOTS client SHOULD implement a DNS64 function to handle the scenario 2123 where an IPv6-only DOTS client communicates with an IPv4-only 2124 alternate DOTS server. 2126 4.7. Heartbeat Mechanism 2128 To provide an indication of signal health and distinguish an 'idle' 2129 signal channel from a 'disconnected' or 'defunct' session, the DOTS 2130 agent sends a heartbeat over the signal channel to maintain its half 2131 of the channel. The DOTS agent similarly expects a heartbeat from 2132 its peer DOTS agent, and may consider a session terminated in the 2133 prolonged absence of a peer agent heartbeat. 2135 While the communication between the DOTS agents is quiescent, the 2136 DOTS client will probe the DOTS server to ensure it has maintained 2137 cryptographic state and vice versa. Such probes can also keep 2138 firewalls and/or stateful translators bindings alive. This probing 2139 reduces the frequency of establishing a new handshake when a DOTS 2140 signal needs to be conveyed to the DOTS server. 2142 DOTS servers MAY trigger their heartbeat requests immediately after 2143 receiving heartbeat probes from peer DOTS clients. As a reminder, it 2144 is the responsibility of DOTS clients to ensure that on-path 2145 translators/firewalls are maintaining a binding so that the same 2146 external IP address and/or port number is retained for the DOTS 2147 session. 2149 In case of a massive DDoS attack that saturates the incoming link(s) 2150 to the DOTS client, all traffic from the DOTS server to the DOTS 2151 client will likely be dropped, although the DOTS server receives 2152 heartbeat requests in addition to DOTS messages sent by the DOTS 2153 client. In this scenario, the DOTS agents MUST behave differently to 2154 handle message transmission and DOTS session liveliness during link 2155 saturation: 2157 o The DOTS client MUST NOT consider the DOTS session terminated even 2158 after a maximum 'missing-hb-allowed' threshold is reached. The 2159 DOTS client SHOULD keep on using the current DOTS session to send 2160 heartbeat requests over it, so that the DOTS server knows the DOTS 2161 client has not disconnected the DOTS session. 2163 After the maximum 'missing-hb-allowed' threshold is reached, the 2164 DOTS client SHOULD try to resume the (D)TLS session. The DOTS 2165 client SHOULD send mitigation requests over the current DOTS 2166 session, and in parallel, for example, try to resume the (D)TLS 2167 session or use 0-RTT mode in DTLS 1.3 to piggyback the mitigation 2168 request in the ClientHello message. 2170 As soon as the link is no longer saturated, if traffic from the 2171 DOTS server reaches the DOTS client over the current DOTS session, 2172 the DOTS client can stop (D)TLS session resumption or if (D)TLS 2173 session resumption is successful then disconnect the current DOTS 2174 session. 2176 o If the DOTS server does not receive any traffic from the peer DOTS 2177 client, then the DOTS server sends heartbeat requests to the DOTS 2178 client and after maximum 'missing-hb-allowed' threshold is 2179 reached, the DOTS server concludes the session is disconnected. 2181 In DOTS over UDP, heartbeat messages MUST be exchanged between the 2182 DOTS agents using the "CoAP Ping" mechanism defined in Section 4.2 of 2183 [RFC7252]. Concretely, the DOTS agent sends an Empty Confirmable 2184 message and the peer DOTS agent will respond by sending a Reset 2185 message. 2187 In DOTS over TCP, heartbeat messages MUST be exchanged between the 2188 DOTS agents using the Ping and Pong messages specified in Section 4.4 2189 of [I-D.ietf-core-coap-tcp-tls]. That is, the DOTS agent sends a 2190 Ping message and the peer DOTS agent would respond by sending a 2191 single Pong message. 2193 5. DOTS Signal Channel YANG Module 2195 This document defines a YANG [RFC7950] module for mitigation scope 2196 and DOTS signal channel session configuration data. 2198 This YANG module defines the DOTS client interaction with the DOTS 2199 server as seen by the DOTS client. A DOTS server is allowed to 2200 update the non-configurable 'ro' entities in the responses. This 2201 YANG module is not intended to be used for DOTS servers management 2202 purposes. Such module is out of the scope of this document. 2204 5.1. Tree Structure 2206 This document defines the YANG module "ietf-dots-signal-channel" 2207 (Section 5.2), which has the following tree structure. A DOTS signal 2208 message can either be a mitigation or a configuration message. 2210 module: ietf-dots-signal-channel 2211 +--rw dots-signal 2212 +--rw (message-type)? 2213 +--:(mitigation-scope) 2214 | +--rw cdid? string 2215 | +--rw scope* [cuid mid] 2216 | +--rw cuid string 2217 | +--rw mid uint32 2218 | +--rw target-prefix* inet:ip-prefix 2219 | +--rw target-port-range* [lower-port upper-port] 2220 | | +--rw lower-port inet:port-number 2221 | | +--rw upper-port inet:port-number 2222 | +--rw target-protocol* uint8 2223 | +--rw target-fqdn* inet:domain-name 2224 | +--rw target-uri* inet:uri 2225 | +--rw alias-name* string 2226 | +--rw lifetime? int32 2227 | +--ro mitigation-start? uint64 2228 | +--ro status? enumeration 2229 | +--ro conflict-information 2230 | | +--ro conflict-status? enumeration 2231 | | +--ro conflict-cause? enumeration 2232 | | +--ro retry-timer? uint32 2233 | | +--ro conflict-scope 2234 | | +--ro target-prefix* inet:ip-prefix 2235 | | +--ro target-port-range* [lower-port upper-port] 2236 | | | +--ro lower-port inet:port-number 2237 | | | +--ro upper-port inet:port-number 2238 | | +--ro target-protocol* uint8 2239 | | +--ro target-fqdn* inet:domain-name 2240 | | +--ro target-uri* inet:uri 2241 | | +--ro alias-name* string 2242 | | +--ro acl-list* [acl-name] 2243 | | +--ro acl-name 2244 | | | -> /ietf-acl:access-lists/acl/name 2245 | | +--ro acl-type? 2246 | | -> /ietf-acl:access-lists/acl/type 2247 | +--ro bytes-dropped? yang:zero-based-counter64 2248 | +--ro bps-dropped? yang:zero-based-counter64 2249 | +--ro pkts-dropped? yang:zero-based-counter64 2250 | +--ro pps-dropped? yang:zero-based-counter64 2251 | +--rw attack-status? enumeration 2252 +--:(signal-config) 2253 | +--rw sid uint32 2254 | +--rw mitigating-config 2255 | | +--rw heartbeat-interval 2256 | | | +--ro max-value? uint16 2257 | | | +--ro min-value? uint16 2258 | | | +--rw current-value? uint16 2259 | | +--rw missing-hb-allowed 2260 | | | +--ro max-value? uint16 2261 | | | +--ro min-value? uint16 2262 | | | +--rw current-value? uint16 2263 | | +--rw max-retransmit 2264 | | | +--ro max-value? uint16 2265 | | | +--ro min-value? uint16 2266 | | | +--rw current-value? uint16 2267 | | +--rw ack-timeout 2268 | | | +--ro max-value? uint16 2269 | | | +--ro min-value? uint16 2270 | | | +--rw current-value? uint16 2271 | | +--rw ack-random-factor 2272 | | +--ro max-value-decimal? decimal64 2273 | | +--ro min-value-decimal? decimal64 2274 | | +--rw current-value-decimal? decimal64 2275 | +--rw idle-config 2276 | | +--rw heartbeat-interval 2277 | | | +--ro max-value? uint16 2278 | | | +--ro min-value? uint16 2279 | | | +--rw current-value? uint16 2280 | | +--rw missing-hb-allowed 2281 | | | +--ro max-value? uint16 2282 | | | +--ro min-value? uint16 2283 | | | +--rw current-value? uint16 2284 | | +--rw max-retransmit 2285 | | | +--ro max-value? uint16 2286 | | | +--ro min-value? uint16 2287 | | | +--rw current-value? uint16 2288 | | +--rw ack-timeout 2289 | | | +--ro max-value? uint16 2290 | | | +--ro min-value? uint16 2291 | | | +--rw current-value? uint16 2292 | | +--rw ack-random-factor 2293 | | +--ro max-value-decimal? decimal64 2294 | | +--ro min-value-decimal? decimal64 2295 | | +--rw current-value-decimal? decimal64 2296 | +--rw trigger-mitigation? boolean 2297 | +--ro config-interval? uint32 2298 +--:(redirected-signal) 2299 +--ro alt-server string 2300 +--ro alt-server-record* [addr] 2301 +--ro addr inet:ip-address 2302 +--ro ttl? uint32 2304 5.2. YANG Module 2306 file "ietf-dots-signal-channel@2018-01-23.yang" 2308 module ietf-dots-signal-channel { 2309 yang-version 1.1; 2310 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel"; 2311 prefix signal; 2313 import ietf-inet-types { 2314 prefix inet; 2315 } 2316 import ietf-yang-types { 2317 prefix yang; 2318 } 2319 import ietf-access-control-list { 2320 prefix ietf-acl; 2321 } 2323 organization 2324 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 2325 contact 2326 "WG Web: 2327 WG List: 2329 Editor: Konda, Tirumaleswar Reddy 2330 2332 Editor: Mohamed Boucadair 2333 2335 Author: Prashanth Patil 2336 2338 Author: Andrew Mortensen 2339 2341 Author: Nik Teague 2342 "; 2343 description 2344 "This module contains YANG definition for the signaling 2345 messages exchanged between a DOTS client and a DOTS server. 2347 Copyright (c) 2018 IETF Trust and the persons identified as 2348 authors of the code. All rights reserved. 2350 Redistribution and use in source and binary forms, with or 2351 without modification, is permitted pursuant to, and subject 2352 to the license terms contained in, the Simplified BSD License 2353 set forth in Section 4.c of the IETF Trust's Legal Provisions 2354 Relating to IETF Documents 2355 (http://trustee.ietf.org/license-info). 2357 This version of this YANG module is part of RFC XXXX; see 2358 the RFC itself for full legal notices."; 2360 revision 2018-01-23 { 2361 description 2362 "Initial revision."; 2363 reference 2364 "RFC XXXX: Distributed Denial-of-Service Open Threat 2365 Signaling (DOTS) Signal Channel"; 2366 } 2368 /* 2369 * Groupings 2370 */ 2372 grouping target { 2373 description 2374 "Specifies the targets of the mitigation request."; 2375 leaf-list target-prefix { 2376 type inet:ip-prefix; 2377 description 2378 "IPv4 or IPv6 prefix identifying the target."; 2379 } 2380 list target-port-range { 2381 key "lower-port upper-port"; 2382 description 2383 "Port range. When only lower-port is 2384 present, it represents a single port number."; 2385 leaf lower-port { 2386 type inet:port-number; 2387 mandatory true; 2388 description 2389 "Lower port number of the port range."; 2390 } 2391 leaf upper-port { 2392 type inet:port-number; 2393 must ". >= ../lower-port" { 2394 error-message 2395 "The upper port number must be greater than 2396 or equal to lower port number."; 2397 } 2398 description 2399 "Upper port number of the port range."; 2400 } 2401 } 2402 leaf-list target-protocol { 2403 type uint8; 2404 description 2405 "Identifies the target protocol number. 2407 The value '0' means 'all protocols'. 2409 Values are taken from the IANA protocol registry: 2410 https://www.iana.org/assignments/protocol-numbers/ 2411 protocol-numbers.xhtml 2413 For example, 6 for TCP or 17 for UDP."; 2414 } 2415 leaf-list target-fqdn { 2416 type inet:domain-name; 2417 description 2418 "FQDN identifying the target."; 2419 } 2420 leaf-list target-uri { 2421 type inet:uri; 2422 description 2423 "URI identifying the target."; 2424 } 2425 } 2427 grouping mitigation-scope { 2428 description 2429 "Specifies the scope of the mitigation request."; 2430 leaf cdid { 2431 type string; 2432 description 2433 "The cdid should be included by a server-domain 2434 DOTS gateway to propagate the client domain 2435 identification information from the 2436 gateway's client-facing-side to the gateway's 2437 server-facing-side, and from the gateway's 2438 server-facing-side to the DOTS server. 2440 It may be used by the final DOTS server 2441 for policy enforcement purposes."; 2442 } 2443 list scope { 2444 key "cuid mid"; 2445 description 2446 "The scope of the request."; 2447 leaf cuid { 2448 type string; 2449 description 2450 "A unique identifier that is randomly 2451 generated by a DOTS client to prevent 2452 request collisions. It is expected that the 2453 cuid will remain consistent throughout the 2454 lifetime of the DOTS client."; 2455 } 2456 leaf mid { 2457 type uint32; 2458 description 2459 "Mitigation request identifier. 2461 This identifier must be unique for each mitigation 2462 request bound to the DOTS client."; 2463 } 2464 uses target; 2465 leaf-list alias-name { 2466 type string; 2467 description 2468 "An alias name that points to a resource."; 2469 } 2470 leaf lifetime { 2471 type int32; 2472 units "seconds"; 2473 default "3600"; 2474 description 2475 "Indicates the lifetime of the mitigation request. 2477 A lifetime of '0' in a mitigation request is an 2478 invalid value. 2480 A lifetime of negative one (-1) indicates indefinite 2481 lifetime for the mitigation request."; 2483 } 2484 leaf mitigation-start { 2485 type uint64; 2486 config false; 2487 description 2488 "Mitigation start time is represented in seconds 2489 relative to 1970-01-01T00:00:00Z in UTC time."; 2490 } 2491 leaf status { 2492 type enumeration { 2493 enum "attack-mitigation-in-progress" { 2494 value 1; 2495 description 2496 "Attack mitigation is in progress (e.g., changing 2497 the network path to re-route the inbound traffic 2498 to DOTS mitigator)."; 2499 } 2500 enum "attack-successfully-mitigated" { 2501 value 2; 2502 description 2503 "Attack is successfully mitigated (e.g., traffic 2504 is redirected to a DDoS mitigator and attack 2505 traffic is dropped or blackholed)."; 2506 } 2507 enum "attack-stopped" { 2508 value 3; 2509 description 2510 "Attack has stopped and the DOTS client can 2511 withdraw the mitigation request."; 2512 } 2513 enum "attack-exceeded-capability" { 2514 value 4; 2515 description 2516 "Attack has exceeded the mitigation provider 2517 capability."; 2518 } 2519 enum "dots-client-withdrawn-mitigation" { 2520 value 5; 2521 description 2522 "DOTS client has withdrawn the mitigation 2523 request and the mitigation is active but 2524 terminating."; 2525 } 2526 enum "attack-mitigation-terminated" { 2527 value 6; 2528 description 2529 "Attack mitigation is now terminated."; 2530 } 2531 enum "attack-mitigation-withdrawn" { 2532 value 7; 2533 description 2534 "Attack mitigation is withdrawn."; 2535 } 2536 enum "attack-mitigation-rejected" { 2537 value 8; 2538 description 2539 "Attack mitigation is rejected."; 2540 } 2541 } 2542 config false; 2543 description 2544 "Indicates the status of a mitigation request. 2545 It must be included in responses only."; 2546 } 2547 container conflict-information { 2548 config false; 2549 description 2550 "Indicates that a conflict is detected. 2551 Must only be used for responses."; 2552 leaf conflict-status { 2553 type enumeration { 2554 enum "request-inactive-other-active" { 2555 value 1; 2556 description 2557 "DOTS Server has detected conflicting mitigation 2558 requests from different DOTS clients. 2559 This mitigation request is currently inactive 2560 until the conflicts are resolved. Another 2561 mitigation request is active."; 2562 } 2563 enum "request-active" { 2564 value 2; 2565 description 2566 "DOTS Server has detected conflicting mitigation 2567 requests from different DOTS clients. 2568 This mitigation request is currently active."; 2569 } 2570 enum "all-requests-inactive" { 2571 value 3; 2572 description 2573 "DOTS Server has detected conflicting mitigation 2574 requests from different DOTS clients. All 2575 conflicting mitigation requests are inactive."; 2576 } 2577 } 2578 description 2579 "Indicates the conflict status."; 2580 } 2581 leaf conflict-cause { 2582 type enumeration { 2583 enum "overlapping-targets" { 2584 value 1; 2585 description 2586 "Overlapping targets. conflict-scope provides 2587 more details about the exact conflict."; 2588 } 2589 enum "conflict-with-whitelist" { 2590 value 2; 2591 description 2592 "Conflicts with an existing white list. 2594 This code is returned when the DDoS mitigation 2595 detects that some of the source addresses/prefixes 2596 listed in the white list ACLs are actually 2597 attacking the target."; 2598 } 2599 enum "cuid-collision" { 2600 value 3; 2601 description 2602 "Conflicts with the cuid used by another 2603 DOTS client."; 2604 } 2605 } 2606 description 2607 "Indicates the cause of the conflict."; 2608 } 2609 leaf retry-timer { 2610 type uint32; 2611 units "seconds"; 2612 description 2613 "The DOTS client must not re-send the 2614 same request that has a conflict before the expiry of 2615 this timer."; 2616 } 2617 container conflict-scope { 2618 description 2619 "Provides more information about the conflict scope."; 2620 uses target { 2621 when "../conflict-cause = 'overlapping-targets'"; 2622 } 2623 leaf-list alias-name { 2624 when "../../conflict-cause = 'overlapping-targets'"; 2625 type string; 2626 description 2627 "Conflicting alias-name."; 2628 } 2629 list acl-list { 2630 when "../../conflict-cause = 'conflict-with-whitelist'"; 2631 key "acl-name"; 2632 description 2633 "List of conflicting ACLs as defined in the DOTS data 2634 channel. These ACLs are uniquely defined by 2635 cuid and acl-name."; 2636 leaf acl-name { 2637 type leafref { 2638 path "/ietf-acl:access-lists/ietf-acl:acl/" + 2639 "ietf-acl:name"; 2640 } 2641 description 2642 "Reference to the conflicting ACL name bound to 2643 a DOTS client."; 2644 } 2645 leaf acl-type { 2646 type leafref { 2647 path "/ietf-acl:access-lists/ietf-acl:acl/" + 2648 "ietf-acl:type"; 2649 } 2650 description 2651 "Reference to the conflicting ACL type bound to 2652 a DOTS client."; 2653 } 2654 } 2655 } 2656 } 2657 leaf bytes-dropped { 2658 type yang:zero-based-counter64; 2659 units "bytes"; 2660 config false; 2661 description 2662 "The total dropped byte count for the mitigation 2663 request since the attack mitigation is triggered. 2664 The count wraps around when it reaches the maximum value 2665 of counter64 for dropped bytes."; 2666 } 2667 leaf bps-dropped { 2668 type yang:zero-based-counter64; 2669 config false; 2670 description 2671 "The average number of dropped bits per second for 2672 the mitigation request since the attack 2673 mitigation is triggered. This should be a 2674 five-minute average."; 2676 } 2677 leaf pkts-dropped { 2678 type yang:zero-based-counter64; 2679 config false; 2680 description 2681 "The total number of dropped packet count for the 2682 mitigation request since the attack mitigation is 2683 triggered. The count wraps around when it reaches 2684 the maximum value of counter64 for dropped packets."; 2685 } 2686 leaf pps-dropped { 2687 type yang:zero-based-counter64; 2688 config false; 2689 description 2690 "The average number of dropped packets per second 2691 for the mitigation request since the attack 2692 mitigation is triggered. This should be a 2693 five-minute average."; 2694 } 2695 leaf attack-status { 2696 type enumeration { 2697 enum "under-attack" { 2698 value 1; 2699 description 2700 "The DOTS client determines that it is still under 2701 attack."; 2702 } 2703 enum "attack-successfully-mitigated" { 2704 value 2; 2705 description 2706 "The DOTS client determines that the attack is 2707 successfully mitigated."; 2708 } 2709 } 2710 description 2711 "Indicates the status of an attack as seen by the 2712 DOTS client."; 2713 } 2714 } 2715 } 2717 grouping config-parameters { 2718 description 2719 "Subset of DOTS signal channel session configuration."; 2720 container heartbeat-interval { 2721 description 2722 "DOTS agents regularly send heartbeats to each other 2723 after mutual authentication is successfully 2724 completed in order to keep the DOTS signal channel 2725 open."; 2726 leaf max-value { 2727 type uint16; 2728 units "seconds"; 2729 config false; 2730 description 2731 "Maximum acceptable heartbeat-interval value."; 2732 } 2733 leaf min-value { 2734 type uint16; 2735 units "seconds"; 2736 config false; 2737 description 2738 "Minimum acceptable heartbeat-interval value."; 2739 } 2740 leaf current-value { 2741 type uint16; 2742 units "seconds"; 2743 default "30"; 2744 description 2745 "Current heartbeat-interval value. 2747 '0' means that heartbeat mechanism is deactivated."; 2748 } 2749 } 2750 container missing-hb-allowed { 2751 description 2752 "Maximum number of missing heartbeats allowed."; 2753 leaf max-value { 2754 type uint16; 2755 config false; 2756 description 2757 "Maximum acceptable missing-hb-allowed value."; 2758 } 2759 leaf min-value { 2760 type uint16; 2761 config false; 2762 description 2763 "Minimum acceptable missing-hb-allowed value."; 2764 } 2765 leaf current-value { 2766 type uint16; 2767 default "5"; 2768 description 2769 "Current missing-hb-allowed value."; 2770 } 2771 } 2772 container max-retransmit { 2773 description 2774 "Maximum number of retransmissions of a Confirmable 2775 message."; 2776 leaf max-value { 2777 type uint16; 2778 config false; 2779 description 2780 "Maximum acceptable max-retransmit value."; 2781 } 2782 leaf min-value { 2783 type uint16; 2784 config false; 2785 description 2786 "Minimum acceptable max-retransmit value."; 2787 } 2788 leaf current-value { 2789 type uint16; 2790 default "3"; 2791 description 2792 "Current max-retransmit value."; 2793 } 2794 } 2795 container ack-timeout { 2796 description 2797 "Initial retransmission timeout value."; 2798 leaf max-value { 2799 type uint16; 2800 units "seconds"; 2801 config false; 2802 description 2803 "Maximum ack-timeout value."; 2804 } 2805 leaf min-value { 2806 type uint16; 2807 units "seconds"; 2808 config false; 2809 description 2810 "Minimum ack-timeout value."; 2811 } 2812 leaf current-value { 2813 type uint16; 2814 units "seconds"; 2815 default "2"; 2816 description 2817 "Current ack-timeout value."; 2818 } 2819 } 2820 container ack-random-factor { 2821 description 2822 "Random factor used to influence the timing of 2823 retransmissions."; 2824 leaf max-value-decimal { 2825 type decimal64 { 2826 fraction-digits 2; 2827 } 2828 config false; 2829 description 2830 "Maximum acceptable ack-random-factor value."; 2831 } 2832 leaf min-value-decimal { 2833 type decimal64 { 2834 fraction-digits 2; 2835 } 2836 config false; 2837 description 2838 "Minimum acceptable ack-random-factor value."; 2839 } 2840 leaf current-value-decimal { 2841 type decimal64 { 2842 fraction-digits 2; 2843 } 2844 default "1.5"; 2845 description 2846 "Current ack-random-factor value."; 2847 } 2848 } 2849 } 2851 grouping signal-config { 2852 description 2853 "DOTS signal channel session configuration."; 2854 leaf sid { 2855 type uint32; 2856 mandatory true; 2857 description 2858 "An identifier for the DOTS signal channel 2859 session configuration data."; 2860 } 2861 container mitigating-config { 2862 description 2863 "Configuration parameters to use when a mitigation 2864 is active."; 2865 uses config-parameters; 2866 } 2867 container idle-config { 2868 description 2869 "Configuration parameters to use when no mitigation 2870 is active."; 2871 uses config-parameters; 2872 } 2873 leaf trigger-mitigation { 2874 type boolean; 2875 default "true"; 2876 description 2877 "If false, then mitigation is triggered 2878 only when the DOTS server channel session is lost."; 2879 } 2880 leaf config-interval { 2881 type uint32; 2882 units "seconds"; 2883 default "3600"; 2884 config false; 2885 description 2886 "This parameter is returned by a DOTS server to 2887 a requesting DOTS client to indicate the time interval 2888 after which the DOTS client must contact the DOTS 2889 server in order to retrieve the signal channel 2890 configuration data. 2892 This mechanism allows the update of the configuration 2893 data if a change occurs. 2895 For example, the new configuration may instruct 2896 a DOTS client to cease heartbeats or reduce 2897 heartbeat frequency. 2899 '0' is used to disable this refresh mechanism."; 2900 } 2901 } 2903 grouping redirected-signal { 2904 description 2905 "Grouping for the redirected signaling."; 2906 leaf alt-server { 2907 type string; 2908 config false; 2909 mandatory true; 2910 description 2911 "FQDN of an alternate server."; 2912 } 2913 list alt-server-record { 2914 key "addr"; 2915 config false; 2916 description 2917 "List of records for the alternate server."; 2918 leaf addr { 2919 type inet:ip-address; 2920 description 2921 "An IPv4 or IPv6 address identifying the server."; 2922 } 2923 leaf ttl { 2924 type uint32; 2925 description 2926 "TTL associated with this record."; 2927 } 2928 } 2929 } 2931 /* 2932 * Main Container for DOTS Signal Channel 2933 */ 2935 container dots-signal { 2936 description 2937 "Main container for DOTS signal message. 2939 A DOTS signal message can be a mitigation, a configuration, 2940 or a redirected signal message."; 2941 choice message-type { 2942 description 2943 "Can be a mitigation, a configuration, or a redirect 2944 message."; 2945 case mitigation-scope { 2946 description 2947 "Mitigation scope of a mitigation message."; 2948 uses mitigation-scope; 2949 } 2950 case signal-config { 2951 description 2952 "Configuration message."; 2953 uses signal-config; 2954 } 2955 case redirected-signal { 2956 description 2957 "Redirected signaling."; 2958 uses redirected-signal; 2959 } 2960 } 2961 } 2962 } 2963 2965 6. Mapping Parameters to CBOR 2967 All parameters in the payload of the DOTS signal channel MUST be 2968 mapped to CBOR types as shown in Table 4 and are assigned an integer 2969 key to save space. The recipient of the payload MAY reject the 2970 information if it is not suitably mapped. 2972 +----------------------+-------------+-----+---------------+--------+ 2973 | Parameter Name | YANG | CBOR| CBOR Major | JSON | 2974 | | Type | Key | Type & | Type | 2975 | | | | Information | | 2976 +----------------------+-------------+-----+---------------+--------+ 2977 | ietf-dots-signal-cha | | | | | 2978 | nnel:mitigation-scope| container | 1 | 5 map | Object | 2979 | cdid | string | 2 | 3 text string | String | 2980 | scope | list | 3 | 4 array | Array | 2981 | cuid | string | 4 | 3 text string | String | 2982 | mid | uint32 | 5 | 0 unsigned | Number | 2983 | target-prefix | leaf-list | 6 | 4 array | Array | 2984 | | inet: | | | | 2985 | | ip-prefix | | 3 text string | String | 2986 | target-port-range | list | 7 | 4 array | Array | 2987 | lower-port | inet: | | | | 2988 | | port-number| 8 | 0 unsigned | Number | 2989 | upper-port | inet: | | | | 2990 | | port-number| 9 | 0 unsigned | Number | 2991 | target-protocol | leaf-list | 10 | 4 array | Array | 2992 | | uint8 | | 0 unsigned | Number | 2993 | target-fqdn | leaf-list | 11 | 4 array | Array | 2994 | | inet: | | | | 2995 | | domain-name| | 3 text string | String | 2996 | target-uri | leaf-list | 12 | 4 array | Array | 2997 | | inet:uri | | 3 text string | String | 2998 | alias-name | leaf-list | 13 | 4 array | Array | 2999 | | string | | 3 text string | String | 3000 | lifetime | int32 | 14 | 0 unsigned | Number | 3001 | | | | 1 negative | Number | 3002 | mitigation-start | uint64 | 15 | 0 unsigned | String | 3003 | status | enumeration | 16 | 0 unsigned | String | 3004 | conflict-information | container | 17 | 5 map | Object | 3005 | conflict-status | enumeration | 18 | 0 unsigned | String | 3006 | conflict-cause | enumeration | 19 | 0 unsigned | String | 3007 | retry-timer | uint32 | 20 | 0 unsigned | Number | 3008 | conflict-scope | container | 21 | 5 map | Object | 3009 | acl-list | list | 22 | 4 array | Array | 3010 | acl-name | leafref | 23 | 3 text string | String | 3011 | acl-type | leafref | 24 | 3 text string | String | 3012 | bytes-dropped | yang:zero- | | | | 3013 | | based- | | | | 3014 | | counter64 | 25 | 0 unsigned | String | 3015 | bps-dropped | yang:zero- | | | | 3016 | | based- | | | | 3017 | | counter64 | 26 | 0 unsigned | String | 3018 | pkts-dropped | yang:zero- | | | | 3019 | | based- | | | | 3020 | | counter64 | 27 | 0 unsigned | String | 3021 | pps-dropped | yang:zero- | | | | 3022 | | based- | | | | 3023 | | counter64 | 28 | 0 unsigned | String | 3024 | attack-status | enumeration | 29 | 0 unsigned | String | 3025 | ietf-dots-signal- | | | | | 3026 | channel:signal-config| container | 30 | 5 map | Object | 3027 | sid | uint32 | 31 | 0 unsigned | Number | 3028 | mitigating-config | container | 32 | 5 map | Object | 3029 | heartbeat-interval | container | 33 | 5 map | Object | 3030 | max-value | uint16 | 34 | 0 unsigned | Number | 3031 | min-value | uint16 | 35 | 0 unsigned | Number | 3032 | current-value | uint16 | 36 | 0 unsigned | Number | 3033 | missing-hb-allowed | container | 37 | 5 map | Object | 3034 | max-retransmit | container | 38 | 5 map | Object | 3035 | ack-timeout | container | 39 | 5 map | Object | 3036 | ack-random-factor | container | 40 | 5 map | Object | 3037 | max-value-decimal | decimal64 | 41 | 6 tag 4 | | 3038 | | | | [-2, integer]| String | 3039 | min-value-decimal | decimal64 | 42 | 6 tag 4 | | 3040 | | | | [-2, integer]| String | 3041 | current-value-decimal| decimal64 | 43 | 6 tag 4 | | 3042 | | | | [-2, integer]| String | 3043 | idle-config | container | 44 | 5 map | Object | 3044 | trigger-mitigation | boolean | 45 | 7 bits 20 | False | 3045 | | | | 7 bits 21 | True | 3046 | config-interval | uint32 | 46 | 0 unsigned | Number | 3047 | ietf-dots-signal-cha | | | | | 3048 |nnel:redirected-signal| container | 47 | 5 map | Object | 3049 | alt-server | string | 48 | 3 text string | String | 3050 | alt-server-record | list | 49 | 4 array | Array | 3051 | addr | inet: | | | | 3052 | | ip-address | 50 | 3 text string | String | 3053 | ttl | uint32 | 51 | 0 unsigned | Number | 3054 +----------------------+-------------+-----+---------------+--------+ 3056 Table 4: CBOR Mappings Used in DOTS Signal Channel Messages 3058 7. (D)TLS Protocol Profile and Performance Considerations 3060 7.1. (D)TLS Protocol Profile 3062 This section defines the (D)TLS protocol profile of DOTS signal 3063 channel over (D)TLS and DOTS data channel over TLS. 3065 There are known attacks on (D)TLS, such as man-in-the-middle and 3066 protocol downgrade attacks. These are general attacks on (D)TLS and, 3067 as such, they are not specific to DOTS over (D)TLS; refer to the 3068 (D)TLS RFCs for discussion of these security issues. DOTS agents 3069 MUST adhere to the (D)TLS implementation recommendations and security 3070 considerations of [RFC7525] except with respect to (D)TLS version. 3071 Since DOTS signal channel encryption relies upon (D)TLS is virtually 3072 a green-field deployment, DOTS agents MUST implement only (D)TLS 1.2 3073 or later. 3075 When a DOTS client is configured with a domain name of the DOTS 3076 server, and connects to its configured DOTS server, the server may 3077 present it with a PKIX certificate. In order to ensure proper 3078 authentication, a DOTS client MUST verify the entire certification 3079 path per [RFC5280]. The DOTS client additionally uses [RFC6125] 3080 validation techniques to compare the domain name with the certificate 3081 provided. 3083 A key challenge to deploying DOTS is the provisioning of DOTS 3084 clients, including the distribution of keying material to DOTS 3085 clients to enable the required mutual authentication of DOTS agents. 3086 EST defines a method of certificate enrollment by which domains 3087 operating DOTS servers may provide DOTS clients with all the 3088 necessary cryptographic keying material, including a private key and 3089 a certificate to authenticate themselves. One deployment option is 3090 DOTS clients behave as EST clients for certificate enrollment from an 3091 EST server provisioned by the mitigation provider. This document 3092 does not specify which EST mechanism the DOTS client uses to achieve 3093 initial enrollment. 3095 The Server Name Indication (SNI) extension [RFC6066] defines a 3096 mechanism for a client to tell a (D)TLS server the name of the server 3097 it wants to contact. This is a useful extension for hosting 3098 environments where multiple virtual servers are reachable over a 3099 single IP address. The DOTS client may or may not know if it is 3100 interacting with a DOTS server in a virtual server hosting 3101 environment, so the DOTS client SHOULD include the DOTS server FQDN 3102 in the SNI extension. 3104 Implementations compliant with this profile MUST implement all of the 3105 following items: 3107 o DTLS record replay detection (Section 3.3 of [RFC6347]) to protect 3108 against replay attacks. 3110 o (D)TLS session resumption without server-side state [RFC5077] to 3111 resume session and convey the DOTS signal. 3113 o Raw public keys [RFC7250] or PSK handshake [RFC4279] which reduces 3114 the size of the ServerHello, and can be used by DOTS agents that 3115 cannot obtain certificates. 3117 Implementations compliant with this profile SHOULD implement all of 3118 the following items to reduce the delay required to deliver a DOTS 3119 signal channel message: 3121 o TLS False Start [RFC7918] which reduces round-trips by allowing 3122 the TLS second flight of messages (ChangeCipherSpec) to also 3123 contain the DOTS signal. 3125 o Cached Information Extension [RFC7924] which avoids transmitting 3126 the server's certificate and certificate chain if the client has 3127 cached that information from a previous TLS handshake. 3129 o TCP Fast Open [RFC7413] can reduce the number of round-trips to 3130 convey DOTS signal channel message. 3132 7.2. (D)TLS 1.3 Considerations 3134 TLS 1.3 [I-D.ietf-tls-tls13] provides critical latency improvements 3135 for connection establishment over TLS 1.2. The DTLS 1.3 protocol 3136 [I-D.ietf-tls-dtls13] is based upon the TLS 1.3 protocol and provides 3137 equivalent security guarantees. (D)TLS 1.3 provides two basic 3138 handshake modes the DOTS signal channel can take advantage of: 3140 o A full handshake mode in which a DOTS client can send a DOTS 3141 mitigation request message after one round trip and the DOTS 3142 server immediately responds with a DOTS mitigation response. This 3143 assumes no packet loss is experienced. 3145 o 0-RTT mode in which the DOTS client can authenticate itself and 3146 send DOTS mitigation request messages in the first message, thus 3147 reducing handshake latency. 0-RTT only works if the DOTS client 3148 has previously communicated with that DOTS server, which is very 3149 likely with the DOTS signal channel. 3151 The DOTS client has to establish a (D)TLS session with the DOTS 3152 server during peacetime and share a PSK. 3154 During a DDoS attack, the DOTS client can use the (D)TLS session 3155 to convey the DOTS mitigation request message and, if there is no 3156 response from the server after multiple retries, the DOTS client 3157 can resume the (D)TLS session in 0-RTT mode using PSK. 3159 Section 8 of [I-D.ietf-tls-tls13] discusses some mechanisms to 3160 implement to limit the impact of replay attacks on 0-RTT data. If 3161 TLS1.3 is used, DOTS servers must implement one of these 3162 mechanisms. 3164 A simplified TLS 1.3 handshake with 0-RTT DOTS mitigation request 3165 message exchange is shown in Figure 25. 3167 DOTS Client DOTS Server 3169 ClientHello 3170 (Finished) 3171 (0-RTT DOTS signal message) 3172 (end_of_early_data) --------> 3173 ServerHello 3174 {EncryptedExtensions} 3175 {ServerConfiguration} 3176 {Certificate} 3177 {CertificateVerify} 3178 {Finished} 3179 <-------- [DOTS signal message] 3180 {Finished} --------> 3182 [DOTS signal message] <-------> [DOTS signal message] 3184 Figure 25: TLS 1.3 handshake with 0-RTT 3186 7.3. MTU and Fragmentation 3188 To avoid DOTS signal message fragmentation and the subsequent 3189 decreased probability of message delivery, DOTS agents MUST ensure 3190 that the DTLS record MUST fit within a single datagram. If the path 3191 MTU is not known to the DOTS server, an IP MTU of 1280 bytes SHOULD 3192 be assumed. If UDP is used to convey the DOTS signal messages then 3193 the DOTS client must consider the amount of record expansion expected 3194 by the DTLS processing when calculating the size of CoAP message that 3195 fits within the path MTU. Path MTU MUST be greater than or equal to 3196 [CoAP message size + DTLS overhead of 13 octets + authentication 3197 overhead of the negotiated DTLS cipher suite + block padding 3198 (Section 4.1.1.1 of [RFC6347]). If the request size exceeds the path 3199 MTU then the DOTS client MUST split the DOTS signal into separate 3200 messages, for example the list of addresses in the 'target-prefix' 3201 parameter could be split into multiple lists and each list conveyed 3202 in a new PUT request. 3204 Implementation Note: DOTS choice of message size parameters works 3205 well with IPv6 and with most of today's IPv4 paths. However, with 3206 IPv4, it is harder to reliably ensure that there is no IP 3207 fragmentation. If IPv4 path MTU is unknown, implementations may want 3208 to limit themselves to more conservative IPv4 datagram sizes such as 3209 576 bytes, as per [RFC0791]. IP packets whose size does not exceed 3210 576 bytes should never need to be fragmented: therefore, sending a 3211 maximum of 500 bytes of DOTS signal over a UDP datagram will 3212 generally avoid IP fragmentation. 3214 8. Mutual Authentication of DOTS Agents & Authorization of DOTS Clients 3216 (D)TLS based upon client certificate can be used for mutual 3217 authentication between DOTS agents. If a DOTS gateway is involved, 3218 DOTS clients and DOTS gateways MUST perform mutual authentication; 3219 only authorized DOTS clients are allowed to send DOTS signals to a 3220 DOTS gateway. The DOTS gateway and the DOTS server MUST perform 3221 mutual authentication; a DOTS server only allows DOTS signal channel 3222 messages from an authorized DOTS gateway, thereby creating a two-link 3223 chain of transitive authentication between the DOTS client and the 3224 DOTS server. 3226 The DOTS server SHOULD support certificate-based client 3227 authentication. The DOTS client SHOULD respond to the DOTS server's 3228 TLS certificate request message with the PKIX certificate held by the 3229 DOTS client. DOTS client certificate validation MUST be performed as 3230 per [RFC5280] and the DOTS client certificate MUST conform to the 3231 [RFC5280] certificate profile. If a DOTS client does not support TLS 3232 client certificate authentication, it MUST support pre-shared key 3233 based or raw public key based client authentication. 3235 +-----------------------------------------------+ 3236 | example.com domain +---------+ | 3237 | | AAA | | 3238 | +---------------+ | Server | | 3239 | | Application | +------+--+ | 3240 | | server +<-----------------+ ^ | 3241 | | (DOTS client) | | | | 3242 | +---------------+ | | | 3243 | V V | example.net domain 3244 | +-----+----+--+ | +---------------+ 3245 | +--------------+ | | | | | 3246 | | Guest +<-----x----->+ DOTS +<------>+ DOTS | 3247 | | (DOTS client)| | gateway | | | server | 3248 | +--------------+ | | | | | 3249 | +----+--------+ | +---------------+ 3250 | ^ | 3251 | | | 3252 | +----------------+ | | 3253 | | DDoS detector | | | 3254 | | (DOTS client) +<---------------+ | 3255 | +----------------+ | 3256 +-----------------------------------------------+ 3258 Figure 26: Example of Authentication and Authorization of DOTS Agents 3260 In the example depicted in Figure 26, the DOTS gateway and DOTS 3261 clients within the 'example.com' domain mutually authenticate with 3262 each other. After the DOTS gateway validates the identity of a DOTS 3263 client, it communicates with the AAA server in the 'example.com' 3264 domain to determine if the DOTS client is authorized to request DDoS 3265 mitigation. If the DOTS client is not authorized, a 4.01 3266 (Unauthorized) is returned in the response to the DOTS client. In 3267 this example, the DOTS gateway only allows the application server and 3268 DDoS attack detector to request DDoS mitigation, but does not permit 3269 the user of type 'guest' to request DDoS mitigation. 3271 Also, DOTS gateways and servers located in different domains MUST 3272 perform mutual authentication (e.g., using certificates). A DOTS 3273 server will only allow a DOTS gateway with a certificate for a 3274 particular domain to request mitigation for that domain. In 3275 reference to Figure 26, the DOTS server only allows the DOTS gateway 3276 to request mitigation for 'example.com' domain and not for other 3277 domains. 3279 9. IANA Considerations 3281 This specification registers a service port (Section 9.1), a URI 3282 suffix in the Well-Known URIs registry (Section 9.2), a CoAP response 3283 code (Section 9.3), a YANG module (Section 9.5). It also creates a 3284 registry for mappings to CBOR (Section 9.4). 3286 9.1. DOTS Signal Channel UDP and TCP Port Number 3288 IANA is requested to assign the port number TBD to the DOTS signal 3289 channel protocol for both UDP and TCP from the "Service Name and 3290 Transport Protocol Port Number Registry" available at 3291 https://www.iana.org/assignments/service-names-port-numbers/service- 3292 names-port-numbers.xhtml. 3294 The assignment of port number 4646 is strongly suggested, as 4646 is 3295 the ASCII decimal value for ".." (DOTS). 3297 9.2. Well-Known 'dots' URI 3299 This document requests IANA to register the 'dots' well-known URI in 3300 the Well-Known URIs registry (https://www.iana.org/assignments/well- 3301 known-uris/well-known-uris.xhtml) as defined by [RFC5785]: 3303 +----------+----------------+---------------------+-----------------+ 3304 | URI | Change | Specification | Related | 3305 | suffix | controller | document(s) | information | 3306 +----------+----------------+---------------------+-----------------+ 3307 | dots | IETF | [RFCXXXX] | None | 3308 +----------+----------------+---------------------+-----------------+ 3310 Table 5: 'dots' well-known URI 3312 9.3. CoAP Response Code 3314 IANA is requested to add the following entry to the "CoAP Response 3315 Codes" sub-registry available at https://www.iana.org/assignments/ 3316 core-parameters/core-parameters.xhtml#response-codes: 3318 +------+------------------+-----------+ 3319 | Code | Description | Reference | 3320 +------+------------------+-----------+ 3321 | 3.00 | Alternate Server | [RFCXXXX] | 3322 +------+------------------+-----------+ 3324 Table 6: CoAP Response Code 3326 9.4. DOTS Signal Channel CBOR Mappings Registry 3328 The document requests IANA to create a new registry, entitled "DOTS 3329 Signal Channel CBOR Mappings Registry". The structure of this 3330 registry is provided in Section 9.4.1. 3332 The registry is initially populated with the values in Section 9.4.2. 3334 Values from that registry MUST be assigned via Expert Review 3335 [RFC8126]. 3337 9.4.1. Registration Template 3339 Parameter name: 3340 Parameter name as used in the DOTS signal channel. 3342 CBOR Key Value: 3343 Key value for the parameter. The key value MUST be an integer in 3344 the 1-65536 range. The key values in the 32758-65536 range are 3345 assigned to Vendor-Specific parameters. 3347 CBOR Major Type: 3348 CBOR Major type and optional tag for the claim. 3350 Change Controller: 3351 For Standards Track RFCs, list the "IESG". For others, give the 3352 name of the responsible party. Other details (e.g., postal 3353 address, email address, home page URI) may also be included. 3355 Specification Document(s): 3356 Reference to the document or documents that specify the parameter, 3357 preferably including URIs that can be used to retrieve copies of 3358 the documents. An indication of the relevant sections may also be 3359 included but is not required. 3361 9.4.2. Initial Registry Content 3363 +----------------------+-------+-------+------------+---------------+ 3364 | Parameter Name | CBOR | CBOR | Change | Specification | 3365 | | Key | Major | Controller | Document(s) | 3366 | | Value | Type | | | 3367 +----------------------+-------+-------+------------+---------------+ 3368 | ietf-dots-signal-chan| 1 | 5 | IESG | [RFCXXXX] | 3369 | nel:mitigation-scope | | | | | 3370 | cdid | 2 | 3 | IESG | [RFCXXXX] | 3371 | scope | 3 | 4 | IESG | [RFCXXXX] | 3372 | cuid | 4 | 3 | IESG | [RFCXXXX] | 3373 | mid | 5 | 0 | IESG | [RFCXXXX] | 3374 | target-prefix | 6 | 4 | IESG | [RFCXXXX] | 3375 | target-port-range | 7 | 4 | IESG | [RFCXXXX] | 3376 | lower-port | 8 | 0 | IESG | [RFCXXXX] | 3377 | upper-port | 9 | 0 | IESG | [RFCXXXX] | 3378 | target-protocol | 10 | 4 | IESG | [RFCXXXX] | 3379 | target-fqdn | 11 | 4 | IESG | [RFCXXXX] | 3380 | target-uri | 12 | 4 | IESG | [RFCXXXX] | 3381 | alias-name | 13 | 4 | IESG | [RFCXXXX] | 3382 | lifetime | 14 | 0/1 | IESG | [RFCXXXX] | 3383 | mitigation-start | 15 | 0 | IESG | [RFCXXXX] | 3384 | status | 16 | 0 | IESG | [RFCXXXX] | 3385 | conflict-information | 17 | 5 | IESG | [RFCXXXX] | 3386 | conflict-status | 18 | 0 | IESG | [RFCXXXX] | 3387 | conflict-cause | 19 | 0 | IESG | [RFCXXXX] | 3388 | retry-timer | 20 | 0 | IESG | [RFCXXXX] | 3389 | conflict-scope | 21 | 5 | IESG | [RFCXXXX] | 3390 | acl-list | 22 | 4 | IESG | [RFCXXXX] | 3391 | acl-name | 23 | 3 | IESG | [RFCXXXX] | 3392 | acl-type | 24 | 3 | IESG | [RFCXXXX] | 3393 | bytes-dropped | 25 | 0 | IESG | [RFCXXXX] | 3394 | bps-dropped | 26 | 0 | IESG | [RFCXXXX] | 3395 | pkts-dropped | 27 | 0 | IESG | [RFCXXXX] | 3396 | pps-dropped | 28 | 0 | IESG | [RFCXXXX] | 3397 | attack-status | 29 | 0 | IESG | [RFCXXXX] | 3398 | ietf-dots-signal- | 30 | 5 | IESG | [RFCXXXX] | 3399 | channel:signal-config| | | | | 3400 | sid | 31 | 0 | IESG | [RFCXXXX] | 3401 | mitigating-config | 32 | 5 | IESG | [RFCXXXX] | 3402 | heartbeat-interval | 33 | 5 | IESG | [RFCXXXX] | 3403 | min-value | 34 | 0 | IESG | [RFCXXXX] | 3404 | max-value | 35 | 0 | IESG | [RFCXXXX] | 3405 | current-value | 36 | 0 | IESG | [RFCXXXX] | 3406 | missing-hb-allowed | 37 | 5 | IESG | [RFCXXXX] | 3407 | max-retransmit | 38 | 5 | IESG | [RFCXXXX] | 3408 | ack-timeout | 39 | 5 | IESG | [RFCXXXX] | 3409 | ack-random-factor | 40 | 5 | IESG | [RFCXXXX] | 3410 | min-value-decimal | 41 | 6tag4 | IESG | [RFCXXXX] | 3411 | max-value-decimal | 42 | 6tag4 | IESG | [RFCXXXX] | 3412 | current-value- | 43 | 6tag4 | IESG | [RFCXXXX] | 3413 | decimal | | | | | 3414 | idle-config | 44 | 5 | IESG | [RFCXXXX] | 3415 | trigger-mitigation | 45 | 7 | IESG | [RFCXXXX] | 3416 | config-interval | 46 | 0 | IESG | [RFCXXXX] | 3417 | ietf-dots-signal-chan| 47 | 5 | IESG | [RFCXXXX] | 3418 | nel:redirected-signal| | | | | 3419 | alt-server | 48 | 3 | IESG | [RFCXXXX] | 3420 | alt-server-record | 49 | 4 | IESG | [RFCXXXX] | 3421 | addr | 50 | 3 | IESG | [RFCXXXX] | 3422 | ttl | 51 | 0 | IESG | [RFCXXXX] | 3423 +----------------------+-------+-------+------------+---------------+ 3425 Table 7: Initial DOTS Signal Channel CBOR Mappings Registry 3427 9.5. DOTS Signal Channel YANG Module 3429 This document requests IANA to register the following URI in the 3430 "IETF XML Registry" [RFC3688]: 3432 URI: urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel 3433 Registrant Contact: The IESG. 3434 XML: N/A; the requested URI is an XML namespace. 3436 This document requests IANA to register the following YANG module in 3437 the "YANG Module Names" registry [RFC7950]. 3439 name: ietf-signal 3440 namespace: urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel 3441 prefix: signal 3442 reference: RFC XXXX 3444 10. Implementation Status 3446 [Note to RFC Editor: Please remove this section and reference to 3447 [RFC7942] prior to publication.] 3449 This section records the status of known implementations of the 3450 protocol defined by this specification at the time of posting this 3451 Internet-Draft, and is based upon a proposal described in [RFC7942]. 3452 The description of implementations in this section is intended to 3453 assist the IETF in its decision-making process when progressing 3454 drafts to RFCs. Please note that the listing of any individual 3455 implementation here does not imply endorsement by the IETF. 3456 Furthermore, no effort has been spent to verify the information 3457 presented here, and which was provided by individuals. This is not 3458 intended as, and must not be construed to be, a catalog of available 3459 implementations or features. Readers are advised to note that other 3460 implementations may exist. 3462 According to [RFC7942], "this will allow reviewers and working groups 3463 to assign due consideration to documents that have the benefit of 3464 running code, which may serve as evidence of valuable experimentation 3465 and feedback that have made the implemented protocols more mature. 3466 It is up to the individual working groups to use this information as 3467 they see fit". 3469 10.1. nttdots 3471 Organization: NTT Communication is developing a DOTS client and 3472 DOTS server software based on DOTS signal channel specified in 3473 this draft. It will be open-sourced. 3475 Description: Early implementation of DOTS protocol. It is aimed to 3476 implement a full DOTS protocol specification in accordance with 3477 the nurturing DOTS protocol. 3479 Implementation: https://github.com/nttdots/go-dots 3481 Level of maturity: It is an early implementation of the DOTS 3482 protocol. Messaging between DOTS clients and DOTS servers has 3483 been tested. Level of maturity will increase in accordance with 3484 the nurturing DOTS protocol. 3486 Coverage: Capability of DOTS client: sending DOTS messages to the 3487 DOTS server in CoAP over DTLS as dots-signal. Capability of DOTS 3488 server: receiving dots-signal, validating received dots-signal, 3489 starting mitigation by handing over the dots-signal to DDoS 3490 mitigator. 3492 Licensing: It will be open-sourced with BSD 3-clause license. 3494 Implementation experience: It is implemented in Go-lang. Core 3495 specification of signaling is mature to be implemented, however, 3496 finding good libraries(like DTLS, CoAP) is rather difficult. 3498 Contact: Kaname Nishizuka 3500 11. Security Considerations 3502 Authenticated encryption MUST be used for data confidentiality and 3503 message integrity. The interaction between the DOTS agents requires 3504 Datagram Transport Layer Security (DTLS) and Transport Layer Security 3505 (TLS) with a cipher suite offering confidentiality protection and the 3506 guidance given in [RFC7525] MUST be followed to avoid attacks on 3507 (D)TLS. The (D)TLS protocol profile for DOTS signal channel is 3508 specified in Section 7. 3510 A single DOTS signal channel between DOTS agents can be used to 3511 exchange multiple DOTS signal messages. To reduce DOTS client and 3512 DOTS server workload, DOTS clients SHOULD re-use the (D)TLS session. 3514 If TCP is used between DOTS agents, an attacker may be able to inject 3515 RST packets, bogus application segments, etc., regardless of whether 3516 TLS authentication is used. Because the application data is TLS 3517 protected, this will not result in the application receiving bogus 3518 data, but it will constitute a DoS on the connection. This attack 3519 can be countered by using TCP-AO [RFC5925]. If TCP-AO is used, then 3520 any bogus packets injected by an attacker will be rejected by the 3521 TCP-AO integrity check and therefore will never reach the TLS layer. 3523 Rate-limiting DOTS requests, including those with new 'cuid' values, 3524 from the same DOTS client defends against DoS attacks that would 3525 result in varying the 'cuid' to exhaust DOTS server resources. Rate- 3526 limit policies SHOULD be enforced on DOTS gateways (if deployed) and 3527 DOTS servers. 3529 In order to prevent leaking internal information outside a client- 3530 domain, DOTS gateways located in the client-domain SHOULD NOT reveal 3531 the identification information that pertains to internal DOTS clients 3532 (e.g., source IP address, client's hostname) unless explicitly 3533 configured to do so. 3535 Special care should be taken in order to ensure that the activation 3536 of the proposed mechanism will not impact the stability of the 3537 network (including connectivity and services delivered over that 3538 network). 3540 12. Contributors 3542 The following individuals have contributed to this document: 3544 o Mike Geller, Cisco Systems, Inc. 3250 Florida 33309 USA, Email: 3545 mgeller@cisco.com 3547 o Robert Moskowitz, HTT Consulting Oak Park, MI 42837 United States, 3548 Email: rgm@htt-consult.com 3550 o Dan Wing, Email: dwing-ietf@fuggles.com 3552 o Jon Shallow, NCC Group, Email: jon.shallow@nccgroup.trust 3554 13. Acknowledgements 3556 Thanks to Christian Jacquenet, Roland Dobbins, Roman D. Danyliw, 3557 Michael Richardson, Ehud Doron, Kaname Nishizuka, Dave Dolson, Liang 3558 Xia, Gilbert Clark, and Nesredien Suleiman for the discussion and 3559 comments. 3561 Special thanks to Jon Shallow for the careful reviews and inputs that 3562 enhanced this specification. 3564 14. References 3566 14.1. Normative References 3568 [I-D.ietf-core-coap-tcp-tls] 3569 Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 3570 Silverajan, B., and B. Raymor, "CoAP (Constrained 3571 Application Protocol) over TCP, TLS, and WebSockets", 3572 draft-ietf-core-coap-tcp-tls-11 (work in progress), 3573 December 2017. 3575 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3576 Requirement Levels", BCP 14, RFC 2119, 3577 DOI 10.17487/RFC2119, March 1997, 3578 . 3580 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3581 DOI 10.17487/RFC3688, January 2004, 3582 . 3584 [RFC4279] Eronen, P., Ed. and H. Tschofenig, Ed., "Pre-Shared Key 3585 Ciphersuites for Transport Layer Security (TLS)", 3586 RFC 4279, DOI 10.17487/RFC4279, December 2005, 3587 . 3589 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3590 (TLS) Protocol Version 1.2", RFC 5246, 3591 DOI 10.17487/RFC5246, August 2008, 3592 . 3594 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3595 Housley, R., and W. Polk, "Internet X.509 Public Key 3596 Infrastructure Certificate and Certificate Revocation List 3597 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 3598 . 3600 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 3601 Uniform Resource Identifiers (URIs)", RFC 5785, 3602 DOI 10.17487/RFC5785, April 2010, 3603 . 3605 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 3606 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 3607 June 2010, . 3609 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 3610 Extensions: Extension Definitions", RFC 6066, 3611 DOI 10.17487/RFC6066, January 2011, 3612 . 3614 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 3615 Verification of Domain-Based Application Service Identity 3616 within Internet Public Key Infrastructure Using X.509 3617 (PKIX) Certificates in the Context of Transport Layer 3618 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 3619 2011, . 3621 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 3622 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 3623 DOI 10.17487/RFC6234, May 2011, 3624 . 3626 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 3627 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 3628 January 2012, . 3630 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 3631 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 3632 Transport Layer Security (TLS) and Datagram Transport 3633 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 3634 June 2014, . 3636 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 3637 Application Protocol (CoAP)", RFC 7252, 3638 DOI 10.17487/RFC7252, June 2014, 3639 . 3641 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 3642 "Recommendations for Secure Use of Transport Layer 3643 Security (TLS) and Datagram Transport Layer Security 3644 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 3645 2015, . 3647 [RFC7641] Hartke, K., "Observing Resources in the Constrained 3648 Application Protocol (CoAP)", RFC 7641, 3649 DOI 10.17487/RFC7641, September 2015, 3650 . 3652 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 3653 RFC 7950, DOI 10.17487/RFC7950, August 2016, 3654 . 3656 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 3657 Writing an IANA Considerations Section in RFCs", BCP 26, 3658 RFC 8126, DOI 10.17487/RFC8126, June 2017, 3659 . 3661 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 3662 FETCH Methods for the Constrained Application Protocol 3663 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 3664 . 3666 14.2. Informative References 3668 [I-D.ietf-core-comi] 3669 Veillette, M., Stok, P., Pelov, A., and A. Bierman, "CoAP 3670 Management Interface", draft-ietf-core-comi-02 (work in 3671 progress), December 2017. 3673 [I-D.ietf-core-yang-cbor] 3674 Veillette, M., Pelov, A., Somaraju, A., Turner, R., and A. 3675 Minaburo, "CBOR Encoding of Data Modeled with YANG", 3676 draft-ietf-core-yang-cbor-05 (work in progress), August 3677 2017. 3679 [I-D.ietf-dots-architecture] 3680 Mortensen, A., Andreasen, F., Reddy, T., 3681 christopher_gray3@cable.comcast.com, c., Compton, R., and 3682 N. Teague, "Distributed-Denial-of-Service Open Threat 3683 Signaling (DOTS) Architecture", draft-ietf-dots- 3684 architecture-05 (work in progress), October 2017. 3686 [I-D.ietf-dots-data-channel] 3687 Reddy, T., Boucadair, M., Nishizuka, K., Xia, L., Patil, 3688 P., Mortensen, A., and N. Teague, "Distributed Denial-of- 3689 Service Open Threat Signaling (DOTS) Data Channel", draft- 3690 ietf-dots-data-channel-11 (work in progress), December 3691 2017. 3693 [I-D.ietf-dots-requirements] 3694 Mortensen, A., Moskowitz, R., and T. Reddy, "Distributed 3695 Denial of Service (DDoS) Open Threat Signaling 3696 Requirements", draft-ietf-dots-requirements-10 (work in 3697 progress), January 2018. 3699 [I-D.ietf-dots-use-cases] 3700 Dobbins, R., Migault, D., Fouant, S., Moskowitz, R., 3701 Teague, N., Xia, L., and K. Nishizuka, "Use cases for DDoS 3702 Open Threat Signaling", draft-ietf-dots-use-cases-09 (work 3703 in progress), November 2017. 3705 [I-D.ietf-netmod-yang-tree-diagrams] 3706 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", draft- 3707 ietf-netmod-yang-tree-diagrams-04 (work in progress), 3708 December 2017. 3710 [I-D.ietf-tls-dtls13] 3711 Rescorla, E., Tschofenig, H., and N. Modadugu, "The 3712 Datagram Transport Layer Security (DTLS) Protocol Version 3713 1.3", draft-ietf-tls-dtls13-22 (work in progress), 3714 November 2017. 3716 [I-D.ietf-tls-tls13] 3717 Rescorla, E., "The Transport Layer Security (TLS) Protocol 3718 Version 1.3", draft-ietf-tls-tls13-23 (work in progress), 3719 January 2018. 3721 [proto_numbers] 3722 "IANA, "Protocol Numbers"", 2011, 3723 . 3725 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 3726 DOI 10.17487/RFC0791, September 1981, 3727 . 3729 [RFC1983] Malkin, G., Ed., "Internet Users' Glossary", FYI 18, 3730 RFC 1983, DOI 10.17487/RFC1983, August 1996, 3731 . 3733 [RFC3022] Srisuresh, P. and K. Egevang, "Traditional IP Network 3734 Address Translator (Traditional NAT)", RFC 3022, 3735 DOI 10.17487/RFC3022, January 2001, 3736 . 3738 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3739 Resource Identifier (URI): Generic Syntax", STD 66, 3740 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3741 . 3743 [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram 3744 Congestion Control Protocol (DCCP)", RFC 4340, 3745 DOI 10.17487/RFC4340, March 2006, 3746 . 3748 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 3749 (CIDR): The Internet Address Assignment and Aggregation 3750 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 3751 2006, . 3753 [RFC4732] Handley, M., Ed., Rescorla, E., Ed., and IAB, "Internet 3754 Denial-of-Service Considerations", RFC 4732, 3755 DOI 10.17487/RFC4732, December 2006, 3756 . 3758 [RFC4787] Audet, F., Ed. and C. Jennings, "Network Address 3759 Translation (NAT) Behavioral Requirements for Unicast 3760 UDP", BCP 127, RFC 4787, DOI 10.17487/RFC4787, January 3761 2007, . 3763 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 3764 RFC 4960, DOI 10.17487/RFC4960, September 2007, 3765 . 3767 [RFC4987] Eddy, W., "TCP SYN Flooding Attacks and Common 3768 Mitigations", RFC 4987, DOI 10.17487/RFC4987, August 2007, 3769 . 3771 [RFC5077] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, 3772 "Transport Layer Security (TLS) Session Resumption without 3773 Server-Side State", RFC 5077, DOI 10.17487/RFC5077, 3774 January 2008, . 3776 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 3777 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 3778 DOI 10.17487/RFC5389, October 2008, 3779 . 3781 [RFC6146] Bagnulo, M., Matthews, P., and I. van Beijnum, "Stateful 3782 NAT64: Network Address and Protocol Translation from IPv6 3783 Clients to IPv4 Servers", RFC 6146, DOI 10.17487/RFC6146, 3784 April 2011, . 3786 [RFC6296] Wasserman, M. and F. Baker, "IPv6-to-IPv6 Network Prefix 3787 Translation", RFC 6296, DOI 10.17487/RFC6296, June 2011, 3788 . 3790 [RFC6724] Thaler, D., Ed., Draves, R., Matsumoto, A., and T. Chown, 3791 "Default Address Selection for Internet Protocol Version 6 3792 (IPv6)", RFC 6724, DOI 10.17487/RFC6724, September 2012, 3793 . 3795 [RFC6887] Wing, D., Ed., Cheshire, S., Boucadair, M., Penno, R., and 3796 P. Selkirk, "Port Control Protocol (PCP)", RFC 6887, 3797 DOI 10.17487/RFC6887, April 2013, 3798 . 3800 [RFC6888] Perreault, S., Ed., Yamagata, I., Miyakawa, S., Nakagawa, 3801 A., and H. Ashida, "Common Requirements for Carrier-Grade 3802 NATs (CGNs)", BCP 127, RFC 6888, DOI 10.17487/RFC6888, 3803 April 2013, . 3805 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 3806 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 3807 October 2013, . 3809 [RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 3810 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 3811 . 3813 [RFC7452] Tschofenig, H., Arkko, J., Thaler, D., and D. McPherson, 3814 "Architectural Considerations in Smart Object Networking", 3815 RFC 7452, DOI 10.17487/RFC7452, March 2015, 3816 . 3818 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 3819 NETCONF Protocol over Transport Layer Security (TLS) with 3820 Mutual X.509 Authentication", RFC 7589, 3821 DOI 10.17487/RFC7589, June 2015, 3822 . 3824 [RFC7918] Langley, A., Modadugu, N., and B. Moeller, "Transport 3825 Layer Security (TLS) False Start", RFC 7918, 3826 DOI 10.17487/RFC7918, August 2016, 3827 . 3829 [RFC7924] Santesson, S. and H. Tschofenig, "Transport Layer Security 3830 (TLS) Cached Information Extension", RFC 7924, 3831 DOI 10.17487/RFC7924, July 2016, 3832 . 3834 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 3835 Code: The Implementation Status Section", BCP 205, 3836 RFC 7942, DOI 10.17487/RFC7942, July 2016, 3837 . 3839 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 3840 RFC 7951, DOI 10.17487/RFC7951, August 2016, 3841 . 3843 [RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 3844 Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, 3845 March 2017, . 3847 [RFC8305] Schinazi, D. and T. Pauly, "Happy Eyeballs Version 2: 3848 Better Connectivity Using Concurrency", RFC 8305, 3849 DOI 10.17487/RFC8305, December 2017, 3850 . 3852 Authors' Addresses 3854 Tirumaleswar Reddy (editor) 3855 McAfee, Inc. 3856 Embassy Golf Link Business Park 3857 Bangalore, Karnataka 560071 3858 India 3860 Email: kondtir@gmail.com 3862 Mohamed Boucadair (editor) 3863 Orange 3864 Rennes 35000 3865 France 3867 Email: mohamed.boucadair@orange.com 3869 Prashanth Patil 3870 Cisco Systems, Inc. 3872 Email: praspati@cisco.com 3874 Andrew Mortensen 3875 Arbor Networks, Inc. 3876 2727 S. State St 3877 Ann Arbor, MI 48104 3878 United States 3880 Email: amortensen@arbor.net 3882 Nik Teague 3883 Verisign, Inc. 3884 United States 3886 Email: nteague@verisign.com