A secure remote client/server terminal, written in Golang. Intended as a test-bed for experimental key exchanges and symmetric session crypto.

Integrated chaffing to obscure interactive session and file copy activity, and a playground for other experimental attack-resistance techniques.

Runs on Linux (client/server), Windows (client under MSYS), Android (client/server under Termux). Likely also the *BSDs (client/server) though I haven't personally tested.

Russtopia 49814ff8e0 Update 'CODE_OF_CONDUCT.md' 13 hours ago
bacillus 9fa8f38614 Added unit tests for auth.go 1 month ago
cptest fc79001725 Moved/updated cptest.sha1sum 1 year ago
logger fd95e526e5 Fix for issue #23: null panic if logger obj is null due no active syslog sink 1 month ago
spinsult 94e06abbcb Updates to main Makefile (and added spinsult Makefile) 1 year ago
vendor f3e8383dce Initial aead/chacha20 support (ChaCha20_12) 1 month ago
xs 7d8f34a925 Bumped version, xc reports -v correctly 1 month ago
xsd ea97eb8ccd Merge tag 'v0.8.19' into xc-bigfile-EOF 1 month ago
xsnet ea97eb8ccd Merge tag 'v0.8.19' into xc-bigfile-EOF 1 month ago
xspasswd 18cde5a88c Version tags now reflect mod/vendor build setup. 1 month ago
.golangci.yml 1df11fd67b Added golangci-lint config 1 month ago
CODE_OF_CONDUCT.md 49814ff8e0 Update 'CODE_OF_CONDUCT.md' 13 hours ago
LICENSE.mit f0254c664f The Great Renaming: hkexsh -> xs (Xperimental Shell) 5 months ago
Makefile 7d8f34a925 Bumped version, xc reports -v correctly 1 month ago
README.md 689aa7d532 Update 'README.md' with xc progress info 1 month ago
TODO.txt f6a85ca071 Add (as default) option to use system shadow passwds 3 months ago
auth.go c7228d3267 auth.go: added new unit tests 1 month ago
auth_test.go c7228d3267 auth.go: added new unit tests 1 month ago
consts.go f0254c664f The Great Renaming: hkexsh -> xs (Xperimental Shell) 5 months ago
cp.cmd 5859131678 Continuing groundwork for cp mode - refactor main client code into shell/copy subroutines; -r option 1 year ago
cptest.sha1sum 7c1464f084 Sorted cptest.sha1sum 1 year ago
fixup-gv.sh fc05a9a4a3 Added fixup-gv.sh and Makefile rules to generate annotated goroutines in graphviz output. 1 year ago
go.mod f3e8383dce Initial aead/chacha20 support (ChaCha20_12) 1 month ago
go.sum f3e8383dce Initial aead/chacha20 support (ChaCha20_12) 1 month ago
grml.yaml f0254c664f The Great Renaming: hkexsh -> xs (Xperimental Shell) 5 months ago
session.go f0254c664f The Great Renaming: hkexsh -> xs (Xperimental Shell) 5 months ago
session_test.go 50e786e549 Added session_test.go 1 month ago
termmode_unix.go f0254c664f The Great Renaming: hkexsh -> xs (Xperimental Shell) 5 months ago
termmode_windows.go f0254c664f The Great Renaming: hkexsh -> xs (Xperimental Shell) 5 months ago
viz_xs_dot.png f0254c664f The Great Renaming: hkexsh -> xs (Xperimental Shell) 5 months ago
xsd.initrc f5c155de48 Fixed xsd.initrc $ARGS passing 1 month ago





XS (Xperimental 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 KEX/KEM algorithms used, 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 (xs and xsd) 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).

Key Exchange

Currently supported exchanges are:

Currently supported session algorithms:



  • HMAC-SHA256
  • HMAC-SHA512


Calls to xsnet.Dial() and xsnet.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.

Session Negotiation

Above the xsnet.Conn layer, the server and client apps in this repository (xsd/ and xs/ respectively) negotiate session settings (cipher/hmac algorithms, interactive/non-interactive mode, tunnel specifiers, etc.) to be used for communication.

Padding and Chaffing

Packets are subject to padding (random size, randomly applied as prefix or 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).

Mux/Demux of Chaffing and Tunnel Data

Chaffing and 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 chaff or tunnel specifier so that they can be discarded as chaff or de-multiplexed and delivered to the proper tunnel endpoints, respectively.

Accounts and Passwords

Within the xspasswd/ directory is a password-setting utility. XS uses its own password file distinct from the system /etc/passwd to authenticate clients, using standard bcrypt+salt storage. This is currently done to allow alternate login credentials via xs vs. console/ssh login, due to the experimental nature of the program. At some point in the future an option to use the system's /etc/passwd and /etc/shadow may be implemented, making the use of the auxilliary xspasswd utility optional or obsolete.


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/xs
$ cd $GOPATH/src/blitter.com/go/xs
$ go build ./... # install all dependent go pkgs

To build

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

To install, uninstall, re-install

$ sudo make [install | uninstall | reinstall]

To manage service (assuming openrc init)

An example init script (xsd.initrc) is provided. Consult your Linux distribution documentation for proper service/daemon installation. For openrc,

$ sudo cp xsd.initrc /etc/init.d/xsd
$ sudo rc-config add xsd default

The make system assumes installation in /usr/local/sbin (xsd, xspasswd) and /usr/local/bin (xs/xc symlink).

$ sudo rc-config [start | restart | stop] xsd

To set accounts & passwords:

$ sudo touch /etc/xs.passwd
$ sudo xspasswd/xspasswd -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 xsd && sudo ./xsd &  # add -d for debugging

Interactive shell

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

One-shot command

[B]$ cd xs && ./xs -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 (xs) 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 xs to request a token from the remote server, which will return a hostname:token string. Place this string into $HOME/.xs_id to allow logins without entering a password (obviously, $HOME/.xs_id on both server and client for the user should not be world-readable.)

File Copying using xc

xc is a symlink to xs, 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:

$ xc fileA /some/where/fileB /some/where/else/dirC joebloggs@host-or-ip:remoteDir

Remote (server) to local (client) copy:

$ xc joebloggs@host-or-ip:/remoteDirOrFile /some/where/local/Dir

xc uses a 'tarpipe' to send file data over the encrypted channel. Use the -d flag on client or server to see the generated tar commands if you're curious.

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.

If the 'pv' pipeview utility is available (http://www.ivarch.com/programs/pv.shtml) file transfer progress and bandwidth control will be available (suppress the former with the -q option, set the latter with -L <bytes_per_second>).


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

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

Example, tunnelling ssh through xs

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