How's it going with p2p?

[novemus]

Hello geek!

In this article, we will talk about the purpose and design of a small but useful network tool called plexus. This tool is written in C++. But it is likely that this will be interesting not only to C++ programmers, but also to anyone interested in network programming.

Motivation

Everyone can see how radically digital technologies have changed the world. Everybody migrated to the Internet, quite literally.
Scientists and programmers were the first, advanced youth followed them, then business came and everything started spinning.
Social networks arose, IT giants were born. The clumsy state also came with a delay. In the nineties, the Internet was the territory of true freedom or even anarchy. But now it's becoming more like the Matrix or some kind of it. The paradox is that the Internet architecture designed as decentralized, but the social infrastructure hosted on it is moving towards hyper-centralisation. The appearance of the Torrent, Tor or Bitcoin is like a riot on a ship that went off course. There are many reasons for such trend, but main one is that the Internet, although it helps to overcome borders, allows to collect and analyse a large amount of social information. As the result, this leads to illegal manipulations of data, attempts to direct a social life, and even invasions to the private spaces of citizens. The evolution of AI makes it all worse. At least, it's not very pleasant to feel like a fish in an aquarium. Although the virtual reality is a projection of the real life, it is very restricted in one important ability. This is the ability to make and maintain relationships without intermediaries. Secure and distributed social networks based on peer-to-peer solutions are still quite exotic. However, there is a evident societal demand for such things. One of the constraints is that the IPv4 networks and the NAT are still widespread. That's what we're going to talk about. Who is interested, can eat the red pill and go to the severe Zion. The blue pill will bring you back to the world of sweet dreams.

The NAT has solved the problem of the restricted 32-bits address space. However, NAT forces us to use third parties for private
communications, when our hosts are placed in different private networks. Most users are used to this and have no difficulties until they start thinking about safety and privacy of communications. But the programmers have been working on this for a long time and they have already come up with ways to protect your privacy. Overcoming NAT for P2P connections is used in some types of software, for example, IP-telephony, remote access systems, some messengers, distributed file systems, etc. But all these solutions are embedded in the relevant software and cannot be used separately. It would be great to have a universal tool of this kind. The plexus tool is the result of efforts to do this. To overcome NAT it implements the well-known UDP hole punching technique. We won't immerse into its details. Those who wish can find it on the Web. But further, it is assumed that the reader is familiar with it. Otherwise, skip the description of technical details and read about using of the plexus tool.

How it works

To put it simply, the plexus instances running on local and remote hosts synchronously punch holes in their NATs to each other direction and pass the control to specified applications. Also they pass to apps an endpoint of local interface from which punched a NAT, an endpoint issued by NAT on the public interface, a public endpoint of a peer and a session verification key. The plexus needs of an accessible STUN service to investigate NAT and access to email service to exchange investigated public endpoints with a peer. NATs have to use the independent mapping policy to map the client endpoint to endpoint of the public interface. Thus, for two outgoing packets from the same endpoint (address and port) to different destinations the NAT must assign the same public address and port. The filtering policy doesn't matter. The schema below shows the procedure in more detail.

After start, the plexus investigates is there a NAT and is its mapping policy appropriate, with the help of STUN service. If there is no NAT or NAT policy is suitable the plexus proceeds to the endpoint exchange procedure. One of the sides must run as an acceptor of peer connection requests. The other one has to initiate connection requests.

NAT punching procedure

1. The initiator investigates the mapped endpoint with the help of the STUN service punching a UDP hole in NAT at the same time, but only towards in the direction of the STUN at that moment. On step 6 it will punch the hole towards the peer through mapped endpoint.
2. The initiator sends email message with investigated endpoint and begins to wait the answer.
3. After the message received, the acceptor investigates own endpoint mapped by NAT.
4. The acceptor punches UDP hole to the peer direction and gets mapped endpoint. It sends a packet to the previously received endpoint. A short TTL is set for the punching packets, which enough to leave the home's NAT and don't reach the peer's NAT. This needs because there are NATs with strict filtering policy which drops mapped endpoints when unexpected packets are received. At this moment, the initiator has not yet punched the UDP hole to the peer's direction, so its NAT cannot transfer incoming packages to the local network.
5. The acceptor sends own endpoint to the peer by email and waits handshake. This is a verification procedure for exchanging special packages.
6. After the message received, the initiator starts the handshake sending a packet with special flag set to 0 to the peer's public endpoint. The flag indicates whether the plexus have seen any packet from the peer.
7. After the acceptor got and verified the packet, it sends a reply packet to the initiator with the flag set to 1.
8. After the initiator got and verified the packet, it sends a reply packet to the acceptor with the flag set to 1.

