Appendix A. Client Authentication Mechanisms

Running the Co:Z SFTP client and/or the Co:Z Launcher 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 SFTP or Co:Z Launcher jobs.

Interactive password: Section A.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 A.3, “OpenSSH SSH_ASKPASS authentication”.
Conventional OpenSSH keypairs: Section A.2, “OpenSSH keypair authentication”.
RACF Digital Certificates: Section A.4, “RACF Digital Certificate authentication”.

A.1 Interactive password authentication

This is the simplest form of OpenSSH client authentication and requires no additional setup. It can only be used from a terminal (Unix TTY) 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 interactive shell invocations of Co:Z SFTP.

Note: The IBM z/OS OpenSSH ssh client tools are supported from a TSO OMVS shell session, but do not allow a password to be entered from a 3270 terminal.

A.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: 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 rsa -b 2048
Generating public/private rsa key pair.
Enter file in which to save the key (/home/<userid>/.ssh/id_rsa): <enter>
Enter passphrase (empty for no passphrase): <enter>
Enter same passphrase again: <enter>
Your identification has been saved in /home/<userid>/.ssh/id_rsa.
Your public key has been saved in /home/<userid>/.ssh/id_rsa.pub.
The key fingerprint is:
dd:ff:00:87:43:11:fa:7b:0d:84:3a:19:3b:7f:5d:2e <userid>@<host>
The key's randomart image is:
+--[ RSA 2048]----+
|oEoo .           |
|o.. + o .        |
|.  ..= o .       |
|.   .o=o.        |
|.   ...o+.       |
| . .   ...       |
|  o     o        |
| o     o         |
|  .              |
+-----------------+

The private key file id_rsa 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_rsa.pub authorized_keys
Uploading id_rsa.pub to /home/sgoetze/.ssh/authorized_keys
id_rsa.pub                               100%  601     0.6KB/s   00:00
sftp> quit
        
