SSH Tectia

ssh-broker-config

ssh-broker-config — SSH Connection Broker configuration file format

The Connection Broker configuration file ssh-broker-config.xml is a valid XML file.

The Connection Broker reads three configuration files (if all are available):

  1. The ssh-broker-config-default.xml file is read first. It holds the factory default settings. It is not recommended to edit the file, but you can use it to view the default settings.

    This file must be available and correctly formatted for the Connection Broker to start.

  2. Next, the Connection Broker reads the global configuration file. The settings in the global configuration file override the default settings.

    If the global configuration file is missing or malformed, the Connection Broker will start normally. A malformed global configuration file is ignored and the default settings are used instead.

  3. Last, the Connection Broker reads the user-specific configuration file, if it is available. The settings in the user-specific configuration file override the settings in the global configuration file, with the following exceptions:

    • The following settings from the user-specific configuration are combined with the settings of the global configuration file:

      • In general element, the key-stores and cert-validation settings

      • In profiles element, all settings

      • In static-tunnels element, all settings.

    • If a connection profile with the same name has been defined in both the global configuration file and user-specific configuration file, the latter one is used.

    • If the crypto-lib, strict-host-key-checking, host-key-always-ask, and accept-unknown-host-keys elements have different values in the global and user-specific configuration, the more secure of these values is used.

    If the user-specific configuration file is missing, the Connection Broker will start using the previously read configuration files. However, if a user-specific configuration exists but is malformed, the Connection Broker will not start.

On Unix, the default configuration file locations are:

On Windows, the default configuration file locations are:

This section describes the options available in the Connection Broker configuration file. See Appendix D for more information on the syntax of the configuration file.

Document Type Declaration and the Root Element

The broker configuration file is a valid XML file and starts with the Document Type Declaration.

The root element in the configuration file is secsh-broker. It can include general, default-settings, profiles, static-tunnels, gui, filter-engine, and logging elements.

An example of an empty configuration file is shown below:

<!DOCTYPE secsh-broker SYSTEM "ssh-broker-ng-config-1.dtd">
<secsh-broker version="1.0">

  <general />
  <default-settings />
  <profiles />
  <static-tunnels />
  <gui />
  <filter-engine /> 
  <logging />

</secsh-broker>

The gui element is used with SSH Tectia Connector only. The filter-engine element is used with SSH Tectia Client with EFT Expansion Pack and SSH Tectia Connector.

The general Element

The general element contains settings such as the cryptographic library and the key stores to be used.

crypto-lib

This element selects the cryptographic library mode to be used. Either the standard version (standard) or the FIPS 140-2 certified version (fips) of the crypto library can be used. The library name is given as a value of the mode attribute. By default, standard crypto libraries are used.

FIPS mode will be used, if it is so specified either in global or in user configuration file (or both).

<crypto-lib mode="standard" />

In the FIPS mode, the cryptographic operations are performed according to the rules of the FIPS 140-2 standard. The FIPS library includes the 3des-cbc, aes128-cbc, aes192-cbc, and aes256-cbc ciphers and the hmac-sha1 MAC.

[Note]Note

Setting the FIPS mode does not prevent using algorithms from crypto plugins. For example, CryptiCore can be used even when the main crypto library is set in the FIPS mode. To enforce that only FIPS-compliant algorithms are used, disable the non-FIPS algorithms from the configuration. See cipher and mac.

For a list of platforms on which the FIPS library has been validated or tested, see SSH Tectia Client/Server Product Description.

cert-validation

This element defines public-key infrastructure (PKI) settings used for validating remote server authentication certificates. The element can have three attributes: end-point-identity-check, default-domain, http-proxy-url, and socks-server-url.

The end-point-identity-check attribute specifies whether the client will verify the server's hostname against the Subject Name or Subject Alternative Name (DNS Address) in the server's certificate. If set to no, the fields in the server host certificate are not verified and the certificate is accepted based on validity period and CRL check only. Note that this is a possible security risk, as anyone with a certificate issued by the same trusted CA that issues the server host certificates can perform a man-in-the-middle attack on the server if a client has the end-point identity check disabled. The default value is yes.

The default-domain attribute can be used when the end-point identity check is enabled. It specifies the default domain part of the remote system name and it is used if only the base part of the system name is available. The default-domain is appended to the system name if it does not contain a dot (.).

If the default domain is not specified, the end-point identity check fails, for example, when a user tries to connect to a host "rock" giving only the short hostname and the certificate contains the full DNS address "rock.example.com".

The http-proxy-url attribute defines an HTTP proxy and the socks-server-url attribute defines a SOCKS proxy for making LDAP or OCSP queries for certificate validity.

