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