Stubl: an IPv6 Stateless Tunnel Broker for LANs -- Overview -- Stubl is a transition mechanism for providing a basic level of IPv6 connectivity to individual nodes on a private network. All that's required is a single Linux server with an IPv6 /64 subnet routed to it. The Stubl server consists of a Linux kernel module (stubl.ko) for handling the tunnel packets, and an HTTP server (stubl_http.py) for calculating clients' addresses and providing tunnel setup instructions. The main advantage of Stubl is that it allows a user on the network, running any major OS, to get a working IPv6 connection with nothing but a few lines of shell commands. This makes it very easy for developers to start getting familiar with the protocol, with minimal administrative overhead. -- How it works -- Stubl can be thought of as "6to4 for LANs". A client's address is generated by concatenating the Stubl server's 64-bit prefix with the client's private IPv4 address. For example, with a prefix of 2001:db8:0:1234, and a client IP address of 192.168.2.9, the following IPv6 address is generated: 2001:db8:0:1234:c0a8:0209:: Then, the suffix of the address is encrypted with a 64-bit block cipher, using a key known only to the server. For example, the above address might encrypt to: 2001:db8:0:1234:3d06:b9a0:cb97:27a4 The stubl_http.py daemon handles the address generation, and provides the user with shell commands which create a point-to-point tunnel to the server, add the generated IPv6 address to the interface, and assign a default route through that interface. On the server side, the kernel module accepts IPv6 packets from the outside world whose destination address matches the 64-bit prefix configured for the tunnel. It then decrypts the 64-bit suffix, and verifies that the embedded address is well-formed, and within the range of whitelisted IPv4 subnets that have been assigned to the tunnel. If all goes well, the packet is wrapped in IPv4 proto-41, and forwarded to the matching endpoint. For packets traveling from the LAN toward the outside world, all of the same checks are performed using the source IPv4 and IPv6 addresses, ensuring that only well-formed addresses are able to pass. The upshot of embedding the (encrypted) IPv4 address within the IPv6 address is that the tunnel server does not need to maintain ANY state about which clients have established tunnels. Thus, there's no need to ping endpoints to check for activity, and tunnels can just be abandoned without worrying about doing any cleanup. -- Encrypted Addresses? -- Arguably the most unusual aspect of Stubl is that it generates its client addresses using a block cipher. While this step is not strictly necessary, it does have some nice properties: - Most private IPv4 networks were designed with the assumption that the addresses would not be visible from the outside world. This may or may not have any real security significance, but it's best to err on the side of caution by not leaking these addresses on purpose. - The checks performed by the kernel module when decrypting addresses ensure that only a small fraction (1 in 2^26) of addresses can ever possibly result in the generation of an IPv4 tunnel packet on the LAN. The module's configured whitelist of IPv4 subnets can drop this fraction by a few more orders of magnitude. Thus, it is relatively infeasible for an attacker to blindly scan the network for tunnel endpoints. - The address generation algorithm makes multiple attempts to generate a client address which has the RFC2373 Universal/Local bit set to 0. This means that a Stubl client's address is effectively indistinguishable from a random RFC3041 "Privacy address." -- Firewalling -- Beware that Stubl is absolutely NOT A FIREWALL. It will happily pass any evil IPv6 packets to the clients behind it. The configuration of an IPv6 firewall is beyond the scope of this document. -- Combining Stubl with sit -- The tunnel server will need to have some sort of IPv6 upstream connectivity. Stubl has been designed to coexist with the real 'sit' module, and only scoops up proto-41 packets whose source IPv6 address matches the configured tunnel prefix. This means it should be possible to set up a Stubl server which itself gets connectivity through a configured tunnel, 6to4, etc. If you do this, you'll have to be careful to filter any proto-41 packets from the Internet with a spoofed source address within the range of Stubl's whitelisted subnets. -- Comparison with ISATAP -- ISATAP is another mechanism for running IPv6 on top of a unicast IPv4 local network. The advantages of Stubl over ISATAP include: - You only need to mess with one server to get started. - Never leaks your internal IPv4 addresses. - No special client-side software needed. - Easier to secure, since all traffic runs through one server. However, ISATAP is a much better approximation of a native IPv6 network, and has the following advantages over Stubl: - Multiple addresses per node. - Proper neighbor discovery and link-local addresses. - Better scalability, especially when talking between clients. In general, the best long-term solution is to deploy native IPv6 over Ethernet. Stubl will provide a quick & easy way for clients to see the Dancing Turtle, but it is inherently centralized, which implies a single point of failure, and limited scalability. -- How to actually set up a tunnel server -- 0. Requirements: - A Linux box - A working IPv6 connection, with an entire /64 subnet routed directly to the Linux box. - Python 2.4+ - PyCrypto ( http://www.amk.ca/python/code/crypto.html ) 1. Install the 'stubl' kernel module. cd kernel-module/linux-<version> make sudo make install 2. Create /etc/stubl.conf - Copy ./webserver/stubl.conf.example to /etc/stubl.conf - You may want to tweak permissions so no one else can read the file. - Generate a secret key using ./webserver/generate_tunnel_key.py - Edit the config to your liking. 3. Run this script, to reload the module and initialize the tunnel interface: sudo ./init_tunnel.sh 4. Run the web server, to provide setup instructions to other computers on the LAN. cd webserver ./stubl_http.py