The address of the proxy is given as the value of the attribute. The format of the address is socks://username@socks_server:port/network/netmask,network/netmask ... (with a SOCKS proxy) or http://username@proxy_server:port/network/netmask,network/netmask ... (with an HTTP proxy).

For example, to make the SOCKS server use host socks.ssh.com and port 1080 for connections outside of networks 192.196.0.0 (16-bit domain) and 10.100.23.0 (8-bit domain), and to get these networks connected directly, set socks-server-url as follows:

"socks://mylogin@socks.ssh.com:1080/192.196.0.0/16,10.100.23.0/24"

The cert-validation element can contain multiple ldap-server, ocsp-responder, and crl-prefetch elements, a dod-pki element, and multiple ca-certificate elements.

ldap-server

This element specifies an LDAP server address and port used for fetching CRLs and/or subordinate CA certificates based on the issuer name of the certificate being validated. Several LDAP servers can be specified by using several ldap-server elements.

CRLs are automatically retrieved from the CRL distribution point defined in the certificate to be verified if the point exists.

The default value for port is 389.

ocsp-responder

This element specifies an OCSP (Online Certificate Status Protocol) responder service address in URL format (url). Several OCSP responders can be specified by using several ocsp-responder elements.

If the certificate has a valid Authority Info Access extension with an OCSP Responder URL, it will be used instead of this setting. Note that for the OCSP validation to succeed, both the end-entity certificate and the OCSP Responder certificate must be issued by the same CA.

The validity-period (in seconds) can be optionally defined. During this time, new OCSP queries for the same certificate are not made but the old result is used. The default validity period is 0 (a new query is made every time).

crl-prefetch

This element instructs SSH Tectia Client to periodically download a CRL from the specified url. The url can be an LDAP or HTTP URL, or it can refer to a local file. The file format must be either binary DER or base64, PEM is not supported.

To download CRLs from the local file system, define the file URL in this format:

file:///absolute/path/name

To download CRLs from an LDAP server, define the LDAP URL in this format:

ldap://ldap.server.com:389/CN=Root%20CA,OU=certification%20authorities,
DC=company,DC=com?certificaterevocationlist

Use the interval attribute to specify how often the CRL is downloaded. The default is 3600 (seconds).

dod-pki

This element defines whether the certificates are required to be compliant with the DoD PKI (US Department of Defense Public-Key Infrastructure). In practise, this means that the Digital Signature bit must be set in the Key Usage of the certificate. The enable attribute can have a value of yes or no. The default is no.

ca-certificate

This element defines a CA used in server authentication. It can have four attributes: name, file, disable-crls, and use-expired-crls.

The name attribute must contain the name of the CA.

The element must either contain the path to the X.509 CA certificate file as a value of the file attribute, or include the certificate as a base64-encoded ASCII block.

CRL checking can be disabled by setting the disable-crls attribute to yes. The default is no.

Expired CRLs can be used by setting a numeric value (in seconds) for the use-expired-crls attribute. The default is 0 (do not use expired CRLs).

An example of a certificate validation configuration is shown below:

<cert-validation end-point-identity-check="yes" 
                 default-domain="example.com"
                 http-proxy-url="http://proxy.example.com:8080">
  <ldap-server address="ldap://ldap.example.com:389" />
  <ocsp-responder url="http://ocsp.example.com:8090" validity-period="0" /> 
  <crl-prefetch url="file:///full.path.to.crlfile" interval="1800"/>
  <dod-pki enable="no" />
  <ca-certificate name="ssh_ca1"
                  file="ssh_ca1.crt"
                  disable-crls="no"
                  use-expired-crls="100" />
</cert-validation>         
key-stores

There can be one <key-stores> instance under the <general> element. It can have any amount of <key-store> elements each of which configures one key store provider.

key-store

The key-store element has two attributes: type and init. The type attribute is the key store type. Currently supported types are "software", "mscapi", "entrust", and "pkcs11". The init attribute is the key-store-provider-specific initialization info.

See the section called “Key Store Configuration Examples” for key store configuration examples.

strict-host-key-checking

This element enables strict host key checking. If it is enabled, the Connection Broker never adds host keys to the user's .ssh2/hostkeys directory upon connection, and refuses to connect to hosts whose key has changed. This provides maximum protection against man-in-the-middle attacks. However, it can be somewhat annoying if you frequently connect to new hosts.

The word yes or no is given as the value of the enable attribute. The default is no (the user is asked whether to accept a new or changed host key).

Strict host key checking will be used, if it is so specified in either the global or the user configuration file (or both).

<strict-host-key-checking enable="yes" />
host-key-always-ask

