With default options, the following files and folders should be in the directory of execution of a client or a server (see the Security features section if you do not know how to generate them):

• ./certs/dh4096.pem
• ./certs/certificate.crt
• ./certs/private.key
• ./certs/trusted/ca.crt

Where :

• dh4096.pem contains the Diffie-Hellman parameters needed for the establishment of session keys
• certificate.crt and private.key are the certificate and the private key of the SSF server or client
• ca.crt is the concatenated list of root certificates trusted by the SSF server or client

Moreover, a client will be able to connect to a server if two conditions are fulfilled:

• One of the certification authority which signed the server certificate is present in the trusted list of the client
• One of the certification authority which signed the client certificate is present in the trusted list of the server

In order to customize the paths and file names, the command line accepts a configuration file option -c.
An example is given below.

The configuration file is JSON format file in which several options can be specified. At this point, only security options relative to TLS use can be customized. See below an example of configuration file. For more information about TLS and SSF security see the Security features section.

{
  "ssf": {
    "arguments": "",
    "circuit": [],
    "tls" : {
      "ca_cert_path": "./certs/trusted/ca.crt",
      "cert_path": "./certs/certificate.crt",
      "key_path": "./certs/private.key",
      "key_password": "",
      "dh_path": "./certs/dh4096.pem",
      "cipher_alg": "DHE-RSA-AES256-GCM-SHA384"
    },
    "http_proxy" : {
      "host": "",
      "port": "",
      "user_agent": "",
      "credentials": {
        "username": "",
        "password": "",
        "domain": "",
        "reuse_ntlm": "true",
        "reuse_nego": "true"
      }
    },
    "services": {
      "datagram_forwarder": { "enable": true },
      "datagram_listener": {
        "enable": true,
        "gateway_ports": false
      },
      "stream_forwarder": { "enable": true },
      "stream_listener": {
        "enable": true,
        "gateway_ports": false
      },
      "copy": { "enable": false },
      "shell": {
        "enable": false,
        "path": "/bin/bash|C:\\windows\\system32\\cmd.exe",
        "args": ""
      },
      "socks": { "enable": true }
    }
  }
}

arguments

use configuration arguments instead of given CLI arguments

circuit

relay chain servers used to establish the connection to the remote server

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.key_password

the password protecting the private key (if any)

tls.dh_path

relative or absolute path to the Diffie-Hellman file

tls.cipher_alg

List of allowed SSL cipher suite (see OpenSSL documentation for more information)

http_proxy.host

HTTP proxy host

http_proxy.port

HTTP proxy port

http_proxy.user_agent

User agent in CONNECT request

http_proxy.credentials.username

proxy username credentials

http_proxy.credentials.password

proxy password credentials

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.*.enable

enable/disable local microservice

services.*.gateway_ports

enable/disable gateway ports

services.shell.path

binary path used for process creation

services.shell.args

binary arguments used for process creation

SSF is using microservices to build its features (TCP forwarding, remote SOCKS, ...) There are 7 microservices:

• stream_forwarder
• stream_listener
• datagram_forwarder
• datagram_listener
• copy
• socks
• shell

This architecture makes it easier to build remote features: they use the same microservices but on the opposite side.
ssf and ssfd come with pre-enabled microservices. Here is the default microservices configuration:

"ssf": {
  "services": {
    "datagram_forwarder": { "enable": true },
    "datagram_listener": { "enable": true },
    "stream_forwarder": { "enable": true },
    "stream_listener": { "enable": true },
    "socks": { "enable": true },
    "copy": { "enable": false },
    "shell": { "enable": false }
  }
}

To enable or disable a microservice, set its enable option to true or false.
Trying to use a feature requiring a disabled microservice will result in an error message.

Client command line

  ssf[.exe] [OPTION...] server_address

  -h, --help                    Show help message
  -v, --verbosity arg           Verbosity:
                                critical|error|warning|info|debug|trace (default: info)
  -q, --quiet                   Do not print logs
  -c, --config arg              Specify configuration file. If not set,
                                'config.json' is loaded from the current working
                                directory
  -p, --port arg                Remote port (default: 8011)
  -m, --max-connect-attempts arg
                                Max unsuccessful connection attempts before
                                stopping (default: 1)
  -t, --reconnect-delay arg     Time to wait before attempting to reconnect
                                (default: 60)
  -n, --no-reconnect            Do not attempt to reconnect after loosing a
                                connection
  -g, --gateway-ports           Enable gateway ports
  -S, --status                  Display microservices status

 Services options:
  -Y, --remote-shell [bind_address:]port
                                Enable remote shell service
  -F, --remote-socks [bind_address:]port
                                Enable remote SOCKS service
  -R, --remote-tcp-forward [bind_address:]port:remote_host:remote_port
                                Enable remote TCP port forwarding service
  -V, --remote-udp-forward [bind_address:]port:remote_host:remote_port
                                Enable remote UDP port forwarding service
  -X, --shell [bind_address:]port
                                Enable client shell service
  -D, --socks [bind_address:]port
                                Enable client SOCKS service
  -L, --tcp-forward [bind_address:]port:remote_host:remote_port
                                Enable client TCP port forwarding service
  -U, --udp-forward [bind_address:]port:remote_host:remote_port
                                Enable client UDP port forwarding service

