Your browser does not allow this site to store cookies and other data. Some functionality on this site may not work without them. See Privacy Policy for details on how we would use cookies.

SSH

ssh-server-config

ssh-server-config — Tectia Server configuration file format

The Tectia Server configuration file ssh-server-config.xml is a valid XML file.

On Unix, the configuration related files are stored in the following directories:

  • /etc/ssh2/ contains the ssh-server-config.xml file

  • /opt/tectia/share/auxdata/ssh-server-ng contains the XML DTD.

    [Note]Note

    In Tectia Server 6.1 and earlier on Unix the default auxiliary data directory auxdata was located in /etc/ssh2/ssh-tectia/. If your ssh-server-config.xml file was created for Tectia Server version 6.1 or earlier, please update its DOCTYPE declaration to contain the current path to the server configuration file DTD directory: /opt/tectia/share/auxdata/ssh-server-ng/.

On Windows, the configuration related files are stored in the following directories:

  • "<INSTALLDIR>\SSH Tectia Server" contains the ssh-server-config.xml file

  • "<INSTALLDIR>\SSH Tectia AUX\ssh-server-ng" contains the XML DTD.

If the configuration file cannot be found or some of the elements are missing, hardcoded default values are used. You can view the default values in the ssh-server-config-default.xml file that is stored in the same directory with the configuration file.

The ssh-server-config.xml configuration file is divided into four blocks:

In the connections and authentication-methods blocks, different selectors can be used to set access rules to users based on the user parameters such as user name or location. Users can be divided to groups dynamically, for example, based on the authentication method they use to log in. In the services block, each group can then be allowed or denied services such as tunneling, file transfer, and terminal access.

Document Type Declaration and the Root Element

The server configuration file is a valid XML file and starts with the Document Type Declaration (DTD) inside the DOCTYPE element. Both the DOCTYPE declaration and the DTD are mandatory; should they be missing, the server will not be able to parse the configuration properly.

The root element in the configuration file is secsh-server. It can include params, connections, authentication-methods, and services elements. These elements in turn can include more elements according to the configuration file syntax, see Appendix A.

An example of an empty configuration file is shown below:

<!DOCTYPE secsh-server SYSTEM
    "/opt/tectia/share/auxdata/ssh-server-ng/ssh-server-ng-config-1.dtd">

<secsh-server>

  <params />
  <connections>
    <connection />
  </connections>
  <authentication-methods />
  <services>
    <rule />
  </services>

</secsh-server>
[Note]Note

It is not mandatory to include all elements in the configuration file. If an element is missing, the equivalent default values shown in the ssh-server-config-default.xml file will be used.

The params Block

The params block defines the general server parameters, such as the location of the host key file, the listen address, logging, connection limits, and certificate validation settings.

address-family

This element defines the network address family used for connections. If type is set to inet, the server will accept only IPv4 incoming connections. If set to inet6, the server will accept only IPv6 incoming connections. If set to any, the server will accept both IPv4 and IPv6 incoming connections, will resolve addresses of both families, and opens both IPv4 and IPv6 listeners for remote port forwarding.

<address-family type="inet|inet6|any" />

The default is inet. Command-line options override settings from configuration file.

[Note]Note

The inet6 option is not supported for Solaris 9.

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. The OpenSSL cryptographic library is used in the FIPS mode.

<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, aes128-ctr, aes192-cbc, aes192-ctr, aes256-cbc, and aes256-ctr ciphers, and all the supported HMAC-SHA (both HMAC-SHA1 and HMAC-SHA2) variants of MAC. See also cipher and mac.

[Note]Note

Tectia Server has to be restarted after changing the FIPS mode setting. Extra checks are done when starting the Tectia Server and Connection Broker in the FIPS mode due to the OpenSSL FIPS crypto library health check. This will lead to a noticeable delay in the start of the process on slow machines.

The FIPS 140-2 Cryptographic Library is available on the operating systems supported by Tectia Server, except for Tectia Server for Linux on IBM System z and Tectia Server for IBM z/OS which do not support OpenSSL FIPS-certified cryptographic libraries. They support hardware acceleration on FIPS cryptographic operations.

For more information on the functions used from the cryptographic library, see Cryptographic library.

settings

This element contains miscellaneous settings. It has the following attributes: signature-algorithms, proxy-scheme, xauth-path, x11-listen-address, pam-account-checking-only, resolve-client-hostname, ignore-aix-rlogin, ignore-aix-login, record-ptyless-sessions, user-config-dir, default-path, windows-logon-type, windows-terminal-mode, ignore-nisplus-no-permission, quiet-login and default-domain.

The signature-algorithms attribute can be used to specify a comma-separated list of public-key signature algorithms used for user authentication. The algorithms that can be used are those that are defined in both Tectia Server and Connection Broker configuration files. They are defined in an order of preference. The one that is selected to be used is the first common algorithm that both the client and server have in their configuration. This way the use of only certain algorithms, such as SHA-2, can be enforced.

<settings signature-algorithms="ssh-dss,ssh-rsa-sha256@ssh.com" />
  

The proxy-scheme attribute defines rules for HTTP or SOCKS proxy servers that Tectia Server uses when a client forwards a connection (local tunnel).

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 host name which may be a regular expression containing the characters "*" and "?" and a port range:

name_pattern[:port_range]

An example proxy-scheme 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.

"direct:///127.0.0.0/8,*.ssh.com;
 http-connect://http-proxy.ssh.com:8080/*.example;
 socks://fw.ssh.com:1080/"

The xauth-path attribute contains a path to a supplementary XAuth binary used with X11 forwarding on Unix platforms.

On Unix, the x11-listen-address attribute can be used to configure on what kind of address the x11 listener (used in X11 forwarding) is created. Possible values are:

  • localhost (default) - sets the DISPLAY environment variable to 127.0.0.1:<screen>, where <screen> is the tunneled screen number, typically 10.0. This means that the x11 listener is bound to a loopback address; this setting should be sufficient for most use cases.

  • any - sets the DISPLAY environment variable to <address:screen>, where <address> is the interface to which the SSH session is bound (typically the first network interface) and the <screen> is the tunneled screen number, typically 10.0. This setting will bind the X11 listener to the 0.0.0.0 (wildcard) interface thereby allowing connections to the proxy from other hosts. Use this setting on HPUX systems, if you need to tunnel older X11 applications (such as hpterm).

    When x11-listen-address=any, the SO_REUSEADDR socket option will be left non-set in order to prevent the possibility of session hijacking on some operating systems by other users binding to the same port with a more specific address.

On Unix, the pam-account-checking-only attribute can be used to define that only PAM will be used to check if the user is allowed to login (for example, the account is not locked). Generally, PAM can be used during authentication or in PAM account or session management via the pam-calls-with-commands setting.

Possible values for the pam-account-checking-only attribute are:

  • yes - only PAM is used to check the user account and Tectia Server will not try to independently verify whether the account has been locked or otherwise disabled, if either PAM authentication has succeeded or if pam-calls-with-commands is set.

  • no (default) - the normal system checks will be used to determine whether the user is allowed to login, regardless of the result of PAM authentication or the pam-calls-with-commands setting.

The resolve-client-hostname attribute can be used to define whether Tectia Server should try to resolve the client host name from the client IP address during connection setup.

If an IP address of the client host is defined with the Allow/Deny-from option in the authorization file, then the resolve-client-hostname attribute is ignored. But if a host name is defined with the Allow/Deny-from option, then this attribute is used.

[Note]Note

This attribute does not affect the resolution of TCP tunnel endpoints and Tectia Server will try to resolve the client host name when creating a TCP tunnel.

Possible values for the resolve-client-hostname attribute are:

  • yes (default) - DNS lookups are used to resolve the client host name at connection time

  • no - client host name resolution is not attempted, but the IP address is used as the returned client host name. This is useful when you know that the DNS cannot be reached, and the query would cause just additional delay in logging in.

The ignore-aix-rlogin attribute defines whether the server should ignore the remote login restriction on AIX. Possible values are:

  • yes - Tectia Server will ignore these operating system settings:

    • the rlogin restriction flag

    • the unable to login at this time flags (e.g. logintimes)

  • no (default)

The ignore-aix-login attribute defines whether the server should ignore the local login restriction on AIX. Possible values are:

  • yes - Tectia Server will ignore these operating system settings:

    • the login restriction flag

    • the unable to login at this time flags (e.g. logintimes)

  • no (default)

The record-ptyless-sessions attribute can be used to control whether sessions without PTYs are recorded as user logins in the operating system. Sessions without PTYs are for example remote commands and SFTP sessions. By default, all sessions are recorded. However, some system utilities (such as finger on Solaris) do not allow sessions without PTYs to be recorded because these sessions do not have a valid TTY name. On these systems, only real shell logins should be recorded and others turned off by setting record-ptyless-sessions=no. The value must be yes or no. The default is yes.

The user-config-dir attribute can be used to specify a directory where user-specific configuration data is to be found, if the data is not stored in the default location. With this setting, the administrator can control those options that are usually controlled by the user. Tectia Server expects Tectia-style directory structure under the given directory, for example, the /authorized_keys directory, and the /authorization file, if they are being used.

For user-config-dir, the default is %D/.ssh2. The directory path can include pattern strings which will be expanded by Tectia Server. The following pattern strings can be used:

  • %D or %homedir% is the user's home directory

  • %U or %username% is the user's login name

    For Windows domain users, these strings are substituted differently:

    • %U is expanded to domain.username

    • %username% is expanded to domain\username

  • %IU or %userid% is the user's user ID (uid) (Unix only)

  • %IG or %groupid% is the user's group ID (gid) (Unix only)

On Unix, the default-path attribute can be used to define the default PATH value for the user environment. This path will be applied after connection to a server unless anything else is defined in the system settings. Alternatively, the default environment can be set by using the environment variable PATH.

On Windows, the windows-logon-type attribute can be used to define what kind of user logon methods for the local host are accepted by Tectia Server. The defined logon type affects password authentication. This attribute takes values batch, interactive, network, and network-cleartext. The default value is interactive.

For example, to enable accounts that do not have the access right to log on locally, make the following setting:

<settings windows-logon-type="network" />

For information on the attribute values, refer to Microsoft documentation on the Windows logon types.

