Merge branch 'main' into metrics

Author: acul71

.gitignore

@@ -193,5 +193,7 @@ tests/interop/js_libp2p/js_node/src/package-lock.json
 # Sphinx documentation build
 _build/
 
+# Attack simulation test results
+tests/security/attack_simulation/results/
 libp2p-forge
 libp2p-metrics

README.md

@@ -11,7 +11,6 @@
 [![Python versions](https://img.shields.io/pypi/pyversions/libp2p.svg)](https://pypi.python.org/pypi/libp2p)
 [![Build Status](https://img.shields.io/github/actions/workflow/status/libp2p/py-libp2p/tox.yml?branch=main&label=build%20status)](https://github.com/libp2p/py-libp2p/actions/workflows/tox.yml)
 [![Docs build](https://readthedocs.org/projects/py-libp2p/badge/?version=latest)](http://py-libp2p.readthedocs.io/en/latest/?badge=latest)
-<a href="https://filecoin.drips.network/app/projects/github/libp2p/py-libp2p" target="_blank"><img src="https://filecoin.drips.network/api/embed/project/https%3A%2F%2Fgithub.com%2Flibp2p%2Fpy-libp2p/support.png?background=light&style=drips&text=project&stat=support" alt="Support py-libp2p on drips.network" height="32"></a>
 
 > py-libp2p has moved beyond its experimental roots and is steadily progressing toward production readiness. The core features are stable, and we’re focused on refining performance, expanding protocol support, and ensuring smooth interop with other libp2p implementations. We welcome contributions and real-world usage feedback to help us reach full production maturity.
 
@@ -140,3 +139,7 @@ _(non-normative, useful for team notes, not a reference)_
 **Communication over one connection with multiple protocols**: X and Y can communicate over the same connection using different protocols and the multiplexer will appropriately route messages for a given protocol to a particular handler function for that protocol, which allows for each host to handle different protocols with separate functions. Furthermore, we can use multiple streams for a given protocol that allow for the same protocol and same underlying connection to be used for communication about separate topics between nodes X and Y.
 
 **Why use multiple streams?**: The purpose of using the same connection for multiple streams to communicate over is to avoid the overhead of having multiple connections between X and Y. In order for X and Y to differentiate between messages on different streams and different protocols, a multiplexer is used to encode the messages when a message will be sent and decode a message when a message is received. The multiplexer encodes the message by adding a header to the beginning of any message to be sent that contains the stream id (along with some other info). Then, the message is sent across the raw connection and the receiving host will use its multiplexer to decode the message, i.e. determine which stream id the message should be routed to.
+
+### Support
+
+<a href="https://filecoin.drips.network/app/projects/github/libp2p/py-libp2p" target="_blank"><img src="https://filecoin.drips.network/api/embed/project/https%3A%2F%2Fgithub.com%2Flibp2p%2Fpy-libp2p/support.png?background=light&style=drips&text=project&stat=support" alt="Support py-libp2p on drips.network" height="32"></a>

docs/examples.rst

@@ -21,6 +21,8 @@ Examples
    examples.rendezvous
    examples.random_walk
    examples.multiple_connections
+   tls-support
+   gossipsub-1.2
    examples.websocket
    examples.tls
    examples.autotls

docs/index.rst

@@ -18,7 +18,6 @@ The Python implementation of the libp2p networking stack
 
     Examples <examples>
     API <libp2p>
-    GossipSub 1.2 <gossipsub-1.2>
 
 .. toctree::
     :maxdepth: 1

docs/libp2p.utils.rst

@@ -12,6 +12,14 @@ libp2p.utils.logging module
    :undoc-members:
    :show-inheritance:
 
+libp2p.utils.multiaddr_utils module
+-------------------------------------
+
+.. automodule:: libp2p.utils.multiaddr_utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 libp2p.utils.varint module
 --------------------------
 

docs/tls-support.rst

@@ -0,0 +1,186 @@
+Py-libp2p – TLS Support Documentation
+======================================================
+
+.. contents::
+   :depth: 2
+   :local:
+
+Overview of TLS in Libp2p
+-------------------------
+
+**Purpose of TLS in P2P networking**
+
+- Encrypts data between peers.
+- Authenticates peer identity using certificates.
+- Prevents man-in-the-middle attacks.
+
+**Integration in libp2p security modules**
+
+- TLS is one of the supported secure channel protocols (alongside Noise).
+- Negotiated during connection setup.
+
+**Current status**
+
+- **py-libp2p**: Experimental, usable for local and interop tests.
+- **go-libp2p / js-libp2p**: Stable and production-ready.
+
+Installation Requirements
+-------------------------
+
+**Additional dependencies**
+
+Ubuntu / Debian:
+
+.. code-block:: bash
+
+   sudo apt install build-essential python3-dev libffi-dev libssl-dev
+
+macOS:
+
+.. code-block:: bash
+
+   brew install openssl
+
+Enabling TLS in py-libp2p
+-------------------------
+
+**Working example – Listener and Dialer**
+
+Listener node:
+
+.. code-block:: python
+
+  import trio
+  import multiaddr
+  from libp2p import new_host
+  from libp2p.crypto.secp256k1 import create_new_key_pair
+  from libp2p.security.tls.transport import PROTOCOL_ID, TLSTransport
+
+  async def main():
+    key_pair = create_new_key_pair(secret=None)
+    tls_transport = TLSTransport(libp2p_keypair=key_pair)
+    sec_opt = {PROTOCOL_ID: tls_transport}
+    host = new_host(key_pair=key_pair, sec_opt=sec_opt)
+    listen_addr = multiaddr.Multiaddr("/ip4/0.0.0.0/tcp/8000")
+    async with host.run(listen_addrs=[listen_addr]):
+        while not host.get_addrs():
+            await trio.sleep(0.1)
+        addrs = host.get_addrs()
+        peer_id = host.get_id()
+        print("TLS-enabled listener at:", addrs[0] if addrs else "No addresses")
+        print("Peer ID:", peer_id)
+        print("\nUse this address with the dialer:")
+        print(f"  /ip4/127.0.0.1/tcp/8000/p2p/{peer_id}")
+        await trio.sleep_forever()
+
+  if __name__ == "__main__":
+    trio.run(main)
+
+Dialer node:
+
+.. code-block:: python
+
+  import trio
+  import multiaddr
+  from libp2p import new_host
+  from libp2p.crypto.secp256k1 import create_new_key_pair
+  from libp2p.security.tls.transport import PROTOCOL_ID, TLSTransport
+  from libp2p.peer.peerinfo import info_from_p2p_addr
+
+  async def main():
+      key_pair = create_new_key_pair(secret=None)
+      tls_transport = TLSTransport(libp2p_keypair=key_pair)
+      sec_opt = {PROTOCOL_ID: tls_transport}
+      host = new_host(key_pair=key_pair, sec_opt=sec_opt)
+
+      addr = "/ip4/127.0.0.1/tcp/8000/p2p/16Uiu2HAm3hATVnBDT13acn2utRJXsFa2LRRGrZwDsosJ1mFZsM2Q"
+      maddr = multiaddr.Multiaddr(addr)
+      peer_info = info_from_p2p_addr(maddr)
+
+      async with host.run(listen_addrs=[]):
+          await trio.sleep(0.5)
+          host.peerstore.add_addrs(peer_info.peer_id, peer_info.addrs, 120)
+
+          try:
+              await host.connect(peer_info)
+              print("Connected securely to", peer_info.peer_id)
+              await trio.sleep(1)
+          except Exception as e:
+              print(f"Connection failed: {e}")
+              raise
+
+  if __name__ == "__main__":
+      trio.run(main)
+
+**Defaults if no configuration is provided**
+
+- Generates a self-signed certificate automatically.
+
+**Note for testing with self-signed certificates**
+
+When testing with self-signed certificates, peers need to trust each other's certificates.
+You can do this by calling ``trust_peer_cert_pem()`` on the TLS transport before creating the host:
+
+.. code-block:: python
+
+   # For testing: trust peer certificates
+   listener_tls.trust_peer_cert_pem(dialer_tls.get_certificate_pem())
+   dialer_tls.trust_peer_cert_pem(listener_tls.get_certificate_pem())
+
+Certificate Management
+----------------------
+
+**Generate a development certificate**
+
+.. code-block:: bash
+
+   openssl req -x509 -newkey rsa:2048 \
+     -keyout key.pem -out cert.pem \
+     -days 365 -nodes -subj "/CN=py-libp2p"
+
+- Store keys outside version control.
+- Rotate certificates every 90 days in production.
+
+Testing TLS Connections
+-----------------------
+
+**Local test steps**
+
+1. Run the listener example.
+2. Start the dialer with the listener's multiaddress.
+3. Confirm the secure connection in logs.
+
+**Interop testing**
+
+- Ensure both nodes advertise `/tls/1.0.0`.
+- Peer IDs must match certificate public keys.
+
+Security Considerations
+-----------------------
+
+- Never disable certificate verification in production.
+- Use TLS 1.3 or later.
+- Pin certificates for critical peers.
+
+Troubleshooting
+---------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 30 40
+
+   * - Problem
+     - Cause
+     - Solution
+   * - Certificate not trusted
+     - Self-signed without trust store entry
+     - Add cert to local trust store or disable verification **only** in testing.
+   * - Protocol negotiation failed
+     - One peer does not support `/tls/1.0.0`
+     - Enable TLS on both peers or use Noise.
+   * - SSL handshake failure
+     - TLS version mismatch or clock skew
+     - Enforce TLS 1.3, sync system clock.
+   * - Connection refused
+     - Port blocked or listener not running
+     - Check firewall rules and listener status.