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 cryptographic library can be used. The library name is given as a value of the mode attribute. By default, standard cryptographic libraries are used.

<crypto-lib mode="standard" />

	Note
	The FIPS library is not available on z/OS.

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

This element defines public-key infrastructure (PKI) settings used for validating remote server authentication certificates. The element can have the following 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 or IP address against the Subject Name or Subject Alternative Name (DNS Address) specified in the server host certificate. The default value is yes. If set to no, the fields in the server host certificate are not verified and the certificate is accepted based on the validity period and CRL check only.

	Caution
	Setting end-point-identity-check="no" is a security risk. Then anyone with a certificate issued by the same trusted certification authority (CA) that issues the server host certificates can perform a man-in-the-middle attack on the server.

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 server for making LDAP or OCSP queries for certificate validity.

The address of the server 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 server) 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, crl-prefetch elements, one dod-pki element, and multiple ca-certificate and key-store elements. The elements have to be in the listed order.

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>         

This element defines settings for user public-key and certificate authentication.

Under the <general> element, there can be one <key-stores> instance which in turn can have any number of <key-store>, <user-keys>, and <identification> elements, and the order of the elements is free.

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" />

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" />

	Note
	When transparent FTP tunneling or FTP-SFTP conversion is used, accepting the host key cannot be prompted from the user (this setting must be set to no).

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" />

Note

When transparent FTP tunneling or FTP-SFTP conversion is used, accepting the host key cannot be prompted from the user. Either this setting must be set to yes in the ssh-socks-proxy-config.xml file (not recommended) or the host keys of the Secure Shell tunneling and SFTP servers must be obtained beforehand and stored based on the IP addresses of the servers, for example, by using the ssh-keydist-g3 key distribution tool. See Fetching Remote Server Keys.

	Caution
	Consider carefully before enabling this option. Disabling the host-key checks makes you vulnerable to man-in-the-middle attacks.

In the Connection Broker configuration file, the exclusive-connection element can be used to specify that a new connection is opened for each new channel. This setting takes one attribute enable, with value yes or no. The default is no, meaning that open connections are reused for new channels requested by a client.

On z/OS, the SOCKS Proxy always uses the exclusive connection type, meaning it opens a new connection for each new channel. This element is not needed in the SOCKS Proxy configuration file, and irrespective of the value set by the user, the SOCKS Proxy always interprets this setting as: exclusive-connection enable="yes".

This element specifies different ways for storing the host keys of known server hosts. On z/OS (only), it can contain key-store elements.

This element can be used:

Enter full path to the known-hosts file or to the directory as a value of the path attribute. In addition, you can specify the filename-format attribute that takes values plain and hash.

<known-hosts path="/u/username/.ssh/known_hosts" />
<known-hosts path="/etc/ssh2/hostkeys" />
<known-hosts path="/u/username/.ssh2/hostkeys" />
<known-hosts path="/h/username/hostkeys" filename-format="plain" />

Server hostkeys are searched from 'known-hosts' paths in the order they are specified in the configuration. If no known-hosts directory is specified, the default directories are searched. See the section called “Files” for the default locations.

New host keys are always stored to the last specified directory. If no directory is specified, the new host keys are stored to the default location.

The filename-format attribute affects the file name of the stored hostkey. plain means that the file name format is key_port_host.pub, for example "key_22_my.example.com.pub". With value hash, the file name format is keys_hash, for example "keys_182166d2efe5a134d3fb948646e0b48f780bff6c". The default is hash.

This element is reserved for future use.

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.

<ciphers>
  <cipher name="aes128-cbc" />
  <cipher name="3des-cbc" />
</ciphers>

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.

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

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.

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

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" />

This element specifies the authentication methods that are requested by the SSH Tectia client components. The authentication-methods element can contain one of each: auth-hostbased, auth-password, auth-publickey, auth-gssapi, and auth-keyboard-interactive. Alternatively, you can specify multiple authentication-method elements. The order of these elements is free.

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

