ding/README.md

# ding

ding pronounced `[diŋ]`, in the French language is an onomatopoeia evoking the sound produced by the bells of a steeple
or the bell of a front door. ding is a tool for port knocking, hence the name. It took me 10 seconds to find it, be
nice.

For those who haven't heard, port knocking is a method of externally opening ports on a firewall by generating a
connection attempt on a set of prespecified closed ports. Once a correct sequence of connection attempts is received,
the firewall rules are dynamically modified to allow the host which sent the connection attempts to connect over
specific port(s).

ding, your brand-new secure* port knocking client in less than 400 lines of code.

*In its default configuration, ding protects the configuration file by ciphering it via XChaCha20-Poly1305, an
authenticated encryption with additional data (AEAD) algorithm, that combines the XChaCha20 stream cipher with the
Poly1305 message authentication code.

## How to use it

### Setup

The values of the `-t`, `--timeout` or `timeout` and `-d` `--delay` or `delay` flags are of
type [time.Duration](https://pkg.go.dev/time#Duration), which means that the time unit can take on the following
values: `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. Respectively: nanosecond, microsecond, millisecond, second, minute
and hour.

By default, and for obvious reasons, the configuration file is ciphered (via XChaCha20-Poly1305). You can disable this
behavior with the `-i` or `--insecure` flag.

Also, the minimum entropy of the password must be 65, you can (at your own risk) easily get around this by using
the `-b` or `--bypass-password-entropy` flag. Note that entropy is only checked during the setup phase.

```shell
$ ding setup --help
```

```
NAME:
   ding setup - Launches ding setup

USAGE:
   ding setup [command options] [arguments...]

OPTIONS:
   --address value, -a value                          address to knock
   --port value, -p value [ --port value, -p value ]  ports to knock
   --timeout value, -t value                          timeout in milliseconds (default: 1500ms)
   --delay value, -d value                            delay in milliseconds between knocks (default: 100ms)
   --insecure, -i                                     don't de/cipher configuration file (default: false)
   --bypass-password-entropy, -b                      insecurely bypass password entropy (default: false)
   --help, -h                                         show help
```

#### Interactive mode

```shell
$ ding setup
? address to knock: 192.168.10.6
? port to knock (separated by commas if several): 38457,22949,9686
? timeout in milliseconds: 1.5s
? delay in milliseconds between knocks: 100ms
? password: *****************
```

#### Non-interactive mode

```shell
$ ding setup -a 192.168.10.6 -p 38457 -p 22949 -p 9686 -t 1500ms -d 100ms
? password: *****************
```

These two approaches boil down to exactly the same thing.

If you go to `$XDG_CONFIG_HOME/ding/` or `$HOME/.config/ding/`, you'll find a file named `.salt` containing the salt
used to derive the 32-byte key used to cipher the configuration file (if you haven't used the `-i` or `--insecure`
flag), as well as the configuration file itself, ciphered or not.

```shell
$ ls -lah ~/.config/ding/
total 16K
drwxr-xr-x  2 adrien users 4.0K Jun 30 17:01 ./
drwxr-xr-x 30 adrien users 4.0K Jun 30 17:01 ../
-rw-r--r--  1 adrien users  132 Jun 30 17:11 config.toml
-rw-r--r--  1 adrien users   32 Jun 30 17:11 .salt
```

### Use

```shell
$ ding help
```

```
NAME:
   ding - Command line interface tool to knock ports

USAGE:
   ding [global options] command [command options] [arguments...]

VERSION:
   untagged-0000000000

AUTHOR:
   Adrien <contact@illuad.fr>

COMMANDS:
   setup, s  Launches ding setup
   help, h   Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --insecure, -i  don't de/cipher configuration file (default: false)
   --help, -h      show help
   --version, -v   print the version
```

It couldn't be simpler. The password is the same as the one entered during the setup phase.

```shell
$ ding
? password: *****************
```

If you add the `-i` or `--insecure` flag when you haven't specified it during the setup step, you'll get an error like
this.

```
2023-07-01T11:09:51+02:00 FTL toml: line 1: invalid UTF-8 byte: 0xc4
```

However, if you've set up ding correctly, you should be able to access your server via SSH.