Appendix B. Client Authentication Mechanisms

Running the Co:Z Launcher and/or the Co:Z SFTP client requires that the z/OS ssh client can authenticate with the Target System ssh server. Several authentication choices are available from z/OS; site policies will usually dictate which is best.

One of the following authentication mechanisms should be performed on z/OS from each userid that will be used to execute the Co:Z Batch jobs.

Interactive password: Section B.1, “Interactive password authentication”. Note: this mechanism requires user keyboard interaction, so it will not work in batch. It should only be used for command line invocations of the Co:Z SFTP client.
OpenSSH ASK_PASS (read a password from a dataset): Section B.3, “OpenSSH SSH_ASKPASS authentication”.
Conventional OpenSSH keypairs: Section B.2, “OpenSSH keypair authentication”.
RACF Digital Certificates: Section B.4, “RACF Digital Certificate authentication”.

B.1 Interactive password authentication

This is the simplist form of OpenSSH client authentication and requires no additional setup. It can only be used from a terminal connected shell where the user can supply the Target System password. Due to this requirement, it is not suitable for z/OS batch programs and is therefore not an option for running the Co:Z Launcher or batch Co:Z SFTP. It is suitable for shell invocations of Co:Z SFTP cozsftp.

B.2 OpenSSH keypair authentication

This is the conventional mechanism for performing OpenSSH client authentication. A public/private key pair is generated on z/OS. The private key is kept (protected) in the user's /.ssh directory. The public key is stored on each target system in the user's /.ssh/authorized_keys file. The following steps describe how to generate and use an OpenSSH keypair:

Note: a z/OS shell invoked under telnet, rlogin, or ssh must be used for key generation. Don't attempt to do this under an OMVS shell, since the ssh commands are generally not supported under OMVS.

Note: Proceed with caution if you have more than one userid mapped to the same uid number (an unfortunately common occurrence on z/OS USS). The default key storage home directory is hard to predict.

Generate a keypair using ssh-keygen:

$ mkdir ~/.ssh
$ chmod 700 ~/.ssh
$ ssh-keygen -t dsa
Generating public/private dsa key pair.
Enter file in which to save the key (/home/<userid>/.ssh/id_dsa): <enter>
Enter passphrase (empty for no passphrase): <enter>
Enter same passphrase again: <enter>
Your identification has been saved in /home/<userid>/.ssh/id_dsa.
Your public key has been saved in /home/<userid>/.ssh/id_dsa.pub.
The key fingerprint is:
dd:ff:00:87:43:11:fa:7b:0d:84:3a:19:3b:7f:5d:2e <userid>@<host>

The private key file id_dsa will be generated without a passphrase so that Co:Z can run in batch. It is therefore important that this file is protected with file permissions and/or ACLs that only allow the owning userid to read the file.

Move a copy of the public key to the target system:

ZOS$ sftp -oPort=<port>  cozuser@linux1.myco.com
Connecting to n.n.n.n...
cozuser@linux1.myco.com's password:  ******
sftp>  ascii
Sets the file transfer type to ASCII.
sftp>  cd .ssh
sftp>  put -p id_dsa.pub authorized_keys
Uploading id_dsa.pub to /home/sgoetze/.ssh/authorized_keys
id_dsa.pub                               100%  601     0.6KB/s   00:00
sftp> quit

Note: If you are adding public keys from more than one z/OS userid to authorized_keys, then you must append each key rather than replacing the file as shown above.

B.3 OpenSSH SSH_ASKPASS authentication

OpenSSH supports the use of the SSH_ASKPASS environment variable to point to a program that will read a password, without keyboard interaction.

A dataset member (e.g.) //HLQ.PASSWD(SITE1) must be created that contains a single line with the password starting in the first column and without line numbers.

B.4 RACF Digital Certificate authentication

Traditional OpenSSH keypairs and SSH_ASKPASS are convenient, but some sites have strict policies about keeping user credentials in a SAF facility. The z/OS Communcations Server FTP command can exploit RACF Digital Certificates for authentication and encryption. The Co:Z toolkit provides a similar capability via its saf-ssh-agent which can be used in conjunction with a user RACDCERT RSA certificate to provide OpenSSH client authentication.

