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