Skip to main content

DDoS Open Threat Signaling Protocol
draft-teague-dots-protocol-00

The information below is for an old version of the document.
Document Type
This is an older version of an Internet-Draft whose latest revision state is "Expired".
Authors Nik Teague , Andrew Mortensen
Last updated 2016-10-31
RFC stream (None)
Formats
Stream Stream state (No stream defined)
Consensus boilerplate Unknown
RFC Editor Note (None)
IESG IESG state I-D Exists
Telechat date (None)
Responsible AD (None)
Send notices to (None)
draft-teague-dots-protocol-00
DOTS                                                           N. Teague
Internet-Draft                                            Verisign, Inc.
Intended status: Standards Track                            A. Mortensen
Expires: May 4, 2017                                Arbor Networks, Inc.
                                                        October 31, 2016

                  DDoS Open Threat Signaling Protocol
                     draft-teague-dots-protocol-00

Abstract

   This document describes Distributed-Denial-of-Service (DDoS) Open
   Threat Signaling (DOTS), a signaling 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 4, 2017                   [Page 1]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 2016

   This Internet-Draft will expire on May 4, 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

Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
     1.1.  Terminology  . . . . . . . . . . . . . . . . . . . . . . .  5
   2.  Architecture . . . . . . . . . . . . . . . . . . . . . . . . .  5
     2.1.  DOTS Agents  . . . . . . . . . . . . . . . . . . . . . . .  5
   3.  Protocol Overview  . . . . . . . . . . . . . . . . . . . . . .  6
   4.  Signal Channel . . . . . . . . . . . . . . . . . . . . . . . .  6
     4.1.  Minimum Viable Information . . . . . . . . . . . . . . . .  7
     4.2.  Signal Channel Messages  . . . . . . . . . . . . . . . . .  8
       4.2.1.  Client Message Schema  . . . . . . . . . . . . . . . .  8
         4.2.1.1.  Client Message Schema Fields . . . . . . . . . . .  9
       4.2.2.  Client Mitigation Request Schema . . . . . . . . . . . 10
         4.2.2.1.  Client Mitigation Request Schema Fields  . . . . . 10
       4.2.3.  DOTS Server Message Schema . . . . . . . . . . . . . . 11
         4.2.3.1.  Server Message Schema Fields . . . . . . . . . . . 12
       4.2.4.  Server Error Schema  . . . . . . . . . . . . . . . . . 13
         4.2.4.1.  Server Error Schema Fields . . . . . . . . . . . . 14
       4.2.5.  Server Mitigation Status Schema  . . . . . . . . . . . 15
         4.2.5.1.  Server Mitigation Status Schema Fields . . . . . . 16
     4.3.  Interactions . . . . . . . . . . . . . . . . . . . . . . . 16
       4.3.1.  Session Initialization . . . . . . . . . . . . . . . . 16
         4.3.1.1.  Session Initialization Error Handling  . . . . . . 18
         4.3.1.2  Mis-Sequencing  . . . . . . . . . . . . . . . . . . 18
       4.3.2.  Heartbeat  . . . . . . . . . . . . . . . . . . . . . . 18
         4.3.2.1.  Ping . . . . . . . . . . . . . . . . . . . . . . . 21
       4.3.3.  Mitigation Request Handling  . . . . . . . . . . . . . 21
       4.3.4.  Ancillary Messages . . . . . . . . . . . . . . . . . . 23
 