Thus, the handshake is considered completed after the sides received and sent packets with the flag set to 1. Now the control can be passed to the specified programs.

Visit the repository to read the build manual or download prebuild binaries.

Usage

One of the cases you can use the plexus when you want to connect to a host behind the NAT and there is no mutually accessible VPN.

Run plexus on remote host with accepting mode, set flag --accept. Optionally, you can set packet TTL with key --punch-hops, as we discussed above. By default it's set to 7. To determine actual TTL you can use some trace tools, for example traceroute. This argument matters only for accepting side.

plexus --accept --email-smtps=smtp.peermailer.com:xxx --email-imaps=imap.peermailer.com:xxx --email-login=peerlogin --email-passwd=peerpassword --email-from=peerhost@peermailer.com --email-to=yourhost@yourmailer.com --host-id=remote --peer-id=local --stun-server=stun.someserver.com --stun-client=xxx.xxx.xxx.xxx:xx --exec-command=~/plexus/exec.sh

When you need to connect, run plexus on the local host as initiator, without flag --accept.

plexus --email-smtps=smtp.yourmailer.com:xxx --email-imaps=imap.yourmailer.com:xxx --email-login=yourlogin --email-passwd=yourpassword --email-from=yourhost@yourmailer.com --email-to=peerhost@peermailer.com --host-id=local --peer-id=remote --stun-server=stun.someserver.com --stun-client=xxx.xxx.xxx.xxx:xx --exec-command=~/plexus/exec.sh

If everything went well, the control will be passed to specified applications you set with key --exec-command. You can pass arguments to your application with key --exec-args and use wildcards:

• %innerip% - IP address of the local interface bound by plexus, set by --stun-client or default
• %innerport% - port of the local interface bound by plexus, set by --stun-client or default
• %outerip% - IP address of the public interface issued by NAT
• %outerport% - port of the public interface issued by NAT
• %peerip% - public IP address of the peer
• %peerport% - public port of the peer
• %secret% - verification key calculated by the sides

If you don't pass the --exec-args, the application will be invoked as follows:

/path/to/exec/command innerip innerport outerip outerport peerip peerport secret

For tests, you can use exec.sh and exec.bat scripts from the repository. The scripts are aimed for creating a VPN tunnel between machines and require openvpn installed, which needs administrative privileges. Of course, you can use your own scripts. To increase security level you can force to use S/MIME protocol for IMAP/SMTP communications. Pass --help to see all available arguments.

Code

The following is a concise description of the code interfaces. The code is not complicated and structured and you'll figure it out without difficulty. The main entities are the mediator that's responsible for SMTP and IMAP communication to exchange endpoints and the puncher that communicates with STUN server, punches a UDP hole and performs handshake procedure.

typedef std::pair<endpoint, /* puzzle */ uint64_t> reference;

struct mediator
{
    virtual ~mediator() {}
    virtual reference receive_request() = 0;
    virtual reference receive_response() = 0;
    virtual void dispatch_response(const reference& host) = 0;
    virtual void dispatch_request(const reference& host) = 0;
};

The names of the mediator methods speak for themselves. The reference type contains a peer endpoint and a puzzle which is a randomly generated number. Two numbers from each side form a verification key.

enum binding
{
    address_and_port_dependent = 0,
    address_dependent = 1,
    port_dependent = 2,
    independent = 3
};

struct traverse
{
    unsigned int nat : 1,
                 hairpin : 1,
                 random_port : 1,
                 variable_address : 1,
                 mapping : 2, // enum binding
                 filtering : 2; // enum binding
};

struct nat_puncher
{
    virtual ~nat_puncher() {}
    virtual traverse explore_network() noexcept(false) = 0;
    virtual endpoint reflect_endpoint() noexcept(false) = 0;
    virtual endpoint punch_hole_to_peer(const endpoint& peer, uint8_t hops) noexcept(false) = 0;
    virtual void reach_peer(const endpoint& peer, uint64_t mask) noexcept(false) = 0;
    virtual void await_peer(const endpoint& peer, uint64_t mask) noexcept(false) = 0;
};

Puncher methods

• explore_network - investigates the NAT with the help of STUN server and returns flags describing it. The main flag is the mapping, which describes the policy of public address assignment.
• reflect_endpoint - captures an endpoint on the NAT public interface.
• punch_hole_to_peer - does the same as the previous method and punches a UDP hole towards the peer.
• reach_peer - punches a UDP hole towards the peer and initiates the handshake.
• await_peer - accepts the handshake.

There's one important thing the plexus can't do well - bind TCP applications. This is because the NAT punching doesn't work well for TCP connections. But for such cases, there is the tunneling tool wormhole which can be used with the plexus.

Thank you for your time.