NAME

     gsocket — connect like there is no firewall. Securely.

SYNOPSIS

     gsocket [-qT] [-s secret] [-k keyfile] [-p port] [program] [args ...]

DESCRIPTION

     The gsocket tool can be used to enable a program to communicate through a firewall in
     situations where it would not be possible to establish a direct connection to another
     host/workstation (NATed/firewalled). The typical scenario is two workstations that are on
     separate private networks and behind separate firewalls. The gsocket tool hijacks the
     network library functions (such as connect() and accept()) of the program and encrypts and
     redirects the traffic through the Global Socket Relay Network (GSRN).

     Neither workstation needs to open a port in their firewall nor accept incoming TCP
     connections.

     The connection is end-2-end encrypted using SRP (RFC 5054) with AES-256 and a 4096 Prime.
     The GSRN sees only the encrypted traffic.

     Common uses include:

           •   ssh from one workstation to another
           •   OpenVPN between two workstations
           •   netcat between two workstations
           •   and much, much more.

      ...while both workstations are behind NAT and firewalled.

     Abandon the thought of IP addresses and port numbers: Two programs should be able to
     communicate with each other as long as they know the same secret (rather than each other's
     IP address and port number). The gsocket tools establishes such a connection regardless and
     independent of the local IP address or geographical location. It does so by analyzing the
     program and replacing the IP Layer with its own transport through GSRN. The connection is
     end-2-end encrypted. The GSRN sees only the encrypted traffic.

     The typical scenario is a client/server arrangement such as ssh and sshd: Connections by ssh
     to any hostname ending in '.gsocket' are redirected (through the GSRN) to the (firewalled)
     sshd server.

     The redirection is done per program (and limited to that program only). The gsocket tool
     does not change the routing table and does not change the NAT nor the firewall settings. It
     does not require superuser privileges either.

OPTIONS

     -s secret
             A secret chosen by the user. Both ends need to use the same secret to connect.

     -k file
             A file containing the secret.

     -g      Generate a secure random secret and output it to standard output.

     -q      Quiet mode. Do not output any warnings or errors.

     -T      Use TOR. The gsocket tool will connect through TOR to the GSRN. This requires TOR to
             be installed and running.

     -p port
             TCP port range of listening ports to redirect [default=all].

     Connections to any hostname ending in '*.gsocket' or to the IP Address '127.31.33.7' are
     redirected through the GSRN.

     Connections to any hostname ending in '*.thc' or to the IP Address '127.31.33.8' are first
     redirected through TOR and then through the GSRN.

EXAMPLES

     Example 1 - OpenSSH between two firewalled workstations:

     Server:
           $ gsocket -s MySecret /usr/sbin/sshd
     Client:
           $ gsocket -s MySecret ssh xaitax@gsocket

     Example 2 - netcat between two firewalled workstations:

     Server:
           $ gsocket -s MySecret nc -lp 31337
     Client:
           $ gsocket -s MySecret nc gsocket 31337

     Example 3 - OpenVPN between two firewalled workstations:

     Server:
           $ gsocket -s MySecret openvpn --dev tun1 --proto tcp-server --ifconfig 10.9.8.1
           10.9.8.2
     Client:
           $ gsocket -s MySecret openvpn --dev tun1 --proto tcp-client --ifconfig 10.9.8.2
           10.9.8.1 --remote gsocket

     Example 4 - IRCD between two firewalled workstations:

     Server:
           $ gsocket -s MySecret inspircd --nolog --nofork
     Client:
           $ gsocket -s MySecret irssi -c gsocket

     Example 5 - Socat between two firewalled workstations:

     Server:
           $ gsocket -s MySecret socat - TCP_LISTEN:31337
     Client:
           $ gsocket -s MySecret socat - TCP:gsocket:31337

SYSTEMCTL INSTALLATION

     It is possible to make any service/daemon accessible through any firewall. The service is
     then only acessible through the GSRN and only if the client knows the secret. No port or
     service is exposed to the public Internet and the existence of the service remains hidden.
     This example makes openssh-server (sshd) accessible through the GSRN. Nobody, not even the
     GSRN operators, have access to the port, daemon or service (they do not know the secret).
     The new service coexists with the existing openssh-server and does not interfere with the
     existing openssh-server.

     1. Copy /etc/systemd/system/sshd to /etc/systemd/system/gs-sshd

     2. Edit /etc/systemd/system/gs-sshd and change this line:
           ExecStart=/usr/sbin/sshd -D $SSHD_OPTS
     to
           ExecStart=gsocket -s MySecret /usr/sbin/sshd -D $SSHD_OPTS

     3. Start the newly created service
           # systemctl start gs-sshd

     4. Check the status
           # systemctl status gs-sshd

     5. Connect from any other host to the newly created (hidden) openssh-server:
           $ gsocket -s MySecret ssh user@gsocket

