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:
- Enroll a certificate for yourself. This can be done, for example, with the
ssh-scepclient command-line tools.Example: Key generation and enrollment using
> ssh-cmpclient INITIALIZE \
-p 62154:secret \
-P generate://ssh2:passphrase@rsa:512/user_rsa \
-s 'C=FI,O=SSH,CN=user;email@example.com' \
-o /home/user/.ssh2/user_rsa \
-S http://fw.example.com:1080 \
'C=FI, O=SSH, CN=Test CA 1'
For more information on the
ssh-scepclient, see Appendices ssh-cmpclient and ssh-scepclient.
- Make sure that public-key authentication is enabled in the
- Specify the private key of your software certificate in the
$HOME/.ssh2/identification file. The certificate itself will be read from
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:
- To create a user key in SAF, give the following TSO commands:
RACDCERT ID(USER) GENCERT SUBJECTSDN(CN('User') OU('RD') O('EXAMPLE'))
RACDCERT ID(USER) LIST
- Give the following TSO command to generate the certification request:
RACDCERT ID(USER) GENREQ(LABEL('USER')) DSN('USER.CRT.REQ')
- Use the PKCS#10 certification request in the dataset
'USER.CRT.REQ' to enroll the certificate. The actual steps depend on your CA setup.
- After the enrollment is completed, store the received certificate to a dataset, for example
- 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)
RACDCERT ID(USER) LISTRING(USER)
- For the settings to take effect, give the following TSO command:
SETROPTS RACLIST(DIGTCERT) REFRESH
- Define the z/OS SAF external key provider and its initialization string with the
EkInitString keywords in the
EkInitString "KEYS(ID(%U) RING(%U))"
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.