< draft-ietf-dots-signal-channel-13.txt   draft-ietf-dots-signal-channel-14.txt >
DOTS T. Reddy DOTS T. Reddy
Internet-Draft McAfee Internet-Draft McAfee
Intended status: Standards Track M. Boucadair Intended status: Standards Track M. Boucadair
Expires: June 16, 2018 Orange Expires: June 21, 2018 Orange
P. Patil P. Patil
Cisco Cisco
A. Mortensen A. Mortensen
Arbor Networks, Inc. Arbor Networks, Inc.
N. Teague N. Teague
Verisign, Inc. Verisign, Inc.
December 13, 2017 December 18, 2017
Distributed Denial-of-Service Open Threat Signaling (DOTS) Signal Distributed Denial-of-Service Open Threat Signaling (DOTS) Signal
Channel Channel
draft-ietf-dots-signal-channel-13 draft-ietf-dots-signal-channel-14
Abstract Abstract
This document specifies the DOTS signal channel, a protocol for This document specifies the DOTS signal channel, a protocol for
signaling the need for protection against Distributed Denial-of- signaling the need for protection against Distributed Denial-of-
Service (DDoS) attacks to a server capable of enabling network Service (DDoS) attacks to a server capable of enabling network
traffic mitigation on behalf of the requesting client. traffic mitigation on behalf of the requesting client.
A companion document defines the DOTS data channel, a separate A companion document defines the DOTS data channel, a separate
reliable communication layer for DOTS management and configuration reliable communication layer for DOTS management and configuration
skipping to change at page 2, line 20 skipping to change at page 2, line 20
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on June 16, 2018. This Internet-Draft will expire on June 21, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2017 IETF Trust and the persons identified as the Copyright (c) 2017 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 3, line 4 skipping to change at page 3, line 4
4.1. DOTS Server(s) Discovery . . . . . . . . . . . . . . . . 8 4.1. DOTS Server(s) Discovery . . . . . . . . . . . . . . . . 8
4.2. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . 8 4.2. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . 8
4.3. Happy Eyeballs for DOTS Signal Channel . . . . . . . . . 9 4.3. Happy Eyeballs for DOTS Signal Channel . . . . . . . . . 9
4.4. DOTS Mitigation Methods . . . . . . . . . . . . . . . . . 10 4.4. DOTS Mitigation Methods . . . . . . . . . . . . . . . . . 10
4.4.1. Request Mitigation . . . . . . . . . . . . . . . . . 11 4.4.1. Request Mitigation . . . . . . . . . . . . . . . . . 11
4.4.2. Retrieve Information Related to a Mitigation . . . . 20 4.4.2. Retrieve Information Related to a Mitigation . . . . 20
4.4.3. Efficacy Update from DOTS Clients . . . . . . . . . . 28 4.4.3. Efficacy Update from DOTS Clients . . . . . . . . . . 28
4.4.4. Withdraw a Mitigation . . . . . . . . . . . . . . . . 30 4.4.4. Withdraw a Mitigation . . . . . . . . . . . . . . . . 30
4.5. DOTS Signal Channel Session Configuration . . . . . . . . 32 4.5. DOTS Signal Channel Session Configuration . . . . . . . . 32
4.5.1. Discover Configuration Parameters . . . . . . . . . . 33 4.5.1. Discover Configuration Parameters . . . . . . . . . . 33
4.5.2. Convey DOTS Signal Channel Session Configuration . . 35 4.5.2. Convey DOTS Signal Channel Session Configuration . . 37
4.5.3. Delete DOTS Signal Channel Session Configuration . . 40 4.5.3. Delete DOTS Signal Channel Session Configuration . . 43
4.6. Redirected Signaling . . . . . . . . . . . . . . . . . . 40 4.6. Redirected Signaling . . . . . . . . . . . . . . . . . . 44
4.7. Heartbeat Mechanism . . . . . . . . . . . . . . . . . . . 42 4.7. Heartbeat Mechanism . . . . . . . . . . . . . . . . . . . 45
5. DOTS Signal Channel YANG Module . . . . . . . . . . . . . . . 43 5. DOTS Signal Channel YANG Module . . . . . . . . . . . . . . . 47
5.1. Tree Structure . . . . . . . . . . . . . . . . . . . . . 43 5.1. Tree Structure . . . . . . . . . . . . . . . . . . . . . 47
5.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 45 5.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 49
6. Mapping Parameters to CBOR . . . . . . . . . . . . . . . . . 55 6. Mapping Parameters to CBOR . . . . . . . . . . . . . . . . . 62
7. (D)TLS Protocol Profile and Performance Considerations . . . 56 7. (D)TLS Protocol Profile and Performance Considerations . . . 63
7.1. (D)TLS Protocol Profile . . . . . . . . . . . . . . . . . 56 7.1. (D)TLS Protocol Profile . . . . . . . . . . . . . . . . . 63
7.2. (D)TLS 1.3 Considerations . . . . . . . . . . . . . . . . 58 7.2. (D)TLS 1.3 Considerations . . . . . . . . . . . . . . . . 64
7.3. MTU and Fragmentation . . . . . . . . . . . . . . . . . . 59 7.3. MTU and Fragmentation . . . . . . . . . . . . . . . . . . 65
8. Mutual Authentication of DOTS Agents & Authorization of DOTS 8. Mutual Authentication of DOTS Agents & Authorization of DOTS
Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 61 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 68
9.1. DOTS Signal Channel UDP and TCP Port Number . . . . . . . 61 9.1. DOTS Signal Channel UDP and TCP Port Number . . . . . . . 68
9.2. Well-Known 'dots' URI . . . . . . . . . . . . . . . . . . 61 9.2. Well-Known 'dots' URI . . . . . . . . . . . . . . . . . . 68
9.3. CoAP Response Code . . . . . . . . . . . . . . . . . . . 61 9.3. CoAP Response Code . . . . . . . . . . . . . . . . . . . 68
9.4. DOTS Signal Channel CBOR Mappings Registry . . . . . . . 62 9.4. DOTS Signal Channel CBOR Mappings Registry . . . . . . . 69
9.4.1. Registration Template . . . . . . . . . . . . . . . . 62 9.4.1. Registration Template . . . . . . . . . . . . . . . . 69
9.4.2. Initial Registry Contents . . . . . . . . . . . . . . 62 9.4.2. Initial Registry Contents . . . . . . . . . . . . . . 69
9.5. DOTS Signal Channel YANG Module . . . . . . . . . . . . . 68 9.5. DOTS Signal Channel YANG Module . . . . . . . . . . . . . 75
10. Implementation Status . . . . . . . . . . . . . . . . . . . . 68 10. Implementation Status . . . . . . . . . . . . . . . . . . . . 75
10.1. nttdots . . . . . . . . . . . . . . . . . . . . . . . . 69 10.1. nttdots . . . . . . . . . . . . . . . . . . . . . . . . 76
11. Security Considerations . . . . . . . . . . . . . . . . . . . 69 11. Security Considerations . . . . . . . . . . . . . . . . . . . 76
12. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 70 12. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 77
13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 70 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 77
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 71 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 78
14.1. Normative References . . . . . . . . . . . . . . . . . . 71 14.1. Normative References . . . . . . . . . . . . . . . . . . 78
14.2. Informative References . . . . . . . . . . . . . . . . . 73 14.2. Informative References . . . . . . . . . . . . . . . . . 80
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 76 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 84
1. Introduction 1. Introduction
A distributed denial-of-service (DDoS) attack is an attempt to make A distributed denial-of-service (DDoS) attack is an attempt to make
machines or network resources unavailable to their intended users. machines or network resources unavailable to their intended users.
In most cases, sufficient scale can be achieved by compromising In most cases, sufficient scale can be achieved by compromising
enough end-hosts and using those infected hosts to perpetrate and enough end-hosts and using those infected hosts to perpetrate and
amplify the attack. The victim in this attack can be an application amplify the attack. The victim in this attack can be an application
server, a host, a router, a firewall, or an entire network. server, a host, a router, a firewall, or an entire network.
skipping to change at page 4, line 33 skipping to change at page 4, line 33
detected, suspected, or anticipated attacks. This protocol enables detected, suspected, or anticipated attacks. This protocol enables
cooperation between DOTS agents to permit a highly-automated network cooperation between DOTS agents to permit a highly-automated network
defense that is robust, reliable, and secure. defense that is robust, reliable, and secure.
An example of a network diagram that illustrates a deployment of DOTS An example of a network diagram that illustrates a deployment of DOTS
agents is shown in Figure 1. In this example, a DOTS server is agents is shown in Figure 1. In this example, a DOTS server is
operating on the access network. A DOTS client is located on the LAN operating on the access network. A DOTS client is located on the LAN
(Local Area Network), while a DOTS gateway is embedded in the CPE (Local Area Network), while a DOTS gateway is embedded in the CPE
(Customer Premises Equipment). (Customer Premises Equipment).
Network Network
Resource CPE router Access network __________ Resource CPE router Access network __________
+-----------+ +--------------+ +-------------+ / \ +-----------+ +--------------+ +-------------+ / \
| |____| |_______| |___ | Internet | | |___| |____| |___ | Internet |
|DOTS client| | DOTS gateway | | DOTS server | | | |DOTS client| | DOTS gateway | | DOTS server | | |
| | | | | | | | | | | | | | | |
+-----------+ +--------------+ +-------------+ \__________/ +-----------+ +--------------+ +-------------+ \__________/
Figure 1: Sample DOTS Deployment (1) Figure 1: Sample DOTS Deployment (1)
DOTS servers can also be reachable over the Internet, as depicted in DOTS servers can also be reachable over the Internet, as depicted in
Figure 2. Figure 2.
Network DDoS mitigation Network DDoS mitigation
Resource CPE router __________ service Resource CPE router __________ service
+-----------+ +-------------+ / \ +-------------+ +-----------+ +-------------+ / \ +-------------+
| |____| |_______| |___ | | | |___| |____| |___ | |
|DOTS client| |DOTS gateway | | Internet | | DOTS server | |DOTS client| |DOTS gateway | | Internet | | DOTS server |
| | | | | | | | | | | | | | | |
+-----------+ +-------------+ \__________/ +-------------+ +-----------+ +-------------+ \__________/ +-------------+
Figure 2: Sample DOTS Deployment (2) Figure 2: Sample DOTS Deployment (2)
In typical deployments, the DOTS client belongs to a different In typical deployments, the DOTS client belongs to a different
administrative domain than the DOTS server. For example, the DOTS administrative domain than the DOTS server. For example, the DOTS
client is embedded in a firewall protecting services owned and client is embedded in a firewall protecting services owned and
operated by a domain, while the DOTS server is owned and operated by operated by a domain, while the DOTS server is owned and operated by
a different domain providing DDoS mitigation services. The latter a different domain providing DDoS mitigation services. The latter
might or might not provide connectivity services to the network might or might not provide connectivity services to the network
hosting the DOTS client. hosting the DOTS client.
skipping to change at page 5, line 49 skipping to change at page 5, line 49
2. Notational Conventions and Terminology 2. Notational Conventions and Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in "OPTIONAL" in this document are to be interpreted as described in
[RFC2119]. [RFC2119].
(D)TLS is used for statements that apply to both Transport Layer (D)TLS is used for statements that apply to both Transport Layer
Security [RFC5246] and Datagram Transport Layer Security [RFC6347]. Security [RFC5246] and Datagram Transport Layer Security [RFC6347].
Specific terms will be used for any statement that applies to either Specific terms are used for any statement that applies to either
protocol alone. protocol alone.
The reader should be familiar with the terms defined in The reader should be familiar with the terms defined in
[I-D.ietf-dots-architecture]. [I-D.ietf-dots-architecture].
The meaning of the symbols in YANG tree diagrams is defined in The meaning of the symbols in YANG tree diagrams is defined in
[I-D.ietf-netmod-yang-tree-diagrams]. [I-D.ietf-netmod-yang-tree-diagrams].
3. Design Overview 3. Design Overview
skipping to change at page 6, line 24 skipping to change at page 6, line 24
Application Protocol (CoAP) [RFC7252], a lightweight protocol Application Protocol (CoAP) [RFC7252], a lightweight protocol
originally designed for constrained devices and networks. The many originally designed for constrained devices and networks. The many
features of CoAP (expectation of packet loss, support for features of CoAP (expectation of packet loss, support for
asynchronous non-confirmable messaging, congestion control, small asynchronous non-confirmable messaging, congestion control, small
message overhead limiting the need for fragmentation, use of minimal message overhead limiting the need for fragmentation, use of minimal
resources, and support for (D)TLS) makes it a good candidate to build resources, and support for (D)TLS) makes it a good candidate to build
the DOTS signaling mechanism from. the DOTS signaling mechanism from.
The DOTS signal channel is layered on existing standards (Figure 3). The DOTS signal channel is layered on existing standards (Figure 3).
+--------------+ +---------------------+
| DOTS | | DOTS Signal Channel |
+--------------+ +---------------------+
| CoAP | | CoAP |
+--------------+ +----------+----------+
| TLS | DTLS | | TLS | DTLS |
+--------------+ +----------+----------+
| TCP | UDP | | TCP | UDP |
+--------------+ +----------+----------+
| IP | | IP |
+--------------+ +---------------------+
Figure 3: Abstract Layering of DOTS signal channel over CoAP over Figure 3: Abstract Layering of DOTS signal channel over CoAP over
(D)TLS (D)TLS
By default, a DOTS signal channel MUST run over port number TBD as By default, a DOTS signal channel MUST run over port number TBD as
defined in Section 9.1, for both UDP and TCP, unless the DOTS server defined in Section 9.1, for both UDP and TCP, unless the DOTS server
has a mutual agreement with its DOTS clients to use a different port has a mutual agreement with its DOTS clients to use a different port
number. DOTS clients may alternatively support means to dynamically number. DOTS clients may alternatively support means to dynamically
discover the ports used by their DOTS servers. In order to use a discover the ports used by their DOTS servers. In order to use a
distinct port number (as opposed to TBD), DOTS clients and servers distinct port number (as opposed to TBD), DOTS clients and servers
skipping to change at page 7, line 25 skipping to change at page 7, line 25
or IPv6 transfer capabilities. A Happy Eyeballs procedure for DOTS or IPv6 transfer capabilities. A Happy Eyeballs procedure for DOTS
signal channel is specified in Section 4.3. signal channel is specified in Section 4.3.
Messages exchanged between DOTS agents are serialized using Concise Messages exchanged between DOTS agents are serialized using Concise
Binary Object Representation (CBOR) [RFC7049], CBOR is a binary Binary Object Representation (CBOR) [RFC7049], CBOR is a binary
encoding scheme designed for small code and message size. CBOR- encoding scheme designed for small code and message size. CBOR-
encoded payloads are used to carry signal channel-specific payload encoded payloads are used to carry signal channel-specific payload
messages which convey request parameters and response information messages which convey request parameters and response information
such as errors. In order to allow the use of the same data models, such as errors. In order to allow the use of the same data models,
[RFC7951] specifies the JSON encoding of YANG-modeled data. A [RFC7951] specifies the JSON encoding of YANG-modeled data. A
similar effort for CBOR is defined in [I-D.ietf-core-yang-cbor]. similar effort for CBOR is defined in [I-D.ietf-core-yang-cbor]. All
parameters in the payload of the DOTS signal channel are mapped to
CBOR types as specified in Section 6.
From that standpoint, this document specifies a YANG data model for From that standpoint, this document specifies a YANG data model for
representing mitigation scopes and DOTS signal channel session representing mitigation scopes and DOTS signal channel session
configuration data (Section 5). Representing these data as CBOR data configuration data (Section 5). Representing these data as CBOR data
is assumed to follow the rules in [I-D.ietf-core-yang-cbor] or those is assumed to follow the rules in [I-D.ietf-core-yang-cbor] or those
in [RFC7951] combined with JSON/CBOR conversion rules in [RFC7049]. in [RFC7951] combined with JSON/CBOR conversion rules in [RFC7049]. .
In order to prevent fragmentation, DOTS agents must follow the In order to prevent fragmentation, DOTS agents must follow the
recommendations documented in Section 4.6 of [RFC7252]. Refer to recommendations documented in Section 4.6 of [RFC7252]. Refer to
Section 7.3 for more details. Section 7.3 for more details.
DOTS agents MUST support GET, PUT, and DELETE CoAP methods. The DOTS agents MUST support GET, PUT, and DELETE CoAP methods. The
payload included in CoAP responses with 2.xx and 3.xx Response Codes payload included in CoAP responses with 2.xx and 3.xx Response Codes
MUST be of content type "application/cbor" (Section 5.5.1 of MUST be of content type "application/cbor" (Section 5.5.1 of
[RFC7252]). CoAP responses with 4.xx and 5.xx error Response Codes [RFC7252]). CoAP responses with 4.xx and 5.xx error Response Codes
MUST include a diagnostic payload (Section 5.5.2 of [RFC7252]). The MUST include a diagnostic payload (Section 5.5.2 of [RFC7252]). The
skipping to change at page 8, line 9 skipping to change at page 8, line 11
conflicting mitigation requests from these clients. This document conflicting mitigation requests from these clients. This document
does not aim to specify a comprehensive list of conditions under does not aim to specify a comprehensive list of conditions under
which a DOTS server will characterize two mitigation requests from which a DOTS server will characterize two mitigation requests from
distinct DOTS clients as conflicting, nor recommend a DOTS server distinct DOTS clients as conflicting, nor recommend a DOTS server
behavior for processing conflicting mitigation requests. Those behavior for processing conflicting mitigation requests. Those
considerations are implementation- and deployment-specific. considerations are implementation- and deployment-specific.
Nevertheless, the document specifies the mechanisms to notify DOTS Nevertheless, the document specifies the mechanisms to notify DOTS
clients when conflicts occur, including the conflict cause clients when conflicts occur, including the conflict cause
(Section 4.4). (Section 4.4).
In deployments where one or more translators (e.g., NAT44, NAT64, In deployments where one or more translators (e.g., Traditional NAT
NPTv6) are enabled between the client's network and the DOTS server, [RFC3022], CGN [RFC6888], NAT64 [RFC6146], NPTv6 [RFC6296]) are
DOTS signal channel messages forwarded to a DOTS server must not enabled between the client's network and the DOTS server, DOTS signal
include internal IP addresses/prefixes and/or port numbers; external channel messages forwarded to a DOTS server must not include internal
addresses/ prefixes and/or port numbers as assigned by the translator IP addresses/prefixes and/or port numbers; external addresses/
must be used instead. This document does not make any recommendation prefixes and/or port numbers as assigned by the translator must be
about possible translator discovery mechanisms. The following are used instead. This document does not make any recommendation about
some (non-exhaustive) deployment examples that may be considered: possible translator discovery mechanisms. The following are some
(non-exhaustive) deployment examples that may be considered:
o Port Control Protocol (PCP) [RFC6887] or Session Traversal o Port Control Protocol (PCP) [RFC6887] or Session Traversal
Utilities for NAT (STUN) [RFC5389] may be used to retrieve the Utilities for NAT (STUN) [RFC5389] may be used to retrieve the
external addresses/prefixes and/or port numbers. Information external addresses/prefixes and/or port numbers. Information
retrieved by means of PCP will be used to feed the DOTS signal retrieved by means of PCP or STUN will be used to feed the DOTS
channel messages that will be sent to a DOTS server. signal channel messages that will be sent to a DOTS server.
o A DOTS gateway may be co-located with the translator. The DOTS o A DOTS gateway may be co-located with the translator. The DOTS
gateway will need to update the DOTS messages, based upon the gateway will need to update the DOTS messages, based upon the
local translator's binding table. local translator's binding table.
4. DOTS Signal Channel: Messages & Behaviors 4. DOTS Signal Channel: Messages & Behaviors
4.1. DOTS Server(s) Discovery 4.1. DOTS Server(s) Discovery
This document assumes that DOTS clients are provisioned with the This document assumes that DOTS clients are provisioned with the
skipping to change at page 9, line 17 skipping to change at page 9, line 19
+-----------------------+----------------+-------------+ +-----------------------+----------------+-------------+
| Mitigation | /v1/mitigate | Section 4.4 | | Mitigation | /v1/mitigate | Section 4.4 |
+-----------------------+----------------+-------------+ +-----------------------+----------------+-------------+
| Session configuration | /v1/config | Section 4.5 | | Session configuration | /v1/config | Section 4.5 |
+-----------------------+----------------+-------------+ +-----------------------+----------------+-------------+
Table 1: Operations and their corresponding URIs Table 1: Operations and their corresponding URIs
4.3. Happy Eyeballs for DOTS Signal Channel 4.3. Happy Eyeballs for DOTS Signal Channel
DOTS signaling can operate with DTLS over UDP and TLS over TCP. A
DOTS client can use DNS to determine the IP address(es) of a DOTS
server or a DOTS client may be provided with the list of the IP
addresses of various DOTS servers. The DOTS client MUST know a DOTS
server's domain name; hard-coding the domain name of the DOTS server
into software is NOT RECOMMENDED in case the domain name is not valid
or needs to change for legal or other reasons. The DOTS client
performs A and/or AAAA record lookup of the domain name and the
result will be a list of IP addresses, each of which can be used to
contact the DOTS server using UDP and TCP.
If an IPv4 path to reach a DOTS server is found, but the DOTS
server's IPv6 path is not working, a dual-stack DOTS client can
experience a significant connection delay compared to an IPv4-only
DOTS client. The other problem is that if a middlebox between the
DOTS client and DOTS server is configured to block UDP traffic, the
DOTS client will fail to establish a DTLS session with the DOTS
server and , as a consequence, will have to fall back to TLS over
TCP, thereby incurring significant connection delays.
[I-D.ietf-dots-requirements] mentions that DOTS agents will have to [I-D.ietf-dots-requirements] mentions that DOTS agents will have to
support both connectionless and connection-oriented protocols. support both connectionless and connection-oriented protocols. As
such, the DOTS signal channel is designed to operate with DTLS over
To overcome these connection setup problems, the DOTS client can UDP and TLS over TCP. Further, a DOTS client may acquire a list of
attempt to connect to the DOTS server using both IPv6 and IPv4, and IPv4 and IPv6 addresses (Section 4.1), each of which can be used to
try both DTLS over UDP and TLS over TCP in a manner similar to the contact the DOTS server using UDP and TCP. The following specifies
Happy Eyeballs mechanism [RFC6555]. These connection attempts are the procedure to follow to select the address family and the
performed by the DOTS client when it initializes, and the DOTS client transport protocol for sending DOTS signal channel messages.
uses the results of the Happy Eyeballs procedure for sending its
subsequent messages to the DOTS server.
In order of preference (most preferred first), it is UDP over IPv6, Such procedure is needed to avoid experiencing long connection
UDP over IPv4, TCP over IPv6, and finally TCP over IPv4, which delays. For example, if an IPv4 path to reach a DOTS server is
adheres to address preference order [RFC6724] and the DOTS found, but the DOTS server's IPv6 path is not working, a dual-stack
preference, which privileges the use of UDP over TCP (to avoid TCP's DOTS client may experience a significant connection delay compared to
head of line blocking). an IPv4-only DOTS client. The other problem is that if a middlebox
between the DOTS client and DOTS server is configured to block UDP
traffic, the DOTS client will fail to establish a DTLS session with
the DOTS server and, as a consequence, will have to fall back to TLS
over TCP, thereby incurring significant connection delays.
DOTS client DOTS server To overcome these connection setup problems, the DOTS client attempts
| | to connect to its DOTS server(s) using both IPv6 and IPv4, and tries
|--DTLS ClientHello, IPv6 ---->X | both DTLS over UDP and TLS over TCP in a manner similar to the Happy
|--TCP SYN, IPv6-------------->X | Eyeballs mechanism [RFC6555]. These connection attempts are
|--DTLS ClientHello, IPv4 ---->X | performed by the DOTS client when it initializes. The results of the
|--TCP SYN, IPv4----------------------------------------->| Happy Eyeballs procedure are used by the DOTS client for sending its
|--DTLS ClientHello, IPv6 ---->X | subsequent messages to the DOTS server.
|--TCP SYN, IPv6-------------->X |
|<-TCP SYNACK---------------------------------------------|
|--DTLS ClientHello, IPv4 ---->X |
|--TCP ACK----------------------------------------------->|
|<------------Establish TLS Session---------------------->|
|----------------DOTS signal----------------------------->|
| |
Figure 4: DOTS Happy Eyeballs The order of preference of DOTS signal channel address family and
transport protocol (most preferred first) is: UDP over IPv6, UDP over
IPv4, TCP over IPv6, and finally TCP over IPv4. This order adheres
to the address preference order specified in [RFC6724] and the DOTS
signal channel preference which privileges the use of UDP over TCP
(to avoid TCP's head of line blocking).
In reference to Figure 4, the DOTS client sends two TCP SYNs and two In reference to Figure 4, the DOTS client sends two TCP SYNs and two
DTLS ClientHello messages at the same time over IPv6 and IPv4. In DTLS ClientHello messages at the same time over IPv6 and IPv4. In
this example, it is assumed that the IPv6 path is broken and UDP is this example, it is assumed that the IPv6 path is broken and UDP
dropped by a middlebox but has little impact to the DOTS client traffic is dropped by a middlebox but has little impact to the DOTS
because there is no long delay before using IPv4 and TCP. The DOTS client because there is no long delay before using IPv4 and TCP. The
client repeats the mechanism to discover if DOTS signaling with DTLS DOTS client repeats the mechanism to discover whether DOTS signal
over UDP becomes available from the DOTS server, so the DOTS client channel messages with DTLS over UDP becomes available from the DOTS
can migrate the DOTS signal channel from TCP to UDP. But such server, so the DOTS client can migrate the DOTS signal channel from
probing SHOULD NOT be done more frequently than every 24 hours and TCP to UDP. Such probing SHOULD NOT be done more frequently than
MUST NOT be done more frequently than every 5 minutes. every 24 hours and MUST NOT be done more frequently than every 5
minutes.
+-----------+ +-----------+
|DOTS client| |DOTS server|
+-----------+ +-----------+
| |
|--DTLS ClientHello, IPv6 ---->X |
|--TCP SYN, IPv6-------------->X |
|--DTLS ClientHello, IPv4 ---->X |
|--TCP SYN, IPv4--------------------------------------->|
|--DTLS ClientHello, IPv6 ---->X |
|--TCP SYN, IPv6-------------->X |
|<-TCP SYNACK-------------------------------------------|
|--DTLS ClientHello, IPv4 ---->X |
|--TCP ACK--------------------------------------------->|
|<------------Establish TLS Session-------------------->|
|----------------DOTS signal--------------------------->|
| |
Figure 4: DOTS Happy Eyeballs
4.4. DOTS Mitigation Methods 4.4. DOTS Mitigation Methods
The following methods are used by a DOTS client to request, withdraw, The following methods are used by a DOTS client to request, withdraw,
or retrieve the status of mitigation requests: or retrieve the status of mitigation requests:
PUT: DOTS clients use the PUT method to request mitigation from a PUT: DOTS clients use the PUT method to request mitigation from a
DOTS server (Section 4.4.1). During active mitigation, DOTS DOTS server (Section 4.4.1). During active mitigation, DOTS
clients may use PUT requests to carry mitigation efficacy clients may use PUT requests to carry mitigation efficacy
updates to the DOTS server (Section 4.4.3). updates to the DOTS server (Section 4.4.3).
skipping to change at page 12, line 51 skipping to change at page 12, line 51
"lifetime": integer "lifetime": integer
} }
] ]
} }
} }
Figure 5: PUT to convey DOTS mitigation requests Figure 5: PUT to convey DOTS mitigation requests
The parameters are described below: The parameters are described below:
client-identifier: The client identifier MAY be conveyed by the DOTS client-identifier: The client identifier MAY be conveyed by a
gateway to propagate the DOTS client identity from the gateway's server-side DOTS gateway to propagate the DOTS client identity
client-side to the gateway's server-side, and from the gateway's from the gateway's client-side to the gateway's server-side, and
server-side to the DOTS server. This allows the DOTS server to from the gateway's server-side to the DOTS server. 'client-
accept mitigation requests with scopes which the DOTS client is identifier' MAY be used by the final DOTS server for policy
authorized to manage. enforcement purposes.
The 'client-identifier' value MUST be assigned by the DOTS gateway The 'client-identifier' value MUST be assigned by the server-side
in a manner that ensures that there is zero probability that the DOTS gateway in a manner that ensures that there is zero
same value will be assigned to a different DOTS client. The DOTS probability that the same value will be assigned to a different
gateway MUST conceal potentially sensitive DOTS client identity DOTS client. The server-side DOTS gateway MUST conceal
information. The client-identifier attribute SHOULD NOT be potentially sensitive DOTS client identity information.
generated and included by the DOTS client.
If aggregating DOTS mitigation requests received from multiple
DOTS clients is enabled, the server-side DOTS gateway has to
include a list of 'client-identifier' values; each value is
pointing to a unique DOTS client that is in the aggregated list.
It is out of scope of this document to specify how aggregation is
implemented by a DOTS gateway.
The client-identifier attribute MUST NOT be generated and included
by DOTS clients.
DOTS servers MUST ignore client-identifier attributes that are
directly supplied by source DOTS clients. This implies that first
server-side DOTS gateways MUST strip client-identifier attributes
supplied by DOTS clients. DOTS servers MAY support a
configuration parameter to identify DOTS gateways that are trusted
to supply client-identifier attributes.
This is an optional attribute. This is an optional attribute.
mitigation-id: Identifier for the mitigation request represented mitigation-id: Identifier for the mitigation request represented
with an integer. This identifier MUST be unique for each with an integer. This identifier MUST be unique for each
mitigation request bound to the DOTS client, i.e., the mitigation- mitigation request bound to the DOTS client, i.e., the
id parameter value in the mitigation request needs to be unique 'mitigation-id' parameter value in the mitigation request needs to
relative to the mitigation-id parameter values of active be unique relative to the 'mitigation-id' parameter values of
mitigation requests conveyed from the DOTS client to the DOTS active mitigation requests conveyed from the DOTS client to the
server. This identifier MUST be generated by the DOTS client. DOTS server. This identifier MUST be generated by the DOTS
This document does not make any assumption about how this client. This document does not make any assumption about how this
identifier is generated. identifier is generated.
This is a mandatory attribute. This is a mandatory attribute.
target-prefix: A list of prefixes identifying resources under target-prefix: A list of prefixes identifying resources under
attack. Prefixes are represented using Classless Inter-Domain attack. Prefixes are represented using Classless Inter-Domain
Routing (CIDR) notation [RFC4632]. Routing (CIDR) notation [RFC4632].
As a reminder, the prefix length must be less than or equal to 32 As a reminder, the prefix length must be less than or equal to 32
(resp. 128) for IPv4 (resp. IPv6). (resp. 128) for IPv4 (resp. IPv6).
skipping to change at page 14, line 5 skipping to change at page 14, line 22
'lower-port' is present, it represents a single port number. For 'lower-port' is present, it represents a single port number. For
TCP, UDP, Stream Control Transmission Protocol (SCTP) [RFC4960], TCP, UDP, Stream Control Transmission Protocol (SCTP) [RFC4960],
or Datagram Congestion Control Protocol (DCCP) [RFC4340], the or Datagram Congestion Control Protocol (DCCP) [RFC4340], the
range of ports can be, for example, 1024-65535. range of ports can be, for example, 1024-65535.
This is an optional attribute. This is an optional attribute.
target-protocol: A list of protocols involved in an attack. Values target-protocol: A list of protocols involved in an attack. Values
are taken from the IANA protocol registry [proto_numbers]. are taken from the IANA protocol registry [proto_numbers].
The value 0 has a special meaning for 'all protocols'. The value '0' has a special meaning for 'all protocols'.
This is an optional attribute. This is an optional attribute.
target-fqdn: A list of Fully Qualified Domain Names (FQDNs) target-fqdn: A list of Fully Qualified Domain Names (FQDNs)
identifying resources under attack. An FQDN is the full name of a identifying resources under attack. An FQDN is the full name of a
resource, rather than just its hostname. For example, "venera" is resource, rather than just its hostname. For example, "venera" is
a hostname, and "venera.isi.edu" is an FQDN. a hostname, and "venera.isi.edu" is an FQDN.
This is an optional attribute. This is an optional attribute.
skipping to change at page 15, line 19 skipping to change at page 15, line 36
The CBOR key values for the parameters are defined in Section 6. The CBOR key values for the parameters are defined in Section 6.
Section 9 defines how the CBOR key values can be allocated to Section 9 defines how the CBOR key values can be allocated to
standard bodies and vendors. standard bodies and vendors.
FQDN and URI mitigation scopes may be thought of as a form of scope FQDN and URI mitigation scopes may be thought of as a form of scope
alias, in which the addresses to which the domain name or URI resolve alias, in which the addresses to which the domain name or URI resolve
represent the full scope of the mitigation. represent the full scope of the mitigation.
In the PUT request at least one of the attributes 'target-prefix' or In the PUT request at least one of the attributes 'target-prefix' or
'target-fqdn' or 'target-uri 'or 'alias-name' MUST be present. If 'target-fqdn' or 'target-uri 'or 'alias-name' MUST be present.
the attribute value is empty, then the attribute MUST NOT be present Attributes with emty values MUST NOT be present in a request.
in the request.
The relative order of two mitigation requests from a DOTS client is The relative order of two mitigation requests from a DOTS client is
determined by comparing their respective 'mitigation-id' values. If determined by comparing their respective 'mitigation-id' values. If
two mitigation requests have overlapping mitigation scopes, the two mitigation requests have overlapping mitigation scopes, the
mitigation request with the highest numeric 'mitigation-id' value mitigation request with the highest numeric 'mitigation-id' value
will override the other mitigation request. Two mitigation-ids from will override the other mitigation request. Two mitigation-ids from
a DOTS client are overlapping if there is a common IP address, IP a DOTS client are overlapping if there is a common IP address, IP
prefix, FQDN, URI, or alias-name. To avoid maintaining a long list prefix, FQDN, URI, or alias-name. To avoid maintaining a long list
of overlapping mitigation requests from a DOTS client and avoid of overlapping mitigation requests from a DOTS client and avoid
error-prone provisioning of mitigation requests from a DOTS client, error-prone provisioning of mitigation requests from a DOTS client,
skipping to change at page 17, line 51 skipping to change at page 18, line 5
Enrollment over Secure Transport (EST) server [RFC7030] in the DOTS Enrollment over Secure Transport (EST) server [RFC7030] in the DOTS
gateway-domain to authenticate itself to the DOTS gateway, then the gateway-domain to authenticate itself to the DOTS gateway, then the
'client-identifier' value can be the output of a cryptographic hash 'client-identifier' value can be the output of a cryptographic hash
algorithm whose input is the DER-encoded ASN.1 representation of the algorithm whose input is the DER-encoded ASN.1 representation of the
Subject Public Key Info (SPKI) of an X.509 certificate. Subject Public Key Info (SPKI) of an X.509 certificate.
In this version of the specification, the cryptographic hash In this version of the specification, the cryptographic hash
algorithm used is SHA-256 [RFC6234]. The output of the cryptographic algorithm used is SHA-256 [RFC6234]. The output of the cryptographic
hash algorithm is truncated to 16 bytes; truncation is done by hash algorithm is truncated to 16 bytes; truncation is done by
stripping off the final 16 bytes. The truncated output is base64url stripping off the final 16 bytes. The truncated output is base64url
encoded. If the 'client-identifier' value is already present in the encoded.
mitigation request received from the DOTS client, the DOTS gateway
MAY compute the 'client-identifier' value, as discussed above, and
add the computed 'client-identifier' value to the end of the 'client-
identifier' list. The DOTS server MUST NOT use the 'client-
identifier' for the DOTS client authentication process.
In both DOTS signal and data channel sessions, the DOTS client MUST In both DOTS signal and data channel sessions, the DOTS client MUST
authenticate itself to the DOTS server (Section 8). The DOTS server authenticate itself to the DOTS server (Section 8). The DOTS server
may use the algorithm presented in Section 7 of [RFC7589] to derive may use the algorithm presented in Section 7 of [RFC7589] to derive
the DOTS client identity or username from the client certificate. the DOTS client identity or username from the client certificate.
The DOTS client identity allows the DOTS server to accept mitigation The DOTS client identity allows the DOTS server to accept mitigation
requests with scopes that the DOTS client is authorized to manage. requests with scopes that the DOTS client is authorized to manage.
The DOTS server couples the DOTS signal and data channel sessions The DOTS server couples the DOTS signal and data channel sessions
using the DOTS client identity and the 'client-identifier' parameter using the DOTS client identity and the 'client-identifier' parameter
value, so the DOTS server can validate whether the aliases conveyed value, so the DOTS server can validate whether the aliases conveyed
skipping to change at page 19, line 23 skipping to change at page 19, line 23
"lifetime": 3600 "lifetime": 3600
} }
] ]
} }
} }
Figure 8: 2.xx response body Figure 8: 2.xx response body
If the request is missing one or more mandatory attributes, or If the request is missing one or more mandatory attributes, or
includes multiple 'scope' parameters, or contains invalid or unknown includes multiple 'scope' parameters, or contains invalid or unknown
parameters, the DOTS server replies with 4.00 (Bad Request). DOTS parameters, the DOTS server MUST reply with 4.00 (Bad Request). DOTS
agents can safely ignore Vendor-Specific parameters they don't agents can safely ignore Vendor-Specific parameters they don't
understand. understand.
A DOTS server that receives a mitigation request with a lifetime set A DOTS server that receives a mitigation request with a lifetime set
to '0' MUST reply with a 4.00 (Bad Request). to '0' MUST reply with a 4.00 (Bad Request).
If the DOTS server does not find the 'mitigation-id' parameter value If the DOTS server does not find the 'mitigation-id' parameter value
conveyed in the PUT request in its configuration data, it MAY accept conveyed in the PUT request in its configuration data, it MAY accept
the mitigation request by sending back a 2.01 (Created) response to the mitigation request by sending back a 2.01 (Created) response to
the DOTS client; the DOTS server will consequently try to mitigate the DOTS client; the DOTS server will consequently try to mitigate
skipping to change at page 20, line 7 skipping to change at page 20, line 7
of the conflict (refer to 'conflict-information' specified in of the conflict (refer to 'conflict-information' specified in
Section 4.4.2). Section 4.4.2).
For a mitigation request to continue beyond the initial negotiated For a mitigation request to continue beyond the initial negotiated
lifetime, the DOTS client has to refresh the current mitigation lifetime, the DOTS client has to refresh the current mitigation
request by sending a new PUT request. This PUT request MUST use the request by sending a new PUT request. This PUT request MUST use the
same 'mitigation-id' value, and MUST repeat all the other parameters same 'mitigation-id' value, and MUST repeat all the other parameters
as sent in the original mitigation request apart from a possible as sent in the original mitigation request apart from a possible
change to the lifetime parameter value. change to the lifetime parameter value.
A DOTS gateway MUST update the 'client-identifier' list in the The DOTS gateway, which inserted a 'client-identifier' attribute in a
response to remove the 'client-identifier' value it had added in the request, MUST strip the 'client-identifier' parameter in the
corresponding request before forwarding the response to the DOTS corresponding response before forwarding the response to the DOTS
client. client.
4.4.2. Retrieve Information Related to a Mitigation 4.4.2. Retrieve Information Related to a Mitigation
A GET request is used by a DOTS client to retrieve information A GET request is used by a DOTS client to retrieve information
(including status) of DOTS mitigations from a DOTS server. (including status) of DOTS mitigations from a DOTS server.
The same considerations for manipulating 'client-identifier' The same considerations for manipulating 'client-identifier'
parameter by a DOTS gateway specified in Section 4.4.1 MUST be parameter by a DOTS gateway specified in Section 4.4.1 MUST be
followed for GET requests. followed for GET requests.
skipping to change at page 25, line 47 skipping to change at page 25, line 47
on a CoAP server: The client retrieves a representation of the on a CoAP server: The client retrieves a representation of the
resource and requests this representation be updated by the server as resource and requests this representation be updated by the server as
long as the client is interested in the resource. A DOTS client long as the client is interested in the resource. A DOTS client
conveys the observe option set to '0' in the GET request to receive conveys the observe option set to '0' in the GET request to receive
unsolicited notifications of attack mitigation status from the DOTS unsolicited notifications of attack mitigation status from the DOTS
server. server.
Unidirectional notifications within the bidirectional signal channel Unidirectional notifications within the bidirectional signal channel
allows unsolicited message delivery, enabling asynchronous allows unsolicited message delivery, enabling asynchronous
notifications between the agents. Due to the higher likelihood of notifications between the agents. Due to the higher likelihood of
packet loss during a DDoS attack, DOTS server periodically sends packet loss during a DDoS attack, the DOTS server periodically sends
attack mitigation status to the DOTS client and also notifies the attack mitigation status to the DOTS client and also notifies the
DOTS client whenever the status of the attack mitigation changes. If DOTS client whenever the status of the attack mitigation changes. If
the DOTS server cannot maintain a RTT estimate, it SHOULD NOT send the DOTS server cannot maintain a RTT estimate, it SHOULD NOT send
more than one unsolicited notification every 3 seconds, and SHOULD more than one unsolicited notification every 3 seconds, and SHOULD
use an even less aggressive rate whenever possible (case 2 in use an even less aggressive rate whenever possible (case 2 in
Section 3.1.3 of [RFC8085]). Section 3.1.3 of [RFC8085]).
When conflicting requests are detected, the DOTS server enforces the When conflicting requests are detected, the DOTS server enforces the
corresponding policy (e.g., accept all requests, reject all requests, corresponding policy (e.g., accept all requests, reject all requests,
accept only one request but reject all the others, ...). It is accept only one request but reject all the others, ...). It is
skipping to change at page 28, line 13 skipping to change at page 28, line 13
averted. averted.
4.4.3. Efficacy Update from DOTS Clients 4.4.3. Efficacy Update from DOTS Clients
While DDoS mitigation is active, due to the likelihood of packet While DDoS mitigation is active, due to the likelihood of packet
loss, a DOTS client MAY periodically transmit DOTS mitigation loss, a DOTS client MAY periodically transmit DOTS mitigation
efficacy updates to the relevant DOTS server. A PUT request is used efficacy updates to the relevant DOTS server. A PUT request is used
to convey the mitigation efficacy update to the DOTS server. to convey the mitigation efficacy update to the DOTS server.
The PUT request MUST include all the parameters used in the PUT The PUT request MUST include all the parameters used in the PUT
request to carry the DOTS signal (Section 4.4.1) unchanged apart from request to carry the DOTS mitigation request (Section 4.4.1)
the lifetime parameter value. If this is not the case, the DOTS unchanged apart from the lifetime parameter value. If this is not
server MUST reject the request with a 4.00 (Bad Request). the case, the DOTS server MUST reject the request with a 4.00 (Bad
Request).
The If-Match Option (Section 5.10.8.1 of [RFC7252]) with an empty The If-Match Option (Section 5.10.8.1 of [RFC7252]) with an empty
value is used to make the PUT request conditional on the current value is used to make the PUT request conditional on the current
existence of the mitigation request. If UDP is used as transport, existence of the mitigation request. If UDP is used as transport,
CoAP requests may arrive out-of-order. For example, the DOTS client CoAP requests may arrive out-of-order. For example, the DOTS client
may send a PUT request to convey an efficacy update to the DOTS may send a PUT request to convey an efficacy update to the DOTS
server followed by a DELETE request to withdraw the mitigation server followed by a DELETE request to withdraw the mitigation
request, but the DELETE request arrives at the DOTS server before the request, but the DELETE request arrives at the DOTS server before the
PUT request. To handle out-of-order delivery of requests, if an If- PUT request. To handle out-of-order delivery of requests, if an If-
Match option is present in the PUT request and the 'mitigation-id' in Match option is present in the PUT request and the 'mitigation-id' in
skipping to change at page 32, line 15 skipping to change at page 32, line 15
seconds (5 minutes). seconds (5 minutes).
After the active-but-terminating period elapses, the DOTS server MUST After the active-but-terminating period elapses, the DOTS server MUST
treat the mitigation as terminated, as the DOTS client is no longer treat the mitigation as terminated, as the DOTS client is no longer
responsible for the mitigation. For example, if there is a financial responsible for the mitigation. For example, if there is a financial
relationship between the DOTS client and server domains, the DOTS relationship between the DOTS client and server domains, the DOTS
client stops incurring cost at this point. client stops incurring cost at this point.
4.5. DOTS Signal Channel Session Configuration 4.5. DOTS Signal Channel Session Configuration
The DOTS client can negotiate, configure, and retrieve the DOTS A DOTS client can negotiate, configure, and retrieve the DOTS signal
signal channel session behavior. The DOTS signal channel can be channel session behavior. The DOTS signal channel can be used, for
used, for example, to configure the following: example, to configure the following:
a. Heartbeat interval (heartbeat-interval): DOTS agents regularly a. Heartbeat interval (heartbeat-interval): DOTS agents regularly
send heartbeats (CoAP Ping/Pong) to each other after mutual send heartbeats (CoAP Ping/Pong) to each other after mutual
authentication is successfully completed in order to keep the authentication is successfully completed in order to keep the
DOTS signal channel open. Heartbeat messages are exchanged DOTS signal channel open. Heartbeat messages are exchanged
between the DOTS agents every 'heartbeat-interval' seconds to between DOTS agents every 'heartbeat-interval' seconds to detect
detect the current status of the DOTS signal channel session. the current status of the DOTS signal channel session.
b. Missing heartbeats allowed (missing-hb-allowed): This variable b. Missing heartbeats allowed (missing-hb-allowed): This variable
indicates the maximum number of consecutive heartbeat messages indicates the maximum number of consecutive heartbeat messages
for which a DOTS agent did not receive a response before for which a DOTS agent did not receive a response before
concluding that the session is disconnected or defunct. concluding that the session is disconnected or defunct.
c. Acceptable signal loss ratio: Maximum retransmissions, c. Acceptable signal loss ratio: Maximum retransmissions,
retransmission timeout value, and other message transmission retransmission timeout value, and other message transmission
parameters for the DOTS signal channel. parameters for the DOTS signal channel.
The same or distinct configuration sets may be used during attack
('attack-time-config') and peace times ('peace-time-config'). This
is particularly useful for DOTS servers that might want to reduce
heartbeat frequency or cease heartbeat exchanges when an active DOTS
client has not requested mitigation. If distinct configuration are
used, DOTS agents MUST follow the appropriate configuration set as a
function of the mitigation activity (e.g., if no mitigation request
is active, 'peace-time-config'-related values must be followed).
Additionally, DOTS agents MUST automatically switch to the other
configuration upon a change in the mitigation activity (e.g., if an
attack mitigation is launched after a peacetime, the DOTS agent
switches from 'peace-time-config' to 'attack-time-config'-related
values).
Requests and responses are deemed reliable by marking them as Requests and responses are deemed reliable by marking them as
Confirmable (CON) messages. DOTS signal channel session Confirmable (CON) messages. DOTS signal channel session
configuration requests and responses are marked as Confirmable configuration requests and responses are marked as Confirmable
messages. As explained in Section 2.1 of [RFC7252], a Confirmable messages. As explained in Section 2.1 of [RFC7252], a Confirmable
message is retransmitted using a default timeout and exponential message is retransmitted using a default timeout and exponential
back-off between retransmissions, until the DOTS server sends an back-off between retransmissions, until the DOTS server sends an
Acknowledgement message (ACK) with the same Message ID conveyed from Acknowledgement message (ACK) with the same Message ID conveyed from
the DOTS client. the DOTS client.
Message transmission parameters are defined in Section 4.8 of Message transmission parameters are defined in Section 4.8 of
skipping to change at page 33, line 22 skipping to change at page 33, line 36
that would help it correlate this response, thereby unexpecting that would help it correlate this response, thereby unexpecting
the retransmission message. The DOTS client will send a Reset the retransmission message. The DOTS client will send a Reset
message so it does not receive any more retransmissions. This message so it does not receive any more retransmissions. This
behavior is normal and not an indication of an error (see behavior is normal and not an indication of an error (see
Section 5.3.2 of [RFC7252] for more details). Section 5.3.2 of [RFC7252] for more details).
4.5.1. Discover Configuration Parameters 4.5.1. Discover Configuration Parameters
A GET request is used to obtain acceptable (e.g., minimum and maximum A GET request is used to obtain acceptable (e.g., minimum and maximum
values) and current configuration parameters on the DOTS server for values) and current configuration parameters on the DOTS server for
DOTS signal channel session configuration. Figure 15 shows how to DOTS signal channel session configuration.
obtain acceptable configuration parameters for the DOTS server.
Figure 15 shows how to obtain acceptable configuration parameters for
the DOTS server.
Header: GET (Code=0.01) Header: GET (Code=0.01)
Uri-Host: "host" Uri-Host: "host"
Uri-Path: ".well-known" Uri-Path: ".well-known"
Uri-Path: "dots" Uri-Path: "dots"
Uri-Path: "version" Uri-Path: "version"
Uri-Path: "config" Uri-Path: "config"
Figure 15: GET to retrieve configuration Figure 15: GET to retrieve configuration
The DOTS server in the 2.05 (Content) response conveys the current, The DOTS server in the 2.05 (Content) response conveys the current,
minimum, and maximum attribute values acceptable by the DOTS server minimum, and maximum attribute values acceptable by the DOTS server
(Figure 16). (Figure 16).
Content-Format: "application/cbor" Content-Format: "application/cbor"
{ {
"heartbeat-interval": { "attack-time-config": {
"current-value": integer, "heartbeat-interval": {
"min-value": integer, "current-value": integer,
"max-value": integer "min-value": integer,
}, "max-value": integer
"missing-hb-allowed": { },
"current-value": integer, "missing-hb-allowed": {
"min-value": integer, "current-value": integer,
"max-value": integer "min-value": integer,
}, "max-value": integer
"max-retransmit": { },
"current-value": integer, "max-retransmit": {
"min-value": integer, "current-value": integer,
"max-value": integer "min-value": integer,
}, "max-value": integer
"ack-timeout": { },
"current-value": integer, "ack-timeout": {
"min-value": integer, "current-value": integer,
"max-value": integer "min-value": integer,
}, "max-value": integer
"ack-random-factor": { },
"current-value": number, "ack-random-factor": {
"min-value": number, "current-value": number,
"max-value": number "min-value": number,
}, "max-value": number
"trigger-mitigation": { }
"current-value": boolean },
}, "peace-time-config": {
"config-interval": { "heartbeat-interval": {
"current-value": integer, "current-value": integer,
"min-value": integer, "min-value": integer,
"max-value": integer "max-value": integer
} },
"missing-hb-allowed": {
"current-value": integer,
"min-value": integer,
"max-value": integer
},
"max-retransmit": {
"current-value": integer,
"min-value": integer,
"max-value": integer
},
"ack-timeout": {
"current-value": integer,
"min-value": integer,
"max-value": integer
},
"ack-random-factor": {
"current-value": number,
"min-value": number,
"max-value": number
}
},
"trigger-mitigation": {
"current-value": boolean
},
"config-interval": {
"current-value": integer,
"min-value": integer,
"max-value": integer
} }
}
Figure 16: GET response body Figure 16: GET response body
Figure 17 shows an example of acceptable and current configuration Figure 17 shows an example of acceptable and current configuration
parameters on a DOTS server for DOTS signal channel session parameters on a DOTS server for DOTS signal channel session
configuration. configuration. The same acceptable configuration is used during
attack and peace times.
Content-Format: "application/cbor" Content-Format: "application/cbor"
{ {
"heartbeat-interval": { "attack-time-config": {
"current-value": 30, "heartbeat-interval": {
"min-value": 15, "current-value": 30,
"max-value": 240 "min-value": 15,
}, "max-value": 240
"missing-hb-allowed": { },
"current-value": 5, "missing-hb-allowed": {
"min-value": 3, "current-value": 5,
"max-value": 9 "min-value": 3,
}, "max-value": 9
"max-retransmit": { },
"current-value": 3, "max-retransmit": {
"min-value": 2, "current-value": 3,
"max-value": 15 "min-value": 2,
}, "max-value": 15
"ack-timeout": { },
"current-value": 2, "ack-timeout": {
"min-value": 1, "current-value": 2,
"max-value": 30 "min-value": 1,
}, "max-value": 30
"ack-random-factor": { },
"current-value": 1.5, "ack-random-factor": {
"min-value": 1.1, "current-value": 1.5,
"max-value": 4.0 "min-value": 1.1,
}, "max-value": 4.0
"trigger-mitigation": { }
"current-value": true },
}, "peace-time-config": {
"config-interval": { "heartbeat-interval": {
"current-value": 1439, "current-value": 30,
"min-value": 0, "min-value": 15,
"max-value": 65535 "max-value": 240
} },
"missing-hb-allowed": {
"current-value": 5,
"min-value": 3,
"max-value": 9
},
"max-retransmit": {
"current-value": 3,
"min-value": 2,
"max-value": 15
},
"ack-timeout": {
"current-value": 2,
"min-value": 1,
"max-value": 30
},
"ack-random-factor": {
"current-value": 1.5,
"min-value": 1.1,
"max-value": 4.0
}
},
"trigger-mitigation": {
"current-value": true
},
"config-interval": {
"current-value": 1439,
"min-value": 0,
"max-value": 65535
}
} }
Figure 17: Configuration response body Figure 17: Configuration response body
4.5.2. Convey DOTS Signal Channel Session Configuration 4.5.2. Convey DOTS Signal Channel Session Configuration
A PUT request is used to convey the configuration parameters for the A PUT request is used to convey the configuration parameters for the
signal channel (e.g., heartbeat interval, maximum retransmissions). signal channel (e.g., heartbeat interval, maximum retransmissions).
Message transmission parameters for CoAP are defined in Section 4.8 Message transmission parameters for CoAP are defined in Section 4.8
of [RFC7252]. The RECOMMENDED values of transmission parameter of [RFC7252]. The RECOMMENDED values of transmission parameter
values are ack-timeout (2 seconds), max-retransmit (3), ack-random- values are ack-timeout (2 seconds), max-retransmit (3), ack-random-
factor (1.5). In addition to those parameters, the RECOMMENDED factor (1.5). In addition to those parameters, the RECOMMENDED
specific DOTS transmission parameter values are heartbeat-interval specific DOTS transmission parameter values are 'heartbeat-interval'
(30 seconds) and missing-hb-allowed (5). (30 seconds) and 'missing-hb-allowed' (5).
Note: heartbeat-interval should be tweaked to also assist DOTS Note: heartbeat-interval should be tweaked to also assist DOTS
messages for NAT traversal (SIG-010 of messages for NAT traversal (SIG-010 of
[I-D.ietf-dots-requirements]). According to [RFC8085], keepalive [I-D.ietf-dots-requirements]). According to [RFC8085], keepalive
messages must not be sent more frequently than once every 15 messages must not be sent more frequently than once every 15
seconds and should use longer intervals when possible. seconds and should use longer intervals when possible.
Furthermore, [RFC4787] recommends NATs to use a state timeout of 2 Furthermore, [RFC4787] recommends NATs to use a state timeout of 2
minutes or longer, but experience shows that sending packets every minutes or longer, but experience shows that sending packets every
15 to 30 seconds is necessary to prevent the majority of 15 to 30 seconds is necessary to prevent the majority of
middleboxes from losing state for UDP flows. From that middleboxes from losing state for UDP flows. From that
skipping to change at page 37, line 13 skipping to change at page 38, line 16
DOTS signal channel session between the DOTS agents. DOTS signal channel session between the DOTS agents.
Header: PUT (Code=0.03) Header: PUT (Code=0.03)
Uri-Host: "host" Uri-Host: "host"
Uri-Path: ".well-known" Uri-Path: ".well-known"
Uri-Path: "dots" Uri-Path: "dots"
Uri-Path: "version" Uri-Path: "version"
Uri-Path: "config" Uri-Path: "config"
Content-Format: "application/cbor" Content-Format: "application/cbor"
{ {
"signal-config": { "signal-config": {
"session-id": integer, "session-id": integer,
"heartbeat-interval": integer, "attack-time-config": {
"missing-hb-allowed": integer, "heartbeat-interval": {
"max-retransmit": integer, "current-value": integer
"ack-timeout": integer, },
"ack-random-factor": number, "missing-hb-allowed": {
"trigger-mitigation": boolean, "current-value": integer
"config-interval": integer },
} "max-retransmit": {
"current-value": integer
},
"ack-timeout": {
"current-value": integer
},
"ack-random-factor": {
"current-value": number
}
},
"peace-time-config": {
"heartbeat-interval": {
"current-value": integer
},
"missing-hb-allowed": {
"current-value": integer
},
"max-retransmit": {
"current-value": integer
},
"ack-timeout": {
"current-value": integer
},
"ack-random-factor": {
"current-value": number
}
},
"trigger-mitigation": boolean,
"config-interval": integer
}
} }
Figure 18: PUT to convey the DOTS signal channel session Figure 18: PUT to convey the DOTS signal channel session
configuration data. configuration data.
The parameters in Figure 18 are described below: The parameters in Figure 18 are described below:
session-id: Identifier for the DOTS signal channel session session-id: Identifier for the DOTS signal channel session
configuration data represented as an integer. This identifier configuration data represented as an integer. This identifier
MUST be generated by the DOTS client. This document does not make MUST be generated by the DOTS client. This document does not make
any assumption about how this identifier is generated. any assumption about how this identifier is generated.
This is a mandatory attribute. This is a mandatory attribute.
heartbeat-interval: Time interval in seconds between two attack-time-config: Set of configuration parameters to use when an
consecutive heartbeat messages. attack is active. The following parameters may be included:
'0' is used to disable the heartbeat mechanism. heartbeat-interval: Time interval in seconds between two
consecutive heartbeat messages.
This is an optional attribute. '0' is used to disable the heartbeat mechanism.
missing-hb-allowed: Maximum number of consecutive heartbeat This is an optional attribute.
messages for which the DOTS agent did not receive a response
before concluding that the session is disconnected.
This is an optional attribute. missing-hb-allowed: Maximum number of consecutive heartbeat
messages for which the DOTS agent did not receive a response
before concluding that the session is disconnected.
max-retransmit: Maximum number of retransmissions for a message This is an optional attribute.
(referred to as MAX_RETRANSMIT parameter in CoAP).
This is an optional attribute. max-retransmit: Maximum number of retransmissions for a message
(referred to as MAX_RETRANSMIT parameter in CoAP).
ack-timeout: Timeout value in seconds used to calculate the initial This is an optional attribute.
retransmission timeout value (referred to as ACK_TIMEOUT parameter
in CoAP).
This is an optional attribute. ack-timeout: Timeout value in seconds used to calculate the
initial retransmission timeout value (referred to as
ACK_TIMEOUT parameter in CoAP).
ack-random-factor: Random factor used to influence the timing of This is an optional attribute.
retransmissions (referred to as ACK_RANDOM_FACTOR parameter in
CoAP).
This is an optional attribute. ack-random-factor: Random factor used to influence the timing of
retransmissions (referred to as ACK_RANDOM_FACTOR parameter in
CoAP).
This is an optional attribute.
peace-time-config: Set of configuration parameters to use during
peacetime. This attribute has the same structure as 'attack-time-
config'.
trigger-mitigation: If the parameter value is set to 'false', then trigger-mitigation: If the parameter value is set to 'false', then
DDoS mitigation is triggered only when the DOTS signal channel DDoS mitigation is triggered only when the DOTS signal channel
session is lost. Automated mitigation on loss of signal is session is lost. Automated mitigation on loss of signal is
discussed in Section 3.3.3 of [I-D.ietf-dots-architecture]. discussed in Section 3.3.3 of [I-D.ietf-dots-architecture].
If the DOTS client ceases to respond to heartbeat messages, the If the DOTS client ceases to respond to heartbeat messages, the
DOTS server can detect that the DOTS session is lost. DOTS server can detect that the DOTS session is lost.
The default value of the parameter is 'true'. The default value of the parameter is 'true'.
skipping to change at page 38, line 41 skipping to change at page 40, line 31
config-interval: This parameter is returned to indicate the time config-interval: This parameter is returned to indicate the time
interval expressed in minutes, which a DOTS agent must wait for interval expressed in minutes, which a DOTS agent must wait for
before re-contacting its peer in order to retrieve the signal before re-contacting its peer in order to retrieve the signal
channel configuration data. channel configuration data.
'0' is used to disable this refresh mechanism. '0' is used to disable this refresh mechanism.
If a non-null value of 'config-interval' is received by a DOTS If a non-null value of 'config-interval' is received by a DOTS
agent, it has to issue a PUT request to refresh the configuration agent, it has to issue a PUT request to refresh the configuration
parameters for the signal channel before the expiry of 'config- parameters for the signal channel before the expiry of 'config-
interval'. interval'. When a DDoS attack is active, refresh requests MUST
NOT be sent by DOTS clients and the DOTS server MUST NOT terminate
the (D)TLS session after the expiry of 'config-interval'.
This mechanism allows to update the configuration data if a change This mechanism allows to update the configuration data if a change
occurs at the DOTS server side. For example, the new occurs at the DOTS server side. For example, the new
configuration may instruct a DOTS client to cease heartbeats or configuration may instruct a DOTS client to cease heartbeats or
reduce heartbeat frequency. reduce heartbeat frequency.
If this parameter is not returned, this is equivalent to receiving If this parameter is not returned, this is equivalent to receiving
a 'config-interval' value set to '0'. a 'config-interval' value set to '0'.
If a DOTS server detects that a misbehaving DOTS client does not If a DOTS server detects that a misbehaving DOTS client does not
contact the DOTS server after the expiry of 'config-interval', in contact the DOTS server after the expiry of 'config-interval', in
order to retrieve the signal channel configuration data, it MAY order to retrieve the signal channel configuration data, it MAY
terminate the (D)TLS session. A (D)TLS session is terminated by terminate the (D)TLS session. A (D)TLS session is terminated by
the receipt of an authenticated message that closes the connection the receipt of an authenticated message that closes the connection
(e.g., a fatal alert (Section 7.2 of [RFC5246])). (e.g., a fatal alert (Section 7.2 of [RFC5246])).
This is an optional attribute. This is an optional attribute.
At least one of the attributes 'heartbeat-interval', 'missing-hb- At least one of the attributes 'heartbeat-interval', 'missing-hb-
allowed', 'max-retransmit', 'ack-timeout', 'ack-random-factor', and allowed', 'max-retransmit', 'ack-timeout', 'ack-random-factor', and
'trigger-mitigation' MUST be present in the PUT request . The PUT 'trigger-mitigation' MUST be present in the PUT request. The PUT
request with a higher numeric 'session-id' value overrides the DOTS request with a higher numeric 'session-id' value overrides the DOTS
signal channel session configuration data installed by a PUT request signal channel session configuration data installed by a PUT request
with a lower numeric 'session-id' value. with a lower numeric 'session-id' value.
Figure 19 shows a PUT request example to convey the configuration Figure 19 shows a PUT request example to convey the configuration
parameters for the DOTS signal channel. parameters for the DOTS signal channel. In this example, heartbeat
mechanism is disabled during peacetime, while the heartbeat interval
is set to '91' when an attack is active.
Header: PUT (Code=0.03) Header: PUT (Code=0.03)
Uri-Host: "www.example.com" Uri-Host: "www.example.com"
Uri-Path: ".well-known" Uri-Path: ".well-known"
Uri-Path: "dots" Uri-Path: "dots"
Uri-Path: "v1" Uri-Path: "v1"
Uri-Path: "config" Uri-Path: "config"
Content-Format: "application/cbor" Content-Format: "application/cbor"
{ {
"signal-config": { "signal-config": {
"session-id": 1234534333242, "session-id": 1234534333242,
"heartbeat-interval": 91, "attack-time-config": {
"missing-hb-allowed": 3, "heartbeat-interval": {
"max-retransmit": 7, "current-value": 91
"ack-timeout": 5, },
"ack-random-factor": 1.5, "missing-hb-allowed": {
"trigger-mitigation": false "current-value": 3
},
"max-retransmit": {
"current-value": 7
},
"ack-timeout": {
"current-value": 5
},
"ack-random-factor": {
"current-value": 1.5
}
},
"peace-time-config": {
"heartbeat-interval": {
"current-value": 0
},
"max-retransmit": {
"current-value": 7
},
"ack-timeout": {
"current-value": 5
},
"ack-random-factor": {
"current-value": 1.5
}
},
"trigger-mitigation": false
} }
} }
Figure 19: PUT to convey the configuration parameters Figure 19: PUT to convey the configuration parameters
The DOTS server indicates the result of processing the PUT request The DOTS server indicates the result of processing the PUT request
using CoAP response codes: using CoAP response codes:
o If the DOTS server finds the 'session-id' parameter value conveyed o If the DOTS server finds the 'session-id' parameter value conveyed
in the PUT request in its configuration data and if the DOTS in the PUT request in its configuration data and if the DOTS
server has accepted the updated configuration parameters, then server has accepted the updated configuration parameters, then
2.04 (Changed) code is returned in the response. 2.04 (Changed) code is returned in the response.
o If the DOTS server does not find the 'session-id' parameter value o If the DOTS server does not find the 'session-id' parameter value
conveyed in the PUT request in its configuration data and if the conveyed in the PUT request in its configuration data and if the
DOTS server has accepted the configuration parameters, then a DOTS server has accepted the configuration parameters, then a
response code 2.01 (Created) is returned in the response. response code 2.01 (Created) is returned in the response.
o If the request is missing one or more mandatory attributes or it o If the request is missing one or more mandatory attributes or it
contains one or more invalid or unknown parameters, then 4.00 (Bad contains one or more invalid or unknown parameters, 4.00 (Bad
Request) is returned in the response. Request) is returned in the response.
o Response code 4.22 (Unprocessable Entity) is returned in the o Response code 4.22 (Unprocessable Entity) is returned in the
response, if any of the 'heartbeat-interval', 'missing-hb- response, if any of the 'heartbeat-interval', 'missing-hb-
allowed', 'max-retransmit', 'target-protocol', 'ack-timeout', and allowed', 'max-retransmit', 'target-protocol', 'ack-timeout', and
'ack-random-factor' attribute values are not acceptable to the 'ack-random-factor' attribute values are not acceptable to the
DOTS server. Upon receipt of the 4.22 error response code, the DOTS server. Upon receipt of the 4.22 error response code, the
DOTS client should request the maximum and minimum attribute DOTS client should request the maximum and minimum attribute
values acceptable to the DOTS server (Section 4.5.1). values acceptable to the DOTS server (Section 4.5.1).
skipping to change at page 42, line 28 skipping to change at page 45, line 44
To provide an indication of signal health and distinguish an 'idle' To provide an indication of signal health and distinguish an 'idle'
signal channel from a 'disconnected' or 'defunct' session, the DOTS signal channel from a 'disconnected' or 'defunct' session, the DOTS
agent sends a heartbeat over the signal channel to maintain its half agent sends a heartbeat over the signal channel to maintain its half
of the channel. The DOTS agent similarly expects a heartbeat from of the channel. The DOTS agent similarly expects a heartbeat from
its peer DOTS agent, and may consider a session terminated in the its peer DOTS agent, and may consider a session terminated in the
prolonged absence of a peer agent heartbeat. prolonged absence of a peer agent heartbeat.
While the communication between the DOTS agents is quiescent, the While the communication between the DOTS agents is quiescent, the
DOTS client will probe the DOTS server to ensure it has maintained DOTS client will probe the DOTS server to ensure it has maintained
cryptographic state and vice versa. Such probes can also keep cryptographic state and vice versa. Such probes can also keep
firewall and/or NAT bindings alive. This probing reduces the firewalls and/or stateful translators bindings alive. This probing
frequency of establishing a new handshake when a DOTS signal needs to reduces the frequency of establishing a new handshake when a DOTS
be conveyed to the DOTS server. signal needs to be conveyed to the DOTS server.
In order to avoid complications due to the presence of some stateful
translators and firewalls (e.g., discard an incoming packet because
no matching state is found), DOTS servers MAY trigger their heartbeat
requests immediately after receiving heartbeat probes from peer DOTS
clients.
In case of a massive DDoS attack that saturates the incoming link(s) In case of a massive DDoS attack that saturates the incoming link(s)
to the DOTS client, all traffic from the DOTS server to the DOTS to the DOTS client, all traffic from the DOTS server to the DOTS
client will likely be dropped, although the DOTS server receives client will likely be dropped, although the DOTS server receives
heartbeat requests in addition to DOTS messages sent by the DOTS heartbeat requests in addition to DOTS messages sent by the DOTS
client. In this scenario, the DOTS agents MUST behave differently to client. In this scenario, the DOTS agents MUST behave differently to
handle message transmission and DOTS session liveliness during link handle message transmission and DOTS session liveliness during link
saturation: saturation:
o The DOTS client MUST NOT consider the DOTS session terminated even o The DOTS client MUST NOT consider the DOTS session terminated even
skipping to change at page 44, line 45 skipping to change at page 48, line 7
| | +--ro alias-name* string | | +--ro alias-name* string
| | +--ro acl-list* [acl-name acl-type] | | +--ro acl-list* [acl-name acl-type]
| | +--ro acl-name -> /ietf-acl:access-lists/acl/acl-name | | +--ro acl-name -> /ietf-acl:access-lists/acl/acl-name
| | +--ro acl-type -> /ietf-acl:access-lists/acl/acl-type | | +--ro acl-type -> /ietf-acl:access-lists/acl/acl-type
| +--ro pkts-dropped? yang:zero-based-counter64 | +--ro pkts-dropped? yang:zero-based-counter64
| +--ro bps-dropped? yang:zero-based-counter64 | +--ro bps-dropped? yang:zero-based-counter64
| +--ro bytes-dropped? yang:zero-based-counter64 | +--ro bytes-dropped? yang:zero-based-counter64
| +--ro pps-dropped? yang:zero-based-counter64 | +--ro pps-dropped? yang:zero-based-counter64
+--:(configuration) +--:(configuration)
+--rw session-id int32 +--rw session-id int32
+--rw heartbeat-interval? int16 +--rw attack-time-config
+--rw missing-hb-allowed? int16 | +--rw heartbeat-interval
+--rw max-retransmit? int16 | | +--rw max-value? int16
+--rw ack-timeout? int16 | | +--rw min-value? int16
+--rw ack-random-factor? decimal64 | | +--rw current-value? int16
| +--rw missing-hb-allowed
| | +--rw max-value? int16
| | +--rw min-value? int16
| | +--rw current-value? int16
| +--rw max-retransmit
| | +--rw max-value? int16
| | +--rw min-value? int16
| | +--rw current-value? int16
| +--rw ack-timeout
| | +--rw max-value? int16
| | +--rw min-value? int16
| | +--rw current-value? int16
| +--rw ack-random-factor
| +--rw max-value? decimal64
| +--rw min-value? decimal64
| +--rw current-value? decimal64
+--rw peace-time-config
| +--rw heartbeat-interval
| | +--rw max-value? int16
| | +--rw min-value? int16
| | +--rw current-value? int16
| +--rw missing-hb-allowed
| | +--rw max-value? int16
| | +--rw min-value? int16
| | +--rw current-value? int16
| +--rw max-retransmit
| | +--rw max-value? int16
| | +--rw min-value? int16
| | +--rw current-value? int16
| +--rw ack-timeout
| | +--rw max-value? int16
| | +--rw min-value? int16
| | +--rw current-value? int16
| +--rw ack-random-factor
| +--rw max-value? decimal64
| +--rw min-value? decimal64
| +--rw current-value? decimal64
+--rw trigger-mitigation? boolean +--rw trigger-mitigation? boolean
+--rw config-interval? int32 +--rw config-interval? int32
5.2. YANG Module 5.2. YANG Module
<CODE BEGINS> file "ietf-dots-signal@2017-12-12.yang" <CODE BEGINS> file "ietf-dots-signal@2017-12-19.yang"
module ietf-dots-signal {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-dots-signal";
prefix "signal";
import ietf-inet-types {prefix "inet";}
import ietf-yang-types {prefix yang;}
import ietf-access-control-list {prefix "ietf-acl";}
organization "IETF DDoS Open Threat Signaling (DOTS) Working Group"; module ietf-dots-signal {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-dots-signal";
prefix "signal";
contact import ietf-inet-types {prefix "inet";}
"Konda, Tirumaleswar Reddy <TirumaleswarReddy_Konda@McAfee.com> import ietf-yang-types {prefix yang;}
Mohamed Boucadair <mohamed.boucadair@orange.com> import ietf-access-control-list {prefix "ietf-acl";}
Prashanth Patil <praspati@cisco.com>
Andrew Mortensen <amortensen@arbor.net>
Nik Teague <nteague@verisign.com>";
description organization "IETF DDoS Open Threat Signaling (DOTS) Working Group";
"This module contains YANG definition for the signaling
messages exchanged between a DOTS client and a DOTS server.
Copyright (c) 2017 IETF Trust and the persons identified as contact
authors of the code. All rights reserved. "Konda, Tirumaleswar Reddy <TirumaleswarReddy_Konda@McAfee.com>
Mohamed Boucadair <mohamed.boucadair@orange.com>
Prashanth Patil <praspati@cisco.com>
Andrew Mortensen <amortensen@arbor.net>
Nik Teague <nteague@verisign.com>";
Redistribution and use in source and binary forms, with or description
without modification, is permitted pursuant to, and subject "This module contains YANG definition for the signaling
to the license terms contained in, the Simplified BSD License messages exchanged between a DOTS client and a DOTS server.
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see Copyright (c) 2017 IETF Trust and the persons identified as
the RFC itself for full legal notices."; authors of the code. All rights reserved.
revision 2017-12-12 { Redistribution and use in source and binary forms, with or
description without modification, is permitted pursuant to, and subject
"Initial revision."; to the license terms contained in, the Simplified BSD License
reference set forth in Section 4.c of the IETF Trust's Legal Provisions
"RFC XXXX: Distributed Denial-of-Service Open Threat Relating to IETF Documents
Signaling (DOTS) Signal Channel"; (http://trustee.ietf.org/license-info).
}
grouping target { This version of this YANG module is part of RFC XXXX; see
description the RFC itself for full legal notices.";
"Specifies the scope of the mitigation request.";
leaf-list target-prefix { revision 2017-12-19 {
type inet:ip-prefix;
description description
"IPv4 or IPv6 prefix identifying the target."; "Initial revision.";
reference
"RFC XXXX: Distributed Denial-of-Service Open Threat
Signaling (DOTS) Signal Channel";
} }
list target-port-range { grouping target {
key "lower-port upper-port";
description description
"Port range. When only lower-port is "Specifies the scope of the mitigation request.";
present, it represents a single port.";
leaf lower-port { leaf-list target-prefix {
type inet:port-number; type inet:ip-prefix;
mandatory true; description
description "Lower port number."; "IPv4 or IPv6 prefix identifying the target.";
} }
leaf upper-port { list target-port-range {
type inet:port-number; key "lower-port upper-port";
must ". >= ../lower-port" {
error-message
"The upper port number must be greater than
or equal to lower port number.";
}
description "Upper port number.";
}
}
leaf-list target-protocol { description
type uint8; "Port range. When only lower-port is
description present, it represents a single port.";
"Identifies the target protocol number.
The value '0' means 'all protocols'. leaf lower-port {
type inet:port-number;
mandatory true;
description "Lower port number.";
}
Values are taken from the IANA protocol registry: leaf upper-port {
https://www.iana.org/assignments/protocol-numbers/ type inet:port-number;
protocol-numbers.xhtml must ". >= ../lower-port" {
error-message
"The upper port number must be greater than
or equal to lower port number.";
}
description "Upper port number.";
}
}
For example, 6 for TCP or 17 for UDP."; leaf-list target-protocol {
} type uint8;
description
"Identifies the target protocol number.
leaf-list target-fqdn { The value '0' means 'all protocols'.
type inet:domain-name;
description "FQDN identifying the target.";
}
leaf-list target-uri { Values are taken from the IANA protocol registry:
type inet:uri; https://www.iana.org/assignments/protocol-numbers/
description "URI identifying the target."; protocol-numbers.xhtml
}
leaf-list alias-name { For example, 6 for TCP or 17 for UDP.";
type string; }
description "alias name";
}
}
grouping mitigation-scope { leaf-list target-fqdn {
description type inet:domain-name;
"Specifies the scope of the mitigation request."; description "FQDN identifying the target.";
}
leaf-list client-identifier { leaf-list target-uri {
type binary; type inet:uri;
description description "URI identifying the target.";
"The client identifier may be conveyed by }
the DOTS gateway to propagate the DOTS client
identification information from the gateway's client-side to the
gateway's server-side, and from the gateway's
server-side to the DOTS server.
It allows the destination DOTS server to accept leaf-list alias-name {
mitigation requests with scopes which the DOTS type string;
client is authorized to manage."; description "alias name";
}
} }
list scope { grouping mitigation-scope {
key mitigation-id;
description description
"The scope of the request."; "Specifies the scope of the mitigation request.";
leaf mitigation-id { leaf-list client-identifier {
type int32; type binary;
description description
"Mitigation request identifier. "The client identifier may be conveyed by
the DOTS gateway to propagate the DOTS client
identification information from the gateway's
client-side to the gateway's server-side,
and from the gateway's server-side to the DOTS
server.
This identifier must be unique for each mitigation It may be used by the final DOTS server
request bound to the DOTS client."; for policy enforcement purposes.";
} }
uses target; list scope {
leaf lifetime { key mitigation-id;
type int32;
units "seconds";
default 3600;
description description
"Indicates the lifetime of the mitigation request."; "The scope of the request.";
reference
"RFC XXXX: Distributed Denial-of-Service Open Threat
Signaling (DOTS) Signal Channel";
}
leaf mitigation-start { leaf mitigation-id {
type int64; type int32;
units "seconds"; description
description "Mitigation request identifier.
"Mitigation start time is represented in seconds
relative to 1970-01-01T00:00Z in UTC time.";
}
leaf status { This identifier must be unique for each mitigation
type enumeration { request bound to the DOTS client.";
enum "attack-mitigation-in-progress" { }
value 1;
description
"Attack mitigation is in progress (e.g., changing
the network path to re-route the inbound traffic
to DOTS mitigator).";
}
enum "attack-successfully-mitigated" { uses target;
value 2; leaf lifetime {
description type int32;
"Attack is successfully mitigated (e.g., traffic units "seconds";
is redirected to a DDOS mitigator and attack default 3600;
traffic is dropped or blackholed)."; description
} "Indicates the lifetime of the mitigation request.";
reference
"RFC XXXX: Distributed Denial-of-Service Open Threat
Signaling (DOTS) Signal Channel";
}
enum "attack-stopped" { leaf mitigation-start {
value 3; type int64;
description units "seconds";
"Attack has stopped and the DOTS client can description
withdraw the mitigation request."; "Mitigation start time is represented in seconds
} relative to 1970-01-01T00:00Z in UTC time.";
}
enum "attack-exceeded-capability" { leaf status {
value 4; type enumeration {
description enum "attack-mitigation-in-progress" {
"Attack has exceeded the mitigation provider value 1;
capability."; description
} "Attack mitigation is in progress (e.g., changing
the network path to re-route the inbound traffic
to DOTS mitigator).";
}
enum "dots-client-withdrawn-mitigation" { enum "attack-successfully-mitigated" {
value 5; value 2;
description description
"DOTS client has withdrawn the mitigation "Attack is successfully mitigated (e.g., traffic
request and the mitigation is active but is redirected to a DDOS mitigator and attack
terminating."; traffic is dropped or blackholed).";
} }
enum "attack-mitigation-terminated" { enum "attack-stopped" {
value 6; value 3;
description description
"Attack mitigation is now terminated."; "Attack has stopped and the DOTS client can
} withdraw the mitigation request.";
}
enum "attack-mitigation-withdrawn" { enum "attack-exceeded-capability" {
value 7; value 4;
description description
"Attack mitigation is withdrawn."; "Attack has exceeded the mitigation provider
} capability.";
}
enum "attack-mitigation-rejected" { enum "dots-client-withdrawn-mitigation" {
value 8; value 5;
description description
"Attack mitigation is rejected."; "DOTS client has withdrawn the mitigation
} request and the mitigation is active but
} terminating.";
config false; }
description
"Indicates the status of a mitigation request.
It must be included in responses only.";
}
container conflict-information { enum "attack-mitigation-terminated" {
value 6;
description
"Attack mitigation is now terminated.";
}
enum "attack-mitigation-withdrawn" {
value 7;
description
"Attack mitigation is withdrawn.";
}
enum "attack-mitigation-rejected" {
value 8;
description
"Attack mitigation is rejected.";
}
}
config false; config false;
description description
"Indicates that a conflict is detected. "Indicates the status of a mitigation request.
Must only be used for responses."; It must be included in responses only.";
}
leaf conflict-status { container conflict-information {
type enumeration { config false;
enum "request-inactive-other-active" { description
value 1; "Indicates that a conflict is detected.
description Must only be used for responses.";
"DOTS Server has detected conflicting mitigation
requests from different DOTS clients.
This mitigation request is currently inactive leaf conflict-status {
until the conflicts are resolved. Another type enumeration {
mitigation request is active."; enum "request-inactive-other-active" {
value 1;
description
"DOTS Server has detected conflicting mitigation
requests from different DOTS clients.
This mitigation request is currently inactive
until the conflicts are resolved. Another
mitigation request is active.";
}
enum "request-active" {
value 2;
description
"DOTS Server has detected conflicting mitigation
requests from different DOTS clients.
This mitigation request is currently active.";
}
enum "all-requests-inactive" {
value 3;
description
"DOTS Server has detected conflicting mitigation
requests from different DOTS clients. All
conflicting mitigation requests are inactive.";
}
} }
description
"Indicates the conflict status.
It must be included in responses only.";
}
enum "request-active" { leaf conflict-cause {
value 2; type enumeration {
description enum "overlapping-targets" {
"DOTS Server has detected conflicting mitigation value 1;
requests from different DOTS clients. description
This mitigation request is currently active."; "Overlapping targets. conflict-scope provides
} more details about the exact conflict.";
}
enum "all-requests-inactive" { enum "conflict-with-whitelist" {
value 3; value 2;
description description
"DOTS Server has detected conflicting mitigation "Conflicts with an existing white list.
requests from different DOTS clients. All
conflicting mitigation requests are inactive."; This code is returned when the DDoS mitigation
detects that some of the source addresses/prefixes
listed in the white list ACLs are actually
attacking the target.";
}
} }
description
"Indicates the cause of the conflict.
It must be included in responses only.";
} }
description
"Indicates the conflict status.
It must be included in responses only.";
}
leaf conflict-cause { leaf retry-timer {
type enumeration { type int32;
enum "overlapping-targets" { units "seconds";
value 1; description
description "The DOTS client must not re-send the
"Overlapping targets. conflict-scope provides same request before the expiry of this timer.
more details about the exact conflict."; It must be included in responses, only.";
} }
enum "conflict-with-whitelist" { container conflict-scope {
value 2; description
description "Provides more information about the conflict scope.";
"Conflicts with an existing white list.
This code is returned when the DDoS mitigation uses target {
detects that some of the source addresses/prefixes when "../conflict-cause = 'overlapping-targets'";
listed in the white list ACLs are actually }
attacking the target.";
} list acl-list {
when "../../conflict-cause = 'conflict-with-whitelist'";
key "acl-name acl-type";
description
"List of conflicting ACLs";
leaf acl-name {
type leafref {
path "/ietf-acl:access-lists/ietf-acl:acl" +
"/ietf-acl:acl-name";
}
description
"Reference to the conflicting ACL name bound to
a DOTS client.";
}
leaf acl-type {
type leafref {
path "/ietf-acl:access-lists/ietf-acl:acl" +
"/ietf-acl:acl-type";
}
description
"Reference to the conflicting ACL type bound to
a DOTS client.";
}
}
} }
}
leaf pkts-dropped {
type yang:zero-based-counter64;
config false;
description description
"Indicates the cause of the conflict. "Number of dropped packets";
}
It must be included in responses only."; leaf bps-dropped {
type yang:zero-based-counter64;
config false;
description
"The average number of dropped bytes per second for
the mitigation request since the attack
mitigation is triggered.";
} }
leaf retry-timer { leaf bytes-dropped {
type int32; type yang:zero-based-counter64;
units "seconds"; units 'bytes';
config false;
description description
"The DOTS client must not re-send the "Counter for dropped packets; in bytes.";
same request before the expiry of this timer.
It must be included in responses, only.";
} }
container conflict-scope { leaf pps-dropped {
type yang:zero-based-counter64;
config false;
description description
"Provides more information about the conflict scope."; "The average number of dropped packets per second
for the mitigation request since the attack
mitigation is triggered.";
}
}
}
uses target { grouping config-parameters {
when "../conflict-cause = 'overlapping-targets'"; description
} "Subset of DOTS signal channel session configuration.";
list acl-list { container heartbeat-interval {
when "../../conflict-cause = 'conflict-with-whitelist'"; description
key "acl-name acl-type"; "DOTS agents regularly send heartbeats to each other
description after mutual authentication is successfully
"List of conflicting ACLs"; completed in order to keep the DOTS signal channel
open.";
leaf acl-name { leaf max-value {
type leafref { type int16;
path "/ietf-acl:access-lists/ietf-acl:acl" + units "seconds";
"/ietf-acl:acl-name"; description
} "Maximum acceptable value.";
description reference
"Reference to the conflicting ACL name bound to "RFC XXXX: Distributed Denial-of-Service Open Threat
a DOTS client."; Signaling (DOTS) Signal Channel";
} }
leaf acl-type { leaf min-value {
type leafref { type int16;
path "/ietf-acl:access-lists/ietf-acl:acl" + units "seconds";
"/ietf-acl:acl-type"; description
} "Minimum acceptable value.";
description reference
"Reference to the conflicting ACL type bound to "RFC XXXX: Distributed Denial-of-Service Open Threat
a DOTS client."; Signaling (DOTS) Signal Channel";
}
}
}
} }
leaf pkts-dropped { leaf current-value {
type yang:zero-based-counter64; type int16;
config false; units "seconds";
default 30;
description description
"Number of dropped packets"; "Current value.
'0' means that heartbeat mechanism is deactivated.";
reference
"RFC XXXX: Distributed Denial-of-Service Open Threat
Signaling (DOTS) Signal Channel";
} }
}
leaf bps-dropped { container missing-hb-allowed {
type yang:zero-based-counter64; description
config false; "Maximum number of missing heartbeats allowed.";
leaf max-value {
type int16;
description description
"The average number of dropped bytes per second for "Maximum acceptable value.";
the mitigation request since the attack reference
mitigation is triggered."; "RFC XXXX: Distributed Denial-of-Service Open Threat
Signaling (DOTS) Signal Channel";
} }
leaf bytes-dropped { leaf min-value {
type yang:zero-based-counter64; type int16;
units 'bytes';
config false;
description description
"Counter for dropped packets; in bytes."; "Minimum acceptable value.";
reference
"RFC XXXX: Distributed Denial-of-Service Open Threat
Signaling (DOTS) Signal Channel";
}
leaf current-value {
type int16;
default 5;
description
"Current value.";
reference
"RFC XXXX: Distributed Denial-of-Service Open Threat
Signaling (DOTS) Signal Channel";
} }
}
leaf pps-dropped { container max-retransmit {
type yang:zero-based-counter64; description
config false; "Maximum number of retransmissions of a Confirmable
message.";
leaf max-value {
type int16;
description description
"The average number of dropped packets per second "Maximum acceptable value.";
for the mitigation request since the attack reference
mitigation is triggered."; "Section 4.8 of RFC 7552.";
}
leaf min-value {
type int16;
description
"Minimum acceptable value.";
reference
"Section 4.8 of RFC 7552.";
}
leaf current-value {
type int16;
default 3;
description
"Current value.";
reference
"RFC XXXX: Distributed Denial-of-Service Open Threat
Signaling (DOTS) Signal Channel";
}
} }
}
}
grouping signal-config { container ack-timeout {
description description
"DOTS signal channel session configuration."; "Initial retransmission timeout value.";
leaf session-id { leaf max-value {
type int32; type int16;
mandatory true; units "seconds";
description description
"An identifier for the DOTS signal channel "Maximum value.";
session configuration data."; reference
} "Section 4.8 of RFC 7552.";
}
leaf heartbeat-interval { leaf min-value {
type int16; type int16;
units "seconds"; units "seconds";
default 30; description
description "Minimum value.";
"DOTS agents regularly send heartbeats to each other reference
after mutual authentication is successfully "Section 4.8 of RFC 7552.";
completed, in order to keep the DOTS signal channel }
open. leaf current-value {
type int16;
units "seconds";
default 2;
description
"Current value.";
reference
"Section 4.8 of RFC 7552.";
}
}
'0' means that heartbeat mechanism is deactivated."; container ack-random-factor {
reference description
"RFC XXXX: Distributed Denial-of-Service Open Threat "Random factor used to influence the timing of
Signaling (DOTS) Signal Channel"; retransmissions.";
}
leaf missing-hb-allowed { leaf max-value {
type int16; type decimal64 {
default 5; fraction-digits 2;
description }
"Maximum number of missing heartbeats allowed."; description
reference "Maximum acceptable value.";
"RFC XXXX: Distributed Denial-of-Service Open Threat reference
Signaling (DOTS) Signal Channel"; "Section 4.8 of RFC 7552.";
} }
leaf max-retransmit { leaf min-value {
type int16; type decimal64 {
default 3; fraction-digits 2;
description
"Maximum number of retransmissions of a }
Confirmable message."; description
reference "Minimum acceptable value.";
"RFC XXXX: Distributed Denial-of-Service Open Threat reference
Signaling (DOTS) Signal Channel"; "Section 4.8 of RFC 7552.";
}
leaf current-value {
type decimal64 {
fraction-digits 2;
}
default 1.5;
description
"Current value.";
reference
"Section 4.8 of RFC 7552.";
}
}
} }
leaf ack-timeout { grouping signal-config {
type int16;
units "seconds";
default 2;
description description
"Initial retransmission timeout value."; "DOTS signal channel session configuration.";
reference
"Section 4.8 of RFC 7552.";
}
leaf ack-random-factor { leaf session-id {
type decimal64 { type int32;
fraction-digits 2; mandatory true;
description
"An identifier for the DOTS signal channel
session configuration data.";
} }
default 1.5;
description
"Random factor used to influence the timing of
retransmissions.";
reference
"Section 4.8 of RFC 7552.";
}
leaf trigger-mitigation { container attack-time-config {
type boolean; description
default true; "Configuration paramaters to use when an attack is active.";
description uses config-parameters;
"If false, then mitigation is triggered }
only when the DOTS server channel session is lost";
reference
"RFC XXXX: Distributed Denial-of-Service Open Threat
Signaling (DOTS) Signal Channel";
}
leaf config-interval { container peace-time-config {
type int32; description
units "minutes"; "Configuration paramaters to use in peacetime.";
description uses config-parameters;
"This parameter is returned by a DOTS server to }
a requesting DOTS client to indicate the time interval
after which the DOTS client must contact the DOTS
server in order to retrieve the signal channel
configuration data.
This mechanism allows the update of the configuration leaf trigger-mitigation {
data if a change occurs. type boolean;
default true;
description
"If false, then mitigation is triggered
only when the DOTS server channel session is lost";
reference
"RFC XXXX: Distributed Denial-of-Service Open Threat
Signaling (DOTS) Signal Channel";
}
For example, the new configuration may instruct leaf config-interval {
a DOTS client to cease heartbeats or reduce type int32;
heartbeat frequency. units "minutes";
description
"This parameter is returned by a DOTS server to
a requesting DOTS client to indicate the time interval
after which the DOTS client must contact the DOTS
server in order to retrieve the signal channel
configuration data.
'0' is used to disable this refresh mechanism."; This mechanism allows the update of the configuration
} data if a change occurs.
}
container dots-signal { For example, the new configuration may instruct
description a DOTS client to cease heartbeats or reduce
"Main container for DOTS signal message. heartbeat frequency.
A DOTS signal message can be a mitigation message or
a configuration message.";
choice message-type { '0' is used to disable this refresh mechanism.";
}
}
container dots-signal {
description description
"Either a mitigation or a configuration message."; "Main container for DOTS signal message.
A DOTS signal message can be a mitigation message or
a configuration message.";
case mitigation-scope { choice message-type {
description description
"Mitigation scope of a mitigation message."; "Either a mitigation or a configuration message.";
uses mitigation-scope;
} case mitigation-scope {
description
"Mitigation scope of a mitigation message.";
uses mitigation-scope;
}
case configuration {
description
"Configuration message.";
uses signal-config;
}
case configuration {
description
"Configuration message.";
uses signal-config;
} }
} }
} }
} <CODE ENDS>
<CODE ENDS>
6. Mapping Parameters to CBOR 6. Mapping Parameters to CBOR
All parameters in the payload of the DOTS signal channel MUST be All parameters in the payload of the DOTS signal channel MUST be
mapped to CBOR types as shown in Table 4 and are assigned an integer mapped to CBOR types as shown in Table 4 and are assigned an integer
key to save space. The recipient of the payload MAY reject the key to save space. The recipient of the payload MAY reject the
information if it is not suitably mapped. information if it is not suitably mapped.
/----------------------+----------------+--------------------------\ /----------------------+----------------+--------------------------\
| Parameter name | CBOR key | CBOR major type of value | | Parameter name | CBOR key | CBOR major type of value |
skipping to change at page 55, line 49 skipping to change at page 62, line 34
| target-port-range | 5 | 4 | | target-port-range | 5 | 4 |
| lower-port | 6 | 0 | | lower-port | 6 | 0 |
| upper-port | 7 | 0 | | upper-port | 7 | 0 |
| target-protocol | 8 | 4 | | target-protocol | 8 | 4 |
| target-fqdn | 9 | 4 | | target-fqdn | 9 | 4 |
| target-uri | 10 | 4 | | target-uri | 10 | 4 |
| alias-name | 11 | 4 | | alias-name | 11 | 4 |
| lifetime | 12 | 0 | | lifetime | 12 | 0 |
| attack-status | 13 | 0 | | attack-status | 13 | 0 |
| signal-config | 14 | 5 | | signal-config | 14 | 5 |
| heartbeat-interval | 15 | 0 | | heartbeat-interval | 15 | 5 (map) |
| max-retransmit | 16 | 0 | | max-retransmit | 16 | 5 (map) |
| ack-timeout | 17 | 0 | | ack-timeout | 17 | 5 (map) |
| ack-random-factor | 18 | 7 | | ack-random-factor | 18 | 5 (map) |
| min-value | 19 | 0 | | min-value | 19 | 0 |
| max-value | 20 | 0 | | max-value | 20 | 0 |
| status | 21 | 0 | | status | 21 | 0 |
| conflict-information | 22 | 5 (map) | | conflict-information | 22 | 5 (map) |
| conflict-status | 23 | 0 | | conflict-status | 23 | 0 |
| conflict-cause | 24 | 0 | | conflict-cause | 24 | 0 |
| retry-timer | 25 | 0 | | retry-timer | 25 | 0 |
| bytes-dropped | 26 | 0 | | bytes-dropped | 26 | 0 |
| bps-dropped | 27 | 0 | | bps-dropped | 27 | 0 |
| pkts-dropped | 28 | 0 | | pkts-dropped | 28 | 0 |
| pps-dropped | 29 | 0 | | pps-dropped | 29 | 0 |
| session-id | 30 | 0 | | session-id | 30 | 0 |
| trigger-mitigation | 31 | 7 (simple types) | | trigger-mitigation | 31 | 7 (simple types) |
| missing-hb-allowed | 32 | 0 | | missing-hb-allowed | 32 | 5 (map) |
| current-value | 33 | 0 | | current-value | 33 | 0 |
| mitigation-start | 34 | 7 (floating-point) | | mitigation-start | 34 | 7 (floating-point) |
| target-prefix | 35 | 4 (array) | | target-prefix | 35 | 4 (array) |
| client-identifier | 36 | 2 (byte string) | | client-identifier | 36 | 2 (byte string) |
| alt-server | 37 | 2 | | alt-server | 37 | 2 |
| alt-server-record | 38 | 4 | | alt-server-record | 38 | 4 |
| addr | 39 | 2 | | addr | 39 | 2 |
| ttl | 40 | 0 | | ttl | 40 | 0 |
| conflict-scope | 41 | 5 (map) | | conflict-scope | 41 | 5 (map) |
| acl-name | 42 | 2 | | acl-name | 42 | 3 |
| acl-type | 43 | 3 | | acl-type | 43 | 3 |
| config-interval | 44 | 0 | | config-interval | 44 | 0 |
| attack-time-config | 45 | 5 (map) |
| peace-time-config | 46 | 5 (map) |
\----------------------+----------------+--------------------------/ \----------------------+----------------+--------------------------/
Table 4: CBOR mappings used in DOTS signal channel message Table 4: CBOR mappings used in DOTS signal channel message
7. (D)TLS Protocol Profile and Performance Considerations 7. (D)TLS Protocol Profile and Performance Considerations
7.1. (D)TLS Protocol Profile 7.1. (D)TLS Protocol Profile
This section defines the (D)TLS protocol profile of DOTS signal This section defines the (D)TLS protocol profile of DOTS signal
channel over (D)TLS and DOTS data channel over TLS. channel over (D)TLS and DOTS data channel over TLS.
There are known attacks on (D)TLS, such as man-in-the-middle and There are known attacks on (D)TLS, such as man-in-the-middle and
protocol downgrade attacks. These are general attacks on (D)TLS and, protocol downgrade attacks. These are general attacks on (D)TLS and,
as such, they are not specific to DOTS over (D)TLS; please refer to as such, they are not specific to DOTS over (D)TLS; refer to the
the (D)TLS RFCs for discussion of these security issues. DOTS agents (D)TLS RFCs for discussion of these security issues. DOTS agents
MUST adhere to the (D)TLS implementation recommendations and security MUST adhere to the (D)TLS implementation recommendations and security
considerations of [RFC7525] except with respect to (D)TLS version. considerations of [RFC7525] except with respect to (D)TLS version.
Since DOTS encryption that relies upon (D)TLS is virtually a green- Since DOTS signal channel encryption relies upon (D)TLS is virtually
field deployment, DOTS agents MUST implement only (D)TLS 1.2 or a green-field deployment, DOTS agents MUST implement only (D)TLS 1.2
later. or later.
When a DOTS client is configured with a domain name of the DOTS When a DOTS client is configured with a domain name of the DOTS
server, and connects to its configured DOTS server, the server may server, and connects to its configured DOTS server, the server may
present it with a PKIX certificate. In order to ensure proper present it with a PKIX certificate. In order to ensure proper
authentication, a DOTS client MUST verify the entire certification authentication, a DOTS client MUST verify the entire certification
path per [RFC5280]. The DOTS client additionally uses [RFC6125] path per [RFC5280]. The DOTS client additionally uses [RFC6125]
validation techniques to compare the domain name with the certificate validation techniques to compare the domain name with the certificate
provided. provided.
A key challenge to deploying DOTS is the provisioning of DOTS A key challenge to deploying DOTS is the provisioning of DOTS
skipping to change at page 57, line 37 skipping to change at page 64, line 24
o (D)TLS session resumption without server-side state [RFC5077] to o (D)TLS session resumption without server-side state [RFC5077] to
resume session and convey the DOTS signal. resume session and convey the DOTS signal.
o Raw public keys [RFC7250] or PSK handshake [RFC4279] which reduces o Raw public keys [RFC7250] or PSK handshake [RFC4279] which reduces
the size of the ServerHello, and can be used by DOTS agents that the size of the ServerHello, and can be used by DOTS agents that
cannot obtain certificates. cannot obtain certificates.
Implementations compliant with this profile SHOULD implement all of Implementations compliant with this profile SHOULD implement all of
the following items to reduce the delay required to deliver a DOTS the following items to reduce the delay required to deliver a DOTS
signal: signal channel message:
o TLS False Start [RFC7918] which reduces round-trips by allowing o TLS False Start [RFC7918] which reduces round-trips by allowing
the TLS second flight of messages (ChangeCipherSpec) to also the TLS second flight of messages (ChangeCipherSpec) to also
contain the DOTS signal. contain the DOTS signal.
o Cached Information Extension [RFC7924] which avoids transmitting o Cached Information Extension [RFC7924] which avoids transmitting
the server's certificate and certificate chain if the client has the server's certificate and certificate chain if the client has
cached that information from a previous TLS handshake. cached that information from a previous TLS handshake.
o TCP Fast Open [RFC7413] can reduce the number of round-trips to o TCP Fast Open [RFC7413] can reduce the number of round-trips to
convey DOTS signal. convey DOTS signal channel message.
7.2. (D)TLS 1.3 Considerations 7.2. (D)TLS 1.3 Considerations
TLS 1.3 [I-D.ietf-tls-tls13] provides critical latency improvements TLS 1.3 [I-D.ietf-tls-tls13] provides critical latency improvements
for connection establishment over TLS 1.2. The DTLS 1.3 protocol for connection establishment over TLS 1.2. The DTLS 1.3 protocol
[I-D.ietf-tls-dtls13] is based upon the TLS 1.3 protocol and provides [I-D.ietf-tls-dtls13] is based upon the TLS 1.3 protocol and provides
equivalent security guarantees. (D)TLS 1.3 provides two basic equivalent security guarantees. (D)TLS 1.3 provides two basic
handshake modes the DOTS signal channel can take advantage of: handshake modes the DOTS signal channel can take advantage of:
o A full handshake mode in which a DOTS client can send a DOTS o A full handshake mode in which a DOTS client can send a DOTS
mitigation request message after one round trip. This assumes no mitigation request message after one round trip and the DOTS
packet loss is expereienced, server immediately responds with a DOTS mitigation response. This
assumes no packet loss is experienced.
o 0-RTT mode in which the DOTS client can authenticate itself and o 0-RTT mode in which the DOTS client can authenticate itself and
send DOTS mitigation request messages in the first message, thus send DOTS mitigation request messages in the first message, thus
reducing handshake latency. 0-RTT only works if the DOTS client reducing handshake latency. 0-RTT only works if the DOTS client
has previously communicated with that DOTS server, which is very has previously communicated with that DOTS server, which is very
likely with the DOTS signal channel. likely with the DOTS signal channel.
The DOTS client has to establish a (D)TLS session with the DOTS The DOTS client has to establish a (D)TLS session with the DOTS
server during peacetime and share a PSK. server during peacetime and share a PSK.
skipping to change at page 60, line 12 skipping to change at page 66, line 31
maximum of 500 bytes of DOTS signal over a UDP datagram will maximum of 500 bytes of DOTS signal over a UDP datagram will
generally avoid IP fragmentation. generally avoid IP fragmentation.
8. Mutual Authentication of DOTS Agents & Authorization of DOTS Clients 8. Mutual Authentication of DOTS Agents & Authorization of DOTS Clients
(D)TLS based upon client certificate can be used for mutual (D)TLS based upon client certificate can be used for mutual
authentication between DOTS agents. If a DOTS gateway is involved, authentication between DOTS agents. If a DOTS gateway is involved,
DOTS clients and DOTS gateways MUST perform mutual authentication; DOTS clients and DOTS gateways MUST perform mutual authentication;
only authorized DOTS clients are allowed to send DOTS signals to a only authorized DOTS clients are allowed to send DOTS signals to a
DOTS gateway. The DOTS gateway and the DOTS server MUST perform DOTS gateway. The DOTS gateway and the DOTS server MUST perform
mutual authentication; a DOTS server only allows DOTS signals from an mutual authentication; a DOTS server only allows DOTS signal channel
authorized DOTS gateway, thereby creating a two-link chain of messages from an authorized DOTS gateway, thereby creating a two-link
transitive authentication between the DOTS client and the DOTS chain of transitive authentication between the DOTS client and the
server. DOTS server.
+-----------------------------------------------+ +-----------------------------------------------+
| example.com domain +---------+ | | example.com domain +---------+ |
| | AAA | | | | AAA | |
| +---------------+ | Server | | | +---------------+ | Server | |
| | Application | +------+--+ | | | Application | +------+--+ |
| | server +<-----------------+ ^ | | | server +<-----------------+ ^ |
| | (DOTS client) | | | | | | (DOTS client) | | | |
| +---------------+ | | | | +---------------+ | | |
| V V | example.net domain | V V | example.net domain
skipping to change at page 63, line 12 skipping to change at page 70, line 4
o CBOR Key Value: 1 o CBOR Key Value: 1
o CBOR Major Type: 5 o CBOR Major Type: 5
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Specification Document(s): this document
o Parameter Name: scope o Parameter Name: scope
o CBOR Key Value: 2 o CBOR Key Value: 2
o CBOR Major Type: 5 o CBOR Major Type: 5
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Specification Document(s): this document
o Parameter Name: mitigation-id o Parameter Name: mitigation-id
o CBOR Key Value: 3 o CBOR Key Value: 3
o CBOR Major Type: 0 o CBOR Major Type: 0
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Specification Document(s): this document
o Parameter Name: acl-type o Parameter Name: acl-list
o CBOR Key Value: 4 o CBOR Key Value: 4
o CBOR Major Type: 4 o CBOR Major Type: 4
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Specification Document(s): this document
o Parameter Name: target-port-range o Parameter Name: target-port-range
o CBOR Key Value: 5 o CBOR Key Value: 5
o CBOR Major Type: 4 o CBOR Major Type: 4
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Specification Document(s): this document
skipping to change at page 64, line 39 skipping to change at page 71, line 30
o Specification Document(s): this document o Specification Document(s): this document
o Parameter Name: signal-config o Parameter Name: signal-config
o CBOR Key Value: 14 o CBOR Key Value: 14
o CBOR Major Type: 5 o CBOR Major Type: 5
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Specification Document(s): this document
o Parameter Name: heartbeat-interval o Parameter Name: heartbeat-interval
o CBOR Key Value: 15 o CBOR Key Value: 15
o CBOR Major Type: 0 o CBOR Major Type: 5
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Specification Document(s): this document
o Parameter Name: max-retransmit o Parameter Name: max-retransmit
o CBOR Key Value: 16 o CBOR Key Value: 16
o CBOR Major Type: 0 o CBOR Major Type: 5
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Specification Document(s): this document
o Parameter Name: ack-timeout o Parameter Name: ack-timeout
o CBOR Key Value: 17 o CBOR Key Value: 17
o CBOR Major Type: 0 o CBOR Major Type: 5
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Specification Document(s): this document
o Parameter Name: ack-random-factor o Parameter Name: ack-random-factor
o CBOR Key Value: 18 o CBOR Key Value: 18
o CBOR Major Type: 7 o CBOR Major Type: 5
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Specification Document(s): this document
o Parameter Name: min-value o Parameter Name: min-value
o CBOR Key Value: 19 o CBOR Key Value: 19
o CBOR Major Type: 0 o CBOR Major Type: 0
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Specification Document(s): this document
o Parameter Name: max-value o Parameter Name: max-value
o CBOR Key Value: 20 o CBOR Key Value: 20
o CBOR Major Type: 0 o CBOR Major Type: 0
o Change Controller: IESG o Change Controller: IESG
skipping to change at page 66, line 45 skipping to change at page 73, line 36
o Specification Document(s): this document o Specification Document(s): this document
o Parameter Name: trigger-mitigation o Parameter Name: trigger-mitigation
o CBOR Key Value: 31 o CBOR Key Value: 31
o CBOR Major Type: 7 o CBOR Major Type: 7
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Specification Document(s): this document
o Parameter Name: missing-hb-allowed o Parameter Name: missing-hb-allowed
o CBOR Key Value: 32 o CBOR Key Value: 32
o CBOR Major Type: 0 o CBOR Major Type: 5
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Specification Document(s): this document
o Parameter Name: current-value o Parameter Name: current-value
o CBOR Key Value: 33 o CBOR Key Value: 33
o CBOR Major Type: 0 o CBOR Major Type: 0
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Specification Document(s): this document
o Parameter Name: mitigation-start o Parameter Name: mitigation-start
skipping to change at page 68, line 9 skipping to change at page 74, line 48
o Specification Document(s): this document o Specification Document(s): this document
o Parameter Name: conflict-scope o Parameter Name: conflict-scope
o CBOR Key Value: 41 o CBOR Key Value: 41
o CBOR Major Type: 5 o CBOR Major Type: 5
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Specification Document(s): this document
o Parameter Name: acl-name o Parameter Name: acl-name
o CBOR Key Value: 42 o CBOR Key Value: 42
o CBOR Major Type: 2 o CBOR Major Type: 3
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Specification Document(s): this document
o Parameter Name: acl-type o Parameter Name: acl-type
o CBOR Key Value: 43 o CBOR Key Value: 43
o CBOR Major Type: 3 o CBOR Major Type: 3
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Specification Document(s): this document
o Parameter Name: config-interval o Parameter Name: config-interval
o CBOR Key Value: 44 o CBOR Key Value: 44
o CBOR Major Type: 0 o CBOR Major Type: 0
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Specification Document(s): this document
o Parameter Name: attack-time-config
o CBOR Key Value: 45
o CBOR Major Type: 5
o Change Controller: IESG
o Specification Document(s): this document
o Parameter Name: peace-time-config
o CBOR Key Value: 46
o CBOR Major Type: 5
o Change Controller: IESG
o Specification Document(s): this document
9.5. DOTS Signal Channel YANG Module 9.5. DOTS Signal Channel YANG Module
This document requests IANA to register the following URI in the This document requests IANA to register the following URI in the
"IETF XML Registry" [RFC3688]: "IETF XML Registry" [RFC3688]:
URI: urn:ietf:params:xml:ns:yang:ietf-dots-signal URI: urn:ietf:params:xml:ns:yang:ietf-dots-signal
Registrant Contact: The IESG. Registrant Contact: The IESG.
XML: N/A; the requested URI is an XML namespace. XML: N/A; the requested URI is an XML namespace.
This document requests IANA to register the following YANG module in This document requests IANA to register the following YANG module in
skipping to change at page 70, line 28 skipping to change at page 77, line 31
In order to prevent leaking internal information outside a client- In order to prevent leaking internal information outside a client-
domain, DOTS gateways located in the client-domain SHOULD NOT reveal domain, DOTS gateways located in the client-domain SHOULD NOT reveal
the identification information that pertains to internal DOTS clients the identification information that pertains to internal DOTS clients
(client-identifier) unless explicitly configured to do so. (client-identifier) unless explicitly configured to do so.
Special care should be taken in order to ensure that the activation Special care should be taken in order to ensure that the activation
of the proposed mechanism will not impact the stability of the of the proposed mechanism will not impact the stability of the
network (including connectivity and services delivered over that network (including connectivity and services delivered over that
network). network).
Involved functional elements involved in the DDoS cooperation system
must exchange instructions and notification over a secure and
authenticated channel. Adequate filters can apply to avoid that
nodes outside a trusted domain can inject illegitimate requests.
Attacks can be initiated from within the trusted domain if an entity
has been corrupted. Adequate means to monitor trusted nodes should
also be enabled.
12. Contributors 12. Contributors
The following individuals have contributed to this document: The following individuals have contributed to this document:
Mike Geller Cisco Systems, Inc. 3250 Florida 33309 USA Email: Mike Geller Cisco Systems, Inc. 3250 Florida 33309 USA Email:
mgeller@cisco.com mgeller@cisco.com
Robert Moskowitz HTT Consulting Oak Park, MI 42837 United States Robert Moskowitz HTT Consulting Oak Park, MI 42837 United States
Email: rgm@htt-consult.com Email: rgm@htt-consult.com
skipping to change at page 74, line 29 skipping to change at page 81, line 24
November 2017. November 2017.
[proto_numbers] [proto_numbers]
"IANA, "Protocol Numbers"", 2011, "IANA, "Protocol Numbers"", 2011,
<http://www.iana.org/assignments/protocol-numbers>. <http://www.iana.org/assignments/protocol-numbers>.
[RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791,
DOI 10.17487/RFC0791, September 1981, DOI 10.17487/RFC0791, September 1981,
<https://www.rfc-editor.org/info/rfc791>. <https://www.rfc-editor.org/info/rfc791>.
[RFC3022] Srisuresh, P. and K. Egevang, "Traditional IP Network
Address Translator (Traditional NAT)", RFC 3022,
DOI 10.17487/RFC3022, January 2001,
<https://www.rfc-editor.org/info/rfc3022>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005, RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>. <https://www.rfc-editor.org/info/rfc3986>.
[RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram
Congestion Control Protocol (DCCP)", RFC 4340, Congestion Control Protocol (DCCP)", RFC 4340,
DOI 10.17487/RFC4340, March 2006, DOI 10.17487/RFC4340, March 2006,
<https://www.rfc-editor.org/info/rfc4340>. <https://www.rfc-editor.org/info/rfc4340>.
skipping to change at page 75, line 23 skipping to change at page 82, line 23
[RFC5077] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, [RFC5077] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig,
"Transport Layer Security (TLS) Session Resumption without "Transport Layer Security (TLS) Session Resumption without
Server-Side State", RFC 5077, DOI 10.17487/RFC5077, Server-Side State", RFC 5077, DOI 10.17487/RFC5077,
January 2008, <https://www.rfc-editor.org/info/rfc5077>. January 2008, <https://www.rfc-editor.org/info/rfc5077>.
[RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing,
"Session Traversal Utilities for NAT (STUN)", RFC 5389, "Session Traversal Utilities for NAT (STUN)", RFC 5389,
DOI 10.17487/RFC5389, October 2008, DOI 10.17487/RFC5389, October 2008,
<https://www.rfc-editor.org/info/rfc5389>. <https://www.rfc-editor.org/info/rfc5389>.
[RFC6146] Bagnulo, M., Matthews, P., and I. van Beijnum, "Stateful
NAT64: Network Address and Protocol Translation from IPv6
Clients to IPv4 Servers", RFC 6146, DOI 10.17487/RFC6146,
April 2011, <https://www.rfc-editor.org/info/rfc6146>.
[RFC6296] Wasserman, M. and F. Baker, "IPv6-to-IPv6 Network Prefix
Translation", RFC 6296, DOI 10.17487/RFC6296, June 2011,
<https://www.rfc-editor.org/info/rfc6296>.
[RFC6555] Wing, D. and A. Yourtchenko, "Happy Eyeballs: Success with [RFC6555] Wing, D. and A. Yourtchenko, "Happy Eyeballs: Success with
Dual-Stack Hosts", RFC 6555, DOI 10.17487/RFC6555, April Dual-Stack Hosts", RFC 6555, DOI 10.17487/RFC6555, April
2012, <https://www.rfc-editor.org/info/rfc6555>. 2012, <https://www.rfc-editor.org/info/rfc6555>.
[RFC6724] Thaler, D., Ed., Draves, R., Matsumoto, A., and T. Chown, [RFC6724] Thaler, D., Ed., Draves, R., Matsumoto, A., and T. Chown,
"Default Address Selection for Internet Protocol Version 6 "Default Address Selection for Internet Protocol Version 6
(IPv6)", RFC 6724, DOI 10.17487/RFC6724, September 2012, (IPv6)", RFC 6724, DOI 10.17487/RFC6724, September 2012,
<https://www.rfc-editor.org/info/rfc6724>. <https://www.rfc-editor.org/info/rfc6724>.
[RFC6887] Wing, D., Ed., Cheshire, S., Boucadair, M., Penno, R., and [RFC6887] Wing, D., Ed., Cheshire, S., Boucadair, M., Penno, R., and
P. Selkirk, "Port Control Protocol (PCP)", RFC 6887, P. Selkirk, "Port Control Protocol (PCP)", RFC 6887,
DOI 10.17487/RFC6887, April 2013, DOI 10.17487/RFC6887, April 2013,
<https://www.rfc-editor.org/info/rfc6887>. <https://www.rfc-editor.org/info/rfc6887>.
[RFC6888] Perreault, S., Ed., Yamagata, I., Miyakawa, S., Nakagawa,
A., and H. Ashida, "Common Requirements for Carrier-Grade
NATs (CGNs)", BCP 127, RFC 6888, DOI 10.17487/RFC6888,
April 2013, <https://www.rfc-editor.org/info/rfc6888>.
[RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed., [RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed.,
"Enrollment over Secure Transport", RFC 7030, "Enrollment over Secure Transport", RFC 7030,
DOI 10.17487/RFC7030, October 2013, DOI 10.17487/RFC7030, October 2013,
<https://www.rfc-editor.org/info/rfc7030>. <https://www.rfc-editor.org/info/rfc7030>.
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
October 2013, <https://www.rfc-editor.org/info/rfc7049>. October 2013, <https://www.rfc-editor.org/info/rfc7049>.
[RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP [RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP
 End of changes. 180 change blocks. 
718 lines changed or deleted 1073 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/