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