Server command line

  ssfd[.exe] [OPTION...]

  -h, --help              Show help message
  -v, --verbosity arg     Verbosity: critical|error|warning|info|debug|trace
                          (default: info)
  -q, --quiet             Do not print logs
  -c, --config arg        Specify configuration file. If not set,
                          'config.json' is loaded from the current working directory
  -p, --port arg          Local port (default: 8011)
  -R, --relay-only        The server will only relay connections
  -l, --bind-address arg  Server bind address
  -g, --gateway-ports     Enable gateway ports
  -S, --status            Display microservices status

Examples

./ssfd

./ssf -D 10000 127.0.0.1

Copy command line options

  ssfcp[.exe] [options] [host@]/absolute/path/file [[host@]/absolute/path/file]

  -h, --help           Show help message
  -v, --verbosity arg  Verbosity: critical|error|warning|info|debug|trace
                       (default: info)
  -q, --quiet          Do not print logs
  -c, --config arg     Specify configuration file. If not set, 'config.json'
                       is loaded from the current working directory
  -p, --port arg       Remote port (default: 8011)

 Copy options:
  -t, --stdin-input        Use stdin as input
      --resume             Attempt to resume operation if the destination
                           file exists
      --check-integrity    Check file integrity
  -r, --recursive          Copy files recursively
      --max-transfers arg  Max transfers in parallel (default: 1)

Examples

ssfcp /tmp/test.txt 10.0.0.1@D:/test

ssfcp /tmp/test*.txt 10.0.0.1@D:/test

tar cf - /tmp/test | ssfcp -t 10.0.0.1@D:/test/test.tar

ssfcp 10.0.0.1@D:\test\test.txt /tmp

ssfcp 10.0.0.1@D:/test/test*.txt /tmp

The circuit is a JSON array containing the circuit servers and ports which will be used to establish the connection. They are listed as follow:

{
  "ssf": {
    "circuit": [
      {"host": "SERVER1", "port":"PORT1"},
      {"host": "SERVER2", "port":"PORT2"},
      {"host": "SERVER3", "port":"PORT3"}
    ]
  }
}

For the configuration above, the relay chain will be CLIENT <-> SERVER1:PORT1 <-> SERVER2:PORT2 <-> SERVER3:PORT3 <-> DESTINATION

In this example, a client located in the 10.0.1.* subnet wants to connect to the SSF server on 10.0.6.1:5000. However for this example, firewalls will only allow each subnet to communicate with the next one through a single address. For instance, in a subnet A.B.C.*, only A.B.C.1 can communicate with A.B.C-1.* and A.B.C+1.*. Therefore, to reach 10.0.6.1, the client has to go through 10.0.1.1, 10.0.2.1, ... and 10.0.6.1.

• It is expected that a server is running on each of the six addresses on port 5000 using a command line similar to:

  ./ssfd -p 5000

• Use the following configuration file config.json:

  {
    "ssf": {
      "circuit": [
        {"host": "10.0.1.1", "port":"5000"},
        {"host": "10.0.2.1", "port":"5000"},
        {"host": "10.0.3.1", "port":"5000"},
        {"host": "10.0.4.1", "port":"5000"},
        {"host": "10.0.5.1", "port":"5000"}
      ]
    }
  }

• Connect the client to 10.0.6.1:5000 through all the relay servers using the following command line:

  ./ssf -c config.json -p 5000 10.0.6.1

The SSF client -D port option opens the given port on the SSF client machine and forward SOCKS requests to the SSF target server.
The SSF server will act as the SOCKS server.

The SSF client -F port option opens the given port on the SSF target server machine and forward SOCKS requests to the SSF client.
The SSF client will act as the SOCKS server.

No circuit feature

With circuit feature

• Launch the SSF server on a port (10000 in this example)

  ./ssfd -p 10000

