module cznic-resolver-common {

  yang-version "1.1";

  namespace "https://www.nic.cz/ns/yang/resolver-common";

  prefix "drc";

  import ietf-inet-types {
    prefix "inet";
  }

  import iana-dns-class-rr-type {
    prefix "dnsct";
  }

  import cznic-dns-rdata {
    prefix "rdata";
  }

  organization
    "CZ.NIC, z. s. p. o.";

  contact
    "Editor:   Ladislav Lhotka
               <mailto:lhotka@nic.cz>";

  description
    "This YANG module defines the common part of a data model for DNS
     resolvers.";

  revision 2018-10-29 {
    description
      "Initial revision.";
    reference
      "TODO: put git tag here";
  }

  /* Features */

  feature set-group {
    description
      "This feature indicates support for setting the group.";
  }

  /* Typedefs */

  typedef fs-path {
    type string;
    description
      "This type is used for specifying a filesystem path (absolute
       or relative).

       An implementation must check that the string satisfies all
       rules of the underlying operating system.";
  }

  typedef l2-protocol-selection {
    type bits {
      bit ipv4 {
        description
          "Enable/disable IPv4.";
      }
      bit ipv6 {
        description
          "Enable/disable IPv6.";
      }
    }
    default "ipv4 ipv6";
  }

  /* Groupings */

  grouping static-hint {
    description
      "This grouping defines the content of a static hint.";
    leaf name {
      type inet:domain-name;
      description
        "Domain name of a root server.";
    }
    leaf-list values {
      type inet:ip-address-no-zone;
      min-elements "1";
      description
        "One or more IPv4/IPv6 addresses of the root server.";
    }
  }

  grouping trust-anchor-spec {
    description
      "Specification of a trust anchor.";
    leaf owner {
      type inet:domain-name;
      description
        "The domain name to which the trust anchor applies.

         It is taken relative to the domain for which the trust
         anchor is specified. If the value is '.', then the trust
         anchor applies to the entire domain.";
    }
    choice trust-anchor-rdata {
      description
        "A trust anchor is specified by a DS or DNSKEY resource
         record data.";
      container ds {
        description
          "A trust anchor defined using DS RDATA.";
        uses rdata:ds;
      }
      container dnskey {
        description
          "A trust anchor defined using DS RDATA.";
        uses rdata:dnskey;
      }
    }
  }

  /* Data definitions */

  container dns-resolver {
    description
      "DNS resolver parameters.";
    container server {
      description
        "Parameters of the resolver process.";
      leaf user-name {
        type string;
        description
          "After binding the network socket, drop the privileges and
           run with effective user ID of this user.";
      }
      leaf group-name {
        if-feature "set-group";
        type string;
        description
          "After binding the network socket, drop the privileges and
           run with effective group ID of this group.";
      }
    }
    container network {
      description
        "Network connection parameters.";
      list listen-interfaces {
        key "name";
        unique "ip-address port";
        description
          "Inet sockets to use for listening to queries.";
        leaf name {
          type string;
          description
            "Arbitrary name of the listening socket.";
        }
        leaf ip-address {
          type inet:ip-address;
          mandatory "true";
          description
            "IPv4 or IPv6 address.";
        }
        leaf port {
          type inet:port-number;
          default "53";
          description
            "Port number.";
        }
      }
      container source-address {
        leaf ipv4 {
          type inet:ipv4-address-no-zone;
          description
            "IPv4 address to use as the source address in outgoing
             queries.

             If not configured, the resolver uses any address
             provided by the operationg system.";
        }
        leaf ipv6 {
          type inet:ipv6-address-no-zone;
          description
            "IPv6 address to use as the source address in outgoing
             queries.

             If not configured, the resolver uses any address
             provided by the operationg system.";
        }
      }
      container client-transport {
        description
          "Specify L2 and L3 protocols used for receiving and
           answering client queries.";
        leaf l2-protocols {
          type l2-protocol-selection;
          description
            "L2 protocols used for receiving and answering client
             queries.";
        }
      }
      container recursion-transport {
        description
          "Specify L2 and L3 protocols used for recursive queries.";
        leaf l2-protocols {
          type l2-protocol-selection;
          description
            "L2 protocols used for recursive queries.";
        }
      }
      leaf udp-payload-size {
        type uint16 {
          range "512..max";
        }
        units "octets";
        default "4096";
        description
          "Largest UDP payload that the resolver can accept.

           This value is advertized in EDNS0.";
        reference
          "RFC 2671: Extension Mechanisms for DNS (EDNS0)";
      }
    }
    container resolver {
      description
        "Parameters affecting operation of the DNS resolver.";
      list stub-zones {
        key "domain";
        description
          "List of stub zones.";
        leaf domain {
          type inet:domain-name;
          description
            "Name of the stub zone.";
        }
        leaf nameserver {
          type inet:host;
          description
            "Name or IP address of the stub zone nameserver.";
        }
        leaf port {
          type inet:port-number;
          default "53";
          description
            "Port number to use for communicating with the stub zone
             nameserver.";
        }
      }
      container hints {
        description
          "Configuration of static hints.";
        list root-hint {
          key "name";
          description
            "Each entry contains hints for one root server.

             Records configured this way override the resolver
             defaults and records set via 'root-zone-file'.

             Root hints are used if and only if the root servers
             cannot be resolved from the cache.";
          uses static-hint;
        }
        leaf root-zone-file {
          type fs-path;
          description
            "Path to a root zone file.

             It is used only if root servers cannot be resolved the
             cache and no root hints are set via 'root-hint'.";
        }
      }
      container options {
        description
          "Fine-tuning parameters of resolver operation.";
        leaf glue-checking {
          type boolean;
          default "true";
          description
            "If true, the resolver will only trust glue records that
             are within the responding server's authority.";
        }
        leaf qname-minimisation {
          type boolean;
          description
            "Send minimum amount of information in recursive queries
             to enhance privacy.";
        }
        leaf query-loopback {
          type boolean;
          default "true";
          description
            "This flag permits queries to loopback addresses (prefix
             127.0.0.0/8 for IPv4 and ::1/128 for IPv6).";
        }
        leaf reorder-rrset {
          type boolean;
          default "false";
          description
            "Controls whether resource records within a RRSet are
             reordered each time it is served from the cache.";
        }
      }
    }
    container logging {
      description
        "Logging parameters.";
      leaf verbosity {
        type uint8 {
          range "0..5";
        }
        default "1";
        description
          "Verbosity level.";
      }
    }
    container dnssec {
      presence "Enable DNSSEC";
      description
        "DNSSEC parameters";
      list trust-anchors {
        key "domain";
        description
          "Per-domain DNSSEC trust anchors.";
        leaf domain {
          type inet:domain-name;
          description
            "The domain to which the trust anchors belong.";
        }
        leaf key-file {
          type fs-path;
          description
            "Name of the file in which trust anchors are stored. The
             file contains DS or DNSKEY records in the zone file
             format.

             If the file is specified, it must also exist and be
             properly populated. The only exception is the file for
             the root domain ('.'): if it doesn't exist, it will be
             created and populated from the IANA website.

             The file is used for two purposes:

             - to initialize the trust anchors when the resolver
               starts

             - as a storage place for updates accroding to RFC 5011
               (unless they are turned off using the 'auto-update'
               flag).";
        }
        leaf auto-update {
          type boolean;
          default "true";
          description
            "Setting this flag to false blocks updates according to
             RFC 5011 for the domain. By default, the updates are
             enabled.";
        }
        list trust-anchor {
          config "false";
          description
            "List of trust anchors that are currently in use for the
             domain.";
          uses trust-anchor-spec;
        }
        action add-trust-anchor {
          description
            "Specify a trust anchor explicitly.

             The resolver add this item to the existing trust anchors
             for the domain.";
          input {
            uses trust-anchor-spec;
          }
        }
      }
      leaf-list negative-trust-anchors {
        type inet:domain-name;
        description
          "List of domain names representing negative trust
           anchors.";
        reference
          "RFC 7646: Definition and Use of DNSSEC Negative Trust
           Anchors.";
      }
    }
    container cache {
      description
        "Parameters of the resolver cache.";
      leaf max-size {
        type uint64;
        units "bytes";
        description
          "Maximum size of the cache.";
      }
      leaf current-size {
        type uint64;
        units "bytes";
        config "false";
        description
          "Current size of the cache.";
      }
      leaf max-ttl {
        type uint32;
        units "seconds";
        default "172800";
        description
          "Maximum time-to-live for cache entries.

           This value overrides the original TTL specified for the
           particular resource record if the latter is greater.";
      }
      leaf min-ttl {
        type uint32;
        units "seconds";
        must ". <= ../max-ttl" {
          error-message
            "'min-ttl' must not be higher than 'max-ttl'";
        }
        default "0";
        description
          "Minimum time-to-live for cache entries.

           This value overrides the original TTL specified for the
           particular resource record if the latter is smaller.";
      }
    }
    container dns64 {
      presence "enable DNS64 functionality";
      leaf prefix {
        type inet:ipv6-prefix;
        default "64:ff9b::/96";
        description
          "The DNS64 prefix to be used for synthesizing AAAA records.

           The prefix must be /96 or shorter.";
      }
    }
    container debugging {
      description
        "Configuration of debugging functions.";
    }
  }

  /* Operations */

  rpc resolve {
    description
      "Query the resolver and return the result.";
    input {
      leaf name {
        type inet:domain-name;
        mandatory "true";
        description
          "Query name.";
      }
      leaf type {
        type dnsct:rr-type;
        mandatory "true";
        description
          "Query type.";
      }
      leaf class {
        type dnsct:dns-class;
        default "IN";
        description
          "Query class.";
      }
    }
  }
}