This element defines whether the Connection Broker should prompt the user to accept the proposed host key even if it is already known.

The word yes or no is given as the value of the enable attribute. The default is no (known host keys are accepted without prompting).

Host keys are always asked, if it is so specified in either the global or the user configuration file (or both).

<host-key-always-ask enable="yes" />
accept-unknown-host-keys

This element defines whether the Connection Broker will always accept the proposed host key without saving the key. It is the equivalent of automatically answering "Once" to all accept-host-key prompts.

The word yes or no is given as the value of the enable attribute. The default is no (unknown host keys are not automatically accepted).

If this element is set to no either in the global or the user configuration file, the changed or new host keys are prompted normally. Additionally, setting this element to yes takes effect only when both strict-host-key-checking and host-key-always-ask are set to no (or are not explicitly defined).

<accept-unknown-host-keys enable="no" />
[Caution]Caution

Consider carefully before enabling this option. Disabling the host-key checks can make you vulnerable to a man-in-the-middle attack.

known-hosts

This element specifies the location of an OpenSSH-style known-hosts file that contains the public key data of known server hosts. The full path to the known_hosts file must be given as a value of the path attribute.

<known-hosts path="/u/username/.ssh/known_hosts" />

The hostname(s) in the file must be in clear-text format. Hashed hostnames are not supported.

Key Store Configuration Examples

Software provider

The software provider handles key pairs stored on disk in standard Secure Shell v2 or legacy OpenSSH formats and X.509 certificates stored in native X.509, PKCS#7, and PKCS#12 formats.

To add a single key file (for example, /u/exa/keys/enigma and /etc/my_key), specify both the private key file and the public key file:

<key-stores>
  <key-store type="software" 
             init="key_files(/u/exa/keys/enigma.pub,/u/exa/keys/enigma)" />
  <key-store type="software" 
             init="key_files(/etc/my_key.pub,/etc/my_key)" />
</key-stores>

To add all keys from a specific directory (for example all keys from /u/exa/keys and /etc/keys):

<key-stores>
  <key-store type="software" 
             init="directory(path(/u/exa/keys))" />
  <key-store type="software" 
             init="directory(path(/etc/keys))" />
</key-stores>

Entrust provider

The Entrust provider handles keys and certificates stored in the proprietary Entrust format.

You should provide the initialization file and the profile specific file for the Entrust provider. For example:

<key-stores>
  <key-store type="entrust" 
             init="ini-file(/etc/entrust.ini),profile-file(/etc/profile.epf)" />
</key-stores>

PKCS#11 provider

The PKCS#11 provider handles keys and certificates stored in PKCS#11 tokens (for example, smart cards or USB tokens).

Specify the dynamic library path for the PKCS provider and all or a specific slot. For example, with all slots:

<key-stores>
  <key-store type="pkcs11" init="dll(/usr/lib/pkcs.so),slots(all)" />
</key-stores>

For example, with one slot named sesam:

<key-stores>
  <key-store type="pkcs11" init="dll(/usr/local/lib/pkcs.so),slots(sesam)" />
</key-stores>

The default-settings Element

The default-settings element defines the default connection-related settings. Profile-specific settings can override these settings.

ciphers

This element defines the ciphers that the client will propose to the server. The ciphers element can contain multiple cipher elements.

The ciphers are tried in the order they are specified.

cipher

This element selects a cipher name that the client requests for data encryption.

The supported ciphers are 3des-cbc, aes128-cbc, aes192-cbc, aes256-cbc, arcfour, blowfish-cbc, twofish-cbc, twofish128-cbc, twofish192-cbc, twofish256-cbc, crypticore128@ssh.com, seed-cbc@ssh.com, and none (no encryption).

The default ciphers used by the Connection Broker are, in order: crypticore128@ssh.com (on Windows and Linux x86), aes128-cbc, aes192-cbc, aes256-cbc, 3des, and seed-cbc@ssh.com.

The ciphers that can operate in the FIPS mode are aes128-cbc, aes192-cbc, aes256-cbc, and 3des-cbc.

<ciphers>
  <cipher name="crypticore128@ssh.com" />
  <cipher name="aes128-cbc" />
</ciphers>
macs

This element defines the MACs that the client will propose to the server. The macs element can contain multiple mac elements.

The MACs are tried in the order they are specified.

mac

This element selects a MAC name that the client requests for data integrity verification.

The supported MAC algorithms are hmac-md5, hmac-md5-96, hmac-sha1, hmac-sha1-96, crypticore-mac@ssh.com, and none (no data integrity verification).