<authentication-methods>
  <auth-hostbased>
          <local-hostname name="host.example.com" />
  </auth-hostbased>
  <auth-gssapi />
  <auth-publickey />
  <auth-keyboard-interactive />
  <auth-password>
          <password file="/path/filename" />
  </auth-password>
</authentication-methods>

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.

	Note
	This element is not used by SSH Tectia Server 6.0 for IBM z/OS. Instead the DefaultDomain keyword of ssh2_config is used for the same purpose. See SSH Tectia Server for IBM z/OS Administrator Manual for more information.

This element specifies whether to use compression on all traffic. When activated, the compression is applied to all transferred data on-the-fly; note that this is different from compressing files for the duration of the transfer.

The name of the compression algorithm and the compression level can be given as attributes. The name attribute can be defined as none (compression not used) or zlib, currently the only supported algorithm. By default, compression is not used.

The level attribute can be given an integer from 0 to 9. The default compression level is 6, when compression is activated but no level is given.

Example: to activate compression on the maximum level, make the following setting:

<compression name="zlib" level="9" />

Compression can also be activated per connection when using the sshg3 command-line tool. For information, see sshg3(1).

This element defines rules for HTTP proxy or SOCKS 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:

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/" />

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 type is always connection.

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" />

In the Connection Broker configuration file, the exclusive-connection element can be used to specify that a new connection is opened for each new channel. This setting takes one attribute enable, with value yes or no. The default is no, meaning that open connections are reused for new channels requested by a client.

On z/OS, the SOCKS Proxy always uses the exclusive connection type, meaning it opens a new connection for each new channel. This element is not needed in the SOCKS Proxy configuration file, and irrespective of the value set by the user, the SOCKS Proxy always interprets this setting as: exclusive-connection enable="yes".

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.

To eliminate server banners:

<server-banners visible="no" />

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

	Note
	X11 forwarding is not available on z/OS.

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

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

This element is reserved for future use.

This element can be used to force the Connection Broker to use only certain methods in server authentication. This element can contain up to two authentication-method elements.

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

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

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

The profile element defines a connection profile. It has the following attributes: id, name, host, port, protocol, 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. The name can be used for connecting with the profile on the command line, so define a unique name for each profile.

The host attribute defines the address of the Secure Shell server host and it is a mandatory setting. The address can be either an IP address or a domain name. The value host="*" can be used to prompt the user to enter the host address when starting the session.

An empty value host="" can be used when the profile is used with transparent TCP or FTP tunneling or FTP-SFTP conversion and the host name is taken from the application (filter-engine/rule[@hostname-from-app="yes"]). See rule for details.

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

The protocol is a mandatory setting. Currently the only allowed value is secsh2.

If you want to make the connection specified by the profile automatically when the Connection Broker is started, 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.

The user attribute specifies the user name for opening the connection. The value "%USERNAME%" can be used to set the user name to the current user. The value user="*" can be used to prompt the user to enter the user name when logging in.

An empty value user="" can be used when the profile is used with transparent FTP tunneling or FTP-SFTP conversion and the user name is taken from the application (filter-engine/rule[@username-from-app="yes"]). See rule for details.

The gateway-profile attribute can be used to create nested tunnels. The tunnels defined under the local-tunnel element of the profile, and the tunnels defined under filter-engine and static-tunnels that refer to the profile can be nested. 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.

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 tunnel element specifies a static tunnel. It has the following attributes: type, listen-port, listen-address, dst-host, dst-port, allow-relay, and profile.

The type attribute defines the type of the tunnel. This can be either tcp, ftp, or socks-proxy.

The listen-port attribute defines the listener port number on the local client.

The listen-address attribute can be used to define which network interfaces on the client should be listened. Its value can be an IP address belonging to an interface on the local host. Value 0.0.0.0 listens to all interfaces. The default is 127.0.0.1 (localhost loopback address on the client). Setting any other value requires that allow-relay="yes".

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.

