Host-Based User Authentication

Using Conventional Public Keys
Using Certificates

Host-based authentication uses the public key of the client machine to authenticate a user to the remote server. Host-based authentication can be used with Tectia Client on Unix. The Tectia Server can be either an Unix or Windows server. Usually also Tectia Server is installed on the client machine.

Host-based authentication provides a non-interactive form of authentication, and is best used in scripts and automated processes, such as cron jobs. Host-based authentication can be used to automate backups and file transfers, or in other situations where a user will not be present to input authentication information.

Caution

	Caution
The nature of any non-interactive login is inherently unsecured. Whenever authentication without user challenge is permitted, some level of risk must be assumed. If feasible, public-key authentication is preferred. Tectia Server provides host-based authentication as a form of non-interactive login that is more secure than the `.rhosts` method used by the Berkeley 'r' commands, but it cannot resolve the inherent lack of security of non-interactive logins.

The nature of any non-interactive login is inherently unsecured. Whenever authentication without user challenge is permitted, some level of risk must be assumed. If feasible, public-key authentication is preferred. Tectia Server provides host-based authentication as a form of non-interactive login that is more secure than the .rhosts method used by the Berkeley 'r' commands, but it cannot resolve the inherent lack of security of non-interactive logins.

This means that you should take aggressive measures to ensure that any client machine set up for host-based authentication is adequately secured, both by software and hardware, to prevent unauthorized logins to the server.

Host-based authentication can be enabled either by using conventional public keys or by using certificates.

	Note
	When FIPS mode is enabled in the Server configuration (for more information, see crypto-lib ), host-based authentication only works if the file `libcrypto.*` (the file extension varies between platforms) resides in `/opt/tectia/lib/shlib/`.

In the following instructions, Server is the remote host running Tectia Server to which you are trying to connect. ServerUser is the user name on Server that you are logging in as. Client is the host running Tectia Client. ClientUser is the user name on Client that should be allowed to log in to Server as ServerUser. With Tectia Client, ClientUser and ServerUser must be the same user names.

Using Conventional Public Keys

Client Configuration

To enable host-based authentication with conventional public keys on the client, do the following as ClientUser:

Generate a host key. If Tectia Server has been installed on the same machine, the host key pair /etc/ssh2/hostkey and /etc/ssh2/hostkey.pub has been generated during installation and you can skip this step. Otherwise, give the following command:
```
# ssh-keygen-g3 -P -H hostkey
```
Optionally, you can define a custom location or name for the host key in the ssh-server-config.xml file. If Tectia Server is not installed on the client host, you can create the configuration file manually and save it in the /etc/ssh2 directory.
Add the following line in the ssh-broker-config.xml file:
```
<authentication-methods>
  <auth-hostbased />
  ...
</authentication-methods>
```
Also other authentication methods can be listed. Place the least interactive method first (this means usually the host-based method).

Server Configuration

Do the following as the server administrator:

Copy the client's /etc/ssh2/hostkey.pub file over to the server. Note that this requires root permissions on the server, and may require root permissions on the client as well.
Tectia Server looks for the host keys to use for host-based authentication in the /etc/ssh2/trusted_hosts directory on Unix and in the "<INSTALLDIR>\SSH Tectia Server\trusted_hosts" directory on Windows.
You have to name the client's public key as follows on the server:
```
client.example.com.ssh-dss.pub
```
In the example, client.example.com is the host name that the client is sending to the server. When the server receives the client's public key, it forms a path based on the host name and the key type (ssh-dss, ssh-rsa, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, or ssh-ed25519) and compares the received public key to the key on the disk. If the public key matches and the user's login name in the remote end matches the name the user is trying to log in on the server, the user is let in after the signature check.
To enable host-based authentication on the server, in the ssh-server-config.xml file, under the authentication-methods element, add an auth-hostbased element:
```
<authentication-methods>
  <authentication action="allow">
    <auth-hostbased require-dns-match="no" />
    ...
  </authentication>
</authentication-methods>  
```
Also other authentication methods can be allowed.
To force an exact match between the host name that the client sends to the server and the client's reverse mapped DNS entry, set the require-dns-match attribute to yes.
In this case, make sure the /etc/hosts file has the fully qualified domain name listed before the short host name, for example:
```
123.123.123.123   client.example.com   client
```
Even if you are not using /etc/hosts as your primary resolver, you may need to add entries to it for the client and the server to allow them to resolve each other's fully qualified domain names (if they are not able to do so otherwise).
Notice that when exact DNS matching is set as required, host-based authentication through NAT (Network Address Translation) will not work.
Using the Tectia Server Configuration tool, host-based authentication can be configured on the Authentication page. See Authentication.
Run ssh-server-ctl to take the new configuration in use. See ssh-server-ctl(8).
Click Apply to take the new settings in use.