The default MACs used by the Connection Broker are, in order: crypticore-mac@ssh.com (on Windows and Linux x86), hmac-md5, and hmac-sha1.

The hmac-sha1 algorithm can operate in the FIPS mode.

<macs>
  <mac name="hmac-sha1" />
</macs>
transport-distribution

This setting defines the number of transport channels used by the Secure Shell connection. Using more than one transport may increase the throughput over low bandwidth connections.

The number of transports is given as value of the num-transports attribute. Currently, a value of 1 to 8 transports is supported. On Unix, the default is 1 transport. On Windows, the default is 2 transports.

<transport-distribution num-transports="1" />
rekey

This element specifies the number of transferred bytes after which the key exchange is done again. The value "0" turns rekey requests off. This does not prevent the server from requesting rekeys, however. The default is 1000000000 (1 GB).

<rekey bytes="1000000000" />
authentication-methods

This element specifies the authentication methods that are requested by the client. The authentication-methods element can contain multiple authentication-method elements.

The authentication methods are tried in the order of the authentication-method elements. This means that the least interactive methods should be placed first.

authentication-method

This element specifies an authentication method name.

The allowed authentication method names are: gssapi-with-mic, publickey, keyboard-interactive, password, and hostbased.

SSH Tectia Client supports host-based authentication only on Unix platforms.

<authentication-methods>
  <authentication-method name="hostbased" />
  <authentication-method name="gssapi-with-mic" />
  <authentication-method name="publickey" />
  <authentication-method name="keyboard-interactive" />
  <authentication-method name="password" />
</authentication-methods>
hostbased-default-domain

This element specifies the host's default domain name (as name). This element is used to make sure the fully qualified domain name (FQDN) of the client host is transmitted to the server when using host-based user authentication.

The default domain name is appended to the short hostname before transmitting it to the server. This is needed because some platforms (Solaris for instance) use the short format of the hostname, and with that the signature cannot be created.

The allowed formats of the default domain names are: .example.com and example.com (without the leading dot). For example:

<hostbased-default-domain name=".example.com" />
compression

This element specifies whether to use compression.

The name of the compression algorithm and the compression level can be given as attributes. Currently only zlib is supported as the algorithm. The level can be an integer from 0 to 9. By default, compression is not used.

<compression name="none" />
proxy

This element defines rules for HTTP or SOCKS proxy servers the client will use for connections. It has a single attribute: ruleset.

The format of the attribute value is a sequence of rules delimited by semicolons (;). Each rule has a format that resembles the URL format. In a rule, the connection type is given first. The type can be direct, socks, socks4, socks5, or http-connect (socks is a synonym for socks4). This is followed by the server address and port. If the port is not given, the default ports 1080 for SOCKS and 80 for HTTP are used.

After the address, zero or more conditions delimited by commas (,) are given. The conditions can specify IP addresses or DNS names.

direct:///[cond[,cond]...]
socks://server/[cond[,cond]...]
socks4://server/[cond[,cond]...]
socks5://server/[cond[,cond]...]
http-connect://server/[cond[,cond]...]

The IP address/port conditions have an address pattern and an optional port range:

ip_pattern[:port_range]

The ip_pattern may have one of the following forms:

  • a single IP address x.x.x.x

  • an IP address range of the form x.x.x.x-y.y.y.y

  • an IP sub-network mask of the form x.x.x.x/y

The DNS name conditions consist of a hostname which may be a regular expression containing the characters "*" and "?" and a port range:

name_pattern[:port_range]

An example proxy element is shown below. It causes the server to access the callback address and the ssh.com domain directly, access *.example with HTTP CONNECT, and all other destinations with SOCKS4.

<proxy ruleset="direct:///127.0.0.0/8,*.ssh.com;
                http-connect://http-proxy.ssh.com:8080/*.example;
                socks://fw.ssh.com:1080/" />
idle-timeout

This element specifies how long idle time (after all connection channels are closed) is allowed for a connection before automatically closing the connection. The time is given in seconds.

The default setting is 5 seconds. Setting a longer time allows the connection to the server to remain open even after a session (for example, sshg3) is closed. During this time, a new session to the server can be initiated without re-authentication. Setting the time to 0 (zero) terminates the connection immediately when the last channel to the server is closed.

<idle-timeout time="5" />
server-banners

This element defines whether the server banner message file (if it exists) is visible to the user before login. The word yes or no is given as the value of the visible attribute. The default is yes.

<server-banners visible="no" />
forwards

This element contains forward elements that define whether X11 or agent forwarding (tunneling) are allowed on the client side.

forward

This element defines X11 or agent forwarding settings.

