[Contents] [Index]

About This Document >>     Installing SSH Tectia Server for IBM z/OS >>     Using 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 >>             Server Configuration             Client Configuration         User Authentication with Passwords         User Authentication with Public Keys in File >>         User Authentication with Certificates >>         Host-Based User Authentication >>         User Authentication with Keyboard-Interactive >>     Troubleshooting SSH Tectia Server for IBM z/OS >>     Examples of Use >>     Man Pages >>     Log Messages >>

Client Configuration

The client programs can also be configured to support public-key or certificate authentication or both. The configuration can be different for each host that the client will connect to. If the negotiated server authentication method is RSA certificate, and a trusted key provider is configured, the client uses SAF and, optionally, the SSH Tectia validator to validate the remote server's certificate.

Certificates Stored in File

To configure the client to trust the server's certificate, perform the following tasks:

1. Copy the CA certificate(s) to the client machine. You can either copy the X.509 certificate(s) as such, or you can copy a PKCS #7 package including the CA certificate(s).

   Certificates can be extracted from a PKCS #7 package by specifying the -7 flag with ssh-keygen2.

2. Define the CA certificate(s) to be used in host authentication in the /etc/ssh2/ssh2_config (or $HOME/.ssh2/ssh2_config) file:

   HostCA test-ca1.crt HostKeys.Cert.Required no

   Only one CA certificate can be defined per HostCA keyword. The client will only accept certificates issued by the defined CA.

   Setting the HostKeys.Cert.Required option to yes defines that the server must authenticate with a certificate or else the authentication will fail.

3. Also define the LDAP server(s) used for CRL checks in the ssh2_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.

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

Certificates Stored in SAF

To configure the client to trust the server's SAF certificate, perform the following tasks. Replace the names and IDs with those appropriate to your system:

1. Define the certificate validation method in the /etc/ssh2/ssh2_config (or $HOME/.ssh2/ssh2_config) file. The validation method can be either saf, tectia, or both (saf,tectia).

   HostKeys.Cert.ValidationMethods tectia|saf|saf,tectia HostKeys.Cert.Required yes

   If saf is specified, RACF/SAF is used for validating server host certificates. The server certificates must be found in a trusted key ring defined by the HostKeysEkProvider 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 is used for validating server host certificates. The server certificates must be issued by a trusted certification authority defined in the HostCA, HostCANoCRLs, HostCAEkProvider, or HostCAEkProviderNoCRLs keywords. If both values are specified, the RACF/SAF validation is performed first and after that the SSH Tectia validation. The server certificates must be found in a trusted key ring defined by the HostKeysEkProvider 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. 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 HostKeys.Cert.ValidationMethods. If saf,tectia is selected, both sets of steps need to be completed. Setting the HostKeys.Cert.Required option to yes defines that the server must authenticate with a certificate or else the authentication will fail.
2. (SAF validation) Get the server host certificate and store it to a dataset, for example 'SERVER1.CRT'.
3. (SAF validation) To add the server certificate into SAF, give the following TSO commands:

   RACDCERT ID(USER) ADD('SERVER1.CRT') TRUST WITHLABEL('SERVER1')
   RACDCERT ID(USER) ADDRING(SSH-HOSTKEYS)
   RACDCERT ID(USER) CONNECT(ID(USER) LABEL('SERVER1') RING(SSH-HOSTKEYS) 
     USAGE(PERSONAL))
   RACDCERT ID(USER) LISTRING(SSH-HOSTKEYS)
   

4. (SAF validation) For the settings to take effect, give the following TSO command:

   SETROPTS RACLIST(DIGTCERT) REFRESH
   

5. (SSH Tectia validation) Get the CA certificate and store it to a dataset, for example 'HOSTCA.CRT'.
6. (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(ID(SSHD2) CERTAUTH LABEL('HOSTCA') 
     RING(SSH-HOSTCA) USAGE(CERTAUTH))
   RACDCERT ID(SSHD2) LISTRING(SSH-HOSTCA)
   

7. (SSH Tectia validation) For the settings to take effect, give the following TSO command:

   SETROPTS RACLIST(DIGTCERT) REFRESH
   

8. (SAF validation) If SAF validation is used, define the z/OS SAF external key provider that contains the server host certificates with the HostKeysEkProvider keyword:

   HostKeysEkProvider "zos-saf:KEYS(ID(USER) RING(SSH-HOSTKEYS))"

9. (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:

   HostCAEkProvider "zos-saf:KEYS(ID(SSHD2) RING(SSH-HOSTCA))"

10. (SSH Tectia validation) If SSH Tectia validation is used, define also the LDAP server(s) used for CRL checks. 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.

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.