Using Selectors in Configuration File

The connection settings can be changed based on selectors in the configuration file. Using selectors makes it possible, for example, to:

allow/deny connections from certain IP addresses
require different authentication methods based on user name or group
restrict access based on a certificate field

Selectors are used in the connections, authentication-methods, and services blocks.

The different selector attributes are specified as sub-elements of the selector element. The following sub-elements are available:

certificate: Matches to a pattern in a specified field of the user certificate.
host-certificate: Matches to a pattern in a specified field of the client host certificate.
interface: Matches to the server listener interface ID or address/port.
ip: Matches to the IP address or FQDN of the client.
publickey-passed: Matches if the authentication is passed using a normal public key without a certificate.
user: Matches to a user name or ID.
user-group: Matches to a user group name or ID.
user-password-change-needed (Unix): Matches if the user password has expired and should be changed.
user-privileged: Matches based on the user privilege status (yes/no).
blackboard: Matches based on information stored on the blackboard, for example, channel codes, authentication methods. For more information, see blackboard.

In the connections block, only the interface and ip selectors can be used. In the authentication-methods and services blocks, all selectors can be used.

When a parent element contains multiple child elements with selectors, the first functional child element that matches will be used, and the rest will be ignored. Note that because of this, if the connections element has multiple connection child elements, but the first one has an empty selector, or no selectors at all, that connection element will always match and the remaining ones will never be used.

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

Wildcards in Selectors

Simple wildcards can be used in the user or user-group selector values:

An asterisk (*) matches any number of ny characters.
A question mark (?) matches any single character.
A hyphen (-) can be used in the user id and user-group id values to match a range of integers.

For example, the following selector matches to user names jdoe and jdox, but not to jdoex:

<selector>
  <user name="jdo?" />
</selector>

Regular Expressions in Selectors

Regular expressions can be used in selectors to define ranges of values instead of defining each possible value separately. Each regular expression attribute (regexp, fqdn-regexp or name-regexp) always contains a single pattern, never lists of patterns. The whole string must be matched for a match to be successful.

Regular expressions are applicable for example with user names and user group names. For example, the following selector matches to all user names that consist of (any) 4 letters and (any) 3 numbers:

<selector>
  <user name-regexp="[[:alpha:]]{4}[[:digit:]]{3}" />
</selector>

By default, the regular expressions are matched case-insensitively. Case-sensitive matching can be activated by adding "(?-i)" to the pattern. This instructs the regexp engine to turn off case-insensitive matching for the following string. It can be turned back on with "(?i)".

	Note
	Design the regular expressions very carefully in order to avoid unintentional matches.

For the syntax of the regular expressions, refer to the description of the Egrep Syntax in the SSH Tectia Client User Manual or SSH Tectia ConnectSecure Administrator Manual. Do not use the control characters elsewhere in the values, but if it is unavoidable, carefully escape the relevant characters. The escape character is backslash "\". A literal backslash can be matched with "\\".

Selector Processing

Multiple selector elements are in an OR relation (one of the selector elements must match for the parent element to match). For example, the following block matches if either the IP address is 192.168.0.3 or the user ID is 1001:

<selector>
  <ip address="192.168.0.3" />
</selector>
<selector>
  <user id="1001" />
</selector>

Selector attributes in the same selector element are normally in an AND relation (all attributes must match for the element to match). For example, the following block matches if both the IP address is 192.168.0.3 and the user ID is 1001:

<selector>
  <ip address="192.168.0.3" />
  <user id="1001" />
</selector>

However, selector attributes in the same selector element matching to the same attribute type are in an OR relation to each other. The following three examples produce the same result, either the user name exa or mple matches:

<selector>
  <user name="exa" />
  <user name="mple" />
</selector>

<selector>
  <user name="exa" />
</selector>
<selector>
  <user name="mple" />
</selector>

<selector>
  <user name="exa,mple" />
</selector>

An empty selector always matches:

<selector />

Also, typically, if an element accepts selectors, but none are given, the element is assumed to have an empty selector, which will then always match.

Selectors and Undefined Data

Normally when the server tries to match to a selector attribute for which the respective data has not been defined (the data is not available to the server), the selector matching process ends in error, effectively terminating the connection attempt. This happens, for example, in the following cases:

Other selectors than ip and interface are erroneously used in the connections block. Only the IP address of the client and the connected listener interface are available to the server in that stage of connection. For example, the user name is not yet known.
The certificate selector is erroneously used without previously requiring public-key authentication. The server will not have user certificate data unless it has received it first during public-key authentication.
The host-certificate selector is erroneously used without previously requiring host-based authentication. The server will not have host certificate data unless it has received it first during host-based authentication.
The certificate or host-certificate selector is used to match to a field that does not exist in the certificate.
The user-privileged selector is used in the authentication-methods block on a Windows server and the user is logging in using a domain account and does not yet have an access token allocated.

The allow-undefined attribute can be used in all selector sub-elements to control this behavior. 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 example, encountering the following selector causes the connection attempt to end in failure if the certificate is not available or does not contain the altname-email field:

<selector>
  <certificate 
   field="altname-email" 
   pattern="%username%@ssh.com" />
</selector>

The following selector simply does not match when the certificate does not exist or does not contain the altname-email field, and the processing continues with the next block:

<selector>
  <certificate 
   field="altname-email" 
   pattern="%username%@ssh.com" 
   allow-undefined="yes" />
</selector>