On Windows, the windows-terminal-mode attribute can be used to define the mode of operation of a terminal session on the server side. This attribute takes values console and stream.

If set to console (default), the server reads the screen buffer in a loop and detects modifications based on current cursor location. If set to stream, the server reads the stdout and stderr of cmd.exe as a stream of data, while providing basic facilities for command-line editing.

On Linux and Solaris, the ignore-nisplus-no-permission attribute can be used to define whether Tectia Server should ignore it if NIS+ gives no permission to the user during authentication. The value can be yes or no. The default is no.

When set to yes, and when the user to authenticate is not root, the server will ignore it if the NIS+ returns *NP* when querying for shadow password. *NP* indicates no permission to read the password information.

[Note]Note

When NIS+ returns *NP*, the user will NOT be able to use password authentication or the keyboard-interactive with password authentication to authenticate the session. However, the keyboard-interactive with PAM is possible.

The quiet-login attribute can be used to define whether to suppress the messages about last login, password expiry, messages of the day and other such information during login. This can be useful in case third party applications are used to launch a shell, and the messages are useless or even confusing to the applications. The attribute value can be yes or no. The default is no.

The default-domain attribute can be used to append a domain to server host names that are not fully qualified domain names (FQDN). For example, if the host name is server01 and you define:

<settings default-domain="example.com"/>

then the resulting FQDN will be server01.example.com.

Example of the settings element and its attributes:

<settings 
 proxy-scheme="direct:///10.0.0.0/8,localhost;socks5://fw.example.com:1080/" 
 xauth-path="/usr/X11R6/bin/xauth" 
 ignore-aix-rlogin="no"
 ignore-aix-login="no" 
 record-ptyless-sessions="yes"
 user-config-dir="%D/.ssh2"
 default-path=""
 windows-logon-type="interactive"
 windows-terminal-mode="console"
 ignore-nisplus-no-permission="no"
 default-domain="example.com"
 quiet-login="no" />
pluggable-authentication-modules

This element can be used to define defaults for PAM account management and session management with the following attributes:

  • The pam-calls-with-commands attribute defines whether PAM Account Management (pam_acct_mgmt) and PAM Session Management (pam_session_mgmt) are enabled when the user executes shells, remote commands and subsystems. The values are yes and no. The default is no, which disables PAM session and account management. This setting has no effect on platforms which do not support PAM.

    Enabling pam-calls-with-commands will enforce the PAM restrictions on session and account management regardless of the authentication method that is used to connect to the server. Note that this requires either a PAM configuration file for the service ssh-server-g3 or the use of the service-name attribute to specify the service used by PAM.

  • The service-name attribute can be used to instruct PAM about which configuration it should use. When defined, this setting will override the factory setting which is ssh-server-g3. Note that it is possible to define different service names for user session management and for authentication by defining different values for the service-name attribute in the pluggable-authentication-modules element and in the submethod-pam element.

  • Attribute dll-path can be used to define the location of the PAM library, if the library is not in the default library path of the operating system.

    If the PAM library is not in the default library path then the dll-path attribute is needed both here in pluggable-authentication-modules and in the authentication-methods setting submethod-pam.

The settings made in pluggable-authentication-modules can be overriden locally by adding PAM-related settings also to the authentication-methods block. Under the auth-keyboard-interactive element you can define the submethod-pam element with attributes service-name and dll-path.

With the following example configuration, the factory settings are overriden by defining sshd2 as the service for PAM (in the pluggable-authentication-modules setting). This service will be used by ssh-user-exec, for example. To make the PAM submethod to use the ssh-server-g3 service, it is specified with the service-name in the submethod-pam setting.

<params>
 <pluggable-authentication-modules service-name="sshd2"/>
</params>
         <!-- ... -->
<authentication-methods>
  <authentication action="allow" name="allow-default">
    <auth-keyboard-interactive>
      <submethod-pam service-name="ssh-server-g3" />
    </auth-keyboard-interactive>
  </authentication>
</authentication-methods>
protocol-parameters

This element contains protocol-specific values that can be used to tune the performance. It should be used only in very specific environments. In normal situations the default values should be used.

The threads attribute can be used to define the number of threads the protocol library uses (fast path dispatcher threads). This attribute can be used to allow more concurrent cryptographic transforms in the protocol on systems with more than four CPUs. If the value is set to zero, the default value is used.

Example of the threads attribute:

<protocol-parameters threads="8" />
hostkey

This element defines the location of the private host key and optionally the location of the public key and/or certificate. The elements inside the element must be given in the right order (private key before public).

Inside one hostkey element either the public key or the certificate can be given, not both.

Giving the public key in the configuration file is not mandatory. It will be derived from the private key if it is not found otherwise. However, specifying the public key will decrease the start-up time for the software, as deriving the public key is a fairly slow operation.

private

The private element gives the path to the private key file as a value of the file attribute.

The key file should be located on a local drive. Network or mapped drives should not be used, as the server program may not have proper access rights for them. The default is hostkey, in the /etc/ssh2 directory on Unix and in the "<INSTALLDIR>\SSH Tectia Server" directory on Windows.

On Unix, the private key file should be readable and writable only by root. The private key directory should be writable only by root.

On Windows, the key file and directory should have full permissions for the Administrators group and the SYSTEM account and no other permissions.

public

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

The key file should be located on a local drive. Network or mapped drives should not be used, as the server program may not have proper access rights for them.

Alternatively, the public key can be specified as a base64-encoded ASCII element.

x509-certificate

This element gives the path to the X.509 user certificate file as a value of the file attribute.

Alternatively, the certificate can be specified as a base64-encoded ASCII element.

externalkey

This element defines an external host key. The type must be given as an attribute. The currently supported types are none, software, entrust, mscapi, pkcs11, and pkcs12. Entrust is supported on Windows, only. The init-info for the external key can also be given.

Sample hostkey elements are shown below:

<hostkey>      
  <private file="/etc/ssh2/hostkey_dsa" />
  <public file="/etc/ssh2/hostkey_dsa.pub" />
</hostkey>

<hostkey>      
  <private file="/etc/ssh2/hostcert_rsa" />
  <x509-certificate file="/etc/ssh2/hostcert_rsa.crt" />
</hostkey>

<hostkey>      
  <externalkey type="entrust" 
               init-info="profile-file(/etc/ssh2/hostcertprofile.epf)" />
</hostkey>

For PKCS#12, the <hostkey> settings are as follows:

<hostkey>      
  <externalkey type="software" 
               init-info="key_file(/etc/ssh2/server-cert.p12)
                          key_passphrase_file(/etc/ssh2/my-passphrase)" />
</hostkey>

In the PKCS#12 sample output, the hostkey setting reads the PKCS#12 file server-cert.p12 and if it needs a passphrase to open it, it will read the my-passphrase file and use the contents as the passphrase. The file can also contain additional certificates but they are ignored in Tectia Server.

In the init-info string, the following keywords are supported:

  • directory(<directory_name>) - defines the directory to be polled for the keys. All files in the named directory are added to sshexternalkey. Note however, that this option lacks control over the actual server key and certificate.

  • polling_interval_ms(<time_ms>) - defines the polling interval for the option above.

  • key_files(<key_spec>) - defines that multiple comma-separated files are read. Loose grouping between files is expected so that public key, private key and certificate are assumed to be parts of the same key. Supported in Tectia Server.

  • key_file(<file_name>) - defines that one key file is read. The same as key_files with one parameter.

  • key_passphrase(<passphrase>) - if a private key or certificate container is password-protected, the command tries to open it with the supplied passphrase first. In case the passphrase is not valid, the authentication callback is called normally. In the server, that means a failure to open the file as the server does not have an interactive prompt.

  • key_passphrase_file(<filename>) - defines that instead of giving the passphrase in the configuration file directly, it can be written to a separate file. This option is useful if server configuration file needs to be more widely readable. The private key and passphrase can still be with root access only.

listener

This element is used to specify where the Secure Shell server listens for connections. The element has three attributes: id, address, and port.

The id must be given as an attribute. The value must be unique. The value must begin with a letter, it can contain alphanumeric characters or underscore characters but no any whitespaces. Also the port and network interface address can be given. The default port for listeners is 22.

Several listeners can be created to the same IP address to different ports. Each must have an unique ID. If the address is not specified, the server will listen to the given port on all interfaces.

Sample listener elements are shown below:

<listener id="internet" address="192.0.2.62" />
<listener id="intranet" address="10.0.0.1" />
<listener id="admin-private" port="222" />
domain-policy

On Windows, you can add this optional domain-policy setting to define how Tectia Server will handle user names when a user logs in without specifying the prefix (indicating local or domain user). This setting defines where the server will look for the user account, and how it will fill in the missing prefix part.

The windows-domain-precedence element defines a comma-separated list of trusted domains and special values %default% and %local%. The list is read in order, and the first domain that has an account for the user name will be used to log in the user and the rest will be ignored. If the user name is not found in any of the specified domains, the user account is assumed not to exist.

Value %local% means that a user without a specified prefix will be treated as a local user (usernamelocalmachine_name\username).

Value %default% means that a user without a specified prefix will be treated as a domain user, and the domain name is expected to be the default domain of the local machine (usernamedefaultdomain_name\username).

If this setting is not defined in the Tectia Server configuration, and a user logs in without specifying the prefix, Tectia Server first checks if the given user name is valid in the default domain where the local machine exists. If no match is found, for example because the machine is standalone, the user will be treated as a local user.

A sample domain-policy setting is shown below:

<domain-policy
windows-domain-precedence="%local%, %default%, domainA, domainB" />
logging

This 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 specified 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 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 C.

The following example sets the facility of the Auth_method_failure event to auth and the severity to notice. It also sets the facility of the Server_reconfig_started and Server_starting events to discard (the events will not be logged). All other events use the default settings.

<logging>
  <log-events facility="auth" severity="notice">
    Auth_method_failure
  </log-events>
  <log-events facility="discard">
    Server_reconfig_started Server_starting
  </log-events>
</logging>
limits

This element sets the maximum number of connections and processes the server will handle. Tectia Server uses a distributed architecture where the master server process launches several servant server processes that handle the actual connections. The element can also contain zero or more servant-lifetime elements.

The max-processes attribute defines the maximum number of servant processes the master server will launch. The value range is 1-2048. The default (and recommended) value is 40.

