A YANG Model for Transmission Control
Protocol (TCP) ConfigurationHochschule Esslingen -
University of Applied SciencesFlandernstr. 10173732EsslingenGermanymichael.scharf@hs-esslingen.deKloud Servicesmjethanandani@gmail.comSamsungvmurgai@gmail.com
Transport
TCPMYANGThis document specifies a minimal YANG model for TCP on devices that are
configured by network management protocols. The YANG model defines a
container for all TCP connections and groupings of authentication
parameters that can be imported and used in TCP implementations or by
other models that need to configure TCP parameters. The model also
includes basic TCP statistics. The model is compliant with Network Management Datastore
Architecture (NMDA) (RFC 8342).The Transmission Control
Protocol (TCP) is used by many applications in the Internet, including control
and management protocols. As such, TCP is implemented on network
elements that can be configured via network management protocols such as
NETCONF or RESTCONF.This document specifies a minimal YANG 1.1
model for configuring TCP on
network elements that support YANG. This YANG module is compliant with Network Management Datastore Architecture (NMDA).The YANG module has a narrow scope and focuses on a subset of
fundamental TCP functions and basic statistics. It defines a container
for TCP connection that includes definitions from YANG Groupings for TCP
Clients and TCP Servers. This model adheres to the
recommendation in BGP/MPLS IP Virtual
Private Networks as it allows enabling of
TCP-AO, and accommodates the
installed base that makes use of MD5. The module can be
augmented or updated to address more advanced or
implementation-specific TCP features in the future.Many protocol stacks on IP hosts use other methods to configure
TCP, such as operating system configuration or policies. Many TCP/IP
stacks cannot be configured by network management protocols such as
NETCONF or RESTCONF. Moreover, many existing TCP/IP stacks
do not use YANG data models. Such TCP implementations often have other
means to configure the parameters listed in this document. Such other
means are outside the scope of this document.This specification is orthogonal to the Management Information Base (MIB) for the Transmission
Control Protocol (TCP). The basic statistics defined in this
document follow the model of the TCP MIB. An TCP
Extended Statistics MIB is also available, but this document does
not cover such extended statistics. The YANG module also omits some
selected parameters included in TCP MIB, most notably the configured
Retransmission Timeout (RTO) algorithm. This is conscious decision as
these parameters hardly matter in a state-of-the-art TCP implementation.
It would also be possible also 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. However, this
approach is not used in this document, because a translated model would
not be up-to-date.There are other existing TCP-related YANG models, which are
orthogonal to this specification. Examples are:TCP header attributes are modeled in other security-related
models, such as YANG Data Model for Network
Access Control Lists (ACLs), Distributed
Denial-of-Service Open Thread Signaling (DOTS) Data Channel
Specification, or
I2NSF Capability
YANG Data Model.TCP-related configuration of a NAT (e.g., NAT44, NAT64,
Destination NAT) is defined in A YANG
Module for Network Address Translation (NAT) and Network Prefix
Translation (NPT) and A YANG Data
Model for Dual-Stack Lite (DS-Lite).TCP-AO and TCP MD5 configuration for Layer 3 VPNs is modeled in
A Layer 3 VPN Network YANG
Model. This model assumes that TCP-AO specific parameters
are preconfigured in addition to the keychain parameters. This issue is further
discussed below.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
when, and only when,
they appear in all capitals, as shown here.This document uses several placeholder values throughout the
document. Please replace them as follows and remove this note before
publication.RFC XXXX, where XXXX is the number assigned to this document at the
time of publication.2022-02-04 with the actual date of the publication of this
document.TCP is implemented on different system architectures. As a
result, there are many different and often implementation-specific ways
to configure parameters of the TCP engine. In addition, in
many TCP/IP stacks configuration exists for different scopes:Global configuration: Many TCP implementations have
configuration parameters that affect all TCP connections. Typical
examples include enabling or disabling optional protocol
features.Interface configuration: It can be useful to use different TCP
parameters on different interfaces, e.g., different device ports
or IP interfaces. In that case, TCP parameters can be part of the
interface configuration. Typical examples are the Maximum Segment
Size (MSS) or configuration related to hardware offloading.Connection parameters: Many implementations have means to
influence the behavior of each TCP connection, e.g., on the
programming interface used by applications. Typical examples are
socket options in the socket API, such as disabling the Nagle
algorithm by TCP_NODELAY. If an application uses such an
interface, it is possible that the configuration of the
application or application protocol includes TCP-related
parameters. An example is the BGP YANG Model for Service
Provider Networks .Policies: Setting of TCP parameters can also be part of system
policies, templates, or profiles. An example would be the
preferences defined in An
Abstract Application Layer Interface to Transport
Services.As a result, there is no ground truth for setting certain TCP
parameters, and traditionally different TCP implementation have used
different modeling approaches. For instance, one implementation may
define a given configuration parameter globally, while another one
uses per-interface settings, and both approaches work well for the
corresponding use cases. Also, different systems may use different
default values. In addition, TCP can be implemented in different ways
and design choices by the protocol engine often affect configuration
options.Nonetheless, a number of TCP stack parameters require configuration
by YANG models. This document therefore defines a minimal YANG model
with fundamental parameters directly following from TCP standards.An important use case is the TCP configuration on network elements
such as routers, which often use YANG data models. The model therefore
specifies TCP parameters that are important on such TCP stacks.This in particular applies to the support of TCP-AO. TCP Authentication Option (TCP-AO) is
used on routers to secure routing protocols such as BGP. In that case,
a YANG model for TCP-AO configuration is required. The model defined
in this document includes the required parameters for TCP-AO
configuration, such as the values of SendID and RecvID. The
keychain for TCP-AO can be modeled by the YANG
Data Model for Key Chains. The groupings defined in this document can be imported and used as part of such a preconfiguration.Given an installed base, the model also allows enabling of the
legacy TCP MD5 signature option. As the
TCP MD5 signature option is obsoleted by TCP-AO, it is strongly
RECOMMENDED to use TCP-AO.Similar to the TCP MIB, this document
also specifies basic statistics and a TCP connection table.Statistics: Counters for the number of active/passive opens,
sent and received segments, errors, and possibly other detailed
debugging informationTCP connection table: Access to status information for all TCP
connections. Note, the connection table is modeled as a list
that is read-writeable, even though a connection cannot be
created by adding entries to the table. Similarly, deletion
of connections from this list is implementation-specific.This allows implementations of TCP
MIB to migrate to the YANG model defined in this memo.
Note that the TCP MIB does not include means to reset statistics, which
are defined in this document. This is not a major addition, as a reset
can simply be implemented by storing offset values for the counters.This version of the module does not cover
Multipath TCP.The YANG model defined in this document includes definitions from
the YANG Groupings
for TCP Clients and TCP Servers. Similar to that model, this
specification defines YANG groupings. This allows reuse of these
groupings in different YANG data models. It is intended that these
groupings will be used either standalone or for TCP-based protocols as
part of a stack of protocol-specific configuration models. An example
could be the BGP YANG Model for
Service Provider Networks .This section provides an abridged tree diagram for the YANG module
defined in this document. Annotations used in the diagram are defined
in YANG Tree Diagrams .This YANG module references
The TCP Authentication Option,
Protection of BGP Sessions via the TCP MD5 Signature,
Transmission Control
Protocol (TCP) Specification,
and imports Common YANG Data Types
, The NETCONF Access Control
Model, and
YANG Groupings for TCP Clients and TCP Servers.
file "ietf-tcp@2022-02-04.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
"I-D.ietf-netconf-tcp-client-server: 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";
}
organization
"IETF TCPM Working Group";
contact
"WG Web:
WG List:
Authors: Michael Scharf (michael.scharf at hs-esslingen dot de)
Mahesh Jethanandani (mjethanandani at gmail dot com)
Vishal Murgai (vmurgai at gmail dot 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.
Copyright (c) 2021 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 Simplified 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 XXXX
(https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself
for full legal notices.
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.";
revision "2022-02-04" {
description
"Initial Version";
reference
"RFC XXXX, A YANG Model for Transmission Control Protocol (TCP)
Configuration.";
}
// Features
feature statistics {
description
"This implementation supports statistics reporting.";
}
// TCP-AO Groupings
grouping ao {
leaf enable-ao {
type boolean;
default "false";
description
"When set to true, TCP-Authentication Option (TCP-AO) is
enabled.";
}
leaf send-id {
type uint8 {
range "0..max";
}
must "../enable-ao = 'true'";
description
"The SendID is inserted as the KeyID of the TCP-AO option
of outgoing segments. The SendID must match the RecvID
at the other endpoint.";
reference
"RFC 5925: The TCP Authentication Option, Section 3.1.";
}
leaf recv-id {
type uint8 {
range "0..max";
}
must "../enable-ao = 'true'";
description
"The RecvID is matched against the TCP-AO KeyID of incoming
segments. The RecvID must match the SendID at the other
endpoint.";
reference
"RFC 5925: The TCP Authentication Option, Section 3.1.";
}
leaf include-tcp-options {
type boolean;
must "../enable-ao = 'true'";
default true;
description
"When set to true, TCP options are included in MAC
calculation.";
reference
"RFC 5925: The TCP Authentication Option, Section 3.1.";
}
leaf accept-key-mismatch {
type boolean;
must "../enable-ao = 'true'";
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.";
}
description
"Authentication Option (AO) for TCP.";
reference
"RFC 5925: The TCP Authentication Option.";
}
// MD5 grouping
grouping md5 {
description
"Grouping for use in authenticating TCP sessions using MD5.";
reference
"RFC 2385: Protection of BGP Sessions via the TCP MD5
Signature.";
leaf enable-md5 {
type boolean;
default "false";
description
"Enables, when set to true, support of MD5 to authenticate a
TCP session. As the TCP MD5 signature option is obsoleted by
TCP-AO, it is strongly RECOMMENDED to use TCP-AO instead.";
}
}
// 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.";
}
container common {
uses tcpcmn:tcp-common-grouping;
choice authentication {
case ao {
uses ao;
description
"Use TCP-AO to secure the connection.";
}
case md5 {
uses md5;
description
"Use TCP-MD5 to secure the connection.";
}
description
"Choice of TCP authentication.";
}
description
"Common definitions of TCP configuration. This includes
parameters such as how to secure the connection,
that can be part of either the client or server.";
}
description
"List of TCP connections with their parameters. The list
is modeled as writeable, but implementations may not
allow creation of new TCP connections by adding entries to
the list. Furthermore, the behavior upon removal is
implementation-specific. Implementations may support
closing or resetting a TCP connection upon an operation
that removes the entry from the list.";
}
description
"A container of all TCP connections.";
}
container statistics {
if-feature statistics;
config false;
leaf active-opens {
type yang:counter32;
description
"The number of times that TCP connections have made a
direct transition to the SYN-SENT state from the CLOSED
state.";
reference
"I-D.ietf-tcpm-rfc793bis: Transmission Control Protocol
(TCP) Specification.";
}
leaf passive-opens {
type yang:counter32;
description
"The number of times TCP connections have made a direct
transition to the SYN-RCVD state from the LISTEN state.";
reference
"I-D.ietf-tcpm-rfc793bis: Transmission Control Protocol
(TCP) Specification.";
}
leaf attempt-fails {
type yang:counter32;
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
"I-D.ietf-tcpm-rfc793bis: Transmission Control Protocol
(TCP) Specification.";
}
leaf establish-resets {
type yang:counter32;
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
"I-D.ietf-tcpm-rfc793bis: Transmission Control Protocol
(TCP) Specification.";
}
leaf currently-established {
type yang:gauge32;
description
"The number of TCP connections for which the current state
is either ESTABLISHED or CLOSE-WAIT.";
reference
"I-D.ietf-tcpm-rfc793bis: Transmission Control Protocol
(TCP) Specification.";
}
leaf in-segments {
type yang:counter64;
description
"The total number of segments received, including those
received in error. This count includes segments received
on currently established connections.";
reference
"I-D.ietf-tcpm-rfc793bis: Transmission Control Protocol
(TCP) Specification.";
}
leaf out-segments {
type yang:counter64;
description
"The total number of segments sent, including those on
current connections but excluding those containing only
retransmitted octets.";
reference
"I-D.ietf-tcpm-rfc793bis: Transmission Control Protocol
(TCP) Specification.";
}
leaf retransmitted-segments {
type yang:counter32;
description
"The total number of segments retransmitted; that is, the
number of TCP segments transmitted containing one or more
previously transmitted octets.";
reference
"I-D.ietf-tcpm-rfc793bis: Transmission Control Protocol
(TCP) Specification.";
}
leaf in-errors {
type yang:counter32;
description
"The total number of segments received in error (e.g., bad
TCP checksums).";
reference
"I-D.ietf-tcpm-rfc793bis: Transmission Control Protocol
(TCP) Specification.";
}
leaf out-resets {
type yang:counter32;
description
"The number of TCP segments sent containing the RST flag.";
reference
"I-D.ietf-tcpm-rfc793bis: Transmission Control Protocol
(TCP) Specification.";
}
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.";
}
}
}
]]>This document registers an URI in the "ns" subregistry of the
IETF XML Registry . Following the format
in IETF XML Registry , the following
registration is requested:This document registers a YANG module in the "YANG Module Names"
registry YANG - A Data Modeling Language
. Following the format in YANG - A Data
Modeling Language , the following registration is
requested:The registration is not maintained by IANA.The YANG module specified in this document defines a schema for data
that is designed to be accessed via network management protocols such as
NETCONF or RESTCONF
. The lowest NETCONF layer is the secure transport layer, and the
mandatory-to-implement secure transport is Secure Shell (SSH) described
in Using the NETCONF protocol over SSH .
The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement
secure transport is TLS .The Network Configuration Access Control Model
(NACM) provides the means to restrict access for particular
NETCONF or RESTCONF users to a preconfigured subset of all available
NETCONF or RESTCONF protocol operations and content.There are a number of data nodes defined in this YANG module that are
writable/creatable/deletable (i.e., "config true", which is the
default). These data nodes may be considered sensitive or vulnerable in
some network environments. Write operations (e.g., edit-config) to these
data nodes without proper protection can have a negative effect on
network operations. These are the subtrees and data nodes and their
sensitivity/vulnerability:Common configuration included from
NETCONF Client
and Server Models . Unrestricted
access to all the nodes, e.g., keepalive idle-timer,
can cause connections to fail or to timeout prematurely.Authentication configuration. Unrestricted access to the nodes under
authentication configuration can prevent the use of authenticated
communication and cause connection setups to fail. This can result
in massive security vulnerabilities and service disruption for the
traffic requiring authentication.Some of the readable data nodes in this YANG module may be considered
sensitive or vulnerable in some network environments. It is thus
important to control read access (e.g., via get, get-config, or
notification) to these data nodes. These are the subtrees and data nodes
and their sensitivity/vulnerability:Unrestricted access to connection information of the client or
server can be used by a malicious user to launch an attack, e.g.
MITM.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 YANG module may be considered
sensitive or vulnerable in some network environments. It is thus
important to control access to these operations. These are the
operations and their sensitivity/vulnerability:The YANG module allows for the statistics to be cleared by
executing the reset action. This action should be restricted to
users with the right permission.The module specified in this document supports MD5 to basically
accommodate the installed BGP base. MD5 suffers from the security
weaknesses discussed in Section 2 of RFC 6151
or Section 2.1 of RFC 6952.Michael Scharf was supported by the StandICT.eu project, which is
funded by the European Commission under the Horizon 2020 Programme.The following persons have contributed to this document by
reviews: Mohamed Boucadair, and Tom Petch.This particular example demonstrates how both a particular
connection can be configured for keepalives.192.0.2.1192.0.2.21025805510
]]>The following example demonstrates how to model a TCP-AO configuration for the example in TCP-AO Test Vectors.fd00::1fd00::21025179true6184ao-config"An example for TCP-AO configuration."\
61hmac-sha-1testvector84hmac-sha-1testvector
]]>Here is the complete tree diagram for the TCP YANG model.