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
"WG Web:
WG List:
Editor: Konda, Tirumaleswar Reddy
Editor: Mohamed Boucadair
Author: Prashanth Patil
Author: Andrew Mortensen
Author: Nik Teague
";
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 2018-01-09 {
description
"Initial revision.";
reference
"RFC XXXX: Distributed Denial-of-Service Open Threat
Signaling (DOTS) Signal Channel";
}
grouping target {
description
"Specifies the targets 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.";
}
}
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 mitigation-scope {
description
"Specifies the scope of the mitigation request.";
leaf client-domain-hash {
type string;
description
"The client domain hash may be conveyed by
the server-domain DOTS gateway to propagate the
client domain 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 may be used by the final DOTS server
for policy enforcement purposes.";
}
list scope {
key "cuid mitigation-id";
description
"The scope of the request.";
leaf cuid {
type string;
description
"A unique identifier that is randomly
generated by a DOTS client to prevent
request collisions.";
}
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.";
}
enum "cuid-collision" {
value 3;
description
"Conflicts with the CUID used by another
DOTS client of the same domain.";
}
}
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.";
}
}
}
}
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.";
}
leaf attack-status {
type enumeration {
enum "under-attack" {
value 1;
description
"The DOTS client determines that it is still under
attack.";
}
enum "attack-successfully-mitigated" {
value 2;
description
"The DOTS client determines that the attack is
successfully mitigated.";
}
}
description
"Indicates the status of an attack as seen by the
DOTS client.";
}
}
}
grouping config-parameters {
description
"Subset of DOTS signal channel session configuration.";
container heartbeat-interval {
description
"DOTS agents regularly send heartbeats to each other
after mutual authentication is successfully
completed in order to keep the DOTS signal channel
open.";
leaf max-value {
type int16;
units "seconds";
description
"Maximum acceptable value.";
reference
"RFC XXXX: Distributed Denial-of-Service Open Threat
Signaling (DOTS) Signal Channel";
}
leaf min-value {
type int16;
units "seconds";
description
"Minimum acceptable value.";
reference
"RFC XXXX: Distributed Denial-of-Service Open Threat
Signaling (DOTS) Signal Channel";
}
leaf current-value {
type int16;
units "seconds";
default 30;
description
"Current value.
'0' means that heartbeat mechanism is deactivated.";
reference
"RFC XXXX: Distributed Denial-of-Service Open Threat
Signaling (DOTS) Signal Channel";
}
}
container missing-hb-allowed {
description
"Maximum number of missing heartbeats allowed.";
leaf max-value {
type int16;
description
"Maximum acceptable value.";
reference
"RFC XXXX: Distributed Denial-of-Service Open Threat
Signaling (DOTS) Signal Channel";
}
leaf min-value {
type int16;
description
"Minimum acceptable value.";
reference
"RFC XXXX: Distributed Denial-of-Service Open Threat
Signaling (DOTS) Signal Channel";
}
leaf current-value {
type int16;
default 5;
description
"Current value.";
reference
"RFC XXXX: Distributed Denial-of-Service Open Threat
Signaling (DOTS) Signal Channel";
}
}
container max-retransmit {
description
"Maximum number of retransmissions of a Confirmable
message.";
leaf max-value {
type int16;
description
"Maximum acceptable value.";
reference
"Section 4.8 of RFC 7552.";
}
leaf min-value {
type int16;
description
"Minimum acceptable value.";
reference
"Section 4.8 of RFC 7552.";
}
leaf current-value {
type int16;
default 3;
description
"Current value.";
reference
"RFC XXXX: Distributed Denial-of-Service Open Threat
Signaling (DOTS) Signal Channel";
}
}
container ack-timeout {
description
"Initial retransmission timeout value.";
leaf max-value {
type int16;
units "seconds";
description
"Maximum value.";
reference
"Section 4.8 of RFC 7552.";
}
leaf min-value {
type int16;
units "seconds";
description
"Minimum value.";
reference
"Section 4.8 of RFC 7552.";
}
leaf current-value {
type int16;
units "seconds";
default 2;
description
"Current value.";
reference
"Section 4.8 of RFC 7552.";
}
}
container ack-random-factor {
description
"Random factor used to influence the timing of
retransmissions.";
leaf max-value-decimal {
type decimal64 {
fraction-digits 2;
}
description
"Maximum acceptable value.";
reference
"Section 4.8 of RFC 7552.";
}
leaf min-value-decimal {
type decimal64 {
fraction-digits 2;
}
description
"Minimum acceptable value.";
reference
"Section 4.8 of RFC 7552.";
}
leaf current-value-decimal {
type decimal64 {
fraction-digits 2;
}
default 1.5;
description
"Current value.";
reference
"Section 4.8 of RFC 7552.";
}
}
}
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.";
}
container mitigating-config {
description
"Configuration parameters to use when a mitigation is active.";
uses config-parameters;
}
container idle-config {
description
"Configuration parameters to use when no mitigation is
active.";
uses config-parameters;
}
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 "seconds";
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 redirected-signal {
description
"Grouping for the redirected signaling.";
leaf alt-server {
type string;
mandatory true;
description
"Alias of an alternate server.";
}
list alt-server-record {
key "addr";
description
"List of records for the alternate server.";
leaf addr {
type inet:ip-address;
description
"IPv4 or IPv6 address identifying the server.";
}
leaf ttl {
type int32;
description
"TTL associated with this record.";
}
}
}
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
"Can be a mitigation, a configuration, or a redirect
message.";
case mitigation-scope {
description
"Mitigation scope of a mitigation message.";
uses mitigation-scope;
}
case signal-config {
description
"Configuration message.";
uses signal-config;
}
case redirected-signal {
description
"Redirected signaling.";
uses redirected-signal;
}
}
}
}