An existing SAF/RACF Keyring and client certificate set up for use with the z/OS FTP client may be used with Co:Z Launcher and the Co:Z SFTP client.

The following steps describe how to create an RSA RACF Digital Certificate, export its public key in OpenSSH compatible format, and transfer the public key to the target system.

Create a Keyring and RSA Digital Certificate:

Note: In order to create RACF Digital Certificates, certain RACF permissions must be held. This step is typically performed by an administrator; the permissions required are not required for the user to access the certificate (see below). For details, see the chapter RACF and Digital Certificates z/OS Security Server RACF Security Administrator's Guide (SA22-7683).

This JCL is located in RACDCERT member of the COZ.SAMPJCL PDS. It will create an RSA Digital Certificate labeled MY-CERT held in the keyring MY-RING

//COZUSERJ  JOB (),'',MSGCLASS=H,NOTIFY=&SYSUID
//*
//  EXEC PGM=IKJEFT01 
//SYSPRINT DD SYSOUT=* 
//SYSOUT   DD SYSOUT=* 
//SYSTSPRT DD SYSOUT=* 
//SYSTSIN  DD * 
                                                             
 /* Generate a self-signed RSA certificate to use          */
 /* for SSH client authentication.                         */
 /* A certificate signed by your CA will also work.        */
 RACDCERT ID(COZUSER) GENCERT                              + 
             SUBJECTSDN(                                   + 
                CN('First Lastname' )                      + 
                 O('My Company')                           + 
                OU('Development')                          + 
                 C('US')                                   + 
             )                                             + 
             WITHLABEL('MY-CERT') 
                                                                            
 /* Create a KEYRING for the user                          */
 RACDCERT ID(COZUSER) ADDRING(MY-RING)                        
                                                             
 /* Connect the certificate to the ring                    */
 RACDCERT ID(COZUSER) CONNECT (                            +  
                           ID(COZUSER)                     +  
                           LABEL('MY-CERT')                + 
                           RING(MY-RING)                   + 
                           DEFAULT                         +  
                           USAGE(PERSONAL) ) 
 /* Refresh to activate                                    */
 SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH 
                                                             
 /* List the user's certs                                  */
 RACDCERT ID(COZUSER) LIST                                    
//

	Change the string `COZUSER` to the MVS userid that will own and use the certificate.
	Change the subject DSN fields according to your company's standards.
	Makes this certificate the default in the ring. This allows the user to specify just the keyring name in order to access the certificate.

Export an OpenSSH version of the certificate's public key:
Note: This and the remaining steps are performed by the user. In order to access the keyring and certificate, the user must have READ access to the FACILITY class resources:
- IRR.DIGTCERT.LIST
- IRR.DIGTCERT.LISTRING
Public key extraction is performed using Co:Z's saf-ssh-agent and the -x option. If the -f option is specified, the key is extracted to the specified filename. Otherwise it is written to stdout.
```
$ saf-ssh-agent -x -f cozuser_saf.pub MY-RING:MY-CERT
```
Note: An administrator may export the key of a another user by prefixing the keyring name with USERID/. In order to do this, the administrator must have UPDATE access to the SAF classes listed above.

Move a copy of the public key to the target system:

ZOS$ sftp -oPort=<port>  cozuser@linux1.myco.com
Connecting to n.n.n.n...
cozuser@linux1.myco.com's password:  ******
sftp>  ascii
Sets the file transfer type to ASCII.
sftp>  cd .ssh
sftp>  put -p cozuser_saf.pub authorized_keys
Uploading cozuser_saf.pub to /home/cozuser/.ssh/authorized_keys
cozuser_saf.pub                               100%  601     0.6KB/s   00:00
sftp> quit

Note: If you are adding public keys from more than one z/OS userid to authorized_keys, then you must append each key rather than replacing the file as shown above.

Prev		Next
zsym	Contents	Appendix C. Setting up a test OpenSSH system on z/OS

Prev		Next
zsym	Home	Appendix C. Setting up a test OpenSSH system on z/OS

Co:Z Launcher and Dataset Pipes V 2.0.0