mirror of https://gogs.blitter.com/RLabs/xs
Updated README.md
This commit is contained in:
Russtopia
parent
b8d32ed882
commit
4648188bdc
65
README.md
65
README.md
|
|
@ -1,7 +1,7 @@
|
|||
[](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
|
||||
|
|
|
|||
Loading…
Reference in New Issue