The max-connections attribute defines the maximum number of client connections allowed per servant. The default (and recommended) value is 256.

The maximum number of connections a server can handle depends on system resources.

This setting is useful in systems with low resources. The server has to be restarted to use the changed setting.

A sample limits element is shown below:

<limits max-connections="256" max-processes="40" />
servant-lifetime

This element sets the total number of connections that a servant process will handle before the server process starts a new servant process in its place.

In some situations, the servant process may leak resources in OS provided services, resulting in resource starvation that prevents new connections. The servant-lifetime element will limit the maximum number of connections handled by the servant. After the maximum number of connections is handled, the server process starts retiring the servant. The server process will not pass any new connections to the servant and when the servant has stopped handling all the existing connections, the server process will stop the servant. If after this, the number of running servants is under the defined number, new servants will be started if needed.

You can check the status of the server and servant processes with the ssh-server-ctl tool and its status command.

The total-connections attribute defines the total number of connections the servant process will handle during its lifetime. It can be any number from 1 to 4 billion. The recommended value is 5000.

If you do not give this option at all (default), the servants are never retired.

<limits max-connections="256" max-processes="5">
<servant-lifetime total-connections="5000"/>
</limits>
cert-validation

This element contains the CA certificates used in validation of the host-based and public-key authentication certificates. The element can have the following attributes: http-proxy-url, socks-server-url, cache-size, max-crl-size, external-search-timeout, max-ldap-response-length, ldap-idle-timeout, and max-path-length.

The http-proxy-url attribute defines a 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, by setting socks-server-url to "socks://mylogin@socks.ssh.com:1080/192.168.0.0/16,10.100.23.0/24", the host socks.ssh.com and port 1080 are used as your SOCKS server for connections outside of networks 192.168.0.0 (16-bit domain) and 10.100.23.0 (8-bit domain). Those networks are connected directly.

The cache-size attribute defines the maximum size (in megabytes) of in-memory cache for the certificates and CRLs. The allowed value range is 1 to 512; and the default value is 35 MB.

The max-crl-size attribute defines the maximum size (in megabytes) of CRLs accepted. Processing large CRLs can consume a considerable amount of memory and processing power, so in some environments its advisable to limit their size. The allowed value range is 1 to 512; and the default value is 11 MB.

The external-search-timeout attribute defines the time limit (in seconds) for external HTTP and LDAP searches for CRLs and certificates. The allowed value range is 1 to 3600 seconds; and the default value is 60 seconds.

The max-ldap-response-length attribute defines the maximum size (in megabytes) of LDAP responses accepted. The allowed value range is 1 to 512; and the default value is 11 MB.

The ldap-idle-timeout attribute defines an idle timeout for LDAP connections. The validation engine retains LDAP connections and reuses them in forthcoming searches. The connection is closed only after the LDAP idle timeout has been reached. The allowed value range is 1 to 3600 seconds; and the default idle timeout is 30 seconds.

The max-path-length attribute limits the length of the certification paths when validating certificates. It can be used to safeguard the paths or to optimize against the paths getting too long in a deeply hierarchical PKI or when the PKI is heavily cross-certified with other PKIs. Using the attributes requires knowing the upper limit of the paths used in certificate validation. For example:

<cert-validation max-path-length="6">
  <ldap-server address="ldap://myldap.com" port="389" />
  <dod-pki enable="yes" />
  <ca-certificate name="CA 1" file="ca-certificate1.crt" />
</cert-validation>

In the example, the path is limited to six certificates, including the end-entity and root CA certificates. If not specified, the default value is 10. Decrease the value to optimize the validation if the maximum length of the encountered paths in the certificate validation is known.

The cert-validation element can contain sub- elements. You can use maximum one each of elements cert-cache-file, crl-auto- update, and dod-pki, and multiple instances of the other elements.

The validity of a received certificate is checked separately using each of the defined ca-certificate elements in turn until they are exhausted (in which case the authentication fails), or a positive result is achieved. If the certificate is valid, the connections and authentication-methods elements determine whether the certificate allows the user to log in (of course, the correct signature generated by a matching private key is always required in addition to everything else).

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.

For the OCSP validation to succeed, both the end-entity certificate and the OCSP responder certificate must be issued by the same CA. If the certificate has an Authority Info Access extension with an OCSP Responder URL, it is only used if there are no configured OCSP responders. It is not used if any OCSP responders have been configured.

The validity-period in seconds for the OCSP data can be optionally defined. During this time, new OCSP queries for the same certificate are not made but the old result is used.

If an OCSP responder is defined in the configuration file or in the certificate, it is tried first; only if it fails, traditional CRL checking is tried, and if that fails, the certificate validation returns a failure.

cert-cache-file

This element specifies the name of the file where the certificates and CRLs are stored when the Tectia Server service is stopped, and read back in when the service is restarted.

On Unix, the cache file should be writable only by root.

On Windows, the cache file should be writable only by the Administrators group and the SYSTEM account.

crl-auto-update

This element turns on automatic updating of certificate revocation lists. When it is on, Tectia Server periodically tries to download the new CRL before the old one has expired. The update-before attribute can be used to specify how many seconds before the expiration the update takes place. The minimum-interval sets a limit for the maximum update frequency. The default minimum interval is 30 seconds.

crl-prefetch

This element instructs Tectia Server 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, 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 practice, 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 enables user authentication using certificates. It can have five attributes: name, file, disable-crls, use-expired-crls, and trusted.

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

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

[Note]Note

CRL usage should only be disabled for testing purposes. Otherwise it is highly recommended to always use CRLs.

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

The CA certificate is by default set as a trust anchor and it is trusted explicitly (trusted="yes"). No revocation checks are performed on the CA certificate (only the validity period will be checked), and it will be the end point of the validation path, meaning that no CA above it in the PKI hierarchy will affect the validation. If the trusted attribute is set to no, the CA will be considered an intermediate CA. At least one trusted CA certificate is required for a working PKI setting.

A sample cert-validation element is shown below:

<cert-validation http-proxy-url="http://proxy.example.com:800">
 <ldap-server address="ldap.example.com" port="389" />
 <ocsp-responder validity-period="60" url="http://ca.example.com/ocsp-1/" />
 <cert-cache-file file="/var/cert-cache.dat" />
 <crl-auto-update update-before="30" minimum-interval="600" />
 <crl-prefetch interval="1800" url="http://ca.example.com/default.crl" />
 <dod-pki enable="no" />
 <ca-certificate name="exa-ca1" file="/etc/ssh2/exa-ca1.crt" />
 <ca-certificate name="exa-ca2" file="/etc/ssh2/exa-ca2.crt"
     use-expired-crls="3600" />
 <ca-certificate name="testonly-ca" file="/etc/ssh2/testonly-ca.crt"
     disable-crls="yes" />
</cert-validation>    
password-cache

On Windows, this element specifies the location of the server password cache file, given as the value of the file attribute.

<password-cache file="C:\Program Files\SSH Communications Security\SSH Tectia\
                      SSH Tectia Server\sshpwcache.db"/>

For more information, see Password Cache.

The connections Block

The connections block defines the basic rules for allowing and denying connections. The connections block includes one or more connection elements.

If a user does not match to any selectors in the connection elements, the connection is allowed with server default connection settings.

connection

Each connection element specifies either an allow or deny rule for connections. The element can have three attributes: name, action, and tcp-keepalive.

The word allow or deny is given as a value of the action attribute. By default, if the action attribute is omitted, the connection is allowed.

The name attribute can be used to give an identifier to the connection rule. The value must be a valid XML name beginning with a letter and containing alphanumeric characters or the underscore character without any whitespace. The identifier can be used, for example, in auditing.

The tcp-keepalive attribute defines whether the system should send keepalive messages to the other side. If they are sent, a broken connection or crash of one of the machines will be properly noticed. However, this means that connections will die if the route is down temporarily, and this can be annoying in some situations. On the other hand, if keepalive messages are not sent, sessions may hang indefinitely on the server, leaving "ghost" users and consuming server resources. The value must be yes or no. The default is no (do not send keepalives).

The connection element can include one or more selectors, a rekey setting, and one or more cipher, MAC, KEX and host key algorithm definitions.

selector

The selectors define to which connections this connection rule applies to. Only the interface and ip selector attributes can be used in the connections block. Other information, for example the user name, is not yet available at this stage of the connection. Do not define any other selector attributes, as their matching process would end in error and terminate the connection attempt. See Using Selectors in Configuration File.

interface

This selector matches to the listener interface id or address and/or port. At least one attribute must be given. If the id is defined, the others MUST NOT be given. If the id is not defined, either or both of address and port may be given.

ip

This selector matches to an IP address or FQDN (fully qualified domain name) of the client. Either address or fqdn can be given, not both.

The address can be in one of the following formats:

  • 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 fqdn attribute matches to an FQDN pattern (case-insensitive). The attribute can include a comma-separated list of allowed FQDN patterns. These patterns may also contain "*" and "?" globbing characters.

rekey

This element specifies the number of seconds or transferred bytes after which the key exchange is done again.

If a value for both seconds and bytes is specified, rekeying is done whenever one of the values is reached, after which the counters are reset.

The defaults are 3600 seconds (1 hour) and 1000000000 bytes (~1 GB). The value 0 (zero) turns rekey requests off. This does not prevent the client from requesting rekeys.

cipher

This element selects a cipher name allowed by the server for data encryption. The supported ciphers are:

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

Multiple ciphers can be specified by using multiple cipher elements.

By default, the server allows aes128-cbc, aes192-cbc, aes256-cbc, aes128-ctr, aes192-ctr, aes256-ctr, 3des-cbc, and crypticore128@ssh.com (on Windows and Linux x86).

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

Normally when a specified cipher is not found on the server, the configuration file reading fails and the server will not restart. The cipher element may optionally take an allow-missing attribute, which can have a value of yes or no. If a value of yes is given for this attribute and a specified cipher is not found during configuration reading (for example, CryptiCore on Solaris), the server logs a warning to the syslog but will restart normally. The default is no (a missing cipher is treated as fatal error and the server configuration reading fails).

Setting the allow-missing attribute to yes is useful when you want to use the same ssh-server-config.xml file on multiple servers and only some of the servers have, for example, CryptiCore available.

