RFC 9648

YANG Data Model for TCP

📅 published October 2024, from ietf

RFC 9648: YANG Data Model for TCP 💖

okay bestie, let's get into it! 🎀 This one is an IETF Standards Track doc, so it's a real spec that implementers are supposed to follow, not just a vibe 💅

Here's the title block tea ☕:

  • Number: RFC 9648 ✨
  • Title: YANG Data Model for TCP 🦋
  • Authors: M. Scharf (Hochschule Esslingen), M. Jethanandani (Kloud Services), and V. Murgai (F5, Inc.) 🫶
  • Category: Standards Track 👑
  • Date: October 2024 🍓
  • ISSN: 2070-1721
  • Obsoletes / Updates: the title block doesn't list any, so this one isn't replacing or updating another RFC 🙈

This is part 1 of 5, so more is coming! 🌈 For now we're covering the front matter, the Abstract, the Status and Copyright stuff, the Table of Contents, and the first three sections.

Abstract 🌸

okay so this doc gives you a minimal YANG data model for TCP on devices that get configured and managed by network management protocols 🧚 It's giving "organised TCP settings for your network gear" 💅 The model has a container for all TCP connections, plus groupings of authentication parameters that other TCP implementations or other models can import and use 🔥 It also includes basic TCP statistics 📊 And it's compliant with the Network Management Datastore Architecture (NMDA) [RFC8342] ✨

Status of This Memo ✨

This is an Internet Standards Track document 💜

This document is a product of the Internet Engineering Task Force (IETF) 🦋 It represents the consensus of the IETF community, and it got public review and was approved for publication by the Internet Engineering Steering Group (IESG) 👑 If you want more info on Internet Standards, check Section 2 of RFC 7841 🎀

Info about the current status of this document, any errata, and how to give feedback lives at https://www.rfc-editor.org/info/rfc9648 🫶

Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. 💖

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, because they describe your rights and restrictions with respect to this document. 🧐 Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions, and they're provided without warranty as described in the Revised BSD License 📜

Table of Contents 🧚

1.  Introduction
  1.1.  Conventions
2.  Requirements Language
3.  YANG Module Overview
  3.1.  Scope
  3.2.  Model Design
  3.3.  Tree Diagram
4.  TCP YANG Data Model
5.  IANA Considerations
  5.1.  The IETF XML Registry
  5.2.  The YANG Module Names Registry
6.  Security Considerations
7.  References
  7.1.  Normative References
  7.2.  Informative References
Appendix A.  Examples
  A.1.  Keepalive Configuration
  A.2.  TCP-AO Configuration
Appendix B.  Complete Tree Diagram
Acknowledgements
Authors' Addresses

1. Introduction 🦋

okay so TCP [RFC9293] is used by tons of applications, including control and management protocols 💅 That means TCP is implemented on network elements that can be configured and managed through network management protocols like NETCONF [RFC6241] or RESTCONF [RFC8040] 🔥

This document specifies a minimal YANG 1.1 [RFC7950] data model for configuring and managing TCP on network elements that support YANG 🎀 It covers a TCP connection table, a TCP listener table with info about a particular TCP listener, and an augmentation of the YANG data model for key chains [RFC8177] so authentication works ✨ The YANG module here is compliant with NMDA [RFC8342] 💖

The YANG module has a narrow scope. It focuses on a subset of fundamental TCP functions and basic statistics 🌸 It defines a container for a list of TCP connections, and that includes definitions from "YANG Groupings for TCP Clients and TCP Servers" [RFC9643] 🧚 The model follows the recommendation in "BGP/MPLS IP Virtual Private Networks (VPNs)" [RFC4364] 👑 So it lets you enable the TCP Authentication Option (TCP-AO) [RFC5925] and still accommodates the installed base that uses MD5 🫶 The module can be augmented or updated for more advanced or implementation-specific TCP features later on 🌈

This specification does not deprecate the Management Information Base (MIB) for the Transmission Control Protocol (TCP) [RFC4022] 💜 The basic statistics in this document follow the model of the TCP MIB 📊 A TCP extended statistics MIB [RFC4898] also exists, but this document doesn't cover those extended statistics 🙈 The YANG module also leaves out some selected parameters from the TCP MIB, most notably Retransmission Timeout (RTO) configuration and a maximum connection limit 💀 This was a conscious decision, because these parameters hardly matter in a state-of-the-art TCP implementation ✨ It would also be possible to translate a MIB into a YANG module, for instance using "Translation of Structure of Management Information Version 2 (SMIv2) MIB Modules to YANG Modules" [RFC6643] 🦋 But this approach isn't used here, because a translated model would not be up-to-date 🥲

