[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 >>         User Authentication with Passwords         User Authentication with Public Keys in File >>         User Authentication with Certificates >>             Client Configuration             Server Configuration         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

When using a certificate, the client can start authentication without presenting a username. If the username given by the user matches the value of the IdentityDispatchUsers option in the server configuration, the name retrieved from SAF will be used. However, it is not allowed to change the user ID during the authentication process. For example, if the server requires first certificate authentication and then password authentication, the user must give the password for the user that SAF determines from the certificate.

SAF determines the z/OS username using one-to-one certificate to user ID association, certificate name filtering, or the HostIdMappings certificate extension. SSH Tectia Server for IBM z/OS does not participate in this processing.

The server checks the user certificate using SAF and can be configured to do a full PKI validation using the SSH Tectia Certificate Validator.

The SSH Tectia Server for IBM z/OS client programs use SAF certificates when the configuration includes certificate authentication and a private key provider. The configuration specifies which keys and certificates the client will offer.

Certificates Stored in File

To configure the client to authenticate itself with an X.509 certificate, perform the following tasks:

1. Enroll a certificate for yourself. This can be done, for example, with the ssh-cmpclient or ssh-scepclient command-line tools. Example: Key generation and enrollment using ssh-cmpclient:

   > ssh-cmpclient INITIALIZE \ 
      -p 62154:secret \
      -P generate://ssh2:passphrase@rsa:512/user_rsa \ 
      -s 'C=FI,O=SSH,CN=user;email=user@example.org' \
      -o /home/user/.ssh2/user_rsa \
      -S http://fw.example.com:1080 \
      http://pki.example.com:8080/pkix/ \
      'C=FI, O=SSH, CN=Test CA 1'
   

   For more information on the ssh-cmpclient and ssh-scepclient, see Appendices ssh-cmpclient and ssh-scepclient.
2. Make sure that public-key authentication is enabled in the /etc/ssh2/ssh2_config (or $HOME/.ssh2/ssh2_config) file.

   AllowedAuthentications publickey

3. Specify the private key of your software certificate in the $HOME/.ssh2/identification file.

   CertKey user_rsa

   The certificate itself will be read from user_rsa.crt.

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

Certificates Stored in SAF

To use SAF certificates for user authentication, do the following steps. Replace the names and IDs with those appropriate to your system:

1. To create a user key in SAF, give the following TSO commands:

   RACDCERT ID(USER) GENCERT SUBJECTSDN(CN('User') OU('RD') O('EXAMPLE')) SIZE(1024) WITHLABEL('USER') RACDCERT ID(USER) LIST

2. Give the following TSO command to generate the certification request:

   RACDCERT ID(USER) GENREQ(LABEL('USER')) DSN('USER.CRT.REQ')

3. Use the PKCS#10 certification request in the dataset 'USER.CRT.REQ' to enroll the certificate. The actual steps depend on your CA setup.
4. After the enrollment is completed, store the received certificate to a dataset, for example 'USER.CRT'.
5. To connect the new certificate to a key ring, give the following TSO commands:

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

6. For the settings to take effect, give the following TSO command:

   SETROPTS RACLIST(DIGTCERT) REFRESH
   

7. Define the z/OS SAF external key provider and its initialization string with the EkProvider and EkInitString keywords in the /etc/ssh2/ssh2_config (or $HOME/.ssh2/ssh2_config) file:

   EkProvider zos-saf EkInitString "KEYS(ID(%U) RING(%U))"

   The EkInitString keyword can contain special strings in the key specification that are mapped according the following list:
   • %U = user name
   • %IU = user ID
   • %IG = user group ID

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.