Creating and using pass tickets on z/OS.

As part of looking into secure way of logging on to z/OS, I looked into pass tickets (because Zowe can generate a pass ticket to connect to other sub-systems). I set up the simplest (and oldest) pass ticket configuration. The best practice is to use enhanced pass tickets, and store values encrypted. With enhanced pass tickets you can specify the validity period of the pass ticket – it defaults to 10 minutes. I wanted the easiest way, so I used the older technique.

With thanks to Philippe Richard for his many comments, I’ve incorporated them in the post.

I had the usual struggles with getting the C program to work, but overall it was quite easy.

I successfully used the RACF callable function IRRSPK00 R_ticketserv (IRRSPK00).

You pass a userid and an application name and the service returns a temporary, time limited, password for that userid and application.

The application name depends on what system you are logging on to. I submitted a job from TSO on system with SYSID S0W1, and the application name was TSOS0W1. You cannot use a pass ticket for TSO on a CICS system, because the application names will not match.

When you are under TSO and enter submit the application is still TSO, so use TSOS0W1.

If, for instance, you try to submit a job through the internal reader, then it will use application MVSS0W1.

For example:

//INTRDRS1 EXEC PGM=IEBGENER 
//SYSUT1 DD DSN=PASSTIKT.ENHC.JCL(REFRESH), 
// DISP=SHR 
//SYSUT2 DD SYSOUT=(,INTRDR) 
//* 
//SYSPRINT DD SYSOUT=* 
//SYSIN DD DUMMY

and in member REFRESH, you have a job with userid=racf admin user, password= where you substitute the passticket, like:

//SYSADMX JOB 30000000,’MVS JOB CARD ‘,MSGLEVEL=(1,1), 
// CLASS=A,MSGCLASS=Q,NOTIFY=&SYSUID,TIME=1440,REGION=0M, 
// USER=SYSADM,PASSWORD=PSEG7TXM, 
// JOBRC=MAXRC 
//IEFPROC EXEC PGM=IKJEFT01,REGION=4M,DYNAMNBR=10 
//SYSTSPRT DD SYSOUT=* 
//SYSTSIN DD *
  SETROPTS RACLIST(PTKTDATA) REFRESH

It will use MVSS0W1 as the application ID.

Andrew Mattingly has written a very well detailed blog on passtickets which is well worth a read.

It described with ample details the algorithm and the various techniques to generate pass-tickets.

Security definitions

The security definitions are in two parts

• The profile for using a pass ticket, for example, who can use a ticket for logging on to TSO,
• The profile for which userids can create a pass ticket.

Who can use a pass ticket with which application

You can limit who can use the application, for example

• a profile just TSOS0W1,
• or members of group SYS1 profile TSOS0W1.SYS1,
• or a userid COLIN in group SYS1, profile TSOS0W1.SYS1.COLIN

Example definitions for TSOS0W1 profile

RDEFINE PTKTDATA TSOS0W1  SSIGNON(KEYMASKED(7E4304D681920260)) - 
    APPLDATA('NO REPLAY PROTECTION')

SETROPTS RACLIST(FACILITY,PTKTDATA) REFRESH 

The server, TSO in this case, can use the function __login__applid() to run the thread as the specified userid. You pass the userid, password (pass ticket) and the application to use (TSOS0W1).

Who can define which pass tickets?

You have to define a RACF profile for the application name, and a profile for userids than can generate a pass ticket for that application.

RDEFINE PTKTDATA   IRRPTAUTH.TSOS0W1.*  UACC(NONE)
PERMIT IRRPTAUTH.TSOS0W1.* CLASS(PTKTDATA) ID(COLIN) ACCESS(UPDATE) 
PERMIT IRRPTAUTH.TSOS0W1.* CLASS(PTKTDATA) ID(IBMUSER)ACCESS(UPDATE) 
SETROPTS RACLIST(PTKTDATA) REFRESH 

The above statements define a profile for defining pass ticket with the TSOS0W1 application.

Userids COLIN and IBMUSER can define pass tickets for this application.

What can you use to generate a pass ticket?

