Developer's FAQ

Q: How do I develop my own application using the Six/Four protocol?

You can make any application make use the Six/Four System in the background to tunnel to wherever you want to connect securely and anonymously. Simply use the 64 API in ApplicationLayer/API. You:

1) Type 'make install'

2) Include -L/usr/local/lib -l64 in your linking options.

3) Include -I/usr/local/include/64 in your compiling options.

4) #include <64API.h> in your source code using 6/4 calls.

5) Call API64_init(cert,config,minlinks,tp) in your main function. This will initialize all the Client/Server and routing threads, and read in the configuration and hosts file and trusted peer keys. - cert is a full or relative path to a file containing an x509 ssl certificate. See LinkLayer/SSLkey.sh - config is a full or relative path to a config file. For an example, see CONFIG/64.cfg and CONFIG/64hosts.lst Note: The config file always needs configuring by the user. - minlinks is the number of peers to try to keep linked to automatically. - tp is a "Node *" structure (see PeerLayer/Node.h) with at least members "addr","port","version" and "rsa" filled in. The rsa struct MUST point to the trusted peer's public key, and the IP address that you want to run the Trusted Peer from must be pasted at the end of the file, before submission for signing, i.e.: echo 1.2.3.4 >> TPKEY.1.2.3.4 By convention a trusted peer's key is stored in the file: TPKEY-<IPADDRESS-OF-TP> and read that way by the configuration. This will be the TP that you'll use. You can let the 64API chose a random trusted peer for you, by supplying NULL for this last argument.

6) When you want to open a network connection, don't call the connect() system call - call API64_connect(client_fd, host, port, data, len) instead. - client_fd is a file descriptor where incoming data will automatically be written to by a sub-thread (the API doesn't have a manual read() call). - host is the hostname. Use a FQDN, do not resolve this yourself! That way, you can be tracked by tracking what hostnames you resolve. - port is the port number, such as 80. If you connect to more exotic ports, especially login services, chances are your Trusted Peer won't let you. - data is initial data to be written to the server immediately, can be NULL. - len is the length of above data in bytes. WARNING: The initial data on connect() may not exceed 64 bytes! Subsequent data should be written using the API64_write interface. - RETURN VALUE: the API64_connect returns the SessionID of the connection that you just initiated. You MUST store this SessionID for future calls.

7) Reading is automatic, but when you want to write something to the server, use API64_write(sid, buf, len). sid is the SessionID that I just mentioned, and buf and len are pretty self-explanatory, just like in a normal write(). 8) When you want to close down a connection, you can call API64_close(sid, client_fd) to close it immediately. This will also close your client's file descriptor. IMPORTANT: Six/Four does not always give you explicit notifications when a connection dies, or is DoS'd or when the Trusted Peer can't or won't establish it. You have to see for yourself, by monitoring time-outs, and re-connecting/re-requesting if it takes too long. The client session thread has a maximum timeout which is checked by a permanently running thread, which is DL_TIMEOUT in the file PeerLayer/CLIENT/Download.h. You may want to decrease it (or not).

That's all! That (along with the config file format) is pretty much all you need to know to write and use your own Six/Four applications!

Q: Even if I don't need to know, how does the lower-level Peer Layer work?

To make connections, a Six/Four Session is called that tunnels to the final destination over a trusted peer using the StartSession call:

DOWNLOAD->StartSession(TrustedPeer, InitialData, Datalen, "host.com", 123, destfd);

Incoming data will be automatically written to destfd. StartSession returns a transfer ID number (TID). To send further data as opposed to passively receiving, simply use DOWNLOAD->SendCliData(TID, buffer, buflen);

That's all. Now, you will need to have some back-end functionality in your application to run the Six/Four protocol, the best idea is to do this with 2-3 threads. Use an ACCEPT thread that calls LINKLAYER->listen() once and then keeps calling LINKLAYER->accept(). The return value of accept() is parsed internally in the LINKLAYER object. The other thread that is crucial is a DATA INPUT thread. Here, you need to call LINKLAYER->select(), which will return some Link objects. For each object you should use method Link->read() to read data in a buffer and then pass that buffer on to CLERVER->route() - that's all of the basic functionality. Two other functions which should be called periodically - in the threads or wherever - are MaintainMinCon() from stdfunc.cpp and DOWNLOAD->Timeout(). That's all you ever need to implement in your application to make it a Six/Four application!

Q: Can I send data both ways, and can I do realtime two-way communication?

Of course! Don't be distracted by the class names "Upload" and "Download". Upload is for the serving of a connection as a Trusted Peer and Download has the functions that any normal clerver will call to establish a connection through a TP and communicate in real-time.

To connect somewhere you use StartSession() to issue a connect request to a Trusted Peer. Once GotData() is called, the data will be sent back to the file descriptor you specified in StartSession(). Could be a file, standard input, socket, pipe... You will receive data from the server automatically. To send data to the remote server, issue a SendCliData() everytime you wish to do so. It's all abstracted neatly, you just have to use the TID of the connection.

Q: What message types exist?

Actually, you won't need to bother with it, just with the API in Clerver, Download, LinkLayer (and perhaps Discovery).

Right now there are PING/PONG (to discover nodes), STARTR (to initiate a TCP connection over a Trusted Peer), STARTR_UDP (to do exactly the same for UDP), CLIR (to send further data to a connection), ACK (to send back ACKs for received DATA), DATA (data from server to us), and DONE (sent by either party when a connection should end explicitly).

Q: How does routing work?

Routing is anonymous if it goes over 3 or more clervers - that means, no clerver has information about which distant peers will route or have routed the packet he is routing. Each clerver just knows the routing ID, direct source neighbor and direct destination neighbor. The routing topology is gnutella, i.e. any clerver connects an arbitrary amount of neighbors from one to dozens, and sends outgoing packets to random neighbors. Packets expire by hops and duplicates are avoided by unique routing IDs.

Q: The routing sucks, I want superscalable multi-mega-hypercube routing!

The goal of this protocol is to make it as easy and adaptive as possible to implement and use it, while maintaining efficiency. If you think about gnutella topography, there are no rules. Many developers of gnutella have brought out applications which employ their own topography- and routing optimizations without breaking or violating the gnutella protocol standards (such as MorpheusPE or BearShare or LimeWire). Yet, they use tricks to be much more optimized than the standard no-rules gnutella protocol. You can be the first person and do that with the Six/Four protocol! It's very much possible and intended. Go for it!

Q: How does the crypto work?

Node-To-Node encryption is traditional SSL. The default port is 443 to make it look like HTTPS traffic. End-To-End (Trusted Peer) RSA-based encryption is mandatory, and means that:

1) Node users have to obtain and verify the key of each Trusted Peer by themselves (either out-of-band or through a Trusted Peer connection of an already known peer).

2) When doing a connection request to a TP, normal nodes will send their (temporary) end-to-end session key to a Trusted Peer. The initial packet to the TP will be RSA encrypted, whereas the rest of all messages to a Trusted Peer are encrypted with the negotiated session key. The preauthenticated RSA key ensures authenticity and eliminates the possibility of Man-In-The-Middle info subversion attacks.

About this document ...

This document was generated using the LaTeX2HTML translator Version 2002-2 (1.70)

The command line arguments were:
latex2html -no_subdir -split 0 -show_section_numbers /tmp/lyx_tmpdir10755x1TkOh/lyx_tmpbuf3/README.tex

The translation was initiated by mixter on 2003-02-14

root 2003-02-14