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.

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

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.