DOTS N. Teague Internet-Draft Verisign, Inc. Intended status: Standards Track A. Mortensen Expires: May 21, 2017 Arbor Networks, Inc. November 17, 2016 DDoS Open Threat Signaling Protocol draft-teague-dots-protocol-01 Abstract This document describes Distributed-Denial-of-Service (DDoS) Open Threat Signaling (DOTS), a protocol for requesting and managing mitigation of DDoS attacks. DOTS mitigation requests over the signal channel permit domains to signal the need for help fending off DDoS attacks, setting the scope and duration of the requested mitigation. Elements called DOTS servers field the signals for help, and enable defensive countermeasures to defend against the attack reported by the clients, reporting the status of the delegated defense to the requesting clients. DOTS clients additionally may use the data channel to manage filters and black- and white-lists to restrict or allow traffic to the clients' domains arbitrarily. The DOTS signal channel may operate over UDP [RFC0768] and if necessary TCP [RFC0793]. This revision discusses a transport- agnostic approach to this channel, focusing on the message exchanges and delegating transport specifics to other documents. The DOTS data channel operates over HTTPS or a transport with similar reliability, interaction and security characteristics. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." Teague & Mortensen Expires May 21, 2017 [Page 1] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 This Internet-Draft will expire on May 20, 2017. Copyright Notice Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 2. Architecture . . . . . . . . . . . . . . . . . . . . . . . . 4 2.1. DOTS Agents . . . . . . . . . . . . . . . . . . . . . . . 4 3. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 5 4. Signal Channel . . . . . . . . . . . . . . . . . . . . . . . 5 4.1. Minimum Viable Information . . . . . . . . . . . . . . . 6 4.2. Signal Channel Messages . . . . . . . . . . . . . . . . . 7 4.2.1. Messaging Overview . . . . . . . . . . . . . . . . . 7 4.2.2. Message Definition and Serialization . . . . . . . . 9 4.2.3. Client Message Fields . . . . . . . . . . . . . . . . 9 4.2.4. Mitigation Request Fields . . . . . . . . . . . . . . 10 4.2.5. DOTS Server Message Fields . . . . . . . . . . . . . 11 4.2.6. Server Errors . . . . . . . . . . . . . . . . . . . . 11 4.2.7. Server Mitigation Status Fields . . . . . . . . . . . 13 4.3. Interactions . . . . . . . . . . . . . . . . . . . . . . 13 4.3.1. Session Initialization . . . . . . . . . . . . . . . 13 4.3.2. Heartbeat . . . . . . . . . . . . . . . . . . . . . . 15 4.3.3. Mitigation Request Handling . . . . . . . . . . . . . 18 4.3.4. Ancillary Messages . . . . . . . . . . . . . . . . . 20 5. Data Channel . . . . . . . . . . . . . . . . . . . . . . . . 23 5.1. Role . . . . . . . . . . . . . . . . . . . . . . . . . . 23 5.2. Limitations . . . . . . . . . . . . . . . . . . . . . . . 23 5.3. Transport . . . . . . . . . . . . . . . . . . . . . . . . 23 5.4. Authentication . . . . . . . . . . . . . . . . . . . . . 24 5.5. Authorization . . . . . . . . . . . . . . . . . . . . . . 24 5.6. Resources . . . . . . . . . . . . . . . . . . . . . . . . 24 5.6.1. Resource Root . . . . . . . . . . . . . . . . . . . . 25 5.6.2. {+dataroot}/sessions . . . . . . . . . . . . . . . . 25 Teague & Mortensen Expires May 21, 2017 [Page 2] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 5.6.3. {+dataroot}/filters . . . . . . . . . . . . . . . . . 26 5.6.4. {+dataroot}/config . . . . . . . . . . . . . . . . . 29 5.6.5. Serialization . . . . . . . . . . . . . . . . . . . . 30 5.6.6. Caching . . . . . . . . . . . . . . . . . . . . . . . 31 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 7. Security Considerations . . . . . . . . . . . . . . . . . . . 31 7.1. Data Channel Security . . . . . . . . . . . . . . . . . . 31 7.2. Signal Channel Security . . . . . . . . . . . . . . . . . 32 8. Appendix A: Message Schemas . . . . . . . . . . . . . . . . . 32 8.1. DOTS Client Message Schema . . . . . . . . . . . . . . . 32 8.2. Mitigation Request Schema . . . . . . . . . . . . . . . . 32 8.3. Session Configuration Schema . . . . . . . . . . . . . . 33 8.4. DOTS Server Message Schema . . . . . . . . . . . . . . . 33 8.5. DOTS Redirect Schema . . . . . . . . . . . . . . . . . . 34 8.6. DOTS Mitigation Status Schema . . . . . . . . . . . . . . 35 8.7. Server Error Schema . . . . . . . . . . . . . . . . . . . 35 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 36 9.1. Normative References . . . . . . . . . . . . . . . . . . 36 9.2. Informative References . . . . . . . . . . . . . . . . . 39 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 40 1. Introduction Distributed-Denial-of-Service attack scale and frequency continues to increase year over year, and the trend shows no signs of abating [WISR]. In response to the DDoS attack trends, service providers and vendors have developed various approaches to sharing or delegating responsibility for defense, among them ad hoc service relationships, filtering through peering relationships [COMMUNITYFS], and proprietary solutions ([CLOUDSIGNAL], [OPENHYBRID]). Such hybrid approaches to DDoS defense have proven effective, but the heterogeneous methods employed to coordinate DDoS defenses across domain boundaries have necessarily limited their scope and effectiveness, as the mechanisms in one domain have no traction in another. The DDoS Open Threat Signaling (DOTS) protocol provides a common mechanism to achieve the coordinated attack response previously restricted to custom or proprietary solutions. To meet the needs of network operators facing down modern DDoS attacks, DOTS itself is a hybrid protocol, consisting of a signal channel and a data channel. DOTS uses the signal channel, a lightweight and robust communication layer, to signal the need for mitigation regardless of network conditions, and uses the data channel, an HTTPS [RFC7230] based communication layer with RESTful [REST] semantics, as vehicle for provisioning, configuration, and filter management. Teague & Mortensen Expires May 21, 2017 [Page 3] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 The DOTS protocol is not intended as a replacement for such protocols as BGP Flow Specification [RFC5575] or as a general purpose DDoS countermeasure application programming interface (API), but rather as an advisory protocol enabling attack response coordination between DOTS agents. Any DOTS-enabled device or service is capable of triggering a request for help and shaping the scope and nature of that help, with the details of the actual mitigation left to the discretion of the operators of the attack mitigators. DOTS thereby permits all participating parties to manage their own attack defenses in the manner most appropriate for their own domains. 1.1. Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. Terms used to define entity relationships, transmitted data, and methods of communication are drawn from the terminology defined in [I-D.ietf-dots-requirements]. 2. Architecture The architecture in which the DOTS protocol operates is assumed to be derived from the architectural components and concepts described in [I-D.ietf-dots-architecture]. 2.1. DOTS Agents All protocol communication is between a DOTS client and a DOTS server. The logical agent termed a DOTS gateway is in practice a DOTS server placed back-to-back with a DOTS client. As discussed in [I-D.ietf-dots-architecture], any interface enabling the back-to-back DOTS server and client to act as a DOTS gateway is implementation- specific. This protocol is therefore concerned only with managing one or more bilateral relationships between DOTS clients and the DOTS servers, a signaling mode known as Direct Signaling in the DOTS architecture. This is shown in Figure 1 below: +-----------+ signal channel +-----------+ | |<---------------->| | |DOTS client| |DOTS server| | |<================>| | +-----------+ data channel +-----------+ Figure 1: DOTS protocol direct signaling Teague & Mortensen Expires May 21, 2017 [Page 4] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 The DOTS architecture anticipates many-to-one and one-to-many deployments, in which multiple DOTS clients maintain distinct signaling sessions with a single DOTS server or a single DOTS client maintains distinct signaling sessions with multiple DOTS servers, as shown below in Figure 2: +----+ +----+ +----+ | c1 | | Sa |------| c2 | +----+ +----+ +----+ \ / \ / \ +----+ / +--| Sb |--+ +----+ DOTS DOTS DOTS client 1 servers client 2 Figure 2: DOTS protocol direct signaling DOTS server Sb has signaling sessions with DOTS clients c1 and c2. DOTS client c2 has signaling sessions with DOTS servers Sa and Sb. Except where explicitly defined in this protocol, all mechanisms to maintain multiple signaling sessions are left to the implementation. 3. Protocol Overview The DOTS protocol consists of two channels, a signal channel and a data channel. The signal channel is the minimal secure communication layer a DOTS client uses to request mitigation for resources under the administrative control of the DOTS client; the administrative control may be delegated. The data channel offers DOTS client operators the limited ability to adjust configuration and filtering for their mitigation requests. 4. Signal Channel The purpose of the signaling channel is to convey DDoS mitigation request and status information between participating agents (client and server or gateway). Conditions during a DDoS attack are invariably hostile for connection-oriented protocols traversing affected paths. Mechanisms such as Happy Eyeballs [RFC6555] may be used to select a transport suitable for a given time and prevailing network conditions. Implementations are required to support the DOTS signal channel over UDP as specified in [I-D.ietf-dots-requirements]. This document therefore assumes the the availability of a transport based upon UDP Teague & Mortensen Expires May 21, 2017 [Page 5] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 [RFC0768], but also defines the message exchanges agnostic of the underlying transport used to convey the signaling. Key tenets of DOTS protocol design are low communication overhead and efficient message packing to increase the chances of successful transmission and receipt. Desirable side-effects of efficient packing are the removal of the possibility of fragmentation in addition to a message size that is friendly towards encapsulation (e.g via GRE [RFC2784] or MPLS [RFC3031]). Large UDP packets may also be treated adversely by middleboxes with restrictive policies or may fall foul of aggressive filtering. In support of operational requirements for protocol efficiency, backward compatibility and extensibility in [I-D.ietf-dots-requirements], the signaling channel uses Protocol Buffers [PROTOBUF], also known as Protobufs, to define message schemas and serialize messages exchanged between DOTS agents. Data serialization alone does not cover the security requirements in [I-D.ietf-dots-requirements] of peer mutual authentication (SEC-001), message confidentiality (SEC-002), message replay protection (SEC- 003) or message integrity. These qualities must be present in the transport over which the DOTS protocol operates. Key distribution may be achieved via the data channel, via an online mechanism such as DANE [RFC6698], Enrollment over Secure Transport [RFC7030], or by out-of-band means. 4.1. Minimum Viable Information DOTS is intended to be extensible and to evolve to meet the future needs in communicating as yet unknown threats. However, it must be able to convey the minimum information required for an upstream mitigation platform to successfully counter a DDoS attack. A client may have limited visibility into the full breadth of an attack and as such may not be well placed to provide useful telemetry. DDoS sources may or may not be spoofed and number in the millions. Once mitigation is active, the filtered traffic seen by the DOTS client (or elements informing the DOTS client operator's decision to request mitigation) may not be representative of the ongoing attack. This provides challenges for the quality and usefulness of telemetry and mitigation/countermeasure stipulations and as such this type of information if conveyed can only be considered advisory. In these instances the minimum viable information required for the majority of mitigations to be activated is that which pertains to the resource being targeted by the attack (host, prefix, protocol, port, URI etc.), per [I-D.ietf-dots-requirements] (OP-006). The DOTS requirements also identify a mitigation lifetime period (OP-005) and Teague & Mortensen Expires May 21, 2017 [Page 6] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 mitigation efficacy metric (OP-007). The former may be considered for inclusion in the minimum viable information set, however, the latter may only be relevant in updates. An explicit mitigation request/terminate flag is also required: a mitigation MUST be explicitly requested by a DOTS client operator. Finally, each message should include a message id or sequence number field as well as a field for the last received message id or sequence number. These may then be compared by the endpoints to assist in tracking state and/or identifying loss. 4.2. Signal Channel Messages 4.2.1. Messaging Overview The signal channel requirements in [I-D.ietf-dots-requirements] demand a protocol capable of operating despite significant link congestion between DOTS agents. In an effort to maximize the probability of signal delivery between DOTS agents, all DOTS signal channel messages in the DOTS protocol are conceptually unidirectional heartbeats sent between DOTS agents. The result is a form of scheduled messaging between DOTS agents, in contrast to a conventional request-response model. Once a signal channel is established, a DOTS client begins sending unidirectional heartbeats to the DOTS server, separated by the configured session heartbeat interval (see Section 4.3.1 below). To request mitigation, a DOTS client merely adds the requested mitigation parameters to its heartbeat, and maintains that request until a heartbeat from the DOTS server indicates receipt of that mitigation request. The DOTS server likewise sends its unidirectional heartbeat on the schedule interval, augmenting the content of the heartbeat with mitigation request status. A simple exchange between DOTS agents with an established signaling session is shown below in Figure 3. Teague & Mortensen Expires May 21, 2017 [Page 7] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 Client Server | | // Active signaling session |<==== Signal Channel Active ====>| // with heartbeat interval of | | // 15 seconds, +/- jitter. | | |----------Heartbeat------------->| // Client heartbeat | | |<---------Heartbeat--------------| // Server heartbeat | | \ \ // 15 seconds elapse, during / / // which client adds request \ \ // for mitigation. | | |----------HeartBeat------------->| // Client heartbeat now has | + MitigationRequest | // mitigation request params. | | |<---------HeartBeat--------------| // Server heartbeat now has | + MitigationPending | // pending mitigation request | | // status. | | \ \ / / // 15s elapse, +/- jitter. \ \ | | |----------HeartBeat------------->| // Client heartbeat maintains | + MitigationRequest | // request as it waits for | | // mitigation to begin. | | | X----HeartBeat--------------| // Mitigation enabled, but | + MitigationRunning | // server heartbeat is dropped | | \ \ / / // 15s elapse, +/- jitter. \ \ | | |----------HeartBeat------------->| // Client heartbeat maintains | + MitigationRequest | // request as it waits for | | // mitigation to begin. | | |<---------HeartBeat--------------| // Server heartbeat, status of | + MitigationRunning | // running mitigation | | // delivered to client. Figure 3: Signaling Session with Mitigation Request All messages are variations of this scheduled heartbeat model. See Section 4.3 below for detailed discussion of the message exchanges between DOTS agents. Teague & Mortensen Expires May 21, 2017 [Page 8] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 4.2.2. Message Definition and Serialization The DOTS protocol signal channel uses Protobufs [PROTOBUF] as an interface definition language (IDL) for signal channel messaging between DOTS agent, reducing the number of discrete messages to just a single message superset per direction, with function defined by the chosen fields contained within the message. Protobufs schemas are used to define the messages sent in either direction, from which code may be generated for specific language implementations of DOTS. As Protobufs serialization relies on numbered fields, signal channel messaging permits the introduction of new numbered fields arbitrarily, adding the requisite extensibility to the protocol while retaining backward compatibility. Future revisions of or extensions to the protocol may use the data channel to provide a mechanism by which schema updates or expansions may be communicated during provisioning/session establishment. 4.2.3. Client Message Fields Only the seqno and last_svr_seqno fields are required in every message, as they are the minimum required for the heartbeat. Subsets of the other fields are used to convey a given signal message type. The fields in the DOTS client signal channel message have the following functions: seqno: a client-generated sequence number unique to the message. The client increments the seqno value by one for each message sent over the signal channel. last_svr_seqno: the sequence number of the last message received from the server, provided to the server as a simple way to detect lost messages. mitigations: a list of mitigations requested or withdrawn by the client. The mitigation schema fields are described below. active: indicates a request for a list of active mitigations and their detail that are current on the DOTS server. ping: an operator initiated heartbeat like message which will ellicit a response from the DOTS server. This may be used to prove bi-directional communications on an ad-hoc basis. For example, a DOTS ping may be used to prove keying material on the DOTS client is valid and may be used to establish signaling sessions with the DOTS server. Teague & Mortensen Expires May 21, 2017 [Page 9] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 extensions: these fields may be used to communicate implementation specific details. An example would be the dissemination of filters between DOTS client and DOTS server. 4.2.3.1. Client Message Schema The DOTS client message schema is detailed in Section 8.1. 4.2.4. Mitigation Request Fields The fields in a mitigation request are as follows: eventid: an opaque client generated identifier that distinguishes a unique event or incident. May be used by the client as a reference to the specific event triggering a mitigation request, or for other implementation-specific purposes. requested: signals the need for mitigation to the DOTS server. If true, the DOTS client is requesting mitigation for the provided scope. If false, the DOTS client is indicating it does not require mitigation, and the DOTS server MUST cease the mitigation for the provided scope. scope: the scope of the mitigation requested, which may be any of the types described in [I-D.ietf-dots-requirements], such as Classless Internet Domain Routing (CIDR) [RFC1518],[RFC1519] prefixes, DNS names, or aliases defined by the DOTS client operator through the data channel. lifetime: the lifetime in seconds a mitigation request should be considered valid. efficacy: a metric to convey to a DOTS server the perceived efficacy of an active mitigation, per operational requirements in [I-D.ietf-dots-requirements]. The mitigation efficacy is represented as a floating point value between 0 and 1, with smaller values indicating lesser efficacy, and larger greater efficacy. extensions: these fields may be used to provide implementation- specific mitigation details. 4.2.4.1. Mitigation Request Schema The DOTS client message schema is detailed in Section 8.2. Teague & Mortensen Expires May 21, 2017 [Page 10] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 4.2.5. DOTS Server Message Fields DOTS server messages use a subset of the available fields to convey the given signal type, including additional relevant fields as necessary. The only fields which may be common to all signals are seqno and last_client_seqno which may be used to detect message loss or out-of-order delivery. When conveying mitigation information, the server schema may bundle multiple mitigation status datasets into a single message, provided this does not violate the required sub-MTU message size [I-D.ietf-dots-requirements]. The fields in the DOTS server signal channel message schema have the following functions: seqno: a server generated sequence number unique to the message. last_cli_seqno: the seqno of the last message received from the client. ping: an operator-initiated heartbeat like message which will ellicit a response from the DOTS client. This may be used to prove bi-directional communications on an ad-hoc basis. error: details of an error caused by a DOTS client request. redirect: Populated with the details of the redirection target DOTS server, if the DOTS server is redirecting the DOTS client to another DOTS server. mitigations: a list containing the status of mitigations requested by the DOTS client. The fields in the mitigation status schema are described below. extensions: these fields may be used to communicate implementation specific details. An example would be the communication of DNS mitigation vip to the DOTS client by the DOTS server. 4.2.5.1. DOTS Server Message Schema The server message schema is detailed in Section 8.4. 4.2.6. Server Errors If a DOTS client message cannot be processed by the DOTS server, or for any other reason causes an error, the DOTS server MUST populate the error field in any response to the message causing the error. As the error response itself may be lost, a DOTS client may continue sending problematic messages regardless of the DOTS server's error Teague & Mortensen Expires May 21, 2017 [Page 11] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 notifications. DOTS server implementations MAY terminate the signaling session after client-triggered errors exceed a threshold during a time period equivalent to three times the session heartbeat interval. The DOTS client message triggering the error condition is indicated in the last_client_seqno value of the DOTS server message containing the error. Error codes MUST be one of the following types: NOERROR: Indicates the DOTS server has detected no error resulting from a DOTS client message. Implementations MAY omit the error field entirely when no error condition is present. This value is included in the schema largely to adhere to the convention that an error status of 0 indicates success. INVALID_VALUE: Indicates the DOTS client included an invalid value for a field in the client message most recently received from the client. The DOTS server SHOULD include specifics of the invalid value in the details field of the error. MITIGATION_UNAVAILABLE: Indicates the DOTS server is unable to provide mitigation in response to a mitigation request from the DOTS client. MITIGATION_CONFLICT: Indicates a mitigation request conflicts with an existing mitigation from the client. The DOTS server SHOULD populate the error details field with the status information of the mitigation conflicting with the requested mitigation. MALFORMED_MESSAGE: Indicates the DOTS client message is malformed and cannot be processed. 4.2.6.1. Server Error Fields code: a numeric code categorizing the error type detected by the DOTS server. details: specific information about the reason for the detected error. 4.2.6.2. Server Error Schema The server error schema is detailed in Section 8.7. Teague & Mortensen Expires May 21, 2017 [Page 12] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 4.2.7. Server Mitigation Status Fields The DOTS server message contains zero or more mitigation status messages, the fields of which have the following functions: eventid: an opaque client generated identifier that distinguishes a unique event or incident. ttl: the remaining lifetime of the mitigation, in seconds. bytes_dropped: the total dropped byte count for the mitigation associated with eventid. bps_dropped: the dropped bytes per second for the mitigation associated with eventid. This value is expected to be calculated by the mitigator, and as such is implementation-specific. pkts_dropped: the total dropped packet count for the mitigation associated with eventid.. pps_dropped: the dropped packets per second for the mitigation associated with eventid. This value is expected to be calculated by the mitigator, and as such is implementation-specific. blacklist_enabled: Indicates whether a blacklist of prohibited traffic sources is enabled for the mitigation associated with eventid. The blacklist is managed through the data channel. whitelist_enabled: Indicates whether a whitelist of sources from which traffic must always be allowed is enabled. The whitelist is managed through the data channel. filters_enabled: Indicates whether client-specified traffic filters are enabled for the mitigation associated with eventid. 4.3. Interactions 4.3.1. Session Initialization Signaling sessions are initiated by the DOTS client. Session initialization begins when the DOTS client connects to the DOTS server port, 4646. After connecting, the DOTS client establishes the channel security context, including all necessary cryptographic exchanges between the two DOTS agents. This signal channel specification is transport-agnostic, and delegates the details of transport, including transport security, to transport-specific documents. Regardless of transport, DOTS Teague & Mortensen Expires May 21, 2017 [Page 13] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 implementations nonetheless MUST provide signal channel security meeting the requirements in [I-D.ietf-dots-requirements]. Once the signal channel security context is established, the DOTS client sends a channel initialization message to the DOTS server, optionally including signaling session configuration values; if the session configuration values are excluded, defaults MUST be used for the signaling session. An example initialization message setting the acceptable signal loss and heartbeat interval for the signaling sessions is described in Figure 4 below: message DOTSClientMessage { 1 (seqno) = %; 2 (last_svr_seqno) = %; 6 (config) = { 1 (loss_limit) = %; 3 (heartbeat_interval) = %; }; } Figure 4: Signal Channel Initialization Message The DOTS server MUST respond immediately by sending a heartbeat (see Section 4.3.2 below) to the DOTS client. The signal channel is active when the DOTS client receives a heartbeat from the DOTS server with a last_client_seqno of a signal channel initialization message. Both DOTS agents MUST begin sending heartbeats on the interval for the signaling session once the session is active. The following example assumes a DOTS implementation using UDP as the transport and DTLS1.2 [RFC6347]. In Figure 5 below, the DOTS client uses the default values for acceptable signal loss, maximum mitigation lifetime, and heartbeat interval. The initial DOTS server heartbeat is lost, so the DOTS client sends another channel initialization message after waiting for the minimum heartbeat interval defined below in Section 4.3.2: Teague & Mortensen Expires May 21, 2017 [Page 14] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 Client Server | | |<- - - - DTLS1.2 handshake - - ->| // Server listens on UDP:4646. | | // Client initiates DTLS | | // handshake. | | |----------ChannelInit----------->| // Client sends signal | seqno = 1 | // channel init message | last_svr_seqno = 0 | | | | X----HeartBeat--------------| // Server immediately sends | seqno = 1 | // heartbeat reply, which | last_client_seqno = 1 | // is lost. | | \ \ // Session heartbeat interval / / // elapses. \ \ |----------ChannelInit----------->| // Client retries signal | seqno = 2 | // channel init message. | last_svr_seqno = 0 | | | |<---------HeartBeat--------------| // Server immediately sends | seqno = 2 | // heartbeat reply | last_client_seqno = 2 | | | |<==== Signal Channel Active ====>| Figure 5: Signal Channel Initialization 4.3.1.1. Session Initialization Error Handling If the DOTS client specifies invalid values for the signal channel configuration, the DOTS server replies with an error, and may ultimately terminate the connection if the client fails to correct the invalid values, as described in [I-D.ietf-dots-architecture]. 4.3.1.2. Mis-Sequencing In the event that the DOTS agent receives messages containing invalid seqno, last_client_seqno or last_svr_seqno these should be discarded and ignored. 4.3.2. Heartbeat The most common message exchanged between a DOTS client and a DOTS server is a heartbeat (OP-002 [I-D.ietf-dots-requirements]), which maintains and monitors the health of the DOTS session. This is achieved with simple, loosely-coupled bi-directional messages Teague & Mortensen Expires May 21, 2017 [Page 15] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 containing the sending DOTS agent's message sequence number and the sequence number the sending DOTS agent last received from its peer. Due to the stress volumetric DDoS impose upon a network, a degree of loss during attacks is to be expected. Message loss tolerance may be set on signal channel establishment. The default heartbeat interval is 20 seconds, plus or minus a number of milliseconds between 50 and 2000. The number of milliseconds MUST be randomized in order to introduce jitter into the heartbeat interval, as recommended by [RFC5405]. The default interval is derived from the recommendations in [RFC5405] regarding middlebox traversal, to maintain NAT bindings in the path between DOTS agents. The interval between heartbeats is may also be set by the client when establishing the signal channel. The minimum heartbeat interval is 15 seconds, plus the random number of milliseconds as described above. The maximum heartbeat interval is 120 seconds (two minutes), minus the random number of milliseconds described above. Heartbeats are loosely-coupled, meaning each DOTS agent in a bilateral signaling session sends DOTS heartbeats on the specified interval, but asynchronously, without acknowledgement. Each DOTS agent tracks heartbeats received from its peer, and includes the sequence number of the last heartbeat received from the peer agent in the next heartbeat sent, as shown in Figure 6: Teague & Mortensen Expires May 21, 2017 [Page 16] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 Client Server | | |----------HeartBeat------------->| // Client heartbeat | seqno = 1 | | last_svr_seqno = 0 | | | |<---------HeartBeat--------------| // Server heartbeat | seqno = 1 | | last_client_seqno = 1 | | | |----------HeartBeat------------->| // Client heartbeat | seqno = 2 | | last_svr_seqno = 1 | | | | X---HeartBeat--------------| // Server heartbeat lost | seqno = 2 | | last_client_seqno = 2 | | | |----------HeartBeat------------->| // Client heartbeat, | seqno = 3 | // last_svr_seqno remains 1, | last_svr_seqno = 1 | // indicating lost heartbeat | | |<---------HeartBeat--------------| // Server heartbeat resumes | seqno = 3 | | last_client_seqno = 3 | | | |----------HeartBeat------------->| // Client heartbeat | seqno = 4 | | last_svr_seqno = 3 | | | Figure 6: Heartbeats Between DOTS agents The DOTS client heartbeat has the following format: message DOTSClientMessage { 1 (seqno) = %; 2 (last_svr_seqno) = %; } The DOTS server heartbeat is identical aside from the schema type: message DOTSServerMessage { 1 (seqno) = %; 2 (last_svr_seqno) = %; } Teague & Mortensen Expires May 21, 2017 [Page 17] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 Should the number of signals lost exceed the acceptable lossiness value for the signaling session, the agent detecting the signal loss may consider the signaling session lost. The default value for acceptable signal loss is 9, which, when coupled with the default heartbeat interval, amounts to lack of heartbeat from the peer DOTS agent for 180 seconds (three minutes). 4.3.2.1. Ping There may be cases where a DOTS client or server operator wishes to trigger an immediate heartbeat response in order to validate bi- directional communication (e.g. during provisioning). This ad-hoc triggering may be achieved by setting the ping field set to TRUE. When DOTS agent receives a message on the signal channel with the ping field set to TRUE, it MUST immediately send heartbeat back to the ping sender. A ping reply MUST consist of only the senders sequence number and the sequence number of the received ping. [[EDITOR'S NOTE: rate limiting of pings required?]] A ping is identical to a standard heartbeat, but with the the ping field included and set to true: message DOTSClientMessage { 1 (seqno) = %; 2 (last_svr_seqno) = %; 5 (ping) = true; } 4.3.3. Mitigation Request Handling The mitigation request is the crux of the DOTS protocol, and is comprised of the minimum viable information described in Section 4.1. The request may be augmented with additional implementation specific extensions where these do not result in undue packet bloat. The DOTS client may send repeated requests until it receives a suitable response from the DOTS server by which it may interpret successful receipt. Teague & Mortensen Expires May 21, 2017 [Page 18] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 message DOTSClientMessage { 1 (seqno) = %; 2 (last_svr_seqno) = %; 3 (mitigations) = [ { 1 (eventid) = %; 2 (requested) = %; 3 (scope) = %; 4 (lifetime) = %; } ]; } The DOTS server is expected to respond to confirm that it has accepted and or rejected the mitigation request. Upon receipt of the response the DOTS client should cease sending additional initial requests for the same eventid. If these do not cease then the server may assume that the response was possibly lost and should resend accordingly. Acceptance status is communicated by the DOTS server replying with the corresponding eventid and the enabled field set to 1 for acceptance and 0 for rejection. A rejection by the DOTS server should be accompanied with an extension field detailing succinctly the reason (e.g. out of contract, conflict, maintenance etc. ). message DOTSServerMessage { 1 (seqno) = %; 2 (last_cli_seqno) = %; 4 (mitigations) = [ { 1 (eventid) = %; 2 (enabled) = true; // Mitigation request accepted } ] } After a period of time the mitigation request may expire and the DOTS server may end the mitigation. Alternately, the DOTS client may explicitly terminate the active mitigation by sending a message to the server that contains a mitigation value with the eventid and that has the requested field set to false, as shown below: Teague & Mortensen Expires May 21, 2017 [Page 19] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 message DOTSClientMessage { 1 (seqno) = %; 2 (last_svr_seqno) = %; 3 (mitigations) = [ { 1 (eventid) = %; 2 (requested) = false; // Terminate mitigation } ]; } The server must explicitly acknowledge the termination with a response message with the enabled field now set to false: message DOTSServerMessage { 1 (seqno) = %; 2 (last_cli_seqno) = %; 6 (mitigations) = [ { 1 (eventid) = %; 2 (enabled) = false; // Mitigation terminated } ]; } The life cycle of a DOTS mitigation request resembles the following: Client Server | | |---Request(M=true)----------->| // Mitigation request | | |<---------MitigationActive----| // Server acceptance | | |< - - - - MitigationFeedback -| | | |---Terminate(M=false)-------->| // Mitigation termination | | |<---------MitigationEnded-----| // Server termination ack 4.3.4. Ancillary Messages In addition to the basic interaction, additional messages may be exchanged throughout the lifetime of the mitigation. The following message types are defined to provide requisite information between DOTS agents during an active signaling session. Teague & Mortensen Expires May 21, 2017 [Page 20] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 4.3.4.1. Mitigation Feedback The DOTS server MUST update the client with current mitigation status. This MUST include the eventid, and SHOULD include available dropped attack traffic statistics provided by the mitigator. A DOTS server MAY provide feedback for more than one mitigation in a single message, provided the resulting message meets the sub-MTU size requirements in [I-D.ietf-dots-requirements]. The DOTS client SHOULD use the feedback from the DOTS server when deciding to update or terminate a mitigation request. For example, if the DOTS client learns from DOTS server mitigation feedback that the dropped_pps rate is low, the DOTS client might decide to terminate upstream mitigation and handle the attack locally. A mitigation feedback message from the DOTS server would resemble the following format, assuming an active mitigation request from the DOTS client: message DOTSServerMessage { 1 (seqno) = %; 2 (last_client_seqno) = %; 6 (mitigations) = [ { 1 (eventid) = %; 2 (enabled) = %; 3 (ttl) = %; 4 (bytes_dropped) = %; 5 (bps_dropped) = %; 6 (pkts_dropped) = %; 7 (pps_dropped) = %; 10 (filters_enabled) = true; }, ]; } 4.3.4.2. Mitigation Lifetime Update The DOTS client may wish to update the mitigation during its lifetime. Updates may be to alter the lifetime to extend the mitigation, or an update may communicate the perceived efficacy of the mitigation. The former may be as a result of the DOTS sever feedback which may suggest that an attack shows no sign of abating. The latter may be to notify the DOTS server whether the countermeasures deployed are perceived as effective or not. A DOTS client may update the lifetime of multiple mitigations in a single request as long as the message size meets the sub-MTU Teague & Mortensen Expires May 21, 2017 [Page 21] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 requirement per [I-D.ietf-dots-requirements]. The lifetime update message has the following format: message DOTSClientMessage { 1 (seqno) = %; 2 (last_svr_seqno) = %; 3 (mitigations) = [ { 1 (eventid) = %; 2 (requested) = true; 4 (lifetime) = %; } ]; } Upon receipt of the mitigation lifetime update, the DOTS server replace the current mitigation expiration time with the new value. The updated lifetime MUST be visible in the ttl field in subsequent mitigation feedback messages. When updating a mitigation lifetime, the DOTS client SHOULD continue sending the lifetime update request at the heartbeat interval until the DOTS server's mitigation feedback shows an updated ttl for the updated mitigation. 4.3.4.3. Mitigation Efficacy Updates When a mitigation is active, a DOTS client MUST periodically communicate the locally perceived efficacy of the mitigation to the DOTS server. This gives the DOTS server a rough sense of whether the DOTS client perceives the mitigator's deployed countermeasures as effective. The efficacy update update message has the following format: message DOTSClientMessage { 1 (seqno) = %; 2 (last_svr_seqno) = %; 3 (mitigations) = [ { 1 (eventid) = %; 6 (efficacy) = %; } ]; } The DOTS server SHOULD consider the efficacy update an indication of the effectiveness of any ongoing mitigations related to the eventid provided by the DOTS client. The DOTS server nonetheless MAY treat any efficacy update from the client as advisory, and is under no obligation to alter the mitigation strategy in response. Teague & Mortensen Expires May 21, 2017 [Page 22] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 5. Data Channel 5.1. Role Using the conventions established in [REST], the data channel provides an interface for configuration, black- and white-list management, traffic filter management, and extensibility required for future operator needs (GEN-001 [I-D.ietf-dots-requirements]). 5.2. Limitations Unlike the DOTS signal channel, the data channel potentially offers DOTS client operators limited direct control over the behavior of mitigations requested by the DOTS client. However, the DOTS data channel is not a general purpose application programming interface for mitigators with which a DOTS server is communicating. Certain countermeasure profiles for DDoS attacks are widely understood and deployed, but many remain specific to mitigation vendor implementations, making abstraction all but impossible. The DOTS data channel in this protocol is therefore focused on a limited subset of widely available and well understood mitigation actions, namely black- and white-listing, and rate-limiting. While managing filters and rate-limit policy over the DOTS data channel resembles the dissemination of flow specifications with a match and action on match in [RFC5575], the similarity is restricted to [RFC5575]'s traffic-rate action only in order to prevent a DOTS client from exerting influence over traffic not destined for the DOTS client's domain. 5.3. Transport The DOTS data channel relies on the semantics described in [REST], meaning any reliable application protocol enabling those semantics could be used. This document anticipates HTTP/1.1 over TLS [RFC7230] will be most widely deployed at the time of writing. Implementations of the DOTS protocol therefore MUST support data channels using HTTP/1.1 over TLS. However, this document also leaves open the possibility that the data channel MAY be implemented through such application transports as HTTP/2 [RFC7540] or the Quick UDP Internet Connection [I-D.hamilton-quic-transport-protocol] protocol, as well as other current and future protocols supporting [REST] semantics and the security requirements described in [I-D.ietf-dots-requirements]. Support for alternative secure REST transports for the data channel are deployment- and implementation-specific. Teague & Mortensen Expires May 21, 2017 [Page 23] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 DOTS data channel implementations MUST support the IPv4 [RFC0791] and IPv6 [RFC2460] protocols, and MUST support the "Happy Eyeballs" algorithm for dual stack deployments discussed in [RFC6555]. Implementations of the DOTS data channel MUST use TLS version 1.2 or higher. DOTS agents MUST NOT create a data channel with a peer agent requesting a lower TLS version, and SHOULD drop the connection immediately on detecting the peer DOTS agent does not support a required TLS version. Section 7 offers a more detailed discussion of data channel transport security, including cipher suites. 5.4. Authentication When establishing the data channel, the DOTS client and DOTS server MUST mutually authenticate each other, per SEC-001 in [I-D.ietf-dots-requirements]. A common method for mutual authentication for HTTP/1.1 over TLS is an exchange of X.509 certificates between client and server during the TLS handshake [RFC5246]; similar mechanisms exist in HTTP/2 [RFC7540] and in [I-D.hamilton-quic-transport-protocol]. Regardless of the underlying transport used, this document does not prescribe the method of mutual authentication, and alternatives may include a mix of things like basic auth [RFC7617] and HTTP SPNEGO [RFC4559]. The method of mutual authentication used for the data channel is left to the discretion of the DOTS server operator. Additional discussion of mutual authentication is below in Section 7. 5.5. Authorization TBD deployment-specific, see also security considerations. 5.6. Resources The DOTS server exposes data channel resources to the DOTS client as uniform resource identifiers. The DOTS client sends requests related to the data channel resources using the verbs defined in [RFC7231]: GET, POST, PUT, PATCH and DELETE. The DOTS server responds to the DOTS client requests with a status code and, if the request succeeded, available data returned by the request. The status codes used in DOTS server responses are also defined in [RFC7231]. Teague & Mortensen Expires May 21, 2017 [Page 24] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 5.6.1. Resource Root The root resource or endpoint in the DOTS data channel is /dots/v1/ data. The root resource MUST be prefixed to all resources exposed through the data channel. 5.6.2. {+dataroot}/sessions The /sessions endpoint is a read-only resource from which the DOTS client may request the status of signaling sessions. 5.6.2.1. GET {+dataroot}/sessions The DOTS client requests the list of signaling sessions by issuing a GET for the /sessions resource: GET /dots/v1/data/sessions HTTP/1.1 Host: dots-server.example.com Accept: application/json Figure 7: DOTS Client Requesting Session Status If the DOTS client is authorized, the DOTS server responds to the GET with a list of signaling session identifiers, as in the following example: HTTP/1.1 200 OK Cache-Control: no-cache Content-Type: application/json { "sessions": [ { "id": , "client": , "server": , "duration": , }, { ... } ] } The top-level JSON key-value pairs in the response are as follows: sessions: A list of dictionary objects describing active signaling sessions. If empty, no signaling sessions are active. Teague & Mortensen Expires May 21, 2017 [Page 25] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 Each dictionary within the sessions list contains the following JSON key-value pairs: id: An opaque alphanumeric string identifying the signaling session. client: The dotted-quad IPv4 or formatted IPv6 address [RFC5952] of the DOTS client in the signaling session. server: The dotted-quad IPv4 or formatted IPv6 address [RFC5952] of the DOTS server in the signaling session. duration: An ISO 8601 representation of the duration of the signaling session. 5.6.3. {+dataroot}/filters The /filters endpoint on a DOTS server is a read-write resource through which a DOTS client may request that the DOTS server add, retrieve, modify and delete traffic filters to an active mitigation requested through the signal channel. DOTS servers SHOULD indicate lack of support for filtering by returning a 501 Not Implemented status to any request for a filters URI. If a DOTS client attempts to apply a filter to flows which the DOTS server determines do not belong to the DOTS client, the DOTS server MUST respond with a 403 Forbidden. A filter is a match and an action on match. As discussed above in Section 5.2, actions are restricted to black- and white-listing and rate-limiting. Matches in a filter dictionary may be any of the match types discussed below. All matches MUST include a destination address or identifier; DOTS server implementations MUST NOT accept filters missing a destination address or prefix. A filter can be represented as a map or dictionary with the following attributes: id: a client-generated integer value acting as a unique identifier for the filter. af: address family of the flow to filter, must be one of "ipv4" or "ipv6". This attribute is required in all filters. src: source prefix of the flow(s) to filter. sport: source port of the flow(s) to filter. dst: destination prefix of the flow(s) to filter. Teague & Mortensen Expires May 21, 2017 [Page 26] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 dport: destination port of the flow(s) to filter. action: The action to apply to flows matching the filter. The action MUST be one of "blacklist" (i.e., drop all matching flows), "whitelist" (i.e., always forward traffic matching the filter), or "rate-limit" (i.e., control the rate of traffic matching the filter). Bps: an integer value setting the bytes per second limit for flows matching the filter when action is "rate-limit". 5.6.3.1. POST {+dataroot}/filters/{+mitigation-id} A POST request over the data channel to the /filters endpoint on a DOTS server permits a DOTS client to manage filtering policy for a mitigation: POST /dots/v1/data/filters/42 HTTP/1.1 Host: dots-server.example.com Accept: application/json Content-Type: application/json Content-Length: NNNN { "filters": [ { "id": 1, "af": "ipv4", "src": "192.0.2.2/32", "action": "blacklist", }, { "id": 2, "af": "ipv4", "src": "192.51.100.0/30", "sport": 53, "action": "whitelist", }, ... ] } Figure 8: Filter creation The DOTS server confirms filter creation with an empty OK: Teague & Mortensen Expires May 21, 2017 [Page 27] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 HTTP/1.1 200 OK Cache-Control: no-cache Content-Length: 0 5.6.3.2. PUT {+dataroot}/filters/{+mitigation-id}/{+filter-id} Filters may be updated by sending a PUT request to the specific filter URI. DOTS servers MUST replace the existing filter atomically with the values in the PUT. PUT /dots/v1/data/filters/42/1 HTTP/1.1 Host: dots-server.example.com Accept: application/json Content-Type: application/json Content-Length: NNNN { "id": 1, "af": "ipv4", "src": "192.0.2.2/32", "dst": "198.51.100.0/24", "action": "blacklist", } Figure 9: Filter Update The DOTS server confirms filter update with a No Content response: HTTP/1.1 204 No Content Cache-Control: no-cache Content-Length: 0 5.6.3.3. GET {+dataroot}/filters/{+mitigation-id} A GET request to the /filters endpoint on a DOTS server returns filters for a mitigation requested by the DOTS client. The mitigation-id value MUST be the DOTS client-generated mitigation ID used in a mitigation request previously sent to the DOTS server over the signal channel, with the exception of the global filter list as described below. A request listing the filters active during a mitigation is shown below in Figure 10: Teague & Mortensen Expires May 21, 2017 [Page 28] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 GET /dots/v1/data/filters/42 HTTP/1.1 Host: dots-server.example.com Accept: application/json Figure 10: Filter GET The DOTS server returns a list of active filters applied as part of the mitigation on the DOTS client's behalf as in Figure 11: HTTP/1.1 200 OK Cache-Control: no-cache Content-Type: application/json { "id": 42, "filters": [ { "id": 1, "af": "ipv4", "src": "192.0.2.2/32", "action": "blacklist", }, { "id": 2, "af": "ipv4", "src": "192.51.100.0/30", "sport": 53, "action": "whitelist", }, ] } Figure 11: Filter GET Response If the filter list is empty, no filters are applied as part of the mitigation. 5.6.4. {+dataroot}/config The /config data channel endpoint on a DOTS server is a read-write resource through which a DOTS client may configure global signaling session behavior. Teague & Mortensen Expires May 21, 2017 [Page 29] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 5.6.4.1. GET {+dataroot}/config A GET request to the /config endpoint returns the current DOTS configuration for the DOTS client: GET /dots/v1/data/config HTTP/1.1 Host: dots-server.example.com Accept: application/json Figure 12: DOTS Client Requesting Configuration HTTP/1.1 200 OK Cache-Control: Content-Type: application/json { "config": { "protected-resources": { : [ ] } } } 5.6.4.2. POST {+dataroot}/config/protected-resources/ TBD 5.6.5. Serialization Resource data is exchanged between DOTS client in a serialized format. Implementations MUST support JSON [RFC7159] serialization of resource data. DOTS clients MUST advertise support for JSON-encoded data from the DOTS server through the HTTP Accept header [RFC7231] (or an equivalent if not using HTTP), using the MIME type defined in [RFC7159], application/json: GET /dots/v1/data/sessions HTTP/1.1 Host: dots-server.example.com Accept: application/json Figure 13: DOTS Client Advertising Required Serialization Implementations MAY offer additional serialization formats as well. DOTS clients MAY advertise support for additional serialization formats in requests to the DOTS server through the HTTP Accept header Teague & Mortensen Expires May 21, 2017 [Page 30] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 [RFC7231] (or an equivalent if not using HTTP), as shown in the example HTTP/1.1 request below: GET /dots/v1/data/sessions HTTP/1.1 Host: dots-server.example.com Accept: application/json; q=0.5, application/cbor Figure 14: DOTS Client Supporting Additional Serializations If a DOTS server does not support the media types in the DOTS client's Accept header (or its equivalent), the DOTS server MUST respond with an status code indicating an error in the client request. In HTTP deployments, the DOTS server MUST return the 415 Unsupported Media Type error code defined in [RFC7231]. A DOTS client request lacking indicated support for application/json content suggests an invalid or malicious client implementation. After sending the 415 error response, DOTS servers SHOULD terminate the data channel connection with the invalid client. 5.6.6. Caching DOTS server responses sent over the DOTS data channel MUST NOT be cached by the DOTS client. DOTS server implementations therefore MUST include in responses a Cache-Control header with a value of "no- cache" [RFC7234]. 6. IANA Considerations The DOTS protocol requires a well-known port to which DOTS client messages are sent. The DOTS server listens on the well-known port for client messages. The DOTS client binds to an ephemeral port per Section 4.3.1 above. This document selects port 4646 (the ASCII decimal values for "..": "DOTS") as the well-known port. 7. Security Considerations 7.1. Data Channel Security The DOTS data channel acts as a management plane for DOTS signaling sessions. As discussed in the security considerations of [I-D.ietf-dots-architecture], an attacker with control over data channel may be able to blacklist or rate-limit any flows under the administrative control of the DOTS client. Extra care must therefore be taken when authenticating and authorizing the data channel. DOTS server operators SHOULD enforce access control policies restricting which clients are able to contact DOTS servers. Teague & Mortensen Expires May 21, 2017 [Page 31] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 7.2. Signal Channel Security The DOTS signal channel controls mitigation request and withdrawal and as such care must be taken to protect against concerns outlined in the security considerations of [I-D.ietf-dots-architecture]. 8. Appendix A: Message Schemas 8.1. DOTS Client Message Schema syntax = "proto3"; import "google/protobuf/any.proto"; message DOTSClientMessage { // Client generated sequence number uint64 seqno = 1; // Sequence number of last received server message uint64 last_svr_seqno = 2; repeated DOTSMitigation mitigations = 3; // Request active mitigation list from server bool active = 4; // Ping request (operator initiated) bool ping = 5; DOTSSessionConfig config = 6; repeated google.protobuf.Any extensions = 999; } Figure 15: DOTS Client Message Schema 8.2. Mitigation Request Schema Teague & Mortensen Expires May 21, 2017 [Page 32] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 message DOTSMitigation { // Opaque client-generated event identifier string eventid = 1; // Toggle mitigation for the above scope bool requested = 2; // Mitigation scope as described in I-D.ietf-dots-requirements string scope = 3; // Lifetime of the requested mitigation. uint32 lifetime = 4; // Mitigation efficacy score as a float value between 0 and 1 float efficacy = 5; repeated google.protobuf.Any extensions = 999; } Figure 16: DOTS Client Mitigation Request Schema 8.3. Session Configuration Schema // Per session configuration sent on signaling session init message DOTSSessionConfig { // Acceptable signal loss uint32 loss_limit = 1; // Maximum mitigation lifetime in seconds uint32 lifetime_max = 2; // Heartbeat interval in milliseconds uint32 heartbeat_interval = 3; } Figure 17: DOTS Session Conifiguration Schema 8.4. DOTS Server Message Schema Teague & Mortensen Expires May 21, 2017 [Page 33] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 syntax = "proto3"; import "google/protobuf/any.proto"; message DOTSServerMessage { // Server generated sequence number uint64 seqno = 1; // Sequence number of last received Client message uint64 last_client_seqno = 2; // Request immediate heartbeat response from client. bool ping = 3; // Server error details, if available DOTSServerError error = 4; DOTSRedirect redirect = 5; // Mitigation data, limited by MTU repeated DOTSMitigationStatus mitigations = 6; } Figure 18: DOTS Server Message Schema 8.5. DOTS Redirect Schema message DOTSRedirect { // Redirection target DOTS server address string target = 1; // Address family of redirection target enum RedirectionTargetType { DNSNAME = 0; IPV4 = 4; IPV6 = 6; } RedirectionTargetType target_type = 2; // Port on which to contact redirection target. // XXX Protobufs has no uint16 type, implementations // will need to sanity check. uint32 port = 3; } Teague & Mortensen Expires May 21, 2017 [Page 34] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 8.6. DOTS Mitigation Status Schema syntax = "proto3"; import "google/protobuf/any.proto"; message DOTSMitigationStatus { // Opaque Client generated event identifier, used by DOTS client // to associate a mitigation status with the event triggering the // mitigation request. string eventid = 1; // Mitigation state bool enabled = 2; // Mitigation time-to-live (lifetime - (now - start)) uint32 ttl = 3; // Dropped byte count uint64 bytes_dropped = 4; // Dropped bits per second uint64 bps_dropped = 5; // Dropped packet count uint64 pkts_dropped = 6; // Dropped packets per second uint64 pps_dropped = 7; // Blacklist enabled through data channel bool blacklist_enabled = 8; // Whitelist enabled through data channel bool whitelist_enabled = 9; // Filters enabled through data channel bool filters_enabled = 10; repeated google.protobuf.Any extensions = 999; } Figure 19: DOTS Server Mitigation Status Schema 8.7. Server Error Schema Teague & Mortensen Expires May 21, 2017 [Page 35] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 syntax = "proto3"; import "google/protobuf/any.proto"; message DOTSServerError { enum ErrorCode { NOERROR = 0; INVALID_VALUE = 1; MITIGATION_UNAVAILABLE = 2; MITIGATION_CONFLICT = 3; MALFORMED_MESSAGE = 4; } ErrorCode code = 1; // Error details, returned as a blob google.protobuf.Any details = 2; } Figure 20: DOTS Server Error Schema 9. References 9.1. Normative References [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, DOI 10.17487/RFC0768, August 1980, . [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, DOI 10.17487/RFC0791, September 1981, . [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, RFC 793, DOI 10.17487/RFC0793, September 1981, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ RFC2119, March 1997, . [RFC2460] Deering, S. and R. Hinden, "Internet Protocol, Version 6 (IPv6) Specification", RFC 2460, DOI 10.17487/RFC2460, December 1998, . [RFC2784] Farinacci, D., Li, T., Hanks, S., Meyer, D., and P. Traina, "Generic Routing Encapsulation (GRE)", RFC 2784, DOI 10.17487/RFC2784, March 2000, . Teague & Mortensen Expires May 21, 2017 [Page 36] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 [RFC3031] Rosen, E., Viswanathan, A., and R. Callon, "Multiprotocol Label Switching Architecture", RFC 3031, DOI 10.17487/ RFC3031, January 2001, . [RFC5405] Eggert, L. and G. Fairhurst, "Unicast UDP Usage Guidelines for Application Designers", BCP 145, RFC 5405, DOI 10.17487/RFC5405, November 2008, . [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/ RFC5246, August 2008, . [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 Address Text Representation", RFC 5952, DOI 10.17487/ RFC5952, August 2010, . [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, January 2012, . [RFC6555] Wing, D. and A. Yourtchenko, "Happy Eyeballs: Success with Dual-Stack Hosts", RFC 6555, DOI 10.17487/RFC6555, April 2012, . [RFC6698] Hoffman, P. and J. Schlyter, "The DNS-Based Authentication of Named Entities (DANE) Transport Layer Security (TLS) Protocol: TLSA", RFC 6698, DOI 10.17487/RFC6698, August 2012, . [RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed., "Enrollment over Secure Transport", RFC 7030, DOI 10.17487/RFC7030, October 2013, . [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2014, . [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, DOI 10.17487/RFC7230, June 2014, . Teague & Mortensen Expires May 21, 2017 [Page 37] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, June 2014, . [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", RFC 7234, DOI 10.17487/RFC7234, June 2014, . [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext Transfer Protocol Version 2 (HTTP/2)", RFC 7540, DOI 10.17487/RFC7540, May 2015, . [I-D.ietf-dots-architecture] Mortensen, A., Andreasen, F., Reddy, T., christopher_gray3@cable.comcast.com, c., Compton, R., and N. Teague, "Distributed-Denial-of-Service Open Threat Signaling (DOTS) Architecture", draft-ietf-dots- architecture-01 (work in progress), October 2016. [I-D.ietf-dots-requirements] Mortensen, A., Moskowitz, R., and T. Reddy, "Distributed Denial of Service (DDoS) Open Threat Signaling Requirements", draft-ietf-dots-requirements-03 (work in progress), October 2016. [I-D.hamilton-quic-transport-protocol] Hamilton, R., Iyengar, J., Swett, I., and A. Wilk, "QUIC: A UDP-Based Multiplexed and Secure Transport", draft- hamilton-quic-transport-protocol-01 (work in progress), October 2016. [PROTOBUF] Google, Inc., "Protocol Buffers", 2016, . [REST] Fielding, R., "Architectural Styles and the Design of Network-based Software Architectures", Ph.D. Dissertation, University of California, Irvine, 2000, . Teague & Mortensen Expires May 21, 2017 [Page 38] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 9.2. Informative References [RFC1518] Rekhter, Y. and T. Li, "An Architecture for IP Address Allocation with CIDR", RFC 1518, DOI 10.17487/RFC1518, September 1993, . [RFC1519] Fuller, V., Li, T., Yu, J., and K. Varadhan, "Classless Inter-Domain Routing (CIDR): an Address Assignment and Aggregation Strategy", RFC 1519, DOI 10.17487/RFC1519, September 1993, . [RFC4559] Jaganathan, K., Zhu, L., and J. Brezak, "SPNEGO-based Kerberos and NTLM HTTP Authentication in Microsoft Windows", RFC 4559, DOI 10.17487/RFC4559, June 2006, . [RFC5575] Marques, P., Sheth, N., Raszuk, R., Greene, B., Mauch, J., and D. McPherson, "Dissemination of Flow Specification Rules", RFC 5575, DOI 10.17487/RFC5575, August 2009, . [RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme", RFC 7617, DOI 10.17487/RFC7617, September 2015, . [CLOUDSIGNAL] Arbor Networks, Inc., "Cloud Signaling: A Faster, Automated Way to Mitigate DDoS Attacks", 2011, . [COMMUNITYFS] Team Cymru, Inc., "Community FlowSpec", 2011, . [OPENHYBRID] Verisign, Inc., "Verisign OpenHybrid", 2016, . [WISR] Arbor Networks, Inc., "Worldwide Infrastructure Security Report", 2016, . Teague & Mortensen Expires May 21, 2017 [Page 39] Internet-Draft DDoS Open Threat Signaling Protocol November 2016 Authors' Addresses Nik Teague Verisign, Inc. 12061 Bluemont Way Reston, VA 20190 United States Email: nteague@verisign.com Andrew Mortensen Arbor Networks, Inc. 2727 S. State St Ann Arbor, MI 48104 United States Email: amortensen@arbor.net Teague & Mortensen Expires May 21, 2017 [Page 40]