sslTunnel document

sslTunnel is free software used to secure traffic running between a TCP client and server. It is designed to work as an SSL encryption wrapper, encrypting the messages using TLS/SSL and allowing for secure communication without changing the program running on either side of the TCP connection.

ssltunnel topological graph

Installation

Command line

Configuration file

# sslTunnel 2 configuration file.

# The user who starts ssltunnel must have read permissions to the file. The user set below to run
# ssltunnel does not need any permissions on this file. Usually use the root user to start the
# ssltunnel, so set the owner and group of the configuration file to the root user, and set its
# permissions to 400.
{

    # Specifies a user to run the service as, defaults to an empty string, indicating that the
    # current user is to be used. If the --foreground option isn't specified, ssltunnel will fork
    # a new process with the user after running, and then terminate the current process. The user
    # does not need to have any permissions on this configuration file, certificate files, and
    # certificate private key files.
    "user": "ssltunnel",

    # Specifies a group to run the service as, defaults to an empty string, indicating that the
    # group of user specified by "user" (it is not empty) or group of current user ("user" is set
    # to empty) is to be used. If the --foreground option isn't specified, ssltunnel will fork a
    # new process with the group after running, and then terminate the current process.
    "group": "ssltunnel",

    # The tunnel definitions
    "tunnels": [

        # First tunnel definition
        {

            # Listening settings:
            # - When used as a ssl tunnel server: Listen for ssl tunnel client connections.
            # - When used as a ssl tunnel client: Listen for connections from downstream application
            #   clients.
            "listen": {

                # Tunnel listening address (supports both IPv4 and IPv6 address, blank indicates all
                # IPv4 and IPv6 addresses. The square brackets are not needed for IPv6).
                "address": "127.0.0.1",

                # Tunnel listening port.
                "port": 4120,

                # Server certificates.
                # - When used as a ssl tunnel server: Specifies the server certificates in order
                #   to listen for encrypted incoming connection from ssltunnel client. If multiple
                #   domain names are allowed to be used to connect to the server, a certificate
                #   needs to be specified for each domain name (general domain name certificates
                #   and multiple domain names certificates can also be used).
                # - When used as a ssl tunnel client: Don't specify the server certificates in
                #   order to listen for unencrypted incoming connections from application clients.
                #   The remaining listening settings ("client-auth", "client-verify", "ca", and
                #   "custom") will be ignored.
                "certs": [

                    # First certificate.
                    {

                        # The path to the certificate file, or the path to the full certificate
                        # chain file (if it is a relative path, it is based on the directory where
                        # the configuration file is located). The user who starts ssltunnel must
                        # have read permissions to the file. The user set above to run ssltunnel
                        # does not need any permissions on this file.
                        "cert": "...",

                        # The private key file path (if it is a relative path, it is based on the
                        # directory where the configuration file is located). The user who starts
                        # ssltunnel must have read permissions to the file. The user set above to
                        # run ssltunnel does not need any permissions on this file. Usually use the
                        # root user to start the ssltunnel, so set the owner and group of the
                        # certificate private key file to the root user, and set its permissions to
                        # 400.
                        "key": "...",

                        # Specifies the pass phrase if the private key is encrypted，otherwise the
                        # user will be prompted for a pass phrase on starting the ssltunnel.
                        "passphrase": "..."

                    },

                    # Other certificates.
                    ...

                ],

                # Determines the server's policy for TLS client authentication.
                #  - no:       Indicates that no client certificate should be requested during the
                #              handshake, and if any certificates are sent they will not be
                #              verified.
                #  - request:  Indicates that a client certificate should be requested during the
                #              handshake, and that at handshake, but does not require that the
                #              client send any certificates.
                #  - any:      Indicates that a client certificate should be requested during the
                #              handshake, and that at least one certificate is required to be sent
                #              by the client, but that certificate is not required to be valid.
                #  - optional: Indicates that a client certificate should be requested during the
                #              handshake, but does not require that the client sends a certificate.
                #              If the client does send a certificate it is required to be valid.
                #  - required: Indicates that a client certificate should be requested during the
                #              handshake, and that at least one valid certificate is required to be
                #              sent by the client.
                "client-auth": "required",

                # Determines how the server verifies client certificates:
                #  - cert: Only verify the end-entity (leaf) client certificate against a
                #          certificate specified in "ca" below.
                #  - ca:   Verify the client certificate chain starting from the root CA certificate
                #          specified in "ca" below.
                "client-verify": "ca",

                # Certificate Authority files, specifies one or multiple certificates, to be used to
                # verify client certificates. If a relative path is used, it is based on the
                # directory where the configuration file is located. It's required if "client-auth"
                # above is set to "optional" or "verify". The user who starts ssltunnel must have
                # read permissions to these files. The user set above to run ssltunnel does not need
                # any permissions on these files.
                # - When "client-verify" above is set to "cert": Specifies all end-entity (leaf)
                #   client certificates here. Multiple certificate files can be specified, each file
                #   can contain multiple end-entity (leaf) client certificates.
                # - When "client-verify" above is set to "ca": Specifies the issuing certificate
                #   chain starting with the root CA certificate for all client certificates.
                #   Multiple certificate chain files can be specified.
                "ca": [

                    # First certificate file or certificate chain file.
                    "...",

                    # Other certificate file or certificate chain file.
                    ...

                ],

                # Optional custom configuration. See Custom Configuration.
                "custom": "MinVersion: tls1.2; CurvePreferences: X25519, P256; ..."

            },

            # Connection settings:
            # - When used as a ssl tunnel server: Connect to the upstream application server.
            # - When used as a ssl tunnel client: Connect to the ssl tunnel server.
            "connect": {

                # Destination address for connection. It can be an IP address (both IPv4 and IPv6
                # are supported, and the square brackets are not needed for IPv6.) or a domain name.
                # If the connection destination is TLS/SSL server, the domain name generally needs
                # to be specified here, otherwise a domain name needs to be specified in the
                # "server-name" below so that the server provides an appropriate certificate.
                "address": "domain.com",

                # Destination port for connection.
                "port": 3690,

                # Connection timeout (seconds), its default value is 10 seconds.
                "timeout": 10,

                # Specifies whether the connected server is an TLS/SSL encryption server. If it is
                # set to false, the remaining connect settings ("server-name", "certs",
                # "server-verify", "ca", and "custom") will be ignored.
                # - When used as a ssl tunnel server: Set to false in order to connect to the
                #   upstream application server.
                # - When used as a ssl tunnel client: Set to true in order to connect to the ssl
                #   tunnel server.
                "tls": true,

                # Specifies the server name indication extension sent by the client. the value of
                # "address" above will be used if it isn't set. It's required if the "address" is
                # set to a IP address, and it must match least one server certificate.
                "server-name": "domain.com",

                # Specify the client certificate if the server needs to verify the client
                # certificate.
                "certs": [

                    # First certificate.
                    {

                        # The path to the certificate file, or the path to the full certificate
                        # chain file (if it is a relative path, it is based on the directory where
                        # the configuration file is located). The user who starts ssltunnel must
                        # have read permissions to the file. The user set above to run ssltunnel
                        # does not need any permissions on this file.
                        "cert": "...",

                        # The private key file path (if it is a relative path, it is based on the
                        # directory where the configuration file is located). The user who starts
                        # ssltunnel must have read permissions to the file. The user set above to
                        # run ssltunnel does not need any permissions on this file. Usually use the
                        # root user to start the ssltunnel, so set the owner and group of the
                        # certificate private key file to the root user, and set its permissions to
                        # 400.
                        "key": "...",

                        # Specifies the pass phrase if the private key is encrypted，otherwise the
                        # user will be prompted for a pass phrase on starting the ssltunnel.
                        "passphrase": "..."

                    },

                    # Other certificates.
                    ...

                ],

                # Determines how the client verifies server certificate:
                #  - skip: Don't verify the server certificate, the setting "ca" below will be
                #          ignored.
                #  - cert: Only verify the end-entity (leaf) server certificate against a
                #          certificate specified in "ca" below.
                #  - ca:   Verify the server certificate chain starting from the root CA certificate
                #          specified in "ca" below.
                "server-verify": "ca",

                # Certificate Authority files, specifies one or multiple certificates, to be used
                # to verify server certificate. If a relative path is used, it is based on the
                # directory where the configuration file is located.
                # It's required if "server-verify" above is set to "cert" or "ca", if not specified,
                # the list of trusted root certificates embedded in the operating system is used.
                # The user who starts ssltunnel must have read permissions to these files. The user
                # set above to run ssltunnel does not need any permissions on these files.
                # - When "server-verify" above is set to "cert": Specifies the end-entity (leaf)
                #   server certificate here.
                # - When "server-verify" above is set to "ca": Specifies the issuing certificate
                #   chain starting with the root CA certificate for the server certificate.
                "ca": [

                    # First certificate file or certificate chain file.
                    "...",

                    # Other certificate file or certificate chain file.
                    ...

                ],

                # Optional custom configuration. See Custom Configuration.
                "custom": ""

            }

        },

        # Other tunnel definitions.
        ...

    ],

    # Log definition.
    "log": {

        # Log file, if a relative path is used, it is based on the directory where the configuration
        # file is located. The "stderr" or "stdout" can be used. The "%y", "%m", "%d" and "%w" can
        # be used in log file name in order to rotate log:
        # - %y: 4-digit calendar year (e.g., 2026)
        # - %m: 2-digit month with a leading zero (e.g., 01-12)
        # - %d: 2-digit day with a leading zero (e.g., 01-31)
        # - %w: 2-digit week of the year with a leading zero (e.g., 01-53)
        "file": "stderr",

        # Log level, determining which logs are written to a log file. When you set a specific log
        # level, it acts as a minimum threshold, meaning that level and all higher (more severe)
        # levels will be recorded, while everything below it is discarded or filtered out.
        # - 0: Fatal (highest/most severe)
        # - 1: Error
        # - 2: Warning
        # - 3: Information
        # - 4: Debug (lowest/most verbose)
        "level": 3,

        # Specify the rendering time zone for log entry timestamps, e.g., "+0800", "-0300". defaults
        # to an empty string, indicating that the local time zone to be used.
        "timezone": "+0000",

        # Log format, it defines the structure that each log entry will have, entailing what data
        # to include, the order of presentation, and the separation elements used. following "%"
        # directives can be used in the format string:
        # - %p: Descriptions of log level (fatal, error, warning, message, debug)
        # - %t{.....}: The timestamp for log entries. The string within the curly braces specifies
        #   the time format, utilizing the Go language's time formatting conventions (e.g.,
        #   "%t{2006-01-02 15:04:05}")
        # - %e: Specifies to present the error information (if any, it will be presented on a new
        #   line, starting from the column where %e is located)
        # - %m: Log message
        "format": "%p %e[%t{2006-01-02 15:04:05}] %m",

        # The logs maximum cache size dictates how how many log items an application can store in
        # temporary memory before it must write to log file.
        "max-cache": 10,

        # Specifies whether to compress old log file to save space (in gzip format) when rotate
        # log.
        "compress": true,

        # Specifies the language of log message (e.g., "en-us", "zh-cn"), defaults to an empty
        # string, indicating that the value of "--language" option from the command line is to be
        # used.
        "language": ""

    }

}

Custom configuration

In the configuration file, you can optionally specify custom configurations for each tunnel's listening settings and connection settings separately. The custom configuration value is a string that can contain multiple setting items separated by semicolons. Each setting item includes a name and a value separated by colons. For example:

"custom": "MinVersion: tls1.2; CipherSuites: RSA-RC4_128_SHA,ECDHE_RSA-RC4_128_SHA; CurvePreferences: P256; SessionTicketsDisabled: true"

Available setting items include:

  1. Support/
  2. sslTunnel documents

macSvn

Support

Policy