• Connect the SSF client to the SSF server

  ./ssf -L 9000:127.0.0.1:80 -p 10000 127.0.0.1

  Use -R instead of -L to forward to the the SSF client side and open the port 9000 on the SSF server side

• Launch SSF_SERVER_1 on a port (10000 in this example)

  ./ssfd -p 10000

• Launch SSF_SERVER_2 on a port (10001 in this example)

  ./ssfd -p 10001

• Create the configuration file config.json

  {
    "ssf": {
      "circuit": [
        {"host": "127.0.0.1", "port":"10000"}
      }
    }
  }
  

  The SSF client will connect to SSF_SERVER_2 with one hop on SSF_SERVER_1

• ./ssf -c config.json -L 9000:127.0.0.1:80 -p 10001 127.0.0.1

  Use -R instead of -L to forward to the SSF client side and open the port 9000 on the SSF_SERVER_2 side

• Launch the SSF server on a port (10000 in this example)

  ./ssfd -p 10000

• Connect the SSF client to the SSF server

  ./ssf -U 9000:127.0.0.1:80 -p 10000 127.0.0.1

  Use -V instead of -U to forward to the SSF client side and open the port 9000 on the SSF server side

• Launch SSF_SERVER_1 on a port (10000 in this example)

  ./ssfd -p 10000

• Launch SSF_SERVER_2 on a port (10001 in this example)

  ./ssfd -p 10001

• Create the configuration config.json

  {
    "ssf": {
      "circuit": [
        {"host": "127.0.0.1", "port":"10000"}
      }
    }
  }
  

  The SSF client will connect to SSF_SERVER_2 with one hop on SSF_SERVER_1

• ./ssf -c config.json -U 9000:127.0.0.1:80 -p 10001 127.0.0.1

  Use -V instead of -U to forward to the SSF client side and open the port 9000 on the SSF_SERVER_2 side

• Launch server on ssf.example.com

  ./ssfd

• Connect client to server

  ./ssf -X 10000 -Y 11000 ssf.example.com

  -X: client opens a listening socket on the given port (10000). Each connection to that socket (using netcat for example) will launch a shell on the server side.
  -Y: client orders the server to open a listening socket on the given port (11000). Each connection to that socket (using netcat for example) will launch a shell on the client side.
  I/O are forwarded through the SSF tunnel from/to the shell instance.
• You need to take into consideration some issues such as double echoing (both client and server display your input) or control command interpretation. We will provide a better way to handle this in a future version.
  Here are some workarounds according to your use case:
  • Interact with Linux or OS X shell: if you are using netcat in bash, you must change some options of the current terminal device with stty before establishing a connection:

    stty -echo -icanon -isig min 1

    -echo

    disable local echo

    -icanon

    disable canonical input

    -isig

    disable checking of special control characters (e.g. CTRL+C, CTRL+D)

    min 1

    read and process one character at a time

    All special interpretations will be done by the remote shell (TAB, CTRL+C, CTRL+D, etc.). After use, do not forget to reactivate terminal options device. Here is a oneliner:

    stty -echo -icanon -isig min 1; nc 127.0.0.1 10000; stty echo icanon isig;

  • Interact with Windows shell: if you are using netcat in bash, you can disable checking of control characters. Special characters sequence (TAB, UP, etc.) are disabled. We are still looking for a solution for setting the character input mode. Input will be processed one line at a time and you will notice double echoing.

    stty -isig; nc 127.0.0.1 10000; stty isig;

    If you are facing encoding issue (e.g. occidental accent), you may set your terminal encoding as Occidental (IBM850) on Ubuntu or Western (DOS Latin1) on OS X.

Here is a configuration file example for setting Powershell as the default shell on Windows platform:

{
    "ssf": {
        "services": {
            "shell": {
                "enable": true,
                "path": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
                "args": "-File -"
            }
        }
    }
}

ssf.services.shell.enable

true to activate local shell microservice

ssf.services.shell.path

Powershell binary path. Modify the path according to your system.

ssf.services.shell.args

Powershell binary arguments. -File - is required for redirecting SSF I/O to stdin/stdout Powershell process.

Client or server must be run as superuser

login can be used to login user on connection. Here is an example for setting it instead of /bin/bash:

{
    "ssf": {
        "services": {
            "shell": {
                "enable": true,
                "path": "/bin/login"
            }
        }
    }
}

ssf.services.shell.path

Login binary path. Modify the path according to your system (e.g. /bin/login on Ubuntu/Debian, /usr/bin/login on OS X).

Command line

