netconfcentral logo

ietf-dots-signal

HTML

ietf-dots-signal@2017-12-12



  module ietf-dots-signal {

    yang-version 1.1;

    namespace
      "urn:ietf:params:xml:ns:yang:ietf-dots-signal";

    prefix signal;

    import ietf-inet-types {
      prefix inet;
    }
    import ietf-yang-types {
      prefix yang;
    }
    import ietf-access-control-list {
      prefix ietf-acl;
    }

    organization
      "IETF DDoS Open Threat Signaling (DOTS) Working Group";

    contact
      "Konda, Tirumaleswar Reddy <TirumaleswarReddy_Konda@McAfee.com>
     Mohamed Boucadair <mohamed.boucadair@orange.com>
     Prashanth Patil <praspati@cisco.com>
     Andrew Mortensen <amortensen@arbor.net>
     Nik Teague <nteague@verisign.com>";

    description
      "This module contains YANG definition for the signaling
     messages exchanged between a DOTS client and a DOTS server.

     Copyright (c) 2017 IETF Trust and the persons identified as
     authors of the code.  All rights reserved.

     Redistribution and use in source and binary forms, with or
     without modification, is permitted pursuant to, and subject
     to the license terms contained in, the Simplified BSD License
     set forth in Section 4.c of the IETF Trust's Legal Provisions
     Relating to IETF Documents
     (http://trustee.ietf.org/license-info).

     This version of this YANG module is part of RFC XXXX; see
     the RFC itself for full legal notices.";

    revision "2017-12-12" {
      description "Initial revision.";
      reference
        "RFC XXXX: Distributed Denial-of-Service Open Threat
        	  Signaling (DOTS) Signal Channel";

    }


    grouping target {
      description
        "Specifies the scope of the mitigation request.";
      leaf-list target-prefix {
        type inet:ip-prefix;
        description
          "IPv4 or IPv6 prefix identifying the target.";
      }

      list target-port-range {
        key "lower-port upper-port";
        description
          "Port range. When only lower-port is
         present, it represents a single port.";
        leaf lower-port {
          type inet:port-number;
          mandatory true;
          description "Lower port number.";
        }

        leaf upper-port {
          type inet:port-number;
          must ". >= ../lower-port" {
            error-message
              "The upper port number must be greater than
              or equal to lower port number.";
          }
          description "Upper port number.";
        }
      }  // list target-port-range

      leaf-list target-protocol {
        type uint8;
        description
          "Identifies the target protocol number.

         The value '0' means 'all protocols'.

         Values are taken from the IANA protocol registry:
         https://www.iana.org/assignments/protocol-numbers/
         protocol-numbers.xhtml

         For example, 6 for TCP or 17 for UDP.";
      }

      leaf-list target-fqdn {
        type inet:domain-name;
        description
          "FQDN identifying the target.";
      }

      leaf-list target-uri {
        type inet:uri;
        description
          "URI identifying the target.";
      }

      leaf-list alias-name {
        type string;
        description "alias name";
      }
    }  // grouping target

    grouping mitigation-scope {
      description
        "Specifies the scope of the mitigation request.";
      leaf-list client-identifier {
        type binary;
        description
          "The client identifier may be conveyed by
         the DOTS gateway to propagate the DOTS client
         identification information from the gateway's client-side to the
         gateway's server-side, and from the gateway's
         server-side to the DOTS server.

         It allows the destination DOTS server to accept
         mitigation requests with scopes which the DOTS
         client is authorized to manage.";
      }

      list scope {
        key "mitigation-id";
        description
          "The scope of the request.";
        leaf mitigation-id {
          type int32;
          description
            "Mitigation request identifier.

           This identifier must be unique for each mitigation
           request bound to the DOTS client.";
        }

        uses target;

        leaf lifetime {
          type int32;
          units "seconds";
          default '3600';
          description
            "Indicates the lifetime of the mitigation request.";
          reference
            "RFC XXXX: Distributed Denial-of-Service Open Threat
            	  Signaling (DOTS) Signal Channel";

        }

        leaf mitigation-start {
          type int64;
          units "seconds";
          description
            "Mitigation start time is represented in seconds
           relative to 1970-01-01T00:00Z in UTC time.";
        }

        leaf status {
          type enumeration {
            enum
              "attack-mitigation-in-progress" {
              value 1;
              description
                "Attack mitigation is in progress (e.g., changing
               the network path to re-route the inbound traffic
               to DOTS mitigator).";
            }
            enum
              "attack-successfully-mitigated" {
              value 2;
              description
                "Attack is successfully mitigated (e.g., traffic
               is redirected to a DDOS mitigator and attack
               traffic is dropped or blackholed).";
            }
            enum "attack-stopped" {
              value 3;
              description
                "Attack has stopped and the DOTS client can
               withdraw the mitigation request.";
            }
            enum
              "attack-exceeded-capability" {
              value 4;
              description
                "Attack has exceeded the mitigation provider
               capability.";
            }
            enum
              "dots-client-withdrawn-mitigation" {
              value 5;
              description
                "DOTS client has withdrawn the mitigation
               request and the mitigation is active but
               terminating.";
            }
            enum
              "attack-mitigation-terminated" {
              value 6;
              description
                "Attack mitigation is now terminated.";
            }
            enum
              "attack-mitigation-withdrawn" {
              value 7;
              description
                "Attack mitigation is withdrawn.";
            }
            enum
              "attack-mitigation-rejected" {
              value 8;
              description
                "Attack mitigation is rejected.";
            }
          }
          config false;
          description
            "Indicates the status of a mitigation request.
           It must be included in responses only.";
        }

        container conflict-information {
          config false;
          description
            "Indicates that a conflict is detected.
             Must only be used for responses.";
          leaf conflict-status {
            type enumeration {
              enum
                "request-inactive-other-active" {
                value 1;
                description
                  "DOTS Server has detected conflicting mitigation
                   requests from different DOTS clients.
                   This mitigation request is currently inactive
                   until the conflicts are resolved. Another
                   mitigation request is active.";
              }
              enum "request-active" {
                value 2;
                description
                  "DOTS Server has detected conflicting mitigation
                   requests from different DOTS clients.
                   This mitigation request is currently active.";
              }
              enum "all-requests-inactive" {
                value 3;
                description
                  "DOTS Server has detected conflicting mitigation
                   requests from different DOTS clients.  All
                   conflicting mitigation requests are inactive.";
              }
            }
            description
              "Indicates the conflict status.
               It must be included in responses only.";
          }

          leaf conflict-cause {
            type enumeration {
              enum "overlapping-targets" {
                value 1;
                description
                  "Overlapping targets. conflict-scope provides
                    more details about the exact conflict.";
              }
              enum "conflict-with-whitelist" {
                value 2;
                description
                  "Conflicts with an existing white list.

                    This code is returned when the DDoS mitigation
                    detects that some of the source addresses/prefixes
                    listed in the white list ACLs are actually
                    attacking the target.";
              }
            }
            description
              "Indicates the cause of the conflict.
               It must be included in responses only.";
          }

          leaf retry-timer {
            type int32;
            units "seconds";
            description
              "The DOTS client must not re-send the
               same request before the expiry of this timer.
               It must be included in responses, only.";
          }

          container conflict-scope {
            description
              "Provides more information about the conflict scope.";
            uses target {
              when
                "../conflict-cause = 'overlapping-targets'";
            }

            list acl-list {
              when
                "../../conflict-cause = 'conflict-with-whitelist'";
              key "acl-name acl-type";
              description
                "List of conflicting ACLs";
              leaf acl-name {
                type leafref {
                  path
                    "/ietf-acl:access-lists/ietf-acl:acl"
                      + "/ietf-acl:acl-name";
                }
                description
                  "Reference to the conflicting ACL name bound to
                   a DOTS client.";
              }

              leaf acl-type {
                type leafref {
                  path
                    "/ietf-acl:access-lists/ietf-acl:acl"
                      + "/ietf-acl:acl-type";
                }
                description
                  "Reference to the conflicting ACL type bound to
                   a DOTS client.";
              }
            }  // list acl-list
          }  // container conflict-scope
        }  // container conflict-information

        leaf pkts-dropped {
          type yang:zero-based-counter64;
          config false;
          description
            "Number of dropped packets";
        }

        leaf bps-dropped {
          type yang:zero-based-counter64;
          config false;
          description
            "The average number of dropped bytes per second for
             the mitigation request since the attack
             mitigation is triggered.";
        }

        leaf bytes-dropped {
          type yang:zero-based-counter64;
          units "bytes";
          config false;
          description
            "Counter for dropped packets; in bytes.";
        }

        leaf pps-dropped {
          type yang:zero-based-counter64;
          config false;
          description
            "The average number of dropped packets per second
             for the mitigation request since the attack
             mitigation is triggered.";
        }
      }  // list scope
    }  // grouping mitigation-scope

    grouping signal-config {
      description
        "DOTS signal channel session configuration.";
      leaf session-id {
        type int32;
        mandatory true;
        description
          "An identifier for the DOTS signal channel
         session configuration data.";
      }

      leaf heartbeat-interval {
        type int16;
        units "seconds";
        default '30';
        description
          "DOTS agents regularly send heartbeats to each other
         after mutual authentication is successfully
         completed, in order to keep the DOTS signal channel
         open.

         '0' means that heartbeat mechanism is deactivated.";
        reference
          "RFC XXXX: Distributed Denial-of-Service Open Threat
          	  Signaling (DOTS) Signal Channel";

      }

      leaf missing-hb-allowed {
        type int16;
        default '5';
        description
          "Maximum number of missing heartbeats allowed.";
        reference
          "RFC XXXX: Distributed Denial-of-Service Open Threat
          	  Signaling (DOTS) Signal Channel";

      }

      leaf max-retransmit {
        type int16;
        default '3';
        description
          "Maximum number of retransmissions of a
         Confirmable message.";
        reference
          "RFC XXXX: Distributed Denial-of-Service Open Threat
          	  Signaling (DOTS) Signal Channel";

      }

      leaf ack-timeout {
        type int16;
        units "seconds";
        default '2';
        description
          "Initial retransmission timeout value.";
        reference
          "Section 4.8 of RFC 7552.";

      }

      leaf ack-random-factor {
        type decimal64 {
          fraction-digits 2;
        }
        default '1.5';
        description
          "Random factor used to influence the timing of
         retransmissions.";
        reference
          "Section 4.8 of RFC 7552.";

      }

      leaf trigger-mitigation {
        type boolean;
        default 'true';
        description
          "If false, then mitigation is triggered
         only when the DOTS server channel session is lost";
        reference
          "RFC XXXX: Distributed Denial-of-Service Open Threat
          	  Signaling (DOTS) Signal Channel";

      }

      leaf config-interval {
        type int32;
        units "minutes";
        description
          "This parameter is returned by a DOTS server to
         a requesting DOTS client to indicate the time interval
         after which the DOTS client must contact the DOTS
         server in order to retrieve the signal channel
         configuration data.

         This mechanism allows the update of the configuration
         data if a change occurs.

         For example, the new configuration may instruct
         a DOTS client to cease heartbeats or reduce
         heartbeat frequency.

         '0' is used to disable this refresh mechanism.";
      }
    }  // grouping signal-config

    container dots-signal {
      description
        "Main container for DOTS signal message.
       A DOTS signal message can be a mitigation message or
       a configuration message.";
      choice message-type {
        description
          "Either a mitigation or a configuration message.";
        case mitigation-scope {
          description
            "Mitigation scope of a mitigation message.";
          uses mitigation-scope;
        }  // case mitigation-scope

        case configuration {
          description
            "Configuration message.";
          uses signal-config;
        }  // case configuration
      }  // choice message-type
    }  // container dots-signal
  }  // module ietf-dots-signal

