diff --git a/README.md b/README.md index 104740b3..c6a830d7 100644 --- a/README.md +++ b/README.md @@ -1,153 +1,161 @@ -# Secure Socket Funneling (SSF) +# Secure Socket Funneling -## How to build - -### Requirements - - * Winrar >= 5.2.1 (Third party builds on windows) - * Boost >= 1.61.0 - * OpenSSL >= 1.0.2 - * Google Test = 1.7.0 - * CMake >= 2.8.11 - * nasm (openssl build on windows) - * Perl | Active Perl >= 5.20 (openssl build on windows) - * C++11 compiler (Visual Studio 2013, Clang, g++, etc.) - * libkrb5-dev or equivalent (gssapi on linux) +Secure Socket Funneling (SSF) is a network tool and toolkit. -SSF_SECURITY: +It provides simple and efficient ways to forward data from multiple sockets (TCP or UDP) through a single secure TLS link to a remote computer. -* **STANDARD**: the project will be build with standard security features -* **FORCE_TCP_ONLY**: the project will be built without security features to facilitate debugging +SSF is cross platform (Windows, Linux, OSX) and shipped as standalone executables. -### Build SSF on Windows +Features: +* Local and remote TCP port forwarding +* Local and remote UDP port forwarding +* Local and remote SOCKS server +* Local and remote shell through socket +* Native relay protocol +* TLS connection with strongest cipher-suites -* Go in project directory +[Download prebuilt binaries](https://securesocketfunneling.github.io/ssf/#download) -```bash -cd PROJECT_PATH -``` - -* Copy [Boost archive](http://www.boost.org/users/download/) in ``third_party/boost`` +[Documentation](https://securesocketfunneling.github.io/ssf/) -```bash -cp boost_1_XX_Y.tar.bz2 PROJECT_PATH/third_party/boost -``` +## How to use -* Copy [OpenSSL archive](https://www.openssl.org/source/) in ``third_party/openssl`` +### Standard command line -```bash -cp openssl-1.0.XY.tar.gz PROJECT_PATH/third_party/openssl +```plaintext +ssf[.exe] [-h] [-v verb_level] [-q] [-L loc:ip:dest] [-R rem:ip:dest] [-D port] [-F port] [-U loc:ip:dest] [-V rem:ip:dest] [-X port] [-Y port] [-b bounce_file] [-c config_file] [-p port] [host] ``` -If you are using *openssl-1.0.2a*, you need to fix the file ``crypto/x509v3/v3_scts.c``. It contains an incorrect ``#include`` line. -Copy [the diff from OpenSSL Github](https://github.com/openssl/openssl/commit/77b1f87214224689a84db21d2eb54e9497186d93.diff) -(ignore the 2 first lines) and put it in ``PROJECT_PATH/third_party/openssl/patches``. The build script will then patch the sources. - -* Copy [GTest archive](https://github.com/google/googletest/archive/release-1.7.0.zip) in ``third_party/gtest`` +* -v : Verbosity level (critical, error, warning, info, debug, trace), default is info +* -q : Quiet mode (no log) +* -L : TCP port forwarding with *loc* as the local TCP port, *ip* and *dest* as destination toward which the forward should be done from the server. +* -R : TCP remote port forwarding with *rem* as the TCP port to forward from the remote host, *ip* and *dest* as destination toward which the forward should be done from the client. +* -D : open a port (*port*) on the client to connect to a SOCKS server on the server from the client. +* -F : open a port (*port*) on the server to connect to a SOCKS server on the client from the server. +* -U : UDP port forwarding with *loc* as the UDP port to forward from the client, *ip* and *dest* as destination toward which the forward should be done from the server. +* -V : UDP remote port forwarding with *rem* as the UDP port to forward from the server, *ip* and *dest* as destination toward which the forward should be done from the client. +* -X : open a port (*port*) on the client side, each connection to that port creates a process with I/O forwarded to/from the server side (the binary used can be set with the config file) +* -Y : open a port (*port*) on the server side, each connection to that port creates a process with I/O forwarded to/from the client side (the binary used can be set with the config file) +* -b : *bounce_file* is the file containing the list of relays to use. +* -c : *config_file* is the config file containing configuration for SSF (TLS configuration). +* -p : *port* is the port on which to listen (for the server) or to connect (for the client). The default value is 8011. +* host : the IP address or the name of the remote server to connect to. - ```bash - cp gtest-1.X.Y.zip PROJECT_PATH/third_party/gtest - ``` +#### Server example -* Generate project +Server will listen on all network interfaces on port **8011** -```bash -git submodule update --init --recursive -mkdir PROJECT_PATH/build -cd PROJECT_PATH/build -cmake -DSSF_SECURITY:STRING="STANDARD|FORCE_TCP_ONLY" ../ +```plaintext +ssfs[.exe] ``` -* Build project +Server will listen on **192.168.0.1:9000** -```bash -cd PROJECT_PATH/build -cmake --build . --config Debug|Release +```plaintext +ssfs[.exe] -p 9000 192.168.0.1 ``` -### Build SSF on Linux +#### Client example -* Go in project directory +Client will open port 9000 locally and wait SOCKS requests to be transferred to +server **192.168.0.1:8000** -```bash -cd PROJECT_PATH +```plaintext +ssfc[.exe] -D 9000 -b bounce.txt -c config.json -p 8000 192.168.0.1 ``` -* Copy [Boost archive](http://www.boost.org/users/download/) in ``third_party/boost`` +### Copy command line -```bash -cp boost_1_XX_Y.tar.bz2 PROJECT_PATH/third_party/boost +```plaintext +ssfcp[.exe] [-h] [-b bounce_file] [-c config_file] [-p port] [-t] [host@]path [[host@]path] ``` -* Copy [OpenSSL archive](https://www.openssl.org/source/) in ``third_party/openssl`` - -```bash -cp openssl-1.0.XY.tar.gz PROJECT_PATH/third_party/openssl -``` +* -b : *bounce_file* is the file containing the list of relays to use. +* -c : *config_file* is the config file containing configuration for SSF (TLS configuration). +* -t : input from stdin -* Copy [GTest archive](https://github.com/google/googletest/archive/release-1.7.0.zip) in ``third_party/gtest`` +#### Copy from local to remote destination : -```bash -cp gtest-1.X.Y.zip PROJECT_PATH/third_party/gtest +```plaintext +ssfcp[.exe] [-b bounce_file] [-c config_file] [-p port] path/to/file host@absolute/path/directory_destination ``` -* Generate project - -```bash -git submodule update --init --recursive -mkdir PROJECT_PATH/build -cd PROJECT_PATH/build -cmake -DCMAKE_BUILD_TYPE=Release|Debug -DSSF_SECURITY:STRING="STANDARD|FORCE_TCP_ONLY" ../ +```plaintext +ssfcp[.exe] [-b bounce_file] [-c config_file] [-p port] path/to/file* host@absolute/path/directory_destination ``` -* Build project +#### From stdin to remote destination -```bash -cd PROJECT_PATH/build -cmake --build . -- -j +```plaintext +data_in_stdin | ssfcp[.exe] [-b bounce_file] [-c config_file] [-p port] -t host@path/to/destination/file_destination ``` -### Build SSF on Mac OS X - -* Go in project directory +#### Copy remote files to local destination : -```bash -cd PROJECT_PATH +```plaintext +ssfcp[.exe] [-b bounce_file] [-c config_file] [-p port] remote_host@path/to/file absolute/path/directory_destination ``` -* Copy [Boost archive](http://www.boost.org/users/download/) in ``third_party/boost`` - -```bash -cp boost_1_XX_Y.tar.bz2 PROJECT_PATH/third_party/boost +```plaintext +ssfcp[.exe] [-b bounce_file] [-c config_file] [-p port] remote_host@path/to/file* absolute/path/directory_destination ``` -* Copy [OpenSSL archive](https://www.openssl.org/source/) in ``third_party/openssl`` - -```bash -cp openssl-1.0.XY.tar.gz PROJECT_PATH/third_party/openssl -``` +### File example -* Copy [GTest archive](https://github.com/google/googletest/archive/release-1.7.0.zip) in ``third_party/gtest`` +#### Bounce file (relay servers) -```bash -cp gtest-1.X.Y.zip PROJECT_PATH/third_party/gtest +```plaintext +127.0.0.1:8002 +127.0.0.1:8003 ``` -* Generate project +#### Config file -```bash -git submodule update --init --recursive -mkdir PROJECT_PATH/build -cd PROJECT_PATH/build -cmake -DCMAKE_BUILD_TYPE=Release|Debug -DSSF_SECURITY:STRING="STANDARD|FORCE_TCP_ONLY" ../ +```plaintext +{ + "ssf": { + "tls": { + "ca_cert_path": "./certs/trusted/ca.crt", + "cert_path": "./certs/certificate.crt", + "key_path": "./certs/private.key", + "dh_path": "./certs/dh4096.pem", + "cipher_alg": "DHE-RSA-AES256-GCM-SHA384" + }, + "http_proxy": { + "host": "proxy.example.com", + "port": "3128", + "credentials": { + "username": "user", + "password": "password", + "domain": "EXAMPLE.COM", + "reuse_ntlm": "true", + "reuse_kerb": "true" + } + }, + "services": { + "shell": { + "path": "/bin/bash", + "args": "" + } + } + } +} ``` -* Build project - -```bash -cd PROJECT_PATH/build -cmake --build . -``` +* *tls.ca_cert_path* : relative or absolute path to the CA certificate file +* *tls.cert_path* : relative or absolute path to the instance certificate file +* *tls.key_path* : relative or absolute path to the private key file +* *tls.dh_path* : relative or absolute path to the Diffie-Hellman file +* *tls.cipher_alg* : cipher algorithm +* *http_proxy.host* : HTTP proxy host +* *http_proxy.port* : HTTP proxy port +* *http_proxy.credentials.username* : proxy username credentials (all platform: Basic or Digest, Windows: NTLM and Negotiate if reuse = false) +* *http_proxy.credentials.password* : proxy password credentials (all platform: Basic or Digest, Windows: NTLM and Negotiate if reuse = false) +* *http_proxy.credentials.domain* : user domain (NTLM and Negotiate auth on Windows only) +* *http_proxy.credentials.reuse_ntlm* : reuse current computer user credentials to authenticate with proxy NTLM auth (SSO) +* *http_proxy.credentials.reuse_kerb* : reuse current computer user credentials (Kerberos ticket) to authenticate with proxy Negotiate auth (SSO) +* *services.shell.path* : binary path used for shell creation (optional) +* *services.shell.args* : binary arguments used for shell creation (optional) ## How to configure @@ -230,141 +238,151 @@ SERVER3:PORT3 The chain will be CLIENT -> SERVER1:PORT1 -> SERVER2:PORT2 -> SERVER3:PORT3 -> TARGET -## How to use +## How to build -### Standard command line +### Requirements -```plaintext -ssf[.exe] [-h] [-v verb_level] [-q] [-L loc:ip:dest] [-R rem:ip:dest] [-D port] [-F port] [-U loc:ip:dest] [-V rem:ip:dest] [-X port] [-Y port] [-b bounce_file] [-c config_file] [-p port] [host] + * Winrar >= 5.2.1 (Third party builds on windows) + * Boost >= 1.61.0 + * OpenSSL >= 1.0.2 + * Google Test = 1.7.0 + * CMake >= 2.8.11 + * nasm (openssl build on windows) + * Perl | Active Perl >= 5.20 (openssl build on windows) + * C++11 compiler (Visual Studio 2013, Clang, g++, etc.) + * libkrb5-dev or equivalent (gssapi on linux) + +SSF_SECURITY: + +* **STANDARD**: the project will be build with standard security features +* **FORCE_TCP_ONLY**: the project will be built without security features to facilitate debugging + +### Build SSF on Windows + +* Go in project directory + +```bash +cd PROJECT_PATH ``` -* -v : Verbosity level (critical, error, warning, info, debug, trace), default is info -* -q : Quiet mode (no log) -* -L : TCP port forwarding with *loc* as the local TCP port, *ip* and *dest* as destination toward which the forward should be done from the server. -* -R : TCP remote port forwarding with *rem* as the TCP port to forward from the remote host, *ip* and *dest* as destination toward which the forward should be done from the client. -* -D : open a port (*port*) on the client to connect to a SOCKS server on the server from the client. -* -F : open a port (*port*) on the server to connect to a SOCKS server on the client from the server. -* -U : UDP port forwarding with *loc* as the UDP port to forward from the client, *ip* and *dest* as destination toward which the forward should be done from the server. -* -V : UDP remote port forwarding with *rem* as the UDP port to forward from the server, *ip* and *dest* as destination toward which the forward should be done from the client. -* -X : open a port (*port*) on the client side, each connection to that port creates a process with I/O forwarded to/from the server side (the binary used can be set with the config file) -* -Y : open a port (*port*) on the server side, each connection to that port creates a process with I/O forwarded to/from the client side (the binary used can be set with the config file) -* -b : *bounce_file* is the file containing the list of relays to use. -* -c : *config_file* is the config file containing configuration for SSF (TLS configuration). -* -p : *port* is the port on which to listen (for the server) or to connect (for the client). The default value is 8011. -* host : the IP address or the name of the remote server to connect to. +* Copy [Boost archive](http://www.boost.org/users/download/) in ``third_party/boost`` -#### Server example +```bash +cp boost_1_XX_Y.tar.bz2 PROJECT_PATH/third_party/boost +``` -Server will listen on all network interfaces on port **8011** +* Copy [OpenSSL archive](https://www.openssl.org/source/) in ``third_party/openssl`` -```plaintext -ssfs[.exe] +```bash +cp openssl-1.0.XY.tar.gz PROJECT_PATH/third_party/openssl ``` -Server will listen on **192.168.0.1:9000** +If you are using *openssl-1.0.2a*, you need to fix the file ``crypto/x509v3/v3_scts.c``. It contains an incorrect ``#include`` line. +Copy [the diff from OpenSSL Github](https://github.com/openssl/openssl/commit/77b1f87214224689a84db21d2eb54e9497186d93.diff) +(ignore the 2 first lines) and put it in ``PROJECT_PATH/third_party/openssl/patches``. The build script will then patch the sources. -```plaintext -ssfs[.exe] -p 9000 192.168.0.1 +* Copy [GTest archive](https://github.com/google/googletest/archive/release-1.7.0.zip) in ``third_party/gtest`` + + ```bash + cp gtest-1.X.Y.zip PROJECT_PATH/third_party/gtest + ``` + +* Generate project + +```bash +git submodule update --init --recursive +mkdir PROJECT_PATH/build +cd PROJECT_PATH/build +cmake -DSSF_SECURITY:STRING="STANDARD|FORCE_TCP_ONLY" ../ ``` -#### Client example +* Build project -Client will open port 9000 locally and wait SOCKS requests to be transferred to -server **192.168.0.1:8000** +```bash +cd PROJECT_PATH/build +cmake --build . --config Debug|Release +``` -```plaintext -ssfc[.exe] -D 9000 -b bounce.txt -c config.json -p 8000 192.168.0.1 +### Build SSF on Linux + +* Go in project directory + +```bash +cd PROJECT_PATH ``` -### Copy command line +* Copy [Boost archive](http://www.boost.org/users/download/) in ``third_party/boost`` -```plaintext -ssfcp[.exe] [-h] [-b bounce_file] [-c config_file] [-p port] [-t] [host@]path [[host@]path] +```bash +cp boost_1_XX_Y.tar.bz2 PROJECT_PATH/third_party/boost ``` -* -b : *bounce_file* is the file containing the list of relays to use. -* -c : *config_file* is the config file containing configuration for SSF (TLS configuration). -* -t : input from stdin +* Copy [OpenSSL archive](https://www.openssl.org/source/) in ``third_party/openssl`` -#### Copy from local to remote destination : +```bash +cp openssl-1.0.XY.tar.gz PROJECT_PATH/third_party/openssl +``` -```plaintext -ssfcp[.exe] [-b bounce_file] [-c config_file] [-p port] path/to/file host@absolute/path/directory_destination +* Copy [GTest archive](https://github.com/google/googletest/archive/release-1.7.0.zip) in ``third_party/gtest`` + +```bash +cp gtest-1.X.Y.zip PROJECT_PATH/third_party/gtest ``` -```plaintext -ssfcp[.exe] [-b bounce_file] [-c config_file] [-p port] path/to/file* host@absolute/path/directory_destination +* Generate project + +```bash +git submodule update --init --recursive +mkdir PROJECT_PATH/build +cd PROJECT_PATH/build +cmake -DCMAKE_BUILD_TYPE=Release|Debug -DSSF_SECURITY:STRING="STANDARD|FORCE_TCP_ONLY" ../ ``` -#### From stdin to remote destination +* Build project -```plaintext -data_in_stdin | ssfcp[.exe] [-b bounce_file] [-c config_file] [-p port] -t host@path/to/destination/file_destination +```bash +cd PROJECT_PATH/build +cmake --build . -- -j ``` -#### Copy remote files to local destination : +### Build SSF on Mac OS X -```plaintext -ssfcp[.exe] [-b bounce_file] [-c config_file] [-p port] remote_host@path/to/file absolute/path/directory_destination +* Go in project directory + +```bash +cd PROJECT_PATH ``` -```plaintext -ssfcp[.exe] [-b bounce_file] [-c config_file] [-p port] remote_host@path/to/file* absolute/path/directory_destination +* Copy [Boost archive](http://www.boost.org/users/download/) in ``third_party/boost`` + +```bash +cp boost_1_XX_Y.tar.bz2 PROJECT_PATH/third_party/boost ``` -### File example +* Copy [OpenSSL archive](https://www.openssl.org/source/) in ``third_party/openssl`` -#### Bounce file (relay servers) +```bash +cp openssl-1.0.XY.tar.gz PROJECT_PATH/third_party/openssl +``` -```plaintext -127.0.0.1:8002 -127.0.0.1:8003 +* Copy [GTest archive](https://github.com/google/googletest/archive/release-1.7.0.zip) in ``third_party/gtest`` + +```bash +cp gtest-1.X.Y.zip PROJECT_PATH/third_party/gtest ``` -#### Config file +* Generate project -```plaintext -{ - "ssf": { - "tls": { - "ca_cert_path": "./certs/trusted/ca.crt", - "cert_path": "./certs/certificate.crt", - "key_path": "./certs/private.key", - "dh_path": "./certs/dh4096.pem", - "cipher_alg": "DHE-RSA-AES256-GCM-SHA384" - }, - "http_proxy": { - "host": "proxy.example.com", - "port": "3128", - "credentials": { - "username": "user", - "password": "password", - "domain": "EXAMPLE.COM", - "reuse_ntlm": "true", - "reuse_kerb": "true" - } - }, - "services": { - "shell": { - "path": "/bin/bash", - "args": "" - } - } - } -} +```bash +git submodule update --init --recursive +mkdir PROJECT_PATH/build +cd PROJECT_PATH/build +cmake -DCMAKE_BUILD_TYPE=Release|Debug -DSSF_SECURITY:STRING="STANDARD|FORCE_TCP_ONLY" ../ ``` -* *tls.ca_cert_path* : relative or absolute path to the CA certificate file -* *tls.cert_path* : relative or absolute path to the instance certificate file -* *tls.key_path* : relative or absolute path to the private key file -* *tls.dh_path* : relative or absolute path to the Diffie-Hellman file -* *tls.cipher_alg* : cipher algorithm -* *http_proxy.host* : HTTP proxy host -* *http_proxy.port* : HTTP proxy port -* *http_proxy.credentials.username* : proxy username credentials (all platform: Basic or Digest, Windows: NTLM and Negotiate if reuse = false) -* *http_proxy.credentials.password* : proxy password credentials (all platform: Basic or Digest, Windows: NTLM and Negotiate if reuse = false) -* *http_proxy.credentials.domain* : user domain (NTLM and Negotiate auth on Windows only) -* *http_proxy.credentials.reuse_ntlm* : reuse current computer user credentials to authenticate with proxy NTLM auth (SSO) -* *http_proxy.credentials.reuse_kerb* : reuse current computer user credentials (Kerberos ticket) to authenticate with proxy Negotiate auth (SSO) -* *services.shell.path* : binary path used for shell creation (optional) -* *services.shell.args* : binary arguments used for shell creation (optional) +* Build project + +```bash +cd PROJECT_PATH/build +cmake --build . +```