idnits 2.17.1 draft-ietf-dots-signal-channel-04.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 83 instances of too long lines in the document, the longest one being 14 characters in excess of 72. == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 366 has weird spacing: '...er-port ine...' == Line 367 has weird spacing: '...er-port ine...' -- The document date (October 2, 2017) is 2390 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 1827, but not defined == Outdated reference: A later version (-11) exists of draft-ietf-core-coap-tcp-tls-09 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) == Outdated reference: A later version (-17) exists of draft-ietf-core-comi-01 == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-05 == Outdated reference: A later version (-18) exists of draft-ietf-dots-architecture-04 == Outdated reference: A later version (-31) exists of draft-ietf-dots-data-channel-03 == Outdated reference: A later version (-22) exists of draft-ietf-dots-requirements-06 == Outdated reference: A later version (-25) exists of draft-ietf-dots-use-cases-07 == Outdated reference: A later version (-28) exists of draft-ietf-tls-tls13-21 -- Obsolete informational reference (is this intentional?): RFC 5077 (Obsoleted by RFC 8446) -- 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: 4 errors (**), 0 flaws (~~), 13 warnings (==), 4 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: April 5, 2018 Orange 6 P. Patil 7 Cisco 8 A. Mortensen 9 Arbor Networks, Inc. 10 N. Teague 11 Verisign, Inc. 12 October 2, 2017 14 Distributed Denial-of-Service Open Threat Signaling (DOTS) Signal 15 Channel 16 draft-ietf-dots-signal-channel-04 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. A companion 24 document defines the DOTS data channel, a separate reliable 25 communication layer for DOTS management and configuration. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at https://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on April 5, 2018. 44 Copyright Notice 46 Copyright (c) 2017 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (https://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. Notational Conventions and Terminology . . . . . . . . . . . 3 63 3. Solution Overview . . . . . . . . . . . . . . . . . . . . . . 4 64 4. Happy Eyeballs for DOTS Signal Channel . . . . . . . . . . . 5 65 5. DOTS Signal Channel . . . . . . . . . . . . . . . . . . . . . 7 66 5.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 7 67 5.2. DOTS Signal YANG Module . . . . . . . . . . . . . . . . . 8 68 5.2.1. Mitigation Request YANG Module Tree Structure . . . . 8 69 5.2.2. Mitigation Request YANG Module . . . . . . . . . . . 8 70 5.2.3. Session Configuration YANG Module Tree Structure . . 10 71 5.2.4. Session Configuration YANG Module . . . . . . . . . . 11 72 5.3. Mitigation Request . . . . . . . . . . . . . . . . . . . 12 73 5.3.1. Requesting mitigation . . . . . . . . . . . . . . . . 13 74 5.3.2. Withdraw a DOTS Signal . . . . . . . . . . . . . . . 19 75 5.3.3. Retrieving a DOTS Signal . . . . . . . . . . . . . . 20 76 5.3.4. Efficacy Update from DOTS Client . . . . . . . . . . 25 77 5.4. DOTS Signal Channel Session Configuration . . . . . . . . 27 78 5.4.1. Discover Configuration Parameters . . . . . . . . . . 28 79 5.4.2. Convey DOTS Signal Channel Session Configuration . . 30 80 5.4.3. Delete DOTS Signal Channel Session Configuration . . 33 81 5.4.4. Retrieving DOTS Signal Channel Session Configuration 34 82 5.5. Redirected Signaling . . . . . . . . . . . . . . . . . . 34 83 5.6. Heartbeat Mechanism . . . . . . . . . . . . . . . . . . . 36 84 6. Mapping parameters to CBOR . . . . . . . . . . . . . . . . . 36 85 7. (D)TLS Protocol Profile and Performance considerations . . . 37 86 7.1. MTU and Fragmentation Issues . . . . . . . . . . . . . . 38 87 8. (D)TLS 1.3 considerations . . . . . . . . . . . . . . . . . . 39 88 9. Mutual Authentication of DOTS Agents & Authorization of DOTS 89 Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 90 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42 91 10.1. CoAP Response Code . . . . . . . . . . . . . . . . . . . 42 92 10.2. DOTS signal channel CBOR Mappings Registry . . . . . . . 42 93 10.2.1. Registration Template . . . . . . . . . . . . . . . 42 94 10.2.2. Initial Registry Contents . . . . . . . . . . . . . 43 95 11. Implementation Status . . . . . . . . . . . . . . . . . . . . 46 96 11.1. nttdots . . . . . . . . . . . . . . . . . . . . . . . . 47 98 12. Security Considerations . . . . . . . . . . . . . . . . . . . 47 99 13. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 48 100 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 48 101 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 49 102 15.1. Normative References . . . . . . . . . . . . . . . . . . 49 103 15.2. Informative References . . . . . . . . . . . . . . . . . 50 104 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 52 106 1. Introduction 108 A distributed denial-of-service (DDoS) attack is an attempt to make 109 machines or network resources unavailable to their intended users. 110 In most cases, sufficient scale can be achieved by compromising 111 enough end-hosts and using those infected hosts to perpetrate and 112 amplify the attack. The victim in this attack can be an application 113 server, a host, a router, a firewall, or an entire network. 115 In many cases, it may not be possible for an network administrators 116 to determine the causes of an attack, but instead just realize that 117 certain resources seem to be under attack. This document defines a 118 lightweight protocol permitting a DOTS client to request mitigation 119 from one or more DOTS servers for protection against detected, 120 suspected, or anticipated attacks . This protocol enables cooperation 121 between DOTS agents to permit a highly-automated network defense that 122 is robust, reliable and secure. 124 The requirements for DOTS signal channel protocol are obtained from 125 [I-D.ietf-dots-requirements]. 127 This document satisfies all the use cases discussed in 128 [I-D.ietf-dots-use-cases] except the Third-party DOTS notifications 129 use case in Section 3.2.3 of [I-D.ietf-dots-use-cases] which is an 130 optional feature and not a core use case. Third-party DOTS 131 notifications are not part of the DOTS requirements document. 132 Moreover, the DOTS architecture does not assess whether that use case 133 may have an impact on the architecture itself and/or the DOTS trust 134 model. 136 This is a companion document to the DOTS data channel specification 137 [I-D.ietf-dots-data-channel] that defines a configuration and bulk 138 data exchange mechanism supporting the DOTS signal channel. 140 2. Notational Conventions and Terminology 142 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 143 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 144 "OPTIONAL" in this document are to be interpreted as described in 145 [RFC2119]. 147 (D)TLS: For brevity this term is used for statements that apply to 148 both Transport Layer Security [RFC5246] and Datagram Transport Layer 149 Security [RFC6347]. Specific terms will be used for any statement 150 that applies to either protocol alone. 152 The reader should be familiar with the terms defined in 153 [I-D.ietf-dots-architecture]. 155 3. Solution Overview 157 Network applications have finite resources like CPU cycles, number of 158 processes or threads they can create and use, maximum number of 159 simultaneous connections it can handle, limited resources of the 160 control plane, etc. When processing network traffic, such 161 applications are supposed to use these resources to offer the 162 intended task in the most efficient fashion. However, an attacker 163 may be able to prevent an application from performing its intended 164 task by causing the application to exhaust the finite supply of a 165 specific resource. 167 TCP DDoS SYN-flood, for example, is a memory-exhaustion attack on the 168 victim and ACK-flood is a CPU exhaustion attack on the victim 169 ([RFC4987]). Attacks on the link are carried out by sending enough 170 traffic such that the link becomes excessively congested, and 171 legitimate traffic suffers high packet loss. Stateful firewalls can 172 also be attacked by sending traffic that causes the firewall to hold 173 excessive state. The firewall then runs out of memory, and can no 174 longer instantiate the state required to pass legitimate flows. 175 Other possible DDoS attacks are discussed in [RFC4732]. 177 In each of the cases described above, the possible arrangements 178 between the DOTS client and DOTS server to mitigate the attack are 179 discussed in [I-D.ietf-dots-use-cases]. An example of network 180 diagram showing a deployment of these elements is shown in Figure 1. 181 Architectural relationships between involved DOTS agents is explained 182 in [I-D.ietf-dots-architecture]. In this example, the DOTS server is 183 operating on the access network. 185 Network 186 Resource CPE router Access network __________ 187 +-----------+ +--------------+ +-------------+ / \ 188 | |____| |_______| |___ | Internet | 189 |DOTS client| | DOTS gateway | | DOTS server | | | 190 | | | | | | | | 191 +-----------+ +--------------+ +-------------+ \__________/ 193 Figure 1: Sample DOTS Deployment (1) 195 The DOTS server can also be running on the Internet, as depicted in 196 Figure 2. 198 Network DDoS mitigation 199 Resource CPE router __________ service 200 +-----------+ +-------------+ / \ +-------------+ 201 | |____| |_______| |___ | | 202 |DOTS client| |DOTS gateway | | Internet | | DOTS server | 203 | | | | | | | | 204 +-----------+ +-------------+ \__________/ +-------------+ 206 Figure 2: Sample DOTS Deployment (2) 208 In typical deployments, the DOTS client belongs to a different 209 administrative domain than the DOTS server. For example, the DOTS 210 client is a firewall protecting services owned and operated by an 211 domain, while the DOTS server is owned and operated by a different 212 domain providing DDoS mitigation services. That domain providing 213 DDoS mitigation service might, or might not, also provide Internet 214 access service to the website operator. 216 The DOTS server may (not) be co-located with the DOTS mitigator. In 217 typical deployments, the DOTS server belongs to the same 218 administrative domain as the mitigator. 220 The DOTS client can communicate directly with the DOTS server or 221 indirectly via a DOTS gateway. 223 This document focuses on the DOTS signal channel. 225 4. Happy Eyeballs for DOTS Signal Channel 227 DOTS signaling can happen with DTLS [RFC6347] over UDP and TLS 228 [RFC5246] over TCP. A DOTS client can use DNS to determine the IP 229 address(es) of a DOTS server or a DOTS client may be provided with 230 the list of DOTS server IP addresses. The DOTS client MUST know a 231 DOTS server's domain name; hard-coding the domain name of the DOTS 232 server into software is NOT RECOMMENDED in case the domain name is 233 not valid or needs to change for legal or other reasons. The DOTS 234 client performs A and/or AAAA record lookup of the domain name and 235 the result will be a list of IP addresses, each of which can be used 236 to contact the DOTS server using UDP and TCP. 238 If an IPv4 path to reach a DOTS server is found, but the DOTS 239 server's IPv6 path is not working, a dual-stack DOTS client can 240 experience a significant connection delay compared to an IPv4-only 241 DOTS client. The other problem is that if a middlebox between the 242 DOTS client and DOTS server is configured to block UDP, the DOTS 243 client will fail to establish a DTLS session with the DOTS server and 244 will, then, have to fall back to TLS over TCP incurring significant 245 connection delays. [I-D.ietf-dots-requirements] discusses that DOTS 246 client and server will have to support both connectionless and 247 connection-oriented protocols. 249 To overcome these connection setup problems, the DOTS client can try 250 connecting to the DOTS server using both IPv6 and IPv4, and try both 251 DTLS over UDP and TLS over TCP in a fashion similar to the Happy 252 Eyeballs mechanism [RFC6555]. These connection attempts are 253 performed by the DOTS client when its initializes, and the client 254 uses that information for its subsequent alert to the DOTS server. 255 In order of preference (most preferred first), it is UDP over IPv6, 256 UDP over IPv4, TCP over IPv6, and finally TCP over IPv4, which 257 adheres to address preference order [RFC6724] and the DOTS preference 258 that UDP be used over TCP (to avoid TCP's head of line blocking). 260 DOTS client DOTS server 261 | | 262 |--DTLS ClientHello, IPv6 ---->X | 263 |--TCP SYN, IPv6-------------->X | 264 |--DTLS ClientHello, IPv4 ---->X | 265 |--TCP SYN, IPv4----------------------------------------->| 266 |--DTLS ClientHello, IPv6 ---->X | 267 |--TCP SYN, IPv6-------------->X | 268 |<-TCP SYNACK---------------------------------------------| 269 |--DTLS ClientHello, IPv4 ---->X | 270 |--TCP ACK----------------------------------------------->| 271 |<------------Establish TLS Session---------------------->| 272 |----------------DOTS signal----------------------------->| 273 | | 275 Figure 3: Happy Eyeballs 277 In reference to Figure 3, the DOTS client sends two TCP SYNs and two 278 DTLS ClientHello messages at the same time over IPv6 and IPv4. In 279 this example, it is assumed that the IPv6 path is broken and UDP is 280 dropped by a middle box but has little impact to the DOTS client 281 because there is no long delay before using IPv4 and TCP. The DOTS 282 client repeats the mechanism to discover if DOTS signaling with DTLS 283 over UDP becomes available from the DOTS server, so the DOTS client 284 can migrate the DOTS signal channel from TCP to UDP, but such probing 285 SHOULD NOT be done more frequently than every 24 hours and MUST NOT 286 be done more frequently than every 5 minutes. 288 5. DOTS Signal Channel 290 5.1. Overview 292 The DOTS signal channel is built on top of the Constrained 293 Application Protocol (CoAP) [RFC7252], a lightweight protocol 294 originally designed for constrained devices and networks. CoAP's 295 expectation of packet loss, support for asynchronous non-confirmable 296 messaging, congestion control, small message overhead limiting the 297 need for fragmentation, use of minimal resources, and support for 298 (D)TLS make it a good foundation on which to build the DOTS signaling 299 mechanism. 301 The DOTS signal channel is layered on existing standards (Figure 4). 303 TBD: The default port number for DOTS signal channel is 5684 304 (Section 12.7 of [RFC7252] and Section 10.4 of 305 [I-D.ietf-core-coap-tcp-tls]), for both UDP and TCP. 307 +--------------+ 308 | DOTS | 309 +--------------+ 310 | CoAP | 311 +--------------+ 312 | TLS | DTLS | 313 +--------------+ 314 | TCP | UDP | 315 +--------------+ 316 | IP | 317 +--------------+ 319 Figure 4: Abstract Layering of DOTS signal channel over CoAP over 320 (D)TLS 322 The signal channel is initiated by the DOTS client. Once the signal 323 channel is established, the DOTS agents periodically send heartbeats 324 to keep the channel active. At any time, the DOTS client may send a 325 mitigation request message to the DOTS server over the active 326 channel. While mitigation is active, the DOTS server periodically 327 sends status messages to the client, including basic mitigation 328 feedback details. Mitigation remains active until the DOTS client 329 explicitly terminates mitigation, or the mitigation lifetime expires. 331 Messages exchanged between DOTS client and server are serialized 332 using Concise Binary Object Representation (CBOR) [RFC7049], CBOR is 333 a binary encoding designed for small code and message size. CBOR 334 encoded payloads are used to convey signal channel specific payload 335 messages that convey request parameters and response information such 336 as errors. This specification uses the encoding rules defined in 337 [I-D.ietf-core-yang-cbor] for representing mitigation scope and DOTS 338 signal channel session configuration data defined using YANG 339 (Section 5.2) as CBOR data. 341 DOTS agents MUST support GET, PUT, and DELETE CoAP methods. The 342 payload included in CoAP responses with 2.xx and 3.xx Response Codes 343 MUST be of content type "application/cbor" (Section 5.5.1 of 344 [RFC7252]). CoAP responses with 4.xx and 5.xx error Response Codes 345 MUST include a diagnostic payload (Section 5.5.2 of [RFC7252]). The 346 Diagnostic Payload may contain additional information to aid 347 troubleshooting. 349 5.2. DOTS Signal YANG Module 351 This document defines a YANG [RFC6020] module for mitigation scope 352 and DOTS signal channel session configuration data. 354 5.2.1. Mitigation Request YANG Module Tree Structure 356 This document defines the YANG module "ietf-dots-signal", which has 357 the following tree structure: 359 module: ietf-dots-signal 360 +--rw mitigation-scope 361 +--rw scope* [mitigation-id] 362 +--rw mitigation-id int32 363 +--rw target-ip* inet:ip-address 364 +--rw target-prefix* inet:ip-prefix 365 +--rw target-port-range* [lower-port upper-port] 366 | +--rw lower-port inet:port-number 367 | +--rw upper-port inet:port-number 368 +--rw target-protocol* uint8 369 +--rw fqdn* inet:domain-name 370 +--rw uri* inet:uri 371 +--rw alias-name* string 372 +--rw lifetime? int32 374 5.2.2. Mitigation Request YANG Module 376 file "ietf-dots-signal@2017-08-03.yang" 378 module ietf-dots-signal { 379 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-signal"; 380 prefix "signal"; 381 import ietf-inet-types { 382 prefix "inet"; 383 } 385 organization "McAfee, Inc."; 386 contact "Konda, Tirumaleswar Reddy "; 388 description 389 "This module contains YANG definition for DOTS 390 signal sent by the DOTS client to the DOTS server."; 392 revision 2017-08-03 { 393 reference 394 "https://tools.ietf.org/html/draft-reddy-dots-signal-channel"; 395 } 397 container mitigation-scope { 398 description 399 "Top level container for a mitigation request."; 401 list scope { 402 key mitigation-id; 403 description "Identifier for the mitigation request."; 404 leaf mitigation-id { 405 type int32; 406 description "Mitigation request identifier."; 407 } 408 leaf-list target-ip { 409 type inet:ip-address; 410 description 411 "IPv4 or IPv6 address identifyting the target."; 412 } 414 leaf-list target-prefix { 415 type inet:ip-prefix; 416 description 417 "IPv4 or IPv6 prefix identifyting the target."; 418 } 420 list target-port-range { 421 key "lower-port upper-port"; 422 description "Port range. When only lower-port is present, 423 it represents a single port."; 425 leaf lower-port { 426 type inet:port-number; 427 mandatory true; 428 description "Lower port number."; 429 } 431 leaf upper-port { 432 type inet:port-number; 433 must ". >= ../lower-port" { 434 error-message 435 "The upper port number must be greater than or 436 equal to lower port number."; 437 } 438 description "Upper port number."; 439 } 440 } 442 leaf-list target-protocol { 443 type uint8; 444 description "Identifies the target protocol number."; 445 } 447 leaf-list fqdn { 448 type inet:domain-name; 449 description "FQDN"; 450 } 452 leaf-list uri { 453 type inet:uri; 454 description "URI"; 455 } 457 leaf-list alias-name { 458 type string; 459 description "alias name"; 460 } 462 leaf lifetime { 463 type int32; 464 description 465 "Indicates the lifetime of the mitigation request."; 466 } 467 } 468 } 469 } 470 472 5.2.3. Session Configuration YANG Module Tree Structure 474 This document defines the YANG module "ietf-dots-signal-config", 475 which has the following structure: 477 module: ietf-dots-signal-config 478 +--rw signal-config 479 +--rw session-id? int32 480 +--rw heartbeat-interval? int16 481 +--rw missing-hb-allowed? int16 482 +--rw max-retransmit? int16 483 +--rw ack-timeout? int16 484 +--rw ack-random-factor? decimal64 485 +--rw trigger-mitigation? boolean 487 5.2.4. Session Configuration YANG Module 489 file "ietf-dots-signal-config@2016-11-28.yang" 491 module ietf-dots-signal-config { 492 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-signal-config"; 493 prefix "config"; 495 organization "McAfee, Inc."; 496 contact "Konda, Tirumaleswar Reddy "; 498 description 499 "This module contains YANG definition for DOTS 500 signal channel session configuration."; 502 revision 2016-11-28 { 503 reference 504 "https://tools.ietf.org/html/draft-reddy-dots-signal-channel"; 505 } 507 container signal-config { 508 description "Top level container for DOTS signal channel session 509 configuration."; 511 leaf session-id { 512 type int32; 513 description "An identifier for the DOTS signal channel 514 session configuration data."; 515 } 517 leaf heartbeat-interval { 518 type int16; 519 description 520 "DOTS agents regularly send heartbeats to each other 521 after mutual authentication in order to keep 522 the DOTS signal channel open."; 523 } 524 leaf missing-hb-allowed { 525 type int16; 526 description 527 "Maximum number of missing heartbeats allowed"; 528 } 530 leaf max-retransmit { 531 type int16; 532 description 533 "Maximum number of retransmissions of a 534 Confirmable message."; 535 } 537 leaf ack-timeout { 538 type int16; 539 description 540 "Initial retransmission timeout value."; 541 } 543 leaf ack-random-factor { 544 type decimal64 { 545 fraction-digits 2; 546 } 547 description 548 "Random factor used to influence the timing of 549 retransmissions"; 550 } 551 leaf trigger-mitigation { 552 type boolean; 553 default true; 554 description 555 "If false, then mitigation is triggered 556 only when the DOTS server channel session is lost"; 557 } 558 } 559 } 561 563 5.3. Mitigation Request 565 The following methods are used to request or withdraw mitigation 566 requests: 568 PUT: DOTS clients use the PUT method to request mitigation 569 (Section 5.3.1). During active mitigation, DOTS clients may use 570 PUT requests to convey mitigation efficacy updates to the DOTS 571 server (Section 5.3.4). 573 DELETE: DOTS clients use the DELETE method to withdraw a request for 574 mitigation from the DOTS server (Section 5.3.2). 576 GET: DOTS clients may use the GET method to subscribe to DOTS server 577 status messages, or to retrieve the list of existing mitigations 578 (Section 5.3.3). 580 Mitigation request and response messages are marked as Non- 581 confirmable messages. DOTS agents should follow the data 582 transmission guidelines discussed in Section 3.1.3 of [RFC8085] and 583 control transmission behavior by not sending on average more than one 584 UDP datagram per RTT to the peer DOTS agent. Requests marked by the 585 DOTS client as Non-confirmable messages are sent at regular intervals 586 until a response is received from the DOTS server and if the DOTS 587 client cannot maintain a RTT estimate then it SHOULD NOT send more 588 than one Non-confirmable request every 3 seconds, and SHOULD use an 589 even less aggressive rate when possible (case 2 in Section 3.1.3 of 590 [RFC8085]). 592 5.3.1. Requesting mitigation 594 When a DOTS client requires mitigation for any reason, the DOTS 595 client uses CoAP PUT method to send a mitigation request to the DOTS 596 server (Figure 5, illustrated in JSON diagnostic notation). The DOTS 597 server can enable mitigation on behalf of the DOTS client by 598 communicating the DOTS client's request to the mitigator and relaying 599 selected mitigator feedback to the requesting DOTS client. 601 Header: PUT (Code=0.03) 602 Uri-Host: "host" 603 Uri-Path: "version" 604 Uri-Path: "dots-signal" 605 Uri-Path: "signal" 606 Content-Type: "application/cbor" 607 { 608 "mitigation-scope": { 609 "scope": [ 610 { 611 "mitigation-id": integer, 612 "target-ip": [ 613 "string" 614 ], 615 "target-prefix": [ 616 "string" 617 ], 618 "target-port-range": [ 619 { 620 "lower-port": integer, 621 "upper-port": integer 622 } 623 ], 624 "target-protocol": [ 625 integer 626 ], 627 "fqdn": [ 628 "string" 629 ], 630 "uri": [ 631 "string" 632 ], 633 "alias-name": [ 634 "string" 635 ], 636 "lifetime": integer 637 } 638 ] 639 } 640 } 642 Figure 5: PUT to convey DOTS signals 644 The parameters are described below. 646 mitigation-id: Identifier for the mitigation request represented 647 using an integer. This identifier MUST be unique for each 648 mitigation request bound to the DOTS client, i.e., the mitigation- 649 id parameter value in the mitigation request needs to be unique 650 relative to the mitigation-id parameter values of active 651 mitigation requests conveyed from the DOTS client to the DOTS 652 server. This identifier MUST be generated by the DOTS client. 653 This document does not make any assumption about how this 654 identifier is generated. This is a mandatory attribute. 656 target-ip: A list of IP addresses under attack. This is an optional 657 attribute. 659 target-prefix: A list of prefixes under attack. Prefixes are 660 represented using CIDR notation [RFC4632]. This is an optional 661 attribute. 663 target-port-range: A list of ports under attack. The port range, 664 lower-port for lower port number and upper-port for upper port 665 number. When only lower-port is present, it represents a single 666 port. For TCP, UDP, SCTP, or DCCP: the range of ports (e.g., 667 1024-65535). This is an optional attribute. 669 target-protocol: A list of protocols under attack. Values are taken 670 from the IANA protocol registry [proto_numbers]. The value 0 has 671 a special meaning for 'all protocols'. This is an optional 672 attribute. 674 fqdn: A list of Fully Qualified Domain Names. Fully Qualified 675 Domain Name (FQDN) is the full name of a system, rather than just 676 its hostname. For example, "venera" is a hostname, and 677 "venera.isi.edu" is an FQDN. This is an optional attribute. 679 uri: A list of Uniform Resource Identifiers (URI). This is an 680 optional attribute. 682 alias-name: A list of aliases. Aliases can be created using the 683 DOTS data channel (Section 3.1.1 of [I-D.ietf-dots-data-channel]) 684 or direct configuration, or other means and then used in 685 subsequent signal channel exchanges to refer more efficiently to 686 the resources under attack. This is an optional attribute. 688 lifetime: Lifetime of the mitigation request in seconds. Upon the 689 expiry of this lifetime, and if the request is not refreshed, the 690 mitigation request is removed. The request can be refreshed by 691 sending the same request again. The default lifetime of the 692 mitigation request is 3600 seconds (60 minutes) -- this value was 693 chosen to be long enough so that refreshing is not typically a 694 burden on the DOTS client, while expiring the request where the 695 client has unexpectedly quit in a timely manner. A lifetime of 696 negative one (-1) indicates indefinite lifetime for the mitigation 697 request. The server MUST always indicate the actual lifetime in 698 the response and the remaining lifetime in status messages sent to 699 the client. This is an optional attribute in the request. 701 The CBOR key values for the parameters are defined in Section 6. The 702 IANA Considerations section defines how the CBOR key values can be 703 allocated to standards bodies and vendors. FQDN and URI mitigation 704 scopes may be thought of as a form of scope alias, in which the 705 addresses to which the domain name or URI resolve represent the full 706 scope of the mitigation. In the PUT request at least one of the 707 attributes target-ip or target-prefix or fqdn or uri or alias-name 708 MUST be present. DOTS agents can safely ignore Vendor-Specific 709 parameters they don't understand. The relative order of two 710 mitigation requests from a DOTS client is determined by comparing 711 their respective mitigation-id values. If two mitigation requests 712 have overlapping mitigation scopes the mitigation request with higher 713 numeric mitigation-id value will override the mitigation request with 714 a lower numeric mitigation-id value. Two mitigation-ids are 715 overlapping if there is a common IP, IP Prefix, FQDN, URI or alias- 716 name. The overlapped lower numeric mitigation-id is automatically 717 deleted and no longer available at the DOTS server. The Uri-Path 718 option carries a major and minor version nomenclature to manage 719 versioning and DOTS signal channel in this specification uses v1 720 major version. 722 In both DOTS signal and data channel sessions, the DOTS client MUST 723 authenticate itself to the DOTS server (Section 9). The DOTS server 724 can use the algorithm discussed in Section 7 of [RFC7589] to derive 725 the DOTS client identity or username from the client certificate. 726 The DOTS server couples the DOTS signal and data channel sessions 727 using the DOTS client identity, so the DOTS server can validate 728 whether the aliases conveyed in the mitigation request were indeed 729 created by the same DOTS client using the DOTS data channel session. 730 If the aliases were not created by the DOTS client then the DOTS 731 server returns 4.00 (Bad Request) in the response. The DOTS server 732 couples the DOTS signal channel sessions using the DOTS client 733 identity, and the DOTS server uses mitigation-id parameter value to 734 detect duplicate mitigation requests. If the mitigation request 735 contains both alias-name and other parameters identifying the target 736 resources (such as, target-ip, target-prefix, target-port-range, 737 fqdn, or uri) then the DOTS server appends the parameter values in 738 alias-name with the corresponding parameter values in target-ip, 739 target-prefix, target-port-range, fqdn, or uri. 741 Figure 6 shows an PUT request example to signal that ports 80, 8080, 742 and 443 on the servers 2001:db8:6401::1 and 2001:db8:6401::2 are 743 being attacked (illustrated in JSON diagnostic notation). 745 Header: PUT (Code=0.03) 746 Uri-Host: "www.example.com" 747 Uri-Path: "v1" 748 Uri-Path: "dots-signal" 749 Uri-Path: "signal" 750 Content-Format: "application/cbor" 751 { 752 "mitigation-scope": { 753 "scope": [ 754 { 755 "mitigation-id": 12332, 756 "target-ip": [ 757 "2001:db8:6401::1", 758 "2001:db8:6401::2" 759 ], 760 "target-port-range": [ 761 { 762 "lower-port": 80 763 }, 764 { 765 "lower-port": 443 766 }, 767 { 768 "lower-port": 8080 769 } 770 ], 771 "target-protocol": [ 772 6 773 ] 774 } 775 ] 776 } 777 } 779 The CBOR encoding format is shown below: 781 a1 # map(1) 782 01 # unsigned(1) 783 a1 # map(1) 784 02 # unsigned(2) 785 81 # array(1) 786 a4 # map(4) 787 03 # unsigned(3) 788 19 302c # unsigned(12332) 789 04 # unsigned(4) 790 82 # array(2) 791 70 # text(16) 792 323030313A6462383A363430313A3A31 # "2001:db8:6401::1" 794 70 # text(16) 795 323030313A6462383A363430313A3A32 # "2001:db8:6401::2" 796 05 # unsigned(5) 797 83 # array(3) 798 a1 # map(1) 799 06 # unsigned(6) 800 18 50 # unsigned(80) 801 a1 # map(1) 802 06 # unsigned(6) 803 19 01bb # unsigned(443) 804 a1 # map(1) 805 06 # unsigned(6) 806 19 1f90 # unsigned(8080) 807 08 # unsigned(8) 808 81 # array(1) 809 06 # unsigned(6) 811 Figure 6: PUT for DOTS signal 813 The DOTS server indicates the result of processing the PUT request 814 using CoAP response codes. CoAP 2.xx codes are success. CoAP 4.xx 815 codes are some sort of invalid requests. Figure 7 shows an PUT 816 response for CoAP 2.xx response codes. 818 { 819 "mitigation-scope": { 820 "scope": [ 821 { 822 "mitigation-id": integer, 823 "lifetime": integer 824 } 825 ] 826 } 827 } 829 Figure 7: 2.xx response body 831 COAP 5.xx codes are returned if the DOTS server has erred or is 832 currently unavailable to provide mitigation in response to the 833 mitigation request from the DOTS client. If the DOTS server does not 834 find the mitigation-id parameter value conveyed in the PUT request in 835 its configuration data then the server MAY accept the mitigation 836 request, and a 2.01 (Created) response is returned to the DOTS 837 client, and the DOTS server will try to mitigate the attack. If the 838 DOTS server finds the mitigation-id parameter value conveyed in the 839 PUT request in its configuration data then the server MAY update the 840 mitigation request, and a 2.04 (Changed) response is returned to 841 indicate a successful update of the mitigation request. If the 842 request is missing one or more mandatory attributes, then 4.00 (Bad 843 Request) will be returned in the response or if the request contains 844 invalid or unknown parameters then 4.02 (Invalid query) will be 845 returned in the response. 847 For the mitigation request to continue beyond the initial negotiated 848 lifetime, the DOTS client will need to refresh the current mitigation 849 request by sending a new PUT request. The PUT request MUST use the 850 same mitigation-id value, and MUST repeat all the other parameters as 851 sent in the original mitigation request apart from a possible change 852 to the lifetime parameter value. 854 5.3.2. Withdraw a DOTS Signal 856 A DELETE request is used to withdraw a DOTS signal from a DOTS server 857 (Figure 8). 859 Header: DELETE (Code=0.04) 860 Uri-Host: "host" 861 Uri-Path: "version" 862 Uri-Path: "dots-signal" 863 Uri-Path: "signal" 864 Content-Format: "application/cbor" 865 { 866 "mitigation-scope": { 867 "scope": [ 868 { 869 "mitigation-id": integer 870 } 871 ] 872 } 873 } 875 Figure 8: Withdraw DOTS signal 877 The DOTS server immediately acknowledges a DOTS client's request to 878 withdraw the DOTS signal using 2.02 (Deleted) response code with no 879 response payload. A 2.02 (Deleted) Response Code is returned even if 880 the mitigation-id parameter value conveyed in the DELETE request does 881 not exist in its configuration data before the request. If the DOTS 882 server finds the mitigation-id parameter value conveyed in the DELETE 883 request in its configuration data, then to protect against route or 884 DNS flapping caused by a client rapidly toggling mitigation, and to 885 dampen the effect of oscillating attacks, DOTS servers MAY allow 886 mitigation to continue for a limited period after acknowledging a 887 DOTS client's withdrawal of a mitigation request. During this 888 period, DOTS server status messages SHOULD indicate that mitigation 889 is active but terminating. The active-but-terminating period is 890 initially 30 seconds. If the client requests mitigation again before 891 that 30 second window elapses, the DOTS server MAY exponentially 892 increase the active- but-terminating period up to a maximum of 240 893 seconds (4 minutes). After the active-but-terminating period 894 elapses, the DOTS server MUST treat the mitigation as terminated, as 895 the DOTS client is no longer responsible for the mitigation. For 896 example, if there is a financial relationship between the DOTS client 897 and server domains, the DOTS client ceases incurring cost at this 898 point. 900 5.3.3. Retrieving a DOTS Signal 902 A GET request is used to retrieve information and status of a DOTS 903 signal from a DOTS server (Figure 9). If the DOTS server does not 904 find the mitigation-id parameter value conveyed in the GET request in 905 its configuration data, then it responds with a 4.04 (Not Found) 906 error response code. The 'c' (content) parameter and its permitted 907 values defined in [I-D.ietf-core-comi] can be used to retrieve non- 908 configuration data or configuration data or both. 910 1) To retrieve all DOTS signals signaled by the DOTS client. 912 Header: GET (Code=0.01) 913 Uri-Host: "host" 914 Uri-Path: "version" 915 Uri-Path: "dots-signal" 916 Uri-Path: "signal" 917 Observe : 0 919 2) To retrieve a specific DOTS signal signaled by the DOTS client. 920 The configuration data in the response will be formatted in the 921 same order it was processed at the DOTS server. 923 Header: GET (Code=0.01) 924 Uri-Host: "host" 925 Uri-Path: "version" 926 Uri-Path: "dots-signal" 927 Uri-Path: "signal" 928 Observe : 0 929 Content-Format: "application/cbor" 930 { 931 "mitigation-scope": { 932 "scope": [ 933 { 934 "mitigation-id": integer 935 } 936 ] 937 } 938 } 940 Figure 9: GET to retrieve the rules 942 Figure 10 shows a response example of all the active mitigation 943 requests associated with the DOTS client on the DOTS server and the 944 mitigation status of each mitigation request. 946 { 947 "mitigation-scope": { 948 "scope": [ 949 { 950 "mitigation-id": 12332, 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 "target-protocol": [ 964 6 965 ], 966 "lifetime":1800, 967 "status":3 968 "bytes-dropped": 0, 969 "bps-dropped": 0, 970 "pkts-dropped": 0, 971 "pps-dropped": 0 972 } 973 ] 974 } 975 } 977 Figure 10: Response body 979 The mitigation status parameters are described below. 981 lifetime: The remaining lifetime of the mitigation request in 982 seconds. 984 mitigation-start: Mitigation start time is represented in seconds 985 relative to 1970-01-01T00:00Z in UTC time (Section 2.4.1 of 986 [RFC7049]). 988 bytes-dropped: The total dropped byte count for the mitigation 989 request since the attack mitigation is triggered. The count wraps 990 around when it reaches the maximum value of unsigned integer. 991 This is an optional attribute. 993 bps-dropped: The average dropped bytes per second for the mitigation 994 request since the attack mitigation is triggered. This is an 995 optional attribute. 997 pkts-dropped: The total dropped packet count for the mitigation 998 request since the attack mitigation is triggered. This is an 999 optional attribute. 1001 pps-dropped: The average dropped packets per second for the 1002 mitigation request since the attack mitigation is triggered. This 1003 is an optional attribute. 1005 status: Status of attack mitigation. The 'status' parameter is a 1006 mandatory attribute. 1008 The various possible values of 'status' parameter are explained 1009 below: 1011 /--------------------+---------------------------------------------------\ 1012 | Parameter value | Description | 1013 |--------------------+---------------------------------------------------| 1014 | 1 | Attack mitigation is in progress | 1015 | | (e.g., changing the network path to re-route the | 1016 | | inbound traffic to DOTS mitigator). | 1017 +------------------------------------------------------------------------+ 1018 | 2 | Attack is successfully mitigated | 1019 | | (e.g., traffic is redirected to a DDOS mitigator | 1020 | | and attack traffic is dropped). | 1021 +------------------------------------------------------------------------+ 1022 | 3 | Attack has stopped and the DOTS client | 1023 | | can withdraw the mitigation request. | 1024 +------------------------------------------------------------------------+ 1025 | 4 | Attack has exceeded the mitigation provider | 1026 | | capability. | 1027 +------------------------------------------------------------------------+ 1028 | 5 | DOTS client has withdrawn the mitigation request | 1029 and the mitigation is active but terminating. | 1030 | | | 1031 \--------------------+---------------------------------------------------/ 1033 The observe option defined in [RFC7641] extends the CoAP core 1034 protocol with a mechanism for a CoAP client to "observe" a resource 1035 on a CoAP server: the client retrieves a representation of the 1036 resource and requests this representation be updated by the server as 1037 long as the client is interested in the resource. A DOTS client 1038 conveys the observe option set to 0 in the GET request to receive 1039 unsolicited notifications of attack mitigation status from the DOTS 1040 server. Unidirectional notifications within the bidirectional signal 1041 channel allows unsolicited message delivery, enabling asynchronous 1042 notifications between the agents. A DOTS client that is no longer 1043 interested in receiving notifications from the DOTS server can simply 1044 "forget" the observation. When the DOTS server then sends the next 1045 notification, the DOTS client will not recognize the token in the 1046 message and thus will return a Reset message. This causes the DOTS 1047 server to remove the associated entry. Alternatively, the DOTS 1048 client can explicitly deregister by issuing a GET request that has 1049 the Token field set to the token of the observation to be cancelled 1050 and includes an Observe Option with the value set to 1 (deregister). 1052 DOTS Client DOTS Server 1053 | | 1054 | GET / | 1055 | Token: 0x4a | Registration 1056 | Observe: 0 | 1057 +------------------------------>| 1058 | | 1059 | 2.05 Content | 1060 | Token: 0x4a | Notification of 1061 | Observe: 12 | the current state 1062 | status: "mitigation | 1063 | in progress" | 1064 |<------------------------------+ 1065 | 2.05 Content | 1066 | Token: 0x4a | Notification upon 1067 | Observe: 44 | a state change 1068 | status: "mitigation | 1069 | complete" | 1070 |<------------------------------+ 1071 | 2.05 Content | 1072 | Token: 0x4a | Notification upon 1073 | Observe: 60 | a state change 1074 | status: "attack stopped" | 1075 |<------------------------------+ 1076 | | 1078 Figure 11: Notifications of attack mitigation status 1080 5.3.3.1. Mitigation Status 1082 The DOTS client can send the GET request at frequent intervals 1083 without the Observe option to retrieve the configuration data of the 1084 mitigation request and non-configuration data (i.e., the attack 1085 status). The frequency of polling the DOTS server to get the 1086 mitigation status should follow the transmission guidelines given in 1087 Section 3.1.3 of [RFC8085]. If the DOTS server has been able to 1088 mitigate the attack and the attack has stopped, the DOTS server 1089 indicates as such in the status, and the DOTS client recalls the 1090 mitigation request by issuing a DELETE for the mitigation-id. 1092 A DOTS client should react to the status of the attack from the DOTS 1093 server and not the fact that it has recognized, using its own means, 1094 that the attack has been mitigated. This ensures that the DOTS 1095 client does not recall a mitigation request in a premature fashion 1096 because it is possible that the DOTS client does not sense the DDOS 1097 attack on its resources but the DOTS server could be actively 1098 mitigating the attack and the attack is not completely averted. 1100 5.3.4. Efficacy Update from DOTS Client 1102 While DDoS mitigation is active, a DOTS client MAY frequently 1103 transmit DOTS mitigation efficacy updates to the relevant DOTS 1104 server. An PUT request (Figure 12) is used to convey the mitigation 1105 efficacy update to the DOTS server. The PUT request MUST include all 1106 the parameters used in the PUT request to convey the DOTS signal 1107 (Section 5.3.1) unchanged apart from the lifetime parameter value. 1108 If this is not the case, the DOTS server MUST reject the request with 1109 a 4.02 error response code. The If-Match Option (Section 5.10.8.1 of 1110 [RFC7252]) with an empty value is used to make the PUT request 1111 conditional on the current existence of the mitigation request. If 1112 UDP is used as transport, CoAP requests may arrive out-of-order. For 1113 example, the DOTS client may send a PUT request to convey efficacy 1114 update to the DOTS server followed by a DELETE request to withdraw 1115 the mitigation request, but DELETE request arrives at the DOTS server 1116 before the PUT request. To handle out-of-order delivery of requests, 1117 if an If-Match option is present in the PUT request and the 1118 mitigation-id in the request matches a mitigation request from the 1119 DOTS client then the request is processed, and if no match is found 1120 then the PUT request is silently ignored. 1122 Header: PUT (Code=0.03) 1123 Uri-Host: "host" 1124 Uri-Path: "version" 1125 Uri-Path: "dots-signal" 1126 Uri-Path: "signal" 1127 Content-Format: "application/cbor" 1128 { 1129 "mitigation-scope": { 1130 "scope": [ 1131 { 1132 "mitigation-id": integer, 1133 "target-ip": [ 1134 "string" 1135 ], 1136 "target-port-range": [ 1137 { 1138 "lower-port": integer, 1139 "upper-port": integer 1140 } 1141 ], 1142 "target-protocol": [ 1143 integer 1144 ], 1145 "fqdn": [ 1146 "string" 1147 ], 1148 "uri": [ 1149 "string" 1150 ], 1151 "alias-name": [ 1152 "string" 1153 ], 1154 "lifetime": integer, 1155 "attack-status": integer 1156 } 1157 ] 1158 } 1159 } 1161 Figure 12: Efficacy Update 1163 The 'attack-status' parameter is a mandatory attribute. The various 1164 possible values contained in the 'attack-status' parameter are 1165 explained below: 1167 /--------------------+------------------------------------------------------\ 1168 | Parameter value | Description | 1169 |--------------------+------------------------------------------------------| 1170 | 1 | DOTS client determines that it is still under attack.| 1171 +---------------------------------------------------------------------------+ 1172 | 2 | DOTS client determines that the attack is | 1173 | | successfully mitigated | 1174 | | (e.g., attack traffic is not seen). | 1175 \--------------------+------------------------------------------------------/ 1177 The DOTS server indicates the result of processing the PUT request 1178 using CoAP response codes. The response code 2.04 (Changed) will be 1179 returned in the response if the DOTS server has accepted the 1180 mitigation efficacy update. The error response code 5.03 (Service 1181 Unavailable) is returned if the DOTS server has erred or is incapable 1182 of performing the mitigation. 1184 5.4. DOTS Signal Channel Session Configuration 1186 The DOTS client can negotiate, configure and retrieve the DOTS signal 1187 channel session behavior. The DOTS signal channel can be used, for 1188 example, to configure the following: 1190 a. Heartbeat interval: DOTS agents regularly send heartbeats (Ping/ 1191 Pong) to each other after mutual authentication in order to keep 1192 the DOTS signal channel open, heartbeat messages are exchanged 1193 between the DOTS agents every heartbeat-interval seconds to 1194 detect the current status of the DOTS signal channel session. 1196 b. Missing heartbeats allowed: This variable indicates the maximum 1197 number of consecutive heartbeat messages for which a DOTS agent 1198 did not receive a response before concluding that the session is 1199 disconnected or defunct. 1201 c. Acceptable signal loss ratio: Maximum retransmissions, 1202 retransmission timeout value and other message transmission 1203 parameters for the DOTS signal channel. 1205 Reliability is provided to requests and responses by marking them as 1206 Confirmable (CON) messages. DOTS signal channel session 1207 configuration requests and responses are marked as Confirmable (CON) 1208 messages. As explained in Section 2.1 of [RFC7252], a Confirmable 1209 message is retransmitted using a default timeout and exponential 1210 back-off between retransmissions, until the DOTS server sends an 1211 Acknowledgement message (ACK) with the same Message ID conveyed from 1212 the DOTS client. Message transmission parameters are defined in 1213 Section 4.8 of [RFC7252]. Reliability is provided to the responses 1214 by marking them as Confirmable (CON) messages. The DOTS server can 1215 either piggyback the response in the acknowledgement message or if 1216 the DOTS server is not able to respond immediately to a request 1217 carried in a Confirmable message, it simply responds with an Empty 1218 Acknowledgement message so that the DOTS client can stop 1219 retransmitting the request. Empty Acknowledgement message is 1220 explained in Section 2.2 of [RFC7252]. When the response is ready, 1221 the server sends it in a new Confirmable message which then in turn 1222 needs to be acknowledged by the DOTS client (see Sections 5.2.1 and 1223 Sections 5.2.2 of [RFC7252]). Requests and responses exchanged 1224 between DOTS agents during peacetime are marked as Confirmable 1225 messages. 1227 Implementation Note: A DOTS client that receives a response in a CON 1228 message may want to clean up the message state right after sending 1229 the ACK. If that ACK is lost and the DOTS server retransmits the 1230 CON, the DOTS client may no longer have any state to which to 1231 correlate this response, making the retransmission an unexpected 1232 message; the DOTS client will send a Reset message so it does not 1233 receive any more retransmissions. This behavior is normal and not an 1234 indication of an error (see Section 5.3.2 of [RFC7252] for more 1235 details). 1237 5.4.1. Discover Configuration Parameters 1239 A GET request is used to obtain acceptable and current configuration 1240 parameters on the DOTS server for DOTS signal channel session 1241 configuration. Figure 13 shows how to obtain acceptable 1242 configuration parameters for the server. 1244 Header: GET (Code=0.01) 1245 Uri-Host: "host" 1246 Uri-Path: "version" 1247 Uri-Path: "dots-signal" 1248 Uri-Path: "config" 1250 Figure 13: GET to retrieve configuration 1252 The DOTS server in the 2.05 (Content) response conveys the minimum 1253 and maximum attribute values acceptable by the DOTS server. 1255 Content-Format: "application/cbor" 1256 { 1257 "heartbeat-interval": { 1258 "CurrentValue": integer, 1259 "MinValue": integer, 1260 "MaxValue" : integer, 1261 }, 1262 "missing-hb-allowed": { 1263 "CurrentValue": integer, 1264 "MinValue": integer, 1265 "MaxValue" : integer, 1266 }, 1267 "max-retransmit": { 1268 "CurrentValue": integer, 1269 "MinValue": integer, 1270 "MaxValue" : integer, 1271 }, 1272 "ack-timeout": { 1273 "CurrentValue": integer, 1274 "MinValue": integer, 1275 "MaxValue" : integer, 1276 }, 1277 "ack-random-factor": { 1278 "CurrentValue": number, 1279 "MinValue": number, 1280 "MaxValue" : number, 1281 } 1282 } 1284 Figure 14: GET response body 1286 Figure 15 shows an example of acceptable and current configuration 1287 parameters on the DOTS server for DOTS signal channel session 1288 configuration. 1290 Content-Format: "application/cbor" 1291 { 1292 "heartbeat-interval": { 1293 "CurrentValue": 91, 1294 "MinValue": 60, 1295 "MaxValue" : 240, 1296 }, 1297 "missing-hb-allowed": { 1298 "CurrentValue": 3, 1299 "MinValue": 1, 1300 "MaxValue" : 7, 1301 }, 1302 "max-retransmit": { 1303 "CurrentValue": 4, 1304 "MinValue": 3, 1305 "MaxValue" : 15, 1306 }, 1307 "ack-timeout": { 1308 "CurrentValue": 2, 1309 "MinValue": 1, 1310 "MaxValue" : 30, 1311 }, 1312 "ack-random-factor": { 1313 "CurrentValue": 1.5, 1314 "MinValue": 1.0, 1315 "MaxValue" : 4.0, 1316 } 1317 } 1319 Figure 15: configuration response body 1321 5.4.2. Convey DOTS Signal Channel Session Configuration 1323 A PUT request is used to convey the configuration parameters for the 1324 signaling channel (e.g., heartbeat interval, maximum retransmissions 1325 etc). Message transmission parameters for CoAP are defined in 1326 Section 4.8 of [RFC7252]. The RECOMMENDED values of transmission 1327 parameter values are ack_timeout (2 seconds), max-retransmit (4), 1328 ack-random-factor (1.5), heartbeat-interval (93 seconds) and missing- 1329 hb-allowed (3). The heartbeat-interval value is equal to the 1330 MAX_TRANSMIT_WAIT counter (Section 4.8.2 of [RFC7252]) whose value is 1331 derived from transmission parameters. For the default transmission 1332 parameters, if the DOTS agent does not receive any response from the 1333 peer DOTS agent for three (missing-hb-allowed) consecutive "CoAP 1334 ping" confirmable messages then it concludes that the DOTS signal 1335 channel session is disconnected, and a "CoAP ping" confirmable 1336 message is retransmitted four (max-retransmit) times using a initial 1337 timeout set to random duration between 2 (ack_timeout) and 3 seconds 1338 (ack-timeout*ack-random-factor) and exponential back-off between 1339 retransmissions. 1341 If the DOTS agent wishes to change the default values of message 1342 transmission parameters then it should follow the guidance given in 1343 Section 4.8.1 of [RFC7252]. The DOTS agents MUST use the negotiated 1344 values for message transmission parameters and default values for 1345 non-negotiated message transmission parameters. The signaling 1346 channel session configuration is applicable to a single DOTS signal 1347 channel session between the DOTS agents. 1349 Header: PUT (Code=0.03) 1350 Uri-Host: "host" 1351 Uri-Path: "version" 1352 Uri-Path: "dots-signal" 1353 Uri-Path: "config" 1354 Content-Format: "application/cbor" 1355 { 1356 "signal-config": { 1357 "session-id": integer, 1358 "heartbeat-interval": integer, 1359 "missing-hb-allowed": integer, 1360 "max-retransmit": integer, 1361 "ack-timeout": integer, 1362 "ack-random-factor": number 1363 "trigger-mitigation": boolean 1364 } 1365 } 1367 Figure 16: PUT to convey the DOTS signal channel session 1368 configuration data. 1370 The parameters are described below: 1372 session-id: Identifier for the DOTS signal channel session 1373 configuration data represented as an integer. This identifier 1374 MUST be generated by the DOTS client. This document does not make 1375 any assumption about how this identifier is generated. This is a 1376 mandatory attribute. 1378 heartbeat-interval: Time interval in seconds between two 1379 consecutive heartbeat messages. This is an optional attribute. 1381 missing-hb-allowed: Maximum number of consecutive heartbeat 1382 messages for which the DOTS agent did not receive a response 1383 before concluding that the session is disconnected. This is an 1384 optional attribute. 1386 max-retransmit: Maximum number of retransmissions for a message 1387 (referred to as MAX_RETRANSMIT parameter in CoAP). This is an 1388 optional attribute. 1390 ack-timeout: Timeout value in seconds used to calculate the initial 1391 retransmission timeout value (referred to as ACK_TIMEOUT parameter 1392 in CoAP). This is an optional attribute. 1394 ack-random-factor: Random factor used to influence the timing of 1395 retransmissions (referred to as ACK_RANDOM_FACTOR parameter in 1396 CoAP). This is an optional attribute. 1398 trigger-mitigation: If the parameter value is set to 'false', then 1399 DDoS mitigation is triggered only when the DOTS signal channel 1400 session is lost. Automated mtigation on loss of signal is 1401 discussed in Section 3.3.3 of [I-D.ietf-dots-architecture]. If 1402 the DOTS client ceases to respond to heartbeat messages, then the 1403 DOTS server can detect that the DOTS session is lost. The default 1404 value of the parameter is 'true'. This is an optional attribute. 1406 In the PUT request at least one of the attributes heartbeat-interval, 1407 missing-hb-allowed, max-retransmit, ack-timeout, ack-random-factor, 1408 and trigger-mitigation MUST be present. The PUT request with higher 1409 numeric session-id value over-rides the DOTS signal channel session 1410 configuration data installed by a PUT request with a lower numeric 1411 session-id value. 1413 Figure 17 shows an PUT request example to convey the configuration 1414 parameters for the DOTS signal channel. 1416 Header: PUT (Code=0.03) 1417 Uri-Host: "www.example.com" 1418 Uri-Path: "v1" 1419 Uri-Path: "dots-signal" 1420 Uri-Path: "config" 1421 Content-Format: "application/cbor" 1422 { 1423 "signal-config": { 1424 "session-id": 1234534333242, 1425 "heartbeat-interval": 91, 1426 "missing-hb-allowed": 3, 1427 "max-retransmit": 7, 1428 "ack-timeout": 5, 1429 "ack-random-factor": 1.5, 1430 "trigger-mitigation": false 1431 } 1432 } 1434 Figure 17: PUT to convey the configuration parameters 1436 The DOTS server indicates the result of processing the PUT request 1437 using CoAP response codes. If the DOTS server finds the session-id 1438 parameter value conveyed in the PUT request in its configuration data 1439 and if the DOTS server has accepted the updated configuration 1440 parameters then the a 2.04 (Changed) response will be returned in the 1441 response. If the DOTS server does not find the session-id parameter 1442 value conveyed in the PUT request in its configuration data and if 1443 the DOTS server has accepted the configuration parameters then a 1444 response code 2.01 (Created) will be returned in the response. If 1445 the request is missing one or more mandatory attributes then 4.00 1446 (Bad Request) will be returned in the response or if the request 1447 contains invalid or unknown parameters then 4.02 (Invalid query) will 1448 be returned in the response. Response code 4.22 (Unprocessable 1449 Entity) will be returned in the response if any of the heartbeat- 1450 interval, missing-hb-allowed, max-retransmit, target-protocol, ack- 1451 timeout and ack-random-factor attribute values are not acceptable to 1452 the DOTS server. On receipt of the 4.22 error response code, the 1453 DOTS client should request the maximum and minumum attribute values 1454 acceptable to the DOTS server (Section 5.4.1). The DOTS client can 1455 re-try and send the PUT request with updated attribute values 1456 acceptable to the DOTS server. 1458 5.4.3. Delete DOTS Signal Channel Session Configuration 1460 A DELETE request is used to delete the installed DOTS signal channel 1461 session configuration data (Figure 18). 1463 Header: DELETE (Code=0.04) 1464 Uri-Host: "host" 1465 Uri-Path: "version" 1466 Uri-Path: "dots-signal" 1467 Uri-Path: "config" 1468 Content-Format: "application/cbor" 1469 { 1470 "signal-config": { 1471 "session-id": integer 1472 } 1473 } 1475 Figure 18: DELETE configuration 1477 If the DOTS server does not find the session-id parameter value 1478 conveyed in the DELETE request in its configuration data, then it 1479 responds with a 4.04 (Not Found) error response code. The DOTS 1480 server successfully acknowledges a DOTS client's request to remove 1481 the DOTS signal channel session configuration using 2.02 (Deleted) 1482 response code. 1484 5.4.4. Retrieving DOTS Signal Channel Session Configuration 1486 A GET request is used to retrieve the installed DOTS signal channel 1487 session configuration data from a DOTS server. Figure 19 shows how 1488 to retrieve the DOTS signal channel session configuration data. 1490 Header: GET (Code=0.01) 1491 Uri-Host: "host" 1492 Uri-Path: "version" 1493 Uri-Path: "dots-signal" 1494 Uri-Path: "config" 1495 Content-Format: "application/cbor" 1496 { 1497 "signal-config": { 1498 "session-id": integer 1499 } 1500 } 1502 Figure 19: GET to retrieve configuration 1504 5.5. Redirected Signaling 1506 Redirected Signaling is discussed in detail in Section 3.2.2 of 1507 [I-D.ietf-dots-architecture]. If the DOTS server wants to redirect 1508 the DOTS client to an alternative DOTS server for a signaling session 1509 then the response code 3.00 (alternate server) will be returned in 1510 the response to the client. The DOTS server can return the error 1511 response code 3.00 in response to a PUT request from the DOTS client 1512 or convey the error response code 3.00 in a unidirectional 1513 notification response from the DOTS server. 1515 The DOTS server in the error response conveys the alternate DOTS 1516 server FQDN, and the alternate DOTS server IP addresses and time to 1517 live values in the CBOR body. 1519 { 1520 "alt-server": "string", 1521 "alt-server-record": [ 1522 { 1523 "addr": "string", 1524 "ttl" : integer, 1525 } 1526 ] 1527 } 1529 Figure 20: Error response body 1531 The parameters are described below: 1533 alt-server: FQDN of an alternate DOTS server. 1535 addr: IP address of an alternate DOTS server. 1537 ttl: Time to live (TTL) represented as an integer number of seconds. 1539 Figure 21 shows a 3.00 response example to convey the DOTS alternate 1540 server www.example-alt.com, its IP addresses 2001:db8:6401::1 and 1541 2001:db8:6401::2, and TTL values 3600 and 1800. 1543 { 1545 "alt-server": "www.example-alt.com", 1546 "alt-server-record": [ 1547 { 1548 "ttl" : 3600, 1549 "addr": "2001:db8:6401::1" 1550 }, 1551 { 1552 "ttl" : 1800, 1553 "addr": "2001:db8:6401::2" 1554 } 1555 ] 1556 } 1558 Figure 21: Example of error response body 1560 When the DOTS client receives 3.00 response, it considers the current 1561 request as having failed, but SHOULD try the request with the 1562 alternate DOTS server. During a DDOS attack, the DNS server may be 1563 subjected to DDOS attack, alternate DOTS server IP addresses conveyed 1564 in the 3.00 response help the DOTS client to skip DNS lookup of the 1565 alternate DOTS server and can try to establish UDP or TCP session 1566 with the alternate DOTS server IP addresses. The DOTS client SHOULD 1567 implement DNS64 function to handle the scenario where IPv6-only DOTS 1568 client communicates with IPv4-only alternate DOTS server. 1570 5.6. Heartbeat Mechanism 1572 To provide a metric of signal health and distinguish an 'idle' signal 1573 channel from a 'disconnected' or 'defunct' session, the DOTS agent 1574 sends a heartbeat over the signal channel to maintain its half of the 1575 channel. The DOTS agent similarly expects a heartbeat from its peer 1576 DOTS agent, and may consider a session terminated in the extended 1577 absence of a peer agent heartbeat. 1579 While the communication between the DOTS agents is quiescent, the 1580 DOTS client will probe the DOTS server to ensure it has maintained 1581 cryptographic state and vice versa. Such probes can also keep alive 1582 firewall and/or NAT bindings. This probing reduces the frequency of 1583 establishing a new handshake when a DOTS signal needs to be conveyed 1584 to the DOTS server. 1586 In DOTS over UDP, heartbeat messages may be exchanged between the 1587 DOTS agents using the "COAP ping" mechanism defined in Section 4.2 of 1588 [RFC7252]. Concretely, the DOTS agent sends an Empty Confirmable 1589 message and the peer DOTS agent will respond by sending an Reset 1590 message. 1592 In DOTS over TCP, heartbeat messages can be exchanged between the 1593 DOTS agents using the Ping and Pong messages specified in Section 4.4 1594 of [I-D.ietf-core-coap-tcp-tls]. That is, the DOTS agent sends a 1595 Ping message and the peer DOTS agent would respond by sending a 1596 single Pong message. 1598 6. Mapping parameters to CBOR 1600 All parameters in the payload in the DOTS signal channel MUST be 1601 mapped to CBOR types as follows and are given an integer key to save 1602 space. The recipient of the payload MAY reject the information if it 1603 is not suitably mapped. 1605 /--------------------+------------------------+--------------------------\ 1606 | Parameter name | CBOR key | CBOR major type of value | 1607 |--------------------+------------------------+--------------------------| 1608 | mitigation-scope | 1 | 5 (map) | 1609 | scope | 2 | 5 (map) | 1610 | mitigation-id | 3 | 0 (unsigned) | 1611 | target-ip | 4 | 4 (array) | 1612 | target-port-range | 5 | 4 | 1613 | lower-port | 6 | 0 | 1614 | upper-port | 7 | 0 | 1615 | target-protocol | 8 | 4 | 1616 | fqdn | 9 | 4 | 1617 | uri | 10 | 4 | 1618 | alias-name | 11 | 4 | 1619 | lifetime | 12 | 0 | 1620 | attack-status | 13 | 0 | 1621 | signal-config | 14 | 5 | 1622 | heartbeat-interval | 15 | 0 | 1623 | max-retransmit | 16 | 0 | 1624 | ack-timeout | 17 | 0 | 1625 | ack-random-factor | 18 | 7 | 1626 | MinValue | 19 | 0 | 1627 | MaxValue | 20 | 0 | 1628 | status | 21 | 0 | 1629 | bytes-dropped | 22 | 0 | 1630 | bps-dropped | 23 | 0 | 1631 | pkts-dropped | 24 | 0 | 1632 | pps-dropped | 25 | 0 | 1633 | session-id | 26 | 0 | 1634 | trigger-mitigation | 27 | 7 (simple types) | 1635 | missing-hb-allowed | 28 | 0 | 1636 | CurrentValue | 29 | 0 | 1637 | mitigation-start | 30 | 7 (floating-point) | 1638 \--------------------+------------------------+--------------------------/ 1640 Figure 22: CBOR mappings used in DOTS signal channel message 1642 7. (D)TLS Protocol Profile and Performance considerations 1644 This section defines the (D)TLS protocol profile of DOTS signal 1645 channel over (D)TLS and DOTS data channel over TLS. 1647 There are known attacks on (D)TLS, such as machine-in-the-middle and 1648 protocol downgrade. These are general attacks on (D)TLS and not 1649 specific to DOTS over (D)TLS; please refer to the (D)TLS RFCs for 1650 discussion of these security issues. DOTS agents MUST adhere to the 1651 (D)TLS implementation recommendations and security considerations of 1652 [RFC7525] except with respect to (D)TLS version. Since encryption of 1653 DOTS using (D)TLS is virtually a green-field deployment DOTS agents 1654 MUST implement only (D)TLS 1.2 or later. 1656 Implementations compliant with this profile MUST implement all of the 1657 following items: 1659 o DOTS agents MUST support DTLS record replay detection (Section 3.3 1660 of [RFC6347]) to protect against replay attacks. 1662 o DOTS client can use (D)TLS session resumption without server-side 1663 state [RFC5077] to resume session and convey the DOTS signal. 1665 o Raw public keys [RFC7250] which reduce the size of the 1666 ServerHello, and can be used by servers that cannot obtain 1667 certificates (e.g., DOTS gateways on private networks). 1669 Implementations compliant with this profile SHOULD implement all of 1670 the following items to reduce the delay required to deliver a DOTS 1671 signal: 1673 o TLS False Start [RFC7918] which reduces round-trips by allowing 1674 the TLS second flight of messages (ChangeCipherSpec) to also 1675 contain the DOTS signal. 1677 o Cached Information Extension [RFC7924] which avoids transmitting 1678 the server's certificate and certificate chain if the client has 1679 cached that information from a previous TLS handshake. 1681 o TCP Fast Open [RFC7413] can reduce the number of round-trips to 1682 convey DOTS signal. 1684 7.1. MTU and Fragmentation Issues 1686 To avoid DOTS signal message fragmentation and the consequently 1687 decreased probability of message delivery, DOTS agents MUST ensure 1688 that the DTLS record MUST fit within a single datagram. If the Path 1689 MTU is not known to the DOTS server, an IP MTU of 1280 bytes SHOULD 1690 be assumed. The length of the URL MUST NOT exceed 256 bytes. If UDP 1691 is used to convey the DOTS signal messages then the DOTS client must 1692 consider the amount of record expansion expected by the DTLS 1693 processing when calculating the size of CoAP message that fits within 1694 the path MTU. Path MTU MUST be greater than or equal to [CoAP 1695 message size + DTLS overhead of 13 octets + authentication overhead 1696 of the negotiated DTLS cipher suite + block padding (Section 4.1.1.1 1697 of [RFC6347]]. If the request size exceeds the Path MTU then the 1698 DOTS client MUST split the DOTS signal into separate messages, for 1699 example the list of addresses in the 'target-ip' parameter could be 1700 split into multiple lists and each list conveyed in a new PUT 1701 request. 1703 Implementation Note: DOTS choice of message size parameters works 1704 well with IPv6 and with most of today's IPv4 paths. However, with 1705 IPv4, it is harder to absolutely ensure that there is no IP 1706 fragmentation. If IPv4 support on unusual networks is a 1707 consideration and path MTU is unknown, implementations may want to 1708 limit themselves to more conservative IPv4 datagram sizes such as 576 1709 bytes, as per [RFC0791] IP packets up to 576 bytes should never need 1710 to be fragmented, thus sending a maximum of 500 bytes of DOTS signal 1711 over a UDP datagram will generally avoid IP fragmentation. 1713 8. (D)TLS 1.3 considerations 1715 TLS 1.3 [I-D.ietf-tls-tls13] provides critical latency improvements 1716 for connection establishment over TLS 1.2. The DTLS 1.3 protocol 1717 [I-D.rescorla-tls-dtls13] is based on the TLS 1.3 protocol and 1718 provides equivalent security guarantees. (D)TLS 1.3 provides two 1719 basic handshake modes of interest to DOTS signal channel: 1721 o Absent packet loss, a full handshake in which the DOTS client is 1722 able to send the DOTS signal message after one round trip and the 1723 DOTS server immediately after receiving the first DOTS signal 1724 message from the client. 1726 o 0-RTT mode in which the DOTS client can authenticate itself and 1727 send DOTS signal message on its first flight, thus reducing 1728 handshake latency. 0-RTT only works if the DOTS client has 1729 previously communicated with that DOTS server, which is very 1730 likely with the DOTS signal channel. The DOTS client SHOULD 1731 establish a (D)TLS session with the DOTS server during peacetime 1732 and share a PSK. During DDOS attack, the DOTS client can use the 1733 (D)TLS session to convey the DOTS signal message and if there is 1734 no response from the server after multiple re-tries then the DOTS 1735 client can resume the (D)TLS session in 0-RTT mode using PSK. A 1736 simplified TLS 1.3 handshake with 0-RTT DOTS signal message 1737 exchange is shown in Figure 23. 1739 DOTS Client DOTS Server 1741 ClientHello 1742 (Finished) 1743 (0-RTT DOTS signal message) 1744 (end_of_early_data) --------> 1745 ServerHello 1746 {EncryptedExtensions} 1747 {ServerConfiguration} 1748 {Certificate} 1749 {CertificateVerify} 1750 {Finished} 1751 <-------- [DOTS signal message] 1752 {Finished} --------> 1754 [DOTS signal message] <-------> [DOTS signal message] 1756 Figure 23: TLS 1.3 handshake with 0-RTT 1758 9. Mutual Authentication of DOTS Agents & Authorization of DOTS Clients 1760 (D)TLS based on client certificate can be used for mutual 1761 authentication between DOTS agents. If a DOTS gateway is involved, 1762 DOTS clients and DOTS gateway MUST perform mutual authentication; 1763 only authorized DOTS clients are allowed to send DOTS signals to a 1764 DOTS gateway. DOTS gateway and DOTS server MUST perform mutual 1765 authentication; DOTS server only allows DOTS signals from authorized 1766 DOTS gateway, creating a two-link chain of transitive authentication 1767 between the DOTS client and the DOTS server. 1769 +-------------------------------------------------+ 1770 | example.com domain +---------+ | 1771 | | AAA | | 1772 | +---------------+ | Server | | 1773 | | Application | +------+--+ | 1774 | | server + ^ 1775 | | (DOTS client) |<-----------------+ | | 1776 | +---------------+ + | | example.net domain 1777 | V V | 1778 | +-------------+ | +---------------+ 1779 | +--------------+ | | | | | 1780 | | Guest +<-----x----->+ +<---------------->+ DOTS | 1781 | | (DOTS client)| | DOTS | | | Server | 1782 | +--------------+ | Gateway | | | | 1783 | +----+--------+ | +---------------+ 1784 | ^ | 1785 | | | 1786 | +----------------+ | | 1787 | | DDOS detector | | | 1788 | | (DOTS client) +<--------------+ | 1789 | +----------------+ | 1790 | | 1791 +-------------------------------------------------+ 1793 Figure 24: Example of Authentication and Authorization of DOTS Agents 1795 In the example depicted in Figure 24, the DOTS gateway and DOTS 1796 clients within the 'example.com' domain mutually authenticate with 1797 each other. After the DOTS gateway validates the identity of a DOTS 1798 client, it communicates with the AAA server in the 'example.com' 1799 domain to determine if the DOTS client is authorized to request DDOS 1800 mitigation. If the DOTS client is not authorized, a 4.01 1801 (Unauthorized) is returned in the response to the DOTS client. In 1802 this example, the DOTS gateway only allows the application server and 1803 DDOS detector to request DDOS mitigation, but does not permit the 1804 user of type 'guest' to request DDOS mitigation. 1806 Also, DOTS gateway and DOTS server located in different domains MUST 1807 perform mutual authentication using certificates. A DOTS server will 1808 only allow a DOTS gateway with a certificate for a particular domain 1809 to request mitigation for that domain. In reference to Figure 24, 1810 the DOTS server only allows the DOTS gateway to request mitigation 1811 for 'example.com' domain and not for other domains. 1813 10. IANA Considerations 1815 This specification registers new CoAP response code, new parameters 1816 for DOTS signal channel and establishes registries for mappings to 1817 CBOR. 1819 10.1. CoAP Response Code 1821 The following entry is added to the "CoAP Response Codes" sub- 1822 registry: 1824 +------+------------------------------+-----------+ 1825 | Code | Description | Reference | 1826 +------+------------------------------+-----------+ 1827 | 3.00 | Alternate server | [RFCXXXX] | 1828 +------+------------------------------+-----------+ 1830 Figure 25: CoAP Response Code 1832 [Note to RFC Editor: Please replace XXXX with the RFC number of this 1833 specification.] 1835 10.2. DOTS signal channel CBOR Mappings Registry 1837 A new registry will be requested from IANA, entitled "DOTS signal 1838 channel CBOR Mappings Registry". The registry is to be created as 1839 Expert Review Required. 1841 10.2.1. Registration Template 1843 Parameter name: 1844 Parameter names (e.g., "target_ip") in the DOTS signal channel. 1846 CBOR Key Value: 1847 Key value for the parameter. The key value MUST be an integer in 1848 the range of 1 to 65536. The key values in the range of 32768 to 1849 65536 are assigned for Vendor-Specific parameters. 1851 CBOR Major Type: 1852 CBOR Major type and optional tag for the claim. 1854 Change Controller: 1855 For Standards Track RFCs, list the "IESG". For others, give the 1856 name of the responsible party. Other details (e.g., postal 1857 address, email address, home page URI) may also be included. 1859 Specification Document(s): 1861 Reference to the document or documents that specify the parameter, 1862 preferably including URIs that can be used to retrieve copies of 1863 the documents. An indication of the relevant sections may also be 1864 included but is not required. 1866 10.2.2. Initial Registry Contents 1868 o Parameter Name: "mitigation-scope" 1869 o CBOR Key Value: 1 1870 o CBOR Major Type: 5 1871 o Change Controller: IESG 1872 o Specification Document(s): this document 1874 o Parameter Name: "scope" 1875 o CBOR Key Value: 2 1876 o CBOR Major Type: 5 1877 o Change Controller: IESG 1878 o Specification Document(s): this document 1880 o Parameter Name: "mitigation-id" 1881 o CBOR Key Value: 3 1882 o CBOR Major Type: 0 1883 o Change Controller: IESG 1884 o Specification Document(s): this document 1886 o Parameter Name:target-ip 1887 o CBOR Key Value: 4 1888 o CBOR Major Type: 4 1889 o Change Controller: IESG 1890 o Specification Document(s): this document 1892 o Parameter Name: target-port-range 1893 o CBOR Key Value: 5 1894 o CBOR Major Type: 4 1895 o Change Controller: IESG 1896 o Specification Document(s): this document 1898 o Parameter Name: "lower-port" 1899 o CBOR Key Value: 6 1900 o CBOR Major Type: 0 1901 o Change Controller: IESG 1902 o Specification Document(s): this document 1904 o Parameter Name: "upper-port" 1905 o CBOR Key Value: 7 1906 o CBOR Major Type: 0 1907 o Change Controller: IESG 1908 o Specification Document(s): this document 1909 o Parameter Name: target-protocol 1910 o CBOR Key Value: 8 1911 o CBOR Major Type: 4 1912 o Change Controller: IESG 1913 o Specification Document(s): this document 1915 o Parameter Name: "fqdn" 1916 o CBOR Key Value: 9 1917 o CBOR Major Type: 4 1918 o Change Controller: IESG 1919 o Specification Document(s): this document 1921 o Parameter Name: "uri" 1922 o CBOR Key Value: 10 1923 o CBOR Major Type: 4 1924 o Change Controller: IESG 1925 o Specification Document(s): this document 1927 o Parameter Name: alias-name 1928 o CBOR Key Value: 11 1929 o CBOR Major Type: 4 1930 o Change Controller: IESG 1931 o Specification Document(s): this document 1933 o Parameter Name: "lifetime" 1934 o CBOR Key Value: 12 1935 o CBOR Major Type: 0 1936 o Change Controller: IESG 1937 o Specification Document(s): this document 1939 o Parameter Name: attack-status 1940 o CBOR Key Value: 13 1941 o CBOR Major Type: 0 1942 o Change Controller: IESG 1943 o Specification Document(s): this document 1945 o Parameter Name: signal-config 1946 o CBOR Key Value: 14 1947 o CBOR Major Type: 5 1948 o Change Controller: IESG 1949 o Specification Document(s): this document 1951 o Parameter Name: heartbeat-interval 1952 o CBOR Key Value: 15 1953 o CBOR Major Type: 0 1954 o Change Controller: IESG 1955 o Specification Document(s): this document 1956 o Parameter Name: max-retransmit 1957 o CBOR Key Value: 16 1958 o CBOR Major Type: 0 1959 o Change Controller: IESG 1960 o Specification Document(s): this document 1962 o Parameter Name: ack-timeout 1963 o CBOR Key Value: 17 1964 o CBOR Major Type: 0 1965 o Change Controller: IESG 1966 o Specification Document(s): this document 1968 o Parameter Name: ack-random-factor 1969 o CBOR Key Value: 18 1970 o CBOR Major Type: 7 1971 o Change Controller: IESG 1972 o Specification Document(s): this document 1974 o Parameter Name: MinValue 1975 o CBOR Key Value: 19 1976 o CBOR Major Type: 0 1977 o Change Controller: IESG 1978 o Specification Document(s): this document 1980 o Parameter Name: MaxValue 1981 o CBOR Key Value: 20 1982 o CBOR Major Type: 0 1983 o Change Controller: IESG 1984 o Specification Document(s): this document 1986 o Parameter Name: status 1987 o CBOR Key Value: 21 1988 o CBOR Major Type: 0 1989 o Change Controller: IESG 1990 o Specification Document(s): this document 1992 o Parameter Name: bytes-dropped 1993 o CBOR Key Value: 22 1994 o CBOR Major Type: 0 1995 o Change Controller: IESG 1996 o Specification Document(s): this document 1998 o Parameter Name: bps-dropped 1999 o CBOR Key Value: 23 2000 o CBOR Major Type: 0 2001 o Change Controller: IESG 2002 o Specification Document(s): this document 2003 o Parameter Name: pkts-dropped 2004 o CBOR Key Value: 24 2005 o CBOR Major Type: 0 2006 o Change Controller: IESG 2007 o Specification Document(s): this document 2009 o Parameter Name: pps-dropped 2010 o CBOR Key Value: 25 2011 o CBOR Major Type: 0 2012 o Change Controller: IESG 2013 o Specification Document(s): this document 2015 o Parameter Name: session-id 2016 o CBOR Key Value: 26 2017 o CBOR Major Type: 0 2018 o Change Controller: IESG 2019 o Specification Document(s): this document 2021 o Parameter Name: trigger-mitigation 2022 o CBOR Key Value: 27 2023 o CBOR Major Type: 7 2024 o Change Controller: IESG 2025 o Specification Document(s): this document 2027 o Parameter Name: missing-hb-allowed 2028 o CBOR Key Value: 28 2029 o CBOR Major Type: 0 2030 o Change Controller: IESG 2031 o Specification Document(s): this document 2033 o Parameter Name: CurrentValue 2034 o CBOR Key Value: 29 2035 o CBOR Major Type: 0 2036 o Change Controller: IESG 2037 o Specification Document(s): this document 2039 11. Implementation Status 2041 [Note to RFC Editor: Please remove this section and reference to 2042 [RFC7942] prior to publication.] 2044 This section records the status of known implementations of the 2045 protocol defined by this specification at the time of posting of this 2046 Internet-Draft, and is based on a proposal described in [RFC7942]. 2047 The description of implementations in this section is intended to 2048 assist the IETF in its decision processes in progressing drafts to 2049 RFCs. Please note that the listing of any individual implementation 2050 here does not imply endorsement by the IETF. Furthermore, no effort 2051 has been spent to verify the information presented here that was 2052 supplied by IETF contributors. This is not intended as, and must not 2053 be construed to be, a catalog of available implementations or their 2054 features. Readers are advised to note that other implementations may 2055 exist. 2057 According to [RFC7942], "this will allow reviewers and working groups 2058 to assign due consideration to documents that have the benefit of 2059 running code, which may serve as evidence of valuable experimentation 2060 and feedback that have made the implemented protocols more mature. 2061 It is up to the individual working groups to use this information as 2062 they see fit". 2064 11.1. nttdots 2066 Organization: NTT Communication is developing a DOTS client and 2067 DOTS server software based on DOTS signal channel specified in 2068 this draft. It will be open-sourced. 2069 Description: Early implementation of DOTS protocol. It is aimed to 2070 implement a full DOTS protocol spec in accordance with maturing of 2071 DOTS protocol itself. 2072 Implementation: https://github.com/nttdots/go-dots 2073 Level of maturity: It is a early implementation of DOTS protocol. 2074 Messaging between DOTS clients and DOTS servers has been tested. 2075 Level of maturity will increase in accordance with maturing of 2076 DOTS protocol itself. 2077 Coverage: Capability of DOTS client: sending DOTS messages to the 2078 DOTS server in CoAP over DTLS as dots-signal. Capability of DOTS 2079 server: receiving dots-signal, validating received dots-signal, 2080 starting mitigation by handing over the dots-signal to DDOS 2081 mitigator. 2082 Licensing: It will be open-sourced with BSD 3-clause license. 2083 Implementation experience: It is implemented in Go-lang. Core 2084 specification of signaling is mature to be implemented, however, 2085 finding good libraries(like DTLS, CoAP) is rather difficult. 2086 Contact: Kaname Nishizuka 2088 12. Security Considerations 2090 Authenticated encryption MUST be used for data confidentiality and 2091 message integrity. (D)TLS based on client certificate MUST be used 2092 for mutual authentication. The interaction between the DOTS agents 2093 requires Datagram Transport Layer Security (DTLS) and Transport Layer 2094 Security (TLS) with a cipher suite offering confidentiality 2095 protection and the guidance given in [RFC7525] MUST be followed to 2096 avoid attacks on (D)TLS. 2098 A single DOTS signal channel between DOTS agents can be used to 2099 exchange multiple DOTS signal messages. To reduce DOTS client and 2100 DOTS server workload, DOTS client SHOULD re-use the (D)TLS session. 2102 If TCP is used between DOTS agents, an attacker may be able to inject 2103 RST packets, bogus application segments, etc., regardless of whether 2104 TLS authentication is used. Because the application data is TLS 2105 protected, this will not result in the application receiving bogus 2106 data, but it will constitute a DoS on the connection. This attack 2107 can be countered by using TCP-AO [RFC5925]. If TCP-AO is used, then 2108 any bogus packets injected by an attacker will be rejected by the 2109 TCP-AO integrity check and therefore will never reach the TLS layer. 2111 Special care should be taken in order to ensure that the activation 2112 of the proposed mechanism won't have an impact on the stability of 2113 the network (including connectivity and services delivered over that 2114 network). 2116 Involved functional elements in the cooperation system must establish 2117 exchange instructions and notification over a secure and 2118 authenticated channel. Adequate filters can be enforced to avoid 2119 that nodes outside a trusted domain can inject request such as 2120 deleting filtering rules. Nevertheless, attacks can be initiated 2121 from within the trusted domain if an entity has been corrupted. 2122 Adequate means to monitor trusted nodes should also be enabled. 2124 13. Contributors 2126 The following individuals have contributed to this document: 2128 Mike Geller Cisco Systems, Inc. 3250 Florida 33309 USA Email: 2129 mgeller@cisco.com 2131 Robert Moskowitz HTT Consulting Oak Park, MI 42837 United States 2132 Email: rgm@htt-consult.com 2134 Dan Wing Email: dwing-ietf@fuggles.com 2136 14. Acknowledgements 2138 Thanks to Christian Jacquenet, Roland Dobbins, Andrew Mortensen, 2139 Roman D. Danyliw, Michael Richardson, Ehud Doron, Kaname Nishizuka, 2140 Dave Dolson, Liang Xia, Jon Shallow, and Gilbert Clark for the 2141 discussion and comments. 2143 15. References 2145 15.1. Normative References 2147 [I-D.ietf-core-coap-tcp-tls] 2148 Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 2149 Silverajan, B., and B. Raymor, "CoAP (Constrained 2150 Application Protocol) over TCP, TLS, and WebSockets", 2151 draft-ietf-core-coap-tcp-tls-09 (work in progress), May 2152 2017. 2154 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2155 Requirement Levels", BCP 14, RFC 2119, 2156 DOI 10.17487/RFC2119, March 1997, 2157 . 2159 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2160 (TLS) Protocol Version 1.2", RFC 5246, 2161 DOI 10.17487/RFC5246, August 2008, 2162 . 2164 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 2165 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 2166 June 2010, . 2168 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2169 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 2170 January 2012, . 2172 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 2173 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 2174 Transport Layer Security (TLS) and Datagram Transport 2175 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 2176 June 2014, . 2178 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2179 Application Protocol (CoAP)", RFC 7252, 2180 DOI 10.17487/RFC7252, June 2014, 2181 . 2183 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 2184 "Recommendations for Secure Use of Transport Layer 2185 Security (TLS) and Datagram Transport Layer Security 2186 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 2187 2015, . 2189 [RFC7641] Hartke, K., "Observing Resources in the Constrained 2190 Application Protocol (CoAP)", RFC 7641, 2191 DOI 10.17487/RFC7641, September 2015, 2192 . 2194 15.2. Informative References 2196 [I-D.ietf-core-comi] 2197 Veillette, M., Stok, P., Pelov, A., and A. Bierman, "CoAP 2198 Management Interface", draft-ietf-core-comi-01 (work in 2199 progress), July 2017. 2201 [I-D.ietf-core-yang-cbor] 2202 Veillette, M., Pelov, A., Somaraju, A., Turner, R., and A. 2203 Minaburo, "CBOR Encoding of Data Modeled with YANG", 2204 draft-ietf-core-yang-cbor-05 (work in progress), August 2205 2017. 2207 [I-D.ietf-dots-architecture] 2208 Mortensen, A., Andreasen, F., Reddy, T., 2209 christopher_gray3@cable.comcast.com, c., Compton, R., and 2210 N. Teague, "Distributed-Denial-of-Service Open Threat 2211 Signaling (DOTS) Architecture", draft-ietf-dots- 2212 architecture-04 (work in progress), July 2017. 2214 [I-D.ietf-dots-data-channel] 2215 Reddy, T., Boucadair, M., Nishizuka, K., Xia, L., Patil, 2216 P., Mortensen, A., and N. Teague, "Distributed Denial-of- 2217 Service Open Threat Signaling (DOTS) Data Channel", draft- 2218 ietf-dots-data-channel-03 (work in progress), August 2017. 2220 [I-D.ietf-dots-requirements] 2221 Mortensen, A., Moskowitz, R., and T. Reddy, "Distributed 2222 Denial of Service (DDoS) Open Threat Signaling 2223 Requirements", draft-ietf-dots-requirements-06 (work in 2224 progress), July 2017. 2226 [I-D.ietf-dots-use-cases] 2227 Dobbins, R., Migault, D., Fouant, S., Moskowitz, R., 2228 Teague, N., Xia, L., and K. Nishizuka, "Use cases for DDoS 2229 Open Threat Signaling", draft-ietf-dots-use-cases-07 (work 2230 in progress), July 2017. 2232 [I-D.ietf-tls-tls13] 2233 Rescorla, E., "The Transport Layer Security (TLS) Protocol 2234 Version 1.3", draft-ietf-tls-tls13-21 (work in progress), 2235 July 2017. 2237 [I-D.rescorla-tls-dtls13] 2238 Rescorla, E., Tschofenig, H., and N. Modadugu, "The 2239 Datagram Transport Layer Security (DTLS) Protocol Version 2240 1.3", draft-rescorla-tls-dtls13-01 (work in progress), 2241 March 2017. 2243 [proto_numbers] 2244 "IANA, "Protocol Numbers"", 2011, 2245 . 2247 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 2248 DOI 10.17487/RFC0791, September 1981, 2249 . 2251 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 2252 (CIDR): The Internet Address Assignment and Aggregation 2253 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 2254 2006, . 2256 [RFC4732] Handley, M., Ed., Rescorla, E., Ed., and IAB, "Internet 2257 Denial-of-Service Considerations", RFC 4732, 2258 DOI 10.17487/RFC4732, December 2006, 2259 . 2261 [RFC4987] Eddy, W., "TCP SYN Flooding Attacks and Common 2262 Mitigations", RFC 4987, DOI 10.17487/RFC4987, August 2007, 2263 . 2265 [RFC5077] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, 2266 "Transport Layer Security (TLS) Session Resumption without 2267 Server-Side State", RFC 5077, DOI 10.17487/RFC5077, 2268 January 2008, . 2270 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2271 the Network Configuration Protocol (NETCONF)", RFC 6020, 2272 DOI 10.17487/RFC6020, October 2010, 2273 . 2275 [RFC6555] Wing, D. and A. Yourtchenko, "Happy Eyeballs: Success with 2276 Dual-Stack Hosts", RFC 6555, DOI 10.17487/RFC6555, April 2277 2012, . 2279 [RFC6724] Thaler, D., Ed., Draves, R., Matsumoto, A., and T. Chown, 2280 "Default Address Selection for Internet Protocol Version 6 2281 (IPv6)", RFC 6724, DOI 10.17487/RFC6724, September 2012, 2282 . 2284 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2285 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2286 October 2013, . 2288 [RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 2289 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 2290 . 2292 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 2293 NETCONF Protocol over Transport Layer Security (TLS) with 2294 Mutual X.509 Authentication", RFC 7589, 2295 DOI 10.17487/RFC7589, June 2015, 2296 . 2298 [RFC7918] Langley, A., Modadugu, N., and B. Moeller, "Transport 2299 Layer Security (TLS) False Start", RFC 7918, 2300 DOI 10.17487/RFC7918, August 2016, 2301 . 2303 [RFC7924] Santesson, S. and H. Tschofenig, "Transport Layer Security 2304 (TLS) Cached Information Extension", RFC 7924, 2305 DOI 10.17487/RFC7924, July 2016, 2306 . 2308 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 2309 Code: The Implementation Status Section", BCP 205, 2310 RFC 7942, DOI 10.17487/RFC7942, July 2016, 2311 . 2313 [RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 2314 Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, 2315 March 2017, . 2317 Authors' Addresses 2319 Tirumaleswar Reddy 2320 McAfee, Inc. 2321 Embassy Golf Link Business Park 2322 Bangalore, Karnataka 560071 2323 India 2325 Email: kondtir@gmail.com 2326 Mohamed Boucadair 2327 Orange 2328 Rennes 35000 2329 France 2331 Email: mohamed.boucadair@orange.com 2333 Prashanth Patil 2334 Cisco Systems, Inc. 2336 Email: praspati@cisco.com 2338 Andrew Mortensen 2339 Arbor Networks, Inc. 2340 2727 S. State St 2341 Ann Arbor, MI 48104 2342 United States 2344 Email: amortensen@arbor.net 2346 Nik Teague 2347 Verisign, Inc. 2348 United States 2350 Email: nteague@verisign.com