Tectia Server for Linux on IBM System z automatically uses hardware acceleration with the IBM-provided cryptographic hardware CPACF, if it is available. Hardware acceleration is used with the following ciphers: 3des-cbc, aes128-cbc, aes192-cbc, and aes256-cbc.

mac

This element selects a MAC name allowed by the server for data integrity verification. The supported MAC algorithms are:

hmac-sha1,
hmac-sha1-96,
hmac-sha256-2@ssh.com,
hmac-sha224@ssh.com,
hmac-sha256@ssh.com,
hmac-sha384@ssh.com,
hmac-sha512@ssh.com,
crypticore-mac@ssh.com,
hmac-md5,
hmac-md5-96,
none (no data integrity verification).

Multiple MACs can be specified by using multiple mac elements.

By default, the server allows hmac-sha1, hmac-sha1-96, hmac-sha256-2@ssh.com, hmac-sha224@ssh.com, hmac-sha256@ssh.com, hmac-sha384@ssh.com, hmac-sha512@ssh.com, and crypticore-mac@ssh.com (on Windows and Linux x86).

All the supported HMAC-SHA (both HMAC-SHA1 and HMAC-SHA2) algorithm variants can operate in the FIPS mode.

Normally when a specified MAC is not found on the server, the configuration file reading fails and the server will not restart. The mac element may optionally take an allow-missing attribute, which can have a value of yes or no. If a value of yes is given for this attribute and a specified MAC is not found during configuration reading (for example, CryptiCore on Solaris), the server logs a warning to the syslog but will restart normally. The default is no (a missing MAC is treated as fatal error and the server configuration reading fails).

Setting the allow-missing attribute to yes is useful when you want to use the same ssh-server-config.xml file on multiple servers and only some of the servers have, for example, CryptiCore available.

Tectia Server for Linux on IBM System z automatically uses hardware acceleration with the IBM-provided cryptographic hardware CPACF, if it is available. Hardware acceleration is used with the following MACs: hmac-sha1, hmac-sha1-96, and hmac-sha1-256.

kex

This element selects a KEX name allowed by the server for key exchange method. The supported KEXs are:

diffie-hellman-group1-sha1,
diffie-hellman-group14-sha1,
diffie-hellman-group14-sha224@ssh.com,
diffie-hellman-group14-sha256@ssh.com,
diffie-hellman-group15-sha256@ssh.com,
diffie-hellman-group15-sha384@ssh.com,
diffie-hellman-group16-sha384@ssh.com,
diffie-hellman-group16-sha512@ssh.com,
diffie-hellman-group18-sha512@ssh.com
diffie-hellman-group-exchange-sha1,
diffie-hellman-group-exchange-sha256,
diffie-hellman-group-exchange-sha224@ssh.com,
diffie-hellman-group-exchange-sha384@ssh.com,
diffie-hellman-group-exchange-sha512@ssh.com.

Multiple KEXs can be specified by using multiple kex elements.

By default, the server allows diffie-hellman-group-exchange-sha256, diffie-hellman-group-exchange-sha1, diffie-hellman-group14-sha1 and diffie-hellman-group1-sha1.

All the supported KEXs can operate in the FIPS mode on Linux, Windows, Solaris and HP-UX Itanium. However, the following supported KEXs cannot operate in the FIPS mode on HP-UX PA-RISC and IBM AIX due to issues in the OpenSSL cryptographic library version 0.9.8: diffie-hellman-group15-sha256@ssh.com, diffie-hellman-group15-sha384@ssh.com.

hostkey-algorithm

This element selects a host key signature algorithm name to be used in server authentication with host keys or certificates.

Multiple host key algorithms can be specified by using multiple hostkey-algorithm elements. The host key algorithms are tried in the order they are specified.

The algorithms to be used are configured in both the Connection Broker and Tectia Server configuration files. The algorithms that will be used are those that are defined in both Tectia Server and Connection Broker configuration files. This way the use of only certain algorithms, such as SHA-2, can be enforced by the server.

The supported host key signature algorithms are:

ssh-dss
ssh-dss-sha224@ssh.com
ssh-dss-sha256@ssh.com
ssh-dss-sha384@ssh.com
ssh-dss-sha512@ssh.com
ssh-rsa
ssh-rsa-sha224@ssh.com
ssh-rsa-sha256@ssh.com
ssh-rsa-sha384@ssh.com
ssh-rsa-sha512@ssh.com
x509v3-sign-dss
x509v3-sign-dss-sha224@ssh.com
x509v3-sign-dss-sha256@ssh.com
x509v3-sign-dss-sha384@ssh.com
x509v3-sign-dss-sha512@ssh.com
x509v3-sign-rsa
x509v3-sign-rsa-sha224@ssh.com
x509v3-sign-rsa-sha256@ssh.com
x509v3-sign-rsa-sha384@ssh.com
x509v3-sign-rsa-sha512@ssh.com

The default host key signature algorithms are: ssh-dss, ssh-rsa, ssh-dss-sha256@ssh.com, ssh-rsa-sha256@ssh.com, x509v3-sign-dss, x509v3-sign-rsa, x509v3-sign-dss-sha256@ssh.com, and x509v3-sign-rsa-sha256@ssh.com.

A sample connection element that allows connections from a specified IP address range is shown below:

<connection name="conn1" action="allow" tcp-keepalive="yes">
  <selector>
    <ip address="192.168.0.42-192.168.0.82" />
  </selector>
  <rekey seconds="600" bytes="500000000" />
  <cipher name="crypticore128@ssh.com" />
  <mac name="crypticore-mac@ssh.com" />
  <kex name="diffie-hellman-group-exchange-sha256" />
  <hostkey-algorithm name="ssh-dss-sha256@ssh.com" />
</connection>

A sample connection element that denies all connections is shown below. As the element does not contain any selectors, it matches always. This can be used as the last element in the connections element to deny all connections that were not explicitly allowed by the previous elements. (By default, non-matching connections would be allowed.)

<connection action="deny" />

The authentication-methods Block

The authentication-methods block defines the authentication methods that are allowed and required by the server. It can have one attribute: login-grace-time. It can contain a banner-message and an auth-file-modes element and multiple authentication elements.

The login-grace-time attribute is used to specify a time after which the server disconnects if the user has not successfully logged in. If the value is set to 0, there is no time limit. The default is 600 (seconds).

The authentication methods that are on the same level under one authentication element are considered allowed (one of them must succeed).

Several authentication methods can be set as required by nesting the authentication elements inside each other.

The server allows by default public-key, keyboard-interactive, and password authentication (one of them must succeed).

If the authentication-methods element is empty or missing from the ssh-server-config.xml file, the server does not allow any authentication methods and the configuration is essentially defunctional.

However, if you put inside authentication-methods an authentication element with no authentication methods defined, the matching users will be allowed to log in without authentication. This can be used in combination with selectors and/or nested authentication methods, but should never be used as the only authentication element.

[Caution]Caution

Consider carefully before putting an empty authentication element in the ssh-server-config.xml file. It will allow the matching users (everyone, if no selectors are used) to log in without authentication.

banner-message

This element specifies the path to the message that is sent to the client before authentication. The path is given as a value of the file attribute. Alternatively, the banner message can be given as the contents of the banner-message element.

Note, however, that the client is not obliged to show this message.

<banner-message file="/etc/ssh2/banner-message">
  This is the server banner message. If file attribute is set,
  this inlined text is ignored, and the file is read instead
  (like in this example).
</banner-message>
auth-file-modes

This element specifies whether Tectia Server on Unix platforms should check permissions and ownership of the user's key files used for public-key authentication or the directory where they are stored.

The word yes or no is given as a value of the strict attribute. If set to yes, the permissions and ownership of the .ssh2 directory, the .ssh2/authorization file (if used), the .ssh2/authorized_keys directory (if used), and the keys listed in the authorization file or present in the authorized_keys directory are checked.

This is normally desirable because users sometimes accidentally leave their directory or files world-writable, in which case anyone can edit the authorization and key files. The default is yes.

The mask-bits attribute can be used to specify the forbidden permission bits in octal format. This setting controls both the file and directory permissions when used without dir-mask-bits. The default is 022 (group and others must not have the write permission).

The ownership of the checked files and directories must be either root or the user.

The value of mask-bits is given with 3 digits:

<auth-file-modes strict="yes" mask-bits="022" />

The dir-mask-bits attribute can be used to specify the forbidden permission bits in octal format (with 4 digits) for the directory where the user's key files are stored.

If only dir-mask-bits is defined, the value of mask-bits is assumed to be 022, and it is only applied to files.

<auth-file-modes strict="yes" dir-mask-bits="0222"/>

When the server has been configured to use strict mode for public-key authentication, you can define different permissions for the user's key files and for their directory. In this case, define both the mask-bits and dir-mask-bits settings together, for example as follows:

<auth-file-modes strict="yes" mask-bits="222" dir-mask-bits="0222"/>
authentication

Each authentication element specifies a chain of authentication methods. It can include one or more selectors and different authentication methods. It may also include other authentication elements.

Defining nesting authentication elements within each other sets the child elements as required (all must be passed for the authentication to be successful). Setting multiple authentication methods at the same level sets them as optional (one of the methods must be passed for the authentication to be successful).

The authentication elements are read in top-down order. For elements on the same level, the first matching element is used and the remaining elements are ignored. If the element has nested child elements, they are matched next using the same procedure.

In the authentication element, the action attribute takes values allow or deny. The allow value means that users who match a selector will be allowed into the system. The deny value means that access will be denied from users who match a selector. By default, if the action attribute is omitted, authentication is allowed.

If an authentication chain ends in a deny action, or if the user does not match to any selectors in the authentication elements, the user is not allowed to log in.

[Note]Note

Note that the behavior has changed in Tectia Server 5.1. In Tectia Server 5.0, a non-matching user was allowed the default authentication methods.

In a nested chain of authentication elements, it is possible, for example, to set the parent method to deny authentication and a child element with a selector to allow authentication. If the user matches the selector and successfully completes the authentication method(s), login is allowed.

For more information on using authentication chains, see Configuring User Authentication Chains.

The authentication element can additionally take a set-group attribute, which sets a group for the users that pass the particular authentication chain. The group definition can be later used in the services element.

