RusstopiaLabs
/
xs
mirror of https://gogs.blitter.com/RLabs/xs
1
0
Fork 0
Code Issues Releases Wiki Activity

Updated README.md

This commit is contained in:
Russtopia 2019-07-05 23:56:18 -07:00
parent b8d32ed882
commit 4648188bdc
1 changed files with 35 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
README.md
View File

@ -1,7 +1,7 @@
[![GoDoc](https://godoc.org/blitter.com/go/hkexsh?status.svg)](https://godoc.org/blitter.com/go/hkexsh) [![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 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 secure sockets using one of a selectable set of experimental key exchange (KEX) or
key encapsulation mechanisms (KEM). key encapsulation mechanisms (KEM).
### Key Exchange
Currently supported exchanges are: Currently supported exchanges are:
* The HerraduraKEx key exchange algorithm first released at * The HerraduraKEx key exchange algorithm first released at
@ -40,16 +41,20 @@ Currently supported session algorithms:
* HMAC-SHA512 * 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. 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 ### Padding and Chaffing
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). 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 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.) 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: ### Dependencies:
--
* Recent version of go (tested, at various times, with go-1.9 to go-1.11.1) * 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/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/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 * [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/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 * [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/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 * [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 * $ go get -u blitter.com/go/hkexsh
* $ cd $GOPATH/src/blitter.com/go/hkexsh * $ cd $GOPATH/src/blitter.com/go/hkexsh
* $ go build ./... # install all dependent go pkgs * $ go build ./... # install all dependent go pkgs
To build ### To build
--
* $ cd $GOPATH/src/blitter.com/go/hkexsh * $ cd $GOPATH/src/blitter.com/go/hkexsh
* $ make clean all * $ make clean all
To install, uninstall, re-install ### To install, uninstall, re-install
--
* $ sudo make [install | uninstall | reinstall] * $ sudo make [install | uninstall | reinstall]
To manage service (assuming openrc init) ### To manage service (assuming openrc init)
--
* $ sudo rc-config [start | restart | stop] hkexshd * $ 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). 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 touch /etc/hkexsh.passwd
* $ sudo hkexpasswd/hkexpasswd -u joebloggs * $ sudo hkexpasswd/hkexpasswd -u joebloggs
* $ <enter a password, enter again to confirm> * $ <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: In separate shells A and B:
* [A]$ cd hkexshd && sudo ./hkexshd & # add -d for debugging * [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 to fix up the shell tty afterwards, as stty echo may not be restored if client crashes
or is interrupted. 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 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 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 entering a password (obviously, $HOME/.hkexsh_id on both server and client for the user
should *not* be world-readable.) 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 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 it is being invoked in 'shell' or 'copy' mode. Refer to the '-h' output for differences in
accepted options. accepted options.
@ -150,18 +155,18 @@ Local (client) to remote (server) copy:
Remote (server) to local (client) copy: Remote (server) to local (client) copy:
* hkexcp joebloggs@host-or-ip:/remoteDirOrFile /some/where/local/Dir * 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. 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. Simple tunnels (client -> server, no reverse tunnels for now) are supported.
Syntax: hkexsh -T=<tunspec>{,<tunspec>...} Syntax: hkexsh -T=<tunspec>{,<tunspec>...}
.. where <tunspec> is <localport:remoteport> .. 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 * [server side] $ sudo /usr/sbin/sshd -p 7002
* [client side, term A] $ hkexsh -T=6002:7002 user@server * [client side, term A] $ hkexsh -T=6002:7002 user@server