etsi-qkd-sdn-node.yang

module etsi-qkd-sdn-node {

  yang-version "1";

  namespace "urn:etsi:qkd:yang:etsi-qkd-node";

  prefix "etsi-qkdn";
  
  import ietf-yang-types { prefix "yang"; }
  import ietf-inet-types { prefix "inet"; }
  import etsi-qkd-node-types { prefix "etsi-qkdn-types"; }

  // meta
  organization "ETSI ISG QKD";

  contact
    "https://www.etsi.org/committee/qkd
    vicente@fi.upm.es";

  description
    "This module contains the groupings and containers composing 
    the software-defined QKD node information models
    specified in ETSI GS QKD 015.";

  revision "2020-09-30" {
    description
      "First definition based on initial requirement analysis.";
  }

  container sdqkd_node {
    description
      "Top module describing a software-defined QKD node (SD-QKD node).";

    leaf node_id {
      type yang:uuid;
      mandatory true;
      description
        "This value reflects the unique ID of the SD-QKD node.";
    }

    leaf location_id {
      type string;
      default "";
      description
        "This value enables the location of the secure
        area that contains the SD-QKD node to be specified.";
    }

    container qkd_capabilities {
      uses qkd_capabilities_top;
      description "Capabilities of the SD-QKD node.";
    }
    
    container qkd_applications {
      uses qkd_applications_top;
      description "List of applications that are currently registered
        in the SD-QKD node. Any entity consuming QKD-derived keys (either 
        for internal or external purposes) is considered an application.";
    }

    container qkd_interfaces {
      uses qkd_interfaces_top;
      description "List of physical QKD modules in a secure location,
        abstracted as interfaces of the SD-QKD node.";
    }

    container qkd_links {
      uses qkd_links_top;
      description "List of (key association) links to other SD-QKD nodes in the network.
        The links can be physical (direct quantum channel) or virtual multi-hop 
        connection doing key-relay through several nodes.";
    }
  }

  grouping qkd_capabilities_top{
      
      leaf link_stats_support {
        type boolean;
        default true;
        description
          "If true, this SD-QKD node exposes link-related statistics (key
          generation rate, link consumption, status).";
      }

      leaf application_stats_support {
        type boolean;
        default true;
        description
          "If true, the SD-QKD node exposes application related 
          statistics (application consumption, alerts).";
      }

