Distributing Mainframe User Keys

Administrators and other people can use passwords or public-key pairs with a passphrase-protected private key to access remote machines with Tectia clients from a Telnet or Secure Shell session. They can also use public-key pairs with a null passphrase if they want to run the Tectia client programs in JCL.

Mainframe batch users are accounts that represent applications or subsystems, not people. They are set up with public-key pairs with a null passphrase to enable non-interactive access through JCL to remote servers. One key pair is generated for each batch user. If the batch user has a shared home directory, the key is placed in the shared $HOME/.ssh2 directory, otherwise it is copied to the user's home directories on all the LPARs.

When ssh-keygen-g3 is run with the -P option, which requests a null passphrase, it can be run from the OMVS shell or in JCL. It must be run under the batch user's user ID in order for the file permissions to be set properly. For more information on the ssh-keygen-g3 options, see ssh-keygen-g3(1).

The batch user accesses the remote machine using an account created and administered on the remote machine. The remote username may either be the same as the batch user's RACF user ID, or the same but in lower case, or a different username. Several batch users may use the same remote account. One batch user may use separate accounts on one remote machine for different accesses.

Each batch user's public key must be distributed to all the remote accounts it will be accessing. The way the public key is set up differs between Tectia and OpenSSH. The ssh-keydist-g3 script must be told which type of server the remote machine has. The server must be running when ssh-keydist-g3 is run.

ssh-keydist-g3 uses password authentication for this initial access to the remote server. The password for the remote account can be entered in a dataset or in a file. See Password in File and Password in Dataset for instructions. The filename is entered as one of the options in the ssh-keydist-g3 command.

The other options needed on the ssh-keydist-g3 command line are the remote account username, the remote host DNS name or IP address, and the type of the remote Secure Shell server (Tectia Server on Unix, Tectia Server on Windows, Tectia Server for IBM z/OS on mainframe, or OpenSSH on Unix).

Examples of Distributing User Keys

The following examples illustrate using ssh-keydist-g3 for distributing user keys.

Example 1: Public-Key Upload to Unix OpenSSH Server from USS Shell

This command creates a 1024-bit RSA key with an empty passphrase and uploads it to a Unix server running OpenSSH, including the necessary conversions. Public-key upload uses password-from-file for authentication. A log of the operation is stored under /tmp. The example assumes that the server host key has already been fetched and verified.

$ ssh-keydist-g3 --key-type rsa --key-bits 1024 --empty-passphrase \
   --remote-user userid --password-file /home/userid/passwd_file \
   --user-key-log /tmp/my_log_file --openssh-unix open_server.example.com

Example 2: Public-Key Upload to Unix OpenSSH Server Using JCL

This example KEYDIST from SAMPLIB presents a JCL script that does the same steps as the USS command in Example 1 above (options are given in short format):

//KEYDIST EXEC PGM=IKJEFT1A,
//             REGION=0M
//SYSTSPRT DD  SYSOUT=*
//STDOUT   DD  PATH='/tmp/&SYSUID.-KEYDIST.out',
//             PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
//             PATHMODE=(SIRUSR,SIWUSR)
//STDERR   DD  PATH='/tmp/&SYSUID.-KEYDIST.err',
//             PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
//             PATHMODE=(SIRUSR,SIWUSR)
//STDENV   DD  DSN=&SYSUID..SSZ.SRVR62.PARMLIB(SSHENV),
//             DISP=SHR
//SYSTSIN  DD  *
  BPXBATCH SH  /opt/tectia/bin/ssh-keydist-g3 +
               -t rsa -b 1024 -P +
               -u userid -p "//'USERID.PASSWD'" +
               -U /tmp/my_log_file +
               -O host1.example.com
/*
//*
//PROUT   EXEC PGM=IKJEFT1A,
//             PARM='OCOPY INDD(STDOUT) OUTDD(STDOUTPR) TEXT'
//SYSTSPRT DD  SYSOUT=*
//SYSTSIN  DD  DUMMY
//STDOUT   DD  PATH='/tmp/&SYSUID.-KEYDIST.out',
//             PATHOPTS=(ORDONLY),
//             PATHDISP=(DELETE,KEEP),
//             PATHMODE=(SIRUSR,SIWUSR)
//STDOUTPR DD  SYSOUT=*,
//             DCB=(LRECL=4000,RECFM=VB)
//*
//*
//PRERR   EXEC PGM=IKJEFT1A,
//             PARM='OCOPY INDD(STDERR) OUTDD(STDERRPR) TEXT'
//SYSTSPRT DD  SYSOUT=*
//SYSTSIN  DD  DUMMY
//STDERR   DD  PATH='/tmp/&SYSUID.-KEYDIST.err',
//             PATHOPTS=(ORDONLY),
//             PATHDISP=(DELETE,KEEP),
//             PATHMODE=(SIRUSR,SIWUSR)
//STDERRPR DD  SYSOUT=*,
//             DCB=(LRECL=4000,RECFM=VB)
//*

Example 3: Public-Key Distribution to Multiple Hosts from USS Shell

This example distributes an existing public key to several remote hosts automatically. Individual user names can be defined for each server. Server type (Tectia Unix, Tectia Windows, Tectia z/OS, OpenSSH) needs to be defined with the flags: -S, -W, -Z, or -O. The example assumes that the relevant server host keys have already been fetched and verified.

In this example you can find four server "blocks":

-O -u user1 open_server.example.com
-S -u user2 tectia_unix.example.com
-W -u user2 tectia_win.example.com
-Z -u user3 tectia_zos.example.com

A password file is defined for each separate user ID. user2 is assumed to have the same password on Unix and Windows. A log of the operation is stored under /tmp.

The command is as follows:

$ ssh-keydist-g3 -f /home/userid/.ssh2/id_rsa_2048_a.pub \
   -U /tmp/userkeys.log \
   -p /home/userid/passwd_file1 \
   -O -u user1 open_server.example.com \
   -p /home/userid/passwd_file2 \
   -S -u user2 tectia_unix.example.com \ 
   -W -u user2 tectia_win.example.com \ 
   -p /home/userid/passwd_file3 \
   -Z -u user3 tectia_zos.example.com