hyp | Hide Your Ports
Go to file
Steven Polley a52f3f0d43 fix incorrect logic in rotateSequence
This was introduced in the previous few commits when adding support for multiple secrets in knockd.  The logic to push and pop entries from the knockSequences slice needed to be adjusted to cound for the number of secrets that are loaded by hypd.
2024-04-20 13:27:00 -06:00
docs add diagram 2024-04-19 18:46:43 -06:00
hyp fix client broke from last commit 2024-04-19 22:08:16 -06:00
hypd fix incorrect logic in rotateSequence 2024-04-20 13:27:00 -06:00
otphyp add support for multiple secrets (independent agents) on the knock daemon 2024-04-19 22:04:00 -06:00
.drone.yml give meaningful names to build artifacts 2024-04-14 19:18:35 -06:00
.gitignore fix incorrect logic in rotateSequence 2024-04-20 13:27:00 -06:00
Dockerfile add step to create symlinks - required for compiling eBPF program 2024-04-14 09:59:23 -06:00
go.mod enter eBPF, libpcap and CGO = bloat 2024-04-13 21:22:22 -06:00
go.sum enter eBPF, libpcap and CGO = bloat 2024-04-13 21:22:22 -06:00
LICENSE Change license from GPLv3 to BSD3 2024-04-10 06:10:38 -06:00
README.md mislinked 2024-04-19 20:34:07 -06:00

hyp | Hide Your Ports

Build Status

hyp is a port knocking implementation written in Go, using spread-spectrum UDP as an authentication mechanism. It enables trusted agents to access services over the internet, wherever they are, and without the service being accessible by others. Your TCP and UDP ports are closed. They will not show in a port scan. Nobody else can connect to them. This is particularly useful as there have been a few VPN gateway vulnerabilities over the years. I often wonder what's out there and hasn't been discovered.

Compared to most port knocking daemons, hyp provides additional protection against replay and sweep attacks. Each authentic knock sequence is a one time use, and new knock sequences are generate every 30 seconds. hyp makes use of pre-shared keys and time to calculate an authentic knock sequence on both the client and server. The following process describes how hyp works:

  1. The pre-shared key is generated and distributed between both the hyp client and the hyp server.
  2. The pre-shared key is run through a sha1-hmac algorithm along with the current system time, this produces the same 160 bits of output on both sides.
  3. The 160 bits is reduced down to 64 bits. This helps protect the key by not revealing the entire output of the hmac... we will be transmitting over an untrusted network after all.
  4. The 64 bits are divided into four 16-bit structures which are typecast to 16-bit unsigned integers. A 16-bit integer can have a value from 0-65535, the same as UDP port numbers. We have four of them now.
  5. Transmit one empty datagram to the knock daemon at a time, one after another using the four integers from the previous calculation as the destination port numbers.
  6. The knock daemon on the firewall verifies the sequence and performs the action of opening the firewall port configured for the client to let them in while remaining closed to everyone else.
  7. The client connects to their application which has its own authentication, authorization, and auditing.

Authentic Knock Sequence

Runtime Requirements

Port knocking clients have minimal requirements and can run on x86, ARM, MIPS, PowerPC, IBM390, or RISC-V. Currently only supported OS's are Linux and Windows, with support for Android planned to be added in the future.

The port knocking daemon has more strict requirements and is only available for Linux. It requires the kernel be built with CONFIG_DEBUG_INFO_BTF, which most major distributions have out of the box.

Build Requirements

Pre-built binaries for configurations I've tested are available on the releases page. This will likely run in many CPU architectures I haven't tested yet though.

To build this yourself, you will need Linux with packages for: git, clang, linux-headers- libbpf-dev and golang. Check out the Dockerfile as a reference for how the build environment for official releases is configured. Once the environment is ready, you can clone the repo and build.

# Clone repository
git clone https://deadbeef.codes/steven/hyp.git

# Build eBPF program
cd hyp/hypd/server
go generate

# Build knock daemon
cd ..
go build -o hypd .
chmod +x hypd

# Run knock daemon and show help
./hypd -h

References

  • RFC 4226 - HOTP: An HMAC-Based One-Time Password Algorithm
  • RFC 6238 - TOTP: Time-Based One-Time Password Algorithm
  • Techniques for Lightweight Concealment and Authentication in IP Networks