Summary

  
  
Organization IETF DDoS Open Threat Signaling (DOTS) Working Group
  
Module ietf-dots-signal
Version 2017-12-12
File ietf-dots-signal@2017-12-12.yang
  
Prefix signal
Namespace urn:ietf:params:xml:ns:yang:ietf-dots-signal
  
Cooked /cookedmodules/ietf-dots-signal/2017-12-12
YANG /src/ietf-dots-signal@2017-12-12.yang
XSD /xsd/ietf-dots-signal@2017-12-12.xsd
  
Abstract This module contains YANG definition for the signaling messages exchanged between a DOTS client and a DOTS server. Copyright (c...
  
Contact
Konda, Tirumaleswar Reddy <TirumaleswarReddy_Konda@McAfee.com>
Mohamed Boucadair <mohamed.boucadair@orange.com>
Prashanth Patil <praspati@cisco.com>
Andrew Mortensen <amortensen@arbor.net>
Nik Teague <nteague@verisign.com>

Description

 
This module contains YANG definition for the signaling
messages exchanged between a DOTS client and a DOTS server.

Copyright (c) 2017 IETF Trust and the persons identified as
authors of the code.  All rights reserved.

Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).

This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices.

Groupings

Grouping Objects Abstract
mitigation-scope client-identifier scope Specifies the scope of the mitigation request.
signal-config session-id heartbeat-interval missing-hb-allowed max-retransmit ack-timeout ack-random-factor trigger-mitigation config-interval DOTS signal channel session configuration.
target target-prefix target-port-range target-protocol target-fqdn target-uri alias-name Specifies the scope of the mitigation request.