If set-group is used here, it overrides any group definitions in the services element. See the section called “The services Block”.

On Windows, the authentication element can take a password-cache attribute with values yes or no. This can be used to enable or disable password caching for the authentication block. By default, password caching is disabled (set to no). For more information, see Password Cache.

The authentication name can be optionally given as an attribute. The value of name must be a valid XML name beginning with a letter and containing alphanumeric characters or the underscore character without any whitespace. The authentication name can be used, for example, in auditing.

[Caution]Caution

Consider carefully before putting an empty authentication element in the ssh-server-config.xml file. It will allow the matching users (everyone, if no selectors are used) to log in without authentication.

selector

The selectors define to which connections this authentication method applies to. All selectors can be used in the authentication-methods block. See Using Selectors in Configuration File.

certificate

This selector defines the information that needs to be matched in the specified field of user certificates used in public-key authentication. The information to match is specified in attribute pattern or regexp (regular expression). Do not define both in the same selector!

Using this selector requires that the parent element in the authentication chain contains an auth-publickey element.

The field can be either ca-list, issuer-name, subject-name, serial-number, altname-email, altname-upn, altname-ip, altname-fqdn, or extended-key-usage.

The format of the pattern depends on the type of the field. The ca-list field contains a list of CA names separated by commas. The names that are defined in the ca-certificate element are used. The issuer-name and subject-name fields contain distinguished names, serial-number a positive integer. The altname-fqdn field contains a host name and altname-ip an IP address or a range. The altname-email field contains an email address and altname-upn the principal name.

The extended-key-usage setting can be used to define the allowed key purposes for certificates. The main purpose of this option is to prevent authentication with wrong certificate types, for example a user certificate should not be accepted for host-based authentication. In the extended-key-usage field, add a comma-separated list of standard names or numerical OIDs that specify which certificate key purposes will be accepted:

Standard name        OID                      Description
------------------------------------------------------------------------------
serverAuth           1.3.6.1.5.5.7.3.1        TLS WWW server authentication
clientAuth           1.3.6.1.5.5.7.3.2        TLS WWW client authentication
ssh-server           1.3.6.1.4.1.2213.15.1.1  SecSH server authentication 
                                              (host certificate)
ssh-client           1.3.6.1.4.1.2213.15.1.2  SecSH user authentication
ssh-clientHostbased  1.3.6.1.4.1.2213.15.1.3  SecSH hostbased authentication.

For a configuration example, see the section called “Authentication Examples”.

With extended-key-usage, the explicit attribute can be used to request that the certificate must include the key purpose ID specified with the pattern. If this attribute is not used, any certificate containing no key purpose ID or containing the anyExtendedKeyUsage definition will be accepted. For information on anyExtendedKeyUsage and its usage, see RFC3280, Section 4.2.1.13: Extended Key Usage.

The altname-fqdn, altname-upn, altname-email, subject-name, and issuer-name selectors may contain the %username% keyword which is replaced with the user's login name before comparing with the actual certificate data. On Windows, the %username-without-domain% keyword can be used and it is replaced by the user's login name without the domain part. The %hostname% keyword can be used in the same way and it is replaced by the client's FQDN. These patterns may also contain "*" and "?" globbing characters.

Patterns are normally matched case-insensitively. Alternatively, the pattern can be specified using the pattern-case-sensitive attribute.

In the regexp attribute, you can define a regular expression to match a range of values in the selected field. Regular expressions follow the egrep syntax.

For the issuer-name and subject-name selectors, you can also define if the pattern has to match the subject name completely or only partly. Use the ignore-prefix attribute to match only the end of subject name, and the ignore-suffix attribute to match only the beginning of the subject name. The ignore options are optional.

You can also define both of the ignore options on simultaneously in which case the pattern has to match with some point in the subject name. For example: when both ignore settings are defined on, pattern O=SSH,OU=*,CN=example matches with:

C=FI, O=SSH, OU=RandD, CN=example, CN=UID12345

The allow-undefined attribute can be used to control the behavior of the selector when the required certificate data is not defined (certificates have not been used at all, or the certificate does not contain the fields to be matched). Its value must be yes or no. If set to yes, the undefined data is treated as non-matched and the matching continues to other elements. The default is no, (trying to match undefined data results in termination of the connection). For more information, see Selectors and Undefined Data.

[Caution]Caution

When creating the certificate selectors, make sure that every selector element ties the user name to the certificate, either by including a user sub-element, or by putting the special substitution string %username% or %username-without-domain% to a field used to match the correcponding field in the certificate.

Failing to do this may cause unintended consequences, for example authentication succeeding with many different user names with a single certificate.

host-certificate

This selector defines the information that needs to be matched in the specified field of host certificates used in public-key authentication. The information to match is specified in attribute pattern or regexp (regular expression). Do not define both in the same selector!

Using this selector requires that the parent element in the authentication chain contains an auth-hostbased element.

The field can be either ca-list, issuer-name, subject-name, serial-number, altname-email, altname-upn, altname-ip, altname-fqdn, or extended-key-usage.

See details of the field contents under the certificate selector.

Patterns are normally matched case-insensitively. Alternatively, the pattern can be specified using the pattern-case-sensitive attribute.

In the regexp attribute, you can define a regular expression to match a range of values in the selected field. Regular expressions follow the egrep syntax.

For the issuer-name and subject-name selectors, you can also define if the pattern has to match the subject name completely or only partly. Use the ignore-prefix attribute to match only the end of the subject name, and the ignore-suffix attribute to match only the beginning of the subject name. Both attributes can be used together in which case the pattern has to match with some point in the subject name. The ignore options are optional.

The allow-undefined attribute can be used to control the behavior of the selector when the required certificate data is not defined (certificates have not been used at all, or the certificate does not contain the fields to be matched). Its value must be yes or no. If set to yes, the undefined data is treated as non-matched and the matching continues to other elements. The default is no, (trying to match undefined data results in termination of the connection). For more information, see Selectors and Undefined Data.

interface

This selector matches to the listener interface id or address and/or port. At least one attribute must be given. If the id is defined, the others MUST NOT be given. If the id is not defined, either or both of address and port may be given.

ip

This selector matches to an IP address or FQDN (fully qualified domain name) of the client. Define the information to be matched with either the address or the fqdn or the fqdn-regexp attribute, but do not use them together.

The address can be in one of the following formats:

  • 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 fqdn attribute matches to an FQDN pattern (case-insensitive). The attribute can include a comma-separated list of allowed FQDN patterns.

In the fqdn-regexp attribute, you can define a regular expression to match a range of FQDNs. Regular expressions follow the egrep syntax.

user

This selector matches to a user name or ID. Define the information to be matched with one of the following attributes (do not use them together): name, id or name-regexp.

In attribute name, you can define a comma-separated list of user names.

In attribute id, you can define a comma-separated list of user IDs.

In attribute name-regexp, you can define a regular expression to match a range of names. Regular expressions follow the egrep syntax.

Names are normally matched case-insensitively. Alternatively, you can define the names to be taken exactly as entered by using the name-case-sensitive attribute.

In Windows domain environment, the user and user-group selectors have a length limitation. For more information, see the description of option User in Tectia Server Configuration Tool.

user-group

This selector matches to a user group name or ID. Define the information to be matched with either the name or the id or the name-regexp attribute, but do not use them together.

In attribute name, you can define a comma-separated list of user names.

In attribute id, you can define a comma-separated list of user IDs.

In attribute name-regexp, you can define a regular expression to match a range of user group names. Regular expressions follow the egrep syntax.

Names are normally matched case-insensitively. Alternatively, you can define the names to be taken exactly as entered by using the name-case-sensitive attribute.

In Windows domain environment, the user and user-group selectors have a length limitation. For more information, see the description of option User in Tectia Server Configuration Tool.

user-privileged

This selector matches to a privileged user (administrator or root) or to a non-privileged user. The value can be yes (match to a privileged user) or no (match to a normal user).

The allow-undefined attribute can be used to control the behavior of the selector when the required data is not defined (user-privilege level is not known). Its value must be yes or no. If set to yes, the undefined data is treated as non-matched and the matching continues to other elements. The default is no, (trying to match undefined data results in termination of the connection). For more information, see Selectors and Undefined Data.

[Note]Note

On a Windows server, the user-privilege level is not available during the authentication phase when the user is logging in using a domain account and does not yet have an access token allocated. To get the user-privilege status for domain users, the user should first pass password or GSSAPI authentication.

If the privilege level needs to be checked for local accounts, the allow-undefined attribute should be set to yes or else connection fails for users logging in using domain accounts. However, this means that the user-privilege status will not be verified for Windows domain users.

To check the privilege level of domain accounts on a Windows server in the authentication-methods block, the user-privileged selector should be used in a nested authentication block when password or GSSAPI authentication has already been passed.

blackboard

This selector matches to information in the specified blackboard field. The information to match can be defined with attribute pattern or regexp. Do not define both in the same selector!

During the connection setup phase, the server stores information on the various parameters of the client (for example, IP address, username, certificate fields), which can be later used to allow/deny the connection and set the connection parameters. The information is stored in the so called blackboard fields. The blackboard fields are used as elements inside the selectors.

The most commonly used selector attributes have their own sub-elements. Custom attributes can be specified with the generic blackboard sub-element.

Patterns are normally matched case-insensitively. Alternatively, the pattern can be specified using the pattern-case-sensitive attribute.

In the regexp attribute, you can define a regular expression to match a range of values in the selected field. Regular expressions follow the egrep syntax.

The allow-undefined attribute can be used to control the behavior of the selector when the required data is not defined. Its value must be yes or no. If set to yes, the undefined data is treated as non-matched and the matching continues to other elements. The default is no, (trying to match undefined data results in termination of the connection). For more information, see Selectors and Undefined Data.

publickey-passed

This selector matches if authentication is passed using a normal public key (without a certificate). Using this selector requires that the authentication chain contains an auth-publickey element.

Optionally, the length range of the public key can be given as an attribute, for example "1024-2048" (keys from 1024 to 2048 bits match). The range can also be left open, for example "1536-" (keys over 1536 bits match).

