This application implements UDP Hole Punching (http://en.wikipedia.org/wiki/UDP_hole_punching). The application allows cooperating clients to locate each other and to communicate directly. It consists of two parts: a server, which runs continuously on a public Internet host (currently home.contextshift.co.uk:60218); and a client that runs on computers that may (but need not) be behind behind a firewall.
|Server||the punch server.|
|Client||a punch client.|
|Supplicant||the initiator of a punch request to the server.|
|Correspondents||the parties to a client-to-client connection.|
The Punch Server process is defined mainly in punch.c.
The application provides an open, anonymous service to users wishing to locate one-another and to communicate. It serves only for client rendezvous, with all subsequent data transfers taking place between clients (peer-to-peer).
The Server forks (parent exits) to put itself into the background and then forks again; the child runs the punch service whilst the parent waits for child death on failure and re-forks to keep the service running.
Two ports are opened, one for TCP connections and one for UDP. Clients attach initially to the TCP port and maintain this connection for the duration of their session. Client traffic on its server connection, defined in Message Formats, consists of:
As all of these involve small amounts of traffic/data, the server does not fork to serve each client - the overhead seems unnecessary.
The server maintains a double-linked-list of groups, creating new groups upon request. List entries contain the group name and password and the number of members attached. The first member of a group specifies its password, if any. When the last member leaves the group, the member count reaches zero and the group is deleted from the list. Permanent groups with fixed passwords are defined manually by adding an entry (a file) in the groups directory. The server checks this directory for changes and creates any newly defined groups before creating any dynamic group. Permanent groups have their member count initialized to 1 instead of zero to prevent deleteion.
A double-linked-list of clients is maintained. Each entry, created when a client attaches to the server TCP socket, contains:
A new entry initially contains just the connection ID, socket and IP address. The remaining fields are filled-in when the client introduces itself with a mandatory ‘intro’ message.
The server can log actions to a log file or to stdout. The log file is defined on the command line.
Groups are normally created on request. Permanent groups can be created by creating a group directory that holds a file for each permanent group. The file holds the group password (and may be empty if no password is required). The group directory is defined on the command line.
The Client is defined mainly in punch-client.c.
The application supports a single client, which identifies itself to the server using a user name and a group name. User/group name-pairs must be unique. Group names are self-selected - ie. a number of users can agree on any desired group name, as long as it does not already exist. Group names are dynamic: they are created upon first use and deleted when their member count falls to zero. There is no facility for listing existing groups, so group naming and membership must be pre-agreed (between users). When a group is first created (by the first member joining) a password may be specified. Each user may optionally specify an associated email address or other extra identification information.
For details of name and password sizes and rules, see Message Formats.
Each client maintains a TCP connection to the Server. The client receives a unique identifier (ID) when the connection is first created and identifies itself to the Server (with user/group/password and email address) across this TCP connection. It receives update massages as other clients join and leave the group and can request a list of all group members; the client itself will be included in the list received.
The client presents a prompt to the user showing the user/group name in use. It allows conversations to be started with other group members to exercise the hole-punching mechanism.
The commands available at the prompts are -
Once corresponding, any non-command text typed is sent to all correspondents. If corresponding with several users, prefix text with ‘@name ‘ to send to just one
For a client to punch a hole and start a conversation with another group member, both ends must open UDP ports and both must be made aware of the corresponding address (IP address and port number) of the other end. The Server facilitates this address exchange.
For details of messages and their formats, see Message Formats.