There are other existing TCP-related YANG data models, and they're orthogonal to this spec 🧚 Some examples:

  • TCP header attributes are modeled in other security-related models, such as "YANG Data Model for Network Access Control Lists (ACLs)" [RFC8519], "Distributed Denial-of-Service Open Threat Signaling (DOTS) Data Channel Specification" [RFC8783], "I2NSF Capability YANG Data Model" [NSF-CAP-YANG], or "I2NSF Network Security Function-Facing Interface YANG Data Model" [NSF-FACING-YANG] 🛡️
  • TCP-related configuration of a NAT (for example NAT44, NAT64, or Destination NAT) is defined in "A YANG Module for Network Address Translation (NAT) and Network Prefix Translation (NPT)" [RFC8512] and "A YANG Data Model for Dual-Stack Lite (DS-Lite)" [RFC8513] 🌐
  • TCP-AO and TCP MD5 configuration for Layer 3 VPNs is modeled in "A YANG Network Data Model for Layer 3 VPNs" [RFC9182]. This model assumes that TCP-AO-specific parameters are preconfigured in addition to the key chain parameters 🎀

1.1. Conventions 🌸

Various examples in this document use the XML [W3C.REC-xml-20081126] encoding 💻 Other encodings, such as JSON [RFC8259], could be used instead 🧩

Various examples in this document contain long lines that may be folded, as described in [RFC8792] 📏

2. Requirements Language 💅

okay the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here 🔥 Basically, those capitalised words are the real rules, so read them carefully bestie 🫶

3. YANG Module Overview 🧚

Part 2 is coming next, so stay tuned! 🌈✨

3.1. Scope

Okay so TCP gets built on loads of different system architectures 💅, which means there are tons of different (and often implementation-specific) ways to set its parameters 🫶. On top of that, a lot of TCP/IP stacks have config at different scopes ✨:

  • System-wide configuration: Lots of TCP implementations have parameters that affect every TCP connection from or to that stack 🌸. Typical examples are turning optional protocol features on or off. For instance, many implementations can switch window scaling (defined in "Transmission Control Protocol (TCP)" [RFC9293]) on or off for all TCP connections.
  • Interface configuration: It can be useful to use different TCP parameters on different interfaces, like different device ports or IP interfaces 🦋. In that case, TCP parameters can live in the interface configuration. Typical examples are the Maximum Segment Size (MSS) or config related to hardware offloading.
  • Connection parameters: Lots of implementations have ways to influence how each TCP connection behaves, like through the programming interface apps use 💖. Typical examples are socket options in the socket API, such as disabling the Nagle algorithm (as described in "Transmission Control Protocol (TCP)" [RFC9293]) with TCP_NODELAY. If an application uses an interface like that, the app or application protocol config might include TCP-related parameters too. An example is the BGP YANG module for service provider networks [BGP-MODEL].
  • Application preferences: Setting TCP parameters can also be part of application preferences, templates, or profiles 🧚. An example would be the preferences defined in "An Abstract Application Layer Interface to Transport Services" [TAPS-INTERFACE].

So ngl, there's no ground truth for setting certain TCP parameters 😭, and different TCP implementations have used different modeling approaches. One implementation might define a given parameter globally, while another uses per-interface settings, and both approaches work well for their own use cases. Different systems may also use different default values. And TCP can be implemented in different ways, so the design choices in the protocol engine often affect which config options exist 🙈.

Even so, a bunch of TCP stack parameters need to be configured with YANG data models 👑. This document therefore defines a minimal YANG data model with the fundamental parameters. An important use case is TCP config on network elements, like routers, which often use YANG data models. The model specifies the TCP parameters that matter on those TCP stacks.

This especially applies to support for the TCP Authentication Option (TCP-AO) [RFC5925] and its cryptographic algorithms [RFC5926] 🔐. TCP-AO is used on routers to secure routing protocols like BGP. In that case, a YANG data model for TCP-AO config is required. The model in this document includes the parameters TCP-AO config needs, like the values of SendID and RecvID. The key chain for TCP-AO can be modeled with the YANG data model for key chains [RFC8177], and the groupings defined in this document can be imported and used as part of that preconfiguration.

