etsi-qkd-sdn-node.yang

/* Copyright 2021 ETSI
Licensed under the BSD-3 Clause (https://forge.etsi.org/legal-matters) */

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 V1.1.1";

  revision "2021-09-30" {
    description
      "Refinement of the YANG model to make it compatible with the ETSI ISG QKD 018. Minor fixes.";
  }

  revision "2020-09-30" {
    description
      "First definition based on initial requirement analysis.";
  }
  
  grouping qkdn_id {
    description "Grouping of qkdn_id leaf";
    leaf qkdn_id {
      type yang:uuid;
      mandatory true;
      description
        "This value reflects the unique ID of the SD-QKD node.";
    }
  }
  
  grouping qkdn_version {
    leaf qkdn_version {
      type string;
      description "Hardware or software version of the SD-QKD node.";
    }
  }

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

  grouping qkdn_status {
    leaf qkdn_status {
      config false;
      type etsi-qkdn-types:qkdn-status-types;
      description "Status of the SD-QKD node.";
    }
  }

  grouping qkdn_capabilities {
    container qkdn_capabilities {
      description "Capabilities of the SD-QKD node.";

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

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

      leaf key_relay_mode_enable {
        type boolean;
        default true;
        description "If true, this node supports key relay (multi-hop) mode services.";
      }
    }
  }
  
  grouping 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.";
    }
  }
  
  grouping app_basic {
    
    uses app_id;
        
    leaf app_status {
      config false;
      type etsi-qkdn-types:app-status-types;
      description "Status of the application";
    }
  }
  
  grouping app_priority {
    leaf app_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.";
    }
  }
  
  grouping app_details {
    leaf app_type {
      type etsi-qkdn-types:qkd-app-types;
      description "Type of the registered application. These
        values, defined within the types module, can be client
        (if an 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 client application connecting to 
      the local key server of the peer SD-QKD node.";
    }

    leaf-list client_app_id {
      type inet:uri;
      description "ID of the client application connecting to 
      the local key server of the peer SD-QKD node.";
    }

    uses app_priority;
  }
  
  grouping local_qkdn_id {
    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.";
    }
  }
  
  grouping app_time {
    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.";
    }
  }
  
  grouping app_statistics {
    container app_statistics {
      description "Statistical information relating to a specific statistic period of time.";

      list statistics {
        description "List of statistics";
        key "end_time";
        config false;

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

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

        leaf consumed_bits {
          type uint32;
          config false;
          description "Consumed secret key amount (in bits) for a statistics collection period of time.";
        }
      }
    }
  }
  
  grouping app_qos {
    container app_qos {
      description "Requested Quality of Service.";
      
      leaf max_bandwidth {
        type uint32;
        description "Maximum bandwidth (in bits per second) 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) with a default value.";
      }

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

      leaf jitter {
        type uint32;
        description "This value allows to specify the maximum jitter 
          (in 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 
          (in seconds) that a key could be kept in the key store for 
          a given application without being used.";
      }
    }
  }
  
  grouping augmented_app_qos {
    uses app_qos {
      augment app_qos {

        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).";
        }
      }
    }
  }

  grouping qkd_applications {
    container qkd_applications {
      description "List of applications container";

      list qkd_app {
        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.";
        key "app_id";
   
        uses app_basic;
    
        uses app_details;

        uses app_time;
        
        uses app_statistics;
        
        uses augmented_app_qos;

        leaf-list backing_qkdl_id {
          type yang:uuid;
          description "Unique ID of the key association link which is 
            providing QKD keys to these applications.";
        }

        uses local_qkdn_id;

        leaf remote_qkdn_id {
          type yang:uuid;
          description "Unique ID of the remote SD-QKD node which 
            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.";
        }
      }
    }
  }

  grouping qkdi_status {
    leaf qkdi_status {
      config false;
      type etsi-qkdn-types:iface-status-types;
      description "Status of a QKD interface of the SD-QKD node.";
    }
  }
  
  grouping qkdi_model {
    leaf qkdi_model {
      type string;
      description "Device model (vendor/device).";
    }
  }
  
  grouping qkdi_type {
    leaf qkdi_type {
      type etsi-qkdn-types:qkd-technology-types;
      description "Interface type (QKD  technology).";
    }
  }
  
  grouping qkdi_att_point {
    container qkdi_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 qkdi_id {
    leaf qkdi_id {
      type uint32;
      description "It is described as a locally unique number, 
      which is globally unique when combined with the SD-QKD node ID.";
    }
  }
  
  grouping qkd_interface_item {
  
    uses qkdi_id;

    uses qkdi_model;

    uses qkdi_type;

    uses qkdi_att_point;

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

      leaf role_support {
        type 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 (in dB).";
      }
    }
  }
  
  grouping qkd_interfaces {
    container qkd_interfaces {
      description "List of interfaces container";

      list qkd_interface {
        key "qkdi_id";
        description "List of physical QKD modules in a secure location,
          abstracted as interfaces of the SD-QKD node.";

        uses qkd_interface_item;
        
        uses qkdi_status;
        
      }
    }
  }
  
  grouping qkdl_id {
    leaf qkdl_id {
      type yang:uuid;
      description "Unique ID of the QKD link (key association).";
    }
  }
  
  grouping qkdl_status {
    leaf qkdl_status {
      type etsi-qkdn-types:link-status-types;
      description "Status of the QKD key association link.";
    }
  }

  grouping common_performance {
    leaf expected_consumption {
      type uint32;
      config false;
      description "Sum of all the application's bandwidth (in bits 
        per second) that are on this particular key association link.";
    }
    
    leaf skr {
      type uint32;
      config false;
      description "Secret key rate generation (in bits per second) 
        of the key association link.";
    }

    leaf eskr {
      type uint32;
      config false;
      description "Effective secret key rate (in bits per second) generation 
        of the key association link available after internal consumption.";
    }
  }

  grouping physical_link_perf {
    list phys_perf {
      description "List of physical performance parameters.";
      key "perf_type";
      config false;

      leaf perf_type {
        type etsi-qkdn-types:phys-perf-types;
        config false;
        description "Type of the physical performance value to be
          exposed to the controller.";
      }

      leaf value {
        type uint32;
        config false;
        description "Numerical value for the performance parameter 
          type specified above.";
      }
    }
  }

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

    leaf-list virt_next_hop {
      type yang:uuid;
      description "Next hop(s) in a multihop/virtual key 
        association link config. Defined as a list for multicast 
        over shared sub-paths.";
    }

    leaf virt_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 phys_channel_att {
      type uint8;
      description "Expected attenuation on the quantum channel (in dB) 
        between the Source/qkd_node and Destination/qkd_node.";
      
    }
            
    leaf phys_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 phys_qkd_role {
      type 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.";
    }
  }

  grouping qkd_links {
    container qkd_links {
      description "List of links container";
      
      list qkd_link {
        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.";
        key "qkdl_id";

        uses qkdl_id;
        
        uses qkdl_status;

        leaf qkdl_enable {
          type boolean;
          default true;
          description "This value allows to enable of disable the key generation 
            process for a given link.";

        }

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

          leaf qkdn_id {
            type yang:uuid;
            description "Unique ID of the remote QKD node. 
            This value is provided by the SDN controller when the key 
            association link request arrives.";
          }

          leaf qkdi_id {
            type uint32;
            description "Interface used to create the link.";
          }
        }

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

          leaf qkdn_id {
            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 qkdi_id {
            type uint32;
            description "Interface used to create the key association link.";
          }
        }

        leaf qkdl_type {
          type etsi-qkdn-types:qkd-link-types;
          description "Link type: Virtual (multi-hop) or physical.";
        }

        leaf-list qkdl_applications {
          type yang:uuid;
          description "Applications which are consuming keys from
           this key association link.";
        }

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

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

        container qkdl_performance {

          uses common_performance;

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

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

    uses qkdn_id;
    
    uses qkdn_status;
    
    uses qkdn_version;

    uses qkdn_location_id;

    uses qkdn_capabilities;
    
    uses qkd_applications;

    uses qkd_interfaces;

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

  grouping severity {
    leaf severity {
      type etsi-qkdn-types:severity-types;
      description "Placeholder for the severity.";
    }
  }
  
  grouping reason {
    leaf reason {
      type string;
      description "Auxiliary parameter to include additional
        information about the reason for link failure.";
    }
  }

  notification sdqkdn_application_new {
    container qkd_application {
    
      uses app_details;

      uses local_qkdn_id;
     
      uses augmented_app_qos;
      
    }
  }

  notification sdqkdn_application_qos_update {
    container qkd_application {
    
      uses app_id;
     
      uses augmented_app_qos;

      uses app_priority;
      
    }
  }

  notification sdqkdn_application_disconnected {
    container qkd_application {
    
      uses app_id;
      
    }
  }

  notification sdqkdn_interface_new {
    container qkd_interface{
    
      uses qkd_interface_item;
      
    }
  }

  notification sdqkdn_interface_down {
    container qkd_interface {
      
      uses qkdi_id;

      uses reason;
      
    }
  }

  notification sdqkdn_interface_out {
    container qkd_interface {
      
      uses qkdi_id;
      
    }
  }

  notification sqdkdn_link_down {
    container qkd_link {

      uses qkdl_id;

      uses reason;
      
    }
  }

  notification sqdkdn_link_perf_update {
    container qkd_link {

      uses qkdl_id;

      container performance {

        uses common_performance;

        uses physical_link_perf;
  
      }   
    }
  }

  notification sqdkdn_link_overloaded {
    container qkd_link {

      uses qkdl_id;

      container performance {

        uses common_performance;
  
      }   
    }
  }

  notification alarm {

    container link {

        uses qkdl_id;

        uses qkdl_status;  

        uses message;
        
        uses severity;
        
    }

    container interface {

        uses qkdi_id;
        
        uses qkdi_status;

        uses message;
        
        uses severity;
        
    }

    container application {

        uses app_basic;

        uses message;
        
        uses severity;
        
    }

  }

  notification event {

    container link {

        uses qkdl_id;

        uses qkdl_status;    

        uses message;
        
        uses severity;
        
    }

    container interface {

        uses qkdi_id;
        
        uses qkdi_status;

        uses message;
        
        uses severity;
        
    }

    container application {

        uses app_basic;

        uses message;
        
        uses severity;
        
    }

  }

}