ding/README.md
adrien 1d7c7fba86
All checks were successful
goreleaser / goreleaser (push) Successful in 56s
First commit
2023-07-01 16:17:20 +02:00

4.3 KiB

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, 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.

$ 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

$ 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

$ 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.

$ 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

$ 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.

$ 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.