Experimental support for IPv6 (#7671)

Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: achamayou <4016369+achamayou@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 4 people

.github/workflows/ci.yml

@@ -113,7 +113,7 @@ jobs:
       ]
     container:
       image: mcr.microsoft.com/azurelinux/base/core:3.0
-      options: --user root --publish-all --cap-add NET_ADMIN --cap-add NET_RAW --cap-add SYS_PTRACE
+      options: --user root --publish-all --cap-add NET_ADMIN --cap-add NET_RAW --cap-add SYS_PTRACE --sysctl net.ipv6.conf.all.disable_ipv6=0 --sysctl net.ipv6.conf.default.disable_ipv6=0 --sysctl net.ipv6.conf.lo.disable_ipv6=0
 
     steps:
       - name: "Checkout dependencies"
@@ -187,7 +187,7 @@ jobs:
       ]
     container:
       image: mcr.microsoft.com/azurelinux/base/core:3.0
-      options: --user root --publish-all --cap-add NET_ADMIN --cap-add NET_RAW --cap-add SYS_PTRACE
+      options: --user root --publish-all --cap-add NET_ADMIN --cap-add NET_RAW --cap-add SYS_PTRACE --sysctl net.ipv6.conf.all.disable_ipv6=0 --sysctl net.ipv6.conf.default.disable_ipv6=0 --sysctl net.ipv6.conf.lo.disable_ipv6=0
 
     steps:
       - name: "Checkout dependencies"

.github/workflows/coverage.yml

@@ -21,7 +21,7 @@ jobs:
       ]
     container:
       image: mcr.microsoft.com/azurelinux/base/core:3.0
-      options: --user root --publish-all --cap-add NET_ADMIN --cap-add NET_RAW --cap-add SYS_PTRACE
+      options: --user root --publish-all --cap-add NET_ADMIN --cap-add NET_RAW --cap-add SYS_PTRACE --sysctl net.ipv6.conf.all.disable_ipv6=0 --sysctl net.ipv6.conf.default.disable_ipv6=0 --sysctl net.ipv6.conf.lo.disable_ipv6=0
 
     steps:
       - name: "Checkout dependencies"

.github/workflows/long-test.yml

@@ -29,7 +29,7 @@ jobs:
       ]
     container:
       image: mcr.microsoft.com/azurelinux/base/core:3.0
-      options: --user root --publish-all --cap-add NET_ADMIN --cap-add NET_RAW --cap-add SYS_PTRACE
+      options: --user root --publish-all --cap-add NET_ADMIN --cap-add NET_RAW --cap-add SYS_PTRACE --sysctl net.ipv6.conf.all.disable_ipv6=0 --sysctl net.ipv6.conf.default.disable_ipv6=0 --sysctl net.ipv6.conf.lo.disable_ipv6=0
 
     steps:
       - name: "Checkout dependencies"
@@ -89,7 +89,7 @@ jobs:
       ]
     container:
       image: mcr.microsoft.com/azurelinux/base/core:3.0
-      options: --user root --publish-all --privileged
+      options: --user root --publish-all --privileged --sysctl net.ipv6.conf.all.disable_ipv6=0 --sysctl net.ipv6.conf.default.disable_ipv6=0 --sysctl net.ipv6.conf.lo.disable_ipv6=0
 
     steps:
       - name: "Checkout dependencies"
@@ -152,7 +152,7 @@ jobs:
       ]
     container:
       image: mcr.microsoft.com/azurelinux/base/core:3.0
-      options: --user root --publish-all --cap-add NET_ADMIN --cap-add NET_RAW --cap-add SYS_PTRACE
+      options: --user root --publish-all --cap-add NET_ADMIN --cap-add NET_RAW --cap-add SYS_PTRACE --sysctl net.ipv6.conf.all.disable_ipv6=0 --sysctl net.ipv6.conf.default.disable_ipv6=0 --sysctl net.ipv6.conf.lo.disable_ipv6=0
 
     steps:
       - name: "Checkout dependencies"