      leaf key_relay_mode_enable {
        type boolean;
        default true;
        description
          "If true, the SD-QKD node supports key relay (multi-hop) mode services.";
      }

  }

  grouping qkd_applications_top{
    
      list qkd_application {
        key "app_id";

        leaf app_id {
          type yang:uuid;
          description 
            "This value uniquely identifies a pair of applications
            extracting keys from a QKD key association link. This value is similar
            to a key ID or key handle.";
        }

        container qos {

          leaf max_bandwidth {
            type uint32;
            description "Maximum bandwidth (bps) allowed for this specific
              application. Exceeding this value will raise an error
              from the local key store to the application. This value might
              be internally configured (or by an administrator).";
          }

          leaf min_bandwidth {
            type uint32;
            description "This value is an optional QoS parameter
              indicating the minimum key rate that the application is expected
              to request (in bits per second).";
          }

          leaf jitter {
            type uint32;
            description "This value allows a maximum time
              jitter (msec) of keys provided by the key delivery API to be specified, for
              applications requiring fast rekeying. This value can
              be coordinated with the other QoS to provide a wide
              enough QoS definition.";
          }

          leaf ttl {
            type uint32;
            description "Time To Live (sec) specifies the maximum
              time a key can have been stored before delivery to 
              an application.";
          }

          leaf clients_shared_path_enable {
            type boolean;
            default false;
            description "If true, multiple clients for this application
              might share paths across the network (rather than having
              disjoint paths) to reduce service impact (consumption).";
          }

          leaf clients_shared_keys_required {
            type boolean;
            default false;
            description "If true, multiple clients for this application
              might share keys to reduce service impact (consumption).";
          }

        }

        leaf type {
          type identityref {
            base etsi-qkdn-types:QKD-APP-TYPES;
          }
          description "Type of the registered application. These
            values, defined within the types module, can be client
            (external applications requesting keys)
            or internal (application is defined to maintain
            the QKD network - e.g. multi-hop, authentication or
            other encryption operations).";
        }

        leaf server_app_id {
          type inet:uri;
          description "ID of the server application connecting to
            the key store.";
        }

        leaf-list client_app_id {
          type inet:uri;
          description "ID of the client application connecting to
            the key server of the peer SD-QKD node. It is considered
            as the client from the security perspective.";
        }

        leaf-list backing_link_ids {
          type yang:uuid;
          description "Universally Unique IDs of the (key association) links providing
            QKD keys to these applications.";
        }

        leaf local_qkdn_id {
          type yang:uuid;
          description "Universally Unique ID of the local SD-QKD node that
            is providing QKD keys to the local application.";
        }

        leaf remote_qkdn_id {
          type yang:uuid;
          description "Universally Unique ID of the remote SD-QKD node that
            is providing QKD keys to the remote application. While
            unknown, the local SD-QKD will not be able to provide
            keys to the local application.";
        }

        leaf priority {
          type uint32;
          default 0;
          description "Priority of the association/application.
            High value indicate high priority. This might be defined by 
            the user, but will usually assigned by a network administrator.";
        }

        leaf creation_time {
          config false;
          type yang:date-and-time;
          description "Date and time of the service creation.";
        }

        leaf expiration_time {
          type yang:date-and-time;
          description "Date and time of the service expiration.";
        }

        container statistics {

          description " Statistical information relating to a 
            specific statistic period of time.";

          list statistic {

            key "end_time";
            config false;

            leaf end_time {
              type yang:date-and-time;
              config false;
              description "End time for the statistics collection period.";
            }

            leaf start_time {
              type yang:date-and-time;
              config false;
              description "Start time for the statistics collection period.";
            }

            leaf consumed_bits {
              type uint32;
              config false;
              description "Consumed secret key amount (bits)
                for a statistics collection period of time.";
            }

          }
        }
      }
  }

  grouping qkd_interfaces_top {
      list qkd_interface {
        key "qkdi_id";
        description "QKD Interface ID.";

        uses qkd_interface_common;
        
      }
  }

  grouping qkd_interface_common {

    leaf qkdi_id {
      type uint32;
      description "Interface ID. A locally unique number, which 
        is globally unique when combined with the SD-QKD node ID.";
    }

    container capabilities {
      description "Capabilities of the QKD system (interface).";

      leaf role_support {
        type identityref {
          base etsi-qkdn-types:QKD-ROLE-TYPES;
        }
        description "Support for transmit, receive or both.";
      }

      
      leaf wavelength_range {
        type  etsi-qkdn-types:wavelength-range-type;
        description "Range of supported wavelengths (nm) (multiple
          if it contains a tunable laser).";
      }

      leaf max_absorption {
        type uint32;
        description "Maximum absorption supported (dB).";
      }
    }

    leaf model {
      type string;
      description "Device model (vendor/device).";
    }

    leaf type {
      type identityref {
        base etsi-qkdn-types:QKD-TECHNOLOGY-TYPES;
      }
      description "Interface type (QKD  technology).";
    }

    container att_point {
      description "Interface attachment point to an optical switch.";

      leaf device {
        type string;
        description "Unique ID of the optical switch (or
        passive component) to which the interface is connected.";
      }

      leaf port {
        type uint32;
        description "Port ID of the device to which the interface
        is connected.";
      }
    }
  }

  grouping qkd_links_top {

    list qkd_link {
      key "link_id";

      leaf link_id{
        type yang:uuid;
        description "Universally Unique ID of the QKD link (key association).";
      }

      leaf enable {
        type boolean;
        default true;
        description "This value allows the key generation process for a 
          given link to be enabled or disabled. If true, the key generation 
          process is enabled.";
      }

      container local {
        description "Source (local) node of the QKD link.";

        leaf qkd_node {
          type yang:uuid;
          description "Universally Unique ID of the local qkd-node.";
        }

        leaf interface {
          type uint32;
          description "Interface used to create the key association link.";
        }
      }

      container remote {
        description "Destination (remote) unique QKD node ID.";

        leaf qkd_node {
          type yang:uuid;
          description "Universally Unique ID of the remote QKD node. 
            This value is provided by the SDN controller as part 
            of the request to establish the key association link.";
        }

        leaf interface {
          type uint32;
          description "Interface used to create the key association link.";
        }
      }

      leaf type {
        type identityref {
          base etsi-qkdn-types:QKD-LINK-TYPES;
        }
        description "Link type: Virtual (multi-hop) or physical.";
      }

      leaf state {
        type identityref {
          base etsi-qkdn-types:LINK-STATUS-TYPES;
        }
        description "Status of the QKD key association link.";
      }

      leaf-list applications {
        type yang:uuid;
        description " Universally Unique IDs of Applications which 
          are consuming keys from the QKD key association link.";
      }

      uses virtual_link_spec {
        when "../type = 'VIRT'" {
          description "Virtual key association link specific configuration.";
        }
      }

      uses physical_link_spec {
        when "../type = 'PHYS'" {
          description "Physical key association link specific configuration.";
        }
      }

      container performance {

        uses common_performance;

        uses physical_link_perf {
          when "../type = 'PHYS'" {
            description "Performance of the specific physical link.";
          }
        }
      }

    }
  }

  grouping common_performance {

    leaf expected_consumption {
        type uint32;
        description "Sum of the bandwidths (bps) of the application's that are
          consuming keys from the key association link.";
    }
    
    leaf skr {
        type uint32;
        description "Total secret key rate (bps) generation of the key association 
           link.";
    }

    leaf eskr {
        type uint32;
        description "Effective secret key rate (bps) generated by the key association
           link. i.e. the available rate to the applications after internal 
           consumption.";
    }

  }

  grouping physical_link_perf {

    list phys_perf {
      key "type";

      leaf type {
        type identityref {
            base "etsi-qkdn-types:PHYS-PERF-TYPES";
          }
          description "Type of the physical performance value to be
            exposed to the controller.";
      }

      leaf value {
        type uint32;
        description "Numerical value for the performance parameter.";
      }
    }

  }

  grouping virtual_link_spec {

      leaf prev_hop {
        type yang:uuid;
        description "Universally Unique ID of the previous hop in 
            a multi-hop/virtual link configuration.";
      }

      leaf-list next_hop {
        type yang:uuid;
        description "Universally Unique IDs of the Next hop(s) in 
            a multi-hop/virtual key association link configuration. List will 
            contain multiple entries for multicast over shared sub-paths.";
      }

      leaf bandwidth {
        type uint32;
        description "Required bandwidth (bps)for the key association link. Used to
          reserve bandwidth from the physical link to support the virtual link
          as an internal application.";
      }
  }

  grouping physical_link_spec {

      leaf channel_att {
        type uint8;
        description "Expected attenuation on the quantum channel (dB).";
      }

      
      leaf wavelength {
        type etsi-qkdn-types:wavelength;    
        description "Wavelength (nm) to be used for the quantum channel. If
          the interface is not tunable, this parameter can by bypassed.";
      }

      leaf qkd_role {
        type identityref {
          base "etsi-qkdn-types:QKD-ROLE-TYPES";
        }
        description "Transmitter/receiver mode for the QKD system. If 
          there is no multi-role support, this could be ignored.";
      }
  }

  notification sdqkdn_application_new {

    container qkd_application {

      leaf server_app_id {
        type inet:uri;
        description "ID of the server application connecting to
          the key store.";
      }

      leaf-list client_app_id {
        type inet:uri;
        description "ID of the client application connecting to
          the key server of the peer SD-QKD node. It is considered
          as the client from the security perspective.";
      }

      leaf local_qkdn_id {
        type yang:uuid;
        description "Universally Unique ID of the local SD-QKD node which
          is providing QKD keys to the local application.";
      }

      leaf priority {
        type uint32;
        default 0;
        description "Priority of the association/application.
          Higher values indicate higher priority. This might be 
          defined by the user, but usually handled
          by a network administrator.";
      }
     
      container qos {

        leaf max_bandwidth {
          type uint32;
          description "Maximum bandwidth (bps) allowed for this specific
            application. Exceeding this value will raise an error
            from the local key store to the application. This value
            might be internally configured (or by an administrator).";
        }

        leaf min_bandwidth {
          type uint32;
          description "This value is an optional QoS parameter
            that enables an application to request a minimum key 
            rate (in bits per second).";
        }

        leaf jitter {
          type uint32;
          description "This value allows to specify the maximum
            jitter (msec) of keys provided by the key delivery API, for
            applications requiring fast rekeying. This value can
            be coordinated with the other QoS parameters to provide a wide
            enough QoS definition.";
        }

        leaf ttl {
          type uint32;
          description "Time To Live specifies the maximum
            time (secs) a key can have been stored delivery to 
            and application.";
        }

        leaf clients_shared_path_enable {
          type boolean;
          default false;
          description "If true, multiple clients for this application
            might share paths to reduce service impact (consumption).";
        }

        leaf clients_shared_keys_required {
          type boolean;
          default false;
          description "If true, multiple clients for this application
            might share keys to reduce service impact (consumption).";
        }

      }

      leaf type {
        type identityref {
          base etsi-qkdn-types:QKD-APP-TYPES;
        }
        description "Type of the registered application. These
          values, defined within the types module, can be client
          (it we have an external application requesting keys)
          or internal (if the application is defined to maintain
          the QKD network - e.g. multi-hop, authentication or
          other encryption operations).";
      }
    }
  }

  notification sdqkdn_application_qos_update {

    container qkd_application {

      leaf app_id {
        type yang:uuid;
        description 
          "This value uniquely identifies a pair of applications
          extracting keys from a QKD link. This value is similar
          to a key ID or key handle.";
      }
     
      container qos {

        leaf max_bandwidth {
          type uint32;
          description "Maximum bandwidth (bps) allowed for this specific
            application. Exceeding this value will raise an error
            from the local key store to the appl. This value might
            be internally configured (or by an admin).";
        }

        leaf min_bandwidth {
          type uint32;
          description "This value is an optional QoS parameter
            which enables to require a minimum key rate (bps)
            for the application.";
        }

        leaf jitter {
          type uint32;
          description "This value allows to specify the maximum
            jitter (msec) to be provided by the key delivery API for
            applications requiring fast rekeying. This value can
            be coordinated with the other QoS to provide a wide
            enough QoS definition.";
        }

        leaf ttl {
          type uint32;
          description "This value is used to specify the maximum
            time that a key could be kept in the key store (sec) for a
            given application without being used.";
        }

        leaf clients_shared_path_enable {
          type boolean;
          default false;
          description "If true, multiple clients for this application
            might share keys to reduce service impact (consumption).";
        }

        leaf clients_shared_keys_required {
          type boolean;
          default false;
          description "If true, multiple clients for this application
            might share keys to reduce service impact (consumption).";
        }
      }

      leaf priority {
        type uint32;
        default 0;
        description "Priority of the association/application. Higher numbers
          mean higher priority. It might be defined by the user, but usually handled
          by a network administrator.";
      }
    }
  }

  notification sdqkdn_application_disconnected {

    container qkd_application {

      leaf app_id {
        type yang:uuid;
        description 
          "This value uniquely identifies a pair of applications
          extracting keys from a QKD key association link. This value is similar
          to a key ID or key handle.";
      }
    }
  }

  notification sdqkdn_interface_new {

    container qkd_interface{
      uses qkd_interface_common;
    }

  }

  notification sdqkdn_interface_down {

    container qkd_interface {
      
      leaf qkdi_id {
        type uint32;
        description "Interface id. It is described as a locally
          unique number, which is globally unique when combined
          with the SD-QKD node ID.";
      }

      leaf reason {
        type string;
        description "Auxilar parameter to include additional
          information about the reason for interface failure.";
      }
    }
  }

  notification sdqkdn_interface_out {

    container qkd_interface {
      
      leaf qkdi_id {
        type uint32;
        description "Interface id. It is described as a locally
          unique number, which is globally unique when combined
          with the SD-QKD node ID.";
      }
    }
  }

  notification sqdkdn_link_down {

    container qkd_link {

      leaf link_id{
        type yang:uuid;
        description "Unique ID of the QKD link (key association).";
      }

      leaf reason {
        type string;
        description "Auxilar parameter to include additional
          information about the reason for link failure.";
      }
    }
  }

  notification sqdkdn_link_perf_update {

    container qkd_link {

      leaf link_id{
        type yang:uuid;
        description "Unique ID of the key association QKD link.";
      }

      container performance {

        uses common_performance;

        uses physical_link_perf;
  
      }   
    }
  }

  notification sqdkdn_link_overloaded {

    container qkd_link {

      leaf link_id{
        type yang:uuid;
        description "Unique ID of the key association QKD link.";
      }

      container performance {

        uses common_performance;
  
      }   
    }
  }

  notification alarm {

    container link {

        leaf link_id {
          type yang:uuid;
          description "Placeholder for link_id of an Alarm.";
        }

        leaf status {
          type identityref {
            base "etsi-qkdn-types:LINK-STATUS-TYPES";
          }
          description "Placeholder for status of an Alarm.";
        }

        leaf message {
          type string;
          description "Placeholder for message of an Alarm.";
        }

        leaf severity {
          type identityref {
            base "etsi-qkdn-types:SEVERITY-TYPES";
          }
          description "Placeholder for the severity of an Alarm.";
        }
    }

    container interface {

        leaf qkdi_id {
          type uint32;
          description "Placeholder for a new interface.";
        }

        leaf status {
          type identityref {
            base "etsi-qkdn-types:IFACE-STATUS-TYPES";
          }
          description "Placeholder for the status of the new interface.";
        }

        leaf message {
          type string;
          description "Placeholder for the message.";
        }

        leaf severity {
          type identityref {
            base "etsi-qkdn-types:SEVERITY-TYPES";
          }
          description "Placeholder for the severity.";
        }
    }

    container application {

        leaf app_id {
          type yang:uuid;
          description "Placeholder for the description of the new App.";
        }

        leaf status {
          type identityref {
            base "etsi-qkdn-types:APP-STATUS-TYPES";
          }
          description "Placeholder for the status of the new App.";
        }

        leaf message {
          type string;
          description "Placeholder for the message associated to the new App.";
        }

        leaf severity {
          type identityref {
            base "etsi-qkdn-types:SEVERITY-TYPES";
          }
          description "Placeholder for the severity.";
        }
    }

  }

  notification event {

    container link {

        leaf link_id {
          type yang:uuid;
          description "Placeholder for the description of the new event.";
        }

        leaf status {
          type identityref {
            base "etsi-qkdn-types:LINK-STATUS-TYPES";
          }
          description "Placeholder for the status.";
        }

        leaf message {
          type string;
          description "Placeholder for the message.";
        }

        leaf severity {
          type identityref {
            base "etsi-qkdn-types:SEVERITY-TYPES";
          }
          description "Placeholder for the severity.";
        }
    }

    container interface {

        leaf qkdi_id {
          type uint32;
          description "Placeholder for the QKD ID.";
        }

        leaf status {
          type identityref {
            base "etsi-qkdn-types:IFACE-STATUS-TYPES";
          }
          description "Placeholder for the status.";
        }

        leaf message {
          type string;
          description "Placeholder for the message.";
        }

        leaf severity {
          type identityref {
            base "etsi-qkdn-types:SEVERITY-TYPES";
          }
          description "Placeholder for the severity.";
        }
    }

    container application {

        leaf app_id {
          type yang:uuid;
          description "Placeholder for the app_id.";
        }

        leaf status {
          type identityref {
            base "etsi-qkdn-types:APP-STATUS-TYPES";
          }
          description "Placeholder for the status.";
        }

        leaf message {
          type string;
          description "Placeholder for the message.";
        }

        leaf severity {
          type identityref {
            base "etsi-qkdn-types:SEVERITY-TYPES";
          }
          description "Placeholder for the severity.";
        }
    }
  }
}