Given an installed base, the model also allows enabling the legacy TCP MD5 signature option [RFC2385] 🕰️. The TCP MD5 signature option was obsoleted by TCP-AO in 2010. If current implementations need TCP authentication, it is RECOMMENDED to use TCP-AO [RFC5925] ✨.

Similar to the TCP MIB [RFC4022], this document also specifies basic statistics, a TCP connection list, and a TCP listener list 📊.

  • Statistics: Counters for the number of active and passive opens, sent and received TCP segments, errors, and possibly other detailed debugging info 🔍.
  • TCP connection list: Access to status info for all TCP connections. Note that the connection table is modeled as a list that is readable and writable, even though a connection can't be created by adding entries to the table. Similarly, deleting connections from this list is implementation-specific 🫠.
  • TCP listener list: A list with info about TCP listeners, meaning applications willing to accept connections 👂.

This lets implementations of the TCP MIB [RFC4022] migrate to the YANG data model defined in this memo 🦋. Note that the TCP MIB doesn't include a way to reset statistics, which this document does define. That's not a huge addition, since a reset can simply be implemented by storing offset values for the counters.

This version of the module does not model details of Multipath TCP [RFC8684]. That could be addressed in a later version of this document 🌈.

3.2. Model Design

The YANG data model defined in this document includes definitions from "YANG Groupings for TCP Clients and TCP Servers" [RFC9643]. Just like that model, this specification defines YANG groupings 🧩. That means these groupings can be reused in different YANG data models. They're meant to be used either standalone or for TCP-based protocols as part of a stack of protocol-specific config models. An example is the one described in "YANG Model for Border Gateway Protocol (BGP-4)" [BGP-MODEL] 💜.

3.3. Tree Diagram

This section gives an abridged tree diagram for the YANG module defined in this document 🌸. The annotations used in the diagram are defined in "YANG Tree Diagrams" [RFC8340]. The complete tree diagram is in Appendix B.

module: ietf-tcp
  +--rw tcp!
     +--rw connections
     |     ...
     +--ro tcp-listeners* [type address port]
     |     ...
     +--ro statistics {statistics}?
           ...

  augment /key-chain:key-chains/key-chain:key-chain/key-chain:key:
    +--rw authentication {authentication}?
       +--rw keychain?    key-chain:key-chain-ref
       +--rw (authentication)?
             ...

4. TCP YANG Data Model

Here's the main event 🎀. This YANG module references "The TCP Authentication Option" [RFC5925], "Protection of BGP Sessions via the TCP MD5 Signature Option" [RFC2385], and "Transmission Control Protocol (TCP)" [RFC9293]. It imports "Common YANG Data Types" [RFC6991], "Network Configuration Access Control Model" [RFC8341], and "YANG Groupings for TCP Clients and TCP Servers" [RFC9643] 💅.

<CODE BEGINS> file "ietf-tcp@2024-10-10.yang"
module ietf-tcp {
  yang-version 1.1;
  namespace "urn:ietf:params:xml:ns:yang:ietf-tcp";
  prefix tcp;

  import ietf-yang-types {
    prefix yang;
    reference
      "RFC 6991: Common YANG Data Types.";
  }
  import ietf-tcp-common {
    prefix tcpcmn;
    reference
      "RFC 9643: YANG Groupings for TCP Clients and TCP Servers.";
  }
  import ietf-inet-types {
    prefix inet;
    reference
      "RFC 6991: Common YANG Data Types.";
  }
  import ietf-netconf-acm {
    prefix nacm;
    reference
      "RFC 8341: Network Configuration Access Control Model.";
  }
  import ietf-key-chain {
    prefix key-chain;
    reference
      "RFC 8177: YANG Data Model for Key Chains.";
  }

  organization
    "IETF TCPM Working Group";

  contact
    "WG Web:   https://datatracker.ietf.org/wg/tcpm/about
     WG List:  TCPM WG <tcpm@ietf.org>

     Authors:  Michael Scharf <michael.scharf@hs-esslingen.de>
               Mahesh Jethanandani <mjethanandani@gmail.com>
               Vishal Murgai <vmurgai@gmail.com>";

  description
    "This module focuses on fundamental TCP functions and basic
     statistics.  The model can be augmented to address more advanced
     or implementation-specific TCP features.

     The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
     NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
     'MAY', and 'OPTIONAL' in this document are to be interpreted as
     described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
     they appear in all capitals, as shown here.

