code/network-generator/network_generation/model/yang/ietf-inet-types@2021-02-22.yang

   1 module ietf-inet-types {
   2
   3   namespace "urn:ietf:params:xml:ns:yang:ietf-inet-types";
   4   prefix "inet";
   5
   6   organization
   7    "IETF Network Modeling (NETMOD) Working Group";
   8
   9   contact
  10    "WG Web:   <https://datatracker.ietf.org/wg/netmod/>
  11     WG List:  <mailto:netmod@ietf.org>
  12
  13     Editor:   Juergen Schoenwaelder
  14               <mailto:j.schoenwaelder@jacobs-university.de>";
  15
  16   description
  17    "This module contains a collection of generally useful derived
  18     YANG data types for Internet addresses and related things.
  19
  20     The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
  21     NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
  22     'MAY', and 'OPTIONAL' in this document are to be interpreted as
  23     described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
  24     they appear in all capitals, as shown here.
  25
  26     Copyright (c) 2021 IETF Trust and the persons identified as
  27     authors of the code.  All rights reserved.
  28
  29     Redistribution and use in source and binary forms, with or
  30     without modification, is permitted pursuant to, and subject
  31     to the license terms contained in, the Simplified BSD License
  32     set forth in Section 4.c of the IETF Trust's Legal Provisions
  33     Relating to IETF Documents
  34     (http://trustee.ietf.org/license-info).
  35
  36     This version of this YANG module is part of RFC XXXX;
  37     see the RFC itself for full legal notices.";
  38
  39   revision 2021-02-22 {
  40     description
  41      "This revision adds the following new data types:
  42       - inet:ip-address-and-prefix
  43       - inet:ipv4-address-and-prefix
  44       - inet:ipv6-address-and-prefix
  45       - inet:host-name
  46       - inet:email-address
  47       The inet:host union was changed to use inet:host-name instead
  48       of inet:domain-name.";
  49     reference
  50      "RFC XXXX: Common YANG Data Types";
  51   }
  52   revision 2013-07-15 {
  53     description
  54      "This revision adds the following new data types:
  55       - inet:ip-address-no-zone
  56       - inet:ipv4-address-no-zone
  57       - inet:ipv6-address-no-zone";
  58     reference
  59      "RFC 6991: Common YANG Data Types";
  60   }
  61
  62   revision 2010-09-24 {
  63     description
  64      "Initial revision.";
  65     reference
  66      "RFC 6021: Common YANG Data Types";
  67   }
  68
  69   /*** collection of types related to protocol fields ***/
  70
  71   typedef ip-version {
  72     type enumeration {
  73       enum unknown {
  74         value "0";
  75         description
  76          "An unknown or unspecified version of the Internet
  77           protocol.";
  78       }
  79       enum ipv4 {
  80         value "1";
  81         description
  82          "The IPv4 protocol as defined in RFC 791.";
  83       }
  84       enum ipv6 {
  85         value "2";
  86         description
  87          "The IPv6 protocol as defined in RFC 2460.";
  88       }
  89     }
  90     description
  91      "This value represents the version of the IP protocol.
  92
  93       In the value set and its semantics, this type is equivalent
  94       to the InetVersion textual convention of the SMIv2.";
  95     reference
  96      "RFC  791: Internet Protocol
  97       RFC 2460: Internet Protocol, Version 6 (IPv6) Specification
  98       RFC 4001: Textual Conventions for Internet Network Addresses";
  99   }
 100   typedef dscp {
 101     type uint8 {
 102       range "0..63";
 103     }
 104     description
 105      "The dscp type represents a Differentiated Services Code Point
 106       that may be used for marking packets in a traffic stream.
 107
 108       In the value set and its semantics, this type is equivalent
 109       to the Dscp textual convention of the SMIv2.";
 110     reference
 111      "RFC 3289: Management Information Base for the Differentiated
 112                 Services Architecture
 113       RFC 2474: Definition of the Differentiated Services Field
 114                 (DS Field) in the IPv4 and IPv6 Headers
 115       RFC 2780: IANA Allocation Guidelines For Values In
 116                 the Internet Protocol and Related Headers";
 117   }
 118
 119   typedef ipv6-flow-label {
 120     type uint32 {
 121       range "0..1048575";
 122     }
 123     description
 124      "The ipv6-flow-label type represents the flow identifier or
 125       Flow Label in an IPv6 packet header that may be used to
 126       discriminate traffic flows.
 127
 128       In the value set and its semantics, this type is equivalent
 129       to the IPv6FlowLabel textual convention of the SMIv2.";
 130     reference
 131      "RFC 3595: Textual Conventions for IPv6 Flow Label
 132       RFC 2460: Internet Protocol, Version 6 (IPv6) Specification";
 133   }
 134
 135   typedef port-number {
 136     type uint16 {
 137       range "0..65535";
 138     }
 139     description
 140      "The port-number type represents a 16-bit port number of an
 141       Internet transport-layer protocol such as UDP, TCP, DCCP, or
 142       SCTP.  Port numbers are assigned by IANA.  A current list of
 143       all assignments is available from <http://www.iana.org/>.
 144
 145       Note that the port number value zero is reserved by IANA.  In
 146       situations where the value zero does not make sense, it can
 147       be excluded by subtyping the port-number type.
 148       In the value set and its semantics, this type is equivalent
 149       to the InetPortNumber textual convention of the SMIv2.";
 150     reference
 151      "RFC  768: User Datagram Protocol
 152       RFC  793: Transmission Control Protocol
 153       RFC 4960: Stream Control Transmission Protocol
 154       RFC 4340: Datagram Congestion Control Protocol (DCCP)
 155       RFC 4001: Textual Conventions for Internet Network Addresses";
 156   }
 157
 158   /*** collection of types related to autonomous systems ***/
 159
 160   typedef as-number {
 161     type uint32;
 162     description
 163      "The as-number type represents autonomous system numbers
 164       which identify an Autonomous System (AS).  An AS is a set
 165       of routers under a single technical administration, using
 166       an interior gateway protocol and common metrics to route
 167       packets within the AS, and using an exterior gateway
 168       protocol to route packets to other ASes.  IANA maintains
 169       the AS number space and has delegated large parts to the
 170       regional registries.
 171
 172       Autonomous system numbers were originally limited to 16
 173       bits.  BGP extensions have enlarged the autonomous system
 174       number space to 32 bits.  This type therefore uses an uint32
 175       base type without a range restriction in order to support
 176       a larger autonomous system number space.
 177
 178       In the value set and its semantics, this type is equivalent
 179       to the InetAutonomousSystemNumber textual convention of
 180       the SMIv2.";
 181     reference
 182      "RFC 1930: Guidelines for creation, selection, and registration
 183                 of an Autonomous System (AS)
 184       RFC 4271: A Border Gateway Protocol 4 (BGP-4)
 185       RFC 4001: Textual Conventions for Internet Network Addresses
 186       RFC 6793: BGP Support for Four-Octet Autonomous System (AS)
 187                 Number Space";
 188   }
 189
 190   /*** collection of types related to IP addresses and hostnames ***/
 191
 192   typedef ip-address {
 193     type union {
 194       type inet:ipv4-address;
 195       type inet:ipv6-address;
 196     }
 197     description
 198      "The ip-address type represents an IP address and is IP
 199       version neutral.  The format of the textual representation
 200       implies the IP version.  This type supports scoped addresses
 201       by allowing zone identifiers in the address format.";
 202     reference
 203      "RFC 4007: IPv6 Scoped Address Architecture";
 204   }
 205
 206   typedef ipv4-address {
 207     type string {
 208       pattern
 209         '(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3}'
 210       +  '([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])'
 211       + '(%[\p{N}\p{L}]+)?';
 212     }
 213     description
 214       "The ipv4-address type represents an IPv4 address in
 215        dotted-quad notation.  The IPv4 address may include a zone
 216        index, separated by a % sign.
 217
 218        The zone index is used to disambiguate identical address
 219        values.  For link-local addresses, the zone index will
 220        typically be the interface index number or the name of an
 221        interface.  If the zone index is not present, the default
 222        zone of the device will be used.
 223
 224        The canonical format for the zone index is the numerical
 225        format";
 226   }
 227
 228   typedef ipv6-address {
 229     type string {
 230       pattern '((:|[0-9a-fA-F]{0,4}):)([0-9a-fA-F]{0,4}:){0,5}'
 231             + '((([0-9a-fA-F]{0,4}:)?(:|[0-9a-fA-F]{0,4}))|'
 232             + '(((25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])\.){3}'
 233             + '(25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])))'
 234             + '(%[\p{N}\p{L}]+)?';
 235       pattern '(([^:]+:){6}(([^:]+:[^:]+)|(.*\..*)))|'
 236             + '((([^:]+:)*[^:]+)?::(([^:]+:)*[^:]+)?)'
 237             + '(%.+)?';
 238     }
 239     description
 240      "The ipv6-address type represents an IPv6 address in full,
 241       mixed, shortened, and shortened-mixed notation.  The IPv6
 242       address may include a zone index, separated by a % sign.
 243
 244       The zone index is used to disambiguate identical address
 245       values.  For link-local addresses, the zone index will
 246       typically be the interface index number or the name of an
 247       interface.  If the zone index is not present, the default
 248       zone of the device will be used.
 249
 250       The canonical format of IPv6 addresses uses the textual
 251       representation defined in Section 4 of RFC 5952.  The
 252       canonical format for the zone index is the numerical
 253       format as described in Section 11.2 of RFC 4007.";
 254     reference
 255      "RFC 4291: IP Version 6 Addressing Architecture
 256       RFC 4007: IPv6 Scoped Address Architecture
 257       RFC 5952: A Recommendation for IPv6 Address Text
 258                 Representation";
 259   }
 260
 261   typedef ip-address-no-zone {
 262     type union {
 263       type inet:ipv4-address-no-zone;
 264       type inet:ipv6-address-no-zone;
 265     }
 266     description
 267      "The ip-address-no-zone type represents an IP address and is
 268       IP version neutral.  The format of the textual representation
 269       implies the IP version.  This type does not support scoped
 270       addresses since it does not allow zone identifiers in the
 271       address format.";
 272     reference
 273      "RFC 4007: IPv6 Scoped Address Architecture";
 274   }
 275
 276   typedef ipv4-address-no-zone {
 277     type inet:ipv4-address {
 278       pattern '[0-9\.]*';
 279     }
 280     description
 281       "An IPv4 address without a zone index.  This type, derived from
 282        ipv4-address, may be used in situations where the zone is known
 283        from the context and hence no zone index is needed.";
 284   }
 285
 286   typedef ipv6-address-no-zone {
 287     type inet:ipv6-address {
 288       pattern '[0-9a-fA-F:\.]*';
 289     }
 290     description
 291       "An IPv6 address without a zone index.  This type, derived from
 292        ipv6-address, may be used in situations where the zone is known
 293        from the context and hence no zone index is needed.";
 294     reference
 295      "RFC 4291: IP Version 6 Addressing Architecture
 296       RFC 4007: IPv6 Scoped Address Architecture
 297       RFC 5952: A Recommendation for IPv6 Address Text
 298                 Representation";
 299   }
 300
 301   typedef ip-prefix {
 302     type union {
 303       type inet:ipv4-prefix;
 304       type inet:ipv6-prefix;
 305     }
 306     description
 307      "The ip-prefix type represents an IP prefix and is IP
 308       version neutral.  The format of the textual representations
 309       implies the IP version.";
 310   }
 311
 312   typedef ipv4-prefix {
 313     type string {
 314       pattern
 315          '(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3}'
 316        +  '([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])'
 317        + '/(([0-9])|([1-2][0-9])|(3[0-2]))';
 318     }
 319     description
 320      "The ipv4-prefix type represents an IPv4 prefix.
 321       The prefix length is given by the number following the
 322       slash character and must be less than or equal to 32.
 323
 324       A prefix length value of n corresponds to an IP address
 325       mask that has n contiguous 1-bits from the most
 326       significant bit (MSB) and all other bits set to 0.
 327
 328       The canonical format of an IPv4 prefix has all bits of
 329       the IPv4 address set to zero that are not part of the
 330       IPv4 prefix.
 331
 332       The definition of ipv4-prefix does not require that bits,
 333       which are not part of the prefix, are set to zero. However,
 334       implementations have to return values in canonical format,
 335       which requires non-prefix bits to be set to zero. This means
 336       that 192.0.2.1/24 must be accepted as a valid value but it
 337       will be converted into the canonical format 192.0.2.0/24.";
 338   }
 339
 340   typedef ipv6-prefix {
 341     type string {
 342       pattern '((:|[0-9a-fA-F]{0,4}):)([0-9a-fA-F]{0,4}:){0,5}'
 343             + '((([0-9a-fA-F]{0,4}:)?(:|[0-9a-fA-F]{0,4}))|'
 344             + '(((25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])\.){3}'
 345             + '(25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])))'
 346             + '(/(([0-9])|([0-9]{2})|(1[0-1][0-9])|(12[0-8])))';
 347       pattern '(([^:]+:){6}(([^:]+:[^:]+)|(.*\..*)))|'
 348             + '((([^:]+:)*[^:]+)?::(([^:]+:)*[^:]+)?)'
 349             + '(/.+)';
 350     }
 351     description
 352      "The ipv6-prefix type represents an IPv6 prefix.
 353       The prefix length is given by the number following the
 354       slash character and must be less than or equal to 128.
 355
 356       A prefix length value of n corresponds to an IP address
 357       mask that has n contiguous 1-bits from the most
 358       significant bit (MSB) and all other bits set to 0.
 359
 360       The canonical format of an IPv6 prefix has all bits of
 361       the IPv6 address set to zero that are not part of the
 362       IPv6 prefix.  Furthermore, the IPv6 address is represented
 363       as defined in Section 4 of RFC 5952.
 364
 365       The definition of ipv6-prefix does not require that bits,
 366       which are not part of the prefix, are set to zero. However,
 367       implementations have to return values in canonical format,
 368       which requires non-prefix bits to be set to zero. This means
 369       that 2001:db8::1/64 must be accepted as a valid value but it
 370       will be converted into the canonical format 2001:db8::/64.";
 371     reference
 372      "RFC 5952: A Recommendation for IPv6 Address Text
 373                 Representation";
 374   }
 375
 376   typedef ip-address-and-prefix {
 377     type union {
 378       type inet:ipv4-address-and-prefix;
 379       type inet:ipv6-address-and-prefix;
 380     }
 381     description
 382      "The ip-address-and-prefix type represents an IP address and
 383       prefix and is IP version neutral.  The format of the textual
 384       representations implies the IP version.";
 385   }
 386
 387   typedef ipv4-address-and-prefix {
 388     type string {
 389       pattern
 390          '(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3}'
 391        +  '([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])'
 392        + '/(([0-9])|([1-2][0-9])|(3[0-2]))';
 393     }
 394     description
 395      "The ipv4-address-and-prefix type represents an IPv4
 396       address and an associated ipv4 prefix.
 397       The prefix length is given by the number following the
 398       slash character and must be less than or equal to 32.
 399
 400       A prefix length value of n corresponds to an IP address
 401       mask that has n contiguous 1-bits from the most
 402       significant bit (MSB) and all other bits set to 0.";
 403   }
 404
 405   typedef ipv6-address-and-prefix {
 406     type string {
 407       pattern '((:|[0-9a-fA-F]{0,4}):)([0-9a-fA-F]{0,4}:){0,5}'
 408             + '((([0-9a-fA-F]{0,4}:)?(:|[0-9a-fA-F]{0,4}))|'
 409             + '(((25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])\.){3}'
 410             + '(25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])))'
 411             + '(/(([0-9])|([0-9]{2})|(1[0-1][0-9])|(12[0-8])))';
 412       pattern '(([^:]+:){6}(([^:]+:[^:]+)|(.*\..*)))|'
 413             + '((([^:]+:)*[^:]+)?::(([^:]+:)*[^:]+)?)'
 414             + '(/.+)';
 415     }
 416     description
 417      "The ipv6-address-and-prefix type represents an IPv6
 418       address and an associated ipv4 prefix.
 419       The prefix length is given by the number following the
 420       slash character and must be less than or equal to 128.
 421
 422       A prefix length value of n corresponds to an IP address
 423       mask that has n contiguous 1-bits from the most
 424       significant bit (MSB) and all other bits set to 0.
 425
 426       The canonical format requires that the IPv6 address is
 427       represented as defined in Section 4 of RFC 5952.";
 428     reference
 429      "RFC 5952: A Recommendation for IPv6 Address Text
 430                 Representation";
 431   }
 432
 433   /*** collection of domain name and URI types ***/
 434
 435   typedef domain-name {
 436     type string {
 437       length "1..253";
 438       pattern
 439         '((([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9]\.)*'
 440       + '([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9]\.?)'
 441       + '|\.';
 442     }
 443     description
 444      "The domain-name type represents a DNS domain name.  The
 445       name SHOULD be fully qualified whenever possible. This
 446       type does not support wildcards (see RFC 4592) or
 447       classless in-addr.arpa delegations (see RFC 2317).
 448
 449       Internet domain names are only loosely specified.  Section
 450       3.5 of RFC 1034 recommends a syntax (modified in Section
 451       2.1 of RFC 1123).  The pattern above is intended to allow
 452       for current practice in domain name use, and some possible
 453       future expansion.  Note that Internet host names have a
 454       stricter syntax (described in RFC 952) than the DNS
 455       recommendations in RFCs 1034 and 1123. Schema nodes
 456       representing host names should use the host-name type
 457       instead of the domain-type.
 458
 459       The encoding of DNS names in the DNS protocol is limited
 460       to 255 characters.  Since the encoding consists of labels
 461       prefixed by a length bytes and there is a trailing NULL
 462       byte, only 253 characters can appear in the textual dotted
 463       notation.
 464
 465       The description clause of schema nodes using the domain-name
 466       type MUST describe when and how these names are resolved to
 467       IP addresses.  Note that the resolution of a domain-name value
 468       may require to query multiple DNS records (e.g., A for IPv4
 469       and AAAA for IPv6).  The order of the resolution process and
 470       which DNS record takes precedence can either be defined
 471       explicitly or may depend on the configuration of the
 472       resolver.
 473
 474       Domain-name values use the US-ASCII encoding.  Their canonical
 475       format uses lowercase US-ASCII characters.  Internationalized
 476       domain names MUST be A-labels as per RFC 5890.";
 477     reference
 478      "RFC  952: DoD Internet Host Table Specification
 479       RFC 1034: Domain Names - Concepts and Facilities
 480       RFC 1123: Requirements for Internet Hosts -- Application
 481                 and Support
 482       RFC 2317: Classless IN-ADDR.ARPA delegation
 483       RFC 2782: A DNS RR for specifying the location of services
 484                 (DNS SRV)
 485       RFC 4592: The Role of Wildcards in the Domain Name System
 486       RFC 5890: Internationalized Domain Names in Applications
 487                 (IDNA): Definitions and Document Framework";
 488   }
 489
 490   typedef host-name {
 491     type domain-name {
 492       pattern '[a-zA-Z0-9\-\.]+';
 493       length "2..max";
 494     }
 495     description
 496      "The host-name type represents (fully qualified) host names.
 497       Host names must be at least two characters long (see RFC 952)
 498       and they are restricted to labels consisting of letters, digits
 499       and hyphens separated by dots (see RFC1123 and RFC 952).";
 500     reference
 501      "RFC  952: DoD Internet Host Table Specification
 502       RFC 1123: Requirements for Internet Hosts: Application and Support";
 503   }
 504
 505   typedef host {
 506     type union {
 507       type inet:ip-address;
 508       type inet:host-name;
 509     }
 510     description
 511      "The host type represents either an IP address or a (fully
 512       qualified) host name.";
 513   }
 514
 515   /*
 516    * DISCUSS:
 517    * - It was discussed to define int-domain-name and int-host-name
 518    *   that use U-labels instead of A-labels and to add int-host-name
 519    *   to the inet:host union, perhaps all gated by an inet:idna-aware
 520    *   feature.
 521    * - It is not clear how inet:idna-aware affects inet:email-address
 522    *   and inet:uri - do we also need int-uri and int-email-address?
 523    */
 524
 525   typedef uri {
 526     type string;
 527     description
 528      "The uri type represents a Uniform Resource Identifier
 529       (URI) as defined by STD 66.
 530
 531       Objects using the uri type MUST be in US-ASCII encoding,
 532       and MUST be normalized as described by RFC 3986 Sections
 533       6.2.1, 6.2.2.1, and 6.2.2.2.  All unnecessary
 534       percent-encoding is removed, and all case-insensitive
 535       characters are set to lowercase except for hexadecimal
 536       digits, which are normalized to uppercase as described in
 537       Section 6.2.2.1.
 538
 539       The purpose of this normalization is to help provide
 540       unique URIs.  Note that this normalization is not
 541       sufficient to provide uniqueness.  Two URIs that are
 542       textually distinct after this normalization may still be
 543       equivalent.
 544
 545       Objects using the uri type may restrict the schemes that
 546       they permit.  For example, 'data:' and 'urn:' schemes
 547       might not be appropriate.
 548
 549       A zero-length URI is not a valid URI.  This can be used to
 550       express 'URI absent' where required.
 551
 552       In the value set and its semantics, this type is equivalent
 553       to the Uri SMIv2 textual convention defined in RFC 5017.";
 554     reference
 555      "RFC 3986: Uniform Resource Identifier (URI): Generic Syntax
 556       RFC 3305: Report from the Joint W3C/IETF URI Planning Interest
 557                 Group: Uniform Resource Identifiers (URIs), URLs,
 558                 and Uniform Resource Names (URNs): Clarifications
 559                 and Recommendations
 560       RFC 5017: MIB Textual Conventions for Uniform Resource
 561                 Identifiers (URIs)";
 562   }
 563
 564   typedef email-address {
 565     type string {
 566       // dot-atom-text "@" ...
 567       pattern '[a-zA-Z0-9!#$%&'+"'"+'*+/=?^_`{|}~-]+'
 568             + '(\.[a-zA-Z0-9!#$%&'+"'"+'*+/=?^_`{|}~-]+)*'
 569             + '@'
 570             + '[a-zA-Z0-9!#$%&'+"'"+'*+/=?^_`{|}~-]+'
 571             + '(\.[a-zA-Z0-9!#$%&'+"'"+'*+/=?^_`{|}~-]+)*';
 572     }
 573     description
 574       "The email-address type represents an email address as
 575        defined as addr-spec in RFC 5322 section 3.4.1.";
 576     reference
 577       "RFC 5322: Internet Message Format";
 578   }
 579
 580   /*
 581    * DISCUSS:
 582    * - Need to define a pattern that has a meaningful trade-off
 583    *   between precision and complexity (there are very tight
 584    *   pattern that are very long and complex). The current
 585    *   pattern does not take care of quoted-string, obs-local-part,
 586    *   domain-literal, obs-domain.
 587    */
 588
 589 }