Objects

Type Key
Mandatory config
Optional config
Not config
Object Type Abstract
dots-signal container Main container for DOTS signal message. A DOTS signal message can be a mitigation message or a configuration message.
   message-type choice Either a mitigation or a configuration message.
      configuration case Configuration message.
         ack-random-factor leaf Random factor used to influence the timing of retransmissions.
         ack-timeout leaf Initial retransmission timeout value.
         config-interval leaf This parameter is returned by a DOTS server to a requesting DOTS client to indicate the time interval after which the DOTS client must contact the DOTS server in order to retrieve the signal channel configuration data. This mechanism allows the update of...
         heartbeat-interval leaf DOTS agents regularly send heartbeats to each other after mutual authentication is successfully completed, in order to keep the DOTS signal channel open. '0' means that heartbeat mechanism is deactivated.
         max-retransmit leaf Maximum number of retransmissions of a Confirmable message.
         missing-hb-allowed leaf Maximum number of missing heartbeats allowed.
         session-id leaf An identifier for the DOTS signal channel session configuration data.
         trigger-mitigation leaf If false, then mitigation is triggered only when the DOTS server channel session is lost
      mitigation-scope case Mitigation scope of a mitigation message.
         client-identifier leaf-list The client identifier may be conveyed by the DOTS gateway to propagate the DOTS client identification information from the gateway's client-side to the gateway's server-side, and from the gateway's server-side to the DOTS server. It allows the destinatio...
         scope list The scope of the request.
            alias-name leaf-list alias name
            bps-dropped leaf The average number of dropped bytes per second for the mitigation request since the attack mitigation is triggered.
            bytes-dropped leaf Counter for dropped packets; in bytes.
            conflict-information container Indicates that a conflict is detected. Must only be used for responses.
               conflict-cause leaf Indicates the cause of the conflict. It must be included in responses only.
               conflict-scope container Provides more information about the conflict scope.
                  acl-list list List of conflicting ACLs
                     acl-name leaf Reference to the conflicting ACL name bound to a DOTS client.
                     acl-type leaf Reference to the conflicting ACL type bound to a DOTS client.
                  alias-name leaf-list alias name
                  target-fqdn leaf-list FQDN identifying the target.
                  target-port-range list Port range. When only lower-port is present, it represents a single port.
                     lower-port leaf Lower port number.
                     upper-port leaf Upper port number.
                  target-prefix leaf-list IPv4 or IPv6 prefix identifying the target.
                  target-protocol leaf-list Identifies the target protocol number. The value '0' means 'all protocols'. Values are taken from the IANA protocol registry: https://www.iana.org/assignments/protocol-numbers/ protocol-numbers.xhtml For example, 6 for TCP or 17 for UDP.
                  target-uri leaf-list URI identifying the target.
               conflict-status leaf Indicates the conflict status. It must be included in responses only.
               retry-timer leaf The DOTS client must not re-send the same request before the expiry of this timer. It must be included in responses, only.
            lifetime leaf Indicates the lifetime of the mitigation request.
            mitigation-id leaf Mitigation request identifier. This identifier must be unique for each mitigation request bound to the DOTS client.
            mitigation-start leaf Mitigation start time is represented in seconds relative to 1970-01-01T00:00Z in UTC time.
            pkts-dropped leaf Number of dropped packets
            pps-dropped leaf The average number of dropped packets per second for the mitigation request since the attack mitigation is triggered.
            status leaf Indicates the status of a mitigation request. It must be included in responses only.
            target-fqdn leaf-list FQDN identifying the target.
            target-port-range list Port range. When only lower-port is present, it represents a single port.
               lower-port leaf Lower port number.
               upper-port leaf Upper port number.
            target-prefix leaf-list IPv4 or IPv6 prefix identifying the target.
            target-protocol leaf-list Identifies the target protocol number. The value '0' means 'all protocols'. Values are taken from the IANA protocol registry: https://www.iana.org/assignments/protocol-numbers/ protocol-numbers.xhtml For example, 6 for TCP or 17 for UDP.
            target-uri leaf-list URI identifying the target.