====== Architecture overview ======

paplon is the TCP server. It queues work.

oclvankus downloads work for chain computation. It uses slice.c OpenCL kernel. The kernel is generated by genkernel scripts.

delta_client downloads work for table lookup.

Most of it is Python. oclvankus OpenCL interface was very slow in Python, so several key functions were rewritten to C and wrapped with swig. This is called libvankus.

delta lookups are facilitated by functions in delta.c, again, linked with swig to delta_client.

The cracking process works like this:
  * Client submits "crack 010101…" on tcp/1578
  * The keystream is sent to oclvankus. Distinguished points are computed and burst is returned.
  * Distinguished points are sent to delta_client. Corresponding starting points are looked up in the tables. If nothing is found, zeros are returned.
  * Keystream and starting points are sent to oclvankus. The chains are regenerated from the starting points and compared to the keystream. If secret states (the chainlink immediately preceding a successful comparison) are found, they are sent to paplon and then to clients.

===== Network protocol =====

Client connects to server and sends "command param1 param2 .. paramN\r\n<binary data>" (command and parameters are separated by spaces). Parameters are command-dependent, usually one of them specifies the length of the binary part (if there is any).

The response is in similar format.

Client-exposed commands are "crack" and "stats". "crack" accepts keystream as a parameter, "stats" has no parameter and prints out some info about server load (namely how many bursts are in which stage of cracking).

Internal commands are the rq_* functions in source code. We provide python docstrings for them, keeping a copy in wiki would be prone to obsolence.

===== Keystream data format =====

Keystream is 114 bits in ASCII (string of ASCII '0's and '1's). Example: client sends:
<code>
crack 110000111101111011011100000111011000010010011010101010110010100010010101010101000110010101011010101000101001000000
</code>

===== Burst data format =====

Bursts are sent 1) with computed endpoints (to delta_client), 2) with corresponding startpoints (from delta_client).

Burst is composed of number_of_tables * number_of_keystream_samples * number_of_colors = 40 * 51 * 8 = 16320 parts called fragments.

The binary format is simply uint64_t[16320].

We don't care about endianness, but it has to be the same on all of your devices. As you are probably using amd64, it is little endian.

===== clblob data format =====

clblob is submitted by userspace library (oclvankus) to the computing kernel (slice.c), then computing is carried and the result is pushed from the kernel back to oclvankus.

Each fragment in the clblob is specified by uint64_t[4].

<code>struct frag {
  uint64_t prng;      // cipher internal state
  uint64_t rf;        // constant that is XORed in after each round
  uint64_t challenge; // cipher state we are hunting for
  uint64_t flags;
}</code>

Flags:

0x01 = End of color (i.e., 12 bits zero) reached

0x02 = Challenge found, the secret cipher state is in frag.prng.

===== "return" messages =====

Once the client submits a job (114 bits of A5/1 keystream) using the "crack" command, job number is assigned by the server. This is reported as "Cracking #<job_number> <keystream_again>".

If the secret state is found, a message is generated: "Found <secret_state_in_hexadecimal> @ <position> #<job_number> (table:<table_id>)".

Once the job is finished (all fragments have been computed), "took" message is generated: "crack #<job_number> took <number> msec".

These messages are sent to all clients that have submitted a "crack" command.

===== "stats" message =====

The client can enter "stats" command. The server prints how many bursts are queued in which stage of cracking.
<code>
submitted: N
dpsearch: N
endpoints: N
startsearch: N
startpoints: N
collsearch: N
finished: N
</code>