Teague & Mortensen        Expires May 4, 2017                   [Page 2]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 2016

         4.3.4.1.  Mitigation Feedback  . . . . . . . . . . . . . . . 24
         4.3.4.2.  Mitigation Lifetime Update . . . . . . . . . . . . 24
         4.3.4.3.  Mitigation Efficacy Updates  . . . . . . . . . . . 25
   5.  Data Channel . . . . . . . . . . . . . . . . . . . . . . . . . 26
     5.1.  Role . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
     5.2.  Limitations  . . . . . . . . . . . . . . . . . . . . . . . 26
     5.3.  Transport  . . . . . . . . . . . . . . . . . . . . . . . . 26
     5.4.  Authentication . . . . . . . . . . . . . . . . . . . . . . 27
     5.5.  Authorization  . . . . . . . . . . . . . . . . . . . . . . 27
     5.6.  Resources  . . . . . . . . . . . . . . . . . . . . . . . . 27
       5.6.1.  Resource Root  . . . . . . . . . . . . . . . . . . . . 28
       5.6.2.  {+dataroot}/sessions . . . . . . . . . . . . . . . . . 28
         5.6.2.1.  GET {+dataroot}/sessions . . . . . . . . . . . . . 28
       5.6.3.  {+dataroot}/filters  . . . . . . . . . . . . . . . . . 29
         5.6.3.1.  POST {+dataroot}/filters/{+mitigation-id}  . . . . 30
         5.6.3.2.  PUT {+dataroot}/filters/{ 
                   mitigation-id}/{+filter-id}  . . . . . . . . . . . 31
         5.6.3.3.  GET {+dataroot}/filters/{+mitigation-id} . . . . . 31
       5.6.4.  {+dataroot}/config . . . . . . . . . . . . . . . . . . 32
         5.6.4.1.  GET {+dataroot}/config . . . . . . . . . . . . . . 33
         5.6.4.2.  POST {+dataroot}/config/protected-resources/ . . . 33
       5.6.5.  Serialization  . . . . . . . . . . . . . . . . . . . . 33
       5.6.6.  Caching  . . . . . . . . . . . . . . . . . . . . . . . 34
   6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 34
     6.1.  Data Channel Security  . . . . . . . . . . . . . . . . . . 34
     6.2. Signal Channel Security . . . . . . . . . . . . . . . . . . 34
   7.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 34
     7.1.  Normative References . . . . . . . . . . . . . . . . . . . 35
     7.2.  Informative References . . . . . . . . . . . . . . . . . . 38
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 39

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.

 

Teague & Mortensen        Expires May 4, 2017                   [Page 3]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 2016

   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.

   DOTS is not intended as a replacement for such protocols as BGP Flow
   Specification [RFC5575] or as a general purpose mitigation
   application programming interface (API), but rather as an advisory
   protocol enabling attack response coordination between willing
   domains.  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.

 

Teague & Mortensen        Expires May 4, 2017                   [Page 4]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 2016

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

   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:

 

Teague & Mortensen        Expires May 4, 2017                   [Page 5]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 2016

       +----+      +----+      +----+
       | 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.  For the purpose of this draft, however, a
   default signaling transport based upon UDP [RFC5405] will be used.
   UDP's connectionless quality lends itself to being able to sustain
   loose communications during an event which may heavily congest
   certain network paths towards the DOTS signal originating network.
   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
 

Teague & Mortensen        Expires May 4, 2017                   [Page 6]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 2016

   also be treated adversely by middleboxes with restrictive policies or
   may fall foul of aggressive filtering.

   In support of operational requirements for protocol efficiency in
   [I-D.ietf-dots-requirements], the signaling channel uses Protocol
   Buffers [PROTOBUF], also known as Protobufs, to encode messages
   exchanged between DOTS agents.  Thanks to Protobufs' serialization,
   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.

   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 communicaring 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
   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
 

Teague & Mortensen        Expires May 4, 2017                   [Page 7]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 2016

   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

   The DOTS protocol signal channel uses Protobufs to reduce the number
   of discrete messages to just a single message superset per direction,
   with function defined by the chosen fields contained within the
   message.  The protocol therefore defines a single schema each for the
   client and server sides containing all relevant fields.  Tags 1
   through 15 may benefit from only requiring a single byte to encode
   (vs two for tags 16 through 2047) and these should be used for
   frequently occurring message elements.