     Copyright (c) 2024 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 Revised BSD License set
     forth in Section 4.c of the IETF Trust's Legal Provisions
     Relating to IETF Documents
     (https://trustee.ietf.org/license-info).

     This version of this YANG module is part of RFC 9648
     (https://www.rfc-editor.org/info/rfc9648); see the RFC itself
     for full legal notices.";

  revision 2024-10-10 {
    description
      "Initial version.";
    reference
      "RFC 9648: YANG Data Model for TCP.";
  }

  // Typedefs
  typedef mss {
    type uint16;
    description
      "Type definition for the Maximum Segment Size.";
  }

  // Features
  feature statistics {
    description
      "This implementation supports statistics reporting.";
  }

  feature authentication {
    description
      "This implementation supports authentication.";
  }

  // Identities
  identity aes-128 {
    base key-chain:crypto-algorithm;
    description
      "AES128 authentication algorithm used by TCP-AO.";
    reference
      "RFC 5926: Cryptographic Algorithms for the TCP
                 Authentication Option (TCP-AO).";
  }

  // TCP-AO Groupings

  grouping ao {
    leaf send-id {
      type uint8 {
        range "0..max";
      }
      description
        "The SendID is inserted as the KeyID of the TCP-AO option
         of outgoing segments.  In a consistent configuration, the
         SendID matches the RecvID at the other endpoint.";
      reference
        "RFC 5925: The TCP Authentication Option, Section 3.1.";
    }

    leaf recv-id {
      type uint8 {
        range "0..max";
      }
      description
        "The RecvID is matched against the TCP-AO KeyID of incoming
         segments.  In a consistent configuration, the RecvID matches
         the SendID at the other endpoint.";
      reference
        "RFC 5925: The TCP Authentication Option, Section 3.1.";
    }

    leaf include-tcp-options {
      type boolean;
      default "true";
      description
        "When set to true, TCP options are included in the message
         authentication code (MAC) calculation.";
      reference
        "RFC 5925: The TCP Authentication Option, Section 3.1.";
    }

    leaf accept-key-mismatch {
      type boolean;
      description
        "Accept, when set to true, TCP segments with a Master Key
         Tuple (MKT) that is not configured.";
      reference
        "RFC 5925: The TCP Authentication Option, Section 7.3.";
    }

    leaf r-next-key-id {
      type uint8;
      config false;
      description
        "A field indicating the Master Key Tuple (MKT) that is ready
         at the sender to be used to authenticate received segments,
         i.e., the desired 'receive next' key ID.";
      reference
        "RFC 5925: The TCP Authentication Option.";
    }

    description
      "Authentication Option (AO) for TCP.";
    reference
      "RFC 5925: The TCP Authentication Option.";
  }

okay bestie, we're picking right back up in the TCP YANG model 💖 this part is basically all YANG code, so I'm keeping every line exact 🫶

// TCP configuration

container tcp {
  presence "The container for TCP configuration.";

  description
    "TCP container.";

  container connections {
    list connection {
      key "local-address remote-address local-port remote-port";

      leaf local-address {
        type inet:ip-address;
        description
          "Identifies the address that is used by the local
           endpoint for the connection and is one of the four
           elements that form the connection identifier.";
      }

      leaf remote-address {
        type inet:ip-address;
        description
          "Identifies the address that is used by the remote
           endpoint for the connection and is one of the four
           elements that form the connection identifier.";
      }

      leaf local-port {
        type inet:port-number;
        description
          "Identifies the local TCP port used for the connection
           and is one of the four elements that form the
           connection identifier.";
      }

      leaf remote-port {
        type inet:port-number;
        description
          "Identifies the remote TCP port used for the connection
           and is one of the four elements that form the
           connection identifier.";
      }

      leaf mss {
        type mss;
        description
          "Maximum Segment Size (MSS) desired on this connection.
           Note that the 'effective send MSS' can be smaller than
           what is configured here.";
        reference
          "RFC 9293: Transmission Control Protocol (TCP).";
      }

      leaf pmtud {
        type boolean;
        default "false";
        description
          "Turns Path Maximum Transmission Unit Discovery (PMTUD)
           on (true) or off (false).";
        reference
          "RFC 9293: Transmission Control Protocol (TCP).";
      }

      uses tcpcmn:tcp-common-grouping;

      leaf state {
        type enumeration {
          enum closed {
            value 1;
            description
              "Connection is closed. Connections in this state
               may not appear in this list.";
          }
          enum listen {
            value 2;
            description
              "Represents waiting for a connection request from any
               remote TCP peer and port.";
          }
          enum syn-sent {
            value 3;
            description
              "Represents waiting for a matching connection request
               after having sent a connection request.";
          }
          enum syn-received {
            value 4;
            description
              "Represents waiting for a confirming connection
               request acknowledgment after having both received
               and sent a connection request.";
          }
          enum established {
            value 5;
            description
              "Represents an open connection; data received can be
               delivered to the user.  The normal state for the
               data transfer phase of the connection.";
          }
          enum fin-wait-1 {
            value 6;
            description
              "Represents waiting for a connection termination
               request from the remote TCP peer or an
               acknowledgment of the connection termination
               request previously sent.";
          }
          enum fin-wait-2 {
            value 7;
            description
              "Represents waiting for a connection termination
               request from the remote TCP peer.";
          }
          enum close-wait {
            value 8;
            description
              "Represents waiting for a connection termination
               request from the local user.";
          }
          enum last-ack {
            value 9;
            description
              "Represents waiting for an acknowledgment of the
               connection termination request previously sent to
               the remote TCP peer (this termination request sent
               to the remote TCP peer already included an
               acknowledgment of the termination request sent from
               the remote TCP peer).";
          }
          enum closing {
            value 10;
            description
              "Represents waiting for a connection termination
               request acknowledgment from the remote TCP peer.";
          }
          enum time-wait {
            value 11;
            description
              "Represents waiting for enough time to pass to be
               sure the remote TCP peer received the
               acknowledgment of its connection termination
               request and to avoid new connections being impacted
               by delayed segments from previous connections.";
          }
        }
        config false;
        description
          "The state of this TCP connection.";
      }
      description
        "List of TCP connections with their parameters.

         The list is modeled as writable even though only some of
         the nodes are writable, e.g., keepalive.  Connections
         that are created and match this list SHOULD apply the
         writable parameters.  At the same time, implementations
         may not allow creation of new TCP connections simply by
         adding entries to the list.  Furthermore, the behavior
         upon removal is implementation-specific.  Implementations
         may not support closing or resetting a TCP connection
         upon an operation that removes the entry from the list.

         The operational state of this list SHOULD reflect
         connections that have configured but not created and
         connections that have been created.  Connections in the
         CLOSED state are not reflected on this list.";
    }
    description
      "A container of all TCP connections.";
  }

  list tcp-listeners {
    key "type address port";
    config false;

    description
      "A table containing information about a particular
       TCP listener.";

    leaf type {
      type inet:ip-version;
      description
        "The address type of address.  The value
         should be unspecified (0) if connection initiations
         to all local IP addresses are accepted.";
    }

    leaf address {
      type union {
        type inet:ip-address;
        type string {
          length "0";
        }
      }
      description
        "The local IP address for this TCP connection.

         The value of this node can be represented in three
         possible ways, depending on the characteristics of the
         listening application:

         1. For an application willing to accept both IPv4 and
            IPv6 datagrams, the value of this node must be
            ''h (a zero-length octet string), with the value
            of the corresponding 'type' object being
            unspecified (0).

         2. For an application willing to accept only IPv4 or
            IPv6 datagrams, the value of this node must be
            '0.0.0.0' or '::' respectively, with
            'type' representing the appropriate address type.

         3. For an application that is listening for data
            destined only to a specific IP address, the value
            of this node is the specific local address, with
            'type' representing the appropriate address type.";
    }

    leaf port {
      type inet:port-number;
      description
        "The local port number for this TCP connection.";
    }
  }

  container statistics {
    if-feature "statistics";
    config false;

    leaf active-opens {
      type yang:counter64;
      description
        "The number of times that TCP connections have made a
         direct transition to the SYN-SENT state from the CLOSED
         state.";
      reference
        "RFC 9293: Transmission Control Protocol (TCP).";
    }

    leaf passive-opens {
      type yang:counter64;
      description
        "The number of times TCP connections have made a direct
         transition to the SYN-RCVD state from the LISTEN state.";
      reference
        "RFC 9293: Transmission Control Protocol (TCP).";
    }

    leaf attempt-fails {
      type yang:counter64;
      description
        "The number of times that TCP connections have made a
         direct transition to the CLOSED state from either the
         SYN-SENT state or the SYN-RCVD state, plus the number of
         times that TCP connections have made a direct transition
         to the LISTEN state from the SYN-RCVD state.";
      reference
        "RFC 9293: Transmission Control Protocol (TCP).";
    }

    leaf establish-resets {
      type yang:counter64;
      description
        "The number of times that TCP connections have made a
         direct transition to the CLOSED state from either the
         ESTABLISHED state or the CLOSE-WAIT state.";
      reference
        "RFC 9293: Transmission Control Protocol (TCP).";
    }

    leaf currently-established {
      type yang:gauge32;
      description
        "The number of TCP connections for which the current state
         is either ESTABLISHED or CLOSE-WAIT.";
      reference
        "RFC 9293: Transmission Control Protocol (TCP).";
    }

    leaf in-segments {
      type yang:counter64;
      description
        "The total number of TCP segments received, including those
         received in error.  This count includes TCP segments
         received on currently established connections.";
      reference
        "RFC 9293: Transmission Control Protocol (TCP).";
    }

    leaf out-segments {
      type yang:counter64;
      description
        "The total number of TCP segments sent, including those on
         current connections but excluding those containing only
         retransmitted octets.";
      reference
        "RFC 9293: Transmission Control Protocol (TCP).";
    }

    leaf retransmitted-segments {
      type yang:counter64;
      description
        "The total number of TCP segments retransmitted; that is,
         the number of TCP segments transmitted containing one or
         more previously transmitted octets.";
      reference
        "RFC 9293: Transmission Control Protocol (TCP).";
    }

    leaf in-errors {
      type yang:counter64;
      description
        "The total number of TCP segments received in error
         (e.g., bad TCP checksums).";
      reference
        "RFC 9293: Transmission Control Protocol (TCP).";
    }

the connections list is where the vibes get intense 💅 the state enum is literally the TCP state machine in YANG form, values 1 through 11, and the SHOULDs in the list description are the only requirement keywords in this chunk 🔥 tcp-listeners is config false so it's operational state only ✨

and the statistics container is giving data-analyst main character energy 📊🦋 keep going, more parts are coming 🌸

         leaf out-resets {
           type yang:counter64;
           description
             "The number of TCP segments sent containing the RST flag.";
           reference
             "RFC 9293: Transmission Control Protocol (TCP).";
         }

         leaf auth-failures {
           if-feature "authentication";
           type yang:counter64;
           description
             "The number of times that authentication has failed either
              with TCP-AO or MD5.";
         }

         action reset {
           nacm:default-deny-all;
           description
             "Reset statistics action command.";
           input {
             leaf reset-at {
               type yang:date-and-time;
               description
                 "Time when the reset action needs to be
                  executed.";
             }
           }
           output {
             leaf reset-finished-at {
               type yang:date-and-time;
               description
                 "Time when the reset action command completed.";
             }
           }
         }
         description
           "Statistics across all connections.";
       }
     }

     augment "/key-chain:key-chains/key-chain:key-chain/key-chain:key" {
       description
         "Augmentation of the key-chain model to add TCP-AO and TCP-MD5
          authentication.";

       container authentication {
         if-feature "authentication";
         leaf keychain {
           type key-chain:key-chain-ref;
           description
             "Reference to the key chain that will be used by
              this model.  Applicable for TCP-AO and TCP-MD5
              only.";
           reference
             "RFC 8177: YANG Data Model for Key Chains.";
         }

         choice authentication {
           container ao {
             presence "Presence container for all TCP-AO related"
                    + " configuration";
             uses ao;
             description
               "Use TCP-AO to secure the connection.";
           }

           container md5 {
             presence "Presence container for all MD5 related"
                    + " configuration";
             description
               "Use TCP-MD5 to secure the connection.  As the TCP MD5
                signature option is obsoleted by TCP-AO, it is
                RECOMMENDED to use TCP-AO instead.";
             reference
               "RFC 2385: Protection of BGP Sessions via the TCP MD5
                          Signature Option.";
           }
           description
             "Choice of TCP authentication.";
         }
         description
           "Authentication definitions for TCP configuration.
            This includes parameters such as how to secure the
            connection, which can be part of either the client
            or server.";
       }
     }
   }
   <CODE ENDS>

5. IANA Considerations ✨

5.1. The IETF XML Registry 🎀

okay so IANA has registered one URI in the "ns" registry from the "IETF XML Registry" [RFC3688] 💅 here's the entry:

URI:  urn:ietf:params:xml:ns:yang:ietf-tcp
Registrant Contact:  The IESG
XML:  N/A; the requested URI is an XML namespace.

5.2. The YANG Module Names Registry 🦋

IANA also registered something in the "YANG Module Names" registry, which was created by "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)" [RFC6020] ✨ the entry looks like this:

Name:  ietf-tcp
Namespace:  urn:ietf:params:xml:ns:yang:ietf-tcp
Prefix:  tcp
Reference:  RFC 9648

ngl this one is not maintained by IANA as a module, but IANA does keep the URI and the other module details up to date 🫶

6. Security Considerations 🔒

this section follows the template in Section 3.7.1 of [RFC8407], so it's giving structure 💜

okay so the "ietf-tcp" YANG module is a schema for data that you're meant to reach through YANG-based management protocols, like NETCONF [RFC6241] and RESTCONF [RFC8040]. Those protocols come with secure transport layers that are mandatory to implement, like Secure Shell (SSH) [RFC4252], TLS [RFC8446], and QUIC [RFC9000], and they also come with mandatory-to-implement mutual authentication 🔐

The Network Configuration Access Control Model (NACM) [RFC8341] is the bouncer here 💅 it lets you restrict particular NETCONF or RESTCONF users to a preconfigured subset of the protocol operations and content that are available.

Now the serious part, bestie 😭 there are a bunch of data nodes in this module that are writable, creatable, and deletable (that's "config true", which is the default). They can be sensitive or vulnerable in some network environments. Write operations (like edit-config) to these nodes without proper protection can wreck network operations. Here are the subtrees and data nodes, plus why they matter:

  • Common configuration included from NETCONF client and server models [RFC9643]. Unrestricted access to all the nodes, for example the keepalive idle timer, can cause connections to fail or to time out too early.
  • Authentication configuration. Unrestricted access to the nodes under authentication configuration can stop authenticated communication from being used and can cause connection setups to fail. That can lead to massive security vulnerabilities and service disruption for any traffic that needs authentication. 💀

Some of the readable data nodes in this module may also be sensitive or vulnerable in some environments, so it's important to control read access to them (for example through get, get-config, or notification). Here's what's up with those:

  • Unrestricted access to connection information of the client or server can be used by a malicious user to launch an attack.
  • Similarly, unrestricted access to statistics of the client or server can be used by a malicious user to exploit any vulnerabilities of the system.

Some of the RPC operations in this module may be sensitive or vulnerable too, so controlling access to them matters. Here's the one:

  • The YANG module lets you clear the statistics by executing the reset action. This action should be restricted to users with the right permission. 🙈

Heads up, the module in this document supports MD5, mainly to accommodate the BGP base that's already installed. MD5 has the security weaknesses discussed in Section 2 of [RFC6151] or Section 2.1 of [RFC6952], so keep that in mind 🌈

7. References 📚

7.1. Normative References

7.2. Informative References 📚✨

okay bestie, these are the extra reads that back up the spec, and I'm not gonna lie, the list is kind of iconic 💅

Appendix A. Examples 🎀

A.1. Keepalive Configuration 💖

this one's a cute little demo of how a specific connection gets set up for keepalives 🫶

NOTE: '\' line wrapping per RFC 8792

<?xml version="1.0" encoding="UTF-8"?>
<!--
This example shows how TCP keepalive, MSS, and PMTU can be configure\
d for a given connection. An idle connection is dropped after
idle-time + (max-probes * probe-interval).
-->
<tcp
    xmlns="urn:ietf:params:xml:ns:yang:ietf-tcp">
  <connections>
    <connection>
      <local-address>192.0.2.1</local-address>
      <remote-address>192.0.2.2</remote-address>
      <local-port>1025</local-port>
      <remote-port>22</remote-port>
      <mss>1400</mss>
      <pmtud>true</pmtud>
      <keepalives>
        <idle-time>5</idle-time>
        <max-probes>5</max-probes>
        <probe-interval>10</probe-interval>
      </keepalives>
    </connection>
  </connections>
</tcp>

A.2. TCP-AO Configuration 🔥

this example shows how to model a TCP-AO [RFC5925] configuration for the example in "TCP Authentication Option (TCP-AO) Test Vectors" [RFC9235]. the IP addresses and other parameters are taken straight from the test vectors, so it's all legit 👑

NOTE: '\' line wrapping per RFC 8792

<?xml version="1.0" encoding="UTF-8"?>
<!--
This example sets TCP-AO configuration parameters similarly to
the examples in RFC 9235.
-->

<key-chains
    xmlns="urn:ietf:params:xml:ns:yang:ietf-key-chain">
  <key-chain>
    <name>ao-config</name>
    <description>"An example for TCP-AO configuration."</description>
    <key>
      <key-id>55</key-id>
      <lifetime>
        <send-lifetime>
          <start-date-time>2017-01-01T00:00:00Z</start-date-time>
          <end-date-time>2017-02-01T00:00:00Z</end-date-time>
        </send-lifetime>
        <accept-lifetime>
          <start-date-time>2016-12-31T23:59:55Z</start-date-time>
          <end-date-time>2017-02-01T00:00:05Z</end-date-time>
        </accept-lifetime>
      </lifetime>
      <crypto-algorithm
          xmlns:tcp=
          "urn:ietf:params:xml:ns:yang:ietf-tcp">tcp:aes-128</crypto\
-algorithm>
      <key-string>
        <keystring>testvector</keystring>
      </key-string>
      <authentication
          xmlns="urn:ietf:params:xml:ns:yang:ietf-tcp">
        <keychain>ao-config</keychain>
        <ao>
          <send-id>61</send-id>
          <recv-id>84</recv-id>
        </ao>
      </authentication>
    </key>
  </key-chain>
</key-chains>

Appendix B. Complete Tree Diagram 🌈

here's the full tree diagram for the TCP YANG data model, so you can see how everything nests together 🧚

module: ietf-tcp
  +--rw tcp!
     +--rw connections
     |  +--rw connection*
     |          [local-address remote-address local-port remote-port]
     |     +--rw local-address     inet:ip-address
     |     +--rw remote-address    inet:ip-address
     |     +--rw local-port        inet:port-number
     |     +--rw remote-port       inet:port-number
     |     +--rw mss?              mss
     |     +--rw pmtud?            boolean
     |     +--rw keepalives! {keepalives-supported}?
     |     |  +--rw idle-time         uint16
     |     |  +--rw max-probes        uint16
     |     |  +--rw probe-interval    uint16
     |     +--ro state?            enumeration
     +--ro tcp-listeners* [type address port]
     |  +--ro type       inet:ip-version
     |  +--ro address    union
     |  +--ro port       inet:port-number
     +--ro statistics {statistics}?
        +--ro active-opens?             yang:counter64
        +--ro passive-opens?            yang:counter64
        +--ro attempt-fails?            yang:counter64
        +--ro establish-resets?         yang:counter64
        +--ro currently-established?    yang:gauge32
        +--ro in-segments?              yang:counter64
        +--ro out-segments?             yang:counter64
        +--ro retransmitted-segments?   yang:counter64
        +--ro in-errors?                yang:counter64
        +--ro out-resets?               yang:counter64
        +--ro auth-failures?            yang:counter64
        |       {authentication}?
        +---x reset
           +---w input
           |  +---w reset-at?   yang:date-and-time
           +--ro output
              +--ro reset-finished-at?   yang:date-and-time

  augment /key-chain:key-chains/key-chain:key-chain/key-chain:key:
    +--rw authentication {authentication}?
       +--rw keychain?    key-chain:key-chain-ref
       +--rw (authentication)?
          +--:(ao)
          |  +--rw ao!
          |     +--rw send-id?               uint8
          |     +--rw recv-id?               uint8
          |     +--rw include-tcp-options?   boolean
          |     +--rw accept-key-mismatch?   boolean
          |     +--ro r-next-key-id?         uint8
          +--:(md5)
             +--rw md5!

Acknowledgements 🙌

Michael Scharf was supported by the StandICT.eu project, which is funded by the European Commission under the Horizon 2020 Programme. so grateful 🥹

the following people reviewed this document and contributed to it (in alphabetical order): Mohamed Boucadair, Gorry Fairhurst, Jeffrey Haas, and Tom Petch. huge thanks to all of them, they're the real MVPs ✨

Authors' Addresses 💌

Michael Scharf Hochschule Esslingen University of Applied Sciences Kanalstr. 33 73728 Esslingen am Neckar Germany Email: michael.scharf@hs-esslingen.de

Mahesh Jethanandani Kloud Services Email: mjethanandani@gmail.com

Vishal Murgai F5, Inc. Email: vmurgai@gmail.com

📦 where this page comes from