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