4.2.1.  Client Message Schema

   The entire client schema is detailed in Figure 3.  It is not expected
   that client messages will require all fields to be used
   simultaneously but instead a subset to convey a given signal type.
   The only fields which may be common to all signals are seqno and
   lastsvrseqno which may be used to detect loss or drop outs.  The DOTS
   client message schema is defined in Figure 3 below:

 

Teague & Mortensen        Expires May 4, 2017                   [Page 8]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 2016

       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;

         // 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;
         }
         DOTSSessionConfig config = 6;

         repeated google.protobuf.Any extensions;
       }

                   Figure 3: DOTS Client Message Schema

4.2.1.1.  Client Message Schema Fields

   The fields in the DOTS client signal channel message schema 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.
 

Teague & Mortensen        Expires May 4, 2017                   [Page 9]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 2016

   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.

   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.2.  Client Mitigation Request Schema

   The schema for mitigation requests sent by the DOTS client is defined
   in Figure 4 below:

       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;
       }

              Figure 4: DOTS Client Mitigation Request Schema

4.2.2.1.  Client Mitigation Request Schema Fields

   The fields in the DOTS client mitigation request schema are as
   follows:

 

Teague & Mortensen        Expires May 4, 2017                  [Page 10]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 2016

   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.  XXX - The efficacy value is calculated as

   extensions:  these fields may be used to provide implementation-
      specific mitigation details.

4.2.3.  DOTS Server Message Schema

   The entire server schema is detailed in Figure 5.  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].

 

Teague & Mortensen        Expires May 4, 2017                  [Page 11]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 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;

         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;
         }
         DOTSRedirect redirect = 5;

         // Mitigation data, limited by MTU
         repeated DOTSMitigationStatus mitigations = 6;
       }

                   Figure 5: DOTS Server Message Schema

4.2.3.1.  Server Message Schema Fields

   The fields in the DOTS server signal channel message schema have the
   following functions:

   seqno:  a server generated sequence number unique to the message.

 

Teague & Mortensen        Expires May 4, 2017                  [Page 12]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 2016

   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.4.  Server Error Schema

   The schema for server error information is described in Figure 6
   below:

       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 6: DOTS Server Error Schema

   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
 

Teague & Mortensen        Expires May 4, 2017                  [Page 13]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 2016

   the error response itself may be lost, a DOTS client may continue
   sending problematic messages regardless of the DOTS server's error
   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.

   Errors may 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.4.1.  Server Error Schema Fields

   code:  a numeric code categorizing the error type detected by the
      DOTS server.

   details:  specific information about the reason for the detected
      error.

 

Teague & Mortensen        Expires May 4, 2017                  [Page 14]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 2016

4.2.5.  Server Mitigation Status Schema

   The schema for the status of mitigations managed by the DOTS server
   are described in Figure 7 below:

     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))
       uint64 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 = 11;
     }

              Figure 7: DOTS Server Mitigation Status Schema

 

Teague & Mortensen        Expires May 4, 2017                  [Page 15]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 2016

4.2.5.1.  Server Mitigation Status Schema 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.

   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 (the hex value for the ASCII character "." twice).
   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
 

Teague & Mortensen        Expires May 4, 2017                  [Page 16]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 2016

   transport-specific documents.  Regardless of transport, DOTS
   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 8 below:

       message DOTSClientMessage {
         1 (seqno) = %;
         2 (last_svr_seqno) = %;
         6 (config) = {
           1 (loss_limit) = %;
           3 (heartbeat_interval) = %;
         };
       }

              Figure 8: 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.3 [I-D.rescorla-tls-dtls13].  In Figure 9 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 4, 2017                  [Page 17]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 2016

      Client                           Server
        |                                 |
        |---UDP connect to Server:4646--->|
        |                                 |
        |<- - - -DTLS1.3 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.
        |                                 |
        \ (min heartbeat interval passes) \
        /                                 /
        \                                 \
        |----------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 9: 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_server_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
   containing the sending DOTS agent's message sequence number and the
 

Teague & Mortensen        Expires May 4, 2017                  [Page 18]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 2016

   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 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.

   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 {fig-heartbeats}:

 

