Front cover Implementing PKI Services on z/OS Installation of PKI and all of its prerequistes on z/OS An example of the PKI Exit PKI’s use of ICSF to store Master Key Chris Rayns Theo Antoff Jack Jones Patrick Kappeler Vicente Ranieri Roland Trauner ibm.com/redbooks International Technical Support Organization Implementing PKI Services on z/OS February 2004 SG24-6968-00 Note: Before using this information and the product it supports, read the information in “Notices” on page vii. First Edition (February 2004) This edition applies to z/OS Version 1, Release 3. © Copyright International Business Machines Corporation 2004. All rights reserved. Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents Notices . vii Trademarks . viii Preface . ix The team that wrote this redbook. ix Become a published author . x Comments welcome. xi Chapter 1. Security Server PKI Services. 1 1.1 Overview of digital certificate. 2 1.2 The PKIX standards . 4 1.2.1 CA hierarchy . 6 1.2.2 The X.509 certificate and Certificate Revocation List . 9 1.2.3 The x.509 v3 certificate extension fields . 14 1.2.4 Certificate and CRL appearance. 17 1.3 The z/OS PKI Services . 21 1.3.1 Security Server PKI Services in z/OS . 21 1.3.2 Prerequisite products . 22 1.3.3 Requests supported by z/OS PKI Services. 23 1.3.4 Browser and server certificates. 24 1.3.5 The z/OS PKI Services architecture . 26 1.4 Security Server PKI Services enhancement in z/OS V1R4. 29 1.4.1 Sysplex support. 30 1.4.2 Event notification via e-mail . 32 1.4.3 Additional distinguished name qualifier support . 33 1.4.4 LDAP password encryption. 33 1.4.5 PKCS#7 certificate chain support . 33 1.4.6 Key generation via PCICC . 35 1.4.7 Additional default CERTAUTH . 35 1.4.8 Summary of z/OS PKI external characteristics as of z/OS V1R4 . 35 Chapter 2. RACF for PKI Services . 37 2.1 Introduction to creating an RACF environment for new products . 38 2.1.1 RACF group structure . 38 2.1.2 Machine user IDs . 39 2.1.3 System data set profiles . 40 2.1.4 Ownership . 40 2.2 New RACF features . 40 2.2.1 Access control lists . 41 © Copyright IBM Corp. 2004. All rights reserved. iii 2.2.2 Automatic assignment of UID/GID . 50 2.3 Setting up RACF environment for PKI prerequisites . 55 2.3.1 z/OS UNIX level security. 56 2.3.2 RACF for Web server . 58 2.3.3 RACF for OCSF and OCEP . 59 2.3.4 RACF for LDAP. 59 2.3.5 RACF for ICSF . 60 2.4 Setting up the RACF environment for PKI Services . 61 2.4.1 Add RACF groups for PKI Services . 61 2.4.2 Adding RACF user IDs for PKI Services . 62 2.4.3 Adding PKI data set profiles . 63 2.4.4 Using RACF to create certificates . 64 2.4.5 Daemon and server control for PKI user ID and surrogate user ID . 76 2.4.6 Allow PKI user ID to act as CA . 76 2.4.7 Allow Web server to access its own key ring . 77 2.4.8 Allow Web server user ID to switch identity to surrogate user ID . 77 2.4.9 Profile for PKI Services procedure in class STARTED . 77 2.4.10 Allow access for PKISTU to OCSF . 77 2.4.11 ICSF . 77 2.4.12 Protect certificate functions . 79 2.5 RACF administration for PKI Services . 84 2.5.1 Creating a help desk function . 84 2.5.2 Administering certificates with the HostIdMappings extension . 85 2.5.3 Display your PKI Services certificates. 86 2.5.4 Establishing PKI Services as intermediate certificate authority . 89 2.5.5 Renewing your PKI Services CA certificate . 91 2.5.6 Recovering a CA certificate profile . 91 2.5.7 Controlling applications that call R_PKIServ. 94 2.5.8 Using encrypted passwords for LDAP servers . 97 2.5.9 Register a Personal Certificate with RACF . 100 Chapter 3. Easy steps to get PKI up and running . 105 3.1 Preparing the PKI Server installation . 106 3.1.1 Steps to set up the PKI server . 106 3.2 Prepare and configure the environment . 106 3.3 Setting up the Web servers for PKI . 107 3.3.1 Why do we need two Web servers? . 108 3.3.2 Setting up the Web server as a secure Web server . 108 3.3.3 Customizing the Web server for SSL . 108 3.3.4 Customizing the first Web server for PKI . 109 3.3.5 Customizing the second Web server for PKI . 113 3.4 Setting up the LDAP server for PKI. 116 3.4.1 LDAP setup: running the ldapcnf utility . 119 iv Implementing PKI Services on z/OS 3.5 Setting up the PKI Services task . 126 3.6 Configure OCSF and OCEP to work with PKI Services . 127 3.7 Configure the PKI Services . 128 3.7.1 Set up the environment variables for PKI Services. 129 3.7.2 Customizing the PKI Services configuration file . 130 3.7.3 Customizing the PKI template. 132 3.8 Checking the VSAM data set . 134 Chapter 4. Customizing the z/OS PKI Services: the template file . 137 4.1 The template file, CGI, and the Web end user . 138 4.1.1 The template file sections . 138 4.1.2 The CGI modules . 151 4.1.3 Relationship between CGI modules and Web user templates . 153 4.1.4 An example of simple customization of the template file . 155 4.2 Structure of the template file for interaction with the PKI Administrator . 158 4.2.1 The CGI modules . 158 4.2.2 Customization of the administration Web pages. 160 4.2.3 PKI administrator e-mail address . 161 4.2.4 PKI Services certification policy . 161 4.2.5 Link to PKI Services from your home page. 162 4.2.6 Certificate authentication for administrators . 163 Chapter 5. PKI Installation using the IKYSETUP REXX exec . 175 5.1 IKYSETUP overview . 176 5.2 IKYSETUP variables . 176 5.2.1 Compulsory changes to IKYSETUP . 177 5.2.2 Probable changes to IKYSETUP . 179 5.2.3 Optional changes to IKYSETUP . 184 Chapter.