• RCVTPTGN service
• R_GenSec ((IRRSGS00 or IRRSGS64): Generic security API interface
• R_ticketserv (IRRSPK00): Parse or extract
• IRRPassTicket Java class and search for IRRPassTicket

My application code

See C calling a function setting the high order bit on, and passing parameters for a discussion about calling the callable service, and passing the parameters.

 //   Code to generate a pass ticket 
 #pragma linkage(IRRSPK00 ,OS) 
 #pragma runopts(POSIX(ON)) 
 /*Include standard libraries */ 
  #include <stdio.h> 
  #include <stdlib.h> 
  #include <string.h> 
  #include <stdarg.h> 
  #include <iconv.h> 
                                                                 
int main( int argc, char *argv??(??)) 
  { 
     if (argc != 3) 
     { 
        printf("Syntax is %s userid applid\n",argv[0]); 
        return 12 ; 
     } 
     if (strlen(argv[1]) >  8) 
     { 
        printf("length of userid must be <= 8\n"); 
        return 12; 
     } 
     if (strlen(argv[2]) > 8) 
     { 
        printf("length of applid must be <= 8\n"); 
        return 12; 
     } 
                                                                 
     char work_area[1024]; 
     int Option_word = 0; 
     int rc; 
     long SAF_RC,RACF_RC,RACF_RS; 
     SAF_RC=0 ; 
     long ALET = 0; 
     short Function_code= 3; 
     struct { 
       short length; 
       char value[8]; 
     } appl; 
     struct { 
       short length; 
       char value[8]; 
     } userid; 
     struct { 
       short length; 
       char value[20]; 
     } ticket; 
     ticket.length=20; 
     char * u= argv[1] ; 
     strncpy(&userid.value[0],u,8); 
     userid.length =strlen(u); 
     char * pAppl = argv[2]; 
     strncpy(&appl.value[0],pAppl,8); 
     appl.length =strlen(pAppl); 

     int Ticket_options = 1; 
     int * pTO = & Ticket_options; 
                                                          
     rc=IRRSPK00( 
          &work_area, 
          &ALET , &SAF_RC, 
          &ALET , &RACF_RC, 
          &ALET , &RACF_RC, 
          &ALET , &RACF_RS, 
          &ALET ,&Function_code, 
          &Option_word, 
          &ticket, // length followed by area 
          &pTO, 
          &userid, 
          &appl 
          ); 
     printf("return code SAF %d RACF %d RS %d  \n", 
     SAF_RC,RACF_RC,RACF_RS  ); 
     if (SAF_RC == 0) 
     { 
      int l = ticket.length; 
      printf("Pass ticket:%*.*s\n",l,l,ticket.value);           
     } 
  return SAF_RC; 
                                                               
} 

The compile JCL was

//IBMPASST   JOB 1,MSGCLASS=H,COND=(4,LE) 
//S1          JCLLIB ORDER=CBC.SCCNPRC 
// SET LOADLIB=COLIN.LOAD 
//DOCLG       EXEC   PROC=EDCCB,INFILE='COLIN.C.SOURCE(TICKET)', 
//            CPARM='OPTF(DD:COPTS)' 
//COMPILE.ASMLIB DD  DISP=SHR,DSN=SYS1.MACLIB 
//COMPILE.COPTS DD * 
LIST,SOURCE 
aggregate(offsethex) xref 
SEARCH(//'ADCD.C.H',//'SYS1.SIEAHDR.H') 
TEST 
ASM 
RENT ILP32        LO 
OE 
NOMARGINS EXPMAC   SHOWINC XREF 
LANGLVL(EXTENDED) sscom dll 
DEFINE(_ALL_SOURCE) 
DEBUG 
/* 
//BIND.SYSLMOD DD DISP=SHR,DSN=&LOADLIB. 
//*IND.SYSLIB  DD DISP=SHR,DSN=&LIBPRFX..SCEELKED 
//*IND.OBJLIB  DD DISP=SHR,DSN=COLIN.OBJLIB 
//BIND.CSS    DD DISP=SHR,DSN=SYS1.CSSLIB 
//BIND.SYSIN DD * 
   INCLUDE CSS(IRRSPK00) 
   NAME  TICKET(R) 
/* 
//START1   EXEC PGM=TICKET,REGION=0M,PARM='ADCDB TSOS0W1' 
//STEPLIB  DD DISP=SHR,DSN=&LOADLIB 
//SYSERR   DD SYSOUT=*,DCB=(LRECL=200) 
//SYSERROR DD SYSOUT=*,DCB=(LRECL=200)
//SYSOUT   DD SYSOUT=*,DCB=(LRECL=200) 
//SYSPRINT DD SYSOUT=*,DCB=(LRECL=200) 
//CEEDUMP  DD SYSOUT=*,DCB=(LRECL=200) 
/&  

Problems

I could not get R_GenSec (IRRSGS00 or IRRSGS64): Generic security API interface RACF callable services to work because of the 31 bit program, and the service expecting 64 bit addresses.

This blog post has code which uses R_GenSec in 64 bit C.