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