```
Note: If you are adding more than one public key to authorized_keys, then you must log in to the remote system and append the new public key line to authorized_keys. Be careful that you don't replace an existing authorized_keys file.
Note: The authorized_keys file, the .ssh directory, and the home directory must not be writable by any user other than the owning userid. For details on required file permissions, see the section OpenSSH files Quick Reference / User-generated files in IBM z/OS OpenSSH User's Guide.
Note: For more information on using SSH key authentication, see our webinar archives: IBM Ported Tools for z/OS: OpenSSH - Key Authentication.

A.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.

Using SSH_ASKPASS with OpenSSH requires that other ssh settings and environment variables are configured. The SFTPSAMP and RUNSFTP sample JCL members illustrate how to do this with Co:Z SFTP; the RUNLNCHP sample JCL shows how for Co:Z Launcher. With these samples, a dataset must be created (e.g.)//HLQ.PASSWD(SITE1) that contains a single line with the password starting in the first column and without line numbers. The dataset should be protected with RACF so that it cannot be read except by the required jobs.

A.4 RACF Digital Certificate authentication

Traditional OpenSSH keypairs and SSH_ASKPASS are convenient, but some sites have strict policies about keeping key material in RACF (or another security package), or even ICSF hardware. The z/OS Communcations Server FTP command can exploit SAF/RACF Digital Certificates for authentication and encryption. z/OS OpenSSH allows you to use keys that are stored in SAF/RACF certificates.

An existing SAF/RACF key ring 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 Key Ring 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.

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 key ring MY-RING.

It is also possible to skip creating a key ring - any certificate automatically belongs to the user's virtual key ring, and may be referenced by using the special key ring name "*". For more information on using SAF/RACF key rings with OpenSSH, see our webinar archives: IBM Ported Tools for z/OS: OpenSSH - Using Key Rings.

//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')                                   + 
             )                                             + 
             NOTAFTER(DATE(2026-12-31))                    + 
             WITHLABEL('MY-CERT')                          + 
             ICSF                                            
                                                                            
 /* Create a KEYRING for the user (skip for virtual keyring) */
 RACDCERT ID(COZUSER) ADDRING(MY-RING)                       
                                                             
 /* Connect the certificate to the ring (skip for virtual)   */
 RACDCERT ID(COZUSER) CONNECT (                            + 
                           ID(COZUSER)                     + 
                           LABEL('MY-CERT')                + 
                           RING(MY-RING)                   + 
                           DEFAULT                         + 
                           USAGE(PERSONAL) ) 
 /* Refresh if RACLISTed                                   */
 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.
	Specifies the expiry date of the certificate, otherwise it defaults to one year.
	Optional keywords `ICSF` or `PCICC`, may be specified. When not specified, the generated certificate is stored in the RACF database as a non-ICSF RSA key. When one of `ICSF` or `PCICC` is specified, the certificate generated is stored in the ICSF PKA key data set. The `ICSF` and `PCICC` keywords require ICSF to be started as well as CSFKEYS authorities. For more information, see: "z/OS ICSF Administrator's Guide SA22-7251" - "Using RACF to protect Keys and Services". Note: If using `ICSF` or `PCICC`, you will only be able to use the Co:Z `saf-ssh-agent`, and not the IdentityKeyRingLabel support in z/OS OpenSSH.
	Makes this certificate the default in the ring. This allows the user to specify just the key ring 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 key ring and certificate, the user must have the following SAF/RACF permissions:
- CLASS(FACILITY) IRR.DIGTCERT.LISTRING ACCESS(READ)
- CLASS(CSFSERV) CSFDSG ACCESS(READ)
- CLASS(CSFSERV) CSFDSV ACCESS(READ)
Public key extraction is performed using IBM z/OS OpenSSH ssh-keygen:
```
$ _ZOS_SSH_KEY_RING_LABEL="MY-RING MY-CERT" ssh-keygen -y > cozuser_saf.pub 
```
Note: An administrator may export the key of a another user by prefixing the key ring name with USERID/. In order to do this, the administrator must have UPDATE access to the IRR.DIGTCERT.LISTRING SAF permission above.
Note: READ access to the CLASS(FACILITY) IRR.DIGTCERT.LISTRING resource allows the user to use any key ring the he or she owns. It is also possible to use ring-specific authorization, using CLASS(RDATALIB). See the section "Managing key rings and restricting access to them" in IBM z/OS OpenSSH User's Guide for more information.
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 more than one public key to authorized_keys, then you must log in to the remote system and append the new public key line to authorized_keys. Be careful that you don't replace an existing authorized_keys file.
Note: The authorized_keys file, the .ssh directory, and the home directory must not be writable by any user other than the owning userid. For details on required file permissions, see the section "OpenSSH files Quick Reference / User-generated files" in IBM z/OS OpenSSH User's Guide
Using a SAF/RACF certificate for SSH authentication:
- with Co:Z SFTP client:
```
ZOS$ cozsftp -k MY-RING:MY-CERT  cozuser@linux1.myco.com
      	
```
  (see also the SFTPSAMP or RUNSFTPK sample JCL)
- with Co:Z Launcher:
```
//COZCFG DD * 
saf-cert=MY-RING:MY-CERT 
      	
```
  (see also the RUNLNCHK sample JCL)

Renewing RACF self-signed certificates

You may wish to renew/extend a certificate used with OpenSSH, using the same self-signed key. Note that certificates must be renewed prior to expiration, or a new keypair will be generated, which will require that the new public key be stored on the remote system in the user's authorized_keys file. The following commands can be executed by the owning user before the certificate expires. The owning user must have FACILITY authorities. Refer to "z/OS Security Server RACF Command Language Reference" for additional information.

DELETE 'SYSADM.CERT.REQ' 

RACDCERT GENREQ(LABEL('MY-CERT'))                         + 
            ID(COZUSER)                                   + 
            DSN('SYSADM.CERT.REQ') 
                                                            
RACDCERT GENCERT('SYSADM.CERT.REQ')                       + 
            ID(COZUSER)                                   + 
            WITHLABEL('MY-CERT')                          + 
            NOTAFTER(DATE(2016-12-31))                    + 
            SIGNWITH(LABEL('MY-CERT'))

Prev		Next
5. Co:Z Launcher Examples	Contents	Appendix B. Problem Determination

Prev		Next
5. Co:Z Launcher Examples	Home	Appendix B. Problem Determination

Components

Downloads

Documentation

License/Support

Co:Z Documentation :: Co:Z Launcher - User's Guide V 8.1.0