A simple alternative to ssh (<5% total SLOCC) written from scratch in Go. A testbed for candidate PQC (post-quantum cryptography) KEMs (Key-Encapsulation Mechanisms) and symmetric session encryption algorithms.

xs also features integrated traffic chaffing to obscure interactive session and file copy activity, and is intended as a playground for other attack-resistance techniques.

Runs on Linux, FreeBSD, Windows (client only, MSYS) and Android (within Termux).

Russ Magee b32a9e6c1a Test update of README.md for push hook 3 years ago
hkexnet ea01123b87 GoReporter recommended cleanup 3 years ago
hkexpasswd 205e68dcf8 Changed vis diagrams to PNG 3 years ago
hkexsh 113721b808 Upload files to 'hkexsh' 3 years ago
hkexshd 205e68dcf8 Changed vis diagrams to PNG 3 years ago
logger 6fbbcdadb6 Gometalinter cleanup/audit of hkexsh, hkexshd, hkexpasswd 3 years ago
spinsult 94e06abbcb Updates to main Makefile (and added spinsult Makefile) 3 years ago
CODE_OF_CONDUCT.md d13e340895 Added clause 11a. to cover crypto regs 3 years ago
CODE_OF_MERIT.md 6ac866fdbf Update 'CODE_OF_MERIT.md' 3 years ago
LICENSE.mit 361fa2a7c3 Added hkexnet to LICENSE file 3 years ago
Makefile 55fdffbd9e Moved herradurakex to its own package 3 years ago
README.md b32a9e6c1a Test update of README.md for push hook 3 years ago
TODO.txt 55fdffbd9e Moved herradurakex to its own package 3 years ago
consts.go 91fa5fd2d2 Bumped version -> 0.8.0 3 years ago
cp.cmd 5859131678 Continuing groundwork for cp mode - refactor main client code into shell/copy subroutines; -r option 3 years ago
fixup-gv.sh fc05a9a4a3 Added fixup-gv.sh and Makefile rules to generate annotated goroutines in graphviz output. 3 years ago
go.mod 2fbf5737ef Updated go.mod 3 years ago
go.sum 2fbf5737ef Updated go.mod 3 years ago
grml.yaml e07c5ee996 Updated vis targets to match go-callvis updated cmdline options 3 years ago
hkexauth.go da78f37e42 Rearranged godoc pkg comments 3 years ago
hkexsession.go da78f37e42 Rearranged godoc pkg comments 3 years ago
hkexshd.initrc d28a4af924 Added example openrc init script 3 years ago
termmode_unix.go 6fbbcdadb6 Gometalinter cleanup/audit of hkexsh, hkexshd, hkexpasswd 3 years ago
termmode_windows.go 5da70447b0 MSYS+mintty support; pkg renaming to hkexsh 4 years ago
viz_hkexsh_dot.png b63252dbf6 Added go-code-visualizer PNG and 'make vis' rule to generate 3 years ago




HKExSh (HerraduraKyberEx Shell) is a golang implementation of a simple remote shell client and server, similar in role to ssh, offering encrypted interactive and non-interactive sessions, file copying and tunnels with traffic obfuscation ('chaffing').

NOTE: Due to the experimental nature of the HerraduraKEx and Kyber IND-CCA-2 algorithms, and the novelty of the overall codebase, this package SHOULD BE CONSIDERED EXTREMELY EXPERIMENTAL and USED WITH CAUTION. It DEFINITELY SHOULD NOT be used for any sensitive applications. USE AT YOUR OWN RISK. NEITHER WARRANTY NOR CLAIM OF FITNESS FOR PURPOSE IS EXPRESSED OR IMPLIED.

The client and server programs (hkexsh and hkexshd) use a mostly drop-in replacement for golang's standard golang/pkg/net facilities (net.Dial(), net.Listen(), net.Accept() and the net.Conn type), which automatically negotiate keying material for secure sockets using one of a selectable set of experimental key exchange (KEX) or key encapsulation mechanisms (KEM).

Currently supported exchanges are:

Currently supported session algorithms:



  • HMAC-SHA256
  • HMAC-SHA512

Calls to hkexnet.Dial() and hkexnet.Listen()/Accept() are generally the same as calls to the equivalents within the net package; however upon connection a key exchange automatically occurs whereby client and server independently derive the same keying material, and all following traffic is secured by a symmetric encryption algorithm.

Above the hkexnet.Conn layer, the server and client apps in this repository (hkexshd/ and hkexsh/ respectively) negotiate session settings (cipher/hmac algorithms, interactive/non-interactive, tunnels, if any, etc.) to be used for communication.

Packets are subject to random padding (size, prefix/postfix), and (optionally) the client and server channels can both send chaff packets at random defineable intervals to help thwart analysis of session activity (applicable to interactive and non-interactive command sessions, file copies and tunnels).