The type attribute defines the forwarding type (either x11 or agent). The state attribute sets the forwarding on, off, or denied. If the forwarding is set as denied, the user cannot enable it on the command-line.

An example forward configuration, which allows X11 forwarding and denies agent forwarding globally, is shown below:

<forwards>
  <forward type="x11" state="denied" />
  <forward type="agent" state="on" />
</forwards>

For more information on using X11 and agent forwarding, see X11 Forwarding and Agent Forwarding.

remote-environment

This element contains environment elements that define the environment variables to be passed to the server from the client side by default. The environment variables are then set on the server when requesting a command, shell or subsystem.

You can define the environment variables also for each connection profile. See remote-environment under the profiles element.

Note that the server can restrict the setting of environment variables.

environment

This element defines the name and value of the environment variables, and whether the Connection Broker should process the value. Possible attributes are name, value, and format.

An example remote environment configuration:

<remote-environment>
  <environment name="FOO" value="bar" />
  <environment name="QUX" value="%Ubaz" format="yes" />
  <environment name="ZAPPA" value="%Ubaz" />
</remote-environment>

You can use %U in the value to indicate a user name. When format="yes" is also defined, the Connection Broker processes the %U into the actual user name before sending it to the server.

Let's assume the user name is joedoe in this example. The example configuration results in the following environment variables on the server side, provided that the server allows setting the environment variables:

FOO=bar 
QUX=joedoebaz 
ZAPPA=%Ubaz 

You can override the remote environment settings made in the configuration file if you use the sshg3 command with the --remote-environment or --remote-environment-format arguments on the command-line client.

See --remote-environment name=value in the sshg3 description.

The profiles Element

The profiles element defines the connection profiles for connecting to different servers. It can contain multiple profile elements. Each profile defines the connection rules to one server.

profile

The profile element defines a connection profile. It has seven attributes: id, name, host, port, connect-on-startup, user, and gateway-profile.

The profile id must be a unique identifier that does not change during the lifetime of the profile.

An additional name can be given to the profile. This is a free-form text string. Define a unique name for each profile.

The host is a mandatory setting. The address can be either an IP address or a domain name. The value '*' can be used to prompt the user to enter the hostname when logging in. With the Connector, '%DESTINATION_HOSTNAME%' can be given as the hostname. Then the Connector will pick up the destination IP address from the tunneled application, and open a tunnel to the same host. This way it is no longer necessary to create a separate connection profile for each destination host.

The port is a mandatory setting. The default port is 22.

If you want to make the connection specified by the profile automatically at reboot, set the value of the connect-on-startup attribute to yes. In this case, give also the user attribute (the username the connection is made with). You also need to set up some form of non-interactive authentication for the connection.

In the user attribute, the value '%USERNAME%' can be used to set the user name to the current user. The value '*' can be used to prompt the user to enter the user name when loggin in.

The gateway-profile attribute can be used to create nested tunnels. The profile name through which the connection is made is given as the value of the attribute. The first tunnel is created using the gateway host profile and from there the second tunnel is created to the host defined in this profile.

hostkey

This element gives the path to the remote server host public key file as a value of the file attribute.

Alternatively, the public key can be included as a base64-encoded ASCII block.

ciphers

This element defines the ciphers used with this profile. See the section called “The default-settings Element”.

macs

This element defines the MACs used with this profile. See the section called “The default-settings Element”.

transport-distribution

This element defines the transport distribution for this profile. See the section called “The default-settings Element”.

rekey

This element defines the rekeying settings used with this profile. See the section called “The default-settings Element”.

authentication-methods

This element defines the authentication methods used with this profile. See the section called “The default-settings Element”.

compression

This element defines the compression settings used with this profile. See the section called “The default-settings Element”.

proxy

This element defines the proxy settings used with this profile. See the section called “The default-settings Element”.

If a gateway profile (gateway-profile) has been defined for this profile, the proxy setting is ignored and the default proxy setting or the proxy setting of the gateway profile is used.

idle-timeout

This element defines the idle timeout settings used with this profile. See the section called “The default-settings Element”.

server-banners

This element defines the server banner setting used with this profile. See the section called “The default-settings Element”.

forwards

This element defines the forwards allowed with this profile. See the section called “The default-settings Element”.

tunnels

The tunnels element defines the tunnels that are opened when a connection with this profile is made. The element can contain multiple local-tunnel and remote-tunnel elements.

local-tunnel

This element defines a local tunnel (port forwarding) that is opened automatically when a connection is made with the connection profile. It has five attributes: type, listen-port, dst-host, dst-port, and allow-relay.

