Merge pull request #44 from mcpcpc/tor

add SASL EXTERNAL example

Author: mcpcpc

README.md

@@ -88,18 +88,18 @@ usage: kirc [-s hostname] [-p port] [-c channel] [-n nick] [-r real name] [-u us
 
 ## Transport Layer Security (TLS) Support
 
-There is no native TLS/SSL support. Instead, users can achieve this functionality by using third-party tools (e.g. stunnel, socat, ghosttunnel).
+There is no native TLS/SSL support. Instead, users can achieve this functionality by using third-party utilities (e.g. stunnel, socat, ghosttunnel, etc).
 
-*   _socat_ example:
+*   [socat](https://linux.die.net/man/1/socat) example (remember to replace items enclosed with `<>`):
 
 ```shell
 socat tcp-listen:6667,reuseaddr,fork,bind=127.0.0.1 ssl:<irc-server>:6697
 kirc -s 127.0.0.1 -c 'channel' -n 'name' -r 'realname'
 ```
 
-## PLAIN SASL Authentication
+## SASL PLAIN Authentication
 
-In order to connect using PLAIN SASL authentication, the user must provide the required token during the initial connection. If the authentication token is base64 encoded and, therefore, can be generated a number of ways. For example, using Python, one could use the following:
+In order to connect using `SASL PLAIN` mechanism authentication, the user must provide the required token during the initial connection. If the authentication token is base64 encoded and, therefore, can be generated a number of ways. For example, using Python, one could use the following:
 
 ```shell
 python -c 'import base64; print(base64.encodebytes(b"nick\x00nick\x00password"))'
@@ -113,6 +113,18 @@ b 'amlsbGVzAGppbGxlcwBzZXNhbWU=\n'
 $ kirc -n jilles -a amlsbGVzAGppbGxlcwBzZXNhbWU=
 ```
 
+## SASL EXTERNAL Authentication
+
+Similar to `SASL PLAIN`, the `SASL EXTERNAL` mechanism allows us to authenticate using credentials by external means. An example where this might be required is when trying to connect to an IRC host through [Tor](https://www.torproject.org/). To do so, we can using third-party utilities (e.g. stunnel, socat, ghosttunnel, etc).
+
+*   [socat](https://linux.die.net/man/1/socat) example (remember to replace items enclosed with `<>`):
+
+```shell
+socat TCP4-LISTEN:1110,fork,bind=0,reuseaddr SOCKS4A:127.0.0.1:<onion_address.onion>:<onion_port>,socksport=9050
+socat TCP4-LISTEN:1111,fork,bind=0,reuseaddr 'OPENSSL:127.0.0.1:1110,verify=0,cert=<path_to_pem>'
+kirc -e -s 127.0.0.1 -p 1111 -n <nick> -x 'wait 5000'
+```
+
 ## Contact
 
 For any further questions or concerns, feel free to reach out to me on `#kirc`