CLIQUE-CIPHERER(1) Clique Reference Manual CLIQUE-CIPHERER(1) NAME clique-cipherer - Clique cryptographic daemon SYNOPSIS clique-cipherer [OPTION]... DESCRIPTION The clique-cipherer program is part of the reference implementation for the Clique(7) protocol for encrypted Internet communication with many types of metadata protected against eavesdropping. This program encrypts and decrypts Internet packets received by and originating from a Clique peer. A majority of received packets are intentionally generated random noise and cannot be decrypted; however, where endpoints share a common secret generated by clique-keygen, com- munication becomes possible within this noise. The hope is that even attackers with the four "super powers" of passive eavesdropping (unlim- ited network access, unlimited computing power, unlimited funding, and unlimited legal authority) will not be able to distinguish between actual communication and decoy packets. OPTIONS None of these command-line options are for normal use. clique-cipherer is a daemon and is configured via cipher.conf. -a FILE Writes output for diagnosing memory leaks to FILE. A script for auditing memory use and pinpointing leaks is distributed with the source code in alloc-audit.py, but you will not need it. -c FILE Use configuration file FILE instead of the default cipher.conf(5). -f Stay in the foreground instead of detaching and running as a daemon. This is useful for testing, in part because you can terminate the program using Control-C. -h Prints version number and option summary. -r TEXT Substitutes TEXT for any occurrence of ~CUSTOM~ in cipher.conf. This is useful when testing many instances of the program simul- taneously on a single computer, because they can share a single configuration file. -t Ignore the SIGTERM signal. This is useful when testing for pro- tecting designated cipherer instances from killall(1). Cipher- ers which ignore SIGTERM will still honor SIGINT. EXIT STATUS Not easily usable; this is a daemon. ENVIRONMENT The environment is completely ignored by the cipherer for security rea- sons. Except for macOS, which lacks a library function to accomplish this. SIGNALS SIGINT Clean up and exit in an orderly manner. SIGTERM Clean up and exit in an orderly manner; however, this signal is ignored if the -t command line option is used. SIGHUP, SIGUSR1, SIGUSR2, SIGPIPE These signals are ignored. FILES If the -c command line option is present, its argument will be used as the configuration filename. Otherwise, clique-cipherer looks for a file at ~/.clique/cipher.conf, where ~ is the user's home directory as given in /etc/passwd. If that file does not exist, /etc/clique/cipher.conf is tried next. If none of these files are present, the cipherer exits. NOTES Ordinarily only one clique-cipherer instance runs per machine. When- ever it touches an incoming or outgoing packet to an address with a known key affiliation, the cipherer consults with a user-provided deliverer script either to output the data received, or poll the script for something to encrypt and send. In the event that different keys need routed to different programs or users, that responsibility falls on the deliverer, not the cipherer. The cipherer is also responsible for detection and correction of incor- rect and/or out-of-sequence packets. It operates in a manner similar to TCP using a sliding window acknowledgment protocol, but with some improvements and changes. Clique's checksum is 71 bits stronger than TCP's by default, and there are no reset packets to spoof or worry about. Clique also features negative acknowledgments in most situa- tions, meaning that the sliding window transmitter won't gallop off into the sunset with the horse still hitched to the post. On the other hand, Clique's limited throughput to any particular peer does not mix well with TCP's ability to offer multiple connections between the same endpoints, so Clique doesn't offer them. As the Clique network protocol is the focus of active graduate research, it should be regarded as experimental at this time. EXAMPLES clique-cipherer is ordinarily run with no command line arguments. BUGS All security mechanisms are accompanied by implicit convenience trade- offs, as well as security sacrifices made on other fronts. A signifi- cant limitation of clique-cipherer is that most traffic packets received have to have their entire length decrypted by every key in the user's possession. The reason for this is that most users ordinarily cannot know the IP address of the peer they wish to communicate with, unless they request this information via an open channel that an eaves- dropper can exploit. Even if IP addresses are exchanged with the key in person, they usually are subject to reassignment at difficult times. The cipherer compensates for this problem by making mere advertisement of a key's possession an encrypted operation. The cipherer's CPU use is roughly proportional to the product of the bitrate and the number of keys in the user's possession. This can lead to a busy machine, heat dissipation, and electricity consumption. For better or worse the cipherer is single-threaded, so a multicore proces- sor will either have processing cores that are wasted or that are available for other purposes, depending on the owner's viewpoint. The cipherer does not persist any information between runs. This means in particular that queued plaintext to transmit or deliver will be lost. It also means that the acknowledgment protocol between endpoints will ordinarily lose synchronization when the cipherer at either side restarts, resulting in missing or duplicated information received. This loss of synchronization is not always detected, and when it is, notification is not sent to the remote peer. The good news is that this synchronization loss does not cause deadlock. The endpoints even- tually do recover and continue transmitting data normally afterward. The other good news is that if you need to shutdown or restart clique- scheduler(1), you may do so without disturbing the cipherer. Informa- tion exchange will continue without data compromise once the scheduler returns online. It is not possible to share a key among more than two machines without incurring severe errors, to include deadlock and data corruption. These errors are limited to the over-shared key(s). Rather than having three peers share a single key, a total of three keys is used, one for each of the three transmission paths involved. It is not a good idea to have more than one key installed between any given pair of endpoints. If the cipherer has a choice of more than one key when sending a packet to a given address, it must commit to one before querying the deliverer for plaintext. It's possible that although the deliverer does not have plaintext for the committed key, it might have had plaintext ready for one of the other keys. But faced with a tight deadline of usually less than two seconds, the cipherer will proceed as if no plaintext is available, resulting in a wasted transmission window. Another problem that occurs if a pair of endpoints has more than one key is that not all keys may be discovered between the endpoints. This can happen if a particular key always has plaintext available, in which case that plaintext will starve the link of opportunities to send encrypted key discovery packets instead of ciphertext packets. If two peers can reach each other via more than one clique, deadlock is possible if the cliques do not all use the same packet size. This is discussed in sched.conf(5). Lockout can also occur if the system clock at either endpoint jumps back in time. Simple time zone or daylight savings adjustments are not a problem, but if the number of seconds since the Epoch diminishes, connectivity can be temporarily or permanently lost. This actually is not a bug, but an active failure of Clique's security protocol for thwarting replay attacks. It is a good idea if all endpoints save an "offline" copy of all keys in a secured location, in case a system clock jump locks out a key. This is a temporary measure; ideally clique-keygen(1) should provide a means of resetting a key after a clock jump. It doesn't. Of course, in future versions of Clique, you should never make a backup of any one-time pads. Make backup one-time pads instead. Endpoints cannot communicate if their system clocks are not within a specified tolerance of one another. By default this tolerance is seven days, and it can be adjusted. There is a small tradeoff between the clock tolerance and error detection sensitivity; with the tolerance at seven days the probability of a transmission error going undetected are less than 2**-87. You can diminish these odds further by tightening the clock tolerance. It is self-evident that 4096-bit Rijndael is not secure against eaves- droppers with truly unlimited computing power. This will be remedied in a future release of Clique, which will offer one-time pads as a hedge against such attackers. It would be helpful if the cipherer offered functionality similar to clique-scheduler(1)'s treatment of SIGHUP, SIGUSR1, and SIGUSR2. The documentation is likely to be incomplete in some respects, and dif- ficult to absorb in several respects. SEE ALSO clique-deliverer(1), clique-keygen(1), clique-scheduler(1), cipher.conf(5), sched.conf(5), clique(7) 2016-12-20 CLIQUE-CIPHERER(1)