The allow-undefined attribute can be used to control the behavior of the selector when the required data is not defined (public-key authentication has not been used). Its value must be yes or no. If set to yes, the undefined data is treated as non-matched and the matching continues to other elements. The default is no, (trying to match undefined data results in termination of the connection). For more information, see Selectors and Undefined Data.

user-password-change-needed

On Unix platforms, this selector matches if the user password has expired and should be changed. The actual password change can be done by defining a rule with a forced passwd command. For sample rules, see the section called “The services Block” and the section called “Forcing Password Change”.

The allow-undefined attribute can be used to control the behavior of the selector when the required data is not defined. Its value must be yes or no. If set to yes, the undefined data is treated as non-matched and the matching continues to other elements. The default is no, (trying to match undefined data results in termination of the connection). For more information, see Selectors and Undefined Data.

set-blackboard

The set-blackboard element can be used to describe an item that will be added to the blackboard immediately when this authentication block is encountered. Even if the block does not complete the authentication, the added fields will persist in the blackboard.

The set-blackboard element takes a mandatory attribute field which gives the blackboard key where the item is stored. Any previous data in the location will be overridden. The attribute value can be given with the mutually exclusive options:

value which defines the desired value

file which defines a path to a file containing the desired value

<PCDATA> directly in the element.

set-user

The set-user element can be used to define that a specified user name will be used from here on. Selectors (user, user-group, etc.) will use value specified with this element. The set-user element can occur multiple times in an authentication chain (but only once in one authentication block).

The changed user name is defined in the name attribute.

The value specified here will be persistent, and will take effect immediately after any methods specified in the block have been successfully completed. Any enclosed authentication blocks will use the new value.

The connection will be disconnected if the specified user account does not exist.

auth-publickey

This element sets the public-key authentication method. The element can have the following attributes:require-dns-match, signature-algorithms, authorization-file, authorized-keys-directory, and openssh-authorized-keys-file.

The require-dns-match attribute is used to accept or deny a public key which has the allow/deny-from option set in the authorization file. If the attribute is set to yes, an additional check for a properly configured DNS is made at the moment when the allow/deny-from option is processed. That is, the host name lookup must succeed for the connection to be accepted. If the attribute is set to no (default), the DNS host name for the client's IP address is ignored. This attribute corresponds to RequireReverseMapping and is for compatibility with SSH Tectia Server versions 4.x.

A configuration example:

<publickey require-dns-match="yes" />
[Note]Note

A failure will always result in case of the following configuration settings: resolve-client-hostname="no" and require-dns-match="yes".

The signature-algorithms attribute can be used to specify a comma-separated list of public-key signature algorithms used for user authentication. The algorithms that can be used are those that are defined in both Tectia Server and Connection Broker configuration files. They are defined in an order of preference. The one that is selected to be used, is the first common algorithm that both the client and server have in their configuration. This way the use of only certain algorithms, such as SHA-2, can be enforced.

<auth-publickey signature-algorithms="ssh-rsa,ssh-dss-sha256@ssh.com" />

The authorization-file attribute can be used to specify a comma-separated list of paths to files that contain the user public keys that are authorized for login. The paths can contain pattern strings that are expanded by Tectia Server.

The following pattern strings can be used:

  • %D or %homedir% is the user's home directory

  • %U or %username% is the user's login name

    For Windows domain users, these strings are substituted differently:

    • %U is expanded to domain.username

    • %username% is expanded to domain\username

  • %IU or %userid% is the user's user ID (uid)

  • %IG or %groupid% is the user's group ID (gid)

Note that user ID and group ID are only supported on Unix, not on Windows.

The default is %D/.ssh2/authorization.

The authorized-keys-directory attribute can be used to specify a comma-separated list of directories that contain the user public keys that are authorized for login. As above, the paths can contain pattern strings that are expanded by Tectia Server. The default is %D/.ssh2/authorized_keys.

The openssh-authorized-keys-file attribute can be used to specify a comma-separated list of paths to OpenSSH-style authorized_keys files that contain the user public keys that are authorized for login. As above, the paths can contain pattern strings that are expanded by Tectia Server.

Tectia Server looks for a matching public-key in the following locations in the following order:

  1. In the defined authorization file, if such a file exists.

  2. In the defined authorized_keys directory, if no authorization file is available or the defined file does not include a matching public-key.

  3. In the defined OpenSSH authorized-keys file, if no matching key was found in the Tectia -related authorization file or key directory.

  4. In the authorization file and then in the authorized_keys directory located in the directory defined in user-config-dir in the settings element, if none of the above locations produced a matching key.

  5. In the default public-key storage location, if none of the previous settings was made.

For more information, see User Authentication with Public Keys.

auth-hostbased

This element sets the host-based authentication method. The element can take attributes: require-dns-match, disable-authorization or allow-missing.

If the require-dns-match attribute is set to yes, host-based authentication will require the host name given by the client to match the one found in DNS. If the host name does not match, the authentication will fail. The default is no (exact match not required).

If the disable-authorization attribute is set to yes, host-based authentication ignores authorization requirements. This is applicable for troubleshooting and testing purposes The default is no (authorization is enabled).

Normally the auth-hostbased is required in the server configuration. The allow-missing attribute may optionally be used, and when set to yes the server ignores the missing element. The default is no (a missing auth-hostbased is treated as a fatal error and the server configuration reading fails).

auth-password

This element sets the password authentication method.

The delay between failed attempts in seconds (failure-delay) and the maximum number of attempts (max-tries) can be given as attributes. The default delay is 2 seconds and default maximum is 3 attempts.

auth-keyboard-interactive

This element sets the keyboard-interactive authentication method.

The delay between failed attempts in seconds (failure-delay) and the maximum number attempts (max-tries) can be given as attributes. The default delay is 2 seconds and default maximum is 3 attempts.

The keyboard-interactive submethods are given as child elements. The supported methods are submethod-password, submethod-pam, submethod-securid, submethod-radius, submethod-aix-lam, and submethod-generic.

If no submethods are configured, all available submethods are allowed by default (however, the server may not be able to find the necessary libraries for SecurID and PAM, for example). If some of the submethods are configured, the rest of the submethods are implicitly disabled.

submethod-pam

This element sets the keyboard-interactive PAM submethod in use. PAM is supported on Unix platforms.

The service-name attribute can be used to instructs PAM about which configuration it should use. When used, this setting will override the setting in pluggable-authentication-modules. Note that it is possible to define different service names for authentication and user session management by defining different values for the service-name here and in the pluggable-authentication-modules element.

If you have multiple authentication elements that have the PAM submethod enabled (for example for different authentication chains for intranet and Internet users), you can define different service-name settings for them.

The dll-path can be used to define a non-standard location for the PAM library, or a comma-separated list of PAM DLLs. If the PAM library is not in the default library path then the dll-path attribute is needed both here in submethod-pam and in the pluggable-authentication-modules element.

On AIX, the path should include the archive file, unless the library is a shared object or has been extracted from the shared object.

submethod-password

This element sets the keyboard-interactive password submethod in use.

submethod-securid

This element sets the keyboard-interactive SecurID submethod in use.

The dll-path to the SecurID DLL can be given in an attribute. The path must point to the operating-system specific SecurID module, for example, "/usr/lib/libaceclnt.so" on Solaris.

submethod-radius

This element sets the keyboard-interactive RADIUS submethod in use.

The element can contain multiple radius-server child elements.

radius-server

This element defines a RADIUS server. The element has four attributes: address, port, timeout, and client-nas-identifier.

The address is the IP address of the RADIUS server. The port is the RADIUS server port. The default port is 1812.

The timeout is the time in seconds after which the RADIUS query is terminated if no response is gained. The default is 10 seconds.

The client-nas-identifier attribute defines the network access server (NAS) identifier to be used when talking to the RADIUS server.

The element must contain one radius-shared-secret child element.

radius-shared-secret

This element defines the RADIUS shared secret file.

The path to the secret file can be given as a value of the file attribute.

Alternatively, the secret can be included as the contents of the radius-shared-secret element.

submethod-aix-lam

This element enables Tectia Server to use LAM directly on AIX platforms. LAM is used as a keyboard-interactive plugin. By default, the LAM authentication submethod is enabled.

The submethod-aix-lam takes an optional attribute enable-password-change with value yes or no. By default password changes are not enabled. To enable LAM on AIX, and to allow users to change their expired passwords, use the following settings:

<authentication-methods>
      <authentication name="authentication">
        <auth-keyboard-interactive >
           <submethod-aix-lam enable-password-change="yes" />
        </auth-keyboard-interactive >
      </authentication>
</authentication-methods>
submethod-generic

This element sets the generic submethod in use. This element can be used to add custom submethods to keyboard-interactive authentication.

The name on the method must be given in the attribute.

Optional params for the submethod can be given as well.

auth-gssapi

This element sets the GSSAPI authentication method.

The dll-path can be given as an attribute. This specifies where the necessary GSSAPI libraries are located. If this attribute is not specified, the libraries are searched for in a number of common locations. The full path to the libraries should be given, for example, "/usr/lib/libkrb5.so,/usr/lib/libgssapi_krb5.so".

On AIX, the dll-path should include the archive file, if applicable, for example, "<path>/libgssapi_krb5.a(libgssapi_krb5.a.so)". The archive(shared_object) syntax is not necessary if the library is a shared object or has been extracted from the shared object.

On Windows, the dll-path attribute is ignored. Tectia Server locates the correct DLL automatically.

The allow-ticket-forwarding attribute defines whether the server allows forwarding the Kerberos ticket over several connections. The attribute can have a value of yes or no. The default is no.

[Note]Note
On Microsoft Windows version 5.2 (Server 2003) and newer the possibility to allow Kerberos ticket forwarding is determined by the domain's Kerberos policy. For more information, see "How the Kerberos Version 5 Authentication Protocol Works".

Normally if a specified authentication method is not found on the server, the configuration file reading fails and the server will not restart. The auth-gssapi element may optionally take an allow-missing attribute, which can have a value of yes or no. If a value of yes is given for this attribute and GSSAPI plugin is not found during configuration reading, the server logs a warning to the syslog but will restart normally. The default is no (if GSSAPI is specified but not found, it is treated as fatal error and the server configuration reading fails).

Setting the allow-missing attribute to yes is useful when you want to use the same ssh-server-config.xml file on multiple servers and only some of the servers have Kerberos/GSSAPI available.

