From 95f0b9d054f994ce9ba7ef1076be6ed4f964e33a Mon Sep 17 00:00:00 2001 From: Michael Czigler <37268479+mcpcpc@users.noreply.github.com> Date: Thu, 8 Oct 2020 09:12:55 -0400 Subject: seo activities (#55) * Update and rename README.md to README * Add files via upload * Delete example4.png * Update README --- .github/example4.png | Bin 439810 -> 0 bytes .github/tty.gif | Bin 0 -> 638576 bytes README | 172 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 171 -------------------------------------------------- 4 files changed, 172 insertions(+), 171 deletions(-) delete mode 100644 .github/example4.png create mode 100644 .github/tty.gif create mode 100644 README delete mode 100644 README.md diff --git a/.github/example4.png b/.github/example4.png deleted file mode 100644 index c4b8a43..0000000 Binary files a/.github/example4.png and /dev/null differ diff --git a/.github/tty.gif b/.github/tty.gif new file mode 100644 index 0000000..ed381f5 Binary files /dev/null and b/.github/tty.gif differ diff --git a/README b/README new file mode 100644 index 0000000..b1c9265 --- /dev/null +++ b/README @@ -0,0 +1,172 @@ + + + +

+ kirc +

+ +

KISS for IRC, a tiny IRC client written in POSIX C99.

+ +

+ + + Packaging status + Codacy status +

+ +

+ +

+ +## Features + +* Excellent cross-platform compatibility (due to POSIX standard compliance). +* No dependencies other than a C99 compiler. +* Native SASL PLAIN and EXTERNAL authentication support. +* TLS/SSL protocol capable (via external TLS utilities). +* Full chat history logging. +* Multi-channel joining at server connection. +* Simple command aliases and full support for all RFC 2812 commands. +* Color scheme definition via ANSI 8-bit colors, allowing for uniform color definition across all shell applications. + +## Installation & Usage + +Building and installing on **KISS Linux** using the Community repository: + +```shell +kiss b kirc +kiss i kirc +``` + +Building and installing on **Arch** and **Arch-based** distros using the AUR: + +```shell +git clone https://aur.archlinux.org/kirc-git.git +cd kirc +makepkg -si +``` + +Building and installing from source (works on **Raspbian**, **Debian**, **Ubuntu** and many other Unix distributions): + +```shell +git clone https://github.com/mcpcpc/kirc.git +cd kirc +make +make install +``` + +### Usage + +Consult `man kirc` for a full list and explanation of available `kirc` arguments. + +```shell +kirc [-s hostname] [-p port] [-c channels] [-n nickname] [-r realname] [-u username] [-k password] [-a token] [-x command] [-w nick_width] [-o logfile] [-e|v|V] +``` + +### Command Aliases + +```shell + Send a PRIVMSG to the current channel. +@ Send a message to a specified channel or nick +/ Send command to IRC server (see RFC 2812 for full list). +/# Assign new default message channel. +/? Print current message channel. +``` + +### User Input Key Bindings + +* **CTRL+B** or **LEFT ARROW** moves the cursor one character to the left. +* **CTRL+F** or **RIGHT ARROW** moves the cursor one character to the right. +* **CTRL+A** moves the cursor to the end of the line. +* **CTRL+E** or **HOME** moves the cursor to the start of the line. +* **CTRL+W** deletes the previous word. +* **CTRL+U** deletes the entire line. +* **CTRL+K** deletes the from current character to end of line. + +## Transport Layer Security (TLS) Support + +There is no native TLS/SSL support. Instead, users can achieve this functionality by using third-party utilities (e.g. stunnel, [socat](https://linux.die.net/man/1/socat), ghosttunnel, etc). + +* Example using `socat`. Remember to replace items enclosed with `<>`. + + ```shell + socat tcp-listen:6667,reuseaddr,fork,bind=127.0.0.1 ssl::6697 + kirc -s 127.0.0.1 -c 'channel' -n 'name' -r 'realname' + ``` + +## SASL PLAIN Authentication + +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"))' +``` + +For example, lets assume an authentication identity of `jilles` and password `sesame`: + +```shell +$ python -c 'import base64; print(base64.encodebytes(b"jilles\x00jilles\x00sesame"))' +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). + +* Example using `socat`. Remember to replace items enclosed with `<>`. + + ```shell + socat TCP4-LISTEN:1110,fork,bind=0,reuseaddr SOCKS4A:127.0.0.1::,socksport=9050 + socat TCP4-LISTEN:1111,fork,bind=0,reuseaddr 'OPENSSL:127.0.0.1:1110,verify=0,cert=' + kirc -e -s 127.0.0.1 -p 1111 -n -x 'wait 5000' + ``` + +## Color Scheme Definition + +Applying a new color scheme is easy! One of the quickest ways is to use an application, such as [kfc](https://github.com/mcpcpc/kfc), to apply pre-made color palettes. Alternatively, you can manually apply escape sequences to change the default terminal colors. + +* Example using `kfc` + + ```shell + kfc -s gruvbox + ``` + +* Example using ANSI escape sequences + + ```shell + printf -e "\033]4;;#" + + # Replace with the desired Hex code (e.g. #FFFFFF is white). + # Replace with the one of the numbers below: + # 0 - Regular Black + # 1 - Regular Red + # 2 - Regular Green + # 3 - Regular Yellow + # 4 - Regular Blue + # 5 - Regular Magenta + # 6 - Regular Cyan + # 7 - Regular White + # 8 - Bright Black + # 9 - Bright Red + # 10 - Bright Green + # 11 - Bright Yellow + # 12 - Bright Blue + # 13 - Bright Magenta + # 14 - Bright Cyan + # 15 - Bright White + ``` + +## FAQ + +* **KISS** is an acronym for [Keep It Simple Stupid](https://en.wikipedia.org/wiki/KISS_principle), which is a design principle noted by the U.S. Navy in 1960s. The KISS principle states that most systems work best if they are kept simple rather than made complicated; therefore, simplicity should be a key goal in design, and unnecessary complexity should be avoided. +* **POSIX** is an acronym for [Portable Operating System Interface](https://opensource.com/article/19/7/what-posix-richard-stallman-explains), which is a family of standards specified by the IEEE Computer Society for maintaining compatibility between operating systems. The *C99* Standard is preferred over other versions (e.g. *C89* or *C11*) since this currently the only one specified by [POSIX](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/c99.html). + +## Contact + +For any further questions or concerns, feel free to reach out to me, [mcpcpc](https://github.com/mcpcpc), on `#kirc` +or `#kisslinux` channels of the *irc.freenode.org* server. diff --git a/README.md b/README.md deleted file mode 100644 index a4f6fb1..0000000 --- a/README.md +++ /dev/null @@ -1,171 +0,0 @@ - - -

- kirc -

- -

KISS for IRC, a tiny IRC client written in POSIX C99.

- -

- - - Packaging status - Codacy status -

- -

- -

- -## Features - -* Excellent cross-platform compatibility (due to POSIX standard compliance). -* No dependencies other than a C99 compiler. -* Native SASL PLAIN and EXTERNAL authentication support. -* TLS/SSL protocol capable (via external TLS utilities). -* Full chat history logging. -* Multi-channel joining at server connection. -* Simple command aliases and full support for all RFC 2812 commands. -* Color scheme definition via ANSI 8-bit colors, allowing for uniform color definition across all shell applications. - -## Installation & Usage - -Building and installing on **KISS Linux** using the Community repository: - -```shell -kiss b kirc -kiss i kirc -``` - -Building and installing on **Arch** and **Arch-based** distros using the AUR: - -```shell -git clone https://aur.archlinux.org/kirc-git.git -cd kirc -makepkg -si -``` - -Building and installing from source (works on **Raspbian**, **Debian**, **Ubuntu** and many other Unix distributions): - -```shell -git clone https://github.com/mcpcpc/kirc.git -cd kirc -make -make install -``` - -### Usage - -Consult `man kirc` for a full list and explanation of available `kirc` arguments. - -```shell -kirc [-s hostname] [-p port] [-c channels] [-n nickname] [-r realname] [-u username] [-k password] [-a token] [-x command] [-w nick_width] [-o logfile] [-e|v|V] -``` - -### Command Aliases - -```shell - Send a PRIVMSG to the current channel. -@ Send a message to a specified channel or nick -/ Send command to IRC server (see RFC 2812 for full list). -/# Assign new default message channel. -/? Print current message channel. -``` - -### User Input Key Bindings - -* **CTRL+B** or **LEFT ARROW** moves the cursor one character to the left. -* **CTRL+F** or **RIGHT ARROW** moves the cursor one character to the right. -* **CTRL+A** moves the cursor to the end of the line. -* **CTRL+E** or **HOME** moves the cursor to the start of the line. -* **CTRL+W** deletes the previous word. -* **CTRL+U** deletes the entire line. -* **CTRL+K** deletes the from current character to end of line. - -## Transport Layer Security (TLS) Support - -There is no native TLS/SSL support. Instead, users can achieve this functionality by using third-party utilities (e.g. stunnel, [socat](https://linux.die.net/man/1/socat), ghosttunnel, etc). - -* Example using `socat`. Remember to replace items enclosed with `<>`. - - ```shell - socat tcp-listen:6667,reuseaddr,fork,bind=127.0.0.1 ssl::6697 - kirc -s 127.0.0.1 -c 'channel' -n 'name' -r 'realname' - ``` - -## SASL PLAIN Authentication - -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"))' -``` - -For example, lets assume an authentication identity of `jilles` and password `sesame`: - -```shell -$ python -c 'import base64; print(base64.encodebytes(b"jilles\x00jilles\x00sesame"))' -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). - -* Example using `socat`. Remember to replace items enclosed with `<>`. - - ```shell - socat TCP4-LISTEN:1110,fork,bind=0,reuseaddr SOCKS4A:127.0.0.1::,socksport=9050 - socat TCP4-LISTEN:1111,fork,bind=0,reuseaddr 'OPENSSL:127.0.0.1:1110,verify=0,cert=' - kirc -e -s 127.0.0.1 -p 1111 -n -x 'wait 5000' - ``` - -## Color Scheme Definition - -Applying a new color scheme is easy! One of the quickest ways is to use an application, such as [kfc](https://github.com/mcpcpc/kfc), to apply pre-made color palettes. Alternatively, you can manually apply escape sequences to change the default terminal colors. - -* Example using `kfc` - - ```shell - kfc -s gruvbox - ``` - -* Example using ANSI escape sequences - - ```shell - printf -e "\033]4;;#" - - # Replace with the desired Hex code (e.g. #FFFFFF is white). - # Replace with the one of the numbers below: - # 0 - Regular Black - # 1 - Regular Red - # 2 - Regular Green - # 3 - Regular Yellow - # 4 - Regular Blue - # 5 - Regular Magenta - # 6 - Regular Cyan - # 7 - Regular White - # 8 - Bright Black - # 9 - Bright Red - # 10 - Bright Green - # 11 - Bright Yellow - # 12 - Bright Blue - # 13 - Bright Magenta - # 14 - Bright Cyan - # 15 - Bright White - ``` - -## FAQ - -* **KISS** is an acronym for [Keep It Simple Stupid](https://en.wikipedia.org/wiki/KISS_principle), which is a design principle noted by the U.S. Navy in 1960s. The KISS principle states that most systems work best if they are kept simple rather than made complicated; therefore, simplicity should be a key goal in design, and unnecessary complexity should be avoided. -* **POSIX** is an acronym for [Portable Operating System Interface](https://opensource.com/article/19/7/what-posix-richard-stallman-explains), which is a family of standards specified by the IEEE Computer Society for maintaining compatibility between operating systems. The *C99* Standard is preferred over other versions (e.g. *C89* or *C11*) since this currently the only one specified by [POSIX](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/c99.html). - -## Contact - -For any further questions or concerns, feel free to reach out to me, [mcpcpc](https://github.com/mcpcpc), on `#kirc` -or `#kisslinux` channels of the *irc.freenode.org* server. -- cgit v1.2.3