Abstract for Cryptographic Services PKI Services Guide and Reference
z/OS Version 2 Release 1 summary of changes
Planning
Introducing PKI Services
What is PKI Services?
What is a certificate authority?
What is PKI?
Basic components of PKI Services and related products
Component diagram
Supported standards
Supported certificate types
Supported certificate fields and extensions
Planning your implementation
Installing PKI Services
Requirements for sysplex support
Determining prerequisite products
IBM HTTP server (optional)
Websphere Application Server (optional)
LDAP directory server
OCSF (optional)
ICSF (optional)
sendmail (optional)
OCEP (optional)
DB2 (optional)
Identifying skill requirements
Team members
Skills for setting up prerequisite products
Skills for setting up PKI Services
Creating an implementation plan
Task roadmap for implementing PKI Services
Installing and configuring prerequisite products
Tasks to perform before setting up PKI Services
Installing and configuring the IBM HTTP Server
Steps for setting up the IBM HTTP Server for PKI Services
Installing and configuring Websphere Application Server for z/OS
Installing and configuring LDAP
Steps for installing and configuring LDAP
Installing and configuring ICSF (optional)
Configuring sendmail (optional)
Installing and configuring DB2
Tasks to perform before configuring PKITP
Installing and configuring OCSF
Installing and configuring OCEP
Configuring your system for PKI Services
Running IKYSETUP to perform RACF administration
Overview of IKYSETUP
Before you begin
Variables whose values must change
Variables whose values might change depending on setup
Deciding the value of key_backup
Deciding the value of key_type
Deciding the value of restrict_surrog
Deciding the value of unix_sec
Deciding the value of db2_repos and db2_subsys
Deciding the value of AdminGranularControl
Table of IKYSETUP variables that you might want to change
Variables you can optionally change
Specifying when the CA certificate and Web server certificates expire
Steps for setting the expiration dates for the CA certificate and Web server certificate
Table of IKYSETUP variables you can optionally change
Steps for performing RACF tasks using IKYSETUP
Sample IKYSETUP log data set
Configuring the UNIX runtime environment
Steps for copying files
Optionally updating PKI Services environment variables
(Optional) Steps for updating PKI Services environment variables
Optionally updating the pkiserv.conf configuration file
(Optional) Steps for updating the configuration file
Updating pkiserv.conf after installing a new release of z/OS
Steps for setting up the var directory
Tailoring the LDAP configuration for PKI Services
Steps for loading schema.user.ldif
Setting up authorization to create and access CRLs and certificates
Establishing a secure connection with LDAP (optional)
Updating IBM HTTP Server configuration and starting the server
Setting up IBM HTTP Server 7.0
Steps for updating the IBM HTTP Server V7.0 configuration files
Starting and stopping the IBM HTTP Server V7.0
Setting up IBM HTTP Server V5.3
Steps for updating the IBM HTTP Server configuration files
Steps for starting the IBM HTTP Server
Tailoring the PKI Services configuration file for LDAP
Excerpt of LDAP section
Storing information for encrypted passwords for your LDAP servers
Steps for tailoring the LDAP section of the configuration file
Creating the object store and ICL
The object store and ICL
Creating the object store and ICL using VSAM data sets
Planning VSAM storage requirements
Determining storage needs for the ICL
Determining storage needs for the object store
(Optional) preliminary steps for establishing VSAM RLS
Steps for creating the VSAM object store, ICL data sets, indexes
(Optional) steps for enabling existing data sets for VSAM RLS
Tuning VSAM performance
(Optional) steps for adding VSAM buffer space
Backing up and restoring the VSAM data sets
Steps for backing up the VSAM data sets
Steps for restoring the VSAM data sets
Creating the object store and ICL using DB2 tables
Sysplex considerations
Planning DB2 storage requirements
Steps for creating the object store and ICL DB2 tables
Converting the object store and ICL from VSAM to DB2
Steps for converting the object store and ICL from VSAM to DB2
Columns in the ICL and object store DB2 tables
Starting and stopping PKI Services
Steps for starting the PKI Services daemon
Stopping the PKI Services daemon
Customizing PKI Services
Customizing the end-user Web application if you use REXX CGI execs
Contents of the pkiserv.tmpl certificates templates file
What are substitution variables?
What are named fields?
INSERT sections
Named fields in INSERT sections
The APPLICATION sections
Templates that PKI Services provides
TEMPLATE sections
Summary of subsections contained in certificate templates
Summary of fields in certificate templates
Examining the pkiserv.tmpl file
Examining the APPLICATION section
Examining the PKISERV application
Examining the CUSTOMERS application
Examining the TEMPLATE section
Examining the INSERT section
Relationship between CGIs and the pkiserv.tmpl file
Steps for performing minimal customization
Steps for additional first-time customization
Steps for retrofitting release changes into the templates
Locating code for customizing end-user Web pages
Steps for adding a new certificate template
Changing the runtime user ID
Steps for changing the runtime user ID on requests
Steps for changing the runtime user ID at retrieval
Customizing the OtherName field
Steps for customizing the sample AltOther_<OID> INSERTs
Customizing the administration Web pages if you use REXX CGI execs
CGIs for administration Web pages
Customizing the administration Web pages
Steps for customizing the administration Web pages
Changing the runtime behavior for accessing administration pages
Steps for changing control of access to administration pages
Implementing the Web application using Java server pages
Certificate templates files used with JSPs
Examining the pkitmpl.xml file
Roadmap for implementing the PKI Services Web application using JSPs
Steps for preparing to implement the PKI Services Web application using JSPs
Giving Websphere users authorization to use PKI Services functions
Steps for giving Websphere users authorization to use PKI Services functions
Allowing Websphere users to renew and revoke browser certificates
Steps for allowing Websphere users to renew and revoke browser certificates
Customizing the PKI Services Web application
Updating the template file
(Optional) Modifying the JSP files and the EAR file
Steps for updating the EAR file
Deploying the EAR file to a Websphere application server
Steps for deploying the EAR file to a Websphere application server
Directories for JSP files
Advanced customization
Scaling for high volume installations
Using certificate policies
Steps for creating the CertificatePolicies extension on a global basis
Steps for creating the CertificatePolicies extension on a template basis
Updating the signature algorithm
Steps for changing the signature algorithm
Customizing distribution point CRLs
Specifying the URI format
Determining CRLDistURIn
Specifying an HTTP URI
Specifying an LDAP URI
Determining CRLDistDirPath
Steps for customizing distribution point CRLs
How distribution point CRLs work
How DP CRLs are published
How DP CRLs are partitioned
What about CA certificates?
Enabling support for large CRLs
Steps for enabling support for large CRLs
Using the OCSP responder
Creating a distribution point ARL
Adding an application domain
Creating application domains when you use REXX CGIs to implement the Web application
Steps for creating multiple application sections in the PKI Services template file
Steps for adding application domains to the Web server configuration files
Creating application domains when you use JSPs to implement the Web application
Steps for creating application domains other than Application2
Adding a new CA domain
Task overview
Task roadmap for adding CA domains
Recording your progress adding CA domains
Subtask 1: Steps for planning additional CA domains
Subtask 2: Steps for reconfiguring your initial CA domain to allow it to coexist with other CA domains
Subtask 3: Steps for running the IKYSETUP exec
Subtask 4: Steps for configuring the UNIX environment
Subtask 5: Steps for updating the PKI Services template file
Subtask 6: Steps for updating the Web server configuration
Updating the Web server configuration if you use REXX CGI execs
Updating the Web server configuration if you use Java server pages (JSPs)
Subtask 7: Creating the object store and ICL
Subtask 8: Steps for starting PKI Services
Enabling Simple Certificate Enrollment Protocol (SCEP)
Overview of SCEP preregistration
Overview of certificate request processing for preregistered SCEP clients
Variables used in the <PREREGISTER> section
Checking certificate fingerprints
Steps for enabling Simple Certificate Enrollment Protocol (SCEP)
Customizing e-mail notifications sent to users
Steps for customizing e-mail notification forms
Setting up automatic renewal of certificates
Steps for setting up automatic certificate renewal
Setting up PKI Services to generate keys for certificate requests
Steps for setting up PKI Services to generate keys for certificate requests
Adding custom extensions to certificates
Steps for adding a custom extension to a certificate template if you are using REXX CGI execs
Steps for adding a custom extension to a certificate template if you are using JSPs
Forming the CustomExt value for CertPlist for the R_PKIServ callable service
Customizing with installation exit routines
Exit routine processing for automatic certificate renewal
Steps for updating the exit routine code sample
Using the exit routine for pre- and post-processing
Automatic renewal - preprocessing
Automatic renewal - post-processing
Scenario for using the exit routine
Exit routine processing for the PKI Services CGIs
Steps for updating the exit routine code sample
Using the exit routine for pre- and post-processing
Return codes
GENCERT and GENRENEW - preprocessing
GENCERT and GENRENEW - post-processing
REQCERT and REQRENEW - preprocessing
REQCERT and REQRENEW - post-processing
EXPORT - preprocessing
EXPORT - post-processing
REVOKE - preprocessing
REVOKE - post-processing
QRECOVER - preprocessing
QRECOVER - post-processing
Scenarios for using the exit routine
Scenario 1: Allow selected users to request certificates
Scenario 2: Maintain a customized certificate repository
Scenario 3: Mandate a policy for certificate renewal
Scenario 4: Allow users to recover a PKI generated key certificate when the passphrase is lost
Exit routine processing for Java server pages (JSPs)
Class UserExit
preGenReqCert method
postGenReqCert method
preGenReqRenew method
postGenReqRenew method
preExport method
postExport method
preRevoke method
postRevoke method
preQRecover method
postQRecover method
Class ExportCert
Class QRecover
Class RevokeCert
Class UserExitException
Class CertPlist
Class PkiCertificate
Class QrecoverResultsList
Class RpkiservException
Using PKI Services
Using the end-user Web pages
Steps for accessing the end-user Web pages
Summary of fields
Steps for requesting a new certificate
Retrieving your certificate
Steps for retrieving a certificate from a bookmarked Web page
Steps for retrieving a certificate from the home page
Steps for retrieving a PKI generated key certificate
Steps for renewing a certificate
Steps for revoking or suspending a certificate
Recovering a certificate whose keys were generated by PKI Services
Steps for recovering a certificate whose keys were generated by PKI Services
Steps for preregistering an SCEP client
Using the administration Web pages
Steps for accessing the administration home page
Fields in the administration Web pages
Processing certificate requests
Status of certificate requests
Actions on certificate requests
Using the PKI Services administration home page
Steps for processing a single request
Steps for processing requests by performing searches
Processing certificates
Status of certificates
Actions for certificates
Steps for processing a single certificate
Steps for processing certificates by performing searches
Relationship between certificate requests and certificates
Using PKI Services utilities
Using the createcrls utility
Using the iclview utility
Using the pkiprereg utility
Using the postcerts utility
Using the TemplateTool utility
Using the vosview utility
Sample record 1
Sample record 2
Sample record 3
Sample certificate request record
Using the vsam2db2 utility
Using the certificate management protocol (CMP) with PKI Services
Support for CMP messages
Support for the CMP certificate request message (type cr)
Support for the CMP PKCS #10 certificate request message (type p10cr)
Support for the CMP certificate response message (type cp)
Support for the CMP revocation request message (type rr)
Support for the CMP revocation response message (type rp)
Support for the CMP error message (type error)
Determining the CA domain to which a request is routed
How PKI Services interprets distinguished names (DNs) on CMP requests
Setting up a client to make CMP requests to PKI Services
Steps for setting up a certificate for a CMP requester
Setting up PKI Services to process CMP requests
Enabling the CMP support
Setting up PKI Services to create private keys for CMP clients
Determining the source of certificates used to encrypt the returned private key
Steps for setting up PKI Services to encrypt returned private keys with certificates in a key ring
Setting up the HTTP Server for CMP
Tracing the PKI CMP CGI program
Messages and codes returned from the CMP functions
Administering security for PKI Services
RACF administration for PKI Services
Authorizing users for the PKI Services administration group
Connecting members to the group
Deleting members from groups
Authorizing users for inquiry access
Steps for authorizing users for inquiry access
Administering HostIdMappings extensions
Steps for administering HostIdMappings extensions
Locating your PKI Services certificates and key ring
Steps for locating the PKI Services certificates and key ring
Establishing PKI Services as an intermediate CA
Steps for changing PKI Services from a self-signed CA to an intermediate CA
Renewing your PKI Services CA and RA certificates
Steps for renewing your PKI Services CA certificate
Steps for renewing your PKI Services RA certificate
Recovering a CA certificate profile
Steps for recovering a CA certificate profile
Retiring and replacing the PKI Services CA private key
Steps to retire and replace the PKI Services CA private key for the PKI templates
Steps to retire and replace the PKI Services CA private key for the SAF templates: Scenario 1
Steps to retire and replace the PKI Services CA private key for the SAF templates: Scenario 2
R_PKIServ (IRRSPX00) callable service
Authorizing end-user functions
Authorizing administrative functions
Using encrypted passwords for LDAP servers
Steps for using encrypted passwords
Using the certificate validation service
PKI Services Trust Policy (PKITP)
Overview of PKITP
Certificate policies
Checking certificate status with PKITP
Certificate extensions
CRL extensions and CRL entry extensions
Files for PKITP
Configuring and getting started with PKITP
Steps for configuring PKITP
Trust Policy API
CSSM_TP_PassThrough
Building the sample application to invoke the certificate validation service
Steps for building the sample application
Code sample of the PKITP program (pkitpsamp.c)
Troubleshooting
Using information from SYS1.LOGREC
Sample LOGREC data
Using information from the PKI Services logs
Viewing SYSOUT information
_PKISERV_MSG_LEVEL subcomponents and message levels
Changing logging options
Displaying log options settings
Reference information
Messages
IKYC001I
File directory structure
Product libraries
File system directory and subdirectories
The pkiserv.conf configuration file
Environment variables
Environment variables in the environment variables file
The pkiserv.envars environment variables file
The IKYSETUP REXX exec
Actions IKYSETUP performs by issuing RACF commands
Setting up the PKI Services daemon user ID
Setting up access control to protect PKI Services
Protecting end-user functions
Protecting administrative functions
Establishing your CA and RA certificates
Steps for establishing your CA and RA certificates
Configuring the IBM HTTP Server for SSL mode
Using RACF to obtain a certificate for the Web server
Enabling the IBM HTTP Server for surrogate operation
Allowing PKI Services to generate key pairs for certificate requests
IKYSETUP sample
Other code samples
IBM HTTP Server V5.3 configuration directives
IBM HTTP Server V7.0 configuration directives
IKYCDB2
IKYCVSAM
IKYRVSAM
IKYSBIND
IKYSGRNT
IKYVBKUP
IKYVREST
PKISERVD sample procedure to start PKI Services daemon
SMF recording
PKI Services event code
Relocate section variable data
LDAP directory server requirements
Using a gskkyman key database
Steps for using a gskkyman key database
Configuring PKI Services as an IdenTrust certificate authority
Who should use this information
Related information from IdenTrust
Overview of configuring z/OS PKI Services as a CA
System prerequisites
Task overview
Establish PKI Services as an intermediate CA under the IdenTrust root
Adjust your PKI Services general settings
CRL processing time
Distribution point CRLs
Define PKI Services certificate templates for IdenTrust certificate types
Configuring z/OS PKI Services as a CA
Steps to modify pkiserv.conf for different certificate types
Steps to modify pkiserv.conf general settings
Steps to create IdenTrust specific certificate templates
Code samples
Sample PKI Services configuration file directives for IdenTrust compliance
Sample browser certificate template for IdenTrust compliance
Sample server certificate template for IdenTrust compliance
Using the PKI Services Web application with Internet Explorer on Windows systems
User tasks for setting up a Windows system and Internet Explorer to work with the PKI Services Web application
Installing CAPICOM on a Microsoft Windows system
Steps for installing CAPICOM on a Microsoft Windows system
Installing the PKI Services ActiveX program
Steps for installing the PKI Services ActiveX program from the PKI Services home page
Steps for installing the PKI Services ActiveX program when you renew a certificate
Configuring Internet Explorer to trust PKI Services on a Windows system
Steps for configuring Internet Explorer to trust PKI Services
Installing the PKI Services CA certificate on a Microsoft Windows system
Steps for installing the PKI Services CA certificate on a Microsoft Windows system
Administrator tasks for setting up a Windows system and Internet Explorer to work with the PKI Services Web application
Signing the PKI Services ActiveX programs
Steps for signing the PKI Services ActiveX programs
Steps for building the installer programs using Microsoft Visual Studio