Server Configuration

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

Traditional Public Keys Stored in File

To allow host-based authentication with traditional public keys on Tectia Server for IBM z/OS, perform the following steps as ServerUser:

Create a file named .shosts in the home directory of ServerUser. The contents of this file should be the client's host name, some tabs or spaces, and the user's user name on the client.
```
client.example.com       ClientUser
```
Make sure the .shosts file is owned by ServerUser and its permissions are 0600.
Check that the server user's home directory is owned by the user and its permissions are at most 0755 (or more restrictive, like 0700).
If every user is allowed to write to the directory, there will be nothing to prevent them from overwriting the .shosts file with their own version with an entry for their client user, allowing them to authenticate to Tectia Server as ServerUser.

Do the following as the server administrator:

Copy the client's hostkey.pub file over to the server. Note that this requires root permissions on the client, and optionally on the server as well.
Tectia Server for IBM z/OS is configured by default to look in one of two places on server for the host keys to use for host-based authentication:
```
/opt/tectia/etc/knownhosts
```
OR
```
$HOME/.ssh2/knownhosts
```
The server administrator can edit the UserKnownHosts keyword in the /opt/tectia/etc/sshd2_config file to disable the use of the user-defined known hosts (they are allowed by default).
If you want to allow host-based authentication to all users connecting from the client machine, you can add the public host key to /opt/tectia/etc/knownhosts. Root permissions are required for this method.
If you want to allow host-based authentication only to some users, and if user-defined knownhosts are allowed, then you can instead add the keys to the $HOME/.ssh2/knownhosts directory.
You have to name the client's public key as follows on the server:
```
client.example.com.ssh-rsa.pub
```
In the example, client.example.com is the host name the client is sending to the server. When DefaultDomain has been set on client, this name is always the long host name (FQDN). This gives the server the client's public key so the server can verify the client user's identity based on the public key signature.
In the /opt/tectia/etc/sshd2_config file under the AllowedAuthentications keyword, add hostbased as an allowed method. For example:
```
AllowedAuthentications hostbased,publickey,password
```
If you want to allow multiple authentication methods, place the least interactive method first.
Restart the server as instructed in Restarting and Stopping sshd2.

For more information on the configuration file options, see sshd2_config.

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.

Certificates Stored in File

Tectia Server for IBM z/OS checks the host certificate using SAF and can be configured to do a full PKI validation using the Tectia Certificate Validator (see Server Authentication with Certificates). The certificates of the remote hosts can be entered into SAF as SITE certificates and connected to the key ring configured for host authentication, or they can be issued by a CA that has its CA certificate on the server's key ring.

To allow host-based authentication with certificates on the server, do the following steps as ServerUser:

Create a file named .shosts in the home directory of ServerUser. The contents of this file should be the client's host name, some tabs or spaces, and the user's user name on the client.
```
client.example.com       ClientUser
```

Do the following steps as the server administrator:

In the /opt/tectia/etc/sshd2_config file under the AllowedAuthentications keyword, add hostbased as an allowed method. For example:
```
AllowedAuthentications         hostbased,publickey,password
AuthHostbased.Cert.Required    no
```
If you want to allow multiple authentication methods, place the least interactive method first. Setting the AuthHostbased.Cert.Required option to yes defines that the client host must authenticate with a certificate or else the authentication will fail.
Specify the trusted CA certificate in the ssh_certd_config file:
```
HostCA                         trusted-ca.crt
```
Also define the LDAP server(s) used for CRL checks in ssh_certd_config. If the CA services (OCSP, CRLs) are located behind a firewall, define also the SOCKS server.
```
LdapServers                    ldap://ldap.example.com:389
SocksServer                    socks://fw.example.com:1080
```
Restart the server as instructed in Restarting and Stopping sshd2.

For more information on the configuration file options, see sshd2_config and ssh_certd_config.

Certificates Stored in SAF

To configure the server to allow host-based authentication with SAF certificates, perform the following tasks. Replace the names and IDs with those appropriate to your system:

In the /opt/tectia/etc/sshd2_config file under the AllowedAuthentications keyword, add hostbased as an allowed method. For example:
```
AllowedAuthentications        hostbased,publickey,password
AuthHostbased.Cert.Required   yes
```
If you want to allow multiple authentication methods, place the least interactive method first. Setting the AuthHostbased.Cert.Required option to yes defines that the client host must authenticate with a certificate or else the authentication will fail.

