idnits 2.17.00 (12 Aug 2021) /tmp/idnits500/draft-ietf-dots-signal-channel-13.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 6 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 1917 has weird spacing: '...er-port ine...' == Line 1918 has weird spacing: '...er-port ine...' == Line 1933 has weird spacing: '...er-port ine...' == Line 1934 has weird spacing: '...er-port ine...' -- The document date (December 13, 2017) is 1619 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 2759, but not defined == Outdated reference: draft-ietf-core-coap-tcp-tls has been published as RFC 8323 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) ** Downref: Normative reference to an Informational RFC: RFC 6234 ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) == Outdated reference: A later version (-11) exists of draft-ietf-core-comi-02 == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-05 == Outdated reference: draft-ietf-dots-architecture has been published as RFC 8811 == Outdated reference: draft-ietf-dots-data-channel has been published as RFC 8783 == Outdated reference: draft-ietf-dots-requirements has been published as RFC 8612 == Outdated reference: draft-ietf-dots-use-cases has been published as RFC 8903 == Outdated reference: draft-ietf-netmod-yang-tree-diagrams has been published as RFC 8340 == Outdated reference: draft-ietf-tls-dtls13 has been published as RFC 9147 == Outdated reference: draft-ietf-tls-tls13 has been published as RFC 8446 -- Obsolete informational reference (is this intentional?): RFC 5077 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 5389 (Obsoleted by RFC 8489) -- Obsolete informational reference (is this intentional?): RFC 6555 (Obsoleted by RFC 8305) -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) Summary: 6 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 3 Internet-Draft McAfee 4 Intended status: Standards Track M. Boucadair 5 Expires: June 16, 2018 Orange 6 P. Patil 7 Cisco 8 A. Mortensen 9 Arbor Networks, Inc. 10 N. Teague 11 Verisign, Inc. 12 December 13, 2017 14 Distributed Denial-of-Service Open Threat Signaling (DOTS) Signal 15 Channel 16 draft-ietf-dots-signal-channel-13 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 o This RFC 45 Please update TBD statements with the port number to be assigned to 46 DOTS Signal Channel Protocol. 48 Status of This Memo 50 This Internet-Draft is submitted in full conformance with the 51 provisions of BCP 78 and BCP 79. 53 Internet-Drafts are working documents of the Internet Engineering 54 Task Force (IETF). Note that other groups may also distribute 55 working documents as Internet-Drafts. The list of current Internet- 56 Drafts is at https://datatracker.ietf.org/drafts/current/. 58 Internet-Drafts are draft documents valid for a maximum of six months 59 and may be updated, replaced, or obsoleted by other documents at any 60 time. It is inappropriate to use Internet-Drafts as reference 61 material or to cite them other than as "work in progress." 63 This Internet-Draft will expire on June 16, 2018. 65 Copyright Notice 67 Copyright (c) 2017 IETF Trust and the persons identified as the 68 document authors. All rights reserved. 70 This document is subject to BCP 78 and the IETF Trust's Legal 71 Provisions Relating to IETF Documents 72 (https://trustee.ietf.org/license-info) in effect on the date of 73 publication of this document. Please review these documents 74 carefully, as they describe your rights and restrictions with respect 75 to this document. Code Components extracted from this document must 76 include Simplified BSD License text as described in Section 4.e of 77 the Trust Legal Provisions and are provided without warranty as 78 described in the Simplified BSD License. 80 Table of Contents 82 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 83 2. Notational Conventions and Terminology . . . . . . . . . . . 5 84 3. Design Overview . . . . . . . . . . . . . . . . . . . . . . . 6 85 4. DOTS Signal Channel: Messages & Behaviors . . . . . . . . . . 8 86 4.1. DOTS Server(s) Discovery . . . . . . . . . . . . . . . . 8 87 4.2. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . 8 88 4.3. Happy Eyeballs for DOTS Signal Channel . . . . . . . . . 9 89 4.4. DOTS Mitigation Methods . . . . . . . . . . . . . . . . . 10 90 4.4.1. Request Mitigation . . . . . . . . . . . . . . . . . 11 91 4.4.2. Retrieve Information Related to a Mitigation . . . . 20 92 4.4.3. Efficacy Update from DOTS Clients . . . . . . . . . . 28 93 4.4.4. Withdraw a Mitigation . . . . . . . . . . . . . . . . 30 94 4.5. DOTS Signal Channel Session Configuration . . . . . . . . 32 95 4.5.1. Discover Configuration Parameters . . . . . . . . . . 33 96 4.5.2. Convey DOTS Signal Channel Session Configuration . . 35 97 4.5.3. Delete DOTS Signal Channel Session Configuration . . 40 98 4.6. Redirected Signaling . . . . . . . . . . . . . . . . . . 40 99 4.7. Heartbeat Mechanism . . . . . . . . . . . . . . . . . . . 42 100 5. DOTS Signal Channel YANG Module . . . . . . . . . . . . . . . 43 101 5.1. Tree Structure . . . . . . . . . . . . . . . . . . . . . 43 102 5.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 45 103 6. Mapping Parameters to CBOR . . . . . . . . . . . . . . . . . 55 104 7. (D)TLS Protocol Profile and Performance Considerations . . . 56 105 7.1. (D)TLS Protocol Profile . . . . . . . . . . . . . . . . . 56 106 7.2. (D)TLS 1.3 Considerations . . . . . . . . . . . . . . . . 58 107 7.3. MTU and Fragmentation . . . . . . . . . . . . . . . . . . 59 108 8. Mutual Authentication of DOTS Agents & Authorization of DOTS 109 Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 110 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 61 111 9.1. DOTS Signal Channel UDP and TCP Port Number . . . . . . . 61 112 9.2. Well-Known 'dots' URI . . . . . . . . . . . . . . . . . . 61 113 9.3. CoAP Response Code . . . . . . . . . . . . . . . . . . . 61 114 9.4. DOTS Signal Channel CBOR Mappings Registry . . . . . . . 62 115 9.4.1. Registration Template . . . . . . . . . . . . . . . . 62 116 9.4.2. Initial Registry Contents . . . . . . . . . . . . . . 62 117 9.5. DOTS Signal Channel YANG Module . . . . . . . . . . . . . 68 118 10. Implementation Status . . . . . . . . . . . . . . . . . . . . 68 119 10.1. nttdots . . . . . . . . . . . . . . . . . . . . . . . . 69 120 11. Security Considerations . . . . . . . . . . . . . . . . . . . 69 121 12. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 70 122 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 70 123 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 71 124 14.1. Normative References . . . . . . . . . . . . . . . . . . 71 125 14.2. Informative References . . . . . . . . . . . . . . . . . 73 126 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 76 128 1. Introduction 130 A distributed denial-of-service (DDoS) attack is an attempt to make 131 machines or network resources unavailable to their intended users. 132 In most cases, sufficient scale can be achieved by compromising 133 enough end-hosts and using those infected hosts to perpetrate and 134 amplify the attack. The victim in this attack can be an application 135 server, a host, a router, a firewall, or an entire network. 137 Network applications have finite resources like CPU cycles, the 138 number of processes or threads they can create and use, the maximum 139 number of simultaneous connections it can handle, the limited 140 resources of the control plane, etc. When processing network 141 traffic, such applications are supposed to use these resources to 142 offer the intended task in the most efficient manner. However, a 143 DDoS attacker may be able to prevent an application from performing 144 its intended task by making the application exhaust its finite 145 resources. 147 TCP DDoS SYN-flood, for example, is a memory-exhausting attack while 148 ACK-flood is a CPU-exhausting attack [RFC4987]. Attacks on the link 149 are carried out by sending enough traffic so that the link becomes 150 congested, thereby likely causing packet loss for legitimate traffic. 151 Stateful firewalls can also be attacked by sending traffic that 152 causes the firewall to maintain an excessive number of states that 153 may jeopardize the firewall's operation overall, besides like 154 performance impacts. The firewall then runs out of memory, and can 155 no longer instantiate the states required to process legitimate 156 flows. Other possible DDoS attacks are discussed in [RFC4732]. 158 In many cases, it may not be possible for network administrators to 159 determine the cause(s) of an attack. They may instead just realize 160 that certain resources seem to be under attack. This document 161 defines a lightweight protocol that allows a DOTS client to request 162 mitigation from one or more DOTS servers for protection against 163 detected, suspected, or anticipated attacks. This protocol enables 164 cooperation between DOTS agents to permit a highly-automated network 165 defense that is robust, reliable, and secure. 167 An example of a network diagram that illustrates a deployment of DOTS 168 agents is shown in Figure 1. In this example, a DOTS server is 169 operating on the access network. A DOTS client is located on the LAN 170 (Local Area Network), while a DOTS gateway is embedded in the CPE 171 (Customer Premises Equipment). 173 Network 174 Resource CPE router Access network __________ 175 +-----------+ +--------------+ +-------------+ / \ 176 | |____| |_______| |___ | Internet | 177 |DOTS client| | DOTS gateway | | DOTS server | | | 178 | | | | | | | | 179 +-----------+ +--------------+ +-------------+ \__________/ 181 Figure 1: Sample DOTS Deployment (1) 183 DOTS servers can also be reachable over the Internet, as depicted in 184 Figure 2. 186 Network DDoS mitigation 187 Resource CPE router __________ service 188 +-----------+ +-------------+ / \ +-------------+ 189 | |____| |_______| |___ | | 190 |DOTS client| |DOTS gateway | | Internet | | DOTS server | 191 | | | | | | | | 192 +-----------+ +-------------+ \__________/ +-------------+ 194 Figure 2: Sample DOTS Deployment (2) 196 In typical deployments, the DOTS client belongs to a different 197 administrative domain than the DOTS server. For example, the DOTS 198 client is embedded in a firewall protecting services owned and 199 operated by a domain, while the DOTS server is owned and operated by 200 a different domain providing DDoS mitigation services. The latter 201 might or might not provide connectivity services to the network 202 hosting the DOTS client. 204 The DOTS server may (not) be co-located with the DOTS mitigator. In 205 typical deployments, the DOTS server belongs to the same 206 administrative domain as the mitigator. The DOTS client can 207 communicate directly with a DOTS server or indirectly via a DOTS 208 gateway. 210 The document adheres to the DOTS architecture 211 [I-D.ietf-dots-architecture]. The requirements for DOTS signal 212 channel protocol are documented in [I-D.ietf-dots-requirements]. 213 This document satisfies all the use cases discussed in 214 [I-D.ietf-dots-use-cases]. 216 This document focuses on the DOTS signal channel. This is a 217 companion document of the DOTS data channel specification 218 [I-D.ietf-dots-data-channel] that defines a configuration and a bulk 219 data exchange mechanism supporting the DOTS signal channel. 221 2. Notational Conventions and Terminology 223 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 224 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 225 "OPTIONAL" in this document are to be interpreted as described in 226 [RFC2119]. 228 (D)TLS is used for statements that apply to both Transport Layer 229 Security [RFC5246] and Datagram Transport Layer Security [RFC6347]. 230 Specific terms will be used for any statement that applies to either 231 protocol alone. 233 The reader should be familiar with the terms defined in 234 [I-D.ietf-dots-architecture]. 236 The meaning of the symbols in YANG tree diagrams is defined in 237 [I-D.ietf-netmod-yang-tree-diagrams]. 239 3. Design Overview 241 The DOTS signal channel is built on top of the Constrained 242 Application Protocol (CoAP) [RFC7252], a lightweight protocol 243 originally designed for constrained devices and networks. The many 244 features of CoAP (expectation of packet loss, support for 245 asynchronous non-confirmable messaging, congestion control, small 246 message overhead limiting the need for fragmentation, use of minimal 247 resources, and support for (D)TLS) makes it a good candidate to build 248 the DOTS signaling mechanism from. 250 The DOTS signal channel is layered on existing standards (Figure 3). 252 +--------------+ 253 | DOTS | 254 +--------------+ 255 | CoAP | 256 +--------------+ 257 | TLS | DTLS | 258 +--------------+ 259 | TCP | UDP | 260 +--------------+ 261 | IP | 262 +--------------+ 264 Figure 3: Abstract Layering of DOTS signal channel over CoAP over 265 (D)TLS 267 By default, a DOTS signal channel MUST run over port number TBD as 268 defined in Section 9.1, for both UDP and TCP, unless the DOTS server 269 has a mutual agreement with its DOTS clients to use a different port 270 number. DOTS clients may alternatively support means to dynamically 271 discover the ports used by their DOTS servers. In order to use a 272 distinct port number (as opposed to TBD), DOTS clients and servers 273 should support a configurable parameter to supply the port number to 274 use. The rationale for not using the default port number 5684 275 ((D)TLS CoAP) is to allow for differentiated behaviors in 276 environments where both a DOTS gateway and an IoT gateway (e.g., 277 Figure 3 of [RFC7452]) are present. 279 The signal channel is initiated by the DOTS client (Section 4.4). 280 Once the signal channel is established, the DOTS agents periodically 281 send heartbeats to keep the channel active (Section 4.7). At any 282 time, the DOTS client may send a mitigation request message to a DOTS 283 server over the active channel. While mitigation is active because 284 of the higher likelihood of packet loss during a DDoS attack, the 285 DOTS server periodically sends status messages to the client, 286 including basic mitigation feedback details. Mitigation remains 287 active until the DOTS client explicitly terminates mitigation, or the 288 mitigation lifetime expires. 290 DOTS signaling can happen with DTLS [RFC6347] over UDP and TLS 291 [RFC5246] over TCP. Likewise, DOTS requests may be sent using IPv4 292 or IPv6 transfer capabilities. A Happy Eyeballs procedure for DOTS 293 signal channel is specified in Section 4.3. 295 Messages exchanged between DOTS agents are serialized using Concise 296 Binary Object Representation (CBOR) [RFC7049], CBOR is a binary 297 encoding scheme designed for small code and message size. CBOR- 298 encoded payloads are used to carry signal channel-specific payload 299 messages which convey request parameters and response information 300 such as errors. In order to allow the use of the same data models, 301 [RFC7951] specifies the JSON encoding of YANG-modeled data. A 302 similar effort for CBOR is defined in [I-D.ietf-core-yang-cbor]. 304 From that standpoint, this document specifies a YANG data model for 305 representing mitigation scopes and DOTS signal channel session 306 configuration data (Section 5). Representing these data as CBOR data 307 is assumed to follow the rules in [I-D.ietf-core-yang-cbor] or those 308 in [RFC7951] combined with JSON/CBOR conversion rules in [RFC7049]. 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., NAT44, NAT64, 335 NPTv6) are enabled between the client's network and the DOTS server, 336 DOTS signal channel messages forwarded to a DOTS server must not 337 include internal IP addresses/prefixes and/or port numbers; external 338 addresses/ prefixes and/or port numbers as assigned by the translator 339 must be used instead. This document does not make any recommendation 340 about possible translator discovery mechanisms. The following are 341 some (non-exhaustive) deployment examples that may be considered: 343 o Port Control Protocol (PCP) [RFC6887] or Session Traversal 344 Utilities for NAT (STUN) [RFC5389] may be used to retrieve the 345 external addresses/prefixes and/or port numbers. Information 346 retrieved by means of PCP will be used to feed the DOTS signal 347 channel messages that will be sent to a DOTS server. 349 o A DOTS gateway may be co-located with the translator. The DOTS 350 gateway will need to update the DOTS messages, based upon the 351 local translator's binding table. 353 4. DOTS Signal Channel: Messages & Behaviors 355 4.1. DOTS Server(s) Discovery 357 This document assumes that DOTS clients are provisioned with the 358 reachability information of their DOTS server(s) using a variety of 359 means (e.g., local configuration, or dynamic means such as DHCP). 360 These means are out of scope of this document. 362 Likewise, it is out of scope of this document to specify the behavior 363 of a DOTS client when it sends requests (e.g., contact all servers, 364 select one server among the list) when multiple DOTS servers are 365 provisioned. 367 4.2. CoAP URIs 369 The DOTS server MUST support the use of the path-prefix of "/.well- 370 known/" as defined in [RFC5785] and the registered name of "dots". 371 Each DOTS operation is indicated by a path-suffix that indicates the 372 intended operation. The operation path (Table 1) is appended to the 373 path-prefix to form the URI used with a CoAP request to perform the 374 desired DOTS operation. 376 +-----------------------+----------------+-------------+ 377 | Operation | Operation path | Details | 378 +-----------------------+----------------+-------------+ 379 | Mitigation | /v1/mitigate | Section 4.4 | 380 +-----------------------+----------------+-------------+ 381 | Session configuration | /v1/config | Section 4.5 | 382 +-----------------------+----------------+-------------+ 384 Table 1: Operations and their corresponding URIs 386 4.3. Happy Eyeballs for DOTS Signal Channel 388 DOTS signaling can operate with DTLS over UDP and TLS over TCP. A 389 DOTS client can use DNS to determine the IP address(es) of a DOTS 390 server or a DOTS client may be provided with the list of the IP 391 addresses of various DOTS servers. The DOTS client MUST know a DOTS 392 server's domain name; hard-coding the domain name of the DOTS server 393 into software is NOT RECOMMENDED in case the domain name is not valid 394 or needs to change for legal or other reasons. The DOTS client 395 performs A and/or AAAA record lookup of the domain name and the 396 result will be a list of IP addresses, each of which can be used to 397 contact the DOTS server using UDP and TCP. 399 If an IPv4 path to reach a DOTS server is found, but the DOTS 400 server's IPv6 path is not working, a dual-stack DOTS client can 401 experience a significant connection delay compared to an IPv4-only 402 DOTS client. The other problem is that if a middlebox between the 403 DOTS client and DOTS server is configured to block UDP traffic, the 404 DOTS client will fail to establish a DTLS session with the DOTS 405 server and , as a consequence, will have to fall back to TLS over 406 TCP, thereby incurring significant connection delays. 407 [I-D.ietf-dots-requirements] mentions that DOTS agents will have to 408 support both connectionless and connection-oriented protocols. 410 To overcome these connection setup problems, the DOTS client can 411 attempt to connect to the DOTS server using both IPv6 and IPv4, and 412 try both DTLS over UDP and TLS over TCP in a manner similar to the 413 Happy Eyeballs mechanism [RFC6555]. These connection attempts are 414 performed by the DOTS client when it initializes, and the DOTS client 415 uses the results of the Happy Eyeballs procedure for sending its 416 subsequent messages to the DOTS server. 418 In order of preference (most preferred first), it is UDP over IPv6, 419 UDP over IPv4, TCP over IPv6, and finally TCP over IPv4, which 420 adheres to address preference order [RFC6724] and the DOTS 421 preference, which privileges the use of UDP over TCP (to avoid TCP's 422 head of line blocking). 424 DOTS client DOTS server 425 | | 426 |--DTLS ClientHello, IPv6 ---->X | 427 |--TCP SYN, IPv6-------------->X | 428 |--DTLS ClientHello, IPv4 ---->X | 429 |--TCP SYN, IPv4----------------------------------------->| 430 |--DTLS ClientHello, IPv6 ---->X | 431 |--TCP SYN, IPv6-------------->X | 432 |<-TCP SYNACK---------------------------------------------| 433 |--DTLS ClientHello, IPv4 ---->X | 434 |--TCP ACK----------------------------------------------->| 435 |<------------Establish TLS Session---------------------->| 436 |----------------DOTS signal----------------------------->| 437 | | 439 Figure 4: DOTS Happy Eyeballs 441 In reference to Figure 4, the DOTS client sends two TCP SYNs and two 442 DTLS ClientHello messages at the same time over IPv6 and IPv4. In 443 this example, it is assumed that the IPv6 path is broken and UDP is 444 dropped by a middlebox but has little impact to the DOTS client 445 because there is no long delay before using IPv4 and TCP. The DOTS 446 client repeats the mechanism to discover if DOTS signaling with DTLS 447 over UDP becomes available from the DOTS server, so the DOTS client 448 can migrate the DOTS signal channel from TCP to UDP. But such 449 probing SHOULD NOT be done more frequently than every 24 hours and 450 MUST NOT be done more frequently than every 5 minutes. 452 4.4. DOTS Mitigation Methods 454 The following methods are used by a DOTS client to request, withdraw, 455 or retrieve the status of mitigation requests: 457 PUT: DOTS clients use the PUT method to request mitigation from a 458 DOTS server (Section 4.4.1). During active mitigation, DOTS 459 clients may use PUT requests to carry mitigation efficacy 460 updates to the DOTS server (Section 4.4.3). 462 GET: DOTS clients may use the GET method to subscribe to DOTS 463 server status messages, or to retrieve the list of its 464 mitigations maintained by a DOTS server (Section 4.4.2). 466 DELETE: DOTS clients use the DELETE method to withdraw a request for 467 mitigation from a DOTS server (Section 4.4.4). 469 Mitigation request and response messages are marked as Non- 470 confirmable messages (Section 2.2 of [RFC7252]). 472 DOTS agents SHOULD follow the data transmission guidelines discussed 473 in Section 3.1.3 of [RFC8085] and control transmission behavior by 474 not sending more than one UDP datagram per RTT to the peer DOTS agent 475 on average. 477 Requests marked by the DOTS client as Non-confirmable messages are 478 sent at regular intervals until a response is received from the DOTS 479 server. If the DOTS client cannot maintain an RTT estimate, it 480 SHOULD NOT send more than one Non-confirmable request every 3 481 seconds, and SHOULD use an even less aggressive rate whenever 482 possible (case 2 in Section 3.1.3 of [RFC8085]). 484 4.4.1. Request Mitigation 486 When a DOTS client requires mitigation for some reason, the DOTS 487 client uses the CoAP PUT method to send a mitigation request to its 488 DOTS server(s) (Figure 5, illustrated in JSON diagnostic notation). 489 If this DOTS client is entitled to solicit the DOTS service, the DOTS 490 server can enable mitigation on behalf of the DOTS client by 491 communicating the DOTS client's request to the mitigator and relaying 492 selected mitigator feedback to the requesting DOTS client. 494 Header: PUT (Code=0.03) 495 Uri-Host: "host" 496 Uri-Path: ".well-known" 497 Uri-Path: "dots" 498 Uri-Path: "version" 499 Uri-Path: "mitigate" 500 Content-Type: "application/cbor" 501 { 502 "mitigation-scope": { 503 "client-identifier": [ 504 "string" 505 ], 506 "scope": [ 507 { 508 "mitigation-id": integer, 509 "target-prefix": [ 510 "string" 511 ], 512 "target-port-range": [ 513 { 514 "lower-port": integer, 515 "upper-port": integer 516 } 517 ], 518 "target-protocol": [ 519 integer 520 ], 521 "target-fqdn": [ 522 "string" 523 ], 524 "target-uri": [ 525 "string" 526 ], 527 "alias-name": [ 528 "string" 529 ], 530 "lifetime": integer 531 } 532 ] 533 } 534 } 536 Figure 5: PUT to convey DOTS mitigation requests 538 The parameters are described below: 540 client-identifier: The client identifier MAY be conveyed by the DOTS 541 gateway to propagate the DOTS client identity from the gateway's 542 client-side to the gateway's server-side, and from the gateway's 543 server-side to the DOTS server. This allows the DOTS server to 544 accept mitigation requests with scopes which the DOTS client is 545 authorized to manage. 547 The 'client-identifier' value MUST be assigned by the DOTS gateway 548 in a manner that ensures that there is zero probability that the 549 same value will be assigned to a different DOTS client. The DOTS 550 gateway MUST conceal potentially sensitive DOTS client identity 551 information. The client-identifier attribute SHOULD NOT be 552 generated and included by the DOTS client. 554 This is an optional attribute. 556 mitigation-id: Identifier for the mitigation request represented 557 with an integer. This identifier MUST be unique for each 558 mitigation request bound to the DOTS client, i.e., the mitigation- 559 id parameter value in the mitigation request needs to be unique 560 relative to the mitigation-id parameter values of active 561 mitigation requests conveyed from the DOTS client to the DOTS 562 server. This identifier MUST be generated by the DOTS client. 563 This document does not make any assumption about how this 564 identifier is generated. 566 This is a mandatory attribute. 568 target-prefix: A list of prefixes identifying resources under 569 attack. Prefixes are represented using Classless Inter-Domain 570 Routing (CIDR) notation [RFC4632]. 571 As a reminder, the prefix length must be less than or equal to 32 572 (resp. 128) for IPv4 (resp. IPv6). 574 This is an optional attribute. 576 target-port-range: A list of port numbers bound to resources under 577 attack. 579 The port range is defined by two bounds, a lower port number 580 (lower-port) and an upper port number (upper-port). When only 581 'lower-port' is present, it represents a single port number. For 582 TCP, UDP, Stream Control Transmission Protocol (SCTP) [RFC4960], 583 or Datagram Congestion Control Protocol (DCCP) [RFC4340], the 584 range of ports can be, for example, 1024-65535. 586 This is an optional attribute. 588 target-protocol: A list of protocols involved in an attack. Values 589 are taken from the IANA protocol registry [proto_numbers]. 591 The value 0 has a special meaning for 'all protocols'. 593 This is an optional attribute. 595 target-fqdn: A list of Fully Qualified Domain Names (FQDNs) 596 identifying resources under attack. An FQDN is the full name of a 597 resource, rather than just its hostname. For example, "venera" is 598 a hostname, and "venera.isi.edu" is an FQDN. 600 This is an optional attribute. 602 target-uri: A list of Uniform Resource Identifiers (URIs) [RFC3986] 603 identifying resources under attack. 605 This is an optional attribute. 607 alias-name: A list of aliases of resources for which the mitigation 608 is requested. Aliases can be created using the DOTS data channel 609 (Section 6.1 of [I-D.ietf-dots-data-channel]), direct 610 configuration, or other means. An alias is used in subsequent 611 signal channel exchanges to refer more efficiently to the 612 resources under attack. 614 This is an optional attribute. 616 lifetime: Lifetime of the mitigation request in seconds. The 617 RECOMMENDED lifetime of a mitigation request is 3600 seconds (60 618 minutes) -- this value was chosen to be long enough so that 619 refreshing is not typically a burden on the DOTS client, while 620 expiring the request where the client has unexpectedly quit in a 621 timely manner. DOTS clients MUST include this parameter in their 622 mitigation requests. Upon the expiry of this lifetime, and if the 623 request is not refreshed, the mitigation request is removed. The 624 request can be refreshed by sending the same request again. 626 A lifetime of 0 in a mitigation request is an invalid value. 628 A lifetime of negative one (-1) indicates indefinite lifetime for 629 the mitigation request. The DOTS server MAY refuse indefinite 630 lifetime, for policy reasons; the granted lifetime value is 631 returned in the response. DOTS clients MUST be prepared to not be 632 granted mitigations with indefinite lifetimes. 634 The DOTS server MUST always indicate the actual lifetime in the 635 response and the remaining lifetime in status messages sent to the 636 DOTS client. 638 This is a mandatory attribute. 640 Because of the complexity to handle partial failure cases, this 641 specification does not allow for including multiple mitigation 642 requests in the same PUT request. Concretely, a DOTS client MUST NOT 643 include multiple 'scope' parameters in the same PUT request. 645 The CBOR key values for the parameters are defined in Section 6. 646 Section 9 defines how the CBOR key values can be allocated to 647 standard bodies and vendors. 649 FQDN and URI mitigation scopes may be thought of as a form of scope 650 alias, in which the addresses to which the domain name or URI resolve 651 represent the full scope of the mitigation. 653 In the PUT request at least one of the attributes 'target-prefix' or 654 'target-fqdn' or 'target-uri 'or 'alias-name' MUST be present. If 655 the attribute value is empty, then the attribute MUST NOT be present 656 in the request. 658 The relative order of two mitigation requests from a DOTS client is 659 determined by comparing their respective 'mitigation-id' values. If 660 two mitigation requests have overlapping mitigation scopes, the 661 mitigation request with the highest numeric 'mitigation-id' value 662 will override the other mitigation request. Two mitigation-ids from 663 a DOTS client are overlapping if there is a common IP address, IP 664 prefix, FQDN, URI, or alias-name. To avoid maintaining a long list 665 of overlapping mitigation requests from a DOTS client and avoid 666 error-prone provisioning of mitigation requests from a DOTS client, 667 the overlapped lower numeric 'mitigation-id' MUST be automatically 668 deleted and no longer available at the DOTS server. 670 The Uri-Path option carries a major and minor version nomenclature to 671 manage versioning and DOTS signal channel in this specification uses 672 v1 major version. 674 Figure 6 shows a PUT request example to signal that ports 80, 8080, 675 and 443 used by 2001:db8:6401::1 and 2001:db8:6401::2 servers are 676 under attack (illustrated in JSON diagnostic notation). 678 Header: PUT (Code=0.03) 679 Uri-Host: "www.example.com" 680 Uri-Path: ".well-known" 681 Uri-Path: "dots" 682 Uri-Path: "v1" 683 Uri-Path: "mitigate" 684 Content-Format: "application/cbor" 685 { 686 "mitigation-scope": { 687 "client-identifier": [ 688 "dz6pHjaADkaFTbjr0JGBpw" 689 ], 690 "scope": [ 691 { 692 "mitigation-id": 12332, 693 "target-prefix": [ 694 "2001:db8:6401::1/128", 695 "2001:db8:6401::2/128" 696 ], 697 "target-port-range": [ 698 { 699 "lower-port": 80 700 }, 701 { 702 "lower-port": 443 703 }, 704 { 705 "lower-port": 8080 706 } 707 ], 708 "target-protocol": [ 709 6 710 ] 711 } 712 ] 713 } 714 } 716 Figure 6: PUT for DOTS signal 718 The corresponding CBOR encoding format is shown in Figure 7. 720 A1 # map(1) 721 01 # unsigned(1) 722 A2 # map(2) 723 18 20 # unsigned(32) 724 81 # array(1) 725 76 # text(22) 726 647A3670486A6141446B614654626A72304A47427077 # "dz6pHjaADkaFTbjr0JGBpw" 727 02 # unsigned(2) 728 81 # array(1) 729 A4 # map(4) 730 03 # unsigned(3) 731 19 302C # unsigned(12332) 732 04 # unsigned(4) 733 82 # array(2) 734 74 # text(20) 735 323030313A6462383A363430313A3A312F313238 # "2001:db8:6401::1/128" 736 74 # text(20) 737 323030313A6462383A363430313A3A322F313238 # "2001:db8:6401::2/128" 738 05 # unsigned(5) 739 83 # array(3) 740 A1 # map(1) 741 06 # unsigned(6) 742 18 50 # unsigned(80) 743 A1 # map(1) 744 06 # unsigned(6) 745 19 01BB # unsigned(443) 746 A1 # map(1) 747 06 # unsigned(6) 748 19 1F90 # unsigned(8080) 749 08 # unsigned(8) 750 81 # array(1) 751 06 # unsigned(6) 753 Figure 7: PUT for DOTS signal (CBOR) 755 If the DOTS client is using the certificate provisioned by the 756 Enrollment over Secure Transport (EST) server [RFC7030] in the DOTS 757 gateway-domain to authenticate itself to the DOTS gateway, then the 758 'client-identifier' value can be the output of a cryptographic hash 759 algorithm whose input is the DER-encoded ASN.1 representation of the 760 Subject Public Key Info (SPKI) of an X.509 certificate. 762 In this version of the specification, the cryptographic hash 763 algorithm used is SHA-256 [RFC6234]. The output of the cryptographic 764 hash algorithm is truncated to 16 bytes; truncation is done by 765 stripping off the final 16 bytes. The truncated output is base64url 766 encoded. If the 'client-identifier' value is already present in the 767 mitigation request received from the DOTS client, the DOTS gateway 768 MAY compute the 'client-identifier' value, as discussed above, and 769 add the computed 'client-identifier' value to the end of the 'client- 770 identifier' list. The DOTS server MUST NOT use the 'client- 771 identifier' for the DOTS client authentication process. 773 In both DOTS signal and data channel sessions, the DOTS client MUST 774 authenticate itself to the DOTS server (Section 8). The DOTS server 775 may use the algorithm presented in Section 7 of [RFC7589] to derive 776 the DOTS client identity or username from the client certificate. 777 The DOTS client identity allows the DOTS server to accept mitigation 778 requests with scopes that the DOTS client is authorized to manage. 779 The DOTS server couples the DOTS signal and data channel sessions 780 using the DOTS client identity and the 'client-identifier' parameter 781 value, so the DOTS server can validate whether the aliases conveyed 782 in the mitigation request were indeed created by the same DOTS client 783 using the DOTS data channel session. If the aliases were not created 784 by the DOTS client, the DOTS server returns 4.00 (Bad Request) in the 785 response. 787 The DOTS server couples the DOTS signal channel sessions using the 788 DOTS client identity and the 'client-identifier' parameter value, and 789 the DOTS server uses 'mitigation-id' parameter value to detect 790 duplicate mitigation requests. If the mitigation request contains 791 the alias-name and other parameters identifying the target resources 792 (such as, 'target-prefix', 'target-port-range', 'target-fqdn', or 793 'target-uri'), then the DOTS server appends the parameter values in 794 'alias-name' with the corresponding parameter values in 'target- 795 prefix', 'target-port-range', 'target-fqdn', or 'target-uri'. 797 The DOTS server indicates the result of processing the PUT request 798 using CoAP response codes. CoAP 2.xx codes are success. CoAP 4.xx 799 codes are some sort of invalid requests (client errors). COAP 5.xx 800 codes are returned if the DOTS server has erred or is currently 801 unavailable to provide mitigation in response to the mitigation 802 request from the DOTS client. 804 Figure 8 shows an example of a PUT request that is successfully 805 processed (i.e., CoAP 2.xx response codes). 807 { 808 "mitigation-scope": { 809 "client-identifier": [ 810 "string" 811 ], 812 "scope": [ 813 { 814 "mitigation-id": 12332, 815 "lifetime": 3600 816 } 817 ] 818 } 819 } 821 Figure 8: 2.xx response body 823 If the request is missing one or more mandatory attributes, or 824 includes multiple 'scope' parameters, or contains invalid or unknown 825 parameters, the DOTS server replies with 4.00 (Bad Request). DOTS 826 agents can safely ignore Vendor-Specific parameters they don't 827 understand. 829 A DOTS server that receives a mitigation request with a lifetime set 830 to '0' MUST reply with a 4.00 (Bad Request). 832 If the DOTS server does not find the 'mitigation-id' parameter value 833 conveyed in the PUT request in its configuration data, it MAY accept 834 the mitigation request by sending back a 2.01 (Created) response to 835 the DOTS client; the DOTS server will consequently try to mitigate 836 the attack. 838 If the DOTS server finds the 'mitigation-id' parameter value conveyed 839 in the PUT request in its configuration data, it MAY update the 840 mitigation request, and a 2.04 (Changed) response is returned to 841 indicate a successful update of the mitigation request. 843 If the request is conflicting with an existing mitigation request 844 from a different DOTS client, and the DOTS server decides to maintain 845 the conflicting mitigation request, the DOTS server returns 4.09 846 (Conflict) [RFC8132] to the requesting DOTS client. The response 847 includes enough information for a DOTS client to recognize the source 848 of the conflict (refer to 'conflict-information' specified in 849 Section 4.4.2). 851 For a mitigation request to continue beyond the initial negotiated 852 lifetime, the DOTS client has to refresh the current mitigation 853 request by sending a new PUT request. This PUT request MUST use the 854 same 'mitigation-id' value, and MUST repeat all the other parameters 855 as sent in the original mitigation request apart from a possible 856 change to the lifetime parameter value. 858 A DOTS gateway MUST update the 'client-identifier' list in the 859 response to remove the 'client-identifier' value it had added in the 860 corresponding request before forwarding the response to the DOTS 861 client. 863 4.4.2. Retrieve Information Related to a Mitigation 865 A GET request is used by a DOTS client to retrieve information 866 (including status) of DOTS mitigations from a DOTS server. 868 The same considerations for manipulating 'client-identifier' 869 parameter by a DOTS gateway specified in Section 4.4.1 MUST be 870 followed for GET requests. 872 If the DOTS server does not find the 'mitigation-id' parameter value 873 conveyed in the GET request in its configuration data for the 874 requesting DOTS client or the one identified by 'client-identifier', 875 it MUST respond with a 4.04 (Not Found) error response code. 876 Likewise, the same error MUST be returned as a response to a request 877 to retrieve all mitigation records of a given DOTS client if the DOTS 878 server does not find any mitigation record for that DOTS client or 879 the one identified by 'client-identifier'. 881 The 'c' (content) parameter and its permitted values defined in 882 [I-D.ietf-core-comi] can be used to retrieve non-configuration data 883 (attack mitigation status) or configuration data or both. The DOTS 884 server may support this optional filtering capability. It can safely 885 ignore it if not supported. 887 The following examples illustrate how a DOTS client retrieves active 888 mitigation requests from a DOTS server. In particular: 890 o Figure 9 shows the example of a GET request to retrieve all DOTS 891 mitigation requests signaled by a DOTS client. 893 o Figure 10 shows the example of a GET request to retrieve a 894 specific DOTS mitigation request signaled by a DOTS client. The 895 configuration data to be reported in the response is formatted in 896 the same order it was processed by the DOTS server. 898 These two examples assume the default of "c=a"; that is, the DOTS 899 client asks for all data to be reported by the DOTS server. 901 Header: GET (Code=0.01) 902 Uri-Host: "host" 903 Uri-Path: ".well-known" 904 Uri-Path: "dots" 905 Uri-Path: "version" 906 Uri-Path: "mitigate" 907 Observe : 0 908 { 909 "mitigation-scope": { 910 "client-identifier": [ 911 "dz6pHjaADkaFTbjr0JGBpw" 912 ] 913 } 914 } 916 Figure 9: GET to retrieve all DOTS mitigation requests 918 Header: GET (Code=0.01) 919 Uri-Host: "host" 920 Uri-Path: ".well-known" 921 Uri-Path: "dots" 922 Uri-Path: "version" 923 Uri-Path: "mitigate" 924 Observe : 0 925 Content-Format: "application/cbor" 926 { 927 "mitigation-scope": { 928 "client-identifier": [ 929 "dz6pHjaADkaFTbjr0JGBpw" 930 ], 931 "scope": [ 932 { 933 "mitigation-id": 12332 934 } 935 ] 936 } 937 } 939 Figure 10: GET to retrieve a specific DOTS mitigation request 941 Figure 11 shows a response example of all active mitigation requests 942 associated with the DOTS client on the DOTS server and the mitigation 943 status of each mitigation request. 945 { 946 "mitigation-scope": { 947 "scope": [ 948 { 949 "mitigation-id": 12332, 950 "mitigation-start": 1507818434.00, 951 "target-protocol": [ 952 17 953 ], 954 "lifetime": 1800, 955 "status": 2, 956 "bytes-dropped": 134334555, 957 "bps-dropped": 43344, 958 "pkts-dropped": 333334444, 959 "pps-dropped": 432432 960 }, 961 { 962 "mitigation-id": 12333, 963 "mitigation-start": 1507818393.00, 964 "target-protocol": [ 965 6 966 ], 967 "lifetime": 1800, 968 "status": 3, 969 "bytes-dropped": 0, 970 "bps-dropped": 0, 971 "pkts-dropped": 0, 972 "pps-dropped": 0 973 } 974 ] 975 } 976 } 978 Figure 11: Response body 980 The mitigation status parameters are described below: 982 mitigation-start: Mitigation start time is expressed in seconds 983 relative to 1970-01-01T00:00Z in UTC time (Section 2.4.1 of 984 [RFC7049]). The encoding is modified so that the leading tag 1 985 (epoch-based date/time) MUST be omitted. 987 This is a mandatory attribute. 989 lifetime: The remaining lifetime of the mitigation request, in 990 seconds. 992 This is a mandatory attribute. 994 status: Status of attack mitigation. The various possible values of 995 'status' parameter are explained in Table 2. 997 This is a mandatory attribute. 999 conflict-information: Indicates that a mitigation request is 1000 conflicting with another mitigation request(s) from other DOTS 1001 client(s). This optional attribute has the following structure: 1003 conflict-status: Indicates the status of a conflicting mitigation 1004 request. The following values are defined: 1006 1: DOTS server has detected conflicting mitigation requests 1007 from different DOTS clients. This mitigation request is 1008 currently inactive until the conflicts are resolved. 1009 Another mitigation request is active. 1011 2: DOTS server has detected conflicting mitigation requests 1012 from different DOTS clients. This mitigation request is 1013 currently active. 1015 3: DOTS server has detected conflicting mitigation requests 1016 from different DOTS clients. All conflicting mitigation 1017 requests are inactive. 1019 conflict-cause: Indicates the cause of the conflict. The 1020 following values are defined: 1022 1: Overlapping targets. 'conflict-scope' provides more details 1023 about the conflicting target clauses. 1025 2: Conflicts with an existing white list. This code is 1026 returned when the DDoS mitigation detects source addresses/ 1027 prefixes in the white-listed ACLs are attacking the target. 1029 conflict-scope Indicates the conflict scope. It may include a 1030 list of IP addresses, a list of prefixes, a list of port 1031 numbers, a list of target protocols, a list of FQDNs, a list of 1032 URIs, a list of alias-names, or references to conflicting ACLs. 1034 retry-timer Indicates, in seconds, the time after which the DOTS 1035 client may re-issue the same request. The DOTS server returns 1036 'retry-timer' only to DOTS client(s) for which a mitigation 1037 request is deactivated. Any retransmission of the same 1038 mitigation request before the expiry of this timer is likely to 1039 be rejected by the DOTS server for the same reasons. 1041 The retry-timer SHOULD be equal to the lifetime of the active 1042 mitigation request resulting in the deactivation of the 1043 conflicting mitigation request. The lifetime of the 1044 deactivated mitigation request will be updated to (retry-timer 1045 + 45 seconds), so the DOTS client can refresh the deactivated 1046 mitigation request after retry-timer seconds before expiry of 1047 lifetime and check if the conflict is resolved. 1049 bytes-dropped: The total dropped byte count for the mitigation 1050 request since the attack mitigation is triggered. The count wraps 1051 around when it reaches the maximum value of unsigned integer. 1053 This is an optional attribute. 1055 bps-dropped: The average number of dropped bytes per second for the 1056 mitigation request since the attack mitigation is triggered. This 1057 SHOULD be a five-minute average. 1059 This is an optional attribute. 1061 pkts-dropped: The total number of dropped packet count for the 1062 mitigation request since the attack mitigation is triggered. 1064 This is an optional attribute. 1066 pps-dropped: The average number of dropped packets per second for 1067 the mitigation request since the attack mitigation is triggered. 1068 This SHOULD be a five-minute average. 1070 This is an optional attribute. 1072 +-----------+-------------------------------------------------------+ 1073 | Parameter | Description | 1074 | value | | 1075 +-----------+-------------------------------------------------------+ 1076 | 1 | Attack mitigation is in progress (e.g., changing the | 1077 | | network path to re-route the inbound traffic to DOTS | 1078 | | mitigator). | 1079 +-----------+-------------------------------------------------------+ 1080 | 2 | Attack is successfully mitigated (e.g., traffic is | 1081 | | redirected to a DDOS mitigator and attack traffic is | 1082 | | dropped). | 1083 +-----------+-------------------------------------------------------+ 1084 | 3 | Attack has stopped and the DOTS client can withdraw | 1085 | | the mitigation request. | 1086 +-----------+-------------------------------------------------------+ 1087 | 4 | Attack has exceeded the mitigation provider | 1088 | | capability. | 1089 +-----------+-------------------------------------------------------+ 1090 | 5 | DOTS client has withdrawn the mitigation request and | 1091 | | the mitigation is active but terminating. | 1092 +-----------+-------------------------------------------------------+ 1093 | 6 | Attack mitigation is now terminated. | 1094 +-----------+-------------------------------------------------------+ 1095 | 7 | Attack mitigation is withdrawn. | 1096 +-----------+-------------------------------------------------------+ 1097 | 8 | Attack mitigation is rejected. | 1098 +-----------+-------------------------------------------------------+ 1100 Table 2: Values of 'status' parameter 1102 The observe option defined in [RFC7641] extends the CoAP core 1103 protocol with a mechanism for a CoAP client to "observe" a resource 1104 on a CoAP server: The client retrieves a representation of the 1105 resource and requests this representation be updated by the server as 1106 long as the client is interested in the resource. A DOTS client 1107 conveys the observe option set to '0' in the GET request to receive 1108 unsolicited notifications of attack mitigation status from the DOTS 1109 server. 1111 Unidirectional notifications within the bidirectional signal channel 1112 allows unsolicited message delivery, enabling asynchronous 1113 notifications between the agents. Due to the higher likelihood of 1114 packet loss during a DDoS attack, DOTS server periodically sends 1115 attack mitigation status to the DOTS client and also notifies the 1116 DOTS client whenever the status of the attack mitigation changes. If 1117 the DOTS server cannot maintain a RTT estimate, it SHOULD NOT send 1118 more than one unsolicited notification every 3 seconds, and SHOULD 1119 use an even less aggressive rate whenever possible (case 2 in 1120 Section 3.1.3 of [RFC8085]). 1122 When conflicting requests are detected, the DOTS server enforces the 1123 corresponding policy (e.g., accept all requests, reject all requests, 1124 accept only one request but reject all the others, ...). It is 1125 assumed that this policy is supplied by the DOTS server administrator 1126 or it is a default behavior of the DOTS server implementation. Then, 1127 the DOTS server sends notification message(s) to the DOTS client(s) 1128 at the origin of the conflict. A conflict notification message 1129 includes information about the conflict cause, scope, and the status 1130 of the mitigation request(s). For example, 1132 o A notification message with status code set to '8 (Attack 1133 mitigation is rejected)' and 'conflict-status' set to '1' is sent 1134 to a DOTS client to indicate that this mitigation request is 1135 rejected because a conflict is detected. 1137 o A notification message with status code set to '7 (Attack 1138 mitigation is withdrawn)' and 'conflict-status' set to '1' is sent 1139 to a DOTS client to indicate that an active mitigation request is 1140 deactivated because a conflict is detected. 1142 o A notification message with status code set to '1 (Attack 1143 mitigation is in progress)' and 'conflict-status' set to '2' is 1144 sent to a DOTS client to indicate that this mitigation request is 1145 in progress, but a conflict is detected. 1147 Upon receipt of a conflict notification message indicating that a 1148 mitigation request is deactivated because of a conflict, a DOTS 1149 client MUST NOT resend the same mitigation request before the expiry 1150 of 'retry-timer'. It is also recommended that DOTS clients support 1151 means to alert administrators about mitigation conflicts. 1153 A DOTS client that is no longer interested in receiving notifications 1154 from the DOTS server can simply "forget" the observation. When the 1155 DOTS server sends the next notification, the DOTS client will not 1156 recognize the token in the message and thus will return a Reset 1157 message. This causes the DOTS server to remove the associated entry. 1158 Alternatively, the DOTS client can explicitly deregister itself by 1159 issuing a GET request that has the Token field set to the token of 1160 the observation to be cancelled and includes an Observe Option with 1161 the value set to '1' (deregister). 1163 Figure 12 shows an example of a DOTS client requesting a DOTS server 1164 to send notifications related to a given mitigation request. 1166 DOTS Client DOTS Server 1167 | | 1168 | GET / | 1169 | Token: 0x4a | Registration 1170 | Observe: 0 | 1171 +------------------------------>| 1172 | | 1173 | 2.05 Content | 1174 | Token: 0x4a | Notification of 1175 | Observe: 12 | the current state 1176 | status: "mitigation | 1177 | in progress" | 1178 |<------------------------------+ 1179 | 2.05 Content | 1180 | Token: 0x4a | Notification upon 1181 | Observe: 44 | a state change 1182 | status: "mitigation | 1183 | complete" | 1184 |<------------------------------+ 1185 | 2.05 Content | 1186 | Token: 0x4a | Notification upon 1187 | Observe: 60 | a state change 1188 | status: "attack stopped" | 1189 |<------------------------------+ 1190 | | 1192 Figure 12: Notifications of attack mitigation status 1194 4.4.2.1. Mitigation Status 1196 The DOTS client can send the GET request at frequent intervals 1197 without the Observe option to retrieve the configuration data of the 1198 mitigation request and non-configuration data (i.e., the attack 1199 status). The frequency of polling the DOTS server to get the 1200 mitigation status should follow the transmission guidelines given in 1201 Section 3.1.3 of [RFC8085]. If the DOTS server has been able to 1202 mitigate the attack and the attack has stopped, the DOTS server 1203 indicates as such in the status, and the DOTS client recalls the 1204 mitigation request by issuing a DELETE request for the mitigation-id. 1206 A DOTS client SHOULD react to the status of the attack as per the 1207 information sent by the DOTS server rather than acknowledging by 1208 itself, using its own means, that the attack has been mitigated. 1209 This ensures that the DOTS client does not recall a mitigation 1210 request prematurely because it is possible that the DOTS client does 1211 not sense the DDOS attack on its resources but the DOTS server could 1212 be actively mitigating the attack and the attack is not completely 1213 averted. 1215 4.4.3. Efficacy Update from DOTS Clients 1217 While DDoS mitigation is active, due to the likelihood of packet 1218 loss, a DOTS client MAY periodically transmit DOTS mitigation 1219 efficacy updates to the relevant DOTS server. A PUT request is used 1220 to convey the mitigation efficacy update to the DOTS server. 1222 The PUT request MUST include all the parameters used in the PUT 1223 request to carry the DOTS signal (Section 4.4.1) unchanged apart from 1224 the lifetime parameter value. If this is not the case, the DOTS 1225 server MUST reject the request with a 4.00 (Bad Request). 1227 The If-Match Option (Section 5.10.8.1 of [RFC7252]) with an empty 1228 value is used to make the PUT request conditional on the current 1229 existence of the mitigation request. If UDP is used as transport, 1230 CoAP requests may arrive out-of-order. For example, the DOTS client 1231 may send a PUT request to convey an efficacy update to the DOTS 1232 server followed by a DELETE request to withdraw the mitigation 1233 request, but the DELETE request arrives at the DOTS server before the 1234 PUT request. To handle out-of-order delivery of requests, if an If- 1235 Match option is present in the PUT request and the 'mitigation-id' in 1236 the request matches a mitigation request from that DOTS client, then 1237 the request is processed. If no match is found, the PUT request is 1238 silently ignored. 1240 An example of an efficacy update message, which includes an If-Match 1241 option with an empty value, is depicted in Figure 13. 1243 Header: PUT (Code=0.03) 1244 Uri-Host: "host" 1245 Uri-Path: ".well-known" 1246 Uri-Path: "dots" 1247 Uri-Path: "version" 1248 Uri-Path: "mitigate" 1249 Content-Format: "application/cbor" 1250 If-Match: 1251 { 1252 "mitigation-scope": { 1253 "client-identifier": [ 1254 "string" 1255 ], 1256 "scope": [ 1257 { 1258 "mitigation-id": integer, 1259 "target-prefix": [ 1260 "string" 1261 ], 1262 "target-port-range": [ 1263 { 1264 "lower-port": integer, 1265 "upper-port": integer 1266 } 1267 ], 1268 "target-protocol": [ 1269 integer 1270 ], 1271 "target-fqdn": [ 1272 "string" 1273 ], 1274 "target-uri": [ 1275 "string" 1276 ], 1277 "alias-name": [ 1278 "string" 1279 ], 1280 "lifetime": integer, 1281 "attack-status": integer 1282 } 1283 ] 1284 } 1285 } 1287 Figure 13: Efficacy Update 1289 The 'attack-status' parameter is a mandatory attribute when 1290 performing an efficacy update. The various possible values contained 1291 in the 'attack-status' parameter are described in Table 3. 1293 +-----------+-------------------------------------------------------+ 1294 | Parameter | Description | 1295 | value | | 1296 +-----------+-------------------------------------------------------+ 1297 | 1 | The DOTS client determines that it is still under | 1298 | | attack. | 1299 +-----------+-------------------------------------------------------+ 1300 | 2 | The DOTS client determines that the attack is | 1301 | | successfully mitigated (e.g., attack traffic is not | 1302 | | seen). | 1303 +-----------+-------------------------------------------------------+ 1305 Table 3: Values of 'attack-status' parameter 1307 The DOTS server indicates the result of processing a PUT request 1308 using CoAP response codes. The response code 2.04 (Changed) is 1309 returned if the DOTS server has accepted the mitigation efficacy 1310 update. The error response code 5.03 (Service Unavailable) is 1311 returned if the DOTS server has erred or is incapable of performing 1312 the mitigation. 1314 4.4.4. Withdraw a Mitigation 1316 A DELETE request is used to withdraw a DOTS mitigation request from a 1317 DOTS server (Figure 14). 1319 The same considerations for manipulating 'client-identifier' 1320 parameter by a DOTS gateway, as specified in Section 4.4.1, MUST be 1321 followed for DELETE requests. 1323 Header: DELETE (Code=0.04) 1324 Uri-Host: "host" 1325 Uri-Path: ".well-known" 1326 Uri-Path: "dots" 1327 Uri-Path: "version" 1328 Uri-Path: "mitigate" 1329 Content-Format: "application/cbor" 1330 { 1331 "mitigation-scope": { 1332 "client-identifier": [ 1333 "string" 1334 ], 1335 "scope": [ 1336 { 1337 "mitigation-id": integer 1338 } 1339 ] 1340 } 1341 } 1343 Figure 14: Withdraw DOTS signal 1345 If the request does not include a 'mitigation-id' parameter, the DOTS 1346 server MUST reply with a 4.00 (Bad Request). 1348 Once the request is validated, the DOTS server immediately 1349 acknowledges a DOTS client's request to withdraw the DOTS signal 1350 using 2.02 (Deleted) response code with no response payload. A 2.02 1351 (Deleted) Response Code is returned even if the 'mitigation-id' 1352 parameter value conveyed in the DELETE request does not exist in its 1353 configuration data before the request. 1355 If the DOTS server finds the 'mitigation-id' parameter value conveyed 1356 in the DELETE request in its configuration data for the DOTS client, 1357 then to protect against route or DNS flapping caused by a DOTS client 1358 rapidly removing a mitigation, and to dampen the effect of 1359 oscillating attacks, the DOTS server MAY allow mitigation to continue 1360 for a limited period after acknowledging a DOTS client's withdrawal 1361 of a mitigation request. During this period, the DOTS server status 1362 messages SHOULD indicate that mitigation is active but terminating 1363 (Section 4.4.2). 1365 The initial active-but-terminating period SHOULD be sufficiently long 1366 to absorb latency incurred by route propagation. The active-but- 1367 terminating period SHOULD be set by default to 120 seconds. If the 1368 client requests mitigation again before the initial active-but- 1369 terminating period elapses, the DOTS server MAY exponentially 1370 increase the active-but- terminating period up to a maximum of 300 1371 seconds (5 minutes). 1373 After the active-but-terminating period elapses, the DOTS server MUST 1374 treat the mitigation as terminated, as the DOTS client is no longer 1375 responsible for the mitigation. For example, if there is a financial 1376 relationship between the DOTS client and server domains, the DOTS 1377 client stops incurring cost at this point. 1379 4.5. DOTS Signal Channel Session Configuration 1381 The DOTS client can negotiate, configure, and retrieve the DOTS 1382 signal channel session behavior. The DOTS signal channel can be 1383 used, for example, to configure the following: 1385 a. Heartbeat interval (heartbeat-interval): DOTS agents regularly 1386 send heartbeats (CoAP Ping/Pong) to each other after mutual 1387 authentication is successfully completed in order to keep the 1388 DOTS signal channel open. Heartbeat messages are exchanged 1389 between the DOTS agents every 'heartbeat-interval' seconds to 1390 detect the current status of the DOTS signal channel session. 1392 b. Missing heartbeats allowed (missing-hb-allowed): This variable 1393 indicates the maximum number of consecutive heartbeat messages 1394 for which a DOTS agent did not receive a response before 1395 concluding that the session is disconnected or defunct. 1397 c. Acceptable signal loss ratio: Maximum retransmissions, 1398 retransmission timeout value, and other message transmission 1399 parameters for the DOTS signal channel. 1401 Requests and responses are deemed reliable by marking them as 1402 Confirmable (CON) messages. DOTS signal channel session 1403 configuration requests and responses are marked as Confirmable 1404 messages. As explained in Section 2.1 of [RFC7252], a Confirmable 1405 message is retransmitted using a default timeout and exponential 1406 back-off between retransmissions, until the DOTS server sends an 1407 Acknowledgement message (ACK) with the same Message ID conveyed from 1408 the DOTS client. 1410 Message transmission parameters are defined in Section 4.8 of 1411 [RFC7252]. The DOTS server can either piggyback the response in the 1412 acknowledgement message or, if the DOTS server cannot respond 1413 immediately to a request carried in a Confirmable message, it simply 1414 responds with an Empty Acknowledgement message so that the DOTS 1415 client can stop retransmitting the request. Empty Acknowledgement 1416 message is explained in Section 2.2 of [RFC7252]. When the response 1417 is ready, the server sends it in a new Confirmable message which in 1418 turn needs to be acknowledged by the DOTS client (see Sections 5.2.1 1419 and 5.2.2 of [RFC7252]). Requests and responses exchanged between 1420 DOTS agents during peacetime are marked as Confirmable messages. 1422 Implementation Note: A DOTS client that receives a response in a 1423 CON message may want to clean up the message state right after 1424 sending the ACK. If that ACK is lost and the DOTS server 1425 retransmits the CON, the DOTS client may no longer have any state 1426 that would help it correlate this response, thereby unexpecting 1427 the retransmission message. The DOTS client will send a Reset 1428 message so it does not receive any more retransmissions. This 1429 behavior is normal and not an indication of an error (see 1430 Section 5.3.2 of [RFC7252] for more details). 1432 4.5.1. Discover Configuration Parameters 1434 A GET request is used to obtain acceptable (e.g., minimum and maximum 1435 values) and current configuration parameters on the DOTS server for 1436 DOTS signal channel session configuration. Figure 15 shows how to 1437 obtain acceptable configuration parameters for the DOTS server. 1439 Header: GET (Code=0.01) 1440 Uri-Host: "host" 1441 Uri-Path: ".well-known" 1442 Uri-Path: "dots" 1443 Uri-Path: "version" 1444 Uri-Path: "config" 1446 Figure 15: GET to retrieve configuration 1448 The DOTS server in the 2.05 (Content) response conveys the current, 1449 minimum, and maximum attribute values acceptable by the DOTS server 1450 (Figure 16). 1452 Content-Format: "application/cbor" 1453 { 1454 "heartbeat-interval": { 1455 "current-value": integer, 1456 "min-value": integer, 1457 "max-value": integer 1458 }, 1459 "missing-hb-allowed": { 1460 "current-value": integer, 1461 "min-value": integer, 1462 "max-value": integer 1463 }, 1464 "max-retransmit": { 1465 "current-value": integer, 1466 "min-value": integer, 1467 "max-value": integer 1468 }, 1469 "ack-timeout": { 1470 "current-value": integer, 1471 "min-value": integer, 1472 "max-value": integer 1473 }, 1474 "ack-random-factor": { 1475 "current-value": number, 1476 "min-value": number, 1477 "max-value": number 1478 }, 1479 "trigger-mitigation": { 1480 "current-value": boolean 1481 }, 1482 "config-interval": { 1483 "current-value": integer, 1484 "min-value": integer, 1485 "max-value": integer 1486 } 1487 } 1489 Figure 16: GET response body 1491 Figure 17 shows an example of acceptable and current configuration 1492 parameters on a DOTS server for DOTS signal channel session 1493 configuration. 1495 Content-Format: "application/cbor" 1496 { 1497 "heartbeat-interval": { 1498 "current-value": 30, 1499 "min-value": 15, 1500 "max-value": 240 1501 }, 1502 "missing-hb-allowed": { 1503 "current-value": 5, 1504 "min-value": 3, 1505 "max-value": 9 1506 }, 1507 "max-retransmit": { 1508 "current-value": 3, 1509 "min-value": 2, 1510 "max-value": 15 1511 }, 1512 "ack-timeout": { 1513 "current-value": 2, 1514 "min-value": 1, 1515 "max-value": 30 1516 }, 1517 "ack-random-factor": { 1518 "current-value": 1.5, 1519 "min-value": 1.1, 1520 "max-value": 4.0 1521 }, 1522 "trigger-mitigation": { 1523 "current-value": true 1524 }, 1525 "config-interval": { 1526 "current-value": 1439, 1527 "min-value": 0, 1528 "max-value": 65535 1529 } 1530 } 1532 Figure 17: Configuration response body 1534 4.5.2. Convey DOTS Signal Channel Session Configuration 1536 A PUT request is used to convey the configuration parameters for the 1537 signal channel (e.g., heartbeat interval, maximum retransmissions). 1538 Message transmission parameters for CoAP are defined in Section 4.8 1539 of [RFC7252]. The RECOMMENDED values of transmission parameter 1540 values are ack-timeout (2 seconds), max-retransmit (3), ack-random- 1541 factor (1.5). In addition to those parameters, the RECOMMENDED 1542 specific DOTS transmission parameter values are heartbeat-interval 1543 (30 seconds) and missing-hb-allowed (5). 1545 Note: heartbeat-interval should be tweaked to also assist DOTS 1546 messages for NAT traversal (SIG-010 of 1547 [I-D.ietf-dots-requirements]). According to [RFC8085], keepalive 1548 messages must not be sent more frequently than once every 15 1549 seconds and should use longer intervals when possible. 1550 Furthermore, [RFC4787] recommends NATs to use a state timeout of 2 1551 minutes or longer, but experience shows that sending packets every 1552 15 to 30 seconds is necessary to prevent the majority of 1553 middleboxes from losing state for UDP flows. From that 1554 standpoint, this specification recommends a minimum heartbeat- 1555 interval of 15 seconds and a maximum heartbeat-interval of 240 1556 seconds. The recommended value of 30 seconds is selected to 1557 anticipate the expiry of NAT state. 1559 A heartbeat-interval of 30 seconds may be seen as too chatty in 1560 some deployments. For such deployments, DOTS agents may negotiate 1561 longer heartbeat-interval values to prevent any network overload 1562 with too frequent keepalives. 1564 When a confirmable "CoAP Ping" is sent, and if there is no response, 1565 the "CoAP Ping" is retransmitted max-retransmit number of times by 1566 the CoAP layer using an initial timeout set to a random duration 1567 between ack-timeout and (ack-timeout*ack-random-factor) and 1568 exponential back-off between retransmissions. By choosing the 1569 recommended transmission parameters, the "CoAP Ping" will timeout 1570 after 45 seconds. If the DOTS agent does not receive any response 1571 from the peer DOTS agent for 'missing-hb-allowed' number of 1572 consecutive "CoAP Ping" confirmable messages, it concludes that the 1573 DOTS signal channel session is disconnected. A DOTS client MUST NOT 1574 transmit a "CoAP Ping" while waiting for the previous "CoAP Ping" 1575 response from the same DOTS server. 1577 If the DOTS agent wishes to change the default values of message 1578 transmission parameters, then it should follow the guidance given in 1579 Section 4.8.1 of [RFC7252]. The DOTS agents MUST use the negotiated 1580 values for message transmission parameters and default values for 1581 non-negotiated message transmission parameters. 1583 The signal channel session configuration is applicable to a single 1584 DOTS signal channel session between the DOTS agents. 1586 Header: PUT (Code=0.03) 1587 Uri-Host: "host" 1588 Uri-Path: ".well-known" 1589 Uri-Path: "dots" 1590 Uri-Path: "version" 1591 Uri-Path: "config" 1592 Content-Format: "application/cbor" 1593 { 1594 "signal-config": { 1595 "session-id": integer, 1596 "heartbeat-interval": integer, 1597 "missing-hb-allowed": integer, 1598 "max-retransmit": integer, 1599 "ack-timeout": integer, 1600 "ack-random-factor": number, 1601 "trigger-mitigation": boolean, 1602 "config-interval": integer 1603 } 1604 } 1606 Figure 18: PUT to convey the DOTS signal channel session 1607 configuration data. 1609 The parameters in Figure 18 are described below: 1611 session-id: Identifier for the DOTS signal channel session 1612 configuration data represented as an integer. This identifier 1613 MUST be generated by the DOTS client. This document does not make 1614 any assumption about how this identifier is generated. 1616 This is a mandatory attribute. 1618 heartbeat-interval: Time interval in seconds between two 1619 consecutive heartbeat messages. 1621 '0' is used to disable the heartbeat mechanism. 1623 This is an optional attribute. 1625 missing-hb-allowed: Maximum number of consecutive heartbeat 1626 messages for which the DOTS agent did not receive a response 1627 before concluding that the session is disconnected. 1629 This is an optional attribute. 1631 max-retransmit: Maximum number of retransmissions for a message 1632 (referred to as MAX_RETRANSMIT parameter in CoAP). 1634 This is an optional attribute. 1636 ack-timeout: Timeout value in seconds used to calculate the initial 1637 retransmission timeout value (referred to as ACK_TIMEOUT parameter 1638 in CoAP). 1640 This is an optional attribute. 1642 ack-random-factor: Random factor used to influence the timing of 1643 retransmissions (referred to as ACK_RANDOM_FACTOR parameter in 1644 CoAP). 1646 This is an optional attribute. 1648 trigger-mitigation: If the parameter value is set to 'false', then 1649 DDoS mitigation is triggered only when the DOTS signal channel 1650 session is lost. Automated mitigation on loss of signal is 1651 discussed in Section 3.3.3 of [I-D.ietf-dots-architecture]. 1653 If the DOTS client ceases to respond to heartbeat messages, the 1654 DOTS server can detect that the DOTS session is lost. 1656 The default value of the parameter is 'true'. 1658 This is an optional attribute. 1660 config-interval: This parameter is returned to indicate the time 1661 interval expressed in minutes, which a DOTS agent must wait for 1662 before re-contacting its peer in order to retrieve the signal 1663 channel configuration data. 1665 '0' is used to disable this refresh mechanism. 1667 If a non-null value of 'config-interval' is received by a DOTS 1668 agent, it has to issue a PUT request to refresh the configuration 1669 parameters for the signal channel before the expiry of 'config- 1670 interval'. 1672 This mechanism allows to update the configuration data if a change 1673 occurs at the DOTS server side. For example, the new 1674 configuration may instruct a DOTS client to cease heartbeats or 1675 reduce heartbeat frequency. 1677 If this parameter is not returned, this is equivalent to receiving 1678 a 'config-interval' value set to '0'. 1680 If a DOTS server detects that a misbehaving DOTS client does not 1681 contact the DOTS server after the expiry of 'config-interval', in 1682 order to retrieve the signal channel configuration data, it MAY 1683 terminate the (D)TLS session. A (D)TLS session is terminated by 1684 the receipt of an authenticated message that closes the connection 1685 (e.g., a fatal alert (Section 7.2 of [RFC5246])). 1687 This is an optional attribute. 1689 At least one of the attributes 'heartbeat-interval', 'missing-hb- 1690 allowed', 'max-retransmit', 'ack-timeout', 'ack-random-factor', and 1691 'trigger-mitigation' MUST be present in the PUT request . The PUT 1692 request with a higher numeric 'session-id' value overrides the DOTS 1693 signal channel session configuration data installed by a PUT request 1694 with a lower numeric 'session-id' value. 1696 Figure 19 shows a PUT request example to convey the configuration 1697 parameters for the DOTS signal channel. 1699 Header: PUT (Code=0.03) 1700 Uri-Host: "www.example.com" 1701 Uri-Path: ".well-known" 1702 Uri-Path: "dots" 1703 Uri-Path: "v1" 1704 Uri-Path: "config" 1705 Content-Format: "application/cbor" 1706 { 1707 "signal-config": { 1708 "session-id": 1234534333242, 1709 "heartbeat-interval": 91, 1710 "missing-hb-allowed": 3, 1711 "max-retransmit": 7, 1712 "ack-timeout": 5, 1713 "ack-random-factor": 1.5, 1714 "trigger-mitigation": false 1715 } 1716 } 1718 Figure 19: PUT to convey the configuration parameters 1720 The DOTS server indicates the result of processing the PUT request 1721 using CoAP response codes: 1723 o If the DOTS server finds the 'session-id' parameter value conveyed 1724 in the PUT request in its configuration data and if the DOTS 1725 server has accepted the updated configuration parameters, then 1726 2.04 (Changed) code is returned in the response. 1728 o If the DOTS server does not find the 'session-id' parameter value 1729 conveyed in the PUT request in its configuration data and if the 1730 DOTS server has accepted the configuration parameters, then a 1731 response code 2.01 (Created) is returned in the response. 1733 o If the request is missing one or more mandatory attributes or it 1734 contains one or more invalid or unknown parameters, then 4.00 (Bad 1735 Request) is returned in the response. 1737 o Response code 4.22 (Unprocessable Entity) is returned in the 1738 response, if any of the 'heartbeat-interval', 'missing-hb- 1739 allowed', 'max-retransmit', 'target-protocol', 'ack-timeout', and 1740 'ack-random-factor' attribute values are not acceptable to the 1741 DOTS server. Upon receipt of the 4.22 error response code, the 1742 DOTS client should request the maximum and minimum attribute 1743 values acceptable to the DOTS server (Section 4.5.1). 1745 The DOTS client may re-try and send the PUT request with updated 1746 attribute values acceptable to the DOTS server. 1748 4.5.3. Delete DOTS Signal Channel Session Configuration 1750 A DELETE request is used to delete the installed DOTS signal channel 1751 session configuration data (Figure 20). 1753 Header: DELETE (Code=0.04) 1754 Uri-Host: "host" 1755 Uri-Path: ".well-known" 1756 Uri-Path: "dots" 1757 Uri-Path: "version" 1758 Uri-Path: "config" 1759 Content-Format: "application/cbor" 1761 Figure 20: DELETE configuration 1763 The DOTS server resets the DOTS signal channel session configuration 1764 back to the default values and acknowledges a DOTS client's request 1765 to remove the DOTS signal channel session configuration using 2.02 1766 (Deleted) response code. 1768 4.6. Redirected Signaling 1770 Redirected DOTS signaling is discussed in detail in Section 3.2.2 of 1771 [I-D.ietf-dots-architecture]. 1773 If a DOTS server wants to redirect a DOTS client to an alternative 1774 DOTS server for a signal session, then the response code 3.00 1775 (alternate server) will be returned in the response to the client. 1777 The DOTS server can return the error response code 3.00 in response 1778 to a PUT request from the DOTS client or convey the error response 1779 code 3.00 in a unidirectional notification response from the DOTS 1780 server. 1782 The DOTS server in the error response conveys the alternate DOTS 1783 server's FQDN, and the alternate DOTS server's IP address(es) and 1784 time to live values in the CBOR body (Figure 21). 1786 { 1787 "alt-server": "string", 1788 "alt-server-record": [ 1789 { 1790 "addr": "string", 1791 "ttl" : integer 1792 } 1793 ] 1794 } 1796 Figure 21: Error response body 1798 The parameters are described below: 1800 alt-server: FQDN of an alternate DOTS server. 1802 addr: IP address of an alternate DOTS server. 1804 ttl: Time to live (TTL) represented as an integer number of seconds. 1806 Figure 22 shows a 3.00 response example to convey the DOTS alternate 1807 server 'alt-server.example', its IP addresses 2001:db8:6401::1 and 1808 2001:db8:6401::2, and TTL values 3600 and 1800. 1810 { 1811 "alt-server": "alt-server.example", 1812 "alt-server-record": [ 1813 { 1814 "ttl" : 3600, 1815 "addr": "2001:db8:6401::1" 1816 }, 1817 { 1818 "ttl" : 1800, 1819 "addr": "2001:db8:6401::2" 1820 } 1821 ] 1822 } 1824 Figure 22: Example of error response body 1826 When the DOTS client receives 3.00 response, it considers the current 1827 request as failed, but SHOULD try re-sending the request to the 1828 alternate DOTS server. During a DDOS attack, the DNS server may be 1829 the target of another DDoS attack, alternate DOTS server's IP 1830 addresses conveyed in the 3.00 response help the DOTS client skip DNS 1831 lookup of the alternate DOTS server. The DOTS client can then try to 1832 establish a UDP or a TCP session with the alternate DOTS server. The 1833 DOTS client SHOULD implement a DNS64 function to handle the scenario 1834 where an IPv6-only DOTS client communicates with an IPv4-only 1835 alternate DOTS server. 1837 4.7. Heartbeat Mechanism 1839 To provide an indication of signal health and distinguish an 'idle' 1840 signal channel from a 'disconnected' or 'defunct' session, the DOTS 1841 agent sends a heartbeat over the signal channel to maintain its half 1842 of the channel. The DOTS agent similarly expects a heartbeat from 1843 its peer DOTS agent, and may consider a session terminated in the 1844 prolonged absence of a peer agent heartbeat. 1846 While the communication between the DOTS agents is quiescent, the 1847 DOTS client will probe the DOTS server to ensure it has maintained 1848 cryptographic state and vice versa. Such probes can also keep 1849 firewall and/or NAT bindings alive. This probing reduces the 1850 frequency of establishing a new handshake when a DOTS signal needs to 1851 be conveyed to the DOTS server. 1853 In case of a massive DDoS attack that saturates the incoming link(s) 1854 to the DOTS client, all traffic from the DOTS server to the DOTS 1855 client will likely be dropped, although the DOTS server receives 1856 heartbeat requests in addition to DOTS messages sent by the DOTS 1857 client. In this scenario, the DOTS agents MUST behave differently to 1858 handle message transmission and DOTS session liveliness during link 1859 saturation: 1861 o The DOTS client MUST NOT consider the DOTS session terminated even 1862 after a maximum 'missing-hb-allowed' threshold is reached. The 1863 DOTS client SHOULD keep on using the current DOTS session to send 1864 heartbeat requests over it, so that the DOTS server knows the DOTS 1865 client has not disconnected the DOTS session. 1867 After the maximum 'missing-hb-allowed' threshold is reached, the 1868 DOTS client SHOULD try to resume the (D)TLS session. The DOTS 1869 client SHOULD send mitigation requests over the current DOTS 1870 session, and in parallel, for example, try to resume the (D)TLS 1871 session or use 0-RTT mode in DTLS 1.3 to piggyback the mitigation 1872 request in the ClientHello message. 1874 As soon as the link is no longer saturated, if traffic from the 1875 DOTS server reaches the DOTS client over the current DOTS session, 1876 the DOTS client can stop (D)TLS session resumption or if (D)TLS 1877 session resumption is successful then disconnect the current DOTS 1878 session. 1880 o If the DOTS server does not receive any traffic from the peer DOTS 1881 client, then the DOTS server sends heartbeat requests to the DOTS 1882 client and after maximum 'missing-hb-allowed' threshold is 1883 reached, the DOTS server concludes the session is disconnected. 1885 In DOTS over UDP, heartbeat messages MUST be exchanged between the 1886 DOTS agents using the "CoAP Ping" mechanism defined in Section 4.2 of 1887 [RFC7252]. Concretely, the DOTS agent sends an Empty Confirmable 1888 message and the peer DOTS agent will respond by sending a Reset 1889 message. 1891 In DOTS over TCP, heartbeat messages MUST be exchanged between the 1892 DOTS agents using the Ping and Pong messages specified in Section 4.4 1893 of [I-D.ietf-core-coap-tcp-tls]. That is, the DOTS agent sends a 1894 Ping message and the peer DOTS agent would respond by sending a 1895 single Pong message. 1897 5. DOTS Signal Channel YANG Module 1899 This document defines a YANG [RFC7950] module for mitigation scope 1900 and DOTS signal channel session configuration data. 1902 5.1. Tree Structure 1904 This document defines the YANG module "ietf-dots-signal" 1905 (Section 5.2), which has the following tree structure. A DOTS signal 1906 message can either be a mitigation or a configuration message. 1908 module: ietf-dots-signal 1909 +--rw dots-signal 1910 +--rw (message-type)? 1911 +--:(mitigation-scope) 1912 | +--rw client-identifier* binary 1913 | +--rw scope* [mitigation-id] 1914 | +--rw mitigation-id int32 1915 | +--rw target-prefix* inet:ip-prefix 1916 | +--rw target-port-range* [lower-port upper-port] 1917 | | +--rw lower-port inet:port-number 1918 | | +--rw upper-port inet:port-number 1919 | +--rw target-protocol* uint8 1920 | +--rw target-fqdn* inet:domain-name 1921 | +--rw target-uri* inet:uri 1922 | +--rw alias-name* string 1923 | +--rw lifetime? int32 1924 | +--rw mitigation-start? int64 1925 | +--ro status? enumeration 1926 | +--ro conflict-information 1927 | | +--ro conflict-status? enumeration 1928 | | +--ro conflict-cause? enumeration 1929 | | +--ro retry-timer? int32 1930 | | +--ro conflict-scope 1931 | | +--ro target-prefix* inet:ip-prefix 1932 | | +--ro target-port-range* [lower-port upper-port] 1933 | | | +--ro lower-port inet:port-number 1934 | | | +--ro upper-port inet:port-number 1935 | | +--ro target-protocol* uint8 1936 | | +--ro target-fqdn* inet:domain-name 1937 | | +--ro target-uri* inet:uri 1938 | | +--ro alias-name* string 1939 | | +--ro acl-list* [acl-name acl-type] 1940 | | +--ro acl-name -> /ietf-acl:access-lists/acl/acl-name 1941 | | +--ro acl-type -> /ietf-acl:access-lists/acl/acl-type 1942 | +--ro pkts-dropped? yang:zero-based-counter64 1943 | +--ro bps-dropped? yang:zero-based-counter64 1944 | +--ro bytes-dropped? yang:zero-based-counter64 1945 | +--ro pps-dropped? yang:zero-based-counter64 1946 +--:(configuration) 1947 +--rw session-id int32 1948 +--rw heartbeat-interval? int16 1949 +--rw missing-hb-allowed? int16 1950 +--rw max-retransmit? int16 1951 +--rw ack-timeout? int16 1952 +--rw ack-random-factor? decimal64 1953 +--rw trigger-mitigation? boolean 1954 +--rw config-interval? int32 1956 5.2. YANG Module 1958 file "ietf-dots-signal@2017-12-12.yang" 1960 module ietf-dots-signal { 1961 yang-version 1.1; 1962 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-signal"; 1963 prefix "signal"; 1965 import ietf-inet-types {prefix "inet";} 1966 import ietf-yang-types {prefix yang;} 1967 import ietf-access-control-list {prefix "ietf-acl";} 1969 organization "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 1971 contact 1972 "Konda, Tirumaleswar Reddy 1973 Mohamed Boucadair 1974 Prashanth Patil 1975 Andrew Mortensen 1976 Nik Teague "; 1978 description 1979 "This module contains YANG definition for the signaling 1980 messages exchanged between a DOTS client and a DOTS server. 1982 Copyright (c) 2017 IETF Trust and the persons identified as 1983 authors of the code. All rights reserved. 1985 Redistribution and use in source and binary forms, with or 1986 without modification, is permitted pursuant to, and subject 1987 to the license terms contained in, the Simplified BSD License 1988 set forth in Section 4.c of the IETF Trust's Legal Provisions 1989 Relating to IETF Documents 1990 (http://trustee.ietf.org/license-info). 1992 This version of this YANG module is part of RFC XXXX; see 1993 the RFC itself for full legal notices."; 1995 revision 2017-12-12 { 1996 description 1997 "Initial revision."; 1998 reference 1999 "RFC XXXX: Distributed Denial-of-Service Open Threat 2000 Signaling (DOTS) Signal Channel"; 2001 } 2003 grouping target { 2004 description 2005 "Specifies the scope of the mitigation request."; 2007 leaf-list target-prefix { 2008 type inet:ip-prefix; 2009 description 2010 "IPv4 or IPv6 prefix identifying the target."; 2011 } 2013 list target-port-range { 2014 key "lower-port upper-port"; 2016 description 2017 "Port range. When only lower-port is 2018 present, it represents a single port."; 2020 leaf lower-port { 2021 type inet:port-number; 2022 mandatory true; 2023 description "Lower port number."; 2024 } 2026 leaf upper-port { 2027 type inet:port-number; 2028 must ". >= ../lower-port" { 2029 error-message 2030 "The upper port number must be greater than 2031 or equal to lower port number."; 2032 } 2033 description "Upper port number."; 2034 } 2035 } 2037 leaf-list target-protocol { 2038 type uint8; 2039 description 2040 "Identifies the target protocol number. 2042 The value '0' means 'all protocols'. 2044 Values are taken from the IANA protocol registry: 2045 https://www.iana.org/assignments/protocol-numbers/ 2046 protocol-numbers.xhtml 2048 For example, 6 for TCP or 17 for UDP."; 2049 } 2051 leaf-list target-fqdn { 2052 type inet:domain-name; 2053 description "FQDN identifying the target."; 2054 } 2056 leaf-list target-uri { 2057 type inet:uri; 2058 description "URI identifying the target."; 2059 } 2061 leaf-list alias-name { 2062 type string; 2063 description "alias name"; 2064 } 2065 } 2067 grouping mitigation-scope { 2068 description 2069 "Specifies the scope of the mitigation request."; 2071 leaf-list client-identifier { 2072 type binary; 2073 description 2074 "The client identifier may be conveyed by 2075 the DOTS gateway to propagate the DOTS client 2076 identification information from the gateway's client-side to the 2077 gateway's server-side, and from the gateway's 2078 server-side to the DOTS server. 2080 It allows the destination DOTS server to accept 2081 mitigation requests with scopes which the DOTS 2082 client is authorized to manage."; 2083 } 2085 list scope { 2086 key mitigation-id; 2087 description 2088 "The scope of the request."; 2090 leaf mitigation-id { 2091 type int32; 2092 description 2093 "Mitigation request identifier. 2095 This identifier must be unique for each mitigation 2096 request bound to the DOTS client."; 2097 } 2099 uses target; 2100 leaf lifetime { 2101 type int32; 2102 units "seconds"; 2103 default 3600; 2104 description 2105 "Indicates the lifetime of the mitigation request."; 2106 reference 2107 "RFC XXXX: Distributed Denial-of-Service Open Threat 2108 Signaling (DOTS) Signal Channel"; 2109 } 2111 leaf mitigation-start { 2112 type int64; 2113 units "seconds"; 2114 description 2115 "Mitigation start time is represented in seconds 2116 relative to 1970-01-01T00:00Z in UTC time."; 2117 } 2119 leaf status { 2120 type enumeration { 2121 enum "attack-mitigation-in-progress" { 2122 value 1; 2123 description 2124 "Attack mitigation is in progress (e.g., changing 2125 the network path to re-route the inbound traffic 2126 to DOTS mitigator)."; 2127 } 2129 enum "attack-successfully-mitigated" { 2130 value 2; 2131 description 2132 "Attack is successfully mitigated (e.g., traffic 2133 is redirected to a DDOS mitigator and attack 2134 traffic is dropped or blackholed)."; 2135 } 2137 enum "attack-stopped" { 2138 value 3; 2139 description 2140 "Attack has stopped and the DOTS client can 2141 withdraw the mitigation request."; 2142 } 2144 enum "attack-exceeded-capability" { 2145 value 4; 2146 description 2147 "Attack has exceeded the mitigation provider 2148 capability."; 2149 } 2151 enum "dots-client-withdrawn-mitigation" { 2152 value 5; 2153 description 2154 "DOTS client has withdrawn the mitigation 2155 request and the mitigation is active but 2156 terminating."; 2157 } 2159 enum "attack-mitigation-terminated" { 2160 value 6; 2161 description 2162 "Attack mitigation is now terminated."; 2163 } 2165 enum "attack-mitigation-withdrawn" { 2166 value 7; 2167 description 2168 "Attack mitigation is withdrawn."; 2169 } 2171 enum "attack-mitigation-rejected" { 2172 value 8; 2173 description 2174 "Attack mitigation is rejected."; 2175 } 2176 } 2177 config false; 2178 description 2179 "Indicates the status of a mitigation request. 2180 It must be included in responses only."; 2181 } 2183 container conflict-information { 2184 config false; 2185 description 2186 "Indicates that a conflict is detected. 2187 Must only be used for responses."; 2189 leaf conflict-status { 2190 type enumeration { 2191 enum "request-inactive-other-active" { 2192 value 1; 2193 description 2194 "DOTS Server has detected conflicting mitigation 2195 requests from different DOTS clients. 2197 This mitigation request is currently inactive 2198 until the conflicts are resolved. Another 2199 mitigation request is active."; 2200 } 2202 enum "request-active" { 2203 value 2; 2204 description 2205 "DOTS Server has detected conflicting mitigation 2206 requests from different DOTS clients. 2207 This mitigation request is currently active."; 2208 } 2210 enum "all-requests-inactive" { 2211 value 3; 2212 description 2213 "DOTS Server has detected conflicting mitigation 2214 requests from different DOTS clients. All 2215 conflicting mitigation requests are inactive."; 2216 } 2217 } 2218 description 2219 "Indicates the conflict status. 2220 It must be included in responses only."; 2221 } 2223 leaf conflict-cause { 2224 type enumeration { 2225 enum "overlapping-targets" { 2226 value 1; 2227 description 2228 "Overlapping targets. conflict-scope provides 2229 more details about the exact conflict."; 2230 } 2232 enum "conflict-with-whitelist" { 2233 value 2; 2234 description 2235 "Conflicts with an existing white list. 2237 This code is returned when the DDoS mitigation 2238 detects that some of the source addresses/prefixes 2239 listed in the white list ACLs are actually 2240 attacking the target."; 2241 } 2242 } 2243 description 2244 "Indicates the cause of the conflict. 2246 It must be included in responses only."; 2247 } 2249 leaf retry-timer { 2250 type int32; 2251 units "seconds"; 2252 description 2253 "The DOTS client must not re-send the 2254 same request before the expiry of this timer. 2255 It must be included in responses, only."; 2256 } 2258 container conflict-scope { 2259 description 2260 "Provides more information about the conflict scope."; 2262 uses target { 2263 when "../conflict-cause = 'overlapping-targets'"; 2264 } 2266 list acl-list { 2267 when "../../conflict-cause = 'conflict-with-whitelist'"; 2268 key "acl-name acl-type"; 2269 description 2270 "List of conflicting ACLs"; 2272 leaf acl-name { 2273 type leafref { 2274 path "/ietf-acl:access-lists/ietf-acl:acl" + 2275 "/ietf-acl:acl-name"; 2276 } 2277 description 2278 "Reference to the conflicting ACL name bound to 2279 a DOTS client."; 2280 } 2282 leaf acl-type { 2283 type leafref { 2284 path "/ietf-acl:access-lists/ietf-acl:acl" + 2285 "/ietf-acl:acl-type"; 2286 } 2287 description 2288 "Reference to the conflicting ACL type bound to 2289 a DOTS client."; 2290 } 2291 } 2292 } 2293 } 2294 leaf pkts-dropped { 2295 type yang:zero-based-counter64; 2296 config false; 2297 description 2298 "Number of dropped packets"; 2299 } 2301 leaf bps-dropped { 2302 type yang:zero-based-counter64; 2303 config false; 2304 description 2305 "The average number of dropped bytes per second for 2306 the mitigation request since the attack 2307 mitigation is triggered."; 2308 } 2310 leaf bytes-dropped { 2311 type yang:zero-based-counter64; 2312 units 'bytes'; 2313 config false; 2314 description 2315 "Counter for dropped packets; in bytes."; 2316 } 2318 leaf pps-dropped { 2319 type yang:zero-based-counter64; 2320 config false; 2321 description 2322 "The average number of dropped packets per second 2323 for the mitigation request since the attack 2324 mitigation is triggered."; 2325 } 2326 } 2327 } 2329 grouping signal-config { 2330 description 2331 "DOTS signal channel session configuration."; 2333 leaf session-id { 2334 type int32; 2335 mandatory true; 2336 description 2337 "An identifier for the DOTS signal channel 2338 session configuration data."; 2339 } 2341 leaf heartbeat-interval { 2342 type int16; 2343 units "seconds"; 2344 default 30; 2345 description 2346 "DOTS agents regularly send heartbeats to each other 2347 after mutual authentication is successfully 2348 completed, in order to keep the DOTS signal channel 2349 open. 2351 '0' means that heartbeat mechanism is deactivated."; 2352 reference 2353 "RFC XXXX: Distributed Denial-of-Service Open Threat 2354 Signaling (DOTS) Signal Channel"; 2355 } 2357 leaf missing-hb-allowed { 2358 type int16; 2359 default 5; 2360 description 2361 "Maximum number of missing heartbeats allowed."; 2362 reference 2363 "RFC XXXX: Distributed Denial-of-Service Open Threat 2364 Signaling (DOTS) Signal Channel"; 2365 } 2367 leaf max-retransmit { 2368 type int16; 2369 default 3; 2370 description 2371 "Maximum number of retransmissions of a 2372 Confirmable message."; 2373 reference 2374 "RFC XXXX: Distributed Denial-of-Service Open Threat 2375 Signaling (DOTS) Signal Channel"; 2376 } 2378 leaf ack-timeout { 2379 type int16; 2380 units "seconds"; 2381 default 2; 2382 description 2383 "Initial retransmission timeout value."; 2384 reference 2385 "Section 4.8 of RFC 7552."; 2386 } 2388 leaf ack-random-factor { 2389 type decimal64 { 2390 fraction-digits 2; 2391 } 2392 default 1.5; 2393 description 2394 "Random factor used to influence the timing of 2395 retransmissions."; 2396 reference 2397 "Section 4.8 of RFC 7552."; 2398 } 2400 leaf trigger-mitigation { 2401 type boolean; 2402 default true; 2403 description 2404 "If false, then mitigation is triggered 2405 only when the DOTS server channel session is lost"; 2406 reference 2407 "RFC XXXX: Distributed Denial-of-Service Open Threat 2408 Signaling (DOTS) Signal Channel"; 2409 } 2411 leaf config-interval { 2412 type int32; 2413 units "minutes"; 2414 description 2415 "This parameter is returned by a DOTS server to 2416 a requesting DOTS client to indicate the time interval 2417 after which the DOTS client must contact the DOTS 2418 server in order to retrieve the signal channel 2419 configuration data. 2421 This mechanism allows the update of the configuration 2422 data if a change occurs. 2424 For example, the new configuration may instruct 2425 a DOTS client to cease heartbeats or reduce 2426 heartbeat frequency. 2428 '0' is used to disable this refresh mechanism."; 2429 } 2430 } 2432 container dots-signal { 2433 description 2434 "Main container for DOTS signal message. 2435 A DOTS signal message can be a mitigation message or 2436 a configuration message."; 2438 choice message-type { 2439 description 2440 "Either a mitigation or a configuration message."; 2442 case mitigation-scope { 2443 description 2444 "Mitigation scope of a mitigation message."; 2445 uses mitigation-scope; 2446 } 2448 case configuration { 2449 description 2450 "Configuration message."; 2451 uses signal-config; 2452 } 2453 } 2454 } 2455 } 2456 2458 6. Mapping Parameters to CBOR 2460 All parameters in the payload of the DOTS signal channel MUST be 2461 mapped to CBOR types as shown in Table 4 and are assigned an integer 2462 key to save space. The recipient of the payload MAY reject the 2463 information if it is not suitably mapped. 2465 /----------------------+----------------+--------------------------\ 2466 | Parameter name | CBOR key | CBOR major type of value | 2467 +----------------------+----------------+--------------------------+ 2468 | mitigation-scope | 1 | 5 (map) | 2469 | scope | 2 | 5 (map) | 2470 | mitigation-id | 3 | 0 (unsigned) | 2471 | acl-list | 4 | 4 | 2472 | target-port-range | 5 | 4 | 2473 | lower-port | 6 | 0 | 2474 | upper-port | 7 | 0 | 2475 | target-protocol | 8 | 4 | 2476 | target-fqdn | 9 | 4 | 2477 | target-uri | 10 | 4 | 2478 | alias-name | 11 | 4 | 2479 | lifetime | 12 | 0 | 2480 | attack-status | 13 | 0 | 2481 | signal-config | 14 | 5 | 2482 | heartbeat-interval | 15 | 0 | 2483 | max-retransmit | 16 | 0 | 2484 | ack-timeout | 17 | 0 | 2485 | ack-random-factor | 18 | 7 | 2486 | min-value | 19 | 0 | 2487 | max-value | 20 | 0 | 2488 | status | 21 | 0 | 2489 | conflict-information | 22 | 5 (map) | 2490 | conflict-status | 23 | 0 | 2491 | conflict-cause | 24 | 0 | 2492 | retry-timer | 25 | 0 | 2493 | bytes-dropped | 26 | 0 | 2494 | bps-dropped | 27 | 0 | 2495 | pkts-dropped | 28 | 0 | 2496 | pps-dropped | 29 | 0 | 2497 | session-id | 30 | 0 | 2498 | trigger-mitigation | 31 | 7 (simple types) | 2499 | missing-hb-allowed | 32 | 0 | 2500 | current-value | 33 | 0 | 2501 | mitigation-start | 34 | 7 (floating-point) | 2502 | target-prefix | 35 | 4 (array) | 2503 | client-identifier | 36 | 2 (byte string) | 2504 | alt-server | 37 | 2 | 2505 | alt-server-record | 38 | 4 | 2506 | addr | 39 | 2 | 2507 | ttl | 40 | 0 | 2508 | conflict-scope | 41 | 5 (map) | 2509 | acl-name | 42 | 2 | 2510 | acl-type | 43 | 3 | 2511 | config-interval | 44 | 0 | 2512 \----------------------+----------------+--------------------------/ 2513 Table 4: CBOR mappings used in DOTS signal channel message 2515 7. (D)TLS Protocol Profile and Performance Considerations 2517 7.1. (D)TLS Protocol Profile 2519 This section defines the (D)TLS protocol profile of DOTS signal 2520 channel over (D)TLS and DOTS data channel over TLS. 2522 There are known attacks on (D)TLS, such as man-in-the-middle and 2523 protocol downgrade attacks. These are general attacks on (D)TLS and, 2524 as such, they are not specific to DOTS over (D)TLS; please refer to 2525 the (D)TLS RFCs for discussion of these security issues. DOTS agents 2526 MUST adhere to the (D)TLS implementation recommendations and security 2527 considerations of [RFC7525] except with respect to (D)TLS version. 2528 Since DOTS encryption that relies upon (D)TLS is virtually a green- 2529 field deployment, DOTS agents MUST implement only (D)TLS 1.2 or 2530 later. 2532 When a DOTS client is configured with a domain name of the DOTS 2533 server, and connects to its configured DOTS server, the server may 2534 present it with a PKIX certificate. In order to ensure proper 2535 authentication, a DOTS client MUST verify the entire certification 2536 path per [RFC5280]. The DOTS client additionally uses [RFC6125] 2537 validation techniques to compare the domain name with the certificate 2538 provided. 2540 A key challenge to deploying DOTS is the provisioning of DOTS 2541 clients, including the distribution of keying material to DOTS 2542 clients to enable the required mutual authentication of DOTS agents. 2543 EST defines a method of certificate enrollment by which domains 2544 operating DOTS servers may provide DOTS clients with all the 2545 necessary cryptographic keying material, including a private key and 2546 a certificate to authenticate themselves. One deployment option is 2547 DOTS clients behave as EST clients for certificate enrollment from an 2548 EST server provisioned by the mitigation provider. This document 2549 does not specify which EST mechanism the DOTS client uses to achieve 2550 initial enrollment. 2552 Implementations compliant with this profile MUST implement all of the 2553 following items: 2555 o DTLS record replay detection (Section 3.3 of [RFC6347]) to protect 2556 against replay attacks. 2558 o (D)TLS session resumption without server-side state [RFC5077] to 2559 resume session and convey the DOTS signal. 2561 o Raw public keys [RFC7250] or PSK handshake [RFC4279] which reduces 2562 the size of the ServerHello, and can be used by DOTS agents that 2563 cannot obtain certificates. 2565 Implementations compliant with this profile SHOULD implement all of 2566 the following items to reduce the delay required to deliver a DOTS 2567 signal: 2569 o TLS False Start [RFC7918] which reduces round-trips by allowing 2570 the TLS second flight of messages (ChangeCipherSpec) to also 2571 contain the DOTS signal. 2573 o Cached Information Extension [RFC7924] which avoids transmitting 2574 the server's certificate and certificate chain if the client has 2575 cached that information from a previous TLS handshake. 2577 o TCP Fast Open [RFC7413] can reduce the number of round-trips to 2578 convey DOTS signal. 2580 7.2. (D)TLS 1.3 Considerations 2582 TLS 1.3 [I-D.ietf-tls-tls13] provides critical latency improvements 2583 for connection establishment over TLS 1.2. The DTLS 1.3 protocol 2584 [I-D.ietf-tls-dtls13] is based upon the TLS 1.3 protocol and provides 2585 equivalent security guarantees. (D)TLS 1.3 provides two basic 2586 handshake modes the DOTS signal channel can take advantage of: 2588 o A full handshake mode in which a DOTS client can send a DOTS 2589 mitigation request message after one round trip. This assumes no 2590 packet loss is expereienced, 2592 o 0-RTT mode in which the DOTS client can authenticate itself and 2593 send DOTS mitigation request messages in the first message, thus 2594 reducing handshake latency. 0-RTT only works if the DOTS client 2595 has previously communicated with that DOTS server, which is very 2596 likely with the DOTS signal channel. 2598 The DOTS client has to establish a (D)TLS session with the DOTS 2599 server during peacetime and share a PSK. 2601 During a DDoS attack, the DOTS client can use the (D)TLS session 2602 to convey the DOTS mitigation request message and, if there is no 2603 response from the server after multiple retries, the DOTS client 2604 can resume the (D)TLS session in 0-RTT mode using PSK. 2606 Section 8 of [I-D.ietf-tls-tls13] discusses some mechanisms to 2607 implement to limit the impact of replay attacks on 0-RTT data. If 2608 TLS1.3 is used, DOTS servers must implement one of these 2609 mechanisms. 2611 A simplified TLS 1.3 handshake with 0-RTT DOTS mitigation request 2612 message exchange is shown in Figure 23. 2614 DOTS Client DOTS Server 2616 ClientHello 2617 (Finished) 2618 (0-RTT DOTS signal message) 2619 (end_of_early_data) --------> 2620 ServerHello 2621 {EncryptedExtensions} 2622 {ServerConfiguration} 2623 {Certificate} 2624 {CertificateVerify} 2625 {Finished} 2626 <-------- [DOTS signal message] 2627 {Finished} --------> 2629 [DOTS signal message] <-------> [DOTS signal message] 2631 Figure 23: TLS 1.3 handshake with 0-RTT 2633 7.3. MTU and Fragmentation 2635 To avoid DOTS signal message fragmentation and the subsequent 2636 decreased probability of message delivery, DOTS agents MUST ensure 2637 that the DTLS record MUST fit within a single datagram. If the path 2638 MTU is not known to the DOTS server, an IP MTU of 1280 bytes SHOULD 2639 be assumed. The length of the URL MUST NOT exceed 256 bytes. If UDP 2640 is used to convey the DOTS signal messages then the DOTS client must 2641 consider the amount of record expansion expected by the DTLS 2642 processing when calculating the size of CoAP message that fits within 2643 the path MTU. Path MTU MUST be greater than or equal to [CoAP 2644 message size + DTLS overhead of 13 octets + authentication overhead 2645 of the negotiated DTLS cipher suite + block padding (Section 4.1.1.1 2646 of [RFC6347]). If the request size exceeds the path MTU then the 2647 DOTS client MUST split the DOTS signal into separate messages, for 2648 example the list of addresses in the 'target-prefix' parameter could 2649 be split into multiple lists and each list conveyed in a new PUT 2650 request. 2652 Implementation Note: DOTS choice of message size parameters works 2653 well with IPv6 and with most of today's IPv4 paths. However, with 2654 IPv4, it is harder to reliably ensure that there is no IP 2655 fragmentation. If IPv4 path MTU is unknown, implementations may want 2656 to limit themselves to more conservative IPv4 datagram sizes such as 2657 576 bytes, as per [RFC0791]. IP packets whose size does not exceed 2658 576 bytes should never need to be fragmented: therefore, sending a 2659 maximum of 500 bytes of DOTS signal over a UDP datagram will 2660 generally avoid IP fragmentation. 2662 8. Mutual Authentication of DOTS Agents & Authorization of DOTS Clients 2664 (D)TLS based upon client certificate can be used for mutual 2665 authentication between DOTS agents. If a DOTS gateway is involved, 2666 DOTS clients and DOTS gateways MUST perform mutual authentication; 2667 only authorized DOTS clients are allowed to send DOTS signals to a 2668 DOTS gateway. The DOTS gateway and the DOTS server MUST perform 2669 mutual authentication; a DOTS server only allows DOTS signals from an 2670 authorized DOTS gateway, thereby creating a two-link chain of 2671 transitive authentication between the DOTS client and the DOTS 2672 server. 2674 +-----------------------------------------------+ 2675 | example.com domain +---------+ | 2676 | | AAA | | 2677 | +---------------+ | Server | | 2678 | | Application | +------+--+ | 2679 | | server +<-----------------+ ^ | 2680 | | (DOTS client) | | | | 2681 | +---------------+ | | | 2682 | V V | example.net domain 2683 | +-----+----+--+ | +---------------+ 2684 | +--------------+ | | | | | 2685 | | Guest +<-----x----->+ DOTS +<------>+ DOTS | 2686 | | (DOTS client)| | Gateway | | | Server | 2687 | +--------------+ | | | | | 2688 | +----+--------+ | +---------------+ 2689 | ^ | 2690 | | | 2691 | +----------------+ | | 2692 | | DDOS detector | | | 2693 | | (DOTS client) +<---------------+ | 2694 | +----------------+ | 2695 +-----------------------------------------------+ 2697 Figure 24: Example of Authentication and Authorization of DOTS Agents 2699 In the example depicted in Figure 24, the DOTS gateway and DOTS 2700 clients within the 'example.com' domain mutually authenticate with 2701 each other. After the DOTS gateway validates the identity of a DOTS 2702 client, it communicates with the AAA server in the 'example.com' 2703 domain to determine if the DOTS client is authorized to request DDoS 2704 mitigation. If the DOTS client is not authorized, a 4.01 2705 (Unauthorized) is returned in the response to the DOTS client. In 2706 this example, the DOTS gateway only allows the application server and 2707 DDoS attack detector to request DDOS mitigation, but does not permit 2708 the user of type 'guest' to request DDoS mitigation. 2710 Also, DOTS gateways and servers located in different domains MUST 2711 perform mutual authentication (e.g., using certificates). A DOTS 2712 server will only allow a DOTS gateway with a certificate for a 2713 particular domain to request mitigation for that domain. In 2714 reference to Figure 24, the DOTS server only allows the DOTS gateway 2715 to request mitigation for 'example.com' domain and not for other 2716 domains. 2718 9. IANA Considerations 2720 This specification registers a service port (Section 9.1), an URI 2721 suffix in the Well-Known URIs registry (Section 9.2), a CoAP response 2722 code (Section 9.3), a YANG module (Section 9.5). It also creates a 2723 registry for mappings to CBOR (Section 9.4). 2725 9.1. DOTS Signal Channel UDP and TCP Port Number 2727 IANA is requested to assign the port number TBD to the DOTS signal 2728 channel protocol for both UDP and TCP from the "Service Name and 2729 Transport Protocol Port Number Registry" available at 2730 https://www.iana.org/assignments/service-names-port-numbers/service- 2731 names-port-numbers.xhtml. 2733 The assignment of port number 4646 is strongly suggested, as 4646 is 2734 the ASCII decimal value for ".." (DOTS). 2736 9.2. Well-Known 'dots' URI 2738 This document requests IANA to register the 'dots' well-known URI in 2739 the Well-Known URIs registry (https://www.iana.org/assignments/well- 2740 known-uris/well-known-uris.xhtml) as defined by [RFC5785]. 2742 URI suffix: dots 2744 Change controller: IETF 2746 Specification document(s): This RFC 2748 Related information: None 2750 9.3. CoAP Response Code 2752 IANA is requested to add the following entry to the "CoAP Response 2753 Codes" sub-registry available at https://www.iana.org/assignments/ 2754 core-parameters/core-parameters.xhtml#response-codes: 2756 +------+------------------+-----------+ 2757 | Code | Description | Reference | 2758 +------+------------------+-----------+ 2759 | 3.00 | Alternate server | [RFCXXXX] | 2760 +------+------------------+-----------+ 2762 Table 4: CoAP Response Code 2764 9.4. DOTS Signal Channel CBOR Mappings Registry 2766 The document requests IANA to create a new registry, entitled "DOTS 2767 Signal Channel CBOR Mappings Registry". The structure of this 2768 registry is provided in Section 9.4.1. 2770 The registry is initially populated with the values in Section 9.4.2. 2772 Values from that registry MUST be assigned via Expert Review 2773 [RFC8126]. 2775 9.4.1. Registration Template 2777 Parameter name: 2778 Parameter name as used in the DOTS signal channel. 2780 CBOR Key Value: 2781 Key value for the parameter. The key value MUST be an integer in 2782 the 1-65536 range. The key values in the 32758-65536 range are 2783 assigned to Vendor-Specific parameters. 2785 CBOR Major Type: 2786 CBOR Major type and optional tag for the claim. 2788 Change Controller: 2789 For Standards Track RFCs, list the "IESG". For others, give the 2790 name of the responsible party. Other details (e.g., postal 2791 address, email address, home page URI) may also be included. 2793 Specification Document(s): 2794 Reference to the document or documents that specify the parameter, 2795 preferably including URIs that can be used to retrieve copies of 2796 the documents. An indication of the relevant sections may also be 2797 included but is not required. 2799 9.4.2. Initial Registry Contents 2801 o Parameter Name: mitigation-scope 2802 o CBOR Key Value: 1 2803 o CBOR Major Type: 5 2804 o Change Controller: IESG 2805 o Specification Document(s): this document 2807 o Parameter Name: scope 2808 o CBOR Key Value: 2 2809 o CBOR Major Type: 5 2810 o Change Controller: IESG 2811 o Specification Document(s): this document 2813 o Parameter Name: mitigation-id 2814 o CBOR Key Value: 3 2815 o CBOR Major Type: 0 2816 o Change Controller: IESG 2817 o Specification Document(s): this document 2819 o Parameter Name: acl-type 2820 o CBOR Key Value: 4 2821 o CBOR Major Type: 4 2822 o Change Controller: IESG 2823 o Specification Document(s): this document 2825 o Parameter Name: target-port-range 2826 o CBOR Key Value: 5 2827 o CBOR Major Type: 4 2828 o Change Controller: IESG 2829 o Specification Document(s): this document 2831 o Parameter Name: lower-port 2832 o CBOR Key Value: 6 2833 o CBOR Major Type: 0 2834 o Change Controller: IESG 2835 o Specification Document(s): this document 2837 o Parameter Name: upper-port 2838 o CBOR Key Value: 7 2839 o CBOR Major Type: 0 2840 o Change Controller: IESG 2841 o Specification Document(s): this document 2843 o Parameter Name: target-protocol 2844 o CBOR Key Value: 8 2845 o CBOR Major Type: 4 2846 o Change Controller: IESG 2847 o Specification Document(s): this document 2849 o Parameter Name: target-fqdn 2850 o CBOR Key Value: 9 2851 o CBOR Major Type: 4 2852 o Change Controller: IESG 2853 o Specification Document(s): this document 2855 o Parameter Name: target-uri 2856 o CBOR Key Value: 10 2857 o CBOR Major Type: 4 2858 o Change Controller: IESG 2859 o Specification Document(s): this document 2861 o Parameter Name: alias-name 2862 o CBOR Key Value: 11 2863 o CBOR Major Type: 4 2864 o Change Controller: IESG 2865 o Specification Document(s): this document 2867 o Parameter Name: lifetime 2868 o CBOR Key Value: 12 2869 o CBOR Major Type: 0 2870 o Change Controller: IESG 2871 o Specification Document(s): this document 2873 o Parameter Name: attack-status 2874 o CBOR Key Value: 13 2875 o CBOR Major Type: 0 2876 o Change Controller: IESG 2877 o Specification Document(s): this document 2879 o Parameter Name: signal-config 2880 o CBOR Key Value: 14 2881 o CBOR Major Type: 5 2882 o Change Controller: IESG 2883 o Specification Document(s): this document 2885 o Parameter Name: heartbeat-interval 2886 o CBOR Key Value: 15 2887 o CBOR Major Type: 0 2888 o Change Controller: IESG 2889 o Specification Document(s): this document 2891 o Parameter Name: max-retransmit 2892 o CBOR Key Value: 16 2893 o CBOR Major Type: 0 2894 o Change Controller: IESG 2895 o Specification Document(s): this document 2897 o Parameter Name: ack-timeout 2898 o CBOR Key Value: 17 2899 o CBOR Major Type: 0 2900 o Change Controller: IESG 2901 o Specification Document(s): this document 2903 o Parameter Name: ack-random-factor 2904 o CBOR Key Value: 18 2905 o CBOR Major Type: 7 2906 o Change Controller: IESG 2907 o Specification Document(s): this document 2909 o Parameter Name: min-value 2910 o CBOR Key Value: 19 2911 o CBOR Major Type: 0 2912 o Change Controller: IESG 2913 o Specification Document(s): this document 2915 o Parameter Name: max-value 2916 o CBOR Key Value: 20 2917 o CBOR Major Type: 0 2918 o Change Controller: IESG 2919 o Specification Document(s): this document 2921 o Parameter Name: status 2922 o CBOR Key Value: 21 2923 o CBOR Major Type: 0 2924 o Change Controller: IESG 2925 o Specification Document(s): this document 2927 o Parameter Name: conflict-information 2928 o CBOR Key Value: 22 2929 o CBOR Major Type: 5 2930 o Change Controller: IESG 2931 o Specification Document(s): this document 2933 o Parameter Name: conflict-status 2934 o CBOR Key Value: 23 2935 o CBOR Major Type: 0 2936 o Change Controller: IESG 2937 o Specification Document(s): this document 2939 o Parameter Name: conflict-cause 2940 o CBOR Key Value: 24 2941 o CBOR Major Type: 0 2942 o Change Controller: IESG 2943 o Specification Document(s): this document 2945 o Parameter Name: retry-timer 2946 o CBOR Key Value: 25 2947 o CBOR Major Type: 0 2948 o Change Controller: IESG 2949 o Specification Document(s): this document 2951 o Parameter Name: bytes-dropped 2952 o CBOR Key Value: 26 2953 o CBOR Major Type: 0 2954 o Change Controller: IESG 2955 o Specification Document(s): this document 2957 o Parameter Name: bps-dropped 2958 o CBOR Key Value: 27 2959 o CBOR Major Type: 0 2960 o Change Controller: IESG 2961 o Specification Document(s): this document 2963 o Parameter Name: pkts-dropped 2964 o CBOR Key Value: 28 2965 o CBOR Major Type: 0 2966 o Change Controller: IESG 2967 o Specification Document(s): this document 2969 o Parameter Name: pps-dropped 2970 o CBOR Key Value: 29 2971 o CBOR Major Type: 0 2972 o Change Controller: IESG 2973 o Specification Document(s): this document 2975 o Parameter Name: session-id 2976 o CBOR Key Value: 30 2977 o CBOR Major Type: 0 2978 o Change Controller: IESG 2979 o Specification Document(s): this document 2981 o Parameter Name: trigger-mitigation 2982 o CBOR Key Value: 31 2983 o CBOR Major Type: 7 2984 o Change Controller: IESG 2985 o Specification Document(s): this document 2987 o Parameter Name: missing-hb-allowed 2988 o CBOR Key Value: 32 2989 o CBOR Major Type: 0 2990 o Change Controller: IESG 2991 o Specification Document(s): this document 2993 o Parameter Name: current-value 2994 o CBOR Key Value: 33 2995 o CBOR Major Type: 0 2996 o Change Controller: IESG 2997 o Specification Document(s): this document 2999 o Parameter Name: mitigation-start 3000 o CBOR Key Value: 34 3001 o CBOR Major Type: 7 3002 o Change Controller: IESG 3003 o Specification Document(s): this document 3005 o Parameter Name: target-prefix 3006 o CBOR Key Value: 35 3007 o CBOR Major Type: 4 3008 o Change Controller: IESG 3009 o Specification Document(s): this document 3011 o Parameter Name: client-identifier 3012 o CBOR Key Value: 36 3013 o CBOR Major Type: 2 3014 o Change Controller: IESG 3015 o Specification Document(s): this document 3017 o Parameter Name: alt-server 3018 o CBOR Key Value: 37 3019 o CBOR Major Type: 2 3020 o Change Controller: IESG 3021 o Specification Document(s): this document 3023 o Parameter Name: alt-server-record 3024 o CBOR Key Value: 38 3025 o CBOR Major Type: 4 3026 o Change Controller: IESG 3027 o Specification Document(s): this document 3029 o Parameter Name: addr 3030 o CBOR Key Value: 39 3031 o CBOR Major Type: 2 3032 o Change Controller: IESG 3033 o Specification Document(s): this document 3035 o Parameter Name: ttl 3036 o CBOR Key Value: 40 3037 o CBOR Major Type: 0 3038 o Change Controller: IESG 3039 o Specification Document(s): this document 3041 o Parameter Name: conflict-scope 3042 o CBOR Key Value: 41 3043 o CBOR Major Type: 5 3044 o Change Controller: IESG 3045 o Specification Document(s): this document 3047 o Parameter Name: acl-name 3048 o CBOR Key Value: 42 3049 o CBOR Major Type: 2 3050 o Change Controller: IESG 3051 o Specification Document(s): this document 3053 o Parameter Name: acl-type 3054 o CBOR Key Value: 43 3055 o CBOR Major Type: 3 3056 o Change Controller: IESG 3057 o Specification Document(s): this document 3059 o Parameter Name: config-interval 3060 o CBOR Key Value: 44 3061 o CBOR Major Type: 0 3062 o Change Controller: IESG 3063 o Specification Document(s): this document 3065 9.5. DOTS Signal Channel YANG Module 3067 This document requests IANA to register the following URI in the 3068 "IETF XML Registry" [RFC3688]: 3070 URI: urn:ietf:params:xml:ns:yang:ietf-dots-signal 3071 Registrant Contact: The IESG. 3072 XML: N/A; the requested URI is an XML namespace. 3074 This document requests IANA to register the following YANG module in 3075 the "YANG Module Names" registry [RFC7950]. 3077 name: ietf-signal 3078 namespace: urn:ietf:params:xml:ns:yang:ietf-dots-signal 3079 prefix: signal 3080 reference: RFC XXXX 3082 10. Implementation Status 3084 [Note to RFC Editor: Please remove this section and reference to 3085 [RFC7942] prior to publication.] 3087 This section records the status of known implementations of the 3088 protocol defined by this specification at the time of posting this 3089 Internet-Draft, and is based upon a proposal described in [RFC7942]. 3090 The description of implementations in this section is intended to 3091 assist the IETF in its decision-making process when progressing 3092 drafts to RFCs. Please note that the listing of any individual 3093 implementation here does not imply endorsement by the IETF. 3094 Furthermore, no effort has been spent to verify the information 3095 presented here, and which was provided by individuals. This is not 3096 intended as, and must not be construed to be, a catalog of available 3097 implementations or features. Readers are advised to note that other 3098 implementations may exist. 3100 According to [RFC7942], "this will allow reviewers and working groups 3101 to assign due consideration to documents that have the benefit of 3102 running code, which may serve as evidence of valuable experimentation 3103 and feedback that have made the implemented protocols more mature. 3104 It is up to the individual working groups to use this information as 3105 they see fit". 3107 10.1. nttdots 3109 Organization: NTT Communication is developing a DOTS client and 3110 DOTS server software based on DOTS signal channel specified in 3111 this draft. It will be open-sourced. 3112 Description: Early implementation of DOTS protocol. It is aimed to 3113 implement a full DOTS protocol specification in accordance with 3114 the nurturing DOTS protocol. 3115 Implementation: https://github.com/nttdots/go-dots 3116 Level of maturity: It is an early implementation of the DOTS 3117 protocol. Messaging between DOTS clients and DOTS servers has 3118 been tested. Level of maturity will increase in accordance with 3119 the nurturing DOTS protocol. 3120 Coverage: Capability of DOTS client: sending DOTS messages to the 3121 DOTS server in CoAP over DTLS as dots-signal. Capability of DOTS 3122 server: receiving dots-signal, validating received dots-signal, 3123 starting mitigation by handing over the dots-signal to DDOS 3124 mitigator. 3125 Licensing: It will be open-sourced with BSD 3-clause license. 3126 Implementation experience: It is implemented in Go-lang. Core 3127 specification of signaling is mature to be implemented, however, 3128 finding good libraries(like DTLS, CoAP) is rather difficult. 3129 Contact: Kaname Nishizuka 3131 11. Security Considerations 3133 Authenticated encryption MUST be used for data confidentiality and 3134 message integrity. The interaction between the DOTS agents requires 3135 Datagram Transport Layer Security (DTLS) and Transport Layer Security 3136 (TLS) with a cipher suite offering confidentiality protection and the 3137 guidance given in [RFC7525] MUST be followed to avoid attacks on 3138 (D)TLS. The (D)TLS protocol profile for DOTS signal channel is 3139 specified in Section 7. 3141 A single DOTS signal channel between DOTS agents can be used to 3142 exchange multiple DOTS signal messages. To reduce DOTS client and 3143 DOTS server workload, DOTS clients SHOULD re-use the (D)TLS session. 3145 If TCP is used between DOTS agents, an attacker may be able to inject 3146 RST packets, bogus application segments, etc., regardless of whether 3147 TLS authentication is used. Because the application data is TLS 3148 protected, this will not result in the application receiving bogus 3149 data, but it will constitute a DoS on the connection. This attack 3150 can be countered by using TCP-AO [RFC5925]. If TCP-AO is used, then 3151 any bogus packets injected by an attacker will be rejected by the 3152 TCP-AO integrity check and therefore will never reach the TLS layer. 3154 In order to prevent leaking internal information outside a client- 3155 domain, DOTS gateways located in the client-domain SHOULD NOT reveal 3156 the identification information that pertains to internal DOTS clients 3157 (client-identifier) unless explicitly configured to do so. 3159 Special care should be taken in order to ensure that the activation 3160 of the proposed mechanism will not impact the stability of the 3161 network (including connectivity and services delivered over that 3162 network). 3164 Involved functional elements involved in the DDoS cooperation system 3165 must exchange instructions and notification over a secure and 3166 authenticated channel. Adequate filters can apply to avoid that 3167 nodes outside a trusted domain can inject illegitimate requests. 3168 Attacks can be initiated from within the trusted domain if an entity 3169 has been corrupted. Adequate means to monitor trusted nodes should 3170 also be enabled. 3172 12. Contributors 3174 The following individuals have contributed to this document: 3176 Mike Geller Cisco Systems, Inc. 3250 Florida 33309 USA Email: 3177 mgeller@cisco.com 3179 Robert Moskowitz HTT Consulting Oak Park, MI 42837 United States 3180 Email: rgm@htt-consult.com 3182 Dan Wing Email: dwing-ietf@fuggles.com 3184 13. Acknowledgements 3186 Thanks to Christian Jacquenet, Roland Dobbins, Roman D. Danyliw, 3187 Michael Richardson, Ehud Doron, Kaname Nishizuka, Dave Dolson, Liang 3188 Xia, Gilbert Clark, and Nesredien Suleiman for the discussion and 3189 comments. 3191 Special thanks to Jon Shallow for the careful reviews and inputs that 3192 enhanced this specification. 3194 14. References 3196 14.1. Normative References 3198 [I-D.ietf-core-coap-tcp-tls] 3199 Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 3200 Silverajan, B., and B. Raymor, "CoAP (Constrained 3201 Application Protocol) over TCP, TLS, and WebSockets", 3202 draft-ietf-core-coap-tcp-tls-10 (work in progress), 3203 October 2017. 3205 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3206 Requirement Levels", BCP 14, RFC 2119, 3207 DOI 10.17487/RFC2119, March 1997, 3208 . 3210 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3211 DOI 10.17487/RFC3688, January 2004, 3212 . 3214 [RFC4279] Eronen, P., Ed. and H. Tschofenig, Ed., "Pre-Shared Key 3215 Ciphersuites for Transport Layer Security (TLS)", 3216 RFC 4279, DOI 10.17487/RFC4279, December 2005, 3217 . 3219 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3220 (TLS) Protocol Version 1.2", RFC 5246, 3221 DOI 10.17487/RFC5246, August 2008, 3222 . 3224 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3225 Housley, R., and W. Polk, "Internet X.509 Public Key 3226 Infrastructure Certificate and Certificate Revocation List 3227 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 3228 . 3230 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 3231 Uniform Resource Identifiers (URIs)", RFC 5785, 3232 DOI 10.17487/RFC5785, April 2010, 3233 . 3235 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 3236 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 3237 June 2010, . 3239 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 3240 Verification of Domain-Based Application Service Identity 3241 within Internet Public Key Infrastructure Using X.509 3242 (PKIX) Certificates in the Context of Transport Layer 3243 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 3244 2011, . 3246 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 3247 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 3248 DOI 10.17487/RFC6234, May 2011, 3249 . 3251 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 3252 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 3253 January 2012, . 3255 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 3256 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 3257 Transport Layer Security (TLS) and Datagram Transport 3258 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 3259 June 2014, . 3261 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 3262 Application Protocol (CoAP)", RFC 7252, 3263 DOI 10.17487/RFC7252, June 2014, 3264 . 3266 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 3267 "Recommendations for Secure Use of Transport Layer 3268 Security (TLS) and Datagram Transport Layer Security 3269 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 3270 2015, . 3272 [RFC7641] Hartke, K., "Observing Resources in the Constrained 3273 Application Protocol (CoAP)", RFC 7641, 3274 DOI 10.17487/RFC7641, September 2015, 3275 . 3277 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 3278 RFC 7950, DOI 10.17487/RFC7950, August 2016, 3279 . 3281 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 3282 Writing an IANA Considerations Section in RFCs", BCP 26, 3283 RFC 8126, DOI 10.17487/RFC8126, June 2017, 3284 . 3286 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 3287 FETCH Methods for the Constrained Application Protocol 3288 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 3289 . 3291 14.2. Informative References 3293 [I-D.ietf-core-comi] 3294 Veillette, M., Stok, P., Pelov, A., and A. Bierman, "CoAP 3295 Management Interface", draft-ietf-core-comi-02 (work in 3296 progress), December 2017. 3298 [I-D.ietf-core-yang-cbor] 3299 Veillette, M., Pelov, A., Somaraju, A., Turner, R., and A. 3300 Minaburo, "CBOR Encoding of Data Modeled with YANG", 3301 draft-ietf-core-yang-cbor-05 (work in progress), August 3302 2017. 3304 [I-D.ietf-dots-architecture] 3305 Mortensen, A., Andreasen, F., Reddy, T., 3306 christopher_gray3@cable.comcast.com, c., Compton, R., and 3307 N. Teague, "Distributed-Denial-of-Service Open Threat 3308 Signaling (DOTS) Architecture", draft-ietf-dots- 3309 architecture-05 (work in progress), October 2017. 3311 [I-D.ietf-dots-data-channel] 3312 Reddy, T., Boucadair, M., Nishizuka, K., Xia, L., Patil, 3313 P., Mortensen, A., and N. Teague, "Distributed Denial-of- 3314 Service Open Threat Signaling (DOTS) Data Channel", draft- 3315 ietf-dots-data-channel-10 (work in progress), December 3316 2017. 3318 [I-D.ietf-dots-requirements] 3319 Mortensen, A., Moskowitz, R., and T. Reddy, "Distributed 3320 Denial of Service (DDoS) Open Threat Signaling 3321 Requirements", draft-ietf-dots-requirements-08 (work in 3322 progress), December 2017. 3324 [I-D.ietf-dots-use-cases] 3325 Dobbins, R., Migault, D., Fouant, S., Moskowitz, R., 3326 Teague, N., Xia, L., and K. Nishizuka, "Use cases for DDoS 3327 Open Threat Signaling", draft-ietf-dots-use-cases-09 (work 3328 in progress), November 2017. 3330 [I-D.ietf-netmod-yang-tree-diagrams] 3331 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", draft- 3332 ietf-netmod-yang-tree-diagrams-02 (work in progress), 3333 October 2017. 3335 [I-D.ietf-tls-dtls13] 3336 Rescorla, E., Tschofenig, H., and N. Modadugu, "The 3337 Datagram Transport Layer Security (DTLS) Protocol Version 3338 1.3", draft-ietf-tls-dtls13-22 (work in progress), 3339 November 2017. 3341 [I-D.ietf-tls-tls13] 3342 Rescorla, E., "The Transport Layer Security (TLS) Protocol 3343 Version 1.3", draft-ietf-tls-tls13-22 (work in progress), 3344 November 2017. 3346 [proto_numbers] 3347 "IANA, "Protocol Numbers"", 2011, 3348 . 3350 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 3351 DOI 10.17487/RFC0791, September 1981, 3352 . 3354 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3355 Resource Identifier (URI): Generic Syntax", STD 66, 3356 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3357 . 3359 [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram 3360 Congestion Control Protocol (DCCP)", RFC 4340, 3361 DOI 10.17487/RFC4340, March 2006, 3362 . 3364 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 3365 (CIDR): The Internet Address Assignment and Aggregation 3366 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 3367 2006, . 3369 [RFC4732] Handley, M., Ed., Rescorla, E., Ed., and IAB, "Internet 3370 Denial-of-Service Considerations", RFC 4732, 3371 DOI 10.17487/RFC4732, December 2006, 3372 . 3374 [RFC4787] Audet, F., Ed. and C. Jennings, "Network Address 3375 Translation (NAT) Behavioral Requirements for Unicast 3376 UDP", BCP 127, RFC 4787, DOI 10.17487/RFC4787, January 3377 2007, . 3379 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 3380 RFC 4960, DOI 10.17487/RFC4960, September 2007, 3381 . 3383 [RFC4987] Eddy, W., "TCP SYN Flooding Attacks and Common 3384 Mitigations", RFC 4987, DOI 10.17487/RFC4987, August 2007, 3385 . 3387 [RFC5077] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, 3388 "Transport Layer Security (TLS) Session Resumption without 3389 Server-Side State", RFC 5077, DOI 10.17487/RFC5077, 3390 January 2008, . 3392 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 3393 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 3394 DOI 10.17487/RFC5389, October 2008, 3395 . 3397 [RFC6555] Wing, D. and A. Yourtchenko, "Happy Eyeballs: Success with 3398 Dual-Stack Hosts", RFC 6555, DOI 10.17487/RFC6555, April 3399 2012, . 3401 [RFC6724] Thaler, D., Ed., Draves, R., Matsumoto, A., and T. Chown, 3402 "Default Address Selection for Internet Protocol Version 6 3403 (IPv6)", RFC 6724, DOI 10.17487/RFC6724, September 2012, 3404 . 3406 [RFC6887] Wing, D., Ed., Cheshire, S., Boucadair, M., Penno, R., and 3407 P. Selkirk, "Port Control Protocol (PCP)", RFC 6887, 3408 DOI 10.17487/RFC6887, April 2013, 3409 . 3411 [RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed., 3412 "Enrollment over Secure Transport", RFC 7030, 3413 DOI 10.17487/RFC7030, October 2013, 3414 . 3416 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 3417 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 3418 October 2013, . 3420 [RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 3421 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 3422 . 3424 [RFC7452] Tschofenig, H., Arkko, J., Thaler, D., and D. McPherson, 3425 "Architectural Considerations in Smart Object Networking", 3426 RFC 7452, DOI 10.17487/RFC7452, March 2015, 3427 . 3429 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 3430 NETCONF Protocol over Transport Layer Security (TLS) with 3431 Mutual X.509 Authentication", RFC 7589, 3432 DOI 10.17487/RFC7589, June 2015, 3433 . 3435 [RFC7918] Langley, A., Modadugu, N., and B. Moeller, "Transport 3436 Layer Security (TLS) False Start", RFC 7918, 3437 DOI 10.17487/RFC7918, August 2016, 3438 . 3440 [RFC7924] Santesson, S. and H. Tschofenig, "Transport Layer Security 3441 (TLS) Cached Information Extension", RFC 7924, 3442 DOI 10.17487/RFC7924, July 2016, 3443 . 3445 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 3446 Code: The Implementation Status Section", BCP 205, 3447 RFC 7942, DOI 10.17487/RFC7942, July 2016, 3448 . 3450 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 3451 RFC 7951, DOI 10.17487/RFC7951, August 2016, 3452 . 3454 [RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 3455 Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, 3456 March 2017, . 3458 Authors' Addresses 3460 Tirumaleswar Reddy 3461 McAfee, Inc. 3462 Embassy Golf Link Business Park 3463 Bangalore, Karnataka 560071 3464 India 3466 Email: kondtir@gmail.com 3467 Mohamed Boucadair 3468 Orange 3469 Rennes 35000 3470 France 3472 Email: mohamed.boucadair@orange.com 3474 Prashanth Patil 3475 Cisco Systems, Inc. 3477 Email: praspati@cisco.com 3479 Andrew Mortensen 3480 Arbor Networks, Inc. 3481 2727 S. State St 3482 Ann Arbor, MI 48104 3483 United States 3485 Email: amortensen@arbor.net 3487 Nik Teague 3488 Verisign, Inc. 3489 United States 3491 Email: nteague@verisign.com