Teague & Mortensen        Expires May 4, 2017                  [Page 19]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 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 remains 1
       |          last_svr_seqno = 3     |
       |                                 |

                 Figure 10: 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 4, 2017                  [Page 20]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 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 {minimum-
   viable-information}.  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 4, 2017                  [Page 21]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 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 4, 2017                  [Page 22]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 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 4, 2017                  [Page 23]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 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 4, 2017                  [Page 24]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 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 4, 2017                  [Page 25]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 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 4, 2017                  [Page 26]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 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 6 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 6.

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 4, 2017                  [Page 27]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 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 11: 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": <string>,
                   "client": <ip_address>,
                   "server": <ip_address>,
                   "duration": <iso8601_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 4, 2017                  [Page 28]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 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 4, 2017                  [Page 29]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 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 12: Filter creation

   The DOTS server confirms filter creation with an empty OK:

 

Teague & Mortensen        Expires May 4, 2017                  [Page 30]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 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 13: 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 14:

 

Teague & Mortensen        Expires May 4, 2017                  [Page 31]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 2016

       GET /dots/v1/data/filters/42 HTTP/1.1
       Host: dots-server.example.com
       Accept: application/json

                           Figure 14: 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 15:

       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 15: 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 4, 2017                  [Page 32]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 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 16: DOTS Client Requesting Configuration

   HTTP/1.1 200 OK
   Cache-Control:
   Content-Type: application/json

   {
       "config": {
           "protected-resources": {
               <alnum_id>: [
               ]
           }
       }
   }

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 17: 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 4, 2017                  [Page 33]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 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 18: 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.  Security Considerations

6.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.

6.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].

7.  References

 

Teague & Mortensen        Expires May 4, 2017                  [Page 34]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 2016

