-
Notifications
You must be signed in to change notification settings - Fork 7
Home
This wiki is intended to document cables communication sources. For general documentation, head over to the project site. Installation instructions are detailed on a separate page.
The self-stabilizing communication protocol for a stateless web service-like implementation is specified in doc/cable.txt, and is quite simple: peers push short messages via the requests service on the remote end, and pull files that the other end prepares for them (everything happens via HTTP GETs). The protocol is self-stabilizing in the sense that all actions are eventually retried, and an injected/modified message or file will not confuse the peer.
The key source files that realize the communication protocol are:
- src/server.c, src/service.c — safe, fast web server and requests service
- src/daemon.c — daemon that watches for cable-related events and retries actions
-
cable/loop — launches messages validator and specific loops
- cable/validate — handles timing out of messages which failed to be sent
- cable/fetch — fetches ready messages and certificates
- cable/crypto, cable/cms — encrypt, sign, decrypt, and verify messages using CMS
- cable/comm — sends short request to the service at the other end, and delivers verified and decrypted messages
- cable/send, src/mhdrop.c — a pseudo-MTA for an email client
- bin/gen-cable-username — generates communication certificates
If you want to understand what's going on, I suggest to start with the generation of public encryption/verification certificates and private decryption/signing keys. gen-cable-username generates two public certificates: ca and verify (based on the private keys root and sign). The first certificate is the “root CA”, and the persistent username is generated from its fingerprint. The other certificate, verify, is issued by ca. A static Diffie-Hellman peer key is then generated, and its public part is saved as peer.sig after being signed using verify (the corresponding private key is derive.pem). In the current implementation, root and sign private keys are the same key (due to the resources required to generate a long RSA key), but they don't have to be — that's why two certificates are used instead of just one.
After the certificates, continue to cable/loop, which realizes a complete loop sequence for each of the possible states for a peer. doc/cable.txt is your friend here — there is a very close correspondence between the protocol specification and the individual source files.
src/daemon.c is probably the hardest to understand, since its purpose is to efficiently launch cable/loop whenever a new message is registered by src/service.c. It employs inotify to listen for filesystem events, retries after randomized time periods (to prevent fingerprinting) when no events are detected (since inotify is not too reliable with fuse filesystems), goes into standby while the filesystem is unmounted, waits when too many child processes have been launched, etc.
src/service.c does the simple tasks specified for the service loop, but is extremely carefully written, since it is the most sensitive point of the framework (handling requests).