@@ -224,7 +224,7 @@ jobs:
       ]
     container:
       image: mcr.microsoft.com/azurelinux/base/core:3.0
-      options: --user root --publish-all --cap-add NET_ADMIN --cap-add NET_RAW --cap-add SYS_PTRACE
+      options: --user root --publish-all --cap-add NET_ADMIN --cap-add NET_RAW --cap-add SYS_PTRACE --sysctl net.ipv6.conf.all.disable_ipv6=0 --sysctl net.ipv6.conf.default.disable_ipv6=0 --sysctl net.ipv6.conf.lo.disable_ipv6=0
 
     steps:
       - name: "Checkout dependencies"

.github/workflows/release.yml

@@ -104,7 +104,7 @@ jobs:
       ]
     container:
       image: ${{ needs.image_digest.outputs.image_digest }}
-      options: "--user root --publish-all --cap-add NET_ADMIN --cap-add NET_RAW --cap-add SYS_PTRACE"
+      options: "--user root --publish-all --cap-add NET_ADMIN --cap-add NET_RAW --cap-add SYS_PTRACE --sysctl net.ipv6.conf.all.disable_ipv6=0 --sysctl net.ipv6.conf.default.disable_ipv6=0 --sysctl net.ipv6.conf.lo.disable_ipv6=0"
 
     steps:
       - name: "Set SOURCE_DATE_EPOCH"

CHANGELOG.md

@@ -9,6 +9,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 [7.0.6]: https://github.com/microsoft/CCF/releases/tag/ccf-7.0.6
 
+### Added
+
+- Experimental support for IPv6. Node RPC and node-to-node interface hosts may now be specified as IPv6 literals in bracketed form (e.g. `[::1]:8000`), and addresses are consistently parsed, bound, connected (with fallback across mixed IPv4/IPv6 resolved addresses), serialised, and embedded in redirect URLs for IPv6 (#7671).
+
 ### Fixed
 
 - Forwarded commands are no longer processed until the node is part of the network, matching the existing behaviour for other node-to-node messages. Previously a forwarded command could be executed while the node was in an earlier startup state, which could lead to undefined behaviour for some commands (#7936).

doc/host_config_schema/host_config.json

@@ -20,7 +20,7 @@
               "description": "The published node address advertised to other nodes. This must be different on each node"
             }
           },
-          "description": "Addresses (host:port) to listen on for incoming node-to-node connections (e.g. internal consensus messages)",
+          "description": "Addresses (host:port) to listen on for incoming node-to-node connections (e.g. internal consensus messages). IPv6 literals must be bracketed, e.g. ``[::1]:8081``",
           "required": ["bind_address"],
           "additionalProperties": false
         },