ssfcp[.exe] [-c config_file] [-p port] [-t] [-r] [--resume] [--check-integrity] [--max-transfers arg] [host@]/absolute/path/file [[host@]/absolute/path/file]

From Linux to Linux

ssfcp /home/doe/test.txt 10.0.0.1@/tmp/test_dir

ssfcp /home/doe/*.txt 10.0.0.1@/tmp/test_dir

tar cf - /tmp/test | ssfcp 10.0.0.1@/tmp/test_dir/test.tar

ssfcp 10.0.0.1@/home/doe/test.txt /tmp/test_dir

From Windows to Linux

ssfcp.exe D:/test.txt 10.0.0.1@/tmp/test_dir

ssfcp.exe D:/test.txt 10.0.0.1@/tmp/test_dir

tar.exe cf - D:/test | ssfcp.exe 10.0.0.1@/tmp/test_dir/test.tar

ssfcp 10.0.0.1@D:/test.txt /tmp/test_dir

From Windows to Windows

ssfcp.exe D:/test.txt 10.0.0.1@E:/test_dir

ssfcp.exe D:/*.txt 10.0.0.1@E:/test_dir

tar.exe cf - D:/test | ssfcp.exe 10.0.0.1@E:/test_dir/test.tar

ssfcp.exe 10.0.0.1@D:/test.txt E:/test_dir

and you are connected to its wifi network. You do not trust this connection or don't want the hotel's proxy / router or guy next to you to know what web page you visit.

You will need two things:

• the server side: running, connected to Internet (for example, your home machine, running Windows, or Linux, or Mac)
• the client side: running on your laptop when you want to browse Internet while being locally connected to an untrusted network (e.g. public wifi networks)

Configuring the server side (e.g. your home machine, up and running, connected to internet, even when you are not at home)

./ssfd -p port 10000

Configuring the client side (e.g. your laptop): the simple way

./ssf -D 9000 -p 10000 SERVER_IP

Advanced : Secure DNS resolution

./ssf -D 9000 -U 53:208.67.222.222:53 -p 10000 SERVER_IP

Coffee shop firewall restrictions

SSF is based on Boost.Asio for all its networking and it uses Asio wrapper for OpenSSL. TLS connections support only certificate authentication and enforce mutual authentication.

TLS options

TLS cipher suggestions

Cryptographic suggestions

openssl rsa -in private.key -out private.key -aes256 -passout pass:passphrase

openssl rsa -in private.key -out private.key -aes256 -passin pass:passphrase -passout pass:new_passphrase

openssl rsa -in private.key -out private.key -passin pass:passphrase

Generate elements for TLS connections

openssl dhparam 4096 -outform PEM -out dh4096.pem

openssl req -x509 -nodes -newkey rsa:4096 -keyout ca.key -out ca.crt -days 3650

[ v3_req_p ]
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment

[ v3_ca_p ]
basicConstraints = CA:TRUE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment, keyCertSign

openssl req -newkey rsa:4096 -nodes -keyout ca_int.key -out ca_int.csr

openssl x509 -extfile extfile.txt -extensions v3_ca_p -req -sha1 -days 3650 -CA ca.crt -CAkey ca.key -CAcreateserial -in ca_int.csr -out ca_int.crt
cat ca.crt >> ca_int.crt

openssl req -newkey rsa:4096 -nodes -keyout private.key -out certificate.csr

openssl x509 -extfile extfile.txt -extensions v3_req_p -req -sha1 -days 3650 -CA ca.crt -CAkey ca.key -CAcreateserial -in certificate.csr -out certificate.crt
cat ca.crt >> certificate.crt

SSF is implemented using C++11 to support a wider range of standard compilers (e.g. Visual Studio 2015, g++-4.9 for Ubuntu 16.04). As soon as C++14, and later C++17 are easily accessible (native/default) on every build platforms, the code will be updated to evolve with these standards.

SSF relies on the Boost libraries, especially Asio, and was designed to be extended. A special effort was made to ease the build process: CMake is used to generate any dev environment (ex: Visual Studio, XCode, Make...). The building process for third party libraries (Boost, OpenSSL, GoogleTest) is made easy with custom scripts. SSF also comes with a set of unit tests so that you can fork and tweak the code, and test your changes easily.

The features of SSF framework are designed as microservices, allowing an easy integration of new functionalities. Checkout the documentation to know how to add your own custom features. SSF networking is based on Boost.Asio and provide objects with an Asio compliant interface. This aspect will be extended in a near future to provide a wide network toolkit (still based on Asio) permitting to quickly and easily design complex network protocols and communications.

Do not hesitate to fork, emit requests or fill issues using GitHub.