SSH Tectia  
Previous Next Up [Contents] [Index]

    About This Document >>
    Installing SSH Tectia Server for IBM z/OS >>
    Getting Started with SSH Tectia Server for IBM z/OS >>
    Configuring the Server >>
    Configuring the Client >>
    Authentication >>
        Using the z/OS System Authorization Facility
        Server Authentication with Public Keys in File >>
        Server Authentication with Certificates >>
        User Authentication with Passwords
        User Authentication with Public Keys in File >>
        User Authentication with Certificates >>
        Host-Based User Authentication >>
            Client Configuration
            Server Configuration
            Optional Configuration Settings
        User Authentication with Keyboard-Interactive >>
        Distributing Public Keys Using the Key Distribution Tool >>
    File Transfer Using SFTP >>
    File Transfer Using Transparent FTP Tunneling >>
    Tunneling on the Command Line >>
    Troubleshooting SSH Tectia Server for IBM z/OS >>
    Advanced Information >>
    Man Pages >>
    Log Messages >>

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 the server, do the following steps as ServerUser:

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

    Make sure the .shosts is owned by ServerUser and its permissions are 0600.

  2. 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 SSH Tectia Server as ServerUser.

Do the following steps as the server administrator:

  1. Copy the client's /etc/ssh2/hostkey.pub file over to the server. Note that this requires root permissions on the client, and optionally on the server as well.

    SSH Tectia Server is configured by default to look in one of two places on server for the host keys to use for host-based authentication:

    /etc/ssh2/knownhosts
    

    OR

    $HOME/.ssh2/knownhosts
    

    The server administrator can edit the UserKnownHosts keyword in the /etc/ssh2/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 /etc/ssh2/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 hostname the client is sending to the server. When DefaultDomain has been set on client, this name is always the long hostname (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.

  2. In the /etc/ssh2/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.
  3. Restart the server as instructed in Section Restarting 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:

$ ssh2 ServerUser@server uptime

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

Certificates Stored in File

The server checks the host certificate using SAF and can be configured to do a full PKI validation using the SSH Tectia 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:

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

Do the following steps as the server administrator:

  1. In the /etc/ssh2/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.
  2. Specify the trusted CA certificate in ssh_certd_config file:
    HostCA                        trusted-ca.crt
    
  3. Also define 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
    
  4. Restart the server as instructed in Section Restarting 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:

  1. In the /etc/ssh2/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.
  2. Define the certificate validation method in the /etc/ssh2/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 SSH 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 SSH 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 SSH Tectia validation. These steps are alternative depending on the value of AuthHostbased.Cert.ValidationMethods. If saf,tectia is selected, both sets of steps need to be completed.
  3. (SSH Tectia validation) Get the CA certificate and store it to a dataset, for example 'HOSTCA.CRT'.
  4. (SSH 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)
    
  5. (SSH Tectia validation) For the settings to take effect, give the following TSO command:
    SETROPTS RACLIST(DIGTCERT) REFRESH
    
  6. (SAF validation) Get the client host certificate and store it to some dataset, for example 'CLIENT1.CRT'.
  7. (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)
    
  8. (SAF validation) For the settings to take effect, give the following TSO command:
    SETROPTS RACLIST(DIGTCERT) REFRESH
    
  9. (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 /etc/ssh2/sshd2_config file:
    KnownHostsEkProvider  "zos-saf:KEYS(ID(SSHD2) RING(SSH-KNOWNHOSTS))"
    
  10. (SSH Tectia validation) If SSH 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))"
    
  11. (SSH Tectia validation) If SSH 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.
  12. Restart the server as instructed in Section Restarting sshd2.

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

Previous Next Up [Contents] [Index]


[ Contact Information | Support | Feedback | SSH Home Page | SSH Products ]

Copyright © 2007 SSH Communications Security Corp.
This software is protected by international copyright laws. All rights reserved.
Copyright Notice