CLIQUE-DELIVERER(1) Clique Reference Manual CLIQUE-DELIVERER(1) NAME clique-deliverer - Clique plaintext handling script SYNOPSIS Clique does not come with a user interface, as it would be very system- dependent. Instead, a user-supplied (and often user-written) script is invoked whenever a message is received or about to be transmitted. The concept is akin to CGI scripts for web pages, but the interface is sim- pler and generally more secure. DESCRIPTION The deliverer script is invoked by clique-cipherer for two purposes: 1. delivery of the decrypted content of a received packet 2. polling for content that can be encrypted and sent For the first purpose, the script can be as simple as copying the script's standard input to a console or file somewhere. For the second purpose, the script can be as simple as writing a short message to standard output. But in both cases, certain environment variables are available to the script that are extremely useful. ENVIRONMENT The environment that deliverer scripts run in is clean; it includes only variables which are purposely set by clique-cipherer(1). Many scripts will need no more than the DO, LEN, and DOMAIN variables; the others variables might be helpful to satisfy a user's curiosity or sup- port advanced features. Here are the variables offered today: ADDR The IP address of the remote peer that the packet came from or is going to, formatted as a dotted quad. DO "RX" if plaintext is being delivered, and "TX" if the script is being polled for something to encrypt and transmit. DOMAIN The name of the file containing the key used for encryption or decryption, without any directory information (slashes). In many applications, this identifies the party you are communicat- ing with. LEN The number of octets in the received message, which is exactly the number of bytes that can be read from standard input. The maximum number of octets that can be queued for encrypting and sending. If the deliverer writes more than LEN bytes to its standard output, the cipherer will discard the entire plaintext. This behavior is to avoid confusion as to where in the plaintext stream one has arrived when a message spans multiple packets. PORT The UDP port number that incoming packet arrived on, or the UDP port number to which an outgoing packet will be sent. Note there is no provision to determine what UDP port number origi- nated a packet that was sent to this host, although it is guar- anteed not to be the one specified by PORT. RXDEPTH Ordinarily zero, this is the number of packets which have arrived for this domain but have not been queued to the deliv- erer script yet. This situation can occur when packets have been dropped or received out of order. TXDEPTH Ordinarily zero, this is the number of packets which have been encrypted and sent to the remote peer, but have not been acknowledged yet as being received. This situation can occur in scenarios where a packet needs to be retransmitted, or (more often) we are simply waiting until the scheduled time when the remote peer can send an acknowledgment without leaking metadata. EXIT STATUS The deliverer script should return a zero status when it exits. Addi- tionally, if it is being polled for plaintext to send and has none, it should not write anything to its standard output. If the eight lowest- order bits of the deliverer's return status are not zero, they will be logged by the cipherer for diagnostic use. This means that you can use small numbers (1 through 255) to indicate and troubleshoot specific problems in your delivery script. NOTES The deliverer script needs to be fast. By default, clique-scheduler wakes up two seconds before it's time to transmit any given packet. In that two seconds, it must poll the cipherer to see if it wants to send anything, the cipherer must in term poll your deliverer script, that script must reply, then the cipherer must encrypt it and return its final answer to the scheduler. To preclude the need for complex implementations, the cipherer will only invoke one deliverer script at a time. But this is another reason that your script must be fast; there may be moments when there is a backlog to work through quickly. Be sure to set your deliverer script permissions so that the cipherer can find and execute it. Also make sure that any plaintext files your script handles are accessible with appropriate permissions to the deliverer, and inaccessible to your foes. If you make changes to your deliverer script but do not change its location in the filesystem, your changes are live immediately. You do not need to send the cipherer any signals, do any restarts, or alter cipher.conf(5). BUGS Your deliverer script is responsible for its own race conditions, such as any need to coordinate access to files containing incoming or outgo- ing plaintext with other programs or users. Your deliverer script is responsible for its own side channel vulnera- bilities, such as unerased plaintext left on a disk surface. The cipherer will only give your script one DOMAIN option when it is time to send to a particular address. There is no provision for your script to say, "I don't have anything to send to that domain, but I would like to send something to the same address by means of another domain". Whatever might have gone to a different domain will have to wait for another scheduled transmission. In an effort to be fair, if an address can be serviced by more than one domain, the cipherer will select a domain on the fly at random. The best workaround is not to configure any pair of Clique endpoints with more than one key. The documentation is likely to be incomplete in some respects, and dif- ficult to absorb in several respects. EXAMPLES Clique is shipped with two working deliverer script examples; refer to example.c and example.py with the source code. SEE ALSO clique-cipherer(1), clique-keygen(1), clique-scheduler(1), cipher.conf(5), sched.conf(5), clique(7) 2016-12-20 CLIQUE-DELIVERER(1)