 |
IKYSETUP contains the commands to perform the RACF® administrator tasks of adding groups and
user IDs, setting up access control, creating CA, RA, and SSL certificates,
and setting up daemon security. The following listing might not be
identical to the code sample shipped with the product. For the most
current sample, see SYS1.SAMPLIB member IKYSETUP.
/* REXX */
/********************************************************************/
/* */
/* DESCRIPTIVE NAME: PKI Services RACF setup CLIST */
/* */
/* Licensed Materials - Property of IBM */
/* 5650-ZOS */
/* Copyright IBM Corp. 2001, 2013 */
/* Status = HKY7790 */
/* */
/*01* EXTERNAL CLASSIFICATION: OTHER */
/*01* END OF EXTERNAL CLASSIFICATION: */
/* */
/* FUNCTION: */
/* */
/* This CLIST will issue the RACF TSO commands necessary to set up*/
/* security for PKI Services. It must be run from TSO by a user ID*/
/* that is RACF SPECIAL. */
/* */
/* USAGE: */
/* */
/* 1) Read accompanying PKI Services post installation */
/* instructions. */
/* 2) Perform necessary prerequisite product installation for */
/* the webserver (websphere), LDAP, etc. */
/* 3) Make note of any predetermined values such as the LDAP */
/* suffix, webserver fully qualified domain name, and the */
/* settings contained in the pkiserv.conf file. */
/* 4) Copy the CLIST to a data set where you can edit it. */
/* 5) Examine the entire CLIST, in particular, the configurable */
/* section. */
/* 6) Modify the values in the configurable section as needed for */
/* your installation. */
/* 7) Run the CLIST. Syntax: */
/* */
/* EX 'data-set-name(IKYSETUP)' 'RUN(YES | NO | PROMPT)' */
/* */
/* where: YES - indicates to run CLIST as is */
/* NO - indicates to display the commands only */
/* PROMPT - indicates to prompt the user prior */
/* to invoking each command */
/* */
/* */
/* DISCLAIMER: */
/* */
/* This CLIST is not intended to cover every possible customer */
/* scenario. Modification of the actual commands to be issued */
/* may be required */
/* */
/********************************************************************/
trace value('O')
/*--------------------------------------------------------------*/
/* configurable section */
/*--------------------------------------------------------------*/
/*---------------------------------*/
/* Part 1 - Things you must change */
/*---------------------------------*/
/****************************************************************/
/* This exec will create the certificate, private key, and */
/* keyring needed for your certificate authority. */
/* */
/* You must update the distinguished name of your certificate */
/* authority defined below. The suffix of this DN must match */
/* the suffix set up for your LDAP directory (suffix value from */
/* your slapd.conf file). */
/* */
/* Typically, Certificate Authorities have distinguished names */
/* in the following form: */
/* */
/* OU=<your-CA's-friendly-name>,O=<your-organization>, */
/* C=<your-2-letter-country-abbreviation> */
/* */
/* e.g., OU=Human Resources Certificate Authority.O=IBM,C=US */
/* */
/* If you already have your CA certificate and private key set */
/* up in RACF, set ca_dn="" and update the ca_label variable to */
/* equal your CA certificate's label. Note, it must reside */
/* under CERTAUTH */
/* */
/* If you are running with Multiple-CAs: */
/* You could run IKYSETUP once for each separate CA you */
/* want to operate, changing ca_domain everytime. The */
/* ca_domain value will help qualify the other variables thus */
/* reducing the amount of work the RACF administrator needs */
/* to perform. Otherwise, set to NULL. */
/* */
/****************************************************************/
ca_domain = "" /* @L4A*/
if LENGTH(ca_domain) > 8 then /* @L4A*/
ca_domain_trunc = LEFT(ca_domain,8) /* @L4A*/
else /* @L4A*/
ca_domain_trunc = ca_domain /* @L4A*/
OrgUnit = STRIP(ca_domain "Human Resources Certificate Authority")
/* @L4A*/
ca_dn= "OU('"||OrgUnit||"')",
"O('Your Company')",
"C('Your Country 2 Letter Abbreviation')" /* @L4C*/
ca_label = STRIP(ca_domain "Local PKI CA") /* Label for CA
certificate with the
CA Domain name
prepended @L4A*/
/****************************************************************/
/* ra_label: */
/* A "must change" variable - default: "Local PKI RA" */
/* ra_dn: */
/* A "must change" variable. If you don't wish to have PKI */
/* Services operate with a separate RA certificate, set */
/* ra_dn="" */
/****************************************************************/
ra_label = STRIP(ca_domain "Local PKI RA") /*Label for
RA Certificate @01C*/
if (ra_label = "") then /* If no RA Label ... @L4A*/
ra_dn="" /*@L4A*/
else /*@L4A*/
ra_dn=, /*@L4A*/
"CN('Registration Authority')",
ca_dn
/****************************************************************/
/* This exec will create the certificate, private key, and */
/* keyring needed for your webserver. (Required for SSL.) */
/* */
/* You must update the distinguished name of your */
/* webserver. The Common Name (CN) must match your webserver's */
/* fully qualified domain name. */
/* */
/* e.g., CN=www.ibm.com,O=IBM,C=US */
/* */
/* If you already have your webserver configured for SSL, set */
/* web_dn="". */
/****************************************************************/
web_dn=,
"CN('www.YourCompany.com')",
"O('Your Company')",
"L('Your City')",
"SP('Your Full State or Province Name')",
"C('Your Country 2 Letter Abbreviation')"
/****************************************************************/
/* The sample web server protection directives supplied by PKI */
/* use SSLring for the web server's SAF key ring. If you change */
/* the value below, you will need to modify the "KeyFile" */
/* directive in the samples/httpd.conf and samples/httpd2.conf */
/* files when configuring the web server. */
/* */
/* If you already have your webserver configured for SSL and */
/* are using a SAF key ring (vs a gskkyman keyfile), then set */
/* web_ring equal to your webserver's SAF key ring name. If you */
/* are using a gskkyman keyfile, then set web_ring="". Note, */
/* you will have to manually add the PKI CA's certificate to */
/* the webserver's keyfile/keyring and make the webserver's */
/* root CA available in an HFS file for download. @L9C */
/****************************************************************/
web_ring = "SSLring" /* SAF keyring for web server */
/****************************************************************/
/* You must provide UID and GID values for the user IDs and */
/* groups being created below */
/****************************************************************/
daemon="PKISRVD" /* user ID for PKI daemon */
daemon_uid="554" /* uid for PKI daemon */
surrog="PKISERV" /* user ID for the surrogate */
surrog_uid="555" /* uid for the surrogate id */
****************************************************************/
/* pkigroup members are authorized to administer PKI Services */
/* certificates and certificate requests. If you know the user */
/* IDs that should be connected to this group, update the */
/* pkigroup_mem stem variable. If not, you can always connect */
/* users later. */
/* */
/* If you do not wish to have this exec create this group, */
/* set the group name to "" */
/* */
/****************************************************************/
pkigroup="PKIGRP" /* PKI Services Admin group name */
pki_gid="655" /* PKI Services Admin group id */
pkigroup_mem.0=0 /* Number of pkigroup members to connect */
pkigroup_mem.1=""
/*------------------------------------*/
/* Part 2 - Questions you must answer */
/*------------------------------------*/
/****************************************************************/
/* Question 1 - Restrict the surrogate user ID? */
/* */
/* The surrogate user ID is the identity assigned to client */
/* processes when requesting certificate services. The */
/* RESTRICTED attribute can be assigned to this ID to limit the */
/* resources available to this user should the user ID be */
/* hijacked by an unfriendly client (hacker). We recommend */
/* that you run the surrogate this way. However, this probably */
/* will cause additional setup work. If you want the RESTRICTED */
/* attribute assigned now, set restrict_surrog=1. Note, you */
/* can always do this at some later time. */
/****************************************************************/
restrict_surrog=0
/****************************************************************/
/* Question 2 - Need PKI Services to generate the key pair */
/* for its certificates? */
/* */
/* You have the option of choosing PKI Services to generate the */
/* key pair for the certificates using PKCS#11 APIs. In order */
/* for the daemon to generate the key pair, you need to specify */
/* the TokenName keyword in pkiserv.conf and the CRYPTOZ class */
/* must be activated, the profiles must be defined and the */
/* daemon needs to have appropriate access. */
/* */
/* If you don't need the key generation capability, leave */
/* key_gen = 0, otherwise set key_gen = 1. @L9A */
/* */
/* If you set key_gen = 1, you must also specify a CSFSERV */
/* profile via csfserv_profile set later in this file. @D8A */
/* */
/****************************************************************/
key_gen = 0 /*@L9A*/
/****************************************************************/
/* If you set key_gen=1 above, this exec will activate the */
/* CRYPTOZ class, create profiles in this class and permit */
/* the PKI Services daemon to access them. You may also have */
/* a RACF group for authorized PKCS11 token users. The daemon */
/* ID would need to be added to this group. */
/* */
/* Set the following variables as needed: */
/* */
/* cryptoz_profile_so - Profile to be created in the CRYPTOZ */
/* class to control the security officer (SO) role */
/* cryptoz_profile_user - Profile to be created in the CRYPTOZ */
/* class to control the user role */
/* cryptoz_grp - Group name for authorized PKCS11 token users */
/* @L9A */
/****************************************************************/
cryptoz_profile_so = 'SO.'||daemon||'.*' /*@L9A*/
cryptoz_profile_user = 'USER.'||daemon||'.*' /*@L9A*/
cryptoz_grp = '' /*@L9A*/
/****************************************************************/
/* Question 3 - Use ICSF? */
/* */
/* There are several possible choices for generation and @LBC*/
/* protection of your CA's private key: */
/* */
/* - Generate the RSA key using software and retain it as a */
/* software key. This is the default. (Option 0) */
/* */
/* - Generate the RSA key using software then store the key in */
/* ICSF. (Option 1) @LAC*/
/* */
/* - Generate the RSA key through ICSF using the PCI */
/* cryptographic coprocessor (PCICC) then store the key in */
/* ICSF. (Option 2) @LAC*/
/* */
/* - Generate the DSA key using software and retain it as a */
/* software key. This key cannot be saved in ICSF. (Option 3) */
/* */
/* - Generate the NIST Elliptic Curve Cryptography (ECC) key */
/* using software and retain it as a software key. */
/* (Option 4) @LAA*/
/* */
/* - Generate the Brainpool ECC key using software and retain */
/* it as a software key. (Option 5) @LAA*/
/* */
/* - Generate the NIST Elliptic Curve Cryptography (ECC) */
/* key using the Crypto Express 3 cryptographic coprocessor */
/* and store the key in the ICSF PKA data set (PKDS). */
/* (Option 6) @LBA*/
/* */
/* - Generate the Brainpool Elliptic Curve Cryptography (ECC) */
/* key using the Crypto Express 3 cryptographic coprocessor */
/* and store the key in the ICSF PKA data set (PKDS). */
/* (Option 7) @LBA*/
/* */
/* - Generate the RSA key using the Enterprise PKCS#11 */
/* Cryptographic Coprocessor and store the key in the ICSF */
/* Token Key Data set(TKDS). */
/* (Option 8) @LEA*/
/* */
/* - Generate the NIST Elliptic Curve Cryptography (ECC) key */
/* using the Enterprise PKCS#11 Cryptographic Coprocessor and */
/* store the key in the ICSF Token Key Data set(TKDS). */
/* (Option 9) @LEA*/
/* */
/* - Generate the Brainpool Elliptic Curve Cryptography (ECC) */
/* key using the Enterprise PKCS#11 Cryptographic Coprocessor */
/* and store the key in the ICSF Token Key Data set(TKDS). */
/* (Option 10) @LEA*/
/* */
/* Notes: */
/* */
/* - For options 1, 2, 4 through 10 ICSF must be configured */
/* for support and running. Additionally, for option 2, */
/* a PCICC must be present and operational. */
/* For options 6 and 7, a Crypto Express 3 cryptographic */
/* coprocessor must be operational and configured with the */
/* PKDS. For options 8, 9 or 10 an Enterprise PKCS#11 */
/* cryptographic coprocessor must be operational and */
/* configured with the TKDS. @LEC*/
/* */
/* - Options 0 and 2 are the only way to generate an RSA */
/* private key larger than 1024 bits. @LAC*/
/* */
/* - If option 2, 6, 7, 8, 9 or 10 is selected, the */
/* certificate and private key will not be backed up by this */
/* exec. @LEC*/
/* */
/* - If you select option 0, you can always migrate the key */
/* to ICSF later (recommended). However, if you wish to use */
/* the PCICC, you must select that option now. */
/* */
/* Select the option desired by setting key_type=0 through 10. */
/* @LEC*/
/****************************************************************/
key_type=0
/****************************************************************/
/* If you set key_type=1, 2, 6, 7, 8, 9 or 10 above, you will */
/* need to restrict access to the CA's private key. Unless you */
/* indicate otherwise, this exec will activate the CSFKEYS */
/* classes create a profile in the CSFKEYS class to protect the */
/* CA's private key, and permit the PKI Services daemon to use */
/* it. @LEC*/
/* */
/* If you are already using ICSF, then you may have profiles in */
/* the CSFSERV class protecting ICSF services. If you set */
/* key_type=1, 2, 4, 5, 6, 7, 8, 9 or 10 above, the PKI */
/* Services daemon would need access to the following profiles: */
/* CSFDSV, CSFDSG, CSFPKI, CSFENC, CSFDEC */
/* @LEC*/
/* Also, the PKI Services surrogate ID would need access */
/* to the following profiles that cover the services used */
/* during the SSL/TLS handshake processing depending on */
/* the cipher and certificates being utilized: */
/* CSFENC, CSFDEC, CSFPKD, CSFPKE, CSFPKI, CSFDSG, CSFDSV, */
/* CSFCKI, CSFCKM, CSF1DVK, CSF1GAV, CSF1GKP, CSFIQA, CSF1PKS, */
/* CSF1PKV, CSF1TRD, CSF1TRC */
/* @D8C*/
/* You may already have a RACF group for authorized ICSF users. */
/* If you specify the group name for csfusers_grp, the daemon */
/* and surrogate IDs will be connected to the group, and the */
/* group permitted to the profiles. Otherwise the two IDs will */
/* be directly permitted to the profiles. */
/* @D8C*/
/* Set the following variables as needed: */
/* */
/* csfkeys_profile - Profile to be created in the CSFKEYS class */
/* Set the value to '' if you don't want the profile */
/* csfserv_profile - Profile to be created in the CSFSERV class */
/* e.g., 'CSF*' */
/* csfusers_grp - Group name for authorized ICSF users */
/* e.g., 'ICSFUGRP' */
/****************************************************************/
csfkeys_profile='IRR.DIGTCERT.CERTIFAUTH.*'
if (key_type=1 | key_type=2 | key_type=4 |,
key_type=5 | key_type=6 | key_type=7 |,
key_type=8 | key_type=9 | key_type=10 |, /* @LEA */
key_gen=1)
then csfserv_profile='CSF*'
else csfserv_profile='' /* @D8C*/
csfusers_grp=''
/****************************************************************/
/* Question 4 - Back up your private key? */
/* */
/* The exec will prompt you to enter a pass phrase to encrypt a */
/* backup copy of your CA's certificate and private key. */
/* Caution, the text you enter at the prompt WILL be displayed */
/* at the terminal. Backup is highly recommended. If you do not*/
/* wish to back up your CA's certificate and private key to a */
/* pass phrase encrypted data set, set key_backup=0. The back up*/
/* may be done later if the key is not stored in ICSF. */
/* */
/* Note, back up is not performed if the CA certificate was not */
/* created by this exec or if you specified key_type 2, 6, 7, 8,*/
/* 9 or 10 above. @LEC*/
/* **************************************************************/
key_backup=1
****************************************************************/
/* Question 5 - Set up z/OS UNIX level security? */
/* */
/* z/OS UNIX may be set up to operate with a higher level of */
/* security than traditional UNIX. While we recommend this, it */
/* difficult to set up. You may want to defer this until later. */
/* */
/* If you don't want to set up UNIX security now, leave */
/* unix_sec=0. */
/* */
/* If you already have UNIX level security established and wish */
/* to continue it, set unix_sec=1. */
/* */
/* If you don't have UNIX level security established and wish */
/* to establish it now, set unix_sec=2. Note additional manual */
/* configuration probably will be required. This can be done */
/* by adding, removing, updating members of the two stem */
/* variables below. The pgmcntl_dsn stem contains the data set */
/* names of load libraries that need program control. The */
/* bpx_userid stem contains the user IDs of your server daemons.*/
/* (These need access to BPX.SERVER and BPX.DAEMON in the */
/* FACILITY class.) Again, you can defer this until later by */
/* leaving unix_sec=0 */
/****************************************************************/
unix_sec=0
pgmcntl_dsn.0=8 /* Number of program controlled data sets below @L2C*/
pgmcntl_dsn.1="'CEE.SCEERUN'"
pgmcntl_dsn.2="'CBC.SCLBDLL'"
pgmcntl_dsn.3="'SYS1.SIEALNKE'" /* Common LINKLIST PDSE dataset @L2A*/
pgmcntl_dsn.4="'SYS1.CSSLIB'" /* @L2C*/
pgmcntl_dsn.5="'TCPIP.SEZALOAD'" /* @L2C*/
pgmcntl_dsn.6="'SYS1.LINKLIB'" /* @L2C*/
pgmcntl_dsn.7="'CSF.SCSFMOD0'" /* @L2C*/
pgmcntl_dsn.8="'CSF.SCSFMOD1'" /* @L2C*/
bpx_userid.0=1 /* Number of additional bpx server ids below */
bpx_userid.1="OMVSKERN"
/****************************************************************/
/* Question 6 - Use DB2 as the repository for the Issued */
/* Certificate List (ICL) and Object Store? */
/* */
/* In the default configuration, PKI Services uses VSAM data */
/* sets as the repository for the issued certificate list (ICL) */
/* and the object store. VSAM is an included feature of z/OS. */
/* */
/* Optionally, DB2 for z/OS may be used as the repository for */
/* the ICL and the object store. DB2 for z/OS is a separately */
/* purchased and installed product which provides additional */
/* data stability features and query capabilities beyond those */
/* provided by VSAM. PKI Services may use DB2 for z/OS as the */
/* repository for the ICL and object store if DB2 is running on */
/* the same system as the PKI Services daemon. */
/* */
/* If you wish to use DB2 for z/OS as the repository for the */
/* ICL and object store, set db2_repos to 1; otherwise, leave */
/* db2_repos set to 0. */
/* @LCA */
/****************************************************************/
db2_repos = 0 /* @LCA */
/****************************************************************/
/* If you set db2_repos = 1 above, this exec will permit the */
/* PKI Services daemon access to the DB2 Resource Recovery */
/* Services access facility (RRSAF). */
/* */
/* To grant this access, the name of the local DB2 subsystem */
/* that will be used to provide the repository must be */
/* provided. This is a name of up to 4 characters. You can */
/* obtain this name from your DB2 for z/OS systems programmer. */
/* Change the value of db2_subsys below to contain the name of */
/* the local DB2 subsystem. */
/* @LCA */
/****************************************************************/
db2_subsys = 'DSN9' /* @LCA */
****************************************************************/
/* Question 7 - Need granular control on administrative */
/* functions? */
/* If you wish to set up granular control, set */
/* AdminGranularControl to 1; otherwise, leave */
/* AdminGranularControl set to 0. */
/****************************************************************/
AdminGranularControl = 0 /* @DAC */
/****************************************************************/
/* If you set AdminGranularControl to 1, */
/* provide the template nick names you want to act on and */
/* assign the groups. */
/* Change the value of template1,2,3 below and add more if */
/* needed. */
/* Change the value of pkigroup1,2 below and add more if */
/* needed. */
/****************************************************************/
template.0 = 12 /* @LDA */
template.1 = "1YBSSL" /* @LDA */
template.2 = "1YBSM" /* @LDA */
template.3 = "2YBWL" /* @LDA */
template.4 = "2YBZOS" /* @LDA */
template.5 = "5YSSSL" /* @LDA */
template.6 = "5YSIPS" /* @LDA */
template.7 = "5YSCAP" /* @LDA */
template.8 = "2YIACS" /* @LDA */
template.9 = "SAMPLB" /* @LDA */
template.10= "5YSCEPP" /* @LDA */
template.11= "1YKRC" /* @LDA */
template.12= "2YEVSSL" /* @LDA */
pkigroup1="PKIGRP1" /* PKI Services Admin group name @LDA */
pki_gid1="656" /* PKI Services Admin group id @LDA */
pkigroup1_mem.0=0 /* Number of pkigroup members to connect @LDA */
pkigroup1_mem.1="" /* @LDA */
actions1.0=13 /* @DAC */
actions1.1="QUERYREQS" /* @LDA */
actions1.2="QUERYCERTS" /* @LDA */
actions1.3="APPROVE" /* @LDA */
actions1.4="APPROVEWITHMODS" /* @LDA */
actions1.5="REJECT" /* @LDA */
actions1.6="DELETEREQS" /* @LDA */
actions1.7="REVOKE" /* @LDA */
actions1.8="DELETECERTS" /* @LDA */
actions1.9="RESUME" /* @LDA */
actions1.10="AUTORENEWENABLE" /* @LDA */
actions1.11="AUTORENEWDISABLE" /* @LDA */
actions1.12="CHANGEMAIL" /* @LDA */
actions1.13="PREREGISTER" /* @LDA */
/* 1@DAD*/
pkigroup2="PKIGRP2" /* PKI Services Admin group name @LDA */
pki_gid2="657" /* PKI Services Admin group id @LDA */
pkigroup2_mem.0=0 /* Number of pkigroup members to connect @LDA */
pkigroup2_mem.1="" /* @LDA */
actions2.0=2 /* @LDA */
actions2.1="QUERYREQDETAILS" /* @LDA */
actions2.2="QUERYCERTDETAILS" /* @LDA */
/*---------------------------------*/
/* Part 3 - Things you can change */
/*---------------------------------*/
/****************************************************************/
/* Label of the CA certificate that is the superior (signer) of */
/* the PKI Services CA, if self sign leave blank */
/****************************************************************/
signing_ca_label = "" /*@L4A*/
/****************************************************************/
/* This exec will record results to a log data set if desired. */
/* the name of the data set is specified below. If you do not */
/* want log data set recording, set log_dsn="" (Not recommended)*/
/****************************************************************/
if (ca_domain = "") then /* If no CA Domain... @L4A*/
log_dsn="IKYSETUP.LOG" /* Under your ID */
else /* Else use CA Domain @L4A*/
log_dsn=ca_domain_trunc||".IKYSETUP.LOG" /* CA Domain qualified @L4A*/
/****************************************************************/
/* Note IKYCVSAM, the sample JCL to create VSAM datasets and */
/* pkiserv.conf expect the object store and ICL datasets to */
/* have PKISRVD as their high level qualifier. */
/* Changing either "daemon" or "vsamhlq" will */
/* require making the same change to IKYCVSAM and pkiserv.conf */
/****************************************************************/
vsamhlq=daemon /* HLQ for VSAM data sets. Same as daemon ID */
/****************************************************************/
/* The following variables are used to create the certificates */
/* for the Certificate Authority (CA) and the web server. If */
/* the default settings are used, these certificates will */
/* expire as follows: */
/* - The CA certificate will expire 20 years from the date */
/* when this exec is run. */
/* - The web server SSL certificate will expire 5 years from */
/* the date when this exec is run. */
/* */
/* You may tailor the expiration dates to suit your own need in */
/* one of two ways, which are described below. If you decide */
/* to tailor the expiration dates for these certificates, make */
/* sure that the web server SSL certificate's expiration date */
/* does not exceed the expiration date of the CA certificate; */
/* failure to ensure this will result in the web server SSL */
/* certificate being added as NOTRUST in the RACF database. */
/* - Method 1: You can change the number of years used to */
/* set the CA certificate and web server SSL certificate. */
/* If you choose this method, leave the code segment */
/* labelled "Method 2" below commented out of the exec, */
/* and alter the values for the "ca_exyears" and */
/* "web_exyears" to set the number of years for the CA */
/* certificate and the web server SSL certificate, */
/* respectively. Ensure that the value for "ca_exyears" */
/* equals or exceeds the value for "web_exyears". */
/* - Method 2: You can hardcode the expiration date to be */
/* used for the CA certificate and the web server SSL */
/* certificate. If you choose this method, comment out */
/* the code segment labelled "Method 1" below, uncomment */
/* the code segment labelled "Method 2" below, and alter */
/* the values for the "ca_expires" and "web_expires" to */
/* set the expiration dates for the CA certificate and the */
/* web server SSL certificate, respectively. Ensure that */
/* the expiration date given in "ca_expires" is later */
/* than the date specified in "web_expires". */
/********************************************************* @D9A */
*
Method 1: Set the CA certificate and web server
certificate expiration dates to a number of years in
the future. If using Method 2 to set the expiration
dates, comment out the code in this section. @D9A
*/
ca_exyears = 20 /* @D9C */
web_exyears = 5 /* @D9C */
if (datatype(ca_exyears,'N')^=1) then do
say "The CA certificate expiration years value",
ca_exyears "is not valid." /* @D9A */
return 8 /* @D9A */
end /* @D9A */
if (datatype(web_exyears,'N')^=1) then do
say "The webserver SSL certificate expiration years value",
web_exyears "is not valid." /* @D9A */
return 8 /* @D9A */
end
today = date('S') /* @D9A */
exday = ca_exyears * 10000 + today /* @D9A */
ca_expires = substr(exday,1,4)"/"||,
substr(exday,5,2)"/"||,
substr(exday,7,2) /* @D9A */
exday = web_exyears * 10000 + today /* @D9A */
web_expires = substr(exday,1,4)"/"||,
substr(exday,5,2)"/"||,
substr(exday,7,2) /* @D9A */
/* End of Method 1. @D9A */
/*
Method 2: Set the CA certificate and web server
certificate expiration dates to a specific future
date. If using Method 1 to set the expiration
dates, leave this code segment commented out of
the exec. If using this method, remove the
comment characters from the following two
instructions, change the dates to the desires
values if necessary, and comment out all
instructions in Method 1. @D9A
*/
/* ca_expires = "2030/01/01" */ /* @D9A */
/* web_expires = "2015/01/01" */ /* @D9A */
/* End of Method 2. @D9A */
web_label = "SSL Cert" /* Label for web server cert */
/****************************************************************/
/* PKI Services Key ring name */
/****************************************************************/
if (ca_domain = "") then /* If no CA Domain... @L4A*/
ca_ring="CAring" /* keyring name for PKI Srvs */
else /* Else use CA Domain @L4A*/
ca_ring="CAring."||ca_domain /* CA Domain qualified @L4A*/
/****************************************************************/
/* PKI Services PKCS11 Token Name */
/****************************************************************/
if (ca_domain = "") then /* If no CA Domain... @LEA*/
caStore=daemon||".CATOKEN" /* token name for PKI Srvs */
else /* Else use CA Domain @DBC*/
caStore=daemon||".CATOKEN." || ca_domain
/* CA Domain qualified @DBC*/
/****************************************************************/
/* You can select the size (in bits) of your CA's private key. */
/* Acceptable values depend upon the value that is used for */
/* "key_type" in Question 3. */
/* - When key_type=0 or key_type=2, the acceptable range is */
/* 512 to 4096. */
/* - When key_type=1 or key_type=3, the acceptable range is */
/* 512 to 1024. */
/* - When key_type=4 or Key_type=6 or key_type=9, */
/* the acceptable set of values are 192, */
/* 224, 256, 384, and 521 (yes, that is really 521). */
/* - When key_type=5 or key_type=7 or key_type=10, */
/* the acceptable set of values are 160, */
/* 192, 224, 256, 320, 384, and 512. */
/* - When key_type=8, the acceptable range is 1024 to 4096. */
/* The default value to use for the key size is given in the */
/* "ca_keysize" value below. This default value has been */
/* chosen with the assumption that an RSA key will be used in */
/* the CA certificate ("key_type" = 0, 2 or 8) in Question 3 */
/* above. Please notice that the value of "ca_keysize" must be */
/* changed if an ECC key ("key_type" = 4,5,6,7,9 or 10) or RSA */
/* software key stored in ICSF("key_type" = 1) or DSA key */
/* ("key_type" = 3) is selected in Question 3 above. Also, */
/* please notice that to use an RSA key size greater than 1024 */
/* bits, you must select key_type=0,2 or 8 in Question 3 above. */
/* @DAC*/
/****************************************************************/
ca_keysize="2048"
/****************************************************************/
/* Data set to contain the backup copy of the CA certificate */
/* and private key. (pass phrase encrypted PKCS#12 format) */
/****************************************************************/
if (ca_domain = "") then /* If no CA Domain... @L4A*/
backup_dsn = "'"||daemon||".KEY.BACKUP.P12BIN'" /* @L5C*/
else /* Else use CA Domain @L4A*/
backup_dsn = "'"||daemon||"."||ca_domain_trunc||,
".KEY.BACKUP.P12BIN'" /* @L5C*/
/* CA Domain qualify backup dsn @L4A*/
/****************************************************************/
/* Data set to contain the exported copy of the CA certificate */
/* (DER encoded). This is to assist the backup process. @L9C*/
/* */
/****************************************************************/
if (ca_domain = "") then /* If no CA Domain... @L4A*/
cacert_dsn = "'"||daemon||".CACERT.DERBIN'"
else /* Else use CA Domain @L9C*/
cacert_dsn = "'"||daemon||"."||ca_domain_trunc||".CACERT.DERBIN'"
/* CA Domain qualify export dsn @L9C*/
/****************************************************************/
/* Data set to contain the exported copy of the webserver's */
/* root certificate (DER encoded). This is to be OPUT to an */
/* HFS file later to enable easy downloading by clients. @L9A*/
/****************************************************************/
if (ca_domain = "") then /* If no CA Domain... @L9A*/
export_dsn = "'"||daemon||".WEBROOT.DERBIN'"
else /* Else use CA Domain @L9A*/
export_dsn = "'"||daemon||"."||ca_domain_trunc||".WEBROOT.DERBIN'"
/* CA Domain qualify export dsn @L9A*/
/****************************************************************/
/* Data set to contain the backup copy of the RA certificate */
/* and private key. (pass phrase encrypted PKCS#12 format) */
/****************************************************************/
if (ca_domain = "") then /* If no CA Domain... @01A*/
ra_backup_dsn = "'"||daemon||".RAKEY.BACKUP.P12BIN'" /* @L5C*/
else /* Else use CA Domain @01A*/
ra_backup_dsn = "'"||daemon||"."||ca_domain_trunc||,
".RAKEY.BACKUP.P12BIN'" /* @L5C*/
/* CA Domain qualify RA backup dsn @01A*/
/****************************************************************/
/* This EXEC expects the web server to be set up. If this is */
/* not the case, please refer to: */
/* z/OS HTTP Server Planning, Installing and Using. */
/* If the user ID assigned to the IBM HTTP Server Daemon is not */
/* WEBSRV, please update the assignment below. */
/****************************************************************/
webserver="WEBSRV"
/*--------------------------------------------------------------*/
/* End of configurable section */
/*--------------------------------------------------------------*/
/****************************************************************/
/* Data set to contain the backup copy of the RA certificate */
/* and private key. (pass phrase encrypted PKCS#12 format) */
/****************************************************************/
if (ca_domain = "") then /* If no CA Domain... @01A*/
ra_backup_dsn = "'"||daemon||".RAKEY.BACKUP.P12BIN'" /* @L5C*/
else /* Else use CA Domain @01A*/
ra_backup_dsn = "'"||daemon||"."||ca_domain_trunc||,
".RAKEY.BACKUP.P12BIN'" /* @L5C*/
/* CA Domain qualify RA backup dsn @01A*/
/****************************************************************/
/* This EXEC expects the web server to be set up. If this is */
/* not the case, please refer to: */
/* z/OS HTTP Server Planning, Installing and Using. */
/* If the user ID assigned to the IBM HTTP Server Daemon is not */
/* WEBSRV, please update the assignment below. */
/****************************************************************/
webserver="WEBSRV"
/*--------------------------------------------------------------*/
/* End of configurable section */
/*--------------------------------------------------------------*/
parse upper arg "RUN(" runopt ")"
if runopt = '' then
runopt="NO"
if runopt ^= "YES" & runopt ^= "PROMPT" & runopt ^= "NO" then do
say "syntax ex 'data-set-name(IKYSETUP)' 'run(yes | no | prompt)'"
return 8
end
if runopt ^= "YES" & runopt ^= "PROMPT" then
runopt="NO"
say 'IKYSETUP EXEC invoked ...'
return_code= '0'
max_return_code= '0'
logdata.0=0
if log_dsn ^= "" then do
say "Allocating log data set" log_dsn "..."
x = OUTTRAP(MSGS.)
"FREE FI(IKYLOGDD)"
"FREE DA("||log_dsn||")"
"DELETE" log_dsn
x = OUTTRAP('OFF')
"ALLOCATE DA("||log_dsn||") FILE(IKYLOGDD) RECFM(V B)" ,
" LRECL(256) DSORG(PS) BLKSIZE(2560) SP(1,1) TRACKS "
al_rc= rc
IF al_rc ^= 0 THEN
do
say 'Allocation of log data set failed.'
return 8
end
end
call logsay "RUN("runopt") requested on" DATE() 'at' TIME() '...'
if runopt="NO" then
call logsay "Running in test mode. Commands are not being invoked"
/******************************************************************/
/* Verify the requested key size, based upon the selected key */
/* key type. */
/* - When key_type=0 (RSA software generated key) or */
/* key_type=2 (RSA PCICC generated key), the acceptable */
/* range is 512 to 4096. */
/* - When key_type=1 (RSA software generated key stored in */
/* ICSF) or key_type=3 (DSA software generated key), the */
/* acceptable range is 512 to 1024. */
/* - When key_type=4 (NIST ECC software generated key), @LBC*/
/* or key_type=6 (NIST ECC key in PKDS), the @LBA*/
/* or key_type=9 (NIST ECC key in TKDS), the @LEA*/
/* acceptable set of values are 192, 224, 256, 384, and 521. */
/* - When key_type=5 (Brainpool ECC software generated key), */
/* or key_type=7 (Brainpool ECC in PKDS), @LBA*/
/* or key_type=10 (Brainpool ECC in TKDS), @LEA*/
/* the acceptable set of values are 160, 192, 224, 256, 320, */
/* 384, and 512. */
/* - When key_type=8 (RSA in TKDS), the acceptable range is */
/* 1024 to 4096. @LEA*/
/* If invalid key size is chosen, we will issue message and end */
/* execution. @LAC*/
/******************************************************************/
select /*@LAA*/
when key_type = 0 then do /*@LAA*/
if ca_keysize < 512 /*@LAA*/
then do /*@LAA*/
call logsay "Key size cannot be less than 512",
"for key type" key_type /*@LAA*/
return 8 /*@LAA*/
end /*@LAA*/
else do /*@LAA*/
if ca_keysize > 4096 /*@LAA*/
then do /*@LAA*/
call logsay "Key size cannot be greater than",
"4096 for key type" key_type /*@LAA*/
return 8 /*@LAA*/
end /*@LAA*/
end /*@LAA*/
end /*@LAA*/
when key_type = 1 then do /*@LAA*/
if ca_keysize < 512 /*@LAA*/
then do /*@LAA*/
call logsay "Key size cannot be less than 512", /*@LAA*/
"for key type" key_type /*@LAA*/
return 8 /*@LAA*/
end /*@LAA*/
else do /*@LAA*/
if ca_keysize > 1024 /*@LAA*/
then do /*@LAA*/
call logsay "Key size cannot be greater than",
"1024 for key type" key_type /*@LAA*/
return 8 /*@LAA*/
end /*@LAA*/
end /*@LAA*/
end /*@LAA*/
when key_type = 2 then do /*@LAA*/
if ca_keysize < 512 /*@LAA*/
then do /*@LAA*/
call logsay "Key size cannot be less than 512",
"for key type" key_type /*@LAA*/
return 8 /*@LAA*/
end /*@LAA*/
else do /*@LAA*/
if ca_keysize > 4096 /*@LAA*/
then do /*@LAA*/
call logsay "Key size cannot be greater than",
"4096 for key type" key_type /*@LAA*/
return 8 /*@LAA*/
end /*@LAA*/
end /*@LAA*/
end /*@LAA*/
when key_type = 3 then do /*@LAA*/
if ca_keysize < 512 /*@LAA*/
then do /*@LAA*/
call logsay "Key size cannot be less than 512",
"for key type" key_type /*@LAA*/
return 8 /*@LAA*/
end /*@LAA*/
else do /*@LAA*/
if ca_keysize > 1024 /*@LAA*/
then do /*@LAA*/
call logsay "Key size cannot be greater than",
"1024 for key type" key_type /*@LAA*/
return 8 /*@LAA*/
end /*@LAA*/
end /*@LAA*/
end /*@LAA*/
when key_type = 4 |, /*@LBC*/
key_type = 6 |, /*@LEC*/
key_type = 9 then do /*@LEC*/
if ca_keysize ^= 192 & ca_keysize ^= 224 &,
ca_keysize ^= 256 & ca_keysize ^= 384 &,
ca_keysize ^= 521 /*@LAA*/
then do /*@LAA*/
call logsay "Key size must be: 192, 224, 256, 384,",
"or 521 for key type" key_type /*@LAA*/
return 8 /*@LAA*/
end /*@LAA*/
end /*@LAA*/
when key_type = 5 |, /*@LBC*/
key_type = 7 |, /*@LEC*/
key_type = 10 then do /*@LEC*/
if ca_keysize ^= 160 & ca_keysize ^= 192 &,
ca_keysize ^= 224 & ca_keysize ^= 256 &,
ca_keysize ^= 320 & ca_keysize ^= 384 &,
ca_keysize ^= 512 /*@LAA*/
then do /*@LAA*/
call logsay "Key size must be: 160, 192, 224, 256,",
"320, 384, or 512 for key type",
key_type /*@LAA*/
return 8 /*@LAA*/
end /*@LAA*/
end /*@LAA*/
when key_type = 8 then do /*@LEA*/
if ca_keysize < 1024 /*@LEA*/
then do /*@LEA*/
call logsay "Key size cannot be less than 1024",
"for key type" key_type /*@LEA*/
return 8 /*@LEA*/
end /*@LEA*/
else do /*@LEA*/
if ca_keysize > 4096 /*@LEA*/
then do /*@LEA*/
call logsay "Key size cannot be greater than",
"4096 for key type" key_type /*@LEA*/
return 8 /*@LEA*/
end /*@LEA*/
end /*@LEA*/
end /*@LEA*/
otherwise do /*@LAA*/
call logsay "Key type must be: 0 through 10." /*@LEC*/
return 8 /*@LAA*/
end /*@LAA*/
end /*@LAA*/
/*10@LAD*/
/******************************************************************/
/* Create the daemon and surrogate user IDs using RACF ADDUSER TSO*/
/* command. Give them an OMVS segment since they will need access */
/* to UNIX System Services. */
/******************************************************************/
call logsay2 "Creating users and groups ..."
call tsoserv "ADDUSER " daemon "name('PKI Srvs Daemon')",
" nopassword",
" omvs(uid("daemon_uid")",
" assize(256000000)",
" threads(512))"
if restrict_surrog=1 then /*@D1C*/
resattr="restricted"
else
resattr=""
call tsoserv "ADDUSER " surrog "nopassword",
resattr,
" omvs(uid("surrog_uid"))",
" name('PKI Srvs Surrogate')"
/****************************************************************/
/* Set up PKI Services administration group. */
/* If AdminGranularControl = 1, add additional administration */
/* groups for granular control as specified for Question 7. */
/****************************************************************/
if pkigroup ^= "" then do /* @LCM*/
call tsoserv "ADDGROUP " pkigroup "OMVS(GID("pki_gid"))" /* @LCM*/
do i = 1 to pkigroup_mem.0 /* @LCM*/
call tsoserv "CONNECT" pkigroup_mem.i "GROUP("pkigroup")" /* @LCM*/
end /* @LCM*/
end /* @LCM*/
if AdminGranularControl=1 then do /* @LDA */
if pkigroup1 ^= "" then do /* @LDA */
call tsoserv "ADDGROUP " pkigroup1, /* @LDA */
"OMVS(GID("pki_gid1"))" /* @LDA */
do i = 1 to pkigroup1_mem.0 /* @LDA */
call tsoserv "CONNECT" pkigroup1_mem.i, /* @LDA */
"GROUP("pkigroup1")" /* @LDA */
end /* @LDA */
end /* @LDA */
if pkigroup2 ^= "" then do /* @LDA */
call tsoserv "ADDGROUP " pkigroup2, /* @LDA */
"OMVS(GID("pki_gid2"))" /* @LDA */
do i = 1 to pkigroup2_mem.0 /* @LDA */
call tsoserv "CONNECT" pkigroup2_mem.i, /* @LDA */
"GROUP("pkigroup2")" /* @LDA */
end /* @LDA */
end /* @LDA */
end /* @LDA */
/****************************************************************/
/* Set up the permission needed for the DB2 tables or the VSAM */
/* data sets. @LCA*/
/****************************************************************/
****************************************************************
* The DB2 for z/OS Resource Recovery Services access facility
* (RRSAF) is protected by the RRSAF DSNR class resource that
* is specific to the DB2 subsystem. The following command
* gives READ access to the PKI Services daemon, which allows
* the daemon the capability of interacting with the DB2
* subsystem through this access facility. @LCA
****************************************************************/
if db2_repos=1 then do /* @LCA*/
call logsay2 "Granting DB2 RRSAF access to the PKI",
"Services daemon." /* @LCA*/
call tsoserv "RDEFINE DSNR "db2_subsys".RRSAF",
"UACC(NONE)" /* @LCA*/
call tsoserv "PERMIT "db2_subsys".RRSAF",
"CLASS(DSNR) ACCESS(READ)",
"ID("daemon")" /* @LCA*/
call tsoserv "SETROPTS CLASSACT(DSNR)" /* @LCA*/
end /* @LCA*/
/***************************************************************
* The VSAM data sets created for PKI Services are protected.
* Grant access to these data sets for the PKI Services daemon
* and the administrator. @LCA
***************************************************************/
else do /* @LCA*/
call tsoserv "SETROPTS EGN GENERIC(DATASET)"
call tsoserv "ADDSD '"vsamhlq".**' UACC(NONE)"
call tsoserv "PERMIT '"vsamhlq".**' ID("daemon")",
"ACCESS(ALTER)" /* @D4A*/
if (vsamhlq ^= daemon) then do /* @D4A*/
call tsoserv "ADDSD '"daemon".**' UACC(NONE)" /* @D4A*/
call tsoserv "PERMIT '"daemon".**' ID("daemon")",
"ACCESS(ALTER)" /* @D4A*/
end /* @D4A*/
/************************************************************
* Give the administrators access to the VSAM data sets
* identified in the [ObjectStore] section of
* the pkiserv.conf file.
************************************************************/
call logsay2 "Allowing administrators to access",
"PKI VSAM databases ..." /* @LCC*/
call tsoserv "PERMIT '"vsamhlq".**' ID("pkigroup")",
"ACCESS(CONTROL)"
call tsoserv "SETROPTS GENERIC(DATASET) REFRESH"
end /* @LCA*/
/*6@LCM*/
/*********************************************************************/
/* If the key_type is 8 or 9 or 10 a PKCS #11 token must be created */
/* first before using it to create a CA certificate with Secure Key */
/* in the TKDS. @LEA*/
/*********************************************************************/
if (key_type=8 | key_type=9 | key_type=10) then do /* @LEA */
call logsay2 "Creating a PKCS #11 token... " /* @LEA */
call tsoserv "RACDCERT ADDTOKEN("caStore")" /* @LEA */
end /* @LEA */
/****************************************************************/
/* In order to create and sign digital certificates for others */
/* you need to define or import in RACF a Certificate Authority */
/* certificate and associated private key. */
/* This is done using the RACF RACDCERT GENCERT command. */
/****************************************************************/
if ca_dn ^= "" then do
call logsay2 "Creating the CA certificate ..."
if signing_ca_label = "" then /*@L4A*/
certcmd = "RACDCERT GENCERT CERTAUTH SUBJECTSDN("ca_dn")",
" WITHLABEL('"ca_label"') NOTAFTER(DATE("ca_expires"))",
" SIZE("ca_keysize")"
else /*@L4A*/
certcmd = "RACDCERT GENCERT CERTAUTH SUBJECTSDN("ca_dn")",
" WITHLABEL('"ca_label"')",
" SIGNWITH(CERTAUTH LABEL('"signing_ca_label"'))",
" NOTAFTER(DATE("ca_expires"))",
" SIZE("ca_keysize")" /*@L4A*/
if key_type=1 & key_backup=0 then
certcmd= certcmd || " ICSF"
else if key_type=2 then
certcmd= certcmd || " PCICC"
else if key_type=3 then
certcmd =certcmd || " DSA"
else if key_type=4 then
certcmd =certcmd || " NISTECC" /*@D5A*/
else if key_type=5 then
certcmd =certcmd || " BPECC" /*@D6A*/
else if key_type=6 then
certcmd =certcmd || " NISTECC(PKDS)" /*@LBA*/
else if key_type=7 then
certcmd =certcmd || " BPECC(PKDS)" /*@LBA*/
else if key_type=8 then
certcmd =certcmd || " RSA(TOKEN("caStore"))" /*@LEA*/
else if key_type=9 then
certcmd =certcmd || " NISTECC(TOKEN("caStore"))" /*@LEA*/
else if key_type=10 then
certcmd =certcmd || " BPECC(TOKEN("caStore"))" /*@LEA*/
call tsoserv certcmd
if key_type^=2 & key_type^=6 & key_type^=7 & key_type^=8,
& key_type^=9 & key_type^=10 & key_backup=1 /* @LEC*/
then do /* @D8C*/
/****************************************************************/
/* Export certificate and key to PKCS#12 dataset */
/****************************************************************/
say ""
say "Enter a passphrase to protect the key. You will need"
say " this value later if you need to restore the key."
say ""
say "Attention, the value will be displayed in the screen:"
parse pull pp
call logsay2 "Backing up the CA certificate ..."
certcmd = "RACDCERT CERTAUTH EXPORT(LABEL('"ca_label"'))",
" DSN("backup_dsn") FORMAT(PKCS12DER)",
" PASSWORD('"pp"')"
call tsoserv certcmd
end
if key_type=1 & key_backup=1 then do
/****************************************************************/
/* If ICSF was requested and key backup, reload the certificate */
/* to get the key migrated to ICSF */
/****************************************************************/
call logsay2 "Migrating the CA's private key to ICSF ..."
certcmd = "RACDCERT CERTAUTH ADD("backup_dsn")",
" PASSWORD('"pp"') ICSF"
call tsoserv certcmd
end
end /* ca_dn ^= "" */
/****************************************************************/
/* Mark the CA certificate as HIGHTRUST so HostIdMappings */
/* are honored */
/****************************************************************/
call logsay2 "Marking CA certificate as HIGHTRUST ..."
certcmd = "RACDCERT CERTAUTH ALTER(LABEL('"ca_label"')) HIGHTRUST"
call tsoserv certcmd
/*****************************************************************/
/* The CA certificate must be saved to a data set to assist the */
/* backup process. @L9C */
/*****************************************************************/
call logsay2 "Saving the CA certificate to a data set ..."/* @L9C*/
certcmd = "RACDCERT CERTAUTH EXPORT(LABEL('"ca_label"'))",
" DSN("cacert_dsn") FORMAT(CERTDER)" /* @L9C*/
call tsoserv certcmd
if (ra_label ^= "") then do /* @L4A*/
/**************************************************************/
/* Creating RA Certificate */
/**************************************************************/
call logsay2 "Creating the RA certificate ..." /* @L4A*/
certcmd = "RACDCERT ID("daemon") GENCERT SUBJECTSDN("ra_dn")",
" KEYUSAGE(HANDSHAKE) SIGNWITH(CERTAUTH LABEL('"ca_label"'))",
" NOTAFTER(DATE("ca_expires")) WITHLABEL('"ra_label"')" /* @L4A*/
call tsoserv certcmd /* @L4A*/
/***************************************************************/
/* Backing up RA Certificate */
/***************************************************************/
call logsay2 "Backing up RA certificate ..." /* @L4A*/
certcmd = "RACDCERT ID("daemon") EXPORT(LABEL('"ra_label"'))",
" DSN("ra_backup_dsn") FORMAT(PKCS12DER)",
" PASSWORD('"pp"')" /* @L4A*/
call tsoserv certcmd /* @L4A*/
end /* @L4A*/
/*****************************************************************/
/* The CA/RA certificate must be placed in a key ring so that */
/* PKI Services can access it. */
/*****************************************************************/
call logsay2 "Creating the PKI Services keyring ..."
call tsoserv "RACDCERT ADDRING("ca_ring") ID("daemon")"
call tsoserv "RACDCERT ID("daemon") CONNECT(CERTAUTH",
" LABEL('"ca_label"')",
" RING("ca_ring") USAGE(PERSONAL) DEFAULT) "
if (ra_label ^= "") then /* @L4A*/
call tsoserv "RACDCERT ID("daemon") CONNECT(LABEL('"ra_label"')",
" RING("ca_ring") USAGE(PERSONAL))" /* @D2C*/
/*******************************************************************/
/* Create the certificate for the webserver signed by your new CA */
/*******************************************************************/
if web_dn ^= "" then do
call logsay2 "Creating the Webserver SSL certificate and keyring ..."
call tsoserv "RACDCERT GENCERT ID("webserver") SIGNWITH(CERTAUTH",
" LABEL('"ca_label"'))",
" WITHLABEL('"web_label"') SUBJECTSDN("web_dn")",
" NOTAFTER(DATE("web_expires"))"
/****************************************************************/
/* Add the webserver's certificate to the webserver's RACF (SAF)*/
/* key ring @L9C */
/****************************************************************/
call tsoserv "RACDCERT ADDRING("web_ring") ID("webserver")"
call tsoserv "RACDCERT ID("webserver") CONNECT(ID("webserver")",
" LABEL('"web_label"') RING("web_ring") USAGE(PERSONAL) DEFAULT)"
end /* web_dn ^= "" */
/****************************************************************/
/* Add the PKI CA certificate to the webserver's RACF (SAF) */
/* key ring @L9C */
/****************************************************************/
if web_ring ^= "" then
call tsoserv "RACDCERT ID("webserver") CONNECT(CERTAUTH",
" LABEL('"ca_label"') RING("web_ring"))"
****************************************************************/
/* The webserver's root CA certificate must be saved to a data */
/* set so that it may be OPUT to an HFS file for download @L9A*/
/****************************************************************/
/* If webserver certificate is generated in this exec and */
/* it is issued by the self-signed PKI CA, ie. the self-signed */
/* PKI CA is the webserver's root CA, export it for OPUT @L9A*/
if web_dn ^= "" & signing_ca_label = "" then do /*@L9A*/
call logsay2 "Saving the webserver's root CA certificate to a ",
"data set for OPUT ..." /*@L9A*/
certcmd = "RACDCERT CERTAUTH EXPORT(LABEL('"ca_label"'))",
" DSN("export_dsn") FORMAT(CERTDER)" /*@L9A*/
call tsoserv certcmd
end
else /*@L9A*/
/* Need to manually export the webserver's root
CA certificate @L9A*/
call logsay2 "You need to manually export the webserver's ",
"root CA certificate." /*@L9A*/
if unix_sec = 0 then do
/****************************************************************/
/* Not setting up z/OS UNIX higher security. However, the */
/* daemon does need access to one server service. So, if the */
/* daemon user ID is not uid 0, then it must be given read */
/* access to FACILITY class profile BPX.SERVER */
/****************************************************************/
if strip(daemon_uid,L,'0') ^= "" then do /* if daemon not uid 0 */
call logsay2 "Giving" daemon "access to BPX.SERVER ..."
call tsoserv "RDEFINE FACILITY BPX.SERVER"
call tsoserv "PERMIT BPX.SERVER CLASS(FACILITY)",
" ID("daemon") ACCESS(READ)"
end
end
else do
call logsay2 "Setting up or modifying z/OS UNIX security ..."
if unix_sec = 2 then do
/****************************************************************/
/* Set up z/OS UNIX to operate with a higher level of */
/* security than traditional UNIX, by defining BPX.SERVER and */
/* BPX.DAEMON classes. */
/****************************************************************/
call tsoserv "RDEFINE FACILITY BPX.SERVER"
call tsoserv "RDEFINE FACILITY BPX.DAEMON"
do i = 1 to bpx_userid.0
call tsoserv "PERMIT BPX.SERVER CLASS(FACILITY)",
" ID("bpx_userid.i") ACCESS(READ)"
call tsoserv "PERMIT BPX.DAEMON CLASS(FACILITY)",
" ID("bpx_userid.i") ACCESS(READ)"
end
end
/****************************************************************/
/* To use the higher level of security, you need to establish */
/* RACF program control and enable the PKI Services daemon */
/* user ID and webserver daemon user ID to access protected */
/* UNIX daemon services. */
/****************************************************************/
call tsoserv "PERMIT BPX.SERVER CLASS(FACILITY) ID("daemon")",
" ACCESS(READ)"
call tsoserv "PERMIT BPX.DAEMON CLASS(FACILITY) ID("daemon")",
" ACCESS(READ)"
call tsoserv "PERMIT BPX.SERVER CLASS(FACILITY) ID("webserver")",
" ACCESS(UPDATE)"
call tsoserv "PERMIT BPX.DAEMON CLASS(FACILITY) ID("webserver")",
" ACCESS(READ)"
if unix_sec = 2 then do
/****************************************************************/
/* Set the PKI Services daemon and DLLs up for program control */
/****************************************************************/
call tsoserv "RDEFINE PROGRAM * UACC(NONE)"
do i = 1 to pgmcntl_dsn.0
call tsoserv "RALTER PROGRAM * ADDMEM("pgmcntl_dsn.i"//NOPADCHK)",
" UACC(READ)"
end
call tsoserv "SETROPTS WHEN(PROGRAM)"
end
call tsoserv "PERMIT * CLASS(PROGRAM)",
" ID("surrog") ACCESS(READ)"
call tsoserv "SETROPTS WHEN(PROGRAM) REFRESH"
end /* unix_sec ^= 0 */
/**********************************************************************/
/* Access to the keyring can be controlled either by the profiles in */
/* the FACILITY class or by the profile in the RDATALIB class. The set*/
/* up indicated below uses the FACILITY class. If you want specific */
/* access control on the PKI Services keyring and the Web Server */
/* keyring, you may use the RDATALIB class. For example, for the */
/* daemon's keyring: set up PKISRVD to have CONTROL access on */
/* PKISRVD.CAring.LST. For the web server's keyring: set up WEBSRV to */
/* have READ access on WEBSRV.SSLring.LST. @DBA*/
/**********************************************************************/
/* Allow the daemon to be a certificate authority and give access to */
/* its keyring @DBC*/
/**********************************************************************/
call logsay2 "Allowing the PKI Services daemon to act as a CA ..."
call tsoserv "RDEFINE FACILITY IRR.DIGTCERT.GENCERT"
call tsoserv "RDEFINE FACILITY IRR.DIGTCERT.LISTRING"
/* 1@DBD */
call tsoserv "PERMIT IRR.DIGTCERT.GENCERT CLASS(FACILITY)",
" ID("daemon") ACCESS(CONTROL)"
call tsoserv "PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY)",
" ID("daemon") ACCESS(READ)"
/* 2@DBD */
/*****************************************************************/
/* If the webserver cert and keyring were created in this exec, */
/* Allow the webserver to access its keyring */
/*****************************************************************/
if web_dn ^= "" then do /* @D4A*/
call logsay2 "Allowing the Webserver to access its keyring ..."
call tsoserv "PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY)",
" ID("webserver") ACCESS(READ)"
/* 2@DBD */
end /* web_dn ^= "" */ /* @D4A*/
/*****************************************************************/
/* Permit the webserver daemon User ID to switch identity to the */
/* surrogate Id */
/*****************************************************************/
call logsay2 "Allowing the Webserver to switch identity to "surrog" ..."
call tsoserv "SETROPTS CLASSACT(SURROGAT)"
call tsoserv "RDEFINE SURROGAT BPX.SRV."surrog
call tsoserv "PERMIT BPX.SRV."surrog" CLASS(SURROGAT)",
" ID("webserver") ACCESS(READ)"
call tsoserv "SETROPTS RACLIST(SURROGAT) REFRESH"
/* @D8D*/
/***************************************************/
/* Allow the daemon to use ICSF */
/***************************************************/
if csfkeys_profile ^= '' | csfserv_profile ^= '' then do /* @D8M*/
call logsay2 "Allowing the PKI Services daemon to use ICSF ..."
call tsoserv "SETROPTS GENERIC(CSFKEYS CSFSERV)"
call tsoserv "SETROPTS GENERIC(CSFKEYS CSFSERV) REFRESH"
/* @D8D*/
if csfusers_grp ^= '' then do /* @D8M*/
call tsoserv "CONNECT" daemon "GROUP(" csfusers_grp ")" /* @D8M*/
call tsoserv "CONNECT" surrog "GROUP(" csfusers_grp ")" /* @D8M*/
end /* @D8M*/
if csfkeys_profile ^= '' then do
call tsoserv "RDEFINE CSFKEYS" csfkeys_profile "UACC(NONE)"
if csfusers_grp ^= '' then /* @D8A*/
call tsoserv "PERMIT" csfkeys_profile "CLASS(CSFKEYS)", /* @D8A*/
" ID("csfusers_grp") ACCESS(READ)" /* @D8A*/
else /* @D8A*/
call tsoserv "PERMIT" csfkeys_profile "CLASS(CSFKEYS)",
" ID("daemon") ACCESS(READ)"
call tsoserv "SETROPTS CLASSACT(CSFKEYS) RACLIST(CSFKEYS)"
call tsoserv "SETROPTS RACLIST(CSFKEYS) REFRESH"
end
if csfserv_profile ^= '' then do
call tsoserv "RDEFINE CSFSERV" csfserv_profile "UACC(NONE)"
if csfusers_grp ^= '' then do /* @D8A*/
call tsoserv "PERMIT" csfserv_profile "CLASS(CSFSERV)", /* @D8A*/
" ID("csfusers_grp") ACCESS(READ)" /* @D8A*/
end /* @D8A*/
else do /* @D8A*/
call tsoserv "PERMIT" csfserv_profile "CLASS(CSFSERV)",
" ID("daemon") ACCESS(READ)"
call tsoserv "PERMIT" csfserv_profile "CLASS(CSFSERV)",
" ID("surrog") ACCESS(READ)"
end /* @D8A*/
call tsoserv "SETROPTS CLASSACT(CSFSERV) RACLIST(CSFSERV)"
call tsoserv "SETROPTS RACLIST(CSFSERV) REFRESH"
end
end /* @D8D*/
if (key_gen=1) then do /*@L9A*/
/***************************************************/
/* Allow the daemon to generate key pairs @L9A */
/***************************************************/
call logsay2 "Allowing the PKI Services daemon to ",
"generate key pairs ..." /*@L9A*/
if cryptoz_profile_so ^= '' & cryptoz_profile_user ^= ''
then do /*@L9A*/
call tsoserv "SETROPTS CLASSACT(CRYPTOZ)" /*@L9A*/
call tsoserv "SETROPTS GENERIC(CRYPTOZ)" /*@L9A*/
call tsoserv "SETROPTS RACLIST(CRYPTOZ)" /*@L9A*/
call tsoserv "RDEFINE CRYPTOZ",
cryptoz_profile_so "UACC(NONE)" /*@L9A*/
call tsoserv "RDEFINE CRYPTOZ",
cryptoz_profile_user "UACC(NONE)" /*@L9A*/
call tsoserv "PERMIT" cryptoz_profile_so "CLASS(CRYPTOZ)",
" ID("daemon") ACCESS(UPDATE)" /*@D4C*/
call tsoserv "PERMIT" cryptoz_profile_user "CLASS(CRYPTOZ)",
" ID("daemon") ACCESS(CONTROL)" /*@D4C*/
call tsoserv "SETROPTS RACLIST(CRYPTOZ) REFRESH" /*@L9A*/
call tsoserv "SETROPTS GENERIC(CRYPTOZ) REFRESH" /*@L9A*/
end /*@L9A*/
if cryptoz_grp ^= '' then do /*@L9A*/
call tsoserv "CONNECT" daemon "GROUP(" cryptoz_grp ")" /*@L9A*/
end /*@L9A*/
end
/***************************************************/
/* daemon no longer needs access to OCSF */
/***************************************************/
/***********************************************************
* Tie the daemon user ID to PKI Services started procedure
***********************************************************/
call logsay2 "Creating the STARTED class profile for the daemon ..."
call tsoserv "RDEFINE STARTED PKISERVD.* STDATA(USER("daemon"))"
call tsoserv "SETROPTS CLASSACT(STARTED) RACLIST(STARTED)"
call tsoserv "SETROPTS RACLIST(STARTED) REFRESH"
/****************************************************************/
/* Give the surrogate user ID authority to request certificate */
/* generation functions. */
/****************************************************************/
call logsay2 "Allowing "surrog" to request certificate functions ..."
call tsoserv "SETR GENERIC(FACILITY)"
/*
* When a CA Domain is not specified, use the default value for
* the end user functions generic profile name. When a CA Domain
* is specified, append a dot/period(".") followed by the CA
* Domain value to the default value.
*/
if (ca_domain = "") then /* @L4A*/
profname = "IRR.RPKISERV.**" /* @L4A*/
else /* @L4A*/
profname = "IRR.RPKISERV.*."||ca_domain_trunc /* @L4A*/
call tsoserv "RDEFINE FACILITY "||profname /* @L4C*/
call tsoserv "PERMIT "||profname||" CLASS(FACILITY)",
" ID("surrog") ACCESS(CONTROL)" /* @L4C*/
/****************************************************************/
/* The administrative functions of PKI Services are protected */
/* by the IRR.RPKISERV.PKIADMIN FACILITY class resource and */
/* optionally by the <domain>.<action>.<emplate> PKISERV class */
/* resources. */
/* The following commands give UPDATE access on the resource in */
/* the facility class and READ access on the resources in the */
/* PKISERV class to the PKI services group to allow them to act */
/* on certificate requests and issued certificates. */
/****************************************************************/
call logsay2 "Creating the profile to protect PKI Admin functions ..."
/*
* When a CA Domain is not specified, use the default value for
* the administrative function profile name. When a CA Domain
* is specified, append a dot/period(".") followed by the CA
* Domain value to the default value.
*/
if (ca_domain = "") then /* @L4A*/
profname = "IRR.RPKISERV.PKIADMIN" /* @L4A*/
else /* @L4A*/
profname = "IRR.RPKISERV.PKIADMIN."||ca_domain_trunc /* @L4A*/
call tsoserv "RDEFINE FACILITY "||profname /* @L4C*/
call tsoserv "PERMIT "||profname||" CLASS(FACILITY)",
" ID("pkigroup") ACCESS(UPDATE)" /* @L4C*/
call tsoserv "PERMIT "||profname||" CLASS(FACILITY)",
" ID("surrog") ACCESS(NONE)" /* @L4C*/
call tsoserv "SETROPTS RACLIST(FACILITY) REFRESH"
/****************************************************************/
/* If granular control is set, create the corresponding */
/* profiles for the administrative functions and grant access */
/* to different groups. The following commands show the */
/* examples of giving pkigroup authority to perform all the */
/* functions, except queryreqdetails and querycertdetails which */
/* are permitted for pkigroup2 respectively. */
/****************************************************************/
if AdminGranularControl = 1 then do /* @LDA */
call tsoserv "PERMIT "||profname||" CLASS(FACILITY)",
" ID("pkigroup1") ACCESS(UPDATE)" /* @DAC */
call tsoserv "PERMIT "||profname||" CLASS(FACILITY)",
" ID("pkigroup2") ACCESS(UPDATE)" /* @DAC */
call tsoserv "SETROPTS RACLIST(FACILITY) REFRESH"
call logsay2 "Creating the profiles to granular control",
" individual PKI Admin function......" /* @LDA */
cadomain = ca_domain /* @LDA */
if(cadomain =="") then /* @LDA */
cadomain = "NOCADOMAIN" /* @LDA */
do r = 1 to template.0 /* @DAC */
/* Granular Access to pkigroup1 @LDA */
do p = 1 to actions1.0
call granaccess cadomain template.r pkigroup1 actions1.p
end /* @DAC */
call logsay " " /* @LDA */
/* Granular Access to pkigroup2 @LDA */
do q = 1 to actions2.0
call granaccess cadomain template.r pkigroup2 actions2.q
end /* @DAC */
call logsay " " /* @LDA */
end /* @LDA */
/* The actions POSTCERT and CREATECRL are not template based */
call tsoserv "RDEFINE PKISERV "|| cadomain || ".",
||"POSTCERT"|| " UACC(NONE)" /* @DAC */
call tsoserv "PERMIT "|| cadomain || "." ||"POSTCERT",
|| " CLASS(PKISERV) ID("pkigroup1") ACCESS(READ)" /* @DAC */
call tsoserv "RDEFINE PKISERV "|| cadomain || ".",
||"CREATECRL"|| " UACC(NONE)" /* @DAC */
call tsoserv "PERMIT "|| cadomain || "." ||"CREATECRL",
|| " CLASS(PKISERV) ID("pkigroup1") ACCESS(READ)" /* @DAC */
call tsoserv "SETROPTS RACLIST(PKISERV) REFRESH" /* @LDA */
end /* @LDA */
/******************************/
/* Done. Now write to the log */
/******************************/
upper daemon vsamhql export_dsn
call logsay " "
call logsay "-------------------------------------------------"
call logsay "Information needed for PKI Services UNIX set up:"
call logsay "-------------------------------------------------"
call logsay " "
call logsay "The daemon user ID is:"
call logsay " " daemon
call logsay " "
call logsay "The VSAM high level qualifier is:"
call logsay " " vsamhlq
call logsay,
"This is needed for the [ObjectStore] section in pkiserv.conf"
call logsay " "
call logsay "The PKI Services' DER encoded certificate is in data set:"
call logsay " " cacert_dsn /*@L9C*/
call logsay " "
if export_dsn ^= "" then do /*@L9A*/
call logsay "The webserver's DER encoded root "
call logsay "CA certificate is in data set:"
call logsay " " export_dsn /*@L9A*/
call logsay,
"This must be OPUT to /var/pkiserv/cacert.der with ",
"the BINARY option"
call logsay " "
end /*@L9A*/
else do /*@L9A*/
call logsay "You need to find the webserver's root CA ",
"certificate and export it manually." /*@L9A*/
call logsay " " /*@L9A*/
end
call logsay "The fully qualified PKI Services' SAF keyring is:"
call logsay " " daemon"/"ca_ring
call logsay,
"This is needed for the [SAF] section in pkiserv.conf"
if ra_label ^= "" then do /*@L4A*/
call logsay " " /*2@L4A*/
call logsay "The label of the PKI Services' RA certificate is:"
call logsay " " ra_label /*@L4A*/
call logsay, /*@L4A*/
"This is needed for the [SAF] section in pkiserv.conf" /*@L4A*/
end /*@L4A*/
call logsay " "
if ca_dn ^= "" then do
call logsay "The PKI Services CA DN is:"
call norm_dn ca_dn
call logsay " " dn
call logsay "The suffix must match the LDAP suffix in slapd.conf"
end
else
call logsay "CA certificate not created by this exec"
call logsay " "
if ra_dn ^= "" then do /*@L4A*/
call logsay "The PKI Services RA DN is:" /*@L4A*/
call norm_dn ra_dn /*@L4A*/
call logsay " " dn /*2@L4A*/
call logsay "The suffix must match the LDAP suffix in slapd.conf"
end /*@L4A*/
else /*@L4A*/
call logsay "RA certificate not created by this exec" /*@L4A*/
call logsay " " /*@L4A*/
call logsay, /*2@L4A*/
"The recommended location for the pkiserv.conf and pkiserv.tmpl is:"
if ca_domain = "" then /*@L4A*/
call logsay " /etc/pkiserv" /*@L4A*/
else /*@L4A*/
call logsay " /etc/pkiserv/"ca_domain /*@L4A*/
call logsay " " /*@L4A*/
call logsay, /*2@L4A*/
"Set the following environment variables in pkiserv.envars:"
if ca_domain = "" then /*@L4A*/
call logsay " _PKISERV_CONFIG_PATH=/etc/pkiserv" /*@L4A*/
else do /*2@L4A*/
call logsay " _PKISERV_CA_DOMAIN="ca_domain /*@L4A*/
call logsay " _PKISERV_CONFIG_PATH=/etc/pkiserv/"ca_domain
end /*@L4A*/
call logsay " " /*@L4A*/
call logsay, /*2@L4A*/
"Set the following environment variable in your httpd envvars files:"
if ca_domain = "" then /*@L4A*/
call logsay " _PKISERV_CONFIG_PATH=/etc/pkiserv" /*@L4A*/
else /*2@L4A*/
call logsay " _PKISERV_CONFIG_PATH_"TRANSLATE(ca_domain),
"=/etc/pkiserv/"ca_domain /*@L4A*/
call logsay " " /*@L4A*/
if web_dn ^= "" then do
call logsay "The webserver's SAF keyring is:"
call logsay " " web_ring
call logsay,
"This is needed for the KeyFile directive in httpd*.conf files"
call logsay " "
call logsay "The Webserver's DN is:"
call norm_dn web_dn
call logsay " " dn
call logsay "The left most RDN must be the webserver's fully",
"qualified domain name"
end
else
call logsay,
"Webserver certificate and keyring not created. You must add the CA",
"certificate as a 'trusted root' manually"
call logsay " "
if log_dsn ^= "" then do
x = OUTTRAP(MSGS.)
'EXECIO' logdata.0 'DISKW IKYLOGDD (FINIS STEM LOGDATA.'
'FREE FI(IKYLOGDD)'
x=OUTTRAP('OFF')
say "Commands complete. Results written to log data set" log_dsn
end
/***********************/
/* Exit */
/***********************/
say 'The IKYSETUP EXEC has completed.'
Exit max_return_code
/*************************************************************/
/* tsoserv - echo rc and commands and track highest rc */
/*************************************************************/
tsoserv:
Parse arg cmd
return_code = 0
skipit= 0
if runopt = "NO" | runopt = "PROMPT" then
call logsay cmd
if runopt = "PROMPT" then do
say "Run command (y/n) ?"
parse pull ans
if substr(ans,1,1) ^= 'Y' & substr(ans,1,1) ^= 'y' then
skipit= 1
end
if skipit = 0 then
if runopt = "YES" | runopt = "PROMPT" then do
msg_status= MSG('ON')
x=OUTTRAP('rac_ret.')
Address TSO cmd
return_code=rc
y=OUTTRAP('OFF')
call logsay 'Return code' return_code 'from->' cmd
If return_code\=0 then do
Do j=1 to rac_ret.0
call logsay rac_ret.j
end
end
end
max_return_code= max(max_return_code,return_code)
return return_code
/* 1@LDD */
/*************************************************************/
/* logsay - echo messages to the terminal and logdata stem */
/*************************************************************/
logsay:
Parse arg cmd
parse var cmd leftpart " PASSWORD('" pw "') " rightpart
if pw ^= "" then
cmd= leftpart "PASSWORD('******')" rightpart
say cmd
cmdlen = length(cmd) /* @L5A */
Do Ln = 1 to length(cmd) by 252 /* @L5A */
k= logdata.0 + 1
logdata.k=substr(cmd, Ln, min(252, cmdlen)) /* @L5C */
logdata.0= k
cmdlen = cmdlen - min(252, cmdlen) /* @L5A */
end /* @L5A */
return 0
/*************************************************************/
/* logsay2 - echo a blank line before echoing the command */
/*************************************************************/
logsay2:
Parse arg cmd2
call logsay " "
call logsay cmd2
return 0
/*************************************************************/
/* norm_dn - transform the RACF dn keywords to an LDAP dn */
/*************************************************************/
norm_dn:
parse arg in_dn
parse var in_dn q.1 "('" v.1 "')",
q.2 "('" v.2 "')",
q.3 "('" v.3 "')",
q.4 "('" v.4 "')",
q.5 "('" v.5 "')",
q.6 "('" v.6 "')",
q.7 "('" v.7 "')" rest
dns.= ""
do i = 1 to 7
q= strip(q.i)
upper q
if q = "" then
leave
if q = "CN" then
dns.1= "CN=" || v.i
else
if q = "T" then
dns.2= "T=" || v.i
else
if q = "OU" then
dns.3= "OU=" || v.i
else
if q = "O" then
dns.4= "O=" || v.i
else
if q = "L" then
dns.5= "L=" || v.i
else
if q = "SP" then
dns.6= "ST=" || v.i
else
dns.7= "C=" || v.i
end
dn= ""
do i = 1 to 7
if dns.i ^= "" then
if dn = "" then
dn= dns.i
else
dn= dn || "," || dns.i
end
return 0
/*************************************************************/
/* granaccess - Create profiles and grant access for Granular*/
/* Control */
/*************************************************************/
granaccess: /* @LDA */
parse arg cadomain template pkigroup action /* @DAC */
call tsoserv "RDEFINE PKISERV "|| cadomain || ".",
||action || "." || template "UACC(NONE)" /* @DAC */
call tsoserv "PERMIT "|| cadomain || "." ||action,
|| "." || template || " CLASS(PKISERV) ID("pkigroup")",
"ACCESS(READ)" /* @DAC */
return 0 /* @LDA */
|
z/OS Cryptographic Services PKI Services Guide and Reference
Copyright IBM Corporation 1990, 2014