@@ -293,7 +293,7 @@
                 "properties": {
                   "target_rpc_address": {
                     "type": "string",
-                    "description": "Address (host:port) of a node of the existing service to join"
+                    "description": "Address (host:port) of a node of the existing service to join. IPv6 literals must be bracketed, e.g. ``[2001:db8::1]:8080``"
                   },
                   "retry_timeout": {
                     "type": "string",

doc/operations/configuration.rst

@@ -21,6 +21,48 @@ The configuration for each CCF node must be contained in a single JSON configura
 .. include:: generated_config.rst
 
 
+IPv6 Addresses
+--------------
+
+.. note:: IPv6 support is currently **experimental**.
+
+Every address field accepts an IPv4 address, an IPv6 address, or a fully qualified domain name. IPv6 literals must be written in bracketed form, ``[host]:port``, so that the colons in the address are not mistaken for the host/port separator. This applies to all address fields, including:
+
+- ``network.node_to_node_interface.bind_address`` and ``published_address``
+- ``network.rpc_interfaces.[name].bind_address`` and ``published_address``
+- ``command.join.target_rpc_address``
+
+For example, to bind a node's interfaces to the IPv6 loopback address ``::1`` and publish an address on a different IPv6 host:
+
+.. code-block:: json
+
+    {
+      "network": {
+        "node_to_node_interface": { "bind_address": "[::1]:8081" },
+        "rpc_interfaces": {
+          "primary_rpc_interface": {
+            "bind_address": "[::1]:8080",
+            "published_address": "[2001:db8::1]:12345"
+          }
+        }
+      }
+    }
+
+A node joining over IPv6 sets ``command.join.target_rpc_address`` to the bracketed address of an existing node:
+
+.. code-block:: json
+
+    {
+      "command": {
+        "join": { "target_rpc_address": "[2001:db8::1]:12345" }
+      }
+    }
+
+When a node is identified by an IPv6 literal, the matching ``node_certificate.subject_alt_names`` entry uses the ``iPAddress:`` prefix with the **unbracketed** address, for example ``"iPAddress:2001:db8::1"``.
+
+.. note:: ``published_address`` defaults to ``bind_address`` when omitted, and is the address embedded in redirect URLs returned to clients. Brackets are added automatically where required, so a published IPv6 address appears in a redirect as ``https://[2001:db8::1]:12345/...``.
+
+
 Operator Features
 -----------------
 

doc/operations/start_network.rst

@@ -23,7 +23,7 @@ To create a new CCF network, the first node of the network should be started wit
 
 The unique identifier of a CCF node is the hex-encoded string of the SHA-256 digest of the public key contained in its identity certificate (e.g. ``50211327a77fc16dd2fba8fae5fffac3df909fceeb307cf804a4125ae2679007``). This unique identifier should be used by operators and members to refer to this node with CCF (for example, when :ref:`governance/common_member_operations:Trusting a New Node`).
 
-CCF nodes can be started by using IP Addresses (both IPv4 and IPv6 are supported) or by specifying a fully qualified domain name. If an FQDN is used then a ``dNSName`` subject alternative name should be specified as part of the ``node_certificate.subject_alt_names`` configuration entry. Once a DNS has been setup it will be possible to connect to the node over TLS by using the node's domain name.
+CCF nodes can be started by using IP Addresses (both IPv4 and IPv6 are supported; see :ref:`operations/configuration:IPv6 Addresses` for the bracketed ``[host]:port`` form required for IPv6 literals) or by specifying a fully qualified domain name. If an FQDN is used then a ``dNSName`` subject alternative name should be specified as part of the ``node_certificate.subject_alt_names`` configuration entry. Once a DNS has been setup it will be possible to connect to the node over TLS by using the node's domain name.
 
 When starting up, the node generates its own key pair and outputs the unendorsed certificate associated with its public key at the location specified by the ``node_certificate_file`` configuration entry. The certificate of the freshly-created CCF network is also output at the location specified by the ``service_certificate_file`` configuration entry.
 

include/ccf/service/node_info_network.h

@@ -188,16 +188,60 @@ namespace ccf
     }
   };
 
+  // Splits a NetAddress ("host:port") into its host and port components. IPv6
+  // literals are expected in bracketed form ("[host]:port"), and the brackets
+  // are stripped from the returned host so that it can be used directly for
+  // resolution, certificate SANs and comparison. A port-less address ("host"
+  // or "[host]") returns the host with an empty port. The inverse of
+  // make_net_address.
+  // See https://www.rfc-editor.org/info/rfc3986/#section-3.2.3
   inline static std::pair<std::string, std::string> split_net_address(
     const NodeInfoNetwork::NetAddress& addr)
   {
+    if (addr.starts_with('['))
+    {
+      // Only treat as a bracketed IPv6 literal if it is well-formed, i.e.
+      // exactly "[host]" or "[host]:port". Anything else (e.g.
+      // "[::1]foo:8000") falls through to the generic parsing below rather
+      // than being silently mis-parsed.
+      const auto close = addr.find(']');
+      if (
+        close != std::string::npos &&
+        (close + 1 == addr.size() || addr[close + 1] == ':'))
+      {
+        std::string host = addr.substr(1, close - 1);
+        std::string port;
+        if (close + 1 < addr.size())
+        {
+          port = addr.substr(close + 2);
+        }
+        return std::make_pair(std::move(host), std::move(port));
+      }
+    }
+
+    // rsplit_1 splits on the last ':'. When the address has no port it returns
+    // ("", addr), which would wrongly put the host in the port slot; handle the
+    // port-less case explicitly so the host stays in the first position.
+    if (addr.find(':') == std::string::npos)
+    {
+      return std::make_pair(addr, std::string());
+    }
+
     auto [host, port] = ccf::nonstd::rsplit_1(addr, ":");
     return std::make_pair(std::string(host), std::string(port));
   }
 
