Sample JCL and code

Figure 1 is sample JCL to invoke the Java™ batch program:

Figure 1. Sample JCL for the Java batch program

//*********************************************************************
//* Licensed Materials - Property of IBM
//* 5655-P97 Copyright IBM Corp. 2007
//* Status = HCF7740
//*
//* It is recommended to use IBM JZOS Batch Toolkit for z/OS to invoke 
//* the OpenPGP support.
//* The JZOS invocation samples provided by Encryption Facility V1.2
//* consist of three different files:
//* 1. Procedure in PROCLIB
//* 2. Shell script to configure environment variables
//* 3. Batch job that calls the sample procedure in PROCLIB
//*
//* This is a sample procedure used by the sample batch job 
//* to launch the Encryption Facility V1.2 OpenPGP support.
//*
//* To use this sample, tailor the procedure to your installation:
//* 1.) Replace '<high-level qualifier>.JZOS.LOADLIB' with the PDSE that contains the
//*     JVMLDMxx modules that were installed during installation
//* 2.) The ARGS parameter should not updated.  Instead update the
//*     MAINARGS DD in the calling DD.
//*
//*********************************************************************
//CSDJZSVM PROC JAVACLS='com.ibm.encryptionfacility.EFOpenPGP',
//   ARGS='',                            < Args to Java class
//   LIBRARY='<high-level qualifier>.JZOS.LOADLIB',    <STEPLIB FOR JVMLDM module
//   VERSION='50',                       < JVMLDM version: 50,56
//   LOGLVL='+I',                       <JZOS Dbg LVL: +I(info) +T(trc) 
//   REGSIZE='0M',                       <EXECUTION REGION SIZE
//   LEPARM=''
//JAVAJVM  EXEC PGM=JVMLDM&VERSION,REGION=&REGSIZE,
//   PARM='&LEPARM/&LOGLVL &JAVACLS &ARGS'
//STEPLIB  DD DSN=&LIBRARY,DISP=SHR  
//SYSPRINT DD SYSOUT=*                   <System stdout
//SYSOUT   DD SYSOUT=*                  <System stderr 
//STDOUT   DD SYSOUT=*                  <Java System.out 
//STDERR   DD SYSOUT=*                  <Java System.err 
//CEEDUMP  DD SYSOUT=*
//ABNLIGNR DD DUMMY
//*
//*The following DDs can/should be present in the calling JCL
//*
//*STDIN   DD                       <OPTIONAL - Java System.in
//*STDENV  DD                         <REQUIRED - JVM Environment script
//*MAINARGS DD                          <Preferred method to supply args
// PEND

Figure 2 is sample code for the Java environment script to configure any environment variables for the Java JVM.

Figure 2. Sample code for the Java environment

# Licensed Materials - Property of IBM
# 5655-P97 Copyright IBM Corp. 2007
# Status = HCF7740
#
# It is recommended to use IBM JZOS Batch Toolkit for z/OS to invoke 
# the OpenPGP support.
# The JZOS invocation samples provided by Encryption Facility V1.2
# consist of three different files:
# 1. Procedure in PROCLIB
# 2. Shell script to configure environment variables
# 3. Batch job that calls the sample stored procedure
#
# This is a sample shell script which configures
# any environment variables for the Java JVM.
# Variables must be exported to be seen by the launcher.
#
# To use this sample, tailor the script to your installation:
# 1.) Replace <JAVA_HOME> to point the location of the 5.0 JDK

. /etc/profile
export JAVA_HOME=<JAVA_HOME>
export JZOS_HOME="${JAVA_HOME}"/lib/ext/

export PATH=/bin:"${JAVA_HOME}"/bin:

LIBPATH=/usr/lib/java_runtime:/lib:/usr/lib:"${JAVA_HOME}"/bin
LIBPATH="$LIBPATH":"${JAVA_HOME}"/bin/classic
LIBPATH="$LIBPATH":"${JZOS_HOME}"
export LIBPATH="$LIBPATH":