authentication

The authentication elements can be nested within each other. The method(s) in the child element(s) must be passed in addition to the method in the parent element.

Authentication Examples

A sample authentication-methods element is shown below:

<authentication-methods>
  <authentication>
    <selector>
      <user-group name="staff" />
    </selector>
    <auth-publickey authorized-keys-directory="%IG/ssh2_authorized_keys" />
    <auth-password />
  </authentication>
</authentication-methods>

In this simple authentication example, the users who belong to group "staff" are allowed to log in using either public-key or password authentication. The user public keys are checked from an alternate location. As there are no other authentication blocks, all users that do not match to the selector are implicitly denied authentication.

Another sample authentication-methods element is shown below:

<authentication-methods>
  <authentication action="deny">
    <auth-publickey />
    <authentication action="allow" set-group="local-user">
      <selector>
        <ip address="10.1.55.14-10.1.55.99" />
        <user name="johnd" />
        <user name="janed" />
      </selector>
      <auth-keyboard-interactive max-tries="4"/>
        <submethod-radius>
          <radius-server address="10.1.61.128">
            <radius-shared-secret file="&configdir;/radius-secret-file"/>
          </radius-server>
        </submethod-radius>
      </auth-keyboard-interactive>
    </authentication>
    <authentication action="allow" set-group="finance-inspector">
      <selector>
        <user-group name="finance" />
      </selector>
      <auth-password />
    </authentication>
  </authentication>
</authentication-methods>

In the example above, all users are first required to authenticate using public-key authentication. Based on selector matching, also a second method needs to be passed (RADIUS via keyboard-interactive or password). A group is set based on the matched and passed authentication methods. If a user does not match to either of the child authentication elements, access is denied (the parent authentication element has the action set to deny).

If the action of the parent authentication element would be allow, the non-matching users would be let in after having passed public-key authentication.

See Configuring User Authentication Chains for more examples of configuring authentication chains.

A sample authentication-methods element that sets requirements for certificate authentication is shown below:

<authentication-methods>
  <authentication action="allow">
    <auth-publickey />
    <authentication action="allow" set-group="admin">
      <selector>
        <user-privileged value="yes" allow-undefined="yes" />
        <certificate field="ca-list" pattern="exa-ca1,exa-ca2" 
                     allow-undefined="yes" />
        <certificate field="subject-name" pattern="C=FI,
                      O=SSH, OU=*, CN=%username%" 
                     ignore-suffix="yes" allow-undefined="yes" />
      </selector>
    </authentication>
    <authentication action="allow">
      <selector>
        <publickey-passed length="1024-2048" />
      </selector>
    </authentication>
    <authentication action="deny" />
  </authentication>
</authentication-methods>

In the example above, privileged users (administrators) are required to pass certificate authentication and the certificate must contain the correct fields. Other users are allowed to log in using a plain public key of a size from 1024 to 2048 bits.

In this example, the allow-undefined attribute has to be used in the selectors of the first nested authentication block. Otherwise, the authentication will end in error for users with plain public keys. When the user uses a plain public key, the server will not have the certificate fields to be matched defined. For more information, see Selectors and Undefined Data.

[Note]Note

Specifying an explicit deny action last is necessary in a restrictive policy, as otherwise a non-matching connection would use the allow action of the parent element (if it passed public-key authentication with any key length). A better way to achieve the same result is to set the action of the parent authentication element to deny (as in the previous example).

The following example configuration shows how to define explicitly the certificate types that match the authentication policy:

<authentication-methods>
  <authentication action="deny">
    <auth-publickey />
    <authentication action="allow">
      <selector>
        <certificate field="extended-key-usage"
                     pattern="clientAuth,ssh-client"
                     explicit="yes" />
      </selector>
    </authentication>
  </authentication>
</authentication-methods>

This example configuration denies public-key authentication, and accepts only certificates that include either one or both of the clientAuth and ssh-client key types. explicit="yes" defines that the specified key purpose ID must be matched in the certificate, and so certificates with anyExtendedKeyUsage (or a missing key purpose ID) will not match.

The services Block

The services block defines the policy for the various services the server offers.

The services block contains one or more rules (rule) and optionally defines groups (group).

group

Creates a group that can be used as a basis for restricting services. Groups are defined based on selectors.

The name must be given as an attribute. The value of name must be a valid XML name beginning with a letter and containing alphanumeric characters or the underscore character without any whitespace.

If the user was already put to a group during authentication using the set-group attribute, the group definitions in the services element are ignored.

selector

The selectors define the users that belong to the group. The same selectors can be used as in the authentication-methods block. See Using Selectors in Configuration File and the section called “The authentication-methods Block”.

Sample group elements are shown below:

<!-- Remote access. -->
<group name="remote-access">
  <selector>
    <interface address="192.0.2.62" />
  </selector>
</group>

<!-- Backup. -->
<group name="backup">
  <selector>
    <user name="backup" />
  </selector>
</group>

<!-- Password change needed. -->
<group name="passwd-change">
  <selector>
    <user-password-change-needed />
  </selector>
</group>
rule

This element defines a rule for the specified group of users. Rules can be used to restrict the services and commands the server allows to the users. The element can have three attributes: group, idle-timeout, and print-motd.

The rules are read in order, and the first rule that matches the user's group is used. The match must be exact. No wildcards are allowed in the group attribute. If no group is specified, the rule matches to all users.

The idle-timeout attribute sets the idle timeout limit in seconds. If the connection (all channels) has been idle this long, the connection is closed. The default is 0 (zero), which disables idle timeouts.

The print-motd attribute defines whether the message of the day (/etc/motd) is printed when a user logs in interactively to a Unix server. The value must be yes or no. The default is yes.

Each rule can contain environment, terminal, subsystem, tunnel-agent, tunnel-x11, tunnel-local, tunnel-remote, and command elements.

An empty rule allows the specified group to perform all actions.

[Note]Note

The default (unnamed) rule allows all users access to all services. Keep the default rule as the last rule, so it will match to users that are not set in any group. Remember to edit the rule according to your security policy.

environment

This element defines the environment variables the user group is allowed to set at the client side. The variables are given in the allowed attribute as a comma-separated list. By default, the user can set the TERM, PATH, TZ, LANG, and LC_* variables.

Do not use * (asterisk), as it will allow any and all variables, and that can be a security risk.

Allowed variables are normally matched case-insensitively. If case-sensitive variables are needed, specify them using the allowed-case-sensitive attribute.

terminal

This element defines whether terminal access is allowed or denied for the user group. The word allow or deny can be given as the value of the action attribute. By default, terminal access is allowed.

On Unix systems, the chroot attribute can be optionally used to define a directory where the user is chrooted during the terminal session. For more information on chrooting, see Chrooting (Unix).

If terminal access is denied, also shell commands are denied, unless commands are explicitly allowed or set as forced by the command element. See command.

subsystem

This element defines a subsystem. The element can take the following attributes: type, action, audit (optional), exec-directly (optional), application (optional), and chroot (optional).

The type attribute must be given. It defines the subsystem, for which the settings are made. For example sftp.

The action attribute defines whether the use of the subsystem is allowed or denied. The possible values are allow and deny. The default is allow.

[Note]Note

Denying the SFTP subsystem denies both SFTP and scp2/scpg3 operations to the server, but it does not deny OpenSSH-style SCP operations. To deny OpenSSH SCP, you should restrict remote commands. See also command.

The optional audit attribute can be used to define whether the audit messages of the subsystem are recorded in the system log. Possible values are yes and no. The default is yes. The audit attribute can be used only with the SFTP subsystem.

The exec-directly attribute is only applicable to the sft-server-g3 subsystem on Unix. The default value is yes, which means that the server will launch sft-server-g3 directly without invoking the user's shell. Note that this will allow the user to run file transfers even if a dummy shell, such as /bin/no-shell, is specified in the user account. When the value is no, the server launches the user's shell which then executes sft-server-g3.

All other subsystem applications are run as if exec-directly="no" would be specified. For these subsystems it is not allowed to specify exec-directly="yes".

An example configuration:

<subsystem type="sftp" action="allow" audit="no" exec-directly="no" /> 

The optional application attribute can be used to define the executable of the subsystem. This attribute is not necessary with the SFTP subsystem if the SFTP binary is in the default location. Example setting:

An example configuration:

<subsystem type="sftp" application="sft-server-g3.exe" action="allow" />

On Unix, the optional chroot attribute can be used to define a directory where the user is chrooted when running the subsystem. For more information on chrooting SFTP, see Chrooting SFTP.

The subsystem element can contain multiple attribute child elements.

attribute

This element can be used to define attributes for a subsystem.

The attribute element takes two attributes: name (mandatory) and value (optional).

On Windows platforms, for example the following settings can be used to set the user home directory and virtual folders for the SFTP subsystem:

<subsystem type="sftp" application="sft-server-g3.exe">
  <attribute name="home" value="%USERPROFILE%" />
</subsystem>  

For more information on virtual folders, see Defining SFTP Virtual Folders (Windows).

On Unix, you can define a umask for subsystem SFTP to overwrite the default file mode creation mask for the SFTP server. When you define a value for umask in this configuration file takes precidence over any other umask settings, for example any umask settings in the .profile or other shell init files.

Define the value for the umask in octal format (0nnn) or in decimal format (nnn without the leading zero). For example, the following setting defines the umask to be 0022:

<subsystem type="sftp" application="sft-server-g3"> 
<attribute name="umask" value="0022" /> 
</subsystem>
[Caution]Caution

Support for legacy OpenSSH SCP in Tectia Server is not implemented via the SFTP subsystem but using a command called scp1-compat-srv. When a client uses OpenSSH SCP to connect to Tectia Server, the umask setting does not apply.

command

This element defines a shell command as allowed, denied, or forced. The element can have five attributes, however, all of them are not used at the same time: action, interactive, application, application-case-sensitive, and chroot.

The value of the action attribute can be either allow, deny, or forced. The default is allow.

If the deny action is set, all shell commands are denied and no further attributes should be specified. Commands are also denied if terminal access is denied in the rule and the command element is omitted.

For the allow action, the application can be optionally specified as an attribute. When the allow action is set and the application attribute is specified, running the specified application(s) is allowed and all other applications are implicitly denied. If the application is not given, running all commands is allowed.

For the forced action, the application must be given as an attribute. When the forced action is set, the specified application is run automatically when the user logs in successfully, instead of the application the user is trying to run. All other applications are implicitly denied.

For the forced action, the interactive can be given as an attribute. If the application that is run as forced requires user interaction, set the interactive attribute to yes. If the application that is run as forced does not require user interaction, set the interactive attribute to no. By default its value is set to no. This attribute is for Windows only.

If the terminal element is omitted from the rule and the command element specifies a forced command, terminal is implicitly denied. If the user requests a shell, the forced command is run instead.

If the terminal is explicitly allowed in the rule, the forced action of the command element applies only when the user tries to run remote commands. If the user requests a shell, he can get it normally and the forced command is not run.

If the SFTP subsystem is allowed, the user can also use the scp2/scpg3 and sftp2/sftpg3 programs normally. However, if the SFTP subsystem is denied, trying to use it will not cause the forced command to be run, but gives an error message.

[Note]Note

Support for legacy OpenSSH SCP in Tectia Server is implemented using a command called scp1-compat-srv. When a client uses OpenSSH SCP to connect to Tectia Server, the server invokes this command. Restrictions on remote commands apply also to OpenSSH-style SCP operations to the server.

Users can also define forced commands for public keys in their authorization files or OpenSSH-style authorized_keys files. However, if a command is defined in the ssh-server-config.xml file, it overrides any commands defined in the authorization or authorized_keys files. For more information, see the section called “Authorization File Options”.

Applications are normally matched case-insensitively. Alternatively, the application can be specified using the application-case-sensitive attribute.

On Unix systems, the chroot attribute can be optionally used to define a directory where the user is chrooted when running the command. For more information on chrooting, see Chrooting (Unix).

tunnel-agent

This element defines whether agent tunneling (forwarding) is allowed or denied by the server.

The word allow or deny can be given as the value of the action attribute. By default, agent forwarding is allowed.

For more information on agent forwarding, see Agent Forwarding (Unix).

tunnel-x11

This element defines whether X11 tunneling (forwarding) is allowed or denied by the server.

The word allow or deny can be given as the value of the action attribute. By default, X11 forwarding is allowed.

For more information on X11 forwarding, see X11 Forwarding (Unix).

tunnel-local

This element defines a rule for local TCP tunnels (port forwarding). There can be several of these rules. When a user attempts tunneling, the rules are read in order and the first matching rule is used. For details, see the section called “Tunneling Rule Processing”.

The word allow or deny can be given as the value of the action attribute. By default, local tunnels are allowed.

Tunneling restrictions can be further defined with the src and dst elements.

src

This selector element specifies source address(es) and FQDN(s) for local tunnels.

Define the pattern to be matched with attribute address or fqdn or fqdn-regexp, but do not use them together.

The address can be in one of the following formats:

  • 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 fqdn attribute matches to an FQDN pattern (case-insensitive). The attribute can include a comma-separated list of allowed FQDN patterns. These patterns may also contain "*" and "?" globbing characters.

In the fqdn-regexp attribute, you can define a regular expression to match a range of FQDNs. Regular expressions follow the egrep syntax.

dst

This element defines destination address(es) and port(s) for local tunnels.

The address or the fqdn (not both) can be given as an attribute. Also the port can be given.

The address can be in one of the following formats:

  • 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 fqdn attribute matches to an FQDN pattern (case-insensitive). The attribute can include a comma-separated list of allowed FQDN patterns. These patterns may also contain "*" and "?" globbing characters.

In the fqdn-regexp attribute, you can define a regular expression to match a range of FQDNs. Regular expressions follow the egrep syntax.

The port attribute can specify a single port or a port range (for example, 2000-9000).

For more information on local tunnels, see Local Tunnels.

tunnel-remote

This element defines a rule for remote TCP tunnels (port forwarding). There can be several of these rules. When a user attempts tunneling, the rules are read in order and the first matching rule is used. For details, see the section called “Tunneling Rule Processing”.

The word allow or deny can be given as the value of the action attribute. By default, remote tunnels are allowed.

Tunneling restrictions can be further defined with the src and listen elements.

src

This selector element specifies source address(es) and port(s) for remote tunnels.

Define the pattern to be matched with attribute address or fqdn or fqdn-regexp, but do not use them together.

The address can be in one of the following formats:

  • 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 fqdn attribute matches to an FQDN pattern (case-insensitive). The attribute can include a comma-separated list of allowed FQDN patterns. These patterns may also contain "*" and "?" globbing characters.

In the fqdn-regexp attribute, you can define a regular expression to match a range of FQDNs. Regular expressions follow the egrep syntax.

listen

This element defines listen address(es) and port(s) for remote tunnels.

The address and the port can be given as attributes.

The address can be in the formats described above for the src element.

The port attribute can specify a single port or a port range (for example, 2000-9000).

For more information on remote tunnels, see Remote Tunnels.

Sample rule elements are shown below:

<!-- Administrators are allowed to do anything. -->
<rule group="admin" />

<!-- The finance inspector. -->
<rule group="finance-inspector" print-motd="no">
  <tunnel-local action="allow">
    <!-- Microsoft SQL ports. -->
    <dst fqdn="finance-db.example.com" port="1433" />
    <dst fqdn="finance-db.example.com" port="1434" />
  </tunnel-local>
  <tunnel-remote action="deny" />
  <!-- Can execute commands and shells, as no overriding behavior is defined. -->
</rule>

<!-- Remote access. -->
<rule group="remote-access" idle-timeout="600">
  <!-- Setting terminal action to "deny" also denies shell commands, 
       unless they are specifically allowed.     -->
  <terminal action="deny" />
  <subsystem type="sftp" application="sft-server-g3" chroot="%homedir%" />
  <!-- The listed local tunnels are allowed, other local tunnels are 
       denied. -->
  <tunnel-local action="allow">
    <!-- IMAP. -->
    <dst fqdn="imap.example.com" port="143" />
    <dst fqdn="imap.example.com" port="993" />
    <!-- POP. -->
    <dst fqdn="mail.example.com" port="109" />
    <dst fqdn="mail.example.com" port="110" />
    <dst fqdn="mail.example.com" port="995" />
  </tunnel-local>
  <tunnel-remote action="deny" />
</rule>

<rule group="backup">
  <terminal action="deny" />
  <!-- This account is only used to back up the disk drive. -->
  <command application="dd if=/dev/hda" action="forced" />
  <tunnel-local action="deny" />
  <tunnel-remote action="deny" />
</rule>

<!-- This rule is used to force password change. -->
<rule group="passwd-change">
  <terminal action="deny"/>
  <subsystem type="sftp" application="sft-server-g3" action="deny" />
  <command application="/usr/bin/passwd" action="forced" />
  <tunnel-local action="deny" />
  <tunnel-remote action="deny" />
</rule>

<!-- The default rule, used if the user has not been put to any group. -->
<rule>
  <!-- The listed environment variables are allowed and all others are 
       denied. There is no "denied" setting. -->
  <environment allowed-case-sensitive="TERM,PATH,TZ,LANG,LC_*" />
  <terminal action="deny" />
  <subsystem type="sftp" application="sft-server-g3" chroot="%homedir%" />
  <!-- Only the date command is allowed. Other commands are denied. -->
  <command application="date" action="allow" />
  <tunnel-local action="allow" />
  <tunnel-remote action="deny" />
</rule>

Forcing Password Change

On Unix, the Server default configuration includes settings for forcing the users to change expired passwords.

When users whose passwords have expired attempt to login, the settings in <rule group="passwd-change"> are applied to them. The passwd-change group settings deny all services and force the user to enter a new password.

<!-- This rule is used to force password change. -->
<rule group="passwd-change">
  <terminal action="deny"/>
  <subsystem type="sftp" application="sft-server-g3" action="deny" />
  <command application="/usr/bin/passwd" action="forced" />
  <tunnel-local action="deny" />
  <tunnel-remote action="deny" />
</rule>

Note that the user needs an ssh2/sshg3 terminal client to be able to change the password.

In case you start creating a configuration from scratch, you need to manually add a rule for handling expired passwords. Make sure you do not accidentally allow any services for users who are directed to the passwd- change group after their password has expired. You can use the ssh-server-config-example.xml settings as a model.

On Windows, the password change is handled differently than on Unix platforms, and it is not configurable. If a password change is required for the account by the server, user will be prompted to change the password during authentication right after the validation of the old password. User will be logged on in after successful password change.

Some third-party SSH clients may allow users to request password change themselves during authentication. In that case, it will be handled the same way as it would have been enforced by server.

[Note]Note

For accounts with empty password, and whose login is disabled by policy: "Accounts: Limit local account use of blank passwords to console logon only", the user will be prompted to change the password even when the user is not able to logon otherwise (see Empty/Blank Passwords in User Authentication with Passwords).

Tunneling Rule Processing

The tunneling rules defined by the tunnel-local and tunnel-remote elements operate in the same way as selectors. Inside a tunnel rule, elements of different type are in AND relation to each other. If a tunnel rule contains several items of the same type, they are in OR relation to each other.

For example, the following rule matches if both the listen port and the source FQDN match:

<rule>
  <tunnel-remote action="allow">
    <listen port="1-9000" />
    <src fqdn="trusted.example.com" />
  </tunnel-remote>
...
</rule>

For example, the following rule matches if either of the source addresses match:

<rule>
  <tunnel-remote action="deny">
    <src address="192.168.23.1" />
    <src address="10.1.0.1" />
  </tunnel-remote>
...
</rule>

With several tunneling rules of the same type, the first matching rule is used. For example, the following configuration allows local tunnels to all other addresses in network 192.168.14.0/24 except 192.168.14.21-192.168.14.30:

<rule>
  <tunnel-local action="deny">
    <dst address="192.168.14.21-192.168.14.30" />
  </tunnel-local>

  <tunnel-local action="allow">
    <dst address="192.168.14.0/24" />
  </tunnel-local>
...
</rule>

If the tunnel-local elements were in different order, tunnels to the whole 192.168.14.0/24 network would be allowed as any tunneling attempts would match the first (allow) rule and the second (deny) rule would not be read.

For more examples of tunneling rules, see Chapter 8.

===AUTO_SCHEMA_MARKUP===