Define the certificate validation method in the /opt/tectia/etc/sshd2_config file. The validation method can be either saf, tectia, or both (saf,tectia).

AuthHostbased.Cert.ValidationMethods tectia|saf|saf,tectia

If saf is specified, RACF/SAF is used for validating client host certificates. The host certificates must be found in a trusted key ring defined by the KnownHostsEkProvider keyword. Note that when only SAF validation is used, the certificate validity period and revocation status are not checked.

If tectia is specified (or the keyword is missing from the configuration), the Tectia Certificate Validator (ssh-certd) is used for validating client host certificates. The host certificates must be issued by a trusted certification authority defined in the HostCA, HostCAEkProvider, or HostCAEkProviderNoCRLs keyword of ssh_certd_config.

If both values are specified, the RACF/SAF validation is performed first and after that the Tectia validation. The host certificates must be found in a trusted key ring defined by the KnownHostsEkProvider keyword. Also the CA certificate of the issuing certification authority must be found in a trusted key ring defined by the HostCAEkProvider or HostCAEkProviderNoCRLs keyword of ssh_certd_config.

	Note
	Several of the following steps are marked either as SAF validation or Tectia validation. These steps are alternatives depending on the value of `AuthHostbased.Cert.ValidationMethods`. If `saf,tectia` is selected, both sets of steps need to be completed.

(Tectia validation) Get the CA certificate and store it to a data set, for example 'HOSTCA.CRT'.

(Tectia validation) To add the CA certificate into SAF, give the following TSO commands:

RACDCERT CERTAUTH ADD('HOSTCA.CRT')TRUST WITHLABEL('HOSTCA')
RACDCERT ID(SSHD2) ADDRING(SSH-HOSTCA)
RACDCERT ID(SSHD2) CONNECT(CERTAUTH LABEL('HOSTCA') RING(SSH-HOSTCA) 
  USAGE(CERTAUTH))
RACDCERT ID(SSHD2) LISTRING(SSH-HOSTCA)

(Tectia validation) For the settings to take effect, give the following TSO command:
```
SETROPTS RACLIST(DIGTCERT) REFRESH
```
(SAF validation) Get the client host certificate and store it to some data set, for example 'CLIENT1.CRT'.

(SAF validation) To add the client host certificate into SAF, give the following TSO commands:

RACDCERT ID(SSHD2) ADD('CLIENT1.CRT') TRUST WITHLABEL('CLIENT1')
RACDCERT ID(SSHD2) ADDRING(SSH-KNOWNHOSTS)
RACDCERT ID(SSHD2) CONNECT(ID(SSHD2) LABEL('CLIENT1')
  RING(SSH-KNOWNHOSTS) USAGE(PERSONAL))
RACDCERT ID(SSHD2) LISTRING(SSH-KNOWNHOSTS)

(SAF validation) For the settings to take effect, give the following TSO command:
```
SETROPTS RACLIST(DIGTCERT) REFRESH
```
(SAF validation) If only SAF validation is used, define the z/OS SAF external key provider that contains the known host certificates with the KnownHostsEkProvider keyword in the /opt/tectia/etc/sshd2_config file:
```
KnownHostsEkProvider           "zos-saf:KEYS(ID(SSHD2)RING(SSH-KNOWNHOSTS))"
```
(Tectia validation) If Tectia validation is used, define the z/OS SAF external key provider that contains the CA certificates with the HostCAEkProvider keyword in the ssh_certd_config file:
```
HostCAEkProvider               "zos-saf:KEYS(ID(SSHD2)RING(SSH-HOSTCA))"
```
(Tectia validation) If Tectia validation is used, define also the LDAP server(s) used for CRL checks in the ssh_certd_config file. If the CA services (OCSP, CRLs) are located behind a firewall, define also the SOCKS server.
```
LDAPServers                    ldap://ldap.example.com:389
SocksServer                    socks://fw.example.com:1080
```
Defining the LDAP server is not necessary if the CA certificate contains a CRL Distribution Point or an Authority Info Access extension.
Restart the server as instructed in Restarting and Stopping sshd2.

For more information on the configuration file options, see sshd2_config. For information on the format of the external key initialization string, see ssh-externalkeys.