This allocates a listener port (listen-port) on the local client. Whenever a connection is made to this listener, the connection is tunneled over Secure Shell to the remote server and another connection is made from the server to a specified destination host and port (dst-host, dst-port). The connection from the server onwards will not be secure, it is a normal TCP connection.

The type attribute defines the type of the tunnel. This can be tcp (default, no special processing), ftp (temporary forwarding is created for FTP data channels, effectively securing the whole FTP session), or socks (SSH Tectia Client will act as a SOCKS server for other applications, creating forwards as requested by the SOCKS transaction).

The listen-port attribute defines the local port to be listened. The dst-host and dst-port attributes define the destination host address and port. The value of dst-host can be either an IP address or a domain name. The default is 127.0.0.1 (localhost = server host).

The allow-relay attribute defines whether connections to the listened port are allowed from outside the client host. The default is no.

For more information on using local tunnels, see Local Tunnels.

remote-tunnel

This element defines a remote tunnel (port forwarding) that is opened automatically when a connection is made with the connection profile. It has four attributes: type, listen-port, dst-host, dst-port, and allow-relay.

This allocates a listener port (listen-port) on the remote server. Whenever a connection is made to this listener, the connection is tunneled over Secure Shell to the local client and another connection is made from the client to a specified destination host and port (dst-host, dst-port). The connection from the client onwards will not be secure, it is a normal TCP connection.

The type attribute defines the type of the tunnel. This can be either tcp (default, no special processing) or ftp (temporary forwarding is created for FTP data channels, effectively securing the whole FTP session).

The listen-port attribute defines the remote port to be listened. The dst-host and dst-port attributes define the destination host address and port. The value of dst-host can be either an IP address or a domain name. The default is 127.0.0.1 (localhost = client host).

The allow-relay attribute defines whether connections to the listened port are allowed from outside the server host. The default is no.

For more information on using remote tunnels, see Remote Tunnels.

remote-environment

This element defines the remote environment settings used with this profile. Within the remote-environment element, define an environment element for each environment variable to be passed to the server. For the values, see remote-environment under the default-settings element.

An example connection profile is shown below:

<profile name="rock"
         id="id1"
         host="rock.example.com"
         port="22"
         connect-on-startup="no"
         user="doct">

  <hostkey file="key_22_rock.pub">
  </hostkey>

  <authentication-methods>
    <authentication-method name="publickey" />
    <authentication-method name="password" />
  </authentication-methods>

  <server-banners visible="yes" />

  <forwards>
    <forward type="agent" state="on" />
    <forward type="x11" state="on" />
  </forwards>

  <tunnels>
    <local-tunnel type="tcp"
                  listen-port="143"
                  dst-host="imap.example.com"
                  dst-port="143"
                  allow-relay="no" />
  </tunnels>

  <remote-environment>
    <environment name="FOO" value="bar" />
    <environment name="QUX" value="%Ubaz" format="yes" />
    <environment name="ZAPPA" value="%Ubaz" />
  </remote-environment>

</profile>

The static-tunnels Element

With the static-tunnels setting, you can create listeners for local tunnels automatically when the Connection Broker starts up. The actual tunnel is formed the first time a connection is made to the listener port. If the connection to the server is not open at that time, it will be opened automatically as well.

The static-tunnels element can contain any number of tunnel elements.

tunnel

The tunnel element specifies a static tunnel. It has six attributes: type, listen-port, dst-host, dst-port, allow-relay, and profile.

The type attribute defines the type of the tunnel. This can be either tcp or ftp.

The listen-port attribute defines the local port to be listened. The dst-host and dst-port attributes define the destination host address and port. The value of dst-host can be either an IP address or a domain name. The default is 127.0.0.1 (localhost = server host).

The allow-relay attribute defines whether connections to the listened port are allowed from outside the client host. The default is no.

The profile attribute specifies the connection profile id that is used for the tunnel.

<static-tunnels>
  <tunnel type="tcp"
          listen-port="9000"
          dst-host="st.example.com"
          dst-port="9000"
          allow-relay="no"
          profile="id1" />
</static-tunnels>

The gui Element

The gui element contains only one element (gui), which is used to adjust the Connection Broker GUI settings. The gui element has five attributes: hide-tray-icon, show-exit-button, show-admin, enable-connector, and show-security-notification. All of these must have yes or no as the value. The last two settings have effect only if SSH Tectia Connector has been installed on the system.

The hide-tray-icon attribute controls whether the SSH Tectia tray icon is displayed in the system tray. The default is no (the tray icon is displayed).

The show-exit-button attribute controls whether the Exit command is displayed in the tray icon shortcut menu. The default is yes.