+  // Combines a host and port into a NetAddress ("host:port"). IPv6 literals
+  // (hosts containing ':') are wrapped in brackets to produce an unambiguous,
+  // URL-safe "[host]:port" form. Idempotent for already-bracketed hosts. The
+  // inverse of split_net_address.
   inline static NodeInfoNetwork::NetAddress make_net_address(
     const std::string& host, const std::string& port)
   {
+    if (host.find(':') != std::string::npos && !host.starts_with('['))
+    {
+      return fmt::format("[{}]:{}", host, port);
+    }
     return fmt::format("{}:{}", host, port);
   }
 

src/ds/cli_helper.h

@@ -17,14 +17,69 @@ namespace cli
 {
   using ParsedAddress = ccf::NodeInfoNetwork::NetAddress;
 
+  // Parses and validates a "host:port" (or bracketed "[host]:port") address
+  // from untrusted CLI input. Deliberately does NOT reuse
+  // ccf::split_net_address, despite the apparent overlap, because the two have
+  // different contracts:
+  //  - Missing port: for a bare host like "1.2.3.4" this substitutes
+  //    default_port, returning ("1.2.3.4", default_port); split_net_address
+  //    leaves the port empty, returning ("1.2.3.4", "").
+  //  - Validation: this checks the port is numeric and in 0-65535, and throws
+  //    on malformed input (unmatched '[', junk after ']'); split_net_address
+  //    does no validation and deliberately falls through to lenient parsing.
+  // That leniency is a safety property of split_net_address, which is on the
+  // consensus deserialization path and must not throw on already-persisted
+  // addresses. Validation belongs here, at the input boundary; keep them apart.
   static std::pair<std::string, std::string> validate_address(
     const ParsedAddress& addr, const std::string& default_port = "0")
   {
-    auto found = addr.find_last_of(':');
-    auto hostname = addr.substr(0, found);
+    std::string hostname;
+    std::string port;
 
-    const auto port =
-      found == std::string::npos ? default_port : addr.substr(found + 1);
+    if (!addr.empty() && addr.front() == '[')
+    {
+      // Bracketed IPv6 literal: "[host]:port" or "[host]". The brackets are
+      // stripped from the returned host.
+      const auto close = addr.find(']');
+      if (close == std::string::npos)
+      {
+        throw std::logic_error(
+          fmt::format("Address '{}' has an unmatched '['", addr));
+      }
+      hostname = addr.substr(1, close - 1);
+      if (close + 1 == addr.size())
+      {
+        // "[host]" with no port
+        port = default_port;
+      }
+      else if (addr[close + 1] == ':')
+      {
+        // "[host]:port"
+        port = addr.substr(close + 2);
+      }
+      else
+      {
+        throw std::logic_error(fmt::format(
+          "Address '{}' has unexpected characters after ']'", addr));
+      }
+    }
+    else
+    {
+      // Unbracketed IPv6 literals are ambiguous with the host:port separator.
+      // Require bracketed "[host]:port" form for any address containing more
+      // than one ':' (e.g. "::1").
+      if (
+        addr.find(':') != std::string::npos &&
+        addr.find(':') != addr.find_last_of(':'))
+      {
+        throw std::logic_error(fmt::format(
+          "IPv6 address '{}' must be bracketed as '[host]:port'", addr));
+      }
+
+      auto found = addr.find_last_of(':');
+      hostname = addr.substr(0, found);
+      port = found == std::string::npos ? default_port : addr.substr(found + 1);
+    }
 
     // Check if port is in valid range
     uint16_t port_n = 0;