TESTING

     The gsocket tool uses the LD_PRELOAD method to hijack network calls from the calling
     process. It then concatenates the port number to the secret and spwans a gs-netcat process
     to forward the TCP connection. The setup can be tested with gs-netcat.

     Test 1 - gsocket server and gs-netcat client:

     Server:
           $ gsocket -s MySecret nc -lp 1234 # TCP port is 1234
     Client:
           $ gs-netcat -s 1234-MySecret # Notice `<port>-<SECRET>`

     Test 2 - gsocket client and gs-netcat server:

     Server:
           $ gs-netcat -s 1234-MySecret -l
     Client:
           $ gsocket -s MySecret nc blah.gsocket 1234

     Internally the gsocket tool (on the client side) forks a background gs-netcat process
     listening on 127.31.33.7 on a random TCP port. The gsocket tool then detects `nc` trying to
     resolve `blah.gsocket` and returns 127.31.33.7 to `nc`. The `nc` process then connects to
     127.31.33.7 instead and the gs-netcat process (that got started automatically) takes the
     connection and forwards the traffic via the GSRN. The `nc` tool can also directly connect to
     127.31.33.7 instead of blah.gsocket (for testing):

     Client:
           $ gsocket -s MySecret nc -n 127.31.33.7 1234

     Test 3 - SSHD via gsocket:

     Server:
           $ gsocket -s MySecret /usr/sbin/sshd -D -p 1234
     Client:
           $ gs-netcat -s 1234-MySecret
           SSH-2.0-OpenSSH_8.4p1 Debian-2

     Use gs-netcat as a port-forwarder and ssh to connect:

     Client:
           $ gs-netcat -s 1234-MySecret -p 44222
           $ ssh -p 44222 user@127.1

     Test 4 - SSH via gsocket:

     On the server start a gs-netcat port forward to forward incoming GSRN connections to the
     SSHD on localhost:

     Server:
           $ gs-netcat -s 22-MySecret -l -d 127.0.0.1 -p 22
     Client:
           $ gsocket -s MySecret ssh user@gsocket

ENVIRONMENT

     The following environment variables can be set to control the behavior of gsocket

     GSOCKET_SOCKS_IP
           Specify the IP address of the TOR server (or any other SOCKS server). Use together
           with -T. Default is 127.0.0.1.

     GSOCKET_SOCKS_PORT
           The port number of the TOR server (or any other SOCKS server). Use together with -T.
           Default is 9050.

     GSOCKET_ARGS
           A string containing additional command line parameters. First the normal command line
           parameters are processed and then the command line parameters from GSOCKET_ARGS.

SECURITY

     Passing the password as command line parameter is not secure. Consider using the -k option
     or GSOCKET_ARGS or enter the password when prompted:

           $ gsocket -k <file>

           $ export GSOCKET_ARGS="-s MySecret"
           $ gsocket

     1. The security is end-2-end. This means from user-2-user (and not just to the GSRN). The
     GSRN relays only (encrypted) data to and from the users.

     2. The session is 256 bit and ephemeral. It is freshly generated for every session and
     generated randomly (and is not based on the password). It uses OpenSSL's SRP with AES-256
     and a 4096 Prime.

     3. The password can be 'weak' without weakening the security of the session. A brute force
     attack against a weak password requires a new TCP connection for every guess.

     4. Do not use stupid passwords like 'password123'. Malice might pick the same (stupid)
     password by chance and connect. If in doubt use gs-netcat -g to generate a strong one.
     Alice's and Bob's password should at least be strong enough so that Malice can not guess it
     by chance while Alice is waiting for Bob to connect.

     5. If Alice shares the same password with Bob and Charlie and either one of them connects
     then Alice can not tell if it is Bob or Charlie who connected.

     6. Assume Alice shares the same password with Bob and Malice. When Alice stops listening for
     a connection then Malice could start to listen for the connection instead. Bob (when opening
     a new connection) can not tell if he is connecting to Alice or to Malice. Use -a <token> if
     you worry about this. TL;DR: When sharing the same password with a group larger than 2 then
     it is assumed that everyone in that group plays nicely. Otherwise use SSH over the GS/TLS
     connection.

     7. SRP has Perfect Forward Secrecy. This means that past sessions can not be decrypted even
     if the password becomes known.

NOTES

     The latest version is available from https://github.com/hackerschoice/gsocket/.

SEE ALSO

     gs-netcat(1), gs-sftp(1), gs-mount(1), blitz(1), nc(1), socat(1)

BUGS

     Efforts have been made to have gsocket "do the right thing" in all its various modes. If you
     believe that it is doing the wrong thing under whatever circumstances, please notify me
     (skyper@thc.org) and tell me how you think it should behave.