CIPHER.CONF(5) Clique Reference Manual CIPHER.CONF(5) NAME cipher.conf - Clique cipherer configuration file SYNOPSIS cipher.conf specifies the configuration for clique-cipherer(1). This generally can be a short file with only two lines: KeyDirectory /home/you/.clique/keys Deliverer /home/you/.clique/deliverer DESCRIPTION This file points clique-cipherer(1) to the directory and files that it needs. A secondary purpose is to tackle some odd configuration needs and test scenarios that may arise. In many instances, it is enough to specify where the KeyDirectory is and the location of your Deliverer script. A full list cipherer directives appears in the next section. If clique-cipherer(1) is run using the -c command line option, its argument will be used as the configuration filename. Otherwise, the 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. DIRECTIVES DateFuzz seconds The cipherer evades replay attacks by timestamping the packets it sends. This naturally causes trouble if the clocks do not agree between communicating peers. For this reason, a certain amount of leeway may be configured, and by default it is 604800 seconds, or one week. Permitting a one week clock disagreement may sound like an open invitation for replay attacks, but the system also keeps track of the most recent time which was successfully decrypted. It turns out that at most, a malicious peer attempting a replay attack might replay a missing packet in its original sequence, thereby aiding the communicants instead of disrupting them. The clock is also used to examine decrypted packets for valid- ity, that is, to see if a key matched at all and if the plain- text is correct. This is why a much wider interval such as 140 years is not permitted by default, and why we have a DateFuzz setting in the first place. The default setting of one week results in a checksum strength of slightly more than 87 bits, an average of one bad packet per 89 billion billion billion bytes sent based on 576 bytes per packet. Using a smaller value for seconds increases the checksum robustness accordingly. Deliverer path This line must contain the full path to your deliverer script; e.g., what you put here must start with a /. Be sure that your script is executable! Refer to the clique-deliverer(1) manpage for information about scripts. You can find pre-written working example scripts in the Clique source code; look at "example.c" and "example.py". KeyDirectory path All your key files must be in one directory: this one. This line must contain the full path to the directory; e.g., what you put here must start with a /. Keys are generated with clique- keygen(1). NakSeconds seconds This provides an optimization of the sliding window acknowledg- ment protocol that is used to assemble received packets in their correct order and to request retransmission of missing packets. Ordinary sliding window protocols transmit as many packets as can be sent until their transmit window is full before consider- ing any packets for being retransmitted as missing. This is not the best arrangement us, because it permits packets to be out of order for an extended period of time, which for Clique could be days. So while your friend is waiting to see what you typed three hours ago, your computer is busy sending stuff you much later later, not displaying any received text at all until it is all sorted out on the cipherer's own geological timeframe. NakSeconds takes advantage of the knowledge that the receiver regularly transmits the sequence number of the next frame that it wants, and that if such a number is received at least a cer- tain amount of time after a packet was sent, the number can be used to negatively acknowledge the packet reliably. The default setting is 10 seconds, which accounts for the fact that the schedulers' LagSeconds settings at both ends of the conversation are likely to be 2 seconds each, and that round-trip packet time is generally less than a second. Thus we want NakSeconds to be at least 5 seconds to preclude unnecessary retransmissions, and the default setting of 10 is safe. Q-u-i-t something This was never meant as a user command; it's used internally to tell the program that we've reached the end of the cipher.conf file. But it does work and has application when a tester wants to comment out most of the file. You must put one or more non- white symbols in something, or a syntax error will result. Socket name The scheduler and cipherer communicate via two datagram sockets. Ordinarily these are UNIX domain sockets using the abstract namespace offered by Linux, but regular filesystem sockets are also supported so that non-Linux operating systems like macOS can work. In either mechanism, the socket names in the two con- figuration files much be identical and indicate the name of the socket the cipherer will open to receive data from the sched- uler. Another socket is opened by the scheduler to communicate in the opposite direction; its name is slightly different in that a + (plus sign) is appended to it. The cipherer and sched- uler remove their listening sockets when they terminate nor- mally. The default setting when Socket is not specified is "@clique4.us", with the @ indicating that the abstract namespace is used. To use UNIX domain sockets accessible via the filesys- tem, provide a fully-qualified filesystem name that begins with /. Any directories needed to reach this name must exist and have all permissions to create and use the sockets. Relative filesys- tem names are not supported. If filesystem-based sockets are used, the sockets must not already exist. This safeguard prevents accidental startup of more than one scheduler or cipherer in a given configuration. If the scheduler or cipherer terminates abnormally, it may be nec- essary to manually remove orphaned filesystem sockets. Platforms that do not implement UNIX domain sockets exist, including at this writing the Windows Subsystem for Linux that is available for Windows 10. To work around this, the cipherer and scheduler can communicate using UDP connections through the loopback adapter. Two consecutively numbered ports are used, with the lower-numbered port specified in name. One might wonder if, given that loopback connections are sup- ported, Clique can be configured to use ordinary IPv4 so that the cipherer and scheduler can execute on different machines. There is no way to specify a non-loopback address at this time, mainly because the protocol between the scheduler and cipherer is not intended for insecure environments. Another consequence of this insecure protocol is that on multiuser machines, using filesystem-based sockets with user access restrictions rather than abstract sockets or UDP might provide the most secure con- figuration. Syslog 0 The scheduler and cipherer always start up using syslogd to out- put messages. If you would rather they don't, you have two choices: change the source code, or use this directive. But it only becomes effective after the configuration file is loaded, meaning that it won't preclude all syslog output entirely. Sim- ilarly, if you change your mind later and delete the line or use some non-zero integer for the setting, this decision to re- employ syslogd only becomes after cipher.conf is completely reloaded. If you're wondering how to make syslogd work on Linux Subsystem for Windows, we don't know either and think that platform's ven- dor is in the best position to make it work. Trace flags Not intended as a user command, this enables additional debug- ging output, optionally highlighting some of the output in red on ANSI terminals. For usage, you either need to experiment or refer to an authority such as the Clique source code. flags is a string of symbols which, when present, enable specific fea- tures. Often this would look like the 52-character alphabet in both cases. A symbol that is prefixed with an asterisk (*) turns on the red highlighting for that symbol. To disable trac- ing, you must either omit this line or provide some bogus flags to meet the file's syntax requirements. EXAMPLE A short example appears in the SYNOPSIS section above. A longer exam- ple is included with the Clique source code. SEE ALSO clique-cipherer(1), clique-deliverer(1), clique-keygen(1), clique- scheduler(1), sched.conf(5), clique(7) 2016-12-20 CIPHER.CONF(5)