7.1.  Normative References

   [RFC0768]  Postel, J., "User Datagram Protocol", STD 6, RFC 768, DOI
              10.17487/RFC0768, August 1980,
              <http://www.rfc-editor.org/info/rfc768>.

   [RFC0791]  Postel, J., "Internet Protocol", STD 5, RFC 791, DOI
              10.17487/RFC0791, September 1981,
              <http://www.rfc-editor.org/info/rfc791>.

   [RFC0793]  Postel, J., "Transmission Control Protocol", STD 7, RFC
              793, DOI 10.17487/RFC0793, September 1981,
              <http://www.rfc-editor.org/info/rfc793>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/
              RFC2119, March 1997,
              <http://www.rfc-editor.org/info/rfc2119>.

   [RFC2460]  Deering, S. and R. Hinden, "Internet Protocol, Version 6
              (IPv6) Specification", RFC 2460, DOI 10.17487/RFC2460,
              December 1998, <http://www.rfc-editor.org/info/rfc2460>.

   [RFC2784]  Farinacci, D., Li, T., Hanks, S., Meyer, D., and P.
              Traina, "Generic Routing Encapsulation (GRE)", RFC 2784,
              DOI 10.17487/RFC2784, March 2000,
              <http://www.rfc-editor.org/info/rfc2784>.

   [RFC3031]  Rosen, E., Viswanathan, A., and R. Callon, "Multiprotocol
              Label Switching Architecture", RFC 3031, DOI 10.17487/
              RFC3031, January 2001,
              <http://www.rfc-editor.org/info/rfc3031>.

   [RFC5405]  Eggert, L. and G. Fairhurst, "Unicast UDP Usage Guidelines
              for Application Designers", BCP 145, RFC 5405, DOI
              10.17487/RFC5405, November 2008,
              <http://www.rfc-editor.org/info/rfc5405>.

   [RFC5246]  Dierks, T. and E. Rescorla, "The Transport Layer Security
              (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/
              RFC5246, August 2008,
              <http://www.rfc-editor.org/info/rfc5246>.

   [RFC5952]  Kawamura, S. and M. Kawashima, "A Recommendation for IPv6
              Address Text Representation", RFC 5952, DOI 10.17487/
              RFC5952, August 2010,
              <http://www.rfc-editor.org/info/rfc5952>.
 

Teague & Mortensen        Expires May 4, 2017                  [Page 35]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 2016

   [RFC6555]  Wing, D. and A. Yourtchenko, "Happy Eyeballs: Success with
              Dual-Stack Hosts", RFC 6555, DOI 10.17487/RFC6555, April
              2012, <http://www.rfc-editor.org/info/rfc6555>.

 

Teague & Mortensen        Expires May 4, 2017                  [Page 36]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 2016

   [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, <http://www.rfc-editor.org/info/rfc6698>.

   [RFC7030]  Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed.,
              "Enrollment over Secure Transport", RFC 7030, DOI
              10.17487/RFC7030, October 2013,
              <http://www.rfc-editor.org/info/rfc7030>.

   [RFC7159]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
              Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
              2014, <http://www.rfc-editor.org/info/rfc7159>.

   [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,
              <http://www.rfc-editor.org/info/rfc7230>.

   [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,
              <http://www.rfc-editor.org/info/rfc7231>.

   [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,
              <http://www.rfc-editor.org/info/rfc7234>.

   [RFC7540]  Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext
              Transfer Protocol Version 2 (HTTP/2)", RFC 7540, DOI
              10.17487/RFC7540, May 2015,
              <http://www.rfc-editor.org/info/rfc7540>.

   [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-00 (work in progress), July 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-02 (work in
              progress), July 2016.

 

Teague & Mortensen        Expires May 4, 2017                  [Page 37]
Internet-Draft    DDoS Open Threat Signaling Protocol       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-00 (work in progress),
              July 2016.

   [I-D.rescorla-tls-dtls13]
              Rescorla, E. and H. Tschofenig, "The Datagram Transport
              Layer Security (DTLS) Protocol Version 1.3", draft-
              rescorla-tls-dtls13-00 (work in progress), October 2016.

   [PROTOBUF]
              Google, Inc., "Protocol Buffers", 2016,
              <https://developers.google.com/protocol-buffers/>.

   [REST]     Fielding, R., "Architectural Styles and the Design of
              Network-based Software Architectures", Ph.D. Dissertation,
              University of California, Irvine, 2000,
              <http://www.ics.uci.edu/~fielding/pubs/dissertation/
              fielding_dissertation.pdf>.

7.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, <http://www.rfc-editor.org/info/rfc1518>.

   [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, <http://www.rfc-editor.org/info/rfc1519>.

   [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,
              <http://www.rfc-editor.org/info/rfc4559>.

   [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,
              <http://www.rfc-editor.org/info/rfc5575>.

   [RFC7617]  Reschke, J., "The 'Basic' HTTP Authentication Scheme", RFC
              7617, DOI 10.17487/RFC7617, September 2015,
              <http://www.rfc-editor.org/info/rfc7617>.

 

Teague & Mortensen        Expires May 4, 2017                  [Page 38]
Internet-Draft    DDoS Open Threat Signaling Protocol       October 2016

   [CLOUDSIGNAL]
              Arbor Networks, Inc., "Cloud Signaling: A Faster,
              Automated Way to Mitigate DDoS Attacks", 2011,
              <https://www.arbornetworks.com/cloud-signaling-a-faster-
              automated-way-to-mitigate-ddos-attacks>.

   [COMMUNITYFS]
              Team Cymru, Inc., "Community FlowSpec", 2011,
              <https://www.cymru.com/jtk/misc/community-fs.html>.

   [OPENHYBRID]
              Verisign, Inc., "Verisign OpenHybrid", 2016,
              <http://www.verisign.com/en_US/security-services/ddos-
              protection/open-api/index.xhtml>.

   [WISR]     Arbor Networks, Inc., "Worldwide Infrastructure Security
              Report", 2016,
              <https://www.arbornetworks.com/images/documents/
              WISR2016_EN_Web.pdf>.

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 4, 2017                  [Page 39]