The show-admin attribute defines whether the Configuration command is displayed in the tray icon shortcut menu. The default is yes. If the button is not displayed, the SSH Tectia Configuration tool can be started by running ssh-tectia-configuration.exe, located by default in the "C:\Program Files\SSH Communications Security\SSH Tectia\SSH Tectia Broker" directory.

The enable-connector attribute defines whether SSH Tectia Connector (if present) is active and capturing connections. The default is yes.

The show-security-notification attribute defines whether the SSH Tectia Connector security notification is shown upon establishing a secure application tunnel. The default is yes.

<gui hide-tray-icon="no"
     show-exit-button="yes"
     show-admin="yes"
     enable-connector="yes"
     show-security-notification="yes" />

The filter-engine Element (EFT Expansion Pack , SSH Tectia Connector)

[Note]Note

The filter-engine element is read from the global configuration file, if such a file is available (SSH Tectia Client is controlled by the SSH Tectia Manager). On Unix, the global configuration is stored as /etc/ssh2/ssh-broker-config.xml, and on Windows as "C:\Program Files\SSH Communications Security\SSH Tectia\SSH Tectia Broker\ssh-broker-config.xml". Only when no global configuration file exists, this element is read in the user-specific configuration file.

The filter-engine element defines the SSH Tectia Connector filter rules and SSH Tectia Client (with EFT) FTP-SFTP conversion rules. These settings have no effect if only the basic SSH Tectia Client has been installed on the system.

The top level element is filter-engine. It has two attributes: ip-generate-start and ftp-filter-at-signs.

The ip-generate-start attribute defines the start address of the pseudo IP address space. Pseudo IPs are generated by the Connection Broker when applications do the DNS query through the SSH Capture DLL.

The ftp-filter-at-signs attribute defines that the @ sign is used to extract the FTP user name, FTP server name, and the FTP server password from a string used also when connecting to an FTP server via a proxy. This is needed when FTP-SFTP conversion is used to connect to the FTP server directly from the FTP/SFTP client, bypassing any proxies. The ftp-filter-at-signs takes yes and no as values, no is the default.

For example:

Users apply a script to connect to an FTP server via a proxy. The script defines the username as ftp-user@proxy-user@ftp-server and the password as ftp-password@proxy-password. When FTP-SFTP conversion is used instead, make the setting ftp-filter-at-signs=yes, and the following will be done:

SSH Tectia cuts the username string at the first @ sign to extract the ftp-user and at the last @ sign to extract the ftp-server, and the rest of the string is ignored. Likewise, the passwords string is cut at the last @ sign and the preciding part is used as the password on the FTP server.

Under the filter-engine element there can be any amount of elements of the type network, dns, or filter. The order of the elements is important, because the filter engine uses the elements in the order they were specified in the configuration file.

network

The network element specifies a "location" where SSH Tectia Connector is running. Using the network elements you can implement location-awareness for SSH Tectia Connector. It has four attributes: id, address, domain, and ip-generate-start.

The id attribute specifies a unique identifier for the network element. The address attribute specifies the address of the network. It can be missing or empty, in which case it is not used. The domain attribute contains the domain name of the computer. It can also be missing or empty, in which case it is not used. The ip-generate-start attribute defines the start address of the pseudo IP space. If it is defined here, it overrides the ip-generate-start attribute of the filter-engine element.

dns

The dns element creates a DNS rule for the filter engine. It has six attributes: id, network-id, application, host, ip-address, and pseudo-ip.

The id attribute specifies a unique identifier for the dns element. The network-id attribute contains a reference to a network element. This can be left empty if the dns entry does not bind to a specific network. The application attribute specifies the application for which this DNS entry is used. This can be a regular expression.

The host attribute specifies a target hostname. It can be a regular expression. The ip-address attribute specifies the target host IP address. It can be a regular expression. When both the hostname and the IP address are defined, the host attribute takes precedence and the ip-address attribute is ignored. When the ip-address is left empty and the host matches one of the following things happen:

  • When the pseudo-ip attribute is set to yes, the Connection Broker assigns a pseudo IP address for the target host and SSH Tectia Server resolves the real IP address.

    Pseudo IP addresses should be used when accessing an internal network from the outside, because name resolution for the machines in the internal network is not available from the outside.

  • When the pseudo-ip attribute is set to to no, a normal DNS query is made for the target hostname.

filter

The filter element specifies an action for a connection. It has five attributes: dns-id, ports, action, profile-id, and fallback-to-plain.

The dns-id attribute is a reference to a dns element.

The ports attribute can be a single port or a range. A range is specified with a dash between two integers (such as "21-25").

[Note]Note

For FTP-SFTP conversion, always specify the port unambiguosly if fallback mode is set. Do not use an asterisk (*), because it causes problems in passive mode file transfer when connected to a plaintext FTP server.

The action attribute specifies the action to be done when a filter is used. Its value can be DIRECT, BLOCK, TUNNEL (with SSH Tectia Connector), or FTP-PROXY (with SSH Tectia Client with EFT Expansion Pack).

  • DIRECT causes the connection to be made directly as plaintext without tunneling or FTP-SFTP conversion.

  • BLOCK causes the connection to be blocked.

  • TUNNEL causes the connection to be tunneled through a Secure Shell server specified with the profile-id attribute.

  • FTP-PROXY causes the FTP-SFTP connection to be made to the Secure Shell server specified with the profile-id attribute. If the profile-id attribute is left empty or the referred profile has * (an asterisk) as the value of the host attribute, the connection is made to the server specified by the FTP client application.

When applying the filter rule, if creating the tunnel fails (or the connection to the Secure Shell server fails) the Connection Broker will normally return a "host not reachable" error. However, if the fallback-to-plain attribute is set to yes, a direct (unsecured) connection is used instead. In FTP-SFTP conversion on Unix, this requires that option -F is used with the ssh-convert-ftp command. See ssh-convert-ftp (EFT Expansion Pack on Unix)(1).

The fallback-to-plain and pseudo-ip options should not be enabled at the same time. If they are, and the secure connection fails, the application will try a direct connection with the pseudo IP, which will not work.

An example filter engine configuration with SSH Tectia Connector is shown below.

<filter-engine ip-generate-start="188.1.1.1">
               
  <network id="office"
           address="10.1.48.0"
           domain=".*\.ssh\.com"
           ip-generate-start="" />
           
   <dns id="www-proxy-dns"
       network-id="office"
       application=""
       host="www-cache.*"
       ip-address="" 
       pseudo-ip="no" />
       
   <dns id="telnet-app-dns"
       network-id="office"
       application="telnet.exe"
       host=".*"
       ip-address=".*" 
       pseudo-ip="yes" />
       
   <dns id="all-dns"
       network-id="office"
       application=""
       host=".*"
       ip-address=".*" 
       pseudo-ip="yes" />
       
   <filter dns-id="www-proxy-dns"
          ports="8080"
          action="DIRECT" 
          fallback-to-plain="no" />

   <filter dns-id="telnet-app-dns"
          ports="23"
          action="TUNNEL" 
          profile-id="rock"
          fallback-to-plain="no" />

   <filter dns-id="all-dns"
          ports="21"
          action="BLOCK" 
          fallback-to-plain="no" />

   <filter dns-id="all-dns"
          ports="1-65535"
          action="TUNNEL" 
          profile-id="firewall"
          fallback-to-plain="no" />
          
</filter-engine>

This configuration specifies the following:

  • Connections to a WWW proxy host are passed through directly.

  • Connections from a Telnet application are tunneled through a profile named rock.

  • Connections to FTP ports are blocked.

  • All other connections are tunneled through a profile named firewall.

All of the rules are only used in the "office" network which is specified by network address 10.1.48.0. Pseudo IPs are generated starting from 188.1.1.1.

An example filter engine configuration with SSH Tectia Client with EFT Expansion Pack on Unix is shown below.

<filter-engine>
               
   <dns id="ftp-proxy"
       application="ftp"
       host=".*"
       ip-address=".*" 
       pseudo-ip="no" />
       
   <filter dns-id="ftp-proxy"
          ports="21"
          action="FTP-PROXY" 
          profile-id=""
          fallback-to-plain="no" />
      
</filter-engine>

This configuration specifies that all connections from a FTP application are converted to SFTP and the connection is made to the server specified by the FTP application.

[Note]Note

On Unix platforms, specifying the application with a long application name (with the path) will not work in all cases. Use short application names.

The logging Element

The logging element changes the logging settings that define the log event severities and logging facilities. The element contains one or more log-events elements.

log-events

This element sets the severity and facility of different logging events. The events have reasonable default values, which are used if no explicit logging settings are made. This setting allows customizing the default values.

For the events, facility and severity can be set as attributes. The events itself should be listed inside the log-events element.

The facility can be normal, daemon, user, auth, local0, local1, local2, local3, local4, local5, local6, local7, or discard. Setting the facility to discard causes the server to ignore the specifed log events.

On Windows, only the normal and discard facilities are used.

The severity can be informational, notice, warning, error, critical, security-success, or security-failure.

Any events that are not specifically defined in the configuration file will use the default values. The defaults can be overridden for all remaining events by giving an empty log-events element after all other definitions and setting a severity value for it.

For a complete list of log events, see Appendix F.