From 4648188bdc113b2ce3a3ab10682c45e331ef5197 Mon Sep 17 00:00:00 2001 From: Russtopia Date: Fri, 5 Jul 2019 23:56:18 -0700 Subject: [PATCH] Updated README.md --- README.md | 65 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 35 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 26e40f4..7a8852c 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ [![GoDoc](https://godoc.org/blitter.com/go/hkexsh?status.svg)](https://godoc.org/blitter.com/go/hkexsh) -HKExSh +# HKExSh -- HKExSh (**H**erradura**K**yber**Ex** **Sh**ell) is a golang implementation of a simple @@ -19,6 +19,7 @@ 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 @@ -40,16 +41,20 @@ Currently supported session algorithms: * HMAC-SHA512 +### Conn 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. +### Session Negotiation +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 mode, tunnel specifiers, 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). +### 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). -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. +### 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. -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. +### Accounts and Passwords +Within the hkexpasswd/ directory is a password-setting utility. HKExSh 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 hkexsh 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 hkexpasswd utility optional or obsolete. HERRADURA KEX @@ -65,51 +70,51 @@ 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](https://csrc.nist.gov/Projects/Post-Quantum-Cryptography). 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.) -Dependencies: --- -* Recent version of go (tested, at various times, with go-1.9 to go-1.11.1) +### Dependencies: + +* Recent version of go (tested, at various times, with go-1.9 to go-1.12.4) * [github.com/mattn/go-isatty](http://github.com/mattn/go-isatty) //terminal tty detection * [github.com/kr/pty](http://github.com/kr/pty) //unix pty control (server pty connections) * [github.com/jameskeane/bcrypt](http://github.com/jameskeane/bcrypt) //password storage/auth -* [blitter.com/go/goutmp](https://gogs.blitter.com/RLabs/goutmp) // wtmp/lastlog C bindings +* [blitter.com/go/goutmp](https://gogs.blitter.com/RLabs/goutmp) // wtmp/lastlog C bindings for user accounting * [https://git.schwanenlied.me/yawning/kyber](https://git.schwanenlied.me/yawning/kyber) // golang Kyber KEM * [https://git.schwanenlied.me/yawning/newhope](https://git.schwanenlied.me/yawning/newhope) // golang NEWHOPE,NEWHOPE-SIMPLE KEX * [blitter.com/go/mtwist](https://gogs.blitter.com/RLabs/mtwist) // 64-bit Mersenne Twister PRNG * [blitter.com/go/cryptmt](https://gogs.blitter.com/RLabs/cryptmt) // CryptMTv1 stream cipher -Get source code --- +### 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 --- +### To build + * $ cd $GOPATH/src/blitter.com/go/hkexsh * $ make clean all -To install, uninstall, re-install --- +### To install, uninstall, re-install + * $ sudo make [install | uninstall | reinstall] -To manage service (assuming openrc init) --- +### 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: --- +### 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') --- +### 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 @@ -126,15 +131,15 @@ NOTE if running client (hkexsh) with -d, one will likely need to run 'reset' aft 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 --- +### 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 --- +### 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. @@ -150,18 +155,18 @@ Local (client) to remote (server) copy: Remote (server) to local (client) copy: * hkexcp joebloggs@host-or-ip:/remoteDirOrFile /some/where/local/Dir +hkexcp 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. -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. +### Tunnels -Tunnels --- 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](https://blitter.com:3000/RLabs/hkexsh/issues/15)) +Example, tunnelling ssh through hkexsh * [server side] $ sudo /usr/sbin/sshd -p 7002 * [client side, term A] $ hkexsh -T=6002:7002 user@server