Tunnels, if specified, are set up during initial client->server connection. Packets from the client local port(s) are sent through the main secured connection to the server's remote port(s), and vice versa, tagged with a tunnel specifier so that they can be de-multiplexed and delivered to the proper tunnel endpoints.

Finally, within the hkexpasswd/ directory is a password-setting utility. HKExSh uses its own passwd file distinct from the system /etc/passwd to authenticate clients, using standard bcrypt+salt storage.


As of this time (Oct 2018) no verdict by acknowledged 'crypto experts' as to the level of security of the HerraduraKEx algorithm for purposes of session key exchange over an insecure channel has been rendered. It is hoped that experts in the field will analyze the algorithm and determine if it is indeed a suitable one for use in situations where Diffie-Hellman or other key exchange algorithms are currently utilized.


As of this time (Oct 2018) Kyber is one of the candidate algorithms submitted to the NIST post-quantum cryptography project. The authors recommend using it in "... so-called hybrid mode in combination with established "pre-quantum" security; for example in combination with elliptic-curve Diffie-Hellman." THIS PROJECT DOES NOT DO THIS (in case you didn't notice yet, THIS PROJECT IS EXPERIMENTAL.)


Get source code

  • $ go get -u blitter.com/go/hkexsh
  • $ cd $GOPATH/src/blitter.com/go/hkexsh
  • $ go build ./... # install all dependent go pkgs

To build

  • $ cd $GOPATH/src/blitter.com/go/hkexsh
  • $ make clean all

To install, uninstall, re-install

  • $ sudo make [install | uninstall | reinstall]

To manage service (assuming openrc init)

  • $ sudo rc-config [start | restart | stop] hkexshd

An example init script (hkexshd.initrc) is provided. Consult your Linux distribution documentation for proper service/daemon installation. Default assumes installation in /usr/local/sbin (hkexshd, hkexpasswd) and /usr/local/bin (hkexsh/hkexcp symlink).

To set accounts & passwords:

  • $ sudo touch /etc/hkexsh.passwd
  • $ sudo hkexpasswd/hkexpasswd -u joebloggs
  • $ <enter a password, enter again to confirm>

Testing Client and Server from $GOPATH dev tree (w/o 'make install')

In separate shells A and B:

  • [A]$ cd hkexshd && sudo ./hkexshd & # add -d for debugging

Interactive shell

  • [B]$ cd hkexsh && ./hkexsh joebloggs@host-or-ip # add -d for debugging

One-shot command

  • [B]$ cd hkexsh && ./hkexsh -x "ls /tmp" joebloggs@host-or-ip

WARNING WARNING WARNING: the -d debug flag will echo passwords to the log/console! Logging on Linux usually goes to /var/log/syslog and/or /var/log/debug, /var/log/daemon.log.

NOTE if running client (hkexsh) with -d, one will likely need to run 'reset' afterwards to fix up the shell tty afterwards, as stty echo may not be restored if client crashes or is interrupted.

Setting up an 'authtoken' for scripted (password-free) logins

Use the -g option of hkexsh to request a token from the remote server, which will return a hostname:token string. Place this string into $HOME/.hkexsh_id to allow logins without entering a password (obviously, $HOME/.hkexsh_id on both server and client for the user should not be world-readable.)

File Copying using hkexcp

hkexcp is a symlink to hkexsh, and the binary checks its own filename to determine whether it is being invoked in 'shell' or 'copy' mode. Refer to the '-h' output for differences in accepted options.

General remote syntax is: user@server:[/]src-or-dest-path If no leading / is specified in src-or-dest-path, it is assumed to be relative to $HOME of the remote user. File operations are all performed as the remote user, so account permissions apply as expected.

Local (client) to remote (server) copy:

  • hkexcp fileA /some/where/fileB /some/where/else/dirC joebloggs@host-or-ip:remoteDir

Remote (server) to local (client) copy:

  • hkexcp joebloggs@host-or-ip:/remoteDirOrFile /some/where/local/Dir

NOTE: Renaming while copying (eg., 'cp /foo/bar/fileA ./fileB') is NOT supported. Put another way, the destination (whether local or remote) must ALWAYS be a directory.

hkexcp uses tar (a 'tarpipe') with gzip compression, sending tar data over the hkex encrypted channel. Use the -d flag on client or server to see the generated tar commands if you're curious.


Simple tunnels (client -> server, no reverse tunnels for now) are supported.

Syntax: hkexsh -T=<tunspec>{,<tunspec>...} .. where <tunspec> is <localport:remoteport>

Example, tunnelling ssh through hkexsh (NOTE issue #15)

  • [server side] $ sudo /usr/sbin/sshd -p 7002
  • [client side, term A] $ hkexsh -T=6002:7002 user@server
  • [client side, term B] $ ssh user@localhost -p 6002