To test that host-based authentication works, log in to Client as ClientUser and run the following command:

$ sshg3 ServerUser@server uptime

You should get back the results of uptime on the server.

Using Certificates

It is possible to use a certificate instead of the conventional public-key pair to authenticate the client host.

The endpoint identity check, where the server verifies that the certificate actually belongs to the client that is attempting host-based authentication, is performed according to the following rules:

One of the DNS subject alternative names in the client certificate must match the client's fully qualified domain name obtained by doing a reverse lookup on the client's IP address. The alternative names may have an asterisk (*) as the first component, in which case only the domain part is checked.
If the client's IP address cannot be reverse-mapped, the IP address is compared to the certificate's IP subject alternative names.
If the above checks do not produce a positive result, the certificate's subject name is checked. If it has a CN component that matches the client's reverse-mapped fully qualified domain name or IP address, the certificate is accepted.

Client Configuration

To enable host-based authentication with certificates on Client, make the following settings in the Connection Broker configuration on the client side:

Add the following line in the ssh-broker-config.xml file:
```
<authentication-methods>
  <auth-hostbased />
  ...
</authentication-methods>
```
Also other authentication methods can be listed. Place the least interactive method first (this means usually the host-based method).
Enroll a certificate for Client. See User Authentication with Certificates for more information.
The certificate must contain a dns extension which contains the fully qualified domain name (FQDN) of Client.
Note
The private key associated with the certificate needs to be stored with an empty passphrase.
Define the private key and certificate in ssh-server-config.xml on Client:
```
<params>
  <hostkey>      
    <private file="/etc/ssh2/hostcert" />
    <x509-certificate file="/etc/ssh2/hostcert.crt" />
  </hostkey>
...
</params>
```
If Tectia Server is not installed on Client, create the configuration file manually and save it in the /etc/ssh2 directory.

Server Configuration

Do the following as the server administrator:

Specify the CA certificate in the ssh-server-config.xml file:

<cert-validation>
  <ca-certificate name="exa-ca1" file="/etc/ssh2/exa-ca1.crt" />
  ...
</cert-validation>

In the ssh-server-config.xml file, under the authentication-methods element, add an auth-hostbased element and define the selectors. For example:
```
<authentication-methods>
  <authentication name="hostbased-block">
    <auth-hostbased require-dns-match="no" />
    <authentication action="allow" name="hostbased-cert-allow">
      <selector>
         <host-certificate field="ca-list" pattern="exa-ca1" />
         <host-certificate field="issuer-name" pattern="C=FI, O=SSH, CN=*" />
         <host-certificate field="serial-number" pattern="123456" />
         <host-certificate field="altname-ip" pattern="10.0.1.10" />
         <host-certificate field="altname-fqdn" pattern="*.ssh.com" />
       </selector>
    </authentication>
    <authentication action="deny" />
  </authentication>
</authentication-methods>  
```
The host-based authentication with certificates can be restricted using the following field attributes in the selector:
- ca-list: The pattern is a comma-separated list of CA names. The names that are defined in the ca-certificate element are used.
- issuer-name: The pattern is the required certificate issuer name in LDAP DN (distinguished name) string format. The issuer name may contain glob patterns ('*' and '?') but only in the component values, not names. For example, "C=FI, O=SSH, CN=*" is a legal pattern, but "C=FI, *=SSH, CN=TestCA" is not).
- subject-name: The pattern is the required subject name in LDAP DN (distinguished name) string format. Matching is done in similar manner as with the issuer name described above.
- serial-number: The pattern is the required serial number of the certificate. A combination of issuer name and serial number can be used to uniquely identify a certificate.
- altname-email: The pattern is the e-mail address that must be present in the certificate as a subject alternative name.
- altname-upn: The pattern is the principal name that must be present in the certificate as a subject alternative name.
- altname-ip: The pattern is the IP address that must be present in the certificate as a subject alternative name. Also a range of addresses can be given (for example, 10.1.0.11-10.1.0.61 or 10.1.0.0/8).
- altname-fqdn: The pattern is a list of fully qualified domain names (FQDN) that may contain glob patterns ('*' and '?'). One of the listed domain names must match with a subject alternative name of type FQDN in the certificate.
In addition to matching to the selectors, the certificate must pass the endpoint identity check, described in detail in Using Certificates .
Using the Tectia Server Configuration tool, host-based authentication can be configured on the Authentication page. See Authentication.
Run ssh-server-ctl to take the new configuration in use. See ssh-server-ctl(8).
Click Apply to take the new settings in use.

	Note
	The private key associated with the certificate needs to be stored with an empty passphrase.