# Customize your CLASSPATH here
CLASSPATH=/usr/include/java_classes/ifaedjreg.jar
CLASSPATH=$CLASSPATH:/usr/lpp/encryptionfacility/CSDEncryptionFacility.jar

# Add JZOS required jars to end of CLASSPATH
for i in "${JZOS_HOME}"/*.jar; do
    CLASSPATH="$CLASSPATH":"$i"
    done
export CLASSPATH="$CLASSPATH":

# Set JZOS specific options
# Use this variable to specify encoding for DD STDOUT and STDERR
#export JZOS_OUTPUT_ENCODING=Cp1047
# Use this variable to prevent JZOS from handling MVS operator commands
#export JZOS_ENABLE_MVS_COMMANDS=false
# Use this variable to supply additional arguments to main
#export JZOS_MAIN_ARGS=""

# Configure JVM options
IJO="-Xms16m -Xmx128m"
# Configure the number of garbage collection treads during execution
IJO="$IJO -Xgcthreads4"
# Uncomment the following to aid in debugging "Class Not Found" problems
#IJO="$IJO -verbose:class"
IJO="$IJO -Djzos.home=${JZOS_HOME}"
# Uncomment the following if you want to run without JIT
#IJO="$IJO -Djava.compiler=NONE"
# Uncomment the following if you want to run with Ascii file encoding.
#IJO="$IJO -Dfile.encoding=ISO8859-1"
export IBM_JAVA_OPTIONS="$IJO -Dibm.DES.usehdwr.size=0"

Figure 3. Sample code for the Java environment (continued)

# Uncomment the following if you want to run with trace from hardware crypto
# provider
#export IBM_JAVA_OPTIONS="$IBM_JAVA_OPTIONS -Djava.security.auth.debug=all"

# Uncomment the following if you want to run with trace from JRIO data set
# I/O component
#export IBM_JAVA_OPTIONS="$IBM_JAVA_OPTIONS -DRIOJADEBUG"

export JAVA_DUMP_HEAP=false
export IBM_JAVA_ZOS_TDUMP=NO

# Required to correctly read ASCII armor data sets since ASCII armor data sets 
# contain some 0 byte records
export _EDC_ZERO_RECLEN=Y

Figure 4 shows sample JCL that uses the Java batch program and environment script. This sample includes the following steps:

Encrypt a data set with a passphrase.
Decrypt a data set with a passphrase.
Encrypt a data set with public key.

In order for step 3 (//JAVA3) to run, you must use the -g command with the following options to make the key alias available. This sample is run from the shell script environment. Also, ensure that you set up the Java environment to use larger key sizes. See http://www-03.ibm.com/systems/z/os/zos/tools/java/.:

java -jar /usr/lpp/encryptionfacility/CSDEncryptionFacility.jar   \
-homedir /etc/encryptionfacility  \
-key-alias rsa_md2_4096 \
-keystore /var/encryptionfacility/keystores/encrdecr/keystore_jceks \
-keystore-type JCEKS \ 
-key-size 4096 \
-keystore-password password \
-key-password password \
-g

Figure 4. Sample code for encrypting and decrypting z/OS® data sets

//CSDSMJCL  JOB ()
//PROCLIB JCLLIB ORDER=<HLQ>.JZOS.JCL
//*
//*********************************************************************
//* Licensed Materials - Property of IBM
//* 5655-P97 Copyright IBM Corp. 2007
//* Status = HCF7740
//*
//* It is recommended to use IBM JZOS Batch Toolkit for z/OS to invoke 
//* the OpenPGP support.
//* The JZOS invocation samples provided by Encryption Facility V1.2
//* consist of three different files:
//* 1. Procedure in PROCLIB
//* 2. Shell script to configure environment variables
//* 3. Batch job that calls the sample stored procedure
//*
//* This is a sample batch job to launch the Encryption Facility V1.2 
//* OpenPGP support.
//* Tailor the job for your installation:
//* 1.) Modify the job card per your installation's requirements
//* 2.) Replace '<HLQ>.JZOS.JCL(CSDSMPEN )' with the PDS that contains 
//*     the shell script to update the JVM's environment variables
//* 3.) Replace '<HLQ>.JZOS.JCL' with the PDS that contains the
//*     sample procedure CSDJZSVM
//* 4.) Update the MAINARGS DD to specify options and commands for the 
//*     OpenPGP support invocation.  Refer to the user's guide for the
//*     correct syntax for specifying the options and commands for an 
//*     invocation. 
//*
//* This sample job contains example invocations across three steps:
//* JAVA1-Encrypt a data set with password
//* JAVA2-Decrypt a data set with password
//* JAVA3-Encrypt a text data set with public key
//* The sample steps use the following data sets:
//*  HLQ.EFR2.ENC.OUT - allocated in DD
//*  HLQ.EFR2.ENC.OUT2 - allocated in DD
//*  HLQ.EFR2.INPUT(CLRTXT) - assumed to exist
//*  HLQ.EFR2.DEC.OUT - allocated in DD
//*
//* JAVA3 assumes the existence of a keystore that contains an X.509
//* certificate for alias rsa_md2_4096.
//*
//* The -s2k-passphrase option is shown here for simplicity. It is not
//* recommended to include your passphrase in the JCL.  Instead, update
//* your ibmef.config file to include the passphrase (keyword
//* S2K_PASSPHRASE) and maintain proper access control on the file.
//*
//JAVA1 EXEC PROC=CSDJZSVM,VERSION='50'
//STDENV DD DSN=<HLQ>.JZOS.JCL(CSDSMPEN ),DISP=SHR
//*
//DDDEF DD DSN=HLQ.EFR2.ENC.OUT,
//        DISP=(NEW,KEEP),
//        DCB=(RECFM=VB,LRECL=32756,BLKSIZE=32760),
//        UNIT=SYSALLDA,
//        SPACE=(CYL,(5,1))
//*
//MAINARGS  DD *
-homedir /etc/encryptionfacility/
-o '//DD:DDDEF'
-s2k-passphrase PASSW0RD
-c '//HLQ.EFR2.INPUT(CLRTXT)'
/*

Figure 5. Sample code for encrypting and decrypting z/OS data sets (continued)

//JAVA2 EXEC PROC=CSDJZSVM,VERSION='50'
//STDENV DD DSN=<HLQ>.JZOS.JCL(CSDSMPEN),DISP=SHR
//DDDEF DD DSN=HLQ.EFR2.DEC.OUT,
//        DISP=(NEW,CATLG),
//        DCB=(RECFM=FB,LRECL=80,BLKSIZE=6160),
//        UNIT=SYSALLDA,
//        SPACE=(CYL,(5,1))
//*
//MAINARGS  DD *
-homedir /etc/encryptionfacility/
-o '//DD:DDDEF'
-s2k-passphrase PASSW0RD //HLQ.EFR2.ENC.OUT
/*
//JAVA3 EXEC PROC=CSDJZSVM,VERSION='50'
//STDENV DD DSN=<HLQ>.JZOS.JCL(CSDSMPEN),DISP=SHR
//*
//DDDEF DD DSN=HLQ.EFR2.ENC.OUT2,
//        DISP=(NEW,CATLG),
//        DCB=(RECFM=VB,LRECL=32756,BLKSIZE=32760),
//        UNIT=SYSALLDA,
//        SPACE=(CYL,(5,1))
//*
//MAINARGS  DD *
-homedir /etc/encryptionfacility/
-o 'DD:DDDEF'
-rA rsa_md2_4096
-keystore /var/encryptionfacility/keystores/encrdecr/keystore_jceks
-keystore-type JCEKS
-keystore-password password
-key-password password
-t 'UTF-8'
-e '//HLQ.EFR2.INPUT(CLRTXT)'
/*