The network element specifies a "location" where SSH Tectia Client/ConnectSecure is running. By using the network element, you can implement location-awareness for SSH Tectia Client/ConnectSecure. 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.

	Note
	The dns element exists for backward-compatibility reasons. Currently the rule element is used for the same settings.

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. For their descriptions, see rule below.

	Note
	The filter element exists for backward-compatibility reasons. Currently the rule element is used for the same settings.

The filter element specifies an action for a connection. It has the following attributes: dns-id, ports, action, profile-id, destination, destination-port, fallback-to-plain.

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

For the descriptions of the other attributes, see rule below.

The rule element specifies how a filtered connection will be handled. It has the following attributes: application, host, ip-address, pseudo-ip, ports, action, profile-id, destination, destination-port, username, hostname-from-app, username-from-app, fallback-to-plain.

The application attribute can be used to specify one or more applications to which the rule is applied. This can be a regular expression using the egrep syntax. For information on the syntax, see Appendix C.

The host attribute specifies a target hostname. It can be a regular expression using the egrep syntax.

The ip-address attribute specifies the target host IP address. It can be a regular expression using the egrep syntax. If both the hostname and the IP address are defined, the host attribute takes precedence and the ip-address attribute is ignored.

The pseudo-ip setting has the following effects when the ip-address is left empty and the host matches:

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

	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 matches. Its value can be DIRECT, BLOCK, TUNNEL (Windows only), FTP-TUNNEL, or FTP-PROXY.

The profile-id attribute can be used to specify the connection profile that defines the connection settings.

If the profile-id attribute is left empty and hostname-from-app="yes" is specified, the Secure Shell connection is made to the server specified by the client application using default settings. If a profile-id is specified and also hostname-from-app="yes" is specified, or the referred profile has * (an asterisk) or empty as the value of the host attribute, the Secure Shell connection is made to the server specified by the client application using the profile settings.

The destination and destination-port attributes can be used to define a static destination address and port number that will be used as the end point of the connection instead of the original address and port given by the application.

The username attribute can be used to define the user name used for connecting to the Secure Shell server, or you can define the path from where the Connection Broker should retrieve the user name.

The hostname-from-app attribute defines whether the Connection Broker should extract the Secure Shell server's host name from data sent by the application, or use a Secure Shell server defined by the connection profile in profile-id. The value is yes or no, and the default is no.

When hostname-from-app="no", the tunnel or FTP-SFTP conversion will be created to the Secure Shell server specified in the connection profile referred in the profile-id attribute. Note that with transparent tunneling, the connection from the Secure Shell server to the final destination application will be unsecured and in plaintext. To achieve end-to-end security, the Secure Shell server should reside on the same host as the application.

When hostname-from-app="yes", the tunnel or FTP-SFTP conversion will be created to the destination server specified by the application. This setting can be used with both FTP and TCP tunneling and FTP-SFTP conversion. When using hostname-from-app="yes", it is no longer necessary to create a separate connection profile for each destination host. Note that this requires that a Secure Shell server is installed to each destination server (or that fallback-to-plain is enabled to allow direct connections to those servers that do not have Secure Shell installed).

The username-from-app attribute defines whether the FTP tunneling or FTP-SFTP conversion extracts the user name from data sent by the FTP application. The value is yes or no. The default is no.

When username-from-app="yes", the user name received from the FTP client application is used. This setting can be used with FTP tunneling and FTP-SFTP conversion. This setting will override any user name settings made in a related connection profile. When username-from-app="no", the user name is taken from the connection profile defined with the profile-id attribute.

The fallback-to-plain attribute can be used to define whether a direct (unsecured) connection is used if creating the tunnel fails or the connection to the Secure Shell server fails. The default value is no. Normally, when the secured connection fails when applying a filter rule, the Connection Broker will return a "host not reachable" error.

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

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 specified log events.

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 by setting a severity value for it.