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 | |
---|---|
In Tectia Server 6.1 and earlier on Unix the default auxiliary data directory
|
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:
General server parameters (params
)
Connection rules and encryption methods (connections
)
Authentication rules and methods (authentication-methods
)
Service rules (services
)
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.
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 B.
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 | |
---|---|
It is not mandatory to include all elements in the configuration file. If an element is
missing, the equivalent default values shown in the
|
params
BlockThe 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.
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.
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 | |
---|---|
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. |
For more information on the functions used from the cryptographic library, see Cryptographic library.
This element contains miscellaneous settings. It has the following attributes:
proxy-scheme
, xauth-path
, xauth-shell
,
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 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.
The xauth-shell
attribute specifies the shell used to run xauth binary. The default is to use the user shell.
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 | |
---|---|
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:
%U
is expanded to domain.username
%username%
is expanded to
domain\username
For local server machine users:
%U
is expanded to username
%username%
is expanded to username
(without the domain prefix)
%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 | |
---|---|
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" />
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>
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" />
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).
The following attributes can be used to define aspects of host key rotation:
The status
attribute defines whether the key file will be used
as a host key. The possible values are normal
and
disabled
. A disabled key can be advertised, even as it is not
used as a host key.
The advertise
attribute defines whether the key will be
advertised. The possible values are no
, yes
, and
tectia-only
. When the value is tectia-only
, the
key will be advertised only to Tectia clients.
The rotation-period
attribute defines the time span between key
rotations. The value is entered in seconds by default, but it can be modified with
the m
, minutes
, h
,
hours
, d
, and days
suffices to
represent those time periods. Rotation period is counted from the current host key
timestamp.
The rotation-margin
attribute defines a time span before the
key rotation. At the start of the margin period, a new host key is generated, and
advertisement of the new host key starts.
For more information about key rotation, see Key rotation.
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.
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.
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.
This element gives the path to the OpenSSH user certificate files as a value
of the file
attribute.
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.
This element defines an external host key. The type
must be
given as an attribute. The currently supported types are none
,
software
, mscapi
, pkcs11
, and
pkcs12
. The init-info
for the external key can
also be given.
Sample hostkey
elements are shown below:
<hostkey> <private file="/etc/ssh2/hostkey_rsa" /> <public file="/etc/ssh2/hostkey_rsa.pub" /> </hostkey> <hostkey> <private file="/etc/ssh2/hostcert_rsa" /> <x509-certificate file="/etc/ssh2/hostcert_rsa.crt" /> </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.
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 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" />
On Windows, you can add this optional domain-policy
element to
define how Tectia Server will handle user names when a user logs on without specifying the
prefix (indicating local or domain user). This element defines where the server will
look for the user account, and how it will fill in the missing prefix part.
The windows-domain-precedence
attribute 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 (username
→
localmachine_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 (username
→
defaultdomain_name\username
).
If this element is not defined in the Tectia Server configuration, and a user logs on 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.
The domain-policy
element can contain zero or more
windows-domain
elements.
This element defines domain user accounts for domain access with one-way trust. A one-way trust is a single, non-transitive trust relationship between two domains. In a one-way trust configuration between Tectia Server and a domain controller, the domain controller does not trust the Tectia Server process. The domain controller therefore refuses to give the server any information about the user that is trying to log on. Because the server does not know enough about the user, it refuses the logon procedure. You can use a domain user account to get this information from the domain controller.
For each windows-domain
element, the name
of
the domain and user
must be given as attributes. Set the password
for the account either with the
password-cache
element or using the
Tectia Server Configuration tool (for more information, see Password Cache).
Note that you can only define one domain user account per domain.
The following example defines the windows-domain-precedence
and a
domain user account with one-way trust for user sshadmin
in domain
SSH
:
<domain-policy windows-domain-precedence="%local%, %default%, domainA, domainB"> <windows-domain name="SSH" user="sshadmin" /> </domain-policy>
This element changes the logging settings that define the log event severities and
logging facilities. The element contains one or more log-events
elements.
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 D.
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>
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 allowed value range is 1
to 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" />
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>
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 accepted size (in
megabytes) of CRLs. Processing large CRLs can consume a considerable amount of memory
and processing power, so in some environments it is 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 accepted
size (in megabytes) of LDAP responses. 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).
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
.
This element specifies an OCSP (Online Certificate Status Protocol) responder
HTTP 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 should be issued by the same CA. If different OCSP responder is used instead in the PKI environment, then the OCSP responder certificate itself or the CA certificate of its issuer must be configured in PEM format to enable trusted mode.
A sample ocsp-responder
element for trusted mode is shown
below:
<ocsp-responder validity-period="60" url="http://responder.example.com/ocsp/" > -----BEGIN TRUSTED MODE OCSP CA CERTIFICATE----- MIIDyjCCArKgAwIBAgIEBDH50zANBg... -----END CERTIFICATE----- </ocsp-responder>
If a 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 trusted mode OCSP responders have been configured, even if
the certificate is unknown to the trusted mode OCSP responder.
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.
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.
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.
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).
One of the compliance requirements of the US Department of Defense Public-Key
Infrastructure (DoD PKI) is to have the Digital Signature bit set in the Key Usage
of the certificate. To enforce digital signature in key usage, set the value of
the enable
attribute to yes
. The default is
no
.
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 | |
---|---|
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.
This element enables user authentication using OpenSSH CA-key. It can have two
attributes: name
, and file
.
The name
must contain the name of the CA.
The element must either contain the path to the OpenSSH CA-key file
as a value of the file
attribute, or include the certificate as a
base64-encoded ASCII element.
Generic cert-validation elements do not apply to OpenSSH certificate validation, as there is no revocation checking.
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" /> <openssh-ca-key name="exa-openssh-ca1" file="/etc/ssh2/exa-openssh-ca1.pub" /> </cert-validation>
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 load-control
element defines settings for keeping Tectia Server working
when the load is high, that is, the number of current connections is near
max-connections
(the maximum number of client connections allowed per
servant, specified in the
limits
element). High load might
be caused by a connection flood denial-of-service attack that tries to make the server
unavailable to its intended users by using so much of its resources that normal service
is disrupted.
Load control is implemented by keeping a "white list" of the IP addresses of connections that have had a successful authentication. When Tectia Server starts, the white list is empty. When the server's load is high, connections from IP addresses that are not on the white list (that is, connections that have not recently had a successful authentication) are discarded.
The load-control
element can have three attributes:
enable
, discard-limit
, and
white-list-size
.
The enable
attribute can have a value of yes
or
no
. The default value is yes
(load control is
enabled).
Note | |
---|---|
If the maximum number of client connections allowed per servant is set to 1
( |
When the number of a servant's concurrent connections is not higher than
the value of discard-limit
, the servant accepts connections from any IP
address. When the number of a servant's concurrent connections exceeds the value of
discard-limit
, only connections from IP addresses that are on the
server's white list are accepted. If existing servants cannot accept any more
connections, but the maximum number of servant processes the master server will launch
(specified with the max-processes
attribute of the
limits
element) has not
been reached, the server launches a new servant which will accept new connections.
The allowed value range for discard-limit
is 1 to
max-connections
-1. The default value of
discard-limit
depends on the value of
max-connections
. The default values of discard-limit
for different values of max-connections
are the following:
max-connections | discard-limit default value |
---|---|
1 | N/A (load-control is disabled) |
2-10 | max-connections - 1 |
>10 | 0.9 * max-connections |
If you have not defined any Tectia Server configuration settings (that is, only default
values are used), the value of max-connections
is 256 and the value of
discard-limit
is 230 (that is, 90 percent of
max-connections
).
The white-list-size
attribute specifies the number of IP
addresses on the server's white list. The allowed value range for
white-list-size
is 1 to 10000. The default value is 1000.
connections
BlockThe 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.
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.
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.
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.
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.
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.
This element selects a cipher name
allowed by the server for
data encryption. The supported ciphers are:
3des-cbc
|
arcfour
|
seed-cbc@ssh.com
|
aes128-cbc
|
blowfish-cbc
|
AEAD_AES_128_GCM
|
aes192-cbc
|
twofish-cbc
|
AEAD_AES_256_GCM
|
aes256-cbc
|
twofish128-cbc
|
aes128-gcm@openssh.com,
|
aes128-ctr
|
twofish192-cbc
|
aes256-gcm@openssh.com
|
aes192-ctr
|
twofish256-cbc
| none (no encryption) |
aes256-ctr
|
crypticore128@ssh.com
|
Multiple ciphers can be specified by using multiple cipher
elements.
By default, the server allows crypticore128@ssh.com
(on
Windows and Linux x86), aes128-ctr
, aes192-ctr
,
and aes256-ctr
.
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.
This element selects a MAC name
allowed by the server for
data integrity verification. The supported MAC algorithms are:
hmac-sha1
|
hmac-md5-etm@openssh.com
|
hmac-sha1-96
|
hmac-md5-96-etm@openssh.com
|
hmac-sha2-256
|
crypticore-mac@ssh.com
|
hmac-sha256-2@ssh.com
|
hmac-md5
|
hmac-sha224@ssh.com
|
hmac-md5-96
|
hmac-sha256@ssh.com
|
hmac-sha1-etm@openssh.com
|
hmac-sha384@ssh.com
|
hmac-sha1-96-etm@openssh.com
|
hmac-sha2-512
|
hmac-sha2-256-etm@openssh.com
|
hmac-sha512@ssh.com
|
hmac-sha2-512-etm@openssh.com
|
hmac-sha1-etm@openssh.com
|
hmac-md5-etm@openssh.com
|
hmac-sha1-96-etm@openssh.com
|
hmac-md5-96-etm@openssh.com
|
hmac-sha2-256-etm@openssh.com
| none (no data integrity verification) |
hmac-sha2-512-etm@openssh.com
|
Multiple MACs can be specified by using multiple mac
elements.
By default, the server allows the following MAC algorithms:
crypticore-mac@ssh.com
|
hmac-sha1
|
hmac-sha2-256
|
hmac-sha256-2@ssh.com
|
hmac-sha2-512
|
hmac-sha512@ssh.com
|
hmac-sha1-etm@openssh.com
|
hmac-sha2-256-etm@openssh.com
|
hmac-sha2-512-etm@openssh.com
|
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.
This element selects a KEX name
allowed by the server for key
exchange method. The supported KEXs are:
curve25519-sha256 |
curve25519-sha256@libssh.org |
diffie-hellman-group1-sha1 |
diffie-hellman-group14-sha1 |
diffie-hellman-group14-sha224@ssh.com |
diffie-hellman-group14-sha256@ssh.com |
diffie-hellman-group14-sha256 |
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-group16-sha512 |
diffie-hellman-group18-sha512@ssh.com |
diffie-hellman-group18-sha512 |
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 |
ecdh-sha2-nistp256 |
ecdh-sha2-nistp384 |
ecdh-sha2-nistp521 |
Multiple KEXs can be specified by using multiple kex
elements.
By default, the server allows the following KEXs:
diffie-hellman-group-exchange-sha256
|
diffie-hellman-group16-sha512
|
diffie-hellman-group18-sha512
|
diffie-hellman-group14-sha256
|
diffie-hellman-group14-sha256@ssh.com
|
curve25519-sha256
|
curve25519-sha256@libssh.org
|
curve25519-sha256@libssh.org
is not supported in FIPS mode on
any platform. All other supported KEXs can operate in 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
|
ecdh-sha2-nistp256
|
ecdh-sha2-nistp384
|
ecdh-sha2-nistp521
|
For more information on the FIPS-Certified Cryptographic Library, see Cryptographic library.
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:
ecdsa-sha2-nistp256
|
ssh-rsa-sha224@ssh.com
|
ecdsa-sha2-nistp384
|
ssh-rsa-sha256@ssh.com
|
ecdsa-sha2-nistp521
|
ssh-rsa-sha384@ssh.com
|
ecdsa-sha2-nistp256-cert-v01@openssh.com
|
ssh-rsa-sha512@ssh.com
|
ecdsa-sha2-nistp384-cert-v01@openssh.com
|
x509v3-sign-dss
|
ecdsa-sha2-nistp521-cert-v01@openssh.com
|
x509v3-sign-dss-sha224@ssh.com
|
rsa-sha2-256-cert-v01@openssh.com
|
x509v3-sign-dss-sha256@ssh.com
|
rsa-sha2-512-cert-v01@openssh.com
|
x509v3-sign-dss-sha384@ssh.com
|
ssh-ed25519
|
x509v3-sign-dss-sha512@ssh.com
|
ssh-ed25519-cert-v01@openssh.com
|
x509v3-sign-rsa
|
ssh-dss
|
x509v3-sign-rsa-sha224@ssh.com
|
ssh-dss-cert-v01@openssh.com
|
x509v3-sign-rsa-sha256@ssh.com
|
ssh-dss-sha224@ssh.com
|
x509v3-sign-rsa-sha384@ssh.com
|
ssh-dss-sha256@ssh.com
|
x509v3-sign-rsa-sha512@ssh.com
|
ssh-dss-sha384@ssh.com
|
x509v3-ecdsa-sha2-nistp256
|
ssh-dss-sha512@ssh.com
|
x509v3-ecdsa-sha2-nistp384
|
ssh-rsa
|
x509v3-ecdsa-sha2-nistp521
|
ssh-rsa-cert-v01@openssh.com
|
The default host key signature algorithms are:
ecdsa-sha2-nistp256
|
ecdsa-sha2-nistp384
|
ecdsa-sha2-nistp521
|
ecdsa-sha2-nistp256-cert-v01@openssh.com
|
ecdsa-sha2-nistp384-cert-v01@openssh.com
|
ecdsa-sha2-nistp521-cert-v01@openssh.com
|
rsa-sha2-256
|
rsa-sha2-512
|
rsa-sha2-256-cert-v01@openssh.com
|
rsa-sha2-512-cert-v01@openssh.com
|
ssh-ed25519
|
ssh-ed25519-cert-v01@openssh.com
|
ssh-dss-sha256@ssh.com
|
ssh-rsa-sha256@ssh.com
|
x509v3-ecdsa-sha2-nistp256
|
x509v3-ecdsa-sha2-nistp384
|
x509v3-ecdsa-sha2-nistp521
|
x509v3-rsa2048-sha256
|
x509v3-sign-dss-sha256@ssh.com
|
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" />
authentication-methods
BlockThe 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 | |
---|---|
Consider carefully before putting an empty |
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>
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"/>
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 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 | |
---|---|
Consider carefully before putting an empty |
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.
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 | |
---|---|
When creating the certificate selectors, make sure that every
Failing to do this may cause unintended consequences, for example authentication succeeding with many different user names with a single 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.
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.
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.
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.
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.
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 | |
---|---|
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
To check the privilege level of domain accounts on a Windows server in
the |
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, user name, 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.
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 "2048-4096"
(keys from
2048 to 4096 bits match). The range can also be left open, for example
"2048-"
(keys over 2048 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.
On Unix platforms, this selector matches if the user password has expired and should be changed. For more information, see 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.
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.
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.
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:
<auth-publickey require-dns-match="yes" />
Note | |
---|---|
A failure will always result in case of the following configuration
settings: |
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. The supported and default algorithms
are the same as those listed for
hostkey-algorithm
.
A public-key signature algorithm configuration example:
<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:
In the defined authorization file, if such a file exists.
In the defined authorized_keys
directory, if no
authorization file is available or the defined file does not include a
matching public-key.
In the defined OpenSSH authorized-keys file, if no matching key was found in the Tectia -related authorization file or key directory.
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.
In the default public-key storage location, if none of the previous settings was made.
For more information, see User Authentication with Public Keys.
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).
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.
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.
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.
This element sets the keyboard-interactive password submethod in use.
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.
This element sets the keyboard-interactive RADIUS submethod in use.
The element can contain multiple radius-server
child
elements.
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.
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>
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.
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 | |
---|---|
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.
This element defines an external application to supplement authentication. Tectia Server uses the Tectia Mapper protocol (for more information, see Appendix E) to communicate with the external application.
The mapper
element takes two attributes:
command
(mandatory) and timeout
(optional).
The command
attribute specifies the command for running the
external application.
Caution | |
---|---|
The external application will be launched under root privileges. |
You can use timeout
to set the time limit for the external
application to exit. The allowed value range is 1 to 3600 seconds, and the default
value is 15 seconds. If the application hangs, Tectia Server will not kill it.
Tectia Server sends the following data from its blackboard to the external application:
ip-fqdn
: The domain the client is connecting from
ip-addr
: The client's IP address
ip-port
: The port number the client is connecting
from
interface-port
: The port the server is listening
on
session-id=1
: Session ID
user
: The user's name
user-name-no-domain
: The user's name without the domain
part
user-group
: User group
version-string
: The string sent by the client in version
exchange
Additionally, when certificate authentication is used, also the following data are sent:
certificate-issuer-name
: The Issuer Name
attribute read from the certificate
certificate-subject-name
: The Subject
Name
attribute read from the certificate
certificate-serial-number
: The Serial
Number
attribute read from the certificate
For the authentication to succeed, the external application must return
"success
" and an exit status 0. For more
information on the parameters allowed by Tectia Mapper Protocol, see Parameters.
The authentication will fail if the defined external application does not exist, or is killed by timeout, or if it returns an exit value other than 0.
For examples of how to use the mapper
element in
authentication, see Example with Certificate
Authentication and Example with Password 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.
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="2048-4096" /> </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 2048 to 4096 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 | |
---|---|
Specifying an explicit |
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.
services
BlockThe 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
).
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.
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>
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 | |
---|---|
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. |
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.
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.
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 | |
---|---|
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 |
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" 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.
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"> <attribute name="home" value="%USERPROFILE%" /> </subsystem>
For more information on virtual folders, see Defining SFTP Virtual Folders (Windows).
On Unix, you can use the attribute
element to define a
umask for the SFTP subsystem to overwrite the default file mode creation
mask for the SFTP server. The value defined in the server configuration file
takes precedence over any other umask settings, for example any umask
settings in .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 for all users to be
0022:
<subsystem type="sftp" application="sft-server-g3"> <attribute name="umask" value="0022" /> </subsystem>
If you want to set different umasks for specific users or user groups, define the umask in a rule for the user or user group, for example:
<services> <group name="sftusers"> <selector> <user name="jsmith" /> </selector> </group> <rule group="sftusers"> <subsystem type="sftp" action="allow" application="sft-server-g3"> <attribute name="umask" value="0022" /> </subsystem> </rule> </services>
Note | |
---|---|
If no umask is defined in the server configuration file, the umask that will be used depends on the user's client and shell as follows:
|
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 | |
---|---|
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).
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).
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).
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
,
dst
and mapper
elements. Note that in each
rule, you can define either src
and/or dst
, or
mapper
; you cannot use mapper
in the same rule
with src
and dst
.
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.
Note that SSH clients may spoof their source address, making this method somewhat unreliable in environments with untrusted clients.
The tunnel-src matches tunnel-source addresses. In other words this matches to the address from which the tunnel starts. In scenarios such as chained tunneling, this may differ from the src reported by clients using the tunnel.
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.
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
).
This element defines the use of an external application to verify information for local tunneling connections. Tectia Server uses the Tectia Mapper protocol (for more information, see Appendix E) to communicate with the external application.
The mapper
element takes two attributes:
command
(mandatory) and timeout
(optional).
The command
attribute specifies the external
application which is the executable of the subsystem.
Caution | |
---|---|
The external application will be launched under administrator (root) privileges. |
You can use timeout
to set the time limit for the
external application to exit. The allowed value range is 1 to 3600 seconds,
and the default value is 15 seconds. If the application hangs, Tectia Server will
not kill it.
Tectia Server sends the following data to the external application:
user=
userid
:username
Specifies the user id and user name
user-privileged=true|false
Specifies whether the user has administrator privileges.
{tunnel-src}addr-ip=
ip-address
Specifies the tunnel's source IP address.
{tunnel-src}port=
port
Specifies the tunnel's source port.
{tunnel-src}addr-fqdn=
FQDN
Specifies the tunnel's source host (fully qualified domain name).
{tunnel-dst}addr-ip=
ip-address
Specifies the tunnel's destination IP address.
{tunnel-dst}port=
port
Specifies the tunnel's destination port.
{tunnel-dst}addr-fqdn=
FQDN
Specifies the tunnel's destination host (fully qualified domain name).
For more information on local tunnels, see Local Tunnels. For examples on using the local tunneling rules in the
ssh-server-config.xml
file, see Local Tunneling Rule Examples.
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.
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.
This selector element specifies the destination addresses 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.
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>
On Unix, Tectia Server enforces the changing of expired passwords.
Tectia Server implicitly adds the following group and rule at the top of the rules and groups in the configuration file:
<group name="passwd-change"> <selector> <user-password-change-needed /> </selector> </group> <!-- 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>
Therefore, when users whose passwords have expired attempt to log in, 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.
Note that the user needs an SSH terminal client to be able to change the password.
You can overwrite the implicitly added handling of expired passwords by defining a group
named passwd-change
and adding your own rule for it.
Note | |
---|---|
Tectia Server enforces the changing of expired passwords also when the configuration
file contains a group that is not named |
Note | |
---|---|
In Tectia Server 6.4.9 and earlier it was possible to manually add rules for the handling of
expired passwords, which made it possible to accidentally allow services for users after
their password had expired. If you want the password handling to behave as in Tectia Server 6.4.9
or earlier, define a group named <group name="passwd-change"> <selector> <user name="invalid-user-name-does-not-exist" /> </selector> </group> Add this group as the last
This will prevent Tectia Server from implicitly adding a |
On Windows, 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 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 | |
---|---|
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 log on otherwise using password authentication (see Empty/Blank Passwords in User Authentication with Passwords). |
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.