Log | Files | Refs

commit 1e57c07dbfbfde5c958ae604f85965550362ae62
parent 49fefb88ae08d6f319d0ad5f1ce29f487914c53e
Author: Josuah Demangeon <>
Date:   Sat, 18 Apr 2020 00:37:07 +0200

add documentation on jj + ucspi + s6

Awiki/jj/ | 152+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 152 insertions(+), 0 deletions(-)

diff --git a/wiki/jj/ b/wiki/jj/ @@ -0,0 +1,152 @@ + The jj irc client +=================== + +[[jj]] is an [Internet Relay Chat][irc] client based on the principles of +[[ii]], using FIFO (named pipe) files to read commands from the user, and +simply logs the output of each channels to plain files. + +[ii]: +[jj]: +[irc]: + + +How jj works +------------ +As opposed to ii, which is plain C, jj uses an awk script to do the heavy +lifting of IRC parsing, called from a compiled binary coded in C, that only +does the fifo creation, and multiplexing of user and network input, and +write both to the awk script. + +It reads its entire configuration from environment variables, described on +the the project's, such as $IRC_DIR, in which it create a direcTory +with the channel as a name. + +I set IRC_DIR to /var/irc, which give us (full list on the + + * /var/irc/*.log - messages from users and channels. + * /var/irc/ - the FIFO pipe to which write messages. + +There is one instance of jj per server conexion, which greatly simplifies +the software, makes debugging much easier, and permit to adapt and configure +it specifically for the requirements of each host to connect to. + +Recently, jj acquired the [[UCSPI]] connexion interface, which is a way to +write programs without handling the network protocols into the program itself, +but instead expect an running connexion (TCP, TLS, SSH, SOCKS5...) from standard +input and output (for servers) or file descripTor 6 and 7 (for clients). + +This permits to run it through [[s6-networking]], [[ucspi-y]], [[ucspi-ssl]], +[[curvecp]], or any protocol that has an UCSPI adapter for it. + +[s6-networking]: +[ucspi]: +[ucspi-y]: +[ucspi-ssl]: +[curvecp]: + + +State of IRC client<->server connexions +--------------------------------------- +Because it is run by different people and projects, the connexion to IRC +servers varies greatly through the different cases: + + * Some servers only accept TCP connexions. + * Some servers only accept TLS connexions. + * Some servers permit to use a client TLS certificate to authenticate. + * Some servers support connexion coming form [[Tor]], providing the extra + privacy that the IRC protocol lacks + * Some servers refuse connexions coming from Tor. + * Some are published as Tor hidden services directly: so no need for TLS. + * Some servers still propose TLS over Tor, with certificate authentication. + * Some servers use a self-signed certificate, and publish a fingerprint + of their certificate. + * Some servers used a private certificate *authority* and publish their + root certificate. + +From this plethora of security fine tuning, it is necessary to have an irc +client with a good TLS implementation (lots of lines of code), and a socks +proxy (more lines of code), with a configuration interface (many many lines of +code). + + +How UCSPI helps +--------------- +I use jj under the [[s6]] and [[s6-rc]] supervision tree on a VPS (until I get +real hardware home). + +jj having one instance per host to connect to, and jj supporting UCSPI, all of +these are of a great fit: + +[s6]: +[s6-rc]: +[Tor]: + +By using ucspi, we are entirely avoiding the problemm, as we can compose a +socks client to talk to the Tor daemon (one line of scripts), and once the +connexion has started, it is possible to start a tlsclient program that uses +the active connexion and start a TLS session within that Tor socket, which can +be configured as well to use a client certificate. + +All of the UCSPI tools work by performing their startup work (opening a TCP +connexion, initiating a TLS/SOCKS/... session), and starting a child program, +which was pased as argument to it, with a pipe, or executing them directly. + +This gives more or less long chain, aka [[chainloading]], that [[djb]] used +and popularized through its set of programs. + +[chainloading]: +[djb]: + + +How I use jj and s6/s6-rc and UCSPI together +-------------------------------------------- +The s6 and s6-rc package come with an execline shell-like language that makes +this style of pipling as natural + +This is how it looks like in an [[execline]] ./run script in practice, as povided by s6 for +configuration of daemon (jj) startup scripts: + +Boilerplate I have everywhere (sorry sk., #!/usr/bin/env...): + + #!/usr/bin/env execlineb + fdmove -c 2 1 + +This command reads the content of each file in ./env/ and export environment +variables to their content: env/IRC_HOST, env/IRC_USER, env/IRC_PASSWORD, ... + + s6-envdir "env" + +I use the "irc" user and the /var/irc/ direcTory: + + s6-setuidgid irc + +This starts a TCP connexion to the local Tor daemon running: + + s6-tcpclient 9050 + +This starts a SOCK5 proxy session for communicating with the [[hackint]] + + sockc "5ogdsfyoqk47ompu.onion" "6667" + +At that point, the program called by sockc will be able to communicate +directly with IRC commands, as the TCP connexion is ready, the socks +session is set, and the raw IRC protocol follows. + +It is now possible to call jjd directly, which will recognize the UCSPI +environment through the $PROTO environment variable. + + jjd + +In case there is another context, situation, other UCSPI commands can be +inserted or moved, including the setup of client certifiates, that often goes +through environment variables. + +This is the same script while run as #!/bin/sh. Yes, this is a single command! + + #!/bin/sh + fdmove -c 2 1 \ + s6-envdir "env" \ + s6-setuidgid irc \ + s6-tcpclient 9050 \ + sockc "5ogdsfyoqk47ompu.onion" "6667" \ + jjd