xs

README

XS

XS (Xperimental Shell) is 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. Supports encrypted interactive and non-interactive sessions (remote commands), remote file copying and tunnels.

Runs on Linux, FreeBSD, Windows (client only, MSYS) and Android (within Termux). https://gogs.blitter.com/RLabs/xs

It is stable to the point that I use it for day-to-day remote access in place of, and in preference to, ssh.

---

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:

• The HerraduraKEx key exchange algorithm first released at Omar Elejandro Herrera Reyna's HerraduraKEx project;
• The KYBER IND-CCA-2 secure key encapsulation mechanism, pq-crystals Kyber :: Yawning/kyber golang implementation
• The NEWHOPE algorithm newhopecrypto.org :: Yawning/newhope golang implementation
• The FrodoKEM algorithm frodokem.org :: Go version by Eduardo E. S. Riccardi

Currently supported session algorithms:

[Encryption]

• AES-256
• Twofish-128
• Blowfish-64
• CryptMTv1 (64bit) (https://eprint.iacr.org/2005/165.pdf)
• ChaCha20 (https://github.com/aead/chacha20)
• HOPSCOTCH (https://gogs.blitter.com/Russtopia/hopscotch)

[HMAC]

• HMAC-SHA256
• HMAC-SHA512
• WHIRLPOOL

---

A Note on 'cryptographic agility'

It has been suggested recently to me that offering multiple cryptographic primitives is considered bad in 2021.

An interesting question. See this write-up for a discussion.

xs operates via the philosophy that it is the server admin's prerogitive to configure local policy wrt. allowed cryptographic primitives. The connection protocol makes no allowance for any sort of 'downgrades' or algo substitution during negotiation; there is no 'fallback' mode or two-way negotiation of what primitives to use, which would open the possibility of downgrade attacks. Unlike ssh, the server does not offer to clients a list of supported algorithms; the client can only offer a single configuration to the server, which it simply accepts or rejects without comment to the client.

In all releases prior to v0.9.3, absent a specific whitelist of algs to allow, the server allows 'all' combinations of the above cryptographic primitives to be proposed by clients (but again, only one combination is proposed by the client in a single connect attempt). If the admin wishes to restrict the accepted algorithms now or at any future time, they may use the -aK, -aC and -aH options when launching the server to define a whitelist which excludes certain primitives.

As of release v0.9.3, the default when supplying no explicit KEX, cipher or HMAC algorithms to xsd results in no algs being accepted; so the admin must decide on a specific whitelist of algorithms.

---

Conn

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, xspasswd, used if one wishes xs access to use separate credentials from those of the default (likely ssh) login method. In this mode, xsd uses its own password file distinct from the system /etc/passwd to authenticate clients, using standard bcrypt+salt storage. Activate this mode by invoking xsd with -s false.

HERRADURA KEX

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.

KYBER IND-CCA-2 KEM

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

Installing

As of Go 1.8, one can directly use go install to get the client xs and server xsd binaries; however it is not recommended, as xsd requires root and for general use should be in one of the system directories, akin to other daemons. If one insists, the following will work to place them in $HOME/go/bin:

$ go install blitter.com/go/xs/xs@latest
$ go install blitter.com/go/xs/xsd@latest

(NOTE the -v (version) option for binaries obtained in this manner will be blank; another reason to build them yourself locally using the steps below.)

Get source code

$ git clone https://gogs.blitter.com/RLabs/xs

To build

$ cd xs
$ make clean && make

To install, uninstall, re-install (xsd server)

$ sudo make [install | uninstall | reinstall]

To manage service (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

To manage service (sysV init)

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

$ sudo cp xsd.sysvrc /etc/init.d/xsd
$ sudo sysv-rc-conf --level 2345 xsd on

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
# .. or sudo /etc/init.d/xsd [start | restart stop]

To set accounts & passwords (DEPRECATED: -s is now true by default)

$ 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/.config/xs/.xs_id to allow logins without entering a password (obviously, $HOME/.config/xs/.xs_id on both server and client for the user should not be world-readable.)

$ xs -g user@host.net >>~/.config/xs/.xs_id

[enter password blindly, authtoken entry will be stored in ~/.config/xs/.xs_id]

NOTE you may need to remove older entries for the same host if this is not the first time you have added it to your .xs_id file.

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

Special care should be taken when doing client → server copies: since the tarpipe (should) always succeed at least sending data to the remote side, a destination with no write permission will not return a nonzero status and the client closes its end after sending all data, giving the server no opportunity to send an error code to the client. It is recommended to test beforehand if the server-side destination is writable (and optionally if the destination already exists, if one does not want to clobber an existing path) by:

$ xs -x "test -w /dest/path" me@myserver  ## If clobbering /dest/path is OK, or
$ xs -x "test -w /dest/path -o ! -e /dest/path" me@myserver  ## To prevent clobbering

Perhaps in future a more complex handshake will be devised to allow the client to half-close the tarpipe, allowing the server to complete its side of the operation and send back its success or failure code, but the current connection protocol does not allow this. If this is a deal-breaking feature, please contact the maintainer.

Tunnels

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

Building for FreeBSD

The Makefile(s) to build require GNU make (gmake). Please install and invoke build via: $ gmake clean all

Documentation

Overview

Package xs - a secure terminal client/server written from scratch in Go

Copyright (c) 2017-2020 Russell Magee Licensed under the terms of the MIT license (see LICENSE.mit in this distribution)

golang implementation by Russ Magee (rmagee_at_gmail.com)

Index

• func AuthUserByPasswd(ctx *AuthCtx, username string, auth string, fname string) (valid bool, allowedCmds string)
• func AuthUserByToken(ctx *AuthCtx, username string, connhostname string, auth string) (valid bool)
• func GetTool(tool string) (ret string)
• func ReadPassword(f *os.File) ([]byte, error)
• func Restore(f *os.File, state *State) error
• func VerifyPass(ctx *AuthCtx, user, password string) (bool, error)
• type AuthCtx
  • func NewAuthCtx() (ret *AuthCtx)
• type Session
  • func NewSession(op, who, connhost, ttype, cmd, authcookie []byte, status uint32) *Session
  • func (h Session) AuthCookie(reallyShow bool) []byte
  • func (h *Session) ClearAuthCookie()
  • func (h Session) Cmd() []byte
  • func (h Session) ConnHost() []byte
  • func (h Session) Op() []byte
  • func (h *Session) SetAuthCookie(a []byte)
  • func (h *Session) SetCmd(c []byte)
  • func (h *Session) SetConnHost(n []byte)
  • func (h *Session) SetOp(o []byte)
  • func (h *Session) SetStatus(s uint32)
  • func (h *Session) SetTermType(t []byte)
  • func (h *Session) SetWho(w []byte)
  • func (h Session) Status() uint32
  • func (h *Session) String() string
  • func (h Session) TermType() []byte
  • func (h Session) Who() []byte
• type State
  • func GetState(f *os.File) (*State, error)
  • func MakeRaw(f *os.File) (*State, error)

Functions

func AuthUserByPasswd

func AuthUserByPasswd(ctx *AuthCtx, username string, auth string, fname string) (valid bool, allowedCmds string)

AuthUserByPasswd checks user login information using a password. This checks /etc/xs.passwd for auth info, and system /etc/passwd to cross-check the user actually exists. nolint: gocyclo

func AuthUserByToken

func AuthUserByToken(ctx *AuthCtx, username string, connhostname string, auth string) (valid bool)

AuthUserByToken checks user login information against an auth token. Auth tokens are stored in each user's $HOME/.config/xs/.xs_id and are requested via the -g option. The function also check system /etc/passwd to cross-check the user actually exists.

func GetTool

func GetTool(tool string) (ret string)

func ReadPassword

func ReadPassword(f *os.File) ([]byte, error)

ReadPassword reads a line of input from a terminal without local echo. This is commonly used for inputting passwords and other sensitive data. The slice returned does not include the \n.

func Restore

func Restore(f *os.File, state *State) error

Restore restores the terminal connected to the given file descriptor to a previous state.

func VerifyPass

func VerifyPass(ctx *AuthCtx, user, password string) (bool, error)

VerifyPass verifies a password against system standard shadow file Note auxilliary fields for expiry policy are *not* inspected.

Types

type AuthCtx

type AuthCtx struct {
	// contains filtered or unexported fields
}

func NewAuthCtx

func NewAuthCtx() (ret *AuthCtx)

type Session

type Session struct {
	// contains filtered or unexported fields
}

Session holds essential bookkeeping info about an active session.

func NewSession

func NewSession(op, who, connhost, ttype, cmd, authcookie []byte, status uint32) *Session

NewSession returns a new Session record.

func (Session) AuthCookie

func (h Session) AuthCookie(reallyShow bool) []byte

AuthCookie returns the authcookie (essentially the password) used for authorization of the Session. This return value is censored unless reallyShow is true (so dumps of Session Info do not accidentally leak it).

func (*Session) ClearAuthCookie

func (h *Session) ClearAuthCookie()

ClearAuthCookie attempts to scrub the Session's stored authcookie.

This should of course be called as soon as possible after authentication and it is no longer required.

func (Session) Cmd

func (h Session) Cmd() []byte

Cmd returns the command requested for execution by a client initiating the Session.

func (Session) ConnHost

func (h Session) ConnHost() []byte

ConnHost returns the connecting hostname/IP string for a Session.

func (Session) Op

func (h Session) Op() []byte

Op returns the op code of the Session (interactive shell, cmd, ...)

func (*Session) SetAuthCookie

func (h *Session) SetAuthCookie(a []byte)

SetAuthCookie stores the authcookie (essentially the password) used to authenticate the Session.

func (*Session) SetCmd

func (h *Session) SetCmd(c []byte)

SetCmd stores the command request by the client for execution when initiating the Session.

func (*Session) SetConnHost

func (h *Session) SetConnHost(n []byte)

SetConnHost stores the connecting hostname/IP string for a Session.

func (*Session) SetOp

func (h *Session) SetOp(o []byte)

SetOp stores the op code desired for a Session.

func (*Session) SetStatus

func (h *Session) SetStatus(s uint32)

SetStatus stores the current Session status code.

func (*Session) SetTermType

func (h *Session) SetTermType(t []byte)

SetTermType stores the TERM env variable supplied by the client initiating a Session.

func (*Session) SetWho

func (h *Session) SetWho(w []byte)

SetWho sets the username associated with a Session.

func (Session) Status

func (h Session) Status() uint32

Status returns the (current) Session status code.

This usually corresponds to a UNIX shell exit code, but extended codes are returns at times to indicate internal errors.

func (*Session) String

func (h *Session) String() string

Output Session record as a string. Implements Stringer interface.

func (Session) TermType

func (h Session) TermType() []byte

TermType returns the TERM env variable reported by the client initiating a Session.

func (Session) Who

func (h Session) Who() []byte

Who returns the user associated with a Session.

type State

type State struct {
	// contains filtered or unexported fields
}

State contains the state of a terminal.

func GetState

func GetState(f *os.File) (*State, error)

GetState returns the current state of a terminal which may be useful to restore the terminal after a signal.

func MakeRaw

func MakeRaw(f *os.File) (*State, error)

MakeRaw put the terminal connected to the given file descriptor into raw mode and returns the previous state of the terminal so that it can be restored.