System Z Cryptographic Services and Z/OS PKI Services

Front cover

System z Cryptographic Services and z/OS PKI Services

Hardware cryptography monitoring

PKCS#11 support on z/OS

Java cryptography

Guillaume Hoareau Nikhil V Kapre MuHyun Kim Gerard Laumay Patrick Kappeler Jonathan Barney Joel Porterie Jean Marc Darees Vicente Ranieri, Jr. Pekka Hanninen Dominique Richard Robert Herman Daniel L. Turkenkopf

ibm.com/redbooks

International Technical Support Organization

System z Cryptographic Services and z/OS PKI Services May 2008

SG24-7470-00

Note: Before using this information and the product it supports, read the information in “Notices” on page vii.

First Edition (May 2008)

This edition applies to Version 1, Release 9 of z/OS (product number 5694-A01).

© Copyright International Business Machines Corporation 2008. 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 book ...... ix Become a published author ...... xi Comments welcome...... xi

Part 1. Using cryptography with advanced technologies ...... 1

Chapter 1. System z cryptography infrastructure ...... 3 1.1 Message-security assist ...... 4 1.2 Cryptographic hardware ...... 9 1.2.1 CP Assist for Cryptographic Functions (CPACF) ...... 10 1.2.2 Cryptographic Coprocessor Feature (CCF) ...... 12 1.2.3 PCI Cryptographic Accelerator (PCICA) ...... 13 1.2.4 PCI-X Cryptographic Coprocessor (PCIXCC)...... 14 1.2.5 Crypto Express 2 Feature ...... 17 1.2.6 Comparison of CPACF, CEX2C, and CEX2A...... 19 1.3 IBM Common Cryptographic Architecture...... 20 1.3.1 Rationale for the IBM CCA ...... 20 1.3.2 CCA callable services ...... 21 1.3.3 DES key management ...... 24 1.3.4 PKA key management ...... 30 1.4 ICSF ...... 34 1.4.1 Audit trails ...... 38 1.5 Logical partitioning and System z hardware cryptography exploitation...... 38 1.6 Monitoring the cryptographic workload on z/OS ...... 39 1.7 Sysplex and System z hardware cryptography ...... 40 1.8 Software requirements ...... 40

Chapter 2. Hardware cryptography activity assessment on System z ...... 41 2.1 What is exploiting the System z hardware cryptography?...... 42 2.1.1 Hardware cryptography exploitation on z/OS ...... 42 2.1.2 Hardware cryptography exploitation in Linux on System z ...... 46 2.2 Assessing the use of hardware cryptography on z/OS ...... 47 2.2.1 Detecting the use of RACF-protected cryptographic resources ...... 47 2.2.2 z/OS System SSL example...... 49 2.2.3 The ICSF component trace...... 56 2.3 Assessing the use of hardware cryptography on z/VSE ...... 58 2.4 Assessing the use of hardware cryptography on Linux on System z ...... 58 2.4.1 Status of the z90crypt device driver ...... 59 2.4.2 Collecting information about hardware cryptography activity ...... 60 2.4.3 Programs that invoke hardware cryptography ...... 61 2.5 Setting up hardware cryptography configuration of z/VM ...... 61 2.5.1 Checking the hardware cryptography configuration with z/VM ...... 63

© Copyright IBM Corp. 2008. All rights reserved. iii Chapter 3. Measuring hardware cryptography activity on z/OS with RMF ...... 65 3.1 Overview of ICSF cryptographic workload balancing ...... 66 3.2 SMF reporting of hardware cryptography activity ...... 66 3.3 Using RMF to measure the z/OS hardware cryptography activity...... 68 3.3.1 RMF data collection infrastructure for hardware cryptography ...... 69 3.4 RMF post-processor reports ...... 70 3.4.1 Crypto Hardware Activity RMF report ...... 71 3.4.2 Crypto Hardware Activity report example ...... 74 3.4.3 Crypto Hardware Activity report without local activity ...... 75 3.4.4 Workload Activity report ...... 75 3.4.5 Overview report...... 77

Chapter 4. Assessing activity with OMEGAMON XE on z/OS and RMF...... 79 4.1 Tivoli OMEGAMON XE on z/OS - Cryptographic coprocessor support ...... 80 4.2 OMEGAMON XE on z/OS graphical interface ...... 81 4.3 Measuring activity with RMF and OMEGAMON XE on z/OS ...... 82 4.3.1 SHA-1 activity (CPACF activity) ...... 82 4.3.2 CEX2C activity ...... 85 4.3.3 CEX2A activity ...... 86 4.4 Using the OMEGAMON XE on z/OS Service Call Performance workspace...... 88

Chapter 5. Java cryptography ...... 91 5.1 Java cryptography...... 92 5.1.1 Cryptography overview ...... 92 5.1.2 Types of encryption algorithms ...... 95 5.1.3 Key-management challenge ...... 98 5.1.4 Java cryptography in z/OS ...... 99 5.2 Cryptography providers on z/OS...... 102 5.2.1 How to select a provider (registering a provider in the java.security file) ...... 103 5.2.2 JCE - Java Cryptography Extension ...... 103 5.2.3 JCECCA - JCE using CCA hardware cryptographic devices on z/OS ...... 104 5.2.4 CertPath - Certificate generation and path validation ...... 104 5.2.5 JSSE - Java Secure Sockets Extension (SSL and TLS)...... 105 5.2.6 Map the providers and algorithms...... 105 5.3 Setting up hardware cryptographic features ...... 106 5.3.1 Policy files ...... 107 5.4 Keystore and SAF digital certificates (keyrings) ...... 107 5.4.1 JCEKS ...... 108 5.4.2 JCECCAKS...... 110 5.4.3 JCERACFKS...... 114 5.4.4 JCECCARACFKS ...... 116 5.5 Tools ...... 120 5.5.1 Software keytool ...... 120 5.5.2 Hardware keytool ...... 120 5.5.3 Different characteristics of keystores ...... 120 5.6 Java examples ...... 121 5.6.1 RSA encryption and decryption ...... 121 5.6.2 RSA signature...... 124 5.6.3 Symmetric key encryption...... 127 5.6.4 Generating a true random number ...... 130 5.6.5 Hashing a message ...... 131 5.6.6 Exporting keys from software to hardware keystores ...... 132 5.6.7 Hybrid encryption ...... 134

iv System z Cryptographic Services and z/OS PKI Services 5.7 SOAP examples ...... 137 5.8 Configuring SLL for WebSphere Application Server hardware cryptography ...... 151

Chapter 6. z/OS PKCS#11...... 155 6.1 Public Key Cryptography Standard #11 (PKCS#11)...... 156

6.1.1 PKCS#11 concepts...... 156 6.1.2 Benefits of PKCS#11 on z/OS ...... 157 6.1.3 Mapping PKCS#11 concepts to z/OS cryptographic technology ...... 157 6.2 z/OS PKCS#11 infrastructure and setup...... 158 6.2.1 Tokens ...... 158 6.2.2 Token Key Data Set (TKDS)...... 159 6.2.3 Controlling access to tokens ...... 161 6.2.4 ICSF services provided by z/OS PKCS#11 ...... 162 6.3 z/OS PKCS#11 token administration ...... 163 6.3.1 ICSF panels, token browser ...... 163 6.3.2 RACF panels and RACDCERT commands ...... 171 6.3.3 gskkyman panels ...... 178 6.3.4 Examples ...... 185 6.4 z/OS PKCS#11 programming example...... 194

Part 2. Managing keys ...... 205

Chapter 7. z/OS PKI Services...... 207 7.1 Public Key Infrastructure ...... 208 7.1.1 Certificate life cycle ...... 208 7.1.2 z/OS PKI Services ...... 208 7.1.3 z/OS PKI Services structure ...... 209 7.1.4 Scalability and availability ...... 213 7.2 A product in constant evolution ...... 214 7.2.1 z/OS V1.4 enhancements ...... 214 7.2.2 z/OS V1.5 enhancements ...... 215 7.2.3 z/OS V1.7 enhancements ...... 219 7.2.4 z/OS V1.8 enhancements ...... 222 7.2.5 z/OS V1.9 enhancements ...... 225 7.3 z/OS R9 PKI Services deployment ...... 225 7.3.1 IBM HTTP servers...... 225 7.3.2 IKYSETUP REXX ...... 240 7.3.3 UNIX environment configuration ...... 247 7.3.4 OCSF and OCEP ...... 252 7.3.5 LDAP directory ...... 253 7.3.6 VSAM ObjectStore and ICL data sets...... 253 7.3.7 Starting and stopping PKI Services ...... 255 7.4 Accessing our z/OS PKI Services Home page ...... 255

Chapter 8. Sample scenario ...... 257 8.1 Overall architecture ...... 258 8.1.1 Structure of sample scenario ...... 258 8.2 ITSO implementation ...... 260 8.2.1 Java implementation ...... 261 8.2.2 PKI Services core ...... 265 8.2.3 C code implementation ...... 267

Contents v Appendix A. Additional material ...... 273 Locating the Web material ...... 273 Using the Web material ...... 273 Related publications ...... 275

Publications ...... 275 How to get Redbooks...... 275 Help from IBM ...... 275

Index ...... 277

vi System z Cryptographic Services and z/OS PKI Services Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785 U.S.A.

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.

This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs.

IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. These and other IBM trademarked terms are marked on their first occurrence in this information with the appropriate symbol (® or ™), indicating US registered or common law trademarks owned by IBM at the time this information was published. Such trademarks may also be registered or common law trademarks in other countries. A current list of IBM trademarks is available on the Web at http://www.ibm.com/legal/copytrade.shtml

The following terms are trademarks of the International Business Machines Corporation in the United States, other countries, or both:

Redbooks (logo) ® OS/390® System/370™ AIX® Parallel Sysplex® Tivoli® CICS® PowerPC® VSE/ESA™ DB2® RACF® VTAM® developerWorks® Rational® WebSphere® Enterprise Systems Redbooks® z/Architecture® Architecture/370™ REXX™ z/OS® eServer™ RMF™ z/VM® FICON® S/390® z/VSE™ IBM® System z™ z9™ MVS™ System z9® zSeries® OMEGAMON® System/360™

The following terms are trademarks of other companies:

EJB, Enterprise JavaBeans, J2EE, J2SE, Java, JavaBeans, JDK, JNI, JVM, and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Windows, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.

Intel, Intel logo, Intel Inside logo, and Intel Centrino logo are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Linux is a trademark of Linus Torvalds in the United States, other countries, or both.

Other company, product, or service names may be trademarks or service marks of others.

viii System z Cryptographic Services and z/OS PKI Services Preface

This IBM® Redbook describes System z cryptographic services and technologies. This document also discusses the cryptographic support available for Java™ and J2EE™ applications and the new support introduced in z/OS® V1.9 for PKCS#11. We briefly describe the new PKI Services enhancement introduced with z/OS V1.9. Finally we provide a sample scenario of how an installation can use this technology, and we explain how to download the sample.

The team that wrote this book

This book was produced by a team of specialists from around the world working at the International Technical Support Organization, Poughkeepsie Center.

Patrick Kappeler has held during his 36-year career in IBM many international positions, all dealing with mainframe hardware and software technical support and education. He is now a lead consulting IT Specialist in the Montpellier European Product and Solutions Support Center (PSSC) and has specialized for the past 10 years on e-business security. He extensively presents, writes, and provides advanced technical support and consulting on this topic worldwide. He is also the co-author and leader of many other ITSO projects on z/OS security and e-business.

Jonathan Barney is an Enterprise Security Architect in the United States. He has six years of experience in z/OS, Java, and UNIX® System Services. He holds a Bachelor of Science degree in Computer Science from Clarkson University. His areas of expertise include Java, RACF® Java security, tape encryption, host encryption facility, the WebSphere® family of products, and the PKI and PGP systems.

Jean Marc Darees joined IBM in 1984 as a MVS™ system engineer. Since this time he has held several specialist and architect positions dealing with mainframes and other technologies that support customer and internal projects. He joined the PSSC in Montpellier in 1997, where he now provides consulting and pre-sales technical support in the area of large IT infrastructures.

Pekka Hanninen is an IT specialist working with the Integrated Technology Services team in Finland. He has over 35 years of experience in IBM large systems software. He has worked at IBM for 11 years, and his areas of expertise include cryptography, RACF, and security administration. He holds certificates for CISSP, CISA, and CISM.

Robert Herman was a Senior IT Specialist, Systems Management Integrator with IBM Global Services in Endicott, New York until his death in 2007. He had 27 years of experience supporting CICS® and related products for a variety of IBM internal and external customer accounts. Bob worked on several IBM Redbooks®, including Enterprise JavaBeans for z/OS and OS/390 CICS Transaction Server.

Guillaume Hoareau is an IT Specialist at the New Technology Center of the PSSC in Montpellier, France. He is responsible for ISV sizing support on the z platform, part of the mission of the Virtual International Competency Center at Montpellier. He has worked on several z/VM® and Linux® for System z projects.

© Copyright IBM Corp. 2008. All rights reserved. ix Nikhil V Kapre is an Application Architect in IBM India. He has over 9 years experience and has been deeply involved in designing solutions for customers around the world. He holds a degree in Industrial Engineering from the Delhi College of Engineering in New Delhi, India. His areas of expertise include Java, J2EE, WebSphere Application Server, WebSphere MQ, ORM (Toplink/Hibernate), and several open source distributions. He spends a significant part

of his time in mentoring and training programmers in Java and J2EE and in writing articles.

MuHyun Kim is an Advisory IT Specialist in IBM Korea. He supports field engineers on AIX®, Java, and security issues. Before joining IBM, he worked as a security consultant performing IT audit, penetration test and incident investigation, and developing security policies for four years. He has completed courses at Korea University’s Graduate School of Information Security, majoring in cryptography protocols. He holds certificates for CISA, ITILF, and SCJP.

Gerard Laumay is a System z IBM certified IT Specialist at PSSC in Montpellier, France. He has more than 21 years of experience in the large systems field, as a consultant with IBM customers. His areas of expertise include IBM System z9® hardware, z/OS, z/VM, Linux operating systems, and new workloads on System z. As a member of the zChampion worldwide technical team, he teaches at numerous IBM external and internal conferences. He is a frequent participant in international projects and has written several IBM Redbooks.

Joel Porterie is a Senior IT Specialist who has been with IBM France for 30 years. He works for Network and Channel Connectivity Services in the EMEA Product Support Group. His areas of expertise include z/OS, TCP/IP, VTAM®, OSA-Express, and Parallel Sysplex®. He has taught OSA-Express and FICON® problem determination classes and provided on-site assistance in these areas in numerous countries. He also co-authored the IBM Redbooks Using the IBM S/390 Application StarterPak; OSA-Express Gigabit Ethernet Implementation Guide; OSA-Express Implementation Guide; Introduction to the New Mainframe: Networking; and Communications Server for z/OS V1R7 TCP/IP Implementation, Volume 4 Policy-Based Network Security.

Vicente Ranieri, Jr. is an Executive IT Specialist at the Advanced Technical Support (ATS) team reporting to the Washington Systems Center. He has 28 years of experience working with IBM customers, 23 of which providing technical support for the System z™ platform. He is the System z Security Regional Designated Specialist for Americas South Region, leading several security projects across the region. He writes extensively and has co-authored several Redbooks. He also teaches IBM classes worldwide on all areas of System z security. He has been teaching System z Security Update ITSO workshops since 2001.

Dominique Richard is an IT Specialist at IBM France. He joined IBM in 1982 and was a System Engineer supporting MVS customers in France. Since 2005 he has been part of the European Products and Solutions Support Center, located in Montpellier, where he is involved in testing and establishing benchmarks. He has specialized in the area of host system security.

Daniel L. Turkenkopf is a Solutions Architect in the IBM Design Center for IT Optimization and Business Flexibility located in Poughkeepsie, New York. He leads collaborative design sessions with clients to effectively leverage IBM technology in their infrastructures. His areas of expertise include service-oriented architectures and systems management. Prior to this role, Dan was a J2EE Application Architect with IBM Global Business Services Public Sector where he was responsible for the user interface tier of a multi-billion dollar modernization effort for a federal agency. His Product experience includes WebSphere Application Server, WebSphere Portal Server, and Tivoli® Provisioning Manager. He holds a BA in Mathematics and a BS in Economics with a concentration in Management and Information Systems from the University of Pennsylvania.

x System z Cryptographic Services and z/OS PKI Services Thanks to the following people for their contributions to this project: Paola Bari Richard Conway Robert Haimowitz International Technical Support Organization, Poughkeepsie Center

Wai Choi John Dayka Frank DeGilio Anne Emerick Terry Green Jim Sweeny IBM Poughkeepsie

Alyson Comer IBM Endicott

Special thanks to Dario Facchinetti, IBM Italy, for his support in writing the sample C code used in the PKI sample scenario.

Become a published author

Join us for a two- to six-week residency program! Help write a book dealing with specific products or solutions, while getting hands-on experience with leading-edge technologies. You will have the opportunity to team with IBM technical professionals, Business Partners, and Clients.

Your efforts will help increase product acceptance and customer satisfaction. As a bonus, you will develop a network of contacts in IBM development labs, and increase your productivity and marketability.

Find out more about the residency program, browse the residency index, and apply online at: ibm.com/redbooks/residencies.html

Comments welcome

Your comments are important to us!

We want our books to be as helpful as possible. Send us your comments about this book or other IBM Redbooks in one of the following ways: Use the online Contact us review Redbooks form found at: ibm.com/redbooks Send your comments in an e-mail to: [email protected] Mail your comments to: IBM Corporation, International Technical Support Organization Dept. HYTD Mail Station P099 2455 South Road Poughkeepsie, NY 12601-5400

Preface xi

xii System z Cryptographic Services and z/OS PKI Services

Part 1

Part 1 Using cryptography with advanced technologies

This part covers the following aspects of cryptography: Java middleware - J2EE, WebSphere Application Server, Web services PKCS#11 Cryptography performance and monitoring

2 System z Cryptographic Services and z/OS PKI Services

Chapter 1. System z cryptography infrastructure

The System z platform offers standard and optional hardware cryptographic devices. These devices are available with the proper software components in the different operating systems to provide applications with APIs to invoke the system’s hardware cryptography and to provide key repository management facilities. In this chapter, we focus on the support z/OS provides for applications using hardware cryptography.

This chapter contains a description of the cryptographic elements of System z and how they can be invoked.

The architecture of a system defines its attributes as seen by the programmer - that is, the conceptual structure and functional behavior of the machine, as distinct from the organization of the data flow, the logical design, the physical design, and the performance of any particular implementation. Several dissimilar machine implementations may conform to a single architecture.

z/Architecture® is the next step in the evolution from the System/360™ to the System/370™, System/370 extended architecture (370-XA), Enterprise Systems Architecture/370™ (ESA/370), and Enterprise Systems Architecture/390 (ESA/390). z/Architecture includes most of the facilities of ESA/390 and also provides significant extensions, among which are: 64-bit general registers and control registers. A 64-bit addressing mode, in addition to the 24-bit and 31-bit addressing modes of ESA/390. Both operand addresses and instruction addresses can be 64-bit addresses. The program status word (PSW) is expanded to 16 bytes to contain the larger instruction address. The PSW also contains a newly assigned bit that specifies the 64-bit addressing mode.

IBM announced the z/Architecture in October, 2000. In June, 2003 IBM announced an extension to the z/Architecture called message security assist (MSA). MSA provides the following instructions: CIPHER MESSAGE (KM) CIPHER MESSAGE WITH CHAINING (KMC) COMPUTE INTERMEDIATE MESSAGE DIGEST (KIMD) COMPUTE LAST MESSAGE DIGEST (KLMD) COMPUTE MESSAGE AUTHENTICATION CODE (KMAC)

Each instruction can perform several functions. The MSA basic facility supplies a query function with each instruction so that the programmer can determine whether a given function is available on a given processor. If a programmer attempts to use a function that is not available, the program receives a program interruption with interruption code 6 (specification exception). In z/OS this code is normally presented as an 0C6 abend.

The MSA basic facility also provides two functions for generating a message digest based on the SHA-1 algorithm. One of these functions is provided with the KIMD instruction, and the other is provided with the KLMD instruction.

The MSA data encryption algorithm (DEA) facility provides the following: Six additional functions for encrypting messages, with or without chaining. Three of these functions are provided with the KM instruction and three with the KMC instruction. Three additional functions for generating a message authentication code (MAC). These functions are provided with the KMAC instruction.

In September, 2005 IBM announced MSA Extension 1. MSA Extension 1 provides five additional functions as follows: Two functions for generating a message digest based on the SHA-256 algorithm. One of these functions is provided with the KIMD instruction, and the other is provided with the KLMD instruction.

4 System z Cryptographic Services and z/OS PKI Services Two functions for encrypting messages using the AES-128 algorithm. One of these functions is provided with the KM instruction and the other with the KMC instruction. One function for generating a pseudorandom number.

Each of these instructions has the RRE format shown in Figure 1-1, where R1 and R2 represent general registers. Bits 16-23 of the instruction are ignored.

op code R1 R2

0 16 24 28 31 Figure 1-1 RRE format of the KM, KMC, KIMD, KLMD, and KMAC instructions

These instructions use registers as follows: General register 0 (GR0) Bits 57-63 of GR0 specify the function code of the function that the instruction is to perform. For the KM and KMC instructions, bit 56 of GR0 specifies whether an encryption or decryption operation is to be performed. For the other instructions, bit 56 should be set to 0. General register 1 (GR1) GR1 contains the address of the leftmost byte of the parameter block.

R1 For the KM and KMC instructions, R1 contains the address of the leftmost byte of the data after it has been encrypted or decrypted. For the KIMD, KLMD, and KMAC instructions, the R1 field is ignored.

R2 R2 contains the address of the leftmost byte of the second operand: – The data to be encrypted or decrypted (KM and KMC) – The data upon which a message digest is to be computed (KIMD and KLMD) – The data upon which a MAC is to be computed (KMAC)

R2 + 1 This register contains the length of the second operand.

The contents of R1, R2, and R2 + 1 are ignored for the query function. Table 1-1 shows the functions of the KM instruction.

Table 1-1 Functions of the MSA CIPHER MESSAGE (KM) instruction Function Function Function description Part of Parameter Data code name block for the block function size

0 KM-Query Determine which other functions are available. Basic Status word (16 N/A bytes)

1 KM-DEA Encipher or decipher the 8-byte blocks in DEA Key (8 bytes) 8 operand 2 using the DEA algorithm with the 64-bit key in the parameter block. The operation is performed without chaining.

Chapter 1. System z cryptography infrastructure 5 Function Function Function description Part of Parameter Data code name block for the block function size 2 KM-TDEA-128 Encipher or decipher the 8 byte blocks in DEA Key 1 (8) 8 operand 2 using the TDEA algorithm with the two Key 2 (8) keys in the parameter block (key 3 = key 1). The operation is performed without chaining.

3 KM-TDEA-192 Encipher or decipher the 8 byte blocks in DEA Key 1 (8) 8 operand 2 using the TDEA algorithm with the Key 2 (8) three keys in the parameter block. The operation Key 3 (8) is performed without chaining.

18 KM-AES-128 Encipher or decipher the 16-byte blocks in Ext 1 Key (16) 16 operand 2 using the AES algorithm with the 128-bit key in the parameter block. The operation is performed without chaining.

The “Part of” column in Table 1-1 on page 5 indicates whether the function is included with: The MSA basic facility (Basic) The MSA DEA facility (DEA) MSA extension 1(Ext 1)

Table 1-2 describes the functions of the KMC instruction.

Table 1-2 Functions of the MSA CIPHER MESSAGE WITH CHAINING (KMC) instruction Function Function Function description Part of Parameter Data code name block for the block function size

0 KMC-Query Determine which other functions are available. Basic Status word N/A (16 bytes)

1 KMC-DEA Encipher or decipher the 8-byte blocks in DEA Chaining value 8 operand 2 using the DEA algorithm with the (8) 64-bit key and the 64-bit chaining value in the Key (8) parameter block. The operation is performed with chaining.

2 KMC-TDEA- Encipher or decipher the 8-byte blocks in DEA Chaining value 8 128 operand 2 using the TDEA algorithm with the two (8) keys and the 64-bit chaining value in the Key 1 (8) parameter block (key 3 = key 1). The operation is Key 2 (8) performed with chaining.

3 KMC-TDEA- Encipher or decipher the 8-byte blocks in DEA Chaining value 8 192 operand 2 using the TDEA algorithm with the (8) three keys and the 64-bit chaining value in the Key 1 (8) parameter block. The operation is performed Key 2 (8) with chaining. Key 3 (8)

18 KMC-AES-128 Encipher or decipher the 16-byte blocks in Ext 1 Chaining value 16 operand 2 using the AES algorithm with the (16) 128-bit key and the 128-bit chaining value in the Key (16) parameter block. The operation is performed with chaining.

6 System z Cryptographic Services and z/OS PKI Services Function Function Function description Part of Parameter Data code name block for the block function size 67 KMC-PRNG Pseudorandom number generator. The Ext 1 Chaining value 8 algorithm is based on TDES using three 64-bit (8) cryptographic keys and a 64-bit chaining value. Key 1 (8) Key 2 (8) Key 3 (8)

Table 1-3 describes the functions of the KIMD instruction. The length in bytes of operand 2 must be a multiple of 64.

Table 1-3 Functions of COMPUTE INTERMEDIATE MESSAGE DIGEST instruction Function Function Function description Part of Parameter block Data code name for the function block size

0 KIMD-Query Determine which other functions are available. Basic Status word N/A (16 bytes)

1 KIMD-SHA-1 A 20-byte intermediate message digest is Basic Initial hash value: 64 generated for the 64-byte (512-bit) message H0=x’67452301’ blocks in operand 2 using the SHA-1 algorithm H1=x’EFCDAB89 with the 20-byte (160-bit) initial hash value in the H2=x’98BADCFE parameter block. The generated intermediate H3=x’10325476’ message digest is stored in the parameter block. H4=’C3D2E1F0’

2KIMD-A 32-byte intermediate message digest is Ext 1 Initial hash value: 64 SHA-256 generated for the 64-byte (512-bit) message H0=x’6A09E667’ blocks in operand 2 using the SHA-256 H1=x’BB67AE85’ algorithm with the 32-byte (256-bit) initial hash H2=x’3C6EF372’ value in the parameter block. The generated H3=x’A54FF53A’ intermediate message digest is stored in the H4=x’510E527F’ parameter block. H5=x’9B05688C’ H6=x’1F83D9AB’ H7=x’5BE0CD19’

Table 1-4 describes the functions of the KLMD instruction. The length in bytes of operand 2 need not be a multiple of 64.

Table 1-4 Functions of MSA COMPUTE LAST MESSAGE DIGEST (KLMD) instruction Function Function Function description Part of Parameter block Data code name for the function block size

0 KLMD-Query Determine which other functions are available. Basic Status word (16 N/A bytes)

Chapter 1. System z cryptography infrastructure 7 Function Function Function description Part of Parameter block Data code name for the function block size 1 KLMD-SHA-1 If the length in bytes of the message in operand Basic Initial hash value: 64 2 is greater than or equal to 64, an intermediate H0=x’67452301’ message digest is generated for each 64-byte H1=x’EFCDAB89 (512-bit) message block using the SHA-1 H2=x’98BADCFE algorithm with the 20-byte (160-bit) initial hash H3=x’10325476’ value in the parameter block. The generated H4=’C3D2E1F0’ intermediate message digest is stored in the Length of total initial hash value field of the parameter block. message in bits This repeats until the remaining message is < 64 bytes long. Then a padding operation is performed that includes the remaining portion of the second operand.

2KLMD-The description of KLMD-SHA-256 is the same Ext 1 Initial hash value: 64 SHA-256 as the description of KLMD-SHA-1 if you replace H0=x’6A09E667’ SHA-1 with SHA-256 and 20 with 32. H1=x’BB67AE85’ H2=x’3C6EF372’ H3=x’A54FF53A’ H4=x’510E527F’ H5=x’9B05688C’ H6=x’1F83D9AB’ H7=x’5BE0CD19’ Length of total message in bits

Table 1-5 describes the functions of the KMAC instruction. The length in bytes of the second operand must be a multiple of 8.

Table 1-5 Functions of COMPUTE MESSAGE AUTHENTICATION CODE instruction Function Function Function description Part of Parameter block Data code name for the function block size

0 KMAC-Query Determine which other functions are available. Basic Status word N/A (16 bytes)

1 KMAC-DEA The MAC code for the 8-byte message blocks DEA Chaining value(8) 8 (M1, M2 , . ,, Mn) in operand 2 is computed Key (8) using the DEA algorithm with the 64-bit cryptographic key and the 64-bit chaining value in the parameter block. The MAC, also called the output chaining value, is stored in the chaining value field of the parameter block.

2 KMAC-TDEA- The MAC code for the 8-byte message blocks in DEA Chaining value(8) 8 128 operand 2 is computed using the TDEA Key1 (8) algorithm with the two 64-bit cryptographic keys Key 2 (8) and the 64-bit chaining value in the parameter block. The MAC is stored in the chaining value field of the parameter block.

8 System z Cryptographic Services and z/OS PKI Services Function Function Function description Part of Parameter block Data code name for the function block size 3 KMAC-TDEA- The MAC code for the 8-byte message blocks in DEA Chaining value(8) 8 192 operand 2 is computed using the TDEA Key 1 (8) algorithm with the three 64-bit cryptographic Key 2 (8) keys and the 64-bit chaining value in the Key 3 (8) parameter block. The MAC is stored in the chaining value field of the parameter block.

1.2 Cryptographic hardware

For many years IBM has delivered products that implement in hardware (rather than software) some of the cryptographic algorithms. In recent years it has shipped the following cryptographic hardware products for mainframe servers: Central Processor Assist for Cryptographic Functions (CPACF) Cryptographic Coprocessor Feature (CCF) Peripheral Component Interconnect Cryptographic Coprocessor (PCICC) Peripheral Component Interconnect Cryptographic Accelerator (PCICA) Peripheral Component Interconnect - Extended Cryptographic Coprocessor (PCIXCC) Cryptographic Express 2 Coprocessor (CEX2C) Cryptographic Express 2 Accelerator (CEX2A)

Table 1-6 shows which of these cryptographic hardware products are available for each of several mainframe servers.

Table 1-6 Cryptographic hardware per server type

Server CPACF CCF PCICC PCICA PCIXCC CEX2C CEX2A (feature (feature (feature (feature (feature (feature 0800) 0861) 0862) 0868) 0863) 0863)

9672 G5,G6 No Yes Yes No No No No

z800, z900 No Yes Yes Ye s No No No (requires (requires CCF) CCF)

z890, z990 Yes No No Yes Ye s Ye s No (requires (requires (requires (requires z/OS 1.4 or feature feature feature later) 3863) 3863 and 3863 and ICSF FMID z/OS 1.4 or HCR770A later with or later) ICSF FMID HCR7720 or later)

Chapter 1. System z cryptography infrastructure 9 Server CPACF CCF PCICC PCICA PCIXCC CEX2C CEX2A (feature (feature (feature (feature (feature (feature 0800) 0861) 0862) 0868) 0863) 0863) z9 109 Ye s No No No No Yes Ye s z9 BC (requires (requires (requires z9 EC z/OS 1.6 or feature feature later) 3863 and 3863 and z/OS 1.6 or z/OS 1.6 or later with later with ICSF FMID ICSF FMID HCR7730 HCR7730 or later) or later)

For those readers who are not familiar with recent server hardware announcements from IBM, we note here that on April 27, 2006, IBM announced the System z9 Business Class, also known as the z9 BC, as the successor to the zSeries® 890 mainframe. The z9 BC is available in two hardware model configurations: 2096-R07 and 2096-S07. At the same time it renamed the System z9 109 server to the System z9 Enterprise Class server, also known as the z9 EC. The z9 EC is the successor to the zSeries 990 and is available in the following configurations: 2094-S08, 2094-S18, 2094-S28, 2094-S38, and 2094-S54.

In the sections that follow, we discuss these cryptographic hardware products.

1.2.1 CP Assist for Cryptographic Functions (CPACF)

The CPACF provides the MSA instruction set on every central processor (CP) of a z890, z990, z9 109, z9 BC, and z9 EC server as shown in Figure 1-2.

CEC Cage Memory STI PCIXCC MBA PCICA CP CP CP ... CEX2

CPACF CPACF CPACF ... I/O Cage

Figure 1-2 A CPACF is associated with every CP

On the z890 and z990 the MSA instruction set always includes the following functions: KIMD-SHA-1 KLMD-SHA-1

With the DES/TDES Enablement Feature, feature 3863, it also includes the following functions: KM-DEA, KM-TDEA-128, and KM-TDEA-192 KMC-DEA, KMC-TDEA-128, and KMC-TDEA-192 KMAC-DEA, KMAC-TDEA-128, and KMAC-TDEA-192

10 System z Cryptographic Services and z/OS PKI Services On the z9 109, z9 BC, and z9 EC the MSA instruction set always includes the following functions: KIMD-SHA-1 and KIMD-SHA-256 KLMD-SHA-256 and KLMD-SHA-256

With feature 3863, it also includes the following functions: KM-DEA, KM-TDEA-128, KM-TDEA-192, and KM-AES-128 KMC-DEA, KMC-TDEA-128, KMC-TDEA-192, KMC-AES-128, and KMC-PRNG KMAC-DEA, KMAC-TDEA-128, and KMAC-TDEA-192

When the CPACF performs an encryption or decryption using one of the KM or KMC functions, general register 1 points to the parameter block. The parameter block contains the secret key or keys for the encryption or decryption. That is, the instruction points at a field in memory where the secret key or keys reside in an unencrypted form. This provides a security exposure.

Important: The CPACF operates with clear keys only. A clear key is a key that has not been encrypted under another key and has no additional protection within the cryptographic environment.

If the level of the Integrated Cryptographic Service Facility (ICSF) that you are using is HCR7720 or higher, you can decrease this security exposure by invoking the encryption and decryption functions through ICSF callable services rather than the KM and KMC instructions directly. (Yes, we are getting a little bit ahead of ourselves here; we discuss ICSF in 1.4, “ICSF” on page 34.) Proceed as follows: 1. Use the ICSF Key Generate Utility Program (KGUP) to store the clear key in the ICSF Cryptographic Key Data Set (CKDS). 2. Invoke the ICSF CSNBSYE callable service to perform encryption or the ICSF CSNBSYD callable service to perform decryption, specifying the label of the key token in the CKDS.

ICSF will fetch the clear key value from the CKDS and eventually forward it from the ICSF address space to the CPACF - that is, no application address space will be able to see the clear key value.

Because the CPACF cryptographic functions are implemented in each CP, the potential throughput scales with the number of CPs in the server.

The hardware of the CPACF that performs the secret key operations (DES, TDES, and AES) and SHA functions operates basically synchronous to the CP operations. The CP cannot perform any other instruction execution while a CPACF cryptographic operation is being executed. The CP internal code performs data fetches and stores resultant data while cryptographic operations are executed in the CPACF hardware on a unit basis as defined by the hardware.

Chapter 1. System z cryptography infrastructure 11 1.2.2 Cryptographic Coprocessor Feature (CCF)

The CCF is a single-chip cryptographic coprocessor imbedded as a standard, no-cost component in all IBM CMOS mainframe systems. Depending on its size, each CMOS mainframe has one or two CCFs. Each CCF contains both DES and public key algorithm (PKA) cryptographic processing units as shown in Figure 1-3.

Input Output Data Data Buffer Buffer

Asynchronous SHA-1 PIN DES PRNG 1024-bit modular exponentiation

Master key arrays (1 per LPAR)

Figure 1-3 Cryptographic Coprocessor Feature (CCF)

The possible configurations include DES with PKA These servers are configured for 64-bit DES keys, 1024-bit PKA keys used for distributing DES keys, and 1024- bit PKA keys used for digital signatures. TDES with PKA These servers are configured for TDES with 192-bit keys, 1024-bit PKA keys used for distributing DES keys, and 1024- bit PKA keys used for digital signatures.

The CCF provides a limited set of functions, but it is extremely fast for secret key cryptographic algorithms.

The CCF is certified for Federal Information Processing Standards Publication 140-1 (FIPS PUB 140-1) level 4.

12 System z Cryptographic Services and z/OS PKI Services Figure 1-4 shows a z/800 or z/900 server with two CCFs.

Memory STI PCICC MBA PCICA

CP0 CP1 CP2 CP3 ...

CCF0 CCF1 CEC Cage I/O Cage

Figure 1-4 z/800 or z/900 server with two Cryptographic Coprocessor Features (CCFs)

In Figure 1-4, CCF0 is tied to CP0, and CCF1 is tied to CP2. The work for CCF0 must flow to it through CP0; if CP0 is not available, the work for CCF0 flows to it through CP1. Likewise, the work for CCF1 must flow to it through CP2; if CP2 is not available, the work for CCF1 flows to it through CP3. Since the CCF is embedded in the mainframe, it is difficult to add new functions to it or to modify its functions. However, cryptographic applications are constantly evolving, and no single set of cryptographic functions can meet the needs of all customers over the life of a product. Each year, new application areas and new standards dictate cryptographic product features. In addition, many customers have requirements that are unique to their geography or to their application area. For example, many countries have local banking regulations that impose cryptographic requirements that are different from those of the rest of the world.

IBM learned that flexibility was an essential feature for its cryptographic coprocessors and that it must not design such products with a fixed set of functions. It must be easy to add new functions over time. Furthermore, for specific customers, IBM must have the ability to add special functions to the coprocessor - functions that would not be in the standard product function set.

1.2.3 PCI Cryptographic Accelerator (PCICA)

The PCICA is designed for maximum SSL acceleration rather than for specialized financial applications or for secure long-term storage of keys. As a result, it does not need the tamper detection circuitry that, as we shall see, is a feature of the PCIXCC.

In an IBM z/800 or z/900 server the PCICA does one thing and one thing only: It supports the ICSF CSNDPKD Public Key Decrypt callable service. SSL applications call this service to decrypt the SSL pre-master secret. In a z/900 server, the PCICA can support over 2000 SSL handshakes per second.

In an IBM z/890 or z/990 server, the PCICA provides three things and only three things, but it does them very fast: ICSF CSNDPKD Public Key Decrypt callable service

ICSF CSNDPKE Public Key Encrypt callable service (used by an SSL application to encrypt the pre-master secret) ICSF CSNDDSV Digital Signature Verify callable service

Chapter 1. System z cryptography infrastructure 13 1.2.4 PCI-X Cryptographic Coprocessor (PCIXCC)

With the PCIXCC, we have a single coprocessor card that can replace the CCF, PCICC, and the PCICA features in the zSeries systems. The overview we provide of the PCIXCC card hardware and software is based upon the article “The IBM PCIXCC: A new cryptographic coprocessor for the IBM eServer™,” which appeared in volume 48 of the IBM Journal of Research and Development for May/July 2004.

PCIXCC hardware overview The PCIXCC hardware is implemented as an adapter card for a PCI-X bus. Figure 1-5 shows the components that are on the card.

Secure Tamper- Battery- crypto Real-time detection backed module clock 4 circuitry 10 8 RAM

Random Flash AVR SDRAM number 6 security 9 EPROM 2 generator 3 microcontroller

PowerPC 405GPr Otello cryptographic Rigoletto FPGA microprocessor processor 1 7 5

Interconnect PCI-X base card Batteries PCI-X to PCI-X bridge dc/dc Power PCI-X bus edge connector

Figure 1-5 Components on the PCIXCC card

The numbers in Figure 1-5 correspond to the following list numbers: 1. IBM PowerPC® 405GPr microprocessor operating at 266 MHz The microprocessor serves as the primary controller of card operations. It orchestrates operation of the special-purpose hardware in the card and implements communications with the host and the IBM Common Cryptographic Architecture (CCA) API functions that comprise the external interface from host application programs to the card. 2. Dynamic random access memory (DRAM) - 64 MB 3. Flash-erasable programmable read-only memory (flash EPROM) for storage of persistent data - 16 MB

4. One hundred twenty-eight KB of static CMOS RAM backed up with battery power when the card is powered off - 128 KB Because cryptographic algorithms such as DES, TDES, and AES are controlled by keys, the security of protected data depends on the security of the cryptographic key. Master keys are used to protect (encrypt) the cryptographic keys that are active on your system. The symmetric keys-master key (SYM-MK) protects symmetric keys such as DES keys,

14 System z Cryptographic Services and z/OS PKI Services and the asymmetric keys-master key (ASYM-MK) protects RSA (Rivest-Shamir-Adleman) keys. Because master key protection is essential to the security of the other keys, the master keys are stored within the secure hardware of the PCIXCC in an area that is unaffected by system power outages because it is protected by a battery power unit. 5. IBM-developed custom cryptographic chip called Otello The Otello chip is divided into two cryptographic algorithm sections: – The symmetric key cryptography and hashing unit provides the DES (64-bit key), TDES (192-bit key) and AES (128-bit, 192-bit, and 256-bit keys) secret key encryption algorithms and the SHA-1 and MD5 secure hashing algorithms. In addition to data encryption, the DES implementation includes both DES and TDES MAC support. – The public key unit provides modular math functions that are used to provide algorithms such as RSA. In addition, Otello contains an add-on interface, an interface to the PowerPC microprocessor, an interface to communicate with the Atmel AVR security microcontroller, and an interface to the hardware random-number source. 6. Hardware-based cryptographic-quality random-number source 7. Field-programmable gate array (FPGA) called Rigoletto. The Rigoletto FPGA contains the logic for all interfaces between the host server, the PowerPC microprocessor, and the Otello cryptographic chip. Because both the host server and the PowerPC microprocessor interface directly with the FPGA in order to talk to each other or to request cryptographic services, the FPGA is the key component for all internal and external programming interfaces. The Rigoletto FPGA provides two fundamentally different communication paths for host-to-card transactions: – Normal path In this mode, host requests are transferred directly into DRAM memory in the card. Once a request is in the card, software in the PowerPC microprocessor determines which function has been requested and executes that function with a combination of PowerPC software and calls to the on-card hardware. –Fast path The fast path provides very high performance for public key cryptographic functions. It gives the host server a direct hardware path to the Otello public key unit so that data does not have to stop in the PowerPC memory and no software is involved. The fast path design supports operations using clear RSA keys or using wrapped RSA keys that are encrypted under a TDES fast path master key securely stored inside the module. 8. Real-time clock module This module maintains the date and time for use by the PowerPC microprocessor. 9. AVR security microcontroller Higher layers in the software hierarchy must not be able to modify operation of the lower layers or tamper with security-related data owned by those lower layers. To accomplish this, the card uses a separate microcontroller that keeps track of the security state of the card and blocks access by higher layers to the memory they must not be allowed to access.

10.Tamper-detection circuitry The secure module on the PCIXCC card is designed with industry-leading tamper-detection features. The security-related electronic components are wrapped in a flexible mesh with narrow, imbedded, overlapping conductive lines that prevent any physical intrusion by drilling, mechanical abrasion, chemical etching, or other means. Circuits inside the module detect damage to the conductive lines, and all sensitive data is

Chapter 1. System z cryptography infrastructure 15 immediately destroyed. This is done by zeroizing the battery-backed static RAM; all sensitive data is stored either directly in the static RAM or in flash memory and encrypted under a 192-bit TDES key that is itself stored in that static RAM. If that key is destroyed, all encrypted data in the flash memory is rendered unusable. Other special circuits sense attacks that can cause imprinting in the static RAM. Imprinting is a process that can permanently burn data into the RAM, so that the same data appears each time the RAM chip is powered on. Different data can be written to the chip while it is operating. but the next time it is powered on, the originally imprinted data appears again as the initial memory content. Imprinting can be caused by exposing the memory to either very low temperatures or X-rays, and the tamper circuitry detects either of these and zeroizes the memory before imprinting can occur. Finally, some attacks are driven by manipulating the power-supply voltages to the card, and these conditions are also detected to prevent the attacks from succeeding.

PCIXCC software overview The software that runs on the PowerPC 405GPr microprocessor is divided into four separate components as shown in Figure 1-6.

Segment 3 (in flash, CCA application replaceable) Digital certificate

Segment 2 Operating system (in flash, (Linux) replaceable) and device drivers Digital certificate

Segment 1 POST 1 (in flash, Miniboot 1 replaceable) Digital certificate

Segment 0 POST 0 (in ROM, Miniboot 0 permanent)

Figure 1-6 Software layers of the PCIXCC

The software components that run on the PowerPC405GPr microprocessor are: Segment 0 contains POST (power-on self-test) 0 and Miniboot 0, stored in a region of flash EPROM that is unalterable once the card leaves the factory. POST 0 contains the small, low-level hardware self-test and setup. Miniboot 0 is the lowest level software for control of loading software into segments 1, 2, and 3. Segment 1 contains POST 1 and Miniboot 1. These components are extensions to the POST and Miniboot in Segment 0 but have the important distinction that they can be securely reloaded after the card has been manufactured. Thus, Segment 0 holds the minimum required POST and Miniboot functions, while Segment 1 contains the majority.

16 System z Cryptographic Services and z/OS PKI Services This is done to minimize the chances that a critical error will occur in code that cannot be updated in the field. Segment 2 contains the operating system and device drivers. The PCIXCC card uses an open-source imbedded Linux operating system that provides a subset of the features normally found in desktop or server Linux systems. Special device drivers have been written to allow the operating system and application program to use the unique hardware inside the card. Segment 3 contains the application program that runs on the PowerPC 405GPr to give the card the cryptographic API functions seen by host programs. This application program implements the IBM CCA cryptographic API, which provides the functions accessible to application programs and administrative software running on the host system.

The purpose of POST is to test and initialize all hardware in the coprocessor card, including the PowerPC 405GPr processor, the cryptographic engines, the communications interfaces, and all other logic. It prevents use of the card if serious faults occur.

The purpose of Miniboot is to control the secure loading of new software into Segments 1, 2, and 3. The Miniboot code-loading architecture provides assurance that any software executing in the card has not been tampered with, and that it was created by IBM or someone approved by IBM to do so. Each segment has control over what software can be loaded into the next segment, and all segments are protected with digital signatures that can be verified back to a root key securely managed by IBM.

1.2.5 Crypto Express 2 Feature

The CEX2 feature combines the functions of a coprocessor (for secure key encrypted transactions) with the functions of an accelerator (for acceleration of transactions using SSL) into a single optional feature with two PCI-X adapters. Using the HMC console of a z9 system, the PCI-X adapters can be customized to have two coprocessors, two accelerators,

or one of each. Figure 1-7 shows the layout of a CEX2 feature.

t t

a PCIXCC

PCI-X B

STI bridge card

1/.5 GBps r e

each dir t

t a STI B interface 1 GBps PCI-X PCI-X (64-bit, 133 MHz)

bridge

r e

STI t t

1/.5 GBps a

PCIXCC B each dir PCI-X

bridge card

t a B

STI = Self-timed interface

Figure 1-7 Layout of a CEX2 feature

Chapter 1. System z cryptography infrastructure 17 The CEX2 in coprocessor mode (CEX2C) provides specialized hardware that performs DES, TDES, SHA-1, and RSA operations. The CEX2C is designed to protect the cryptographic keys. Security relevant cryptographic keys are encrypted under a master key when outside of the secure boundary of the CEX2C card. The master keys are always kept in battery backed-up memory within the tamper-protected boundary of the CEX2C, and they are

destroyed if the hardware module detects an attempt to penetrate it. The tamper-responding hardware has been certified at the highest level under the FIPS 140-2 standard, namely, Level 4. The CEX2C also supports the clear key PKA operations that are often used to provide SSL protocol communications.

When configured in accelerator mode (CEX2A), the CEX2 feature provides hardware support to accelerate certain cryptographic operations that occur in the e-business environment. Compute-intensive public key operations as used by the SSL/TLS protocol can be off-loaded from the CP to the CEX2A, potentially increasing system throughput. The CEX2 in accelerator mode works in clear key mode only.

A z9 109, z9 BC, or z9 EC server can support a maximum of eight CEX2 features. Because each feature provides two coprocessors or accelerators, a z9 server can support a maximum of 16 cryptographic coprocessors or accelerators.

The connection of the CEX2 feature to the z9 CPs via the PCI-X bus incurs latency and data transmission time. Because of this connection to the z9 CPs, the CEX2 executes its cryptographic operations asynchronously with a CP operation. A CP requesting a cryptographic operation from the CEX2 uses a message-queuing protocol to communicate with the CEX2. After enqueueing a request to the CEX2, the host operating system suspends the task that has enqueued the cryptographic operation and dispatches another task. Thus, processing of the cryptographic operation in the CEX2 works in parallel to other tasks being executed in the z9 CP. A special CP task polls at fixed time intervals for finished operations of the CEX2, dequeues them, and executes the Resume function to cause the redispatch of the application that is waiting for the result of the cryptographic operation. For each PCI-X adapter in the CEX2, up to 8 requests can be waiting in the queue either for execution or for dequeueing of the result of a cryptographic operation by a CP. In the CEX2, several operations can be performed in parallel.

The CEX2A is actually a CEX2C that has been reconfigured by the user to provide only a subset of the CEX2C functions at enhanced speed. The only functions that remain available when a CEX2C has been reconfigured into a CEX2A are those used for the acceleration of modular arithmetic operations - that is, the RSA cryptographic operations used with the SSL/TLS protocol: PKA decrypt (CSNDPKD) with PKCS 1.2 formatting PKA encrypt (CSNDPKE) with ZERO-PAD formatting Digital signature verification

The encrypt and decrypt RSA functions support key lengths of 512 to 2048 bits.

18 System z Cryptographic Services and z/OS PKI Services Each PCIXCC has an eight-character serial number and a two-digit adjunct processor (AP) number or ID. The number of APs is limited to 16 on System z9, and a CEX2C is therefore given an AP number between 0 and 15. As shown in Example 1-1, the ICSF Coprocessor Management panel refers to these serial numbers and IDs. The panel prefixes the ID with a letter as follows: A for PCICA, E for CEX2C, F for CEX2A, and X for PCIXCC.

Example 1-1 Sample ICSF Coprocessor Management panel

------ICSF Coprocessor Management ------Row 1 to 4 of 4

Select the coprocessors to be processed and press ENTER. Action characters are: A, D, E, K, R and S. See the help panel for details.

COPROCESSOR SERIAL NUMBER STATUS ------. E00 95000224 ACTIVE . E01 95000225 DEACTIVATED . E02 95000182 DEACTIVATED . E03 95000180 DEACTIVATED ******************************* Bottom of data ********************************

Note: ICSF recognizes the CEX2A beginning with the FMID HCR7730 level of ICSF. Previous levels of ICSF ignore the CEX2A cards.

1.2.6 Comparison of CPACF, CEX2C, and CEX2A

Table 1-7 summarizes the functions and attributes of the cryptographic hardware that is available for a System z9.

Table 1-7 Comparison of System z9 cryptographic hardware, Function or attribute CPACF CEX2C CEX2A

DES/TDES encrypt/decrypt with clear key X

AES-128 encrypt/decrypt with clear key X

DES/TDES encrypt/decrypt with secure key X

Pseudorandom number generation X X

Hashing and message authentication X X

RSA functions X X

Clear key RSA X X

Highest SSL handshake performance X

Highest performance for asymmetric X encryption with clear key

Highest performance for asymmetric X encryption with secure key

Physically imbedded on each CP X

Chapter 1. System z cryptography infrastructure 19 Function or attribute CPACF CEX2C CEX2A

Tamper-resistant hardware packaging X FIPS 140-2 Level 4 certification X

ICSF required to be active X X

Storage for system master keys X

System master keys required to be loaded X

Key management operations X

Note: A secure key is a key that has been encrypted under another key (usually the master key).

1.3 IBM Common Cryptographic Architecture

In Figure 1-6 on page 16, we saw that Segment 3 of the PCIXCC software contains the application program that runs on the PowerPC 405GPr to give the card the cryptographic API functions seen by host programs. This application program implements the IBM Common Cryptographic Architecture (CCA) cryptographic API, which provides the functions accessible to application programs and administrative software running on the host system. In this section we explain the rationale for the IBM CCA and describe some of its key features.

1.3.1 Rationale for the IBM CCA

The IBM Common Cryptographic Architecture is, as its name implies, an architecture for the use of cryptography, and this architecture is common across IBM products and operating system platforms. The IBM CCA is not itself a product. The first version of the IBM CCA was published in 1990.

Some applications may need to encrypt a file locally and decrypt it either locally or on a remote system at an indeterminate time in the future. This requires that the cryptographic algorithm be compatible in the two systems and that the key used for decryption be available at the remote system.

Other applications may require that communications between systems be enciphered. This requires the use of a common cryptographic key-management and key-exchange approach.

Cryptographic services are tailored for the environment where they will operate. However, they should perform the same operation, with the same results, regardless of the product or the environment. If a customer uses a workstation-based product for user cryptographic services, it should be compatible with host-based products that provide the same services. In addition, if a customer writes an application that requires cryptographic services, the application should be portable between the IBM strategic operating systems. Considering all these requirements, IBM concluded that a cryptographic architecture was both necessary and desirable.

The IBM CCA cryptographic API definition uses a common key-management approach and contains a set of consistent callable services. (A callable service is a routine that receives control when an application program issues a CALL statement.)

20 System z Cryptographic Services and z/OS PKI Services Common key management ensures that all products that conform to the architecture allow users to share cryptographic keys in a consistent manner. The definition of key management provides methods for initializing keys on systems and networks and also supports methods for the generation, distribution, exchange, and storage of keys.

The callable services provide a common high-level language interface for user or system applications. Thus, an application for a small machine can use the same service calls as an application for a large machine. The services provide a common set of functionality that is applicable to a wide variety of applications. The CCA cryptographic API services define a level of cryptographic capability that allows programs to be developed that work on disparate systems. In particular, the CCA provides two forms of compatibility for applications: interoperability and portability.

Interoperability is the assurance that applications that use the architected services can work together. Interoperability is achieved by using common encryption and decryption algorithms, common key-management definitions, and common external information formats (that is, formats for information sent to another system).

Portability is the ability to move an application program from one system to another without changing the program. However, it should be noted that portability is at the source code level - that is, it may be necessary to recompile the application program for it to be able to run on a different cryptographic system or to run on a different cryptographic product on the same system.

The objectives in designing the architecture for the CCA cryptographic API were to provide an intuitive multisystem API while allowing for future growth (for example, a new cryptographic algorithm or a new hashing algorithm). Growth can be accommodated by adding new services. However, in many cases, the old service definition may almost meet the new requirement, except that some new parameter option specification requires support. This desirable design trait is addressed by the definition of a rule array in many services. The rule array length and rule array parameters, in effect, support a variable-length method of passing information to the service. For any particular level of the software, there is defined maximum size of the rule array in any particular service. However, a later level of software may define more parameter options and support a larger rule array size to accommodate increased functionality.

1.3.2 CCA callable services

Table 1-8 shows most of the categories of CCA callable services and some of the services in each category. The service pseudonym is the descriptive name for a service, while the service name is the formal name for the service and the name by which the service is called from a program.

Table 1-8 Some CCA callable services Service pseudonym Service name

Managing DES cryptographic keys

Clear key import CSNBCKI

Data key export CSNBDKX

Data key import CSNBDKM

Key export CSNBKEX

Key generate CSNBKGN

Chapter 1. System z cryptography infrastructure 21 Service pseudonym Service name

Key import CSNBKIM Random number generate CSNBRNG

Symmetric key export CSNDSYX

Symmetric key generate CSNDSYG

Symmetric key import CSNDSYI

Protecting data

Decipher CSNBDEC

Encipher CSNBENC

Symmetric key decipher CSNBSYD

Symmetric key encipher CSNBSYE

Verifying data integrity and authenticity

MAC generate CSNBMGN

MAC verify CSNBMVR

One-way hash generate CSNBOWH

Financial services

Clear PIN encrypt CSNBCPE

Clear PIN generate CSNBPGN

Encrypted PIN generate CSNBEPG

Encrypted PIN verify CSNBPVR

Using digital signatures

Digital signature generate CSNDDSG

Digital signature verify CSNDDSV

Managing PKA cryptographic keys

PKA key generate CSNDPKG

PKA key import CSNDPKI

PKA key token build CSNDPKB

PKA public key extract CSNDPKX

22 System z Cryptographic Services and z/OS PKI Services If CSNBxxxx is the name of a callable service, then the general format of a call to that service is as follows: CALL CSNBxxxx(return_code, reason_code, exit_data_length, exit_data, parameter_5, parameter_6, ...... parameter_N)

The following rules apply to the callable services: Parameters are required and positional. Each parameter list has a fixed number of parameters. Each parameter is defined as an integer or a character string.

The exit_data parameter contains the character string that is passed to the installation’s preprocessing exit for that callable service. The preprocessing exit is invoked when an application program calls a callable service, but before the callable service starts processing.

As an example of a call to a service, consider Example 1-2, which shows the format of a call to the CSNBSYE service to encipher data in an address space.

Example 1-2 Format of a call to the symmetric key encipher service CALL CSNBSYE( return_code, reason_code, exit_data_length, exit_data, rule_array_count, rule_array, key_identifier_length, key_identifier, key_parms_length, key_parms, block_size, initialization_vector_length, initialization_vector, chain_data_length, chain_data, clear_text_length, clear_text, cipher_text_length, cipher_text, optional_data_length, optional_data)

The CSNBSYE rule_array parameter may contain one, two, three, or four 8-byte keywords that provide information to control the processing: Algorithm (required) The algorithm may be AES or DES. If the algorithm is DES and the key length is 16 or 24 bytes, TDES will be used.

Chapter 1. System z cryptography infrastructure 23 Processing rule (optional) The choices include CBC (cipher block chaining) and ECB (Electronic Codebook). Key rule (optional) This field specifies whether the key_identifier parameter contains the clear key itself, an internal token containing the clear key, or the label name of a key. ICV selection (optional) This field specifies whether the service should take the initialization vector for the encryption algorithm from the initialization_vector parameter or from the output chaining vector contained in the work area to which the chain_data parameter points.

1.3.3 DES key management

Because the DES and TDES algorithms are controlled by keys, the security of protected data depends on the security of the cryptographic key. The CCA uses a master key to protect other keys. Keys are active on a system only when they are encrypted under a variant of the master key, so the master key protects all keys that are used on the system. A master key always remains in a secure area in the cryptographic hardware. In a z/OS environment, an ICSF administrator initializes and changes master keys using the ICSF panels or a Trusted Key Entry (TKE) workstation.

All other keys that are encrypted under a master key are stored outside the protected area of the cryptographic hardware; they cannot be attacked because the master key used to encrypt them is itself secure inside the tamper-protected cryptographic hardware and is zeroized if any attack is attempted. This is an effective way to protect a large number of keys while needing to provide physical security for only a master key.

When the cryptographic hardware is a CCF, the master key is called a DES master key and has a length of 128 bits. When the cryptographic hardware is a PCICC or PCIXCC/CEX2C, the master key is called the symmetric key-master key (SYM-MK). A SYM-MK is 192 bits long; however, in the z/OS environment ICSF forces the SYM-MK to be 128 bits long.

Cryptographic key separation An important concept implemented in the CCA cryptographic API is cryptographic key separation. This concept provides for the creator of a cryptographic key (for example, via the Key Generate service) to declare the intended usage of the key via a key type specification. The cryptographic subsystem then enforces this specification by denying requested services that are inappropriate for the declared key type. For example, a key that is used to encrypt data cannot be used to encrypt a key. Likewise, a key that is designated a key-encrypting key cannot be employed in a decryption operation, thereby preventing the use of a key-encrypting key to obtain a cleartext key.

Table 1-9 shows some of the key types supported by the CCA.

Table 1-9 Some CCA key types Key type Attributes

CIPHER A 64-bit or 128-bit key used in the Encipher or Decipher callable service.

DATA A 64-bit, 128-bit, or 192-bit key used in the Encipher, Decipher, MAC generate, or MAC verify callable service.

DATAC A 128-bit key used in the Encipher or Decipher callable service but not in the MAC generate or MAC verify callable service.

24 System z Cryptographic Services and z/OS PKI Services Key type Attributes

DATAM 128-bit key used in the MAC generate or MAC verify callable service.

DATAMV 128-bit key used in the MAC verify callable service.

DECIPHER A 64-bit or 128-bit key used only to decrypt data. DECIPHER keys cannot be used in the Encipher callable service.

ENCIPHER A 64-bit or 128-bit key used only to encrypt data. ENCIPHER keys cannot be used in the Decipher callable service.

EXPORTER A 128-bit key-encrypting key used to convert a key from the operational form into exportable form. (We discuss key forms in “Key forms” on page 27.)

IMPORTER A 128-bit key-encrypting key used to convert a key from the importable form into operational form.

MAC A 64-bit or 128-bit key used in the MAC generate or MAC verify callable service.

MACVER A 64-bit or 128-bit key used in the MAC verify callable service but not in the MAC generate callable service.

Each type of key (except the master key) has a unique control vector associated with it. Table 1-10 shows some of the key types and their associated control vectors.

Table 1-10 Control vector values for some key types Key type Control vector (in hex)

CIPHER 64-bit 00 03 71 00 03 00 00 00 00 00 00 00 00 00 00 00 128-bit 00 03 71 00 03 41 00 00 00 03 71 00 03 21 00 00

DATA 64-bit 00 00 7D 00 03 00 00 00 00 00 00 00 00 00 00 00 128-bit 00 00 7D 00 03 41 00 00 00 00 7D 00 03 21 00 00

DATAC 00 00 71 00 03 41 00 00 00 00 71 00 03 21 00 00

DATAM 00 00 4D 00 03 41 00 00 00 00 4D 00 03 21 00 00

DATAMV 00 00 44 00 03 41 00 00 00 00 44 00 03 21 00 00

DECIPHER 64-bit 00 03 50 00 03 00 00 00 00 00 00 00 00 00 00 00 128-bit 00 03 50 00 03 41 00 00 00 03 50 00 03 21 00 00

ENCIPHER 64-bit 00 03 60 00 03 00 00 00 00 00 00 00 00 00 00 00 128-bit 00 03 60 00 03 41 00 00 00 03 60 00 03 21 00 00

EXPORTER 00 41 7D 00 03 41 00 00 00 41 7D 00 03 21 00 00

IMPORTER 00 42 7D 00 03 41 00 00 00 42 7D 00 03 21 00 00

Chapter 1. System z cryptography infrastructure 25 Key type Control vector (in hex)

MAC 64-bit 00 05 4D 00 03 00 00 00 00 00 00 00 00 00 00 00 128-bit 00 05 4D 00 03 41 00 00 00 05 4D 00 03 21 00 00

MACVER 64-bit 00 05 44 00 03 00 00 00 00 00 00 00 00 00 00 00 128-bit 00 05 44 00 03 41 00 00 00 05 44 00 03 21 00 00

The bits in a control vector specify the possible uses of the key in great detail; for example, bits specify the key type, the key subtype, whether the key can be exported, and whether the key can be used in encryption, decryption, MAC generation, and MAC verification. This prevents the many attacks that are otherwise possible by using a key for an inappropriate function.

Whenever the master key is used to encrypt a key, the cryptographic hardware produces a variation of the master key according to the type of key that is being enciphered. These variations are called master key variants. The cryptographic hardware creates a master key variant by exclusive ORing a control vector with the master key. For example, when the master key is used to encipher a DATA key, the cryptographic hardware produces the master key DATA variant by XORing the master key with the control vector for DATA keys. After creating the master key DATA variant, the cryptographic hardware encrypts the DATA key by using the master key DATA variant as the key for the encryption algorithm. See Figure 1-8.

Master key

Control vector: Control vector: Control vector: DATA keys MAC keys IMPORTER keys

Master key variant: Master key variant: Master key variant: DATA keys MAC keys IMPORTER keys

DES DES DES encryption encryption encryption algorithm algorithm algorithm DATA key MAC key IMPORTER key to be encrypted to be encrypted to be encrypted

Encrypted Encrypted Encrypted DATA key MAC key IMPORTER key Figure 1-8 Using the master key to encrypt a key

26 System z Cryptographic Services and z/OS PKI Services In Figure 1-9 we formulate a request to encrypt plaintext using a DATA key K that has already been encrypted under the SYM-MK master key of the CEX2C. K has an associated control vector C. C is examined to determine whether it has attributes that qualify it to be used in the called service in the requested way. If it does not, the service invocation fails. If C is valid, execution of the requested service continues. The CEX2C XORs the master key with the

DATA control vector to produce a master key variant. Next it uses the master key variant to decrypt our DATA key K. Finally it performs the requested encryption using the decrypted DATA key.

Encryption request 1

DATA key MIOH JNOR Control Encrypted 7C %=#F vector C key K plaintext ciphertext

Control vector 2 checking DES Master key 5 encryption

3 4 Master key variant: DES DATA keys decryption

Unencrypted DATA key CEX2C secure boundary

Figure 1-9 Processing inside the CEX2C during an encryption request

Notice that each key K is encrypted in such a way that the value of the master key and the control vector C (associated with K) must be specified to recover the key.

If a caller alters the value of the control vector to permit use of the key in a command, the correct value of the key is not recovered by the key decryption process, and any resulting output of the service is invalid - that is, any output is equivalent to that resulting from using a random unknown key value in that service.

Key forms The CCA specifies that a DES key must be in one of three forms: Operational An operational key is a key that is encrypted under the master key at a particular system and can be used in a service at that system. Exportable An exportable key is a key that is encrypted under an exporter key-encrypting key. In this form, a key can be sent outside the system to another system. A key in exportable form cannot be used in a cryptographic function.

Chapter 1. System z cryptography infrastructure 27 Importable An importable key is a key that is encrypted under an importer key-encrypting key. A key is received from another system in this form. A key in importable form cannot be used in a cryptographic function.

The conversion from one key form to another key form is considered to be a one-way flow: importable → operational → exportable. An operational key form cannot be turned back into an importable key form, and an exportable key form cannot be turned back into an operational or importable key form.

Operational keys are accessed either directly by value in an internal key token or indirectly by a key label. Internal key token As shown in Figure 1-10 an internal key token contains an encrypted cryptographic key and its associated control vector. It is typically used for a key with a short life, as for example, a key that is used for a session and is disposed of when the session is over.

Control vector

Key encrypted under master key

Figure 1-10 DES key: internal key token

Key label A key label indirectly identifies an internal key token stored in key storage. (An example of key storage in the z/OS environment is the ICSF Cryptographic Key Dataset, a data set often called the CKDS). An operational key is a candidate for being kept in key storage if it is a key with a long life, if it is appropriate to control access to this key, or if many users need access to this key.

The key_identifier parameter found in most of the cryptographic API callable services allows the programmer to pass keys to the service either directly by value or indirectly via a key label.

A key in importable or exportable form is kept in an external key token. The external key token contains the encrypted key and its associated control vector; see Figure 1-11.

Control vector

Key encrypted under exported key

Figure 1-11 DES key: external key token

28 System z Cryptographic Services and z/OS PKI Services The CCA uses the exportable and importable key forms to support electronic key distribution with minimal manual key installation. Suppose Alice wishes to send a key K to Bob. An initial exporter key-encrypting key is installed on Alice’s system by a courier, and an initial importer key-encrypting key is installed on Bob’s system. The exporter key and the importer key have the same value but different control vectors.

After the manual installation of these initial key-encrypting keys, all subsequent key distribution may be done electronically. For example, Alice may execute the Key Export service to convert the information for K found in its internal key token to an exportable key in an external key token. The external key token contains K encrypted under the exporter key (instead of the master key) and K’s associated control vector. The key is encrypted under the key-encrypting key that exists on Alice’s sending system as an exporter key and on Bob’s receiving system as an importer key. See Figure 1-12 where Alice sends a DATA key to Bob.

Alice's system

Internal Internal External key token key token key token DATA control vector DATA EXPORTER control control vector vector

Key Export

CEX2C Master DES key A encryption

Master key Master key EXPORTER A variant A variant key variant

DES DES decryption decryption DATA control vector

Unencrypted Unencrypted

DATA key EXPORTER key

Figure 1-12 Key distribution: Key Export service

Note that because the Key Export service is performed in the CEX2C, the clear value of the key to be exported is not revealed. In addition, if the content of the control vector is changed either accidentally or intentionally, the correct key value will not be recovered because the value of the encrypted key is cryptographically coupled to the control vector.

Chapter 1. System z cryptography infrastructure 29 Bob’s system considers the key to be in importable form. An application on Bob’s system may execute the Key Import service to perform the cryptographic transformations to convert the information in the external key token to an operational key in an internal key token. The intended usage of the key (that is, its type) is maintained through the control vector mechanism. When the key is re-enciphered from under the importer key to under the master

key for Bob’s system, it is in operational form and can be used again. See Figure 1-13.

Bob's system

External Internal Internal key token key token key token DATA control vector DATA IMPORTER control control vector vector Key Import

CEX2C

Master DES key B encryption

IMPORTER Master key Master key key variant B variant B variant

DES DES decryption decryption

DATA control vector Unencrypted Unencrypted DATA key IMPORTER key

Figure 1-13 Key distribution: Key Import service

1.3.4 PKA key management

A public key algorithm (PKA) is an asymmetric cryptographic process in which a public key is used for encryption of secret (symmetric) keys and digital signature verification and a private key is used for decryption of secret keys and digital signature generation. RSA and DSA are two public key algorithms. The security of data protected by a PKA depends on the security of the private key. The CCA uses a master key to protect private keys. Private keys are active on a system only when they are encrypted under the master key, so the master key protects all private keys that are used on the system. A master key always remains in a secure area in the

cryptographic hardware. In a z/OS environment, an ICSF administrator initializes and changes master keys using the ICSF panels or a Trusted Key Entry (TKE) workstation.

Almost all private keys that are encrypted under a master key are stored outside the protected area of the cryptographic hardware; they cannot be attacked because the master key used to encrypt them is itself secure inside the tamper-protected cryptographic hardware and will be zeroized if any attack is attempted.

30 System z Cryptographic Services and z/OS PKI Services There is one exception to the rule that private keys are stored outside the cryptographic hardware. CCA supports retained RSA keys, in which the RSA key pair is generated inside the secure cryptographic hardware, and only the public key is ever allowed to leave the secure environment. The private key remains inside the secure hardware and is never allowed to leave in any form. This is designed to meet the strict demands of some standards, which require assurance that the private key can exist only in a single cryptographic module. It greatly strengthens nonrepudiation; if a private key can exist only in one cryptographic device, it provides assurance that any digital signature computed using that private key can have originated only at the system in which that device is installed. In the PCIXCC, retained RSA private keys are stored in the flash memory inside the secure module. Like all CCA data stored in that memory, RSA private keys are securely encrypted under a TDES key that is destroyed if any attempt to tamper with the device occurs.

Conceptually, the master key used to protect DES keys could also be used to protect PKA private keys. However, the CCA designers chose to use a different master key as follows: When the cryptographic hardware is a PCICC or PCIXCC/CEX2C, the 192-bit master key is called the asymmetric-key master key (ASYM-MK). When the cryptographic hardware is a CCF, there are two PKA master keys: – The Key Management Master Key (KMMK) is a 192-bit key that is used to protect private keys that are used in both digital signature generation and decryption of secret (symmetric) keys. – The Signature Master Key (SMK) is a 192-bit key that is used to protect private keys that are used only in digital signature generation.

Key forms As was the case with DES keys, the CCA specifies that a PKA private key must be in one of three forms: Operational An operational private key is a key that is encrypted under a PKA master key at a particular system and can be used in a service at that system. Exportable An exportable private key is a key that is either in cleartext or is encrypted under a DES exporter key-encrypting key. In this form, a key can be sent outside the system to another system. A private key in exportable form cannot be used in a cryptographic function. Importable An importable private key is a key that is either in cleartext or is encrypted under a DES importer key-encrypting key. A key is received from another system in this form. A private key in importable form cannot be used in a cryptographic function.

Operational keys are accessed either directly by value in an internal key token or indirectly by a key label. Internal key token The format of an RSA private internal key token differs from the format of a DSS private internal key token; we discuss only the former. As shown in Figure 1-14 on page 32 an RSA private internal key token contains several sections; R indicates that the section is required, while O indicates that the section is optional.

Chapter 1. System z cryptography infrastructure 31

Token identifier: X'1F' Header (R)

RSA private key section (R)

Public key modulus length in bits Public key exponent e RSA public key section (R)

RSA private key name (O)

Flag byte indicating whether: RSA or DSS key Private or public key Private key name section exists Internal information section (R) Private key is unenciphered Key is a retained key Count of number of sections Info about key if it is retained

Figure 1-14 RSA private key: internal key token

An access control system can use the private key name to verify that the calling application is entitled to use the key. The RSA private key section can have three forms: – 1024-bit Modulus exponent form for the CCF. – 2048-bit Chinese Remainder Theorem form. – 1024-bit Modulus exponent form for PCICC, PCIXCC, or CEX2C. See Figure 1-15.

SHA-1 hash value of the next sub-section. This hash value is checked after an enciphered private key is deciphered for use.

Key use flag bits: Decryption of secret keys permitted Digital signature generation permitted Object protection key (OPK) encrypted under the ASYM-MK Private exponent d encrypted under the OPK Modulus n

SHA-1 hash value of the blinding information sub-section

Random number r Random number r-1 Blinding information sub-section X'00' padding to get a multiple of 8 bytes

Figure 1-15 RSA private key internal key token

32 System z Cryptographic Services and z/OS PKI Services Key label A key label indirectly identifies an internal key token stored in key storage. (An example of key storage in the z/OS environment is the ICSF Public Key Dataset, a VSAM data set often called the PKDS).

The key_identifier parameter found in most of the cryptographic API callable services enables the programmer to pass keys to the service either directly by value or indirectly via a key label.

A private key in importable or exportable form is kept in an external key token. The format of an RSA private external key token differs from the format of a DSS private external key token; we discuss only the former. As shown in Figure 1-16 an RSA private external key token contains several sections; once again, R indicates that the section is required while, O indicates that the section is optional.

Token identifier: X'1E' Header (R)

RSA private key section (R)

Public key modulus length in bits Public key exponent e RSA public key section (R)

RSA private key name (O)

Figure 1-16 RSA private key: external key token

Chapter 1. System z cryptography infrastructure 33 The RSA private key section can have two forms: – 1024-bit Modulus exponent form for the CCF and PCICC. – 2048-bit Chinese Remainder Theorem form for the PCICC, PCIXCC, or CEX2C. See Figure 1-17.

SHA-1 hash value of the next subsection. This hash value is checked after an enciphered private key is deciphered for use.

Key security flag: RSA private key is encrypted. RSA private key is unencrypted. SHA-1 hash value of the RSA private key name section if it exists Key use flag bits: Decryption of secret keys is permitted. Digital signature generation permitted. When the "key Random number security flag" so Prime number p indicates, this is Prime number q encrypted under a d mod(p-1) DES importer or d mod(q-1) exporter key using q-1 mod p TDES X'00' padding to get a multiple of 8 bytes Modulus n

Figure 1-17 RSA private key external key token

You can use the PKA Key Import callable service to do either of the following: Get a private key deciphered from an importer key and enciphered by the ASYM-MK. Get a clear, unenciphered private key enciphered by the ASYM-MK.

So far we have only discussed tokens for RSA private keys. The CCA also defines a token for RSA public keys. Because public keys are meant to be shared, the format of an RSA public key token is rather simple: Header containing a token identifier of X’1E’ (indicating an external token) RSA public key section containing the public exponent e and the modulus n in cleartext

CCA callable services can use PKA public key tokens directly in the external form.

1.4 ICSF

In the z/OS environment, the Integrated Cryptographic Service Facility (ICSF) provides access to cryptographic functions through callable services. The ICSF callable services comply with the IBM CCA cryptographic API and are available for programs written in assembler or high-level languages. IBM CCA supports a hierarchical structure of keys where keys can be encrypted by other keys (key-encrypting keys, KEKs), the master key being at the top of the hierarchy.

34 System z Cryptographic Services and z/OS PKI Services ICSF provides cryptographic coprocessors administration facilities for those coprocessors that require a master key to be set.

ICSF also provides key repositories in the form of two VSAM data sets where keys can be kept in “key tokens” in clear value or encrypted under a KEK or under the coprocessors master keys. The VSAM data sets are the Cryptographic Key Dataset (CKDS) and the Public Key Dataset (PKDS). The key tokens in the CKDS and the PKDS are given a user- or system-defined label that is used for their retrieval and maintenance.

Figure 1-18 is a schematic view of the hardware cryptography implementation in the System z environment. Note that the hardware cryptography technology shown here is the one available on the IBM System z9 and eServer zSeries 990 and 890 platforms. The zSeries 800 and 900 host other, although functionally compatible, types of cryptographic coprocessors.

TSO terminal (with optional System z9 TKE workstation)

Hardware Crypto

CEX2C z/OS Symmetric-keys master Key RACF Plaintext Appl Asymmetric-keys ICSF master key Ciphertext Crypto instruction Segment 3 Callable Segment 2 services CALL CSNxxxx Segment 1 APIs Segment 0 Key to use

CPACF Clear application key in storage

or instructions in the application

Options CKDS PKDS data set

Application's DES keys Application's public/private encrypted under keys encrypted under SYM-MK ASYM-MK Figure 1-18 Overview of how the hardware and software work together

In Figure 1-18, you can see an application program that has issued a CCA cryptographic API call on a System z9. The call is routed to the ICSF started task. The ICSF started task invokes RACF to determine whether the user ID associated with the request is authorized to use the requested cryptographic service and any keys associated with the request. If the user ID has the proper authority, the ICSF started task decides whether it should perform the request using ICSF software or cryptographic hardware. If ICSF decides to use cryptographic hardware, it gives control to its routines that contain the crypto instructions. The crypto instructions that drive the CEX2C are IBM proprietary; IBM does not disclose them. The crypto instructions that drive the CPACF were discussed in 1.1, “Message-security assist” on page 4.

Chapter 1. System z cryptography infrastructure 35 If ICSF routes the request to the CEX2C and the request is, say, a request to encrypt data, the ICSF started task provides the CEX2C with the data to be encrypted and the key to be used by the encryption algorithm. Recall that the key is encrypted, in this case, under a variant of the symmetric key-master key (SYM-MK) stored in the CEX2C. The request proceeds as shown previously in Figure 1-9 on page 27.

The interactions between the functional blocks shown in Figure 1-18 on page 35 are as follows: ICSF is a z/OS started task that offers cryptographic APIs to applications and drives the requests to the Crypto Express2 Coprocessors (CEX2C). The CEX2C is a “secure” coprocessor in that it contains a master key used to encrypt keys to be kept in storage or in the PKDS data set. The master key resides in the coprocessor hardware only and is used to decrypt, internally to the coprocessor, the “secure” keys provided so that they can be used to encrypt or decrypt data. ICSF needs other data sets to operate: the CKDS for the use of cryptographic hardware, and an options data set that contains the ICSF started task startup parameters. Installing and maintaining the secret master key is a task that security officers can perform from TSO/E terminals or from an optional Trusted Key Entry (TKE) workstation, the latter for a very high security level of the interactions between the security officers and the CEX2C. If ICSF has access to more than one secure coprocessor, all coprocessors must have been set with the same master key value. The CPACF operates only with clear keys.

The keys can be stored in ICSF-managed VSAM data sets and pointed to by the application program by using the label under which they are stored. The CKDS is used to store the symmetric keys in their encrypted form, and the PKDS is used to store the asymmetric keys. If the level of ICSF that you are using is HCR7720 or higher, you can also store keys in the CKDS in clear (unencrypted) form.

Controlling who can use cryptographic keys and services The ICSF administrator can use RACF to control which applications can use specific keys and services. To set up these controls, the ICSF administrator must create RACF general resource profiles in the CSFKEYS resource class and in the CSFSERV resource class. The CSFKEYS class controls access to cryptographic keys, and the CSFSERV class controls access to ICSF services.

The following RACF command defines a profile in the CSFKEYS class:

RDEFINE CSFKEYS label UACC(NONE) other-optional-operands

where label is the label by which the key is defined in the CKDS or PKDS. Use the RACF PERMIT command to give user IDs or groups access to the profile:

PERMIT label CLASS(CSFKEYS) ID(groupID) ACCESS(READ)

To refresh the in-storage RACF profiles, issue a SETROPTS command: SETROPTS RACLIST(CSFKEYS) REFRESH

36 System z Cryptographic Services and z/OS PKI Services The following RACF command defines a profile in the CSFSERV class: RDEFINE CSFSERV service-name UACC(NONE) other-optional-operands where service-name is chosen from a list in the z/OS V1R9.0 Cryptographic Services ICSF Administrator's Guide, SA22-7521. (If the application program called the CSNBxxxx service, you should generally specify CSFxxxx as the service-name in the RDEFINE command. Note, however, that access to ICSF services CSNBSYE and CSNBSYD is not protected by profiles in the CSFSERV class.) Use the RACF PERMIT command to give user IDs or groups access to the profile: PERMIT service-name CLASS(CSFSERV) ID(groupID) ACCESS(READ)

To refresh the in-storage RACF profiles, issue a SETROPTS command:

SETROPTS RACLIST(CSFSERV) REFRESH

ICSF callable services The format for invoking an ICSF callable service depends on the programming language. For the languages that CICS supports, the formats are as follows: C CSNBxxxx (return_code,reason_code,exit_data_length,exit_data, parameter_5,parameter_6,...,parameter_N) COBOL CALL ‘CSNBxxxx’ USING return_code,reason_code,exit_data_length, exit_data,parameter_5,parameter_6,...,parameter_N PL/I DCL CSNBxxxx ENTRY OPTIONS(ASM); CALL CSNBxxxx return_code,reason_code,exit_data_length,exit_data, parameter_5,parameter_6,...,parameter_N Assembler CALL CSNBxxxx,(return_code,reason_code,exit_data_length,exit_data, parameter_5,parameter_6,...,parameter_N)

You cannot use Java to invoke an ICSF callable service.

Before invoking a callable service in an application program, you must link it into the application program as shown in Example 1-3.

Example 1-3 Linking an ICSF callable service into an application program //LKEDENC JOB //*------* //* * //* This JCL links the ICSF encipher callable service, CSNBENC, * //* into an application called ENCIPHER. * //* * //******************************************************************** //LINK EXEC PGM=IEWL,PARM=’XREF,LIST,LET’ //SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(10,10)) //SYSPRINT DD SYSOUT=* //SYSLIB DD DSN=CSF.SCSFMOD0,DISP=SHR *SERVICES ARE IN HERE //SYSLMOD DD DSN=MYAPPL.LOAD,DISP=SHR *MY APPLICATION LIBRARY //SYSLIN DD DSN=MYAPPL.ENCIPHER.OBJ,DISP=SHR *MY ENCIPHER PROGRAM // DD *

Chapter 1. System z cryptography infrastructure 37 ENTRY ENCIPHER NAME ENCIPHER(R) /*

1.4.1 Audit trails

ICSF provides SMF records with administrative audit data related to ICSF operations themselves and security officer access to the CEX2C coprocessors. These are the SMF type 82 records.

RACF provides auditing data and violation reports on the CSFSERV and CSFKEYS classes of resources as specified by the RACF auditors. The audit data is provided in SMF records types 80, 81, and 83.

1.5 Logical partitioning and System z hardware cryptography exploitation

The functional drawing in Figure 1-18 on page 35 describes cryptographic operations at the logical partition level. Up to 16 different logical partitions can share the same CEX2C card, with two CEX2C cards available in each CEX2C feature plugged in the system.

Note: Each logical partition (LPAR) sharing a physical CEX2C coprocessor is granted a “domain” in the coprocessor. A “domain” is a set of physical resources that are dedicated to this very logical partition. Among the resources provided in a domain are registers intended to securely hold the master keys installed for the ICSF instance that runs in the logical partition.

Domains are part of the CEX2C coprocessor FIPS 140-2 evaluation at level 4 and therefore provide complete isolation and secrecy of individual master keys between the sharing logical partitions.

Domains are manually allocated in the logical partitions image profiles and in the ICSF options data sets.

There is no notion of logical partition sharing with the CPACF because the facility is directly available to any logical partition dispatched on any processing unit.

Introduction to LPAR domains A cryptographic coprocessor actually has 16 physical sets of master key registers, each set belonging to a domain. A domain is allocated to a logical partition via the definitions in the partition’s image profile; the same domain must also be allocated to the ICSF instance running in the logical partition via the options data set.

Each ICSF instance accesses only the master keys corresponding to the domain number specified in the partition’s image profile. In other words, each ICSF instance sees a logical crypto coprocessor made of the physical cryptographic engines, shared between all partitions with access to the coprocessor, and of the unique set of registers, the “domain” dedicated to this partition.

38 System z Cryptographic Services and z/OS PKI Services 1.6 Monitoring the cryptographic workload on z/OS

ICSF collects performance and utilization data for the Crypto Express2 Coprocessors, delivered through SMF types 30, 70, 72, and 82 subtypes 18, 19, and 20 records.

There is no SMF data collection for the utilization of the CPACF.

The data used to monitor the cryptographic services activity is collected and stored into SMF records type 70 subtype 2. This data is collected from ICSF or the Crypto Express 2 feature PCIX adapter.

These records are gathered by the RMF™ Monitor I with the gathering option CRYPTO. They can be processed by the RMF Postprocessor to produce the Crypto Hardware Activity report.The RMF Workload Activity report WLMGL also shows delays, if any, incurred because of unavailable cryptographic devices.

The data shown for CEX2C and CEX2A always reflects the total activity in a system across two types of hardware card: Crypto Express2 Coprocessor (CEX2C) Crypto Express2 provides improved secure key and system throughput. The Crypto Express2 feature supports secure key applications and also offers CVV generation and verification services for 19-digit PANs, providing advanced antifraud security. The CEX2C coprocessor can be reconfigured in CEX2A. PCIX Cryptographic Accelerator (CEX2A) This cryptographic hardware accelerator card is attached via the PCI bus to the system. This card provides a competitive option to customers that do not need the high security environment of the secure key but need high cryptographic performance for RSA public key algorithms that may be required in Web server applications. The CEX2A provides clear key RSA operations with a modulo length of 1024 bits or 2048 bits. Two algorithms are available, Modulus exponent (ME) and Chinese Remainder Theorem (CRT) for both key lengths.

The data shown for ICSF is related to the partition.

The Crypto Hardware Activity report provides performance measurements on selected ICSF activities: Using the Data Encryption Standard (DES) to encipher and decipher data. DES is probably the best known and scrutinized encryption algorithm, Generating and verifying message authentication codes (MAC). The MAC is a value calculated from the message according to a secret shared DES key and sent to the receiver together with the message. The receiver can recalculate the MAC and compare it with the MAC received. If the MAC values are identical, the message has not been altered during transmission. Using public hash functions. A hash is calculated from the transmission data according to a public key or function in cases where it is impossible to share a secret key. If the recalculated hash is identical to the one calculated before transmission, data integrity is ensured. Translating and verifying PINs.

Note: More informations and details on crypto monitoring can be found in Chapter 3, “Measuring hardware cryptography activity on z/OS with RMF” on page 65.

Chapter 1. System z cryptography infrastructure 39 1.7 Sysplex and System z hardware cryptography

Several instances of ICSF can coexist in a sysplex, with one ICSF instance per sysplex member, and they can share the CKDS and PKDS data sets - that is, share the keys stored in these data sets. Note however that: CKDS or PKDS sharing implies having set up the same master keys in the coprocessor domains used by the sharing ICSF instances. At this time, no automatic PKDS cache consistency support between the sharing ICSF is available. When an ICSF changes the PKDS DASD contents, the change is not automatically propagated to the other ICSF instances that share the CKDS in the sysplex. However, it is expected that such changes are manageable manually because they occur at low frequency, and because manual processes do exist in ICSF to resynchronize local PKDS caches to the latest PKDS DASD change.

1.8 Software requirements

To exploit the enhancements brought to the CPACF (AES, SHA-256, PRNG) on System z9 requires at a minimum: – z/OS V1.6 with Cryptographic Support for z/OS V1.6/1.7 and z/OS.e V1.6/1.7 Web deliverable. – z/VM V4.4 for guests systems that are to use the CPACF. – Linux for System z - IBM is working with its distribution partners to provide this function in future distribution releases or service updates. Exploiting the Crypto Express2 on System z9 when configured as a coprocessor or accelerator (clear or secure key operations) requires at a minimum: – z/OS V1.6 with Cryptographic Support for z/OS V1.6 and V1.7 and z/OS.e V1.6 and V1.7 Web deliverable. – z/VM V5.1 for z/OS and Linux guests, with PTFs – z/VM V5.2 for z/OS and Linux guests – VSE/ESA™ V2.7 with PTFs and IBM TCP/IP for VSE/ESA SSL support. z/VSE™ V3.1 with PTF – Linux on System z9 - IBM is working with its Linux distribution partners so this function can be provided in future Linux on System z9 distribution releases or service updates.

Note: z/VSE and Linux on System z9 support clear key RSA operations only. z/VM V5.1 and later supports clear and secure key operations.

40 System z Cryptographic Services and z/OS PKI Services

Chapter 2. Hardware cryptography activity assessment on System z

In this chapter we provide an overview of the hardware cryptography exploiting infrastructures in System z and we are introducing the methods that one can use to assess whether and how heavily the System z hardware cryptographic services are invoked. The hardware cryptography “commodity” on System z is today an option for many applications or middlewares which, otherwise use their own software cryptographic code, leading to a situation where the thrust to make operations as “transparent” as possible to the users makes the user sometimes uncertain as whether the application or the middleware is really exploiting the System z integrated hardware cryptography instead of using its own software implementation of the services.

In this chapter, and the following ones, we discuss ways of obtaining confirmation, if needed, that the hardware cryptographic devices are being used and how to assess, whenever possible, their utilization ratio.

The System z cryptographic devices, CPACF and CEX2C (either in coprocessor or accelerator mode) are exploited by applications or middlewares that run on the following operating systems: z/OS z/VSE Linux on System z

We do not mention z/VM here because z/VM’s role is to behave, from the hardware cryptography exploiters’ standpoint, as a transparent link between the guest virtual machine and the physical cryptographic hardware. However the z/VM CP can provide configuration data pertaining to hardware cryptography resources as shown in 2.5, “Setting up hardware cryptography configuration of z/VM” on page 61.

2.1.1 Hardware cryptography exploitation on z/OS

Figure 2-1 summarizes, at a high level, the z/OS cryptographic APIs as of z/OS V1.9.

IMS DB2 z/OS Encryption Facility RSA Bsafe Middlewares/Applications RACF VTAM VPN Applications that use the Kerberos Applications that use CDSA API PKI The PKCS#11 API CICS TS Services … PKCS11 WebSphere AS … JAVA

http LDAP TN3270 PKCS 11 OCSF z/OS FTP IBM SDK

CPACF System SSL direct call from applications Key datasets Secure keys ICSF CKDS Clear keys PKDS PKCS11 tokens RACF TKDS TSO/E

Hardware Master Key

CPACF CEX2C domain Optional TKE Workstation Figure 2-1 z/OS hardware cryptography infrastructure

In Figure 2-1, three APIs are provided by z/OS to applications or middlewares, in addition to the direct access that an application has to the CPACF hardware using the MSA instructions:

ICSF APIs - These are the lowest level cryptographic APIs that z/OS provides. They are: – The IBM CCA (Common Cryptographic Architecture) API – A subset of the RSA PKCS#11 API, which is a new API introduced at z/OS V1.9 and provided as C/C++ libraries.

42 System z Cryptographic Services and z/OS PKI Services

Note: The ICSF PKCS#11 API implementation relies on already existing ICSF functions, with the consequence that ICSF and hardware cryptographic activities

induced by the PKCS#11 API are actually the execution of CCA services and are reported as such from the utilization standpoint.

The System SSL API - This API is at a higher level than ICSF. System SSL transparently converts the cryptographic services requests it receives from applications into ICSF CCA services calls or direct invocations of the CPACF. System SSL is intended to provide applications with an SSL/TLS run-time support. Note that System SSL does not rely exclusively on the System z hardware cryptographic devices to provide the requested services, because it also has a software implementation of these services should, for any reason, hardware cryptography be unavailable on the system. z/OS System SSL is a typical example of those cryptographic service providers where the user might be uncertain, at first glance, whether hardware or software cryptography is currently being used. The OCSF API - This is another high-level API, which is the z/OS implementation of the Intel® Common Data Security Architecture (CDSA) set of cryptographic services. The exploiting application or middleware has to select the cryptographic service provider it wants to “attach” to. One of these service providers is actually ICSF, invoked via the CCA API. When hardware cryptography is not available on the system then the ICSF cryptographic provider fails. The IBM SDK also provides access for Java exploiters to the JCE (Java Cryptography Extension) to use the ICSF CCA services, which requires that Java cryptographic service providers have been properly specified.I Even with the Java hardware cryptography provider specified, some cryptographic services are still provided by software.

Hardware cryptography utilization and measurement in z/OS The hardware cryptography exploitation assessment in z/OS can be achieved using messages or trace information built in the exploiting application or middleware. In 2.2, “Assessing the use of hardware cryptography on z/OS” on page 47, we provide examples of such messages and traces as implemented in System SSL.

The primary tool for the measurement of hardware cryptography utilization on z/OS is the z/OS Resource Measurement Facility (RMF) product, which relies on data provided by the z/OS System Management Facility (SMF) and on hardware data provided by the CEX2C feature itself. The way RMF operates and how it can be used for measuring hardware cryptography activity is explained in 3.2, “SMF reporting of hardware cryptography activity” on page 66.

Alternatively, or in addition to using RMF, the hardware cryptography activity can be measured using the Tivoli OMEGAMON® XE on z/OS reporting product. We also provide an example of the use of OMEGAMON XE on z/OS at 4.1, “Tivoli OMEGAMON XE on z/OS - Cryptographic coprocessor support” on page 80.

Hardware cryptography exploitation on z/VSE The main use of hardware cryptography on z/VSE stemmed originally from the need to provide hardware assistance to the SSL/TLS protocol. To meet this objective, specific cryptographic services were developed to be used internally in z/VSE, and a decision was made to externalize these services as the set of APIs shown in Figure 2-2 on page 45.

Chapter 2. Hardware cryptography activity assessment on System z 43 Because of the initial intent of providing cryptographic support specifically for SSL/TLS, the z/VSE cryptographic APIs are hosted by the TCP/IP stack component. The z/VSE TCP/IP stack provides the cryptographic services and transparently invokes hardware cryptography when relevant and available.

Hardware cryptography using the CEX2C or CEX2A and CPACF devices is supported starting with TCP/IP for VSE V1.5 running on z/VSE V3.1.

RSA acceleration Note that z/VSE exploits the CEX2C or CEX2A for RSA acceleration only, that is, using clear keys for: RSA decryption or encryption operations during initiation of the SSL/TLS session RSA signature of certificates built by the z/VSE certificate utility.

CPACF exploitation The CPACF is used for SSL/TLS data transfer when one of the following symmetric algorithms has been agreed upon between the client and server: DES, Triple DES, or AES-128 (the latter on System z9 only).

The CPACF is also used when the SHA-1 algorithm has been selected for data integrity checking, both during data transfer or when building a certificate via the certificate utility.

Note: Whether or not hardware cryptography is used is transparent to the z/VSE TCP/IP applications: Whenever hardware cryptography cannot be used, the software implementation of the cryptographic services in the TCP/IP stack is used.

The use of hardware cryptography can be disabled via a setting in the so-called $SOCKOPT Phase for the TCP/IP stack.

44 System z Cryptographic Services and z/OS PKI Services Infrastructure The lowest-level hardware cryptography API provided in z/VSE is the CryptoVSE API, where applications or middlewares can call specific cryptographic services that are eventually performed by the CPACF or CEX2C (in coprocessor or accelerator mode) devices. See Figure 2-2.

z/VSE

TCP/IP Non SSL-enabled SSLD application

TCP/IP SSL SSL-enabled For VSE SSL application For API VSE Application CryptoVSE with cryptography

VSE Crypto Device driver

Clear RSA key only CEX2C CPACF domain

Figure 2-2 z/VSE Hardware cryptography infrastructure

The “SSL for VSE API (in Figure 2-2) is a higher-level API, similar to the z/OS System SSL API, intended to provide SSL-enabled applications with run-time support assistance to handle the SSL/TLS protocol. This API transparently invokes the CryptoVSE functions.

The SSL daemon (SSLD in Figure 2-2) is not an API per se but manages the SSL/TLS protocol on behalf of non SSL-enabled applications, much as z/OS AT-TLS (Application-Transparent TLS) does.

Hardware cryptography utilization and measurement in z/VSE z/VSE does not provide a measurement utility similar to z/OS RMF to report on hardware cryptography activity; however, you can obtain some statistical information, as described in 2.3, “Assessing the use of hardware cryptography on z/VSE” on page 58.

Chapter 2. Hardware cryptography activity assessment on System z 45 2.1.2 Hardware cryptography exploitation in Linux on System z

The hardware cryptography infrastructure for Linux on System z is shown in Figure 2-3.

Java Application Application Middleware/ Application (e.g. API API OpenSSl engine) IBMPKCS11Impl PKCS#11

API libica API z90crypt (device)

Crypto Express2 Coprocessor CPACF domain Figure 2-3 Linux on System z hardware cryptography infrastructure

There are globally three layers of APIs: At the lowest level, the z90crypt, or the more recently available zcrypt, device driver provides an API usually not exploited directly by applications but rather intended for intermediate software layers that in turn provide more sophisticated cryptographic functions to the next upper level of code. The libica Linux library is an intermediate cryptographic functions library that offers a wide range of cryptographic functions, some of them transparently performed by the hardware cryptographic devices under control of the device driver. As it stands today libica, in the majority of cases, is still not directly called by applications or middlewares, which instead rely on a higher-level cryptographic API such as the PKCS#11 API, or its Java version, the IBMPKCS11Impl cryptographic API.

Cryptography utilization and measurement in Linux on System z The hardware cryptography utilization assessment in Linux on System z can be achieved using messages or traces information issued by the exploiting application or middleware.

z90crypt or zcrypt also maintains operations counters that can be used for an assessment of hardware cryptography activity. These counters are described in 2.4, “Assessing the use of hardware cryptography on Linux on System z” on page 58.

46 System z Cryptographic Services and z/OS PKI Services 2.2 Assessing the use of hardware cryptography on z/OS

In this section we describe ways of assessing whether z/OS applications are actually calling the system hardware cryptography, as opposed to using the software implementation of the cryptographic services. The methods used to provide this assessment can differ; in this section, we discuss three methods: The first one consists in detecting whether actual attempts to access cryptographic resources have occurred by protecting them by profiles in RACF, namely profiles in the CSFSERV class. In our second example, we describe the exploitation of the tracing capabilities built in an application or middleware, here the System SSL component of z/OS. The third example is the exploitation of the ICSF component trace.

2.2.1 Detecting the use of RACF-protected cryptographic resources

ICSF services can be protected by RACF profiles in the CSFSERV class of profiles, as described in the , SA22-7521.

The idea here is to detect access attempts by applications to RACF-protected ICSF services. We assume that the user does not want to prevent the request from proceeding and is therefore looking for a warning message rather than hard-stopping the request with a RACF violation exception. We illustrate this approach with the following example. Note however that a real-life approach might differ from the one provided here; you might want rather, for example, to audit all accesses to specific ICSF services by specifying AUDIT(ALL) in the relevant profiles. Activation of the CSFSERV class of profiles: SETROPTS CLASSACT(CSFSERV) RACLIST(CSFSERV) GENERIC(CSFSERV) Create the RACF profile ** in the CSFSERV class, with no access by default and the WARNING attribute: RDEF CSFSERV ** UACC(NONE) WARNING Issue a REFRESH command to modify the “in-storage” RACF profile: SETROPTS RACLIST(CSFSERV) REFRESH To verify this installation, issue the following command: RLIST CSFSERV ** ALL

Chapter 2. Hardware cryptography activity assessment on System z 47 The response to this command should look like the example shown in Figure 2-4.

CLASS NAME ------CSFSERV ** (G)

LEVEL OWNER UNIVERSAL ACCESS YOUR ACCESS WARNING ------00 WELLIE2 NONE NONE YES

INSTALLATION DATA ------NONE

APPLICATION DATA ------NONE

SECLEVEL ------NO SECLEVEL

CATEGORIES ------NO CATEGORIES

SECLABEL ------NO SECLABEL

AUDITING ------FAILURES(READ)

NOTIFY ------NO USER TO BE NOTIFIED

CREATION DATE LAST REFERENCE DATE LAST CHANGE DATE (DAY) (YEAR) (DAY) (YEAR) (DAY) (YEAR) ------089 98 089 98 089 98

ALTER COUNT CONTROL COUNT UPDATE COUNT READ COUNT ------NOT APPLICABLE FOR GENERIC PROFILE

USER ACCESS ------WELLIE2 ALTER

Figure 2-4 Listing RACF profiles in the CSFSERV class

Once this setup has been finished, all users calling RACF-protected ICSF services, who are not permitted to this generic profile, trigger the RACF warning message shown in Figure 2-5.

ICH408I USER(MOP005 ) GROUP(SYS1 ) NAME(MOP USER CSFKGN CL(CSFSERV ) WARNING: INSUFFICIENT AUTHORITY - TEMPORARY ACCESS ALLOWED FROM ** (G) ACCESS INTENT(READ ) ACCESS ALLOWED(NONE )

Figure 2-5 RACF warning message

The name of the service called appears in the message (“CSFKGN”) along with the user ID who called the service (“MOP005”). Because of the WARNING attribute in the resource profile, RACF temporarily grants access to the protected ICSF service.

48 System z Cryptographic Services and z/OS PKI Services 2.2.2 z/OS System SSL example

Attention: It is very important that you inquire from your installation security officers whether running with RACF profiles in WARNING mode is acceptable to them. Already defined discrete profiles in the CSFSERV class take precedence over the generic profile we define in Figure 2-4 on page 48. Do not forget to suppress the WARNING attribute in the profile once you finish testing. You can do so by issuing the command RALTER CSFSERV ** NOWARNING. The ICSF services (CSNBSYE and CSNBSYD) that call the CPACF for encryption and decryption of data are not protected by RACF profiles and their invocation cannot be detected by this method.

In this section we provide an example of what an exploiter of hardware cryptography, namely z/OS System SSL, can provide as information to confirm and to assess the use of the System z hardware cryptographic facilities. Confirmation of hardware cryptography use is sometimes needed because System SSL also provides its own software implementation of the CCA cryptographic algorithms, and it might be unclear to the user which one of the two implementations is currently being used.

z/OS System SSL infrastructure The z/OS System SSL infrastructure is shown in Figure 2-6 on page 50. The System SSL-enabled application, for instance the z/OS HTTP server, calls the System SSL high-level API to trigger the complex actions required by the protocol, such as conducting the SSL handshakes and encrypting and decrypting data being exchanged with the partner application. These actions are then performed by the System SSL software. System SSL transparently requests, whenever appropriate and available, services from the hardware cryptographic coprocessors or accelerators to ICSF or calls directly the CPACF using the MSA instructions.

Chapter 2. Hardware cryptography activity assessment on System z 49

System SSL TCP/IP SSL Started Task Enabled GSKSRVR applications

System SSL DLLs

Handshake System SSL API calls Certificate validation recv() Encrypt/decrypt send() Network data

Hardware crypto Environment variables calls

ICSF CPACF

CEX2C/ CEX2A

Figure 2-6 z/OS System SSL infrastructure

System SSL also recognizes a set of environment variables that can be passed by the calling applications and that affect its behavior.

Finally, the so-called “SSL Started Task,” provides additional services, not required to support the SSL/TLS communication, but services that help manage the System SSL run-time environment, including providing information about the cryptographic facilities or taking component traces. The activation of the SSL Started Task is an option left to the user.

Further information about the z/OS System SSL environment variables and the SSL Started Task can be found in , SC24-5901.

50 System z Cryptographic Services and z/OS PKI Services Querying the available cryptographic services The optional SSL Started Task element of System SSL can provide information about the cryptographic services that is sensed as being offered by the system. The z/OS console command MODIFY GSKSRVR,D CRYPTO invokes the SSL Started Task to query the cryptographic configuration and to provide a status as shown in Figure 2-7.

F GSKSRVR,D CRYPTO

GSK01009I Cryptographic status 464 Algorithm Hardware Software DES 56 56 3DES 168 168 AES 128 256 RC2 -- 128 RC4 -- 128 RSA Encrypt 2048 4096 RSA Sign 2048 4096 DSS -- 1024 SHA-1 160 160 SHA-256 256 256

Figure 2-7 Display Crypto by the SSL Started Task.

The right column indicates which cryptographic algorithms System SSL can provide by software implementation. The center column shows the hardware cryptographic support on the system as it is sensed by the SSL Started Task and that System SSL is able to exploit.

Note: The display shown in Figure 2-4 does not constitute in itself evidence of the use of hardware cryptography, but at least it shows that hardware cryptographic services are available in the system.

Getting informative messages on the use of hardware cryptography Among the set of environment variables that System SSL recognizes, the GSK_SSL_HW_DETECT_MESSAGE variable, when it has been exported with a value of “1” by the calling application, makes system SSL issue explicit messages about the hardware cryptography configuration it recognizes during its initialization. These messages can be retrieved in the application’s STDERR file, as shown in Figure 2-8.

...... This is IBM HTTP Server V5R3M0 ...... Built on Jan 19 2007 at 14:59:51

System SSL: SHA-1 crypto assist is available System SSL: SHA-256 crypto assist is available System SSL: DES crypto assist is available System SSL: DES3 crypto assist is available System SSL: AES 128-bit crypto assist is available System SSL: AES 256-bit crypto assist is not available System SSL: ICSF FMID is HCR7731 System SSL: PCI cryptographic accelerator is available System SSL: PCIX cryptographic coprocessor is available System SSL: Public key hardware support is available

Figure 2-8 System SSL reported cryptographic configuration

Chapter 2. Hardware cryptography activity assessment on System z 51 System SSL has been called in Figure 2-4 on page 48 by the z/OS HTTP server, which can pass the GSK_SSL_HW_DETECT_MESSAGE environment variable value in one of two ways: By editing the HTTP server started task procedure to add: LEPARM='ENVAR("GSK_SSL_HW_DETECT_MESSAGE=1")' By adding the line in the httpd.envvar file: GSK_SSL_HW_DETECT_MESSAGE=1

Switching from hardware to software cryptography The decision as to whether to utilize hardware or software is made internally by System SSL. If a problem is encountered when using hardware cryptography, System SSL switches off hardware support for that particular function and falls back to its software implementation. Prior to z/OS V1.9 this process was transparent to the user, and an analysis of System SSL traces was needed to detect this event.

As of z/OS V1.9 System SSL provides a notification, if the SSL Started Task is active, that such a switch occurred with the message GSK01052W displayed at the system console as shown in Figure 2-9. (In this case, this message has been obtained by stopping ICSF while System SSL was using the hardware cryptography.

GSK01051E HTTPSRV/00B7 Hardware encryption error. ICSF hardware encryption processing is unavailable. GSK01052W HTTPSRV/00B7 Hardware encryption error. PKE encryption processing switched to software.

Figure 2-9 System SSL Notification of fallback to software encryption.

This new notification is intended to help quickly identify conditions that led to a burst in CPU activity - conditions such as switching to software cryptography.

Tracing System SSL calls to the hardware cryptographic devices System SSL offers two tracing options that show calls to ICSF or direct invocation of the CPACF. These options are: A “simple” System SSL trace that is controlled using the environment variables GSK_TRACE_FILE and GSK_TRACE. A System SSL component trace, which requires having the SSL Started Task active prior to starting the trace.

System SSL trace Experience shows that the first option listed previously, “simple” trace, usually provides sufficient information to pinpoint which hardware cryptographic services are actually being used. The trace excerpt shown in Example 2-1 on page 53 indicates which hardware cryptographic services and devices are sensed. Then another piece of the trace, also shown in Example 2-1 on page 53, clearly indicates the use of CPACF (“Clear key DES3 decryption performed”) and of the cryptographic coprocessor (“Hardware RSA private key decryption performed”). Likewise software encryption is clearly indicated should the hardware cryptographic services not be used by System SSL.

52 System z Cryptographic Services and z/OS PKI Services Example 2-1 System SSL trace 04/04/2007-12:14:35 Thd-0 INFO gsk_svc_init(): System SSL Version 3, Release 18, Service level OA18836 04/04/2007-12:14:35 Thd-0 INFO gsk_svc_init(): LE runtime level 0x41080000, 31-bit addressing mode 04/04/2007-12:14:35 Thd-0 INFO gsk_svc_init(): STDOUT handle=-1, STDERR handle=-1, TRACE handle=4 04/04/2007-12:14:35 Thd-0 INFO gsk_dll_init_once(): Using variant character table for code set IBM-1047 04/04/2007-12:14:35 Thd-0 INFO gsk_dll_init_once(): Using local code page IBM-1047 04/04/2007-12:14:35 Thd-0 INFO gsk_dll_init_once(): Using ISO8859-1 for TELETEX string 04/04/2007-12:14:35 Thd-0 INFO gsk_dll_init_once(): 64-bit encryption enabled 04/04/2007-12:14:35 Thd-0 INFO gsk_dll_init_once(): 128-bit encryption enabled 04/04/2007-12:14:35 Thd-0 INFO gsk_dll_init_once(): 168-bit encryption enabled 04/04/2007-12:14:35 Thd-0 INFO gsk_dll_init_once(): 256-bit encryption enabled 04/04/2007-12:14:35 Thd-0 INFO crypto_init(): SHA-1 crypto assist is available 04/04/2007-12:14:35 Thd-0 INFO crypto_init(): SHA-256 crypto assist is available 04/04/2007-12:14:35 Thd-0 INFO crypto_init(): DES crypto assist is available 04/04/2007-12:14:35 Thd-0 INFO crypto_init(): DES3 crypto assist is available 04/04/2007-12:14:35 Thd-0 INFO crypto_init(): AES 128-bit crypto assist is available 04/04/2007-12:14:35 Thd-0 INFO crypto_init(): AES 256-bit crypto assist is not available 04/04/2007-12:14:35 Thd-0 INFO crypto_init(): ICSF FMID is HCR7731 04/04/2007-12:14:35 Thd-0 INFO crypto_init(): PCI cryptographic accelerator is available 04/04/2007-12:14:35 Thd-0 INFO crypto_init(): PCIX cryptographic coprocessor is available 04/04/2007-12:14:35 Thd-0 INFO crypto_init(): Public key hardware support is available 04/04/2007-12:14:35 Thd-0 INFO crypto_init(): Maximum sign key size 2048, Maximum management key size 2048 04/04/2007-12:14:35 Thd-0 INFO crypto_init(): Maximum RSA token size 2500 04/04/2007-12:14:35 Thd-0 INFO gsk_dll_init_once(): Job name HTTPSRV, Process 0100034D ...... 04/04/2007-12:14:35 Thd-0 ENTRY gsk_open_keyring(): ---> Keyring webring 04/04/2007-12:14:35 Thd-0 INFO gsk_open_keyring(): Identifier 1 assigned to 'WebSphereCA' 04/04/2007-12:14:35 Thd-0 ENTRY gsk_decode_certificate(): ---> 04/04/2007-12:14:35 Thd-0 ASCII gsk_decode_certificate(): Encoded X.509 certificate 00000000: 30820289 308201f2 a0030201 02020100 *0...0...... * ...... 04/04/2007-12:14:35 Thd-0 EXIT gsk_generate_random_bytes(): <--- Exit status 0x00000000 (0) 04/04/2007-12:14:35 Thd-0 INFO crypto_des_encrypt(): Clear key DES encryption performed for 640 bytes ....

04/04/2007-12:15:23 Thd-16 INFO gsk_secure_socket_init(): SSL V2 cipher specs: 713624 04/04/2007-12:15:23 Thd-16 INFO gsk_secure_socket_init(): SSL V3 cipher specs: 0A0504090306

Chapter 2. Hardware cryptography activity assessment on System z 53 04/04/2007-12:15:23 Thd-16 INFO default_setsocketoptions(): TCP_NODELAY set for socket 12

04/04/2007-12:15:23 Thd-16 INFO crypto_des_decrypt(): Clear key DES decryption performed for 640 bytes

04/04/2007-12:15:23 Thd-16 EXIT gsk_get_record_by_label(): <--- Exit status 0x00000000 (0) ...... 04/04/2007-12:15:23 Thd-16 INFO crypto_rsa_private_decrypt(): Using PKCS private key 04/04/2007-12:15:23 Thd-16 INFO crypto_rsa_private_decrypt(): RSA modulus is 1024 bits 04/04/2007-12:15:23 Thd-16 INFO crypto_rsa_private_decrypt(): Generating external CRT key token 04/04/2007-12:15:23 Thd-16 INFO crypto_rsa_private_decrypt(): Hardware RSA private key decryption performed ...... 04/04/2007-12:15:23 Thd-16 INFO crypto_des3_decrypt_ctx(): Clear key DES3 decryption performed for 64 bytes

04/04/2007-12:15:23 Thd-16 INFO crypto_des3_encrypt_ctx(): Clear key DES3 encryption performed for 240 bytes 04/04/2007-12:15:23 Thd-16 INFO gsk_write_v3_record(): Calling write routine for 245 bytes 04/04/2007-12:15:23 Thd-16 INFO gsk_write_v3_record(): 245 bytes written ...... 04/04/2007-12:15:23 Thd-16 INFO crypto_des3_decrypt_ctx(): Clear key DES3 decryption performed for 464 bytes

Attention: Selected hardware cryptographic functions can be disabled in System SSL by setting the appropriate bits to zero in the GSK_HW_CRYPTO environment variable value, as per the following bit position assignments: 1 = SHA-1 digest generation 2 = 56-bit DES encryption/decryption 4 = 168-bit Triple DES encryption/decryption 8 = Public key encryption/decryption 16 = AES 128-bit encryption/decryption 32 = SHA-256 digest generation

The corresponding software algorithms will be used when a hardware function is disabled. This is reflected in the System SSL trace as follows: Thd-0 INFO crypto_des_encrypt(): Clear key DES encryption performed for 640 bytes

becomes, when DES has been disabled using GSK_HW_CRYPTO: Thd-0 INFO crypto_des_encrypt(): Software DES encryption performed for 640 bytes

System SSL component trace The System SSL started task provides component trace support for any SSL thread that applications running on the same system as the GSKSRVR started task have started. The trace records can be written to a trace external writer, or they can be kept in an in-storage trace buffer that is part of the GSKSRVR address space. Interactive Problem Control System

54 System z Cryptographic Services and z/OS PKI Services (IPCS) is used to format and display the trace records from either a trace data set or an SVC dump of the GSKSRVR address space.

The System SSL component trace produces outputs such as shown in Figure 2-10.

SC60 MESSAGE 00000002 15:36:19.236028 SSL_EXIT

Job HTTPSRV Process 02000CA0 Thread 00000000 crypto_generate_random_bytes Exit status 00000000 (0)

SC60 MESSAGE 00000008 15:36:19.236104 SSL_INFO

Job HTTPSRV Process 02000CA0 Thread 00000000 crypto_des_encrypt Clear key DES encryption performed for 640 bytes

SC60 MESSAGE 00000008 15:36:19.236373 SSL_INFO

Job HTTPSRV Process 02000CA0 Thread 00000000 gsk_open_keyring Identifier 3 assigned to 'pssc pki ca'

SC60 MESSAGE 00000001 15:36:19.236476 SSL_ENTRY

Job HTTPSRV Process 02000CA0 Thread 00000000 gsk_decode_certificate

Figure 2-10 System SSL component trace

Measuring hardware cryptography activity with z/OS System SSL z/OS System SSL does not provide measurement data per se regarding the use of the System z hardware cryptography. As with the other exploiters of hardware cryptography, the user has to rely on additional performance-reporting products, such as IBM RMF or IBM Tivoli OMEGAMON XE on z/OS, to get measurements data. Figure 2-11 on page 56 is a high-level description of the measurement data-collection infrastructure as built around RMF. The way RMF operates for data collection and how it is used is further developed in 3.3, “Using RMF to measure the z/OS hardware cryptography activity” on page 68.

Chapter 2. Hardware cryptography activity assessment on System z 55

Important: No z/OS-based measurement capability is available today that can provide utilization data for the CPACF, if not built-in the application itself. Because this facility is

actually a part of the system processing unit, the additional machine cycles induced by the CPACF activity are simply reported as CPU utilization by RMF or equivalent products. For example, the only activity reported as hardware cryptography activity in Figure 2-11 is the RSA functions performed by the CEX2C in coprocessor or accelerator mode.

Application

System SSL

RSA DES, T-DES, AES128 RMF ICSF SHA-1, SHA-256 counters

CEX2C CPACF CEX2A

Figure 2-11 Collection of hardware cryptography measurement data with System SSL.

2.2.3 The ICSF component trace

ICSF offers a system component trace capability, which is described in ICSF System Programmer's Guide, SA22-7520.Among other data IPCS can extract counters from the ICSF

56 System z Cryptographic Services and z/OS PKI Services component trace indicating what ICSF services have been called, how many times during tracing, how many failed. This is shown in Figure 2-12.

COMPONENT TRACE SHORT FORMAT COMP(CSF) OPTIONS((COUNTS)) ICSF COUNTS FROM CTRACE: SERVICE CALLS_FOUND = 00000185 FAILING SERVICES = 00000055 SERVICE #SUCCESS #FAILED CSFS1TRL 00000017 00000055 CSFN1GKP 00000007 00000000 CSFS1GAV 00000028 00000000 CSFS1TRD 00000014 00000000 CSFNPKI 00000005 00000000 CSFNDSG 00000005 00000000 CSFNDSV 00000005 00000000 CSFNPKD 00000042 00000000 CSFNIQF 00000007 00000000

Figure 2-12 ICSF component trace.

Chapter 2. Hardware cryptography activity assessment on System z 57 2.3 Assessing the use of hardware cryptography on z/VSE

z/VSE does not offer a performance-reporting facility such as the z/OS RMF; however, it can provide statistical information about the use of hardware cryptography by using the STATUS=CR command of the VSE Security Server. An example of the command output is shown in Figure 2-13; it contains information about the total number of APs (adjunct processors) requests executed, the type of the cryptographic coprocessor actually available, and its status. It also shows which algorithms are supported by the CPACF on the system.

MSG FB,DATA=STATUS=CR AR 0015 1I40I READY FB 0011 BST223I CURRENT STATUS OF THE SECURITY TRANSACTION SERVER: FB 0011 ADJUNCT PROCESSOR CRYPTO SUBTASK STATUS: FB 0011 AP CRYPTO SUBTASK STARTED ...... : YES FB 0011 MAX REQUEST QUEUE SIZE ...... : 1 FB 0011 MAX PENDING QUEUE SIZE ...... : 1 FB 0011 TOTAL NO. OF AP REQUESTS ...... : 16 FB 0011 NO. OF POSTED CALLERS ...... : 16 FB 0011 AP CRYPTO POLLING TIME (1/300 SEC).. : 1 FB 0011 AP CRYPTO WAIT ON BUSY (1/300 SEC).. : 75 FB 0011 AP CRYPTO RETRY COUNT ...... : 5 FB 0011 AP CRYPTO TRACE LEVEL ...... : 3 FB 0011 TOTAL NO. OF WAITS ON BUSY ...... : 0 FB 0011 CURRENT REQUEST QUEUE SIZE ...... : 0 FB 0011 CURRENT PENDING QUEUE SIZE ...... : 0 FB 0011 ASSIGNED APS : PCICC / PCICA ...... : 0 / 0 FB 0011 CEX2C / CEX2A ...... : 2 / 0 FB 0011 PCIXCC ...... : 0 FB 0011 AP 0 : CEX2C - ONLINE FB 0011 AP 1 : CEX2C - ONLINE FB 0011 ASSIGNED AP QUEUE (CRYPTO DOMAIN)... : 4 FB 0011 CPU CRYPTOGRAPHIC ASSIST FEATURE: FB 0011 CPACF AVAILABLE ...... : YES FB 0011 INSTALLED CPACF FUNCTIONS: FB 0011 DES, TDES-128, TDES-192 FB 0011 AES-128 FB 0011 SHA-1, SHA-256 FB 0011 END OF CPACF STATUS

Figure 2-13 The z/VSE Security Server STATUS command

2.4 Assessing the use of hardware cryptography on Linux on System z

The two ways of establishing evidence of a hardware cryptography exploitation by applications that execute in Linux on System z are: By analyzing the status of the z90crypt device driver that executes inside the Linux on System z instance. We discuss this topic in this section. By exploiting the RMF reporting in a z/OS logical partition located in the same physical machine as the Linux on System z logical partition. This topic is discussed in 3.4.3, “Crypto Hardware Activity report without local activity” on page 75.

58 System z Cryptographic Services and z/OS PKI Services

Important: As shown in this section, Linux provides ways of retrieving statistical information about the use of cryptographic coprocessors or accelerators. Linux has no

facility for tracking and assessing the use of the CPACF. Such tracking has to be provided by the exploiting application.

2.4.1 Status of the z90crypt device driver

The z90crypt device driver goal is to route the application cryptographic workload to the supported cryptographic hardware devices installed in the machine.

As a first step, you may want to insure that the device driver is installed. You can checked by issuing the command lsmod, which displays the list of the module loaded in the kernel as shown in Figure 2-14. We can see in the figure that the z90crypt device driver is present.

vpnsrv:~ # lsmod Module Size Used by sha1_z990 20224 0 des_z990 21760 0 des_check_key 18944 1 des_z990 sg 68936 0 st 68920 0 sd_mod 43272 0 sr_mod 39980 0 scsi_mod 206712 4 sg,st,sd_mod,sr_mod cdrom 65320 1 sr_mod ipv6 426664 136 tun 29184 1 qeth 243904 0 qdio 75088 3 qeth ccwgroup 27648 1 qeth z90crypt 77992 2 dm_mod 100120 0 dasd_eckd_mod 89344 4 dasd_mod 103528 5 dasd_eckd_mod ext3 184512 1 jbd 118856 1 ext3

Figure 2-14 lsmod command output

Further information about setting up and testing the hardware cryptography with Linux on System z can be found in the Redpaper Using Cryptographic Adapters for Web Servers with Linux on IBM System z9 and zSeries. REDP-4131.

Chapter 2. Hardware cryptography activity assessment on System z 59 2.4.2 Collecting information about hardware cryptography activity

The Command cat /proc/driver/z90crypt is used to collect information about the device driver status, as shown in Figure 2-15. Note that the status we show in the figure has been collected on a Linux system executing in a logical partition or in a VM guest running on a z990 system. The Linux VM guest machine has access to two PCICA (PCI Cryptographic Accelerator) coprocessors.

vpnsrv:~ # cat /proc/driver/z90crypt

z90crypt version: 1.3.3 Cryptographic domain: 2 Total device count: 2 PCICA count: 2 PCICC count: 0 PCIXCC MCL2 count: 0 PCIXCC MCL3 count: 0 CEX2C count: 0 CEX2A count: 0 requestq count: 0 pendingq count: 0 Total open handles: 2

Online devices: 1=PCICA 2=PCICC 3=PCIXCC(MCL2) 4=PCIXCC(MCL3) 5=CEX2C 6=CEX2A 1100000000000000 0000000000000000 0000000000000000 0000000000000000

Waiting work element counts 0000000000000000 0000000000000000 0000000000000000 0000000000000000

Per-device successfully completed request counts 0000040E 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000

Figure 2-15 z90crypt device driver status

The information displayed in Figure 2-15 comprises four parts: General Information Online devices Waiting work elements counts Per-device count of successfully completed requests

To find evidence of hardware cryptography activity, the following should be checked: In the general information section: The “total device count” indicates how many cryptographic hardware devices are detected online in Linux, and therefore potentially available for applications requesting RSA cryptographic services. The general information also comprises other information such as the device driver version number and the cryptographic domain the Linux applications have access to. In the “online devices” section: This section reports the physical arrangement in the system of the detected cryptographic coprocessors. Each hexadecimal digit position is the adjunct processor number in the system. A maximum of 16 cryptographic devices, or adjunct processors, can be detected among 64 possible adjunct processors positions. When the digit has a value of zero, no device is detected for the adjunct processor number. When not zero, the digit value

60 System z Cryptographic Services and z/OS PKI Services indicates which type of cryptographic device is occupying the adjunct processor position as per the following values: –1=PCICA –2=PCICC – 3=PCIXCC(Machine Level Code 2) – 4=PCIXCC(Machine Level Code 3) – 5=CEX2C – 6=CEX2A Looking at Figure 2-15 on page 60, we therefore conclude that this Linux system instance has detected two PCICA online devices as AP0 and 1. in the “waiting work element counts” section This section reports the number of outstanding units of work for each detected adjunct processor at the time of execution of the cat command. In the “per-device successfully completed request counts” section This last part of the status reports the hardware cryptography successful activity for each adjunct processor which adjunct processor has been detected online. Each device has an eight hexadecimal digit count that represents the cumulative count of work units successfully performed by the device. A count equal to “00000000” can indicate either – The hardware cryptographic coprocessor has not been invoked because no application is requesting cryptographic services, or the applications are requesting services that are not provided by the coprocessor or accelerator. – All requests to the AP have been failing. In the example in Figure 2-15 on page 60, the first online device has successfully performed hexadecimal 40E units of work. Because the count for the second online device is zero, we can conclude that there is no activity or all requests have failed for AP 1.

2.4.3 Programs that invoke hardware cryptography

The programs that invoke hardware cryptography can be retrieved using the lsof command. The command lists open files and which program opened them (remember that almost everything is considered to be a file in Linux). In Figure 2-16, we list which programs opened the z90crypt device driver.

vpnsrv:~ # lsof |grep z90 openvpn 581 nobody 6u CHR 10,62 285122 /dev/z90crypt sshd 12737 root 3u CHR 10,62 285122 /dev/z90crypt sshd 12740 guigui 3u CHR 10,62 285122 /dev/z90crypt

Figure 2-16 Programs that opened the z90crypt device driver

2.5 Setting up hardware cryptography configuration of z/VM

In z/VM real cryptographic coprocessors are assigned to guest virtual machines by specifying the CRYPTO parameter in the VM guest machine directory with the DOMAIN and APDEDICATED or the APVIRTUAL operands. Refer to “z/VM V5R3.0 CP Planning

Chapter 2. Hardware cryptography activity assessment on System z 61 and Administration, SC24-6083, for further explanation of using these parameters.APDEDICATED This operand specifies the numbers of the APs the virtual machine may use for dedicated access to the adjunct processor (AP) cryptographic facility. The DOMAIN operand also must be specified to indicate the coprocessor domain to access in the APs. The AP queues equivalent to the domains specified by all of the DOMAIN operands are assigned to the guest for each AP specified on the APDEDICATED operand on all CRYPTO statements. The APs specified must be selected from the set of APs selected on the PCI Cryptographic Online list on the Crypto Image Profile Page for the z/VM logical partition, or from the candidate list provided that the APs have been brought online to the z/VM logical partition. The DOMAINs specified must be part of the set of domains selected in the Usage Domain Index list in the Crypto Image Profile Page for the logical partition APVIRTUAL This operand tells the z/VM Control Program that this virtual machine may share access with other virtual machines to the clear key functions only of the adjunct processor (AP) cryptographic facility. In that case z/VM will drive the requests to whatever coprocessor is available, and it is not necessary to specify the DOMAIN operand when specifying the APVIRTUAL operand because z/VM will reject all requests for services that would involve the use of secure keys.

Figure 2-17 is an example of a VM guest machine setup, where the z/VM system logical partition has access to APs 5 and 6 in coprocessor mode and AP 2 in accelerator mode. The z/OS VM guest machine’s directory has been set up to specify dedicated access to domain 1 of AP 5 and 6, and the Linux VM guest machines are sharing access to whatever accelerator is available to the z/VM system.

No setup is required to share the CPACF because the facility is available to any guest program dispatched on the PU.

Guest Directory CRYPTO APVIRT

z/OS guest Linux guest Linux guest

Guest Directory Guest Directory CRYPTO DOMAIN 1 CRYPTO APVIRT APDED 5 6 ICSF libica libica z90crypt z90crypt

Domain 2 Domain 2

Dedicated Shared queue CP queue LPAR CP

Image profile Linux libica Usage domain 1,2 + APs 2,5,6 in online/candidate lists Domain 1 Domain 2 CEX2A AP2 Domain Domain 1 2 CPACF 16 domain queues RSA clear key operations only CEX2C Crypto engines DES, T-DES, AES128, SHA-1 Crypto engines AP 5 and 6 SHA-256 Secure key operations Figure 2-17 Hardware cryptographic coprocessors assignment to VM guest machines

62 System z Cryptographic Services and z/OS PKI Services 2.5.1 Checking the hardware cryptography configuration with z/VM

z/VM has no facility to monitor hardware cryptography activity; however, configuration information related to the physical or virtual hardware cryptographic devices can be obtained. Again this does not provide cryptographic activity information but at least shows which VM guests are entitled to use hardware cryptographic coprocessors.

Physical hardware cryptographic devices The CEX2C status appears as an output of the z/VM CP QUERY CRYPTO command that can be used to display the z/VM crypto system configuration.

Using the z/VM CP QUERY CRYPTO command The CP QUERY CRYPTO command can be used to query for the cryptographic coprocessors physical configuration. An example is shown in Figure 2-18 where one PCICA accelerator feature has been detected.

. q crypto Crypto Adjunct Processor Instructions are installed

q crypto ap AP 00 PCICA Queue 11 is installed AP 01 PCICA Queue 11 is installed AP 02 PCIXCC Queue 11 is dedicated to LNXSU2

Figure 2-18 z/VM query crypto command

The output shown in Figure 2-15 on page 60 of the QUERY CRYPTO command indicates that the z/VM system has access to three cryptographic coprocessors (again, in this example, we have issued the command on a z990 system, with PCICA and PCIXCC features installed). Each coprocessor has domain 11 assigned to handle the requests coming from the logical partition where the z/VM instance resides.

Using the z/VM QUERY VIRTUAL CRYPTO command You can use the QUERY VIRTUAL CRYPTO command to display which virtual coprocessors are actually available to a guest machine, as shown in Figure 2-19.

q v crypto No CAM or DAC Crypto Facilities defined AP 06 PCICA Queue 00 dedicated AP 06 PCICA Queue 01 dedicated AP 06 PCICA Queue 10 dedicated AP 12 PCIXCC Queue 00 dedicated AP 12 PCIXCC Queue 01 dedicated AP 12 PCIXCC Queue 10 dedicated

Figure 2-19 The QUERY VIRTUAL CRYPTO command

Chapter 2. Hardware cryptography activity assessment on System z 63

64 System z Cryptographic Services and z/OS PKI Services

Chapter 3. Measuring hardware cryptography activity on z/OS with RMF

This chapter provides an overview of how the IBM Resource Measurement Facility (RMF) program can be used to measure the hardware cryptography activity in a z/OS system. It addresses the way the product operates and shows the reporting data that can be issued and how it can be interpreted.

The chapter also provides an introduction to how the ICSF workload is balanced, and it discusses the SMF records used to report hardware cryptography activity.

Note: Workload balancing of the cryptographic services requests is performed by ICSF itself. z/OS Workload Manager (WLM) does not perform any direct load balancing or prioritization of requests arriving at ICSF.

When operating in a logical partition, an ICSF instance is given access to a unique domain that belongs to as many coprocessors as specified online to the logical partition.

For each coprocessor (actually the domain in the coprocessor) that ICSF can access, ICSF can initiate an architecturally fixed maximum number N of requests to the coprocessor to be executed concurrently. ICSF maintains a structure in storage for each coprocessor that tracks of these N requests. If more requests come in to ICSF than can be initiated in the collection of coprocessors - that is, the number of requests exceeds the N number for each accessible coprocessor - ICSF queues that work behind one of these coprocessors based on a workload-balancing scheme.

Note: N today equals 8 - that is, the structure has 8 entries. It has not been always this way, and the value of N may again change in the future to better adapt to new cryptographic coprocessor technologies. We refer in this book either to “N” or “8”, depending on the context.

The coprocessor workload balancing scheme is essentially as follows: When a new request comes into ICSF, ICSF starts scanning the coprocessor structures, always beginning with the lowest-numbered coprocessor (the AP number) to find the processor that is least used. If it can drive this work out to the coprocessor, because less than N requests are out on that coprocessor, it does so; if not, it queues the work to be eventually executed on that coprocessor. Once queued behind one coprocessor, the request is not moved to any other coprocessor that happens to become available in the meanwhile. When the number of requests on a coprocessor drops below the architectural limit of N, queued requests to this coprocessor are dequeued and sent to the coprocessor. The consequence of this design is that the workload is usually not evenly distributed across available coprocessors. When the workload is light, for example, almost all work is directed only to the lowest-numbered coprocessor because its structure usually is found empty when new work comes into ICSF.

3.2 SMF reporting of hardware cryptography activity

The System Management Facility (SMF) records described in the following sections report on hardware cryptography activity in z/OS. Further details on these SMF records and how to collect them can be found in z/OS V1R9.0 MVS System Management Facilities (SMF), SA22-7630.

Type 82 (ICSF record) This SMF record is mainly used to report ICSF administrative and environmental events, except for subtypes 17, 19, and 20, which are intended to provide performance data. The following record subtypes are written whenever: Subtype 1 - ICSF is started. Subtype 3 - The number of available processors with the cryptographic feature changes.

66 System z Cryptographic Services and z/OS PKI Services Subtype 4 - ICSF handles error conditions for cryptographic feature failure (CC3, Reason Code 1) or cryptographic tampering (CC3 Reason Code 3). Subtype 5 - A change to Special Secure Mode is detected. Subtype 6 and 7 - A key part is entered via the key entry unit (KEU). Subtype 8 - The in-storage copy of the CKDS is refreshed.

Subtype 9 - The CKDS is updated by a dynamic CKDS update service. Subtype 10 - A clear key part is entered for one of the PKA master keys. Subtype 11 - A clear key part is entered for the DES master key. Subtype 12 - Calls to the CSFSPKSC service by TKE are requested and replied to. Subtype 13 - PKDS is updated by a dynamic PKDS update service. Subtype 14 - A clear key part is entered for any of the PCICC master keys. Subtype 15 - A PCICC-retained key is created or deleted. Subtype 16 - Calls to the CSFPCI service (PCI interface) by TKE are requested or replied to. Subtype 17 - This subtype is written periodically to provide an indication of PCICC usage. Subtype 18 - A PCICC, PCIXCC, CEX2C, or CEX2A comes online or offline. Subtype 19 - A PCIXCC operation begins or ends. Subtype 20 - This subtype is written by ICSF to record processing times for PCIXCCs and CEX2Cs. Subtype 21 - ICSF issues IXCJOIN to join the ICSF sysplex group or issues IXCLEAVE to leave the sysplex group. Subtype 22 - The Trusted Block Create callable services are invoked.

Note: A sample job is supplied in z/OS to format the ICSF type 82 SMF records, which gives a report of ICSF activity. The job is available in SYS1.SAMPLIB (CSFSMFJ) and invokes a REXX™ exec SYS1.SAMPLIB(CSFSMFR). The document IBM eServer zSeries 990 (z990) Cryptography Implementation, SG24-7070, provides examples of these utilities.

Type 70 - subtype 2 (RMF Processor Activity) This record contains measurement data for cryptographic coprocessors and accelerators located in the following sections: The Cryptographic Coprocessor Data section, which contains measurement data for cryptographic coprocessors, as provided by the CEX2C features for the coprocessors they contain. The Cryptographic Accelerator Data section, which contains measurement data for cryptographic accelerators, as provided by the CEX2C features for the coprocessors in accelerator mode that they contain. The ICSF Services Data section, which contains measurement data for the set of Integrated Cryptographic Service Facility (ICSF) services that have been selected, by ICSF design, to be reported by RMF.

This record is written for each measurement interval and when the session terminates.

Type 30 (Common Address Space Work) This record contains the field SMF30CSC, which is described as the “Integrated Cryptographic Service Facility/MVS (ICSF/MVS) service count.” This count is the number of cryptographic instructions executed on behalf of the caller: Each time ICSF issues a command to a hardware coprocessor, this count is incremented by one. However, in some cases, such as bulk encryption of data, the count is incremented several times because ICSF may loop on commands being issued to the coprocessor even though it is performing a single service call at the ICSF API level. For other operations, like PIN verification, the count is incremented by one for a single service call to ICSF. Therefore the correlation between the

Chapter 3. Measuring hardware cryptography activity on z/OS with RMF 67 “number of cryptographic instructions” and the actual number of service calls to ICSF can be misleading.

Type 72 - Subtype 3 (Workload Activity) Two fields are used to track, by sampling, the status of tasks waiting to get access to an available hardware cryptographic coprocessor (or adjunct processor): R723APUAP, which is the count of “crypto using” samples - that is, a TCB was found executing on a cryptographic coprocessor. R723APD, which is the count of “AP crypto delay samples,” - that is, a TCB was found waiting for a cryptographic coprocessor.

These counters directly reflect, on a sampling basis, the number of the requests being queued by ICSF because they exceed the N limit previously explained in 3.1, “Overview of ICSF cryptographic workload balancing” on page 66, and the number of requests that are currently being executed by the coprocessor. These counters are further discussed in 3.4.4, “Workload Activity report” on page 75.

3.3 Using RMF to measure the z/OS hardware cryptography activity

The Resource Measurement Facility (RMF) is the IBM strategic product for z/OS performance measurement and management. It collects performance data for z/OS base and sysplex environments and issues reports that can be used to monitor systems’ performance. Thus RMF enables users to optimally tune and configure their systems to meet their business needs.

The hardware cryptographic coprocessors are among the resources for which RMF provides activity and performance data.

Refer to z/OS RMF Programmer’s Guide, SC33-7994, z/OS V1R9.0 RMF User’s Guide, SC33-7990, and z/OS V1R9.0 RMF Report Analysis, SC33-7991, for additional information.

Note: The RMF Spreadsheet Reporter tool version 5.2.3 for Windows® is a tool that complements RMF and is available for download from the IBM Web site. However, as of the writing of this book, it does not support the cryptographic hardware feature performance analysis.

68 System z Cryptographic Services and z/OS PKI Services 3.3.1 RMF data collection infrastructure for hardware cryptography

The data-collection infrastructure is shown in Figure 3-1.

Logical Partition x

Type 82

CEX2C feature ICSF Type 30 2 coprocessor Services invocations Waiting and executing CEX2A Measurement RMF 1 block CEX2C 3 Type 70-2, 72-3

coprocessor SMF

RMF PP

report Figure 3-1 RMF data-collection infrastructure

The RMF data-collection infrastructure is described in the following text (the numbers in Figure 3-1 correspond to the numbers that precede each list item): 1. The CEX2C feature maintains hardware counters that count the requests arriving at the CEX2C or CEX2A coprocessors, regardless of the domains these requests pertain to. The hardware counters also count the elapsed time it takes to complete these requests. RMF collects the value of these counters through z/OS architecture-defined control blocks.

Important: The recorded requests are being differentiated in requests going to a CEX2C (coprocessor) or going to a CEX2A (accelerator) and the length of the RSA key. However, no differentiation is made on which domains these requests are being issued for; therefore, RMF may collect data on hardware cryptography activities that have been initiated by other logical partitions in the system.

2. ICSF maintains its own software counters, pertaining to a set of services intentionally designed to be reported in RMF reports and provides the data to RMF (see “ICSF callable services activities reported to RMF” on page 70).

3. RMF, in turn, requests SMF to wrap the collected data into type 70 and 72 records. All SMF records are eventually processed by the RMF post-processor to issue reports.

Chapter 3. Measuring hardware cryptography activity on z/OS with RMF 69 ICSF callable services activities reported to RMF ICSF reports activities for: Encipher and decipher - that is, DES, Double-DES, or Triple-DES encryption and decryption performed with secure keys - that is performed in the CEX2C. MAC Generate and MAC Verify (still performed by the CEX2C) One-Way Hash SHA-1 and SHA-256, as performed by the CEX2C (SHA-1) or the CPACF (SHA-1 or SHA-256). PIN Translate and PIN Verify, as performed by the CEX2C.

Important: SHA-1 and SHA-256 are the only CPACF activities that are explicitly reported by RMF. To be reported, they should be invoked using the CSNBOWH (One-Way-Hash) service (they are not reported if directly invoked by the application using MSA instructions).

No other CPACF activities are reported, even those invoked by the CSNBYE or CSNBYD (Symmetric Key Encipher or Decipher) services.

3.4 RMF post-processor reports

The RMF post-processor processes the activity data as collected by the RMF data gatherer. In the case of hardware cryptography activity, the RMF Monitor 1 performs the gathering as per the specification in the ERBRMFxx member of SYS1.PARMLIB. By default hardware cryptography activity gathering is enabled unless the NOCRYPTO keyword is specified.

When it comes to generating reports that display information about hardware cryptography activity (the Crypto Hardware Activity or the Workload Activity report), the RMF post-processor program operates as per the option specified in the REPORTS control statement provided as input in the post-processor JCL - the option being CRYPTO or NOCRYPTO. Figure 3-2 shows the control statements input required to get a Crypto Hardware Activity report (REPORTS(CRYPTO)) and a Workload Activity report (SYSRPTS(WLMGL)).

//SYSIN DD * SUMMARY(INT,TOT) DINTV(0001) RTOD(0900,1000) STOD(0900,1000) REPORTS(CRYPTO) SYSRPTS(WLMGL(SCPER)) SYSOUT(A)

Figure 3-2 Sample RMF post-processor SYSIN DD statement

70 System z Cryptographic Services and z/OS PKI Services 3.4.1 Crypto Hardware Activity RMF report

The RMF post-processor report data is arranged in three sections, as shown in Figure 3-3 and explained in the following sections.

CEX2C feature counters (for coprocessor and accelerator mode)

------CRYPTOGRAPHIC COPROCESSOR ------TOTAL ------KEY-GEN TYPE ID RATE EXEC TIME UTIL% RATE CEX2C 1 0.00 0.0 0.0 0.00 2 0.00 0.0 0.0 0.00 3 0.00 0.0 0.0 0.00

------CRYPTOGRAPHIC ACCELERATOR ------

------TOTAL ------ME(1024) ------ME(2048) ------CRT(1024) ------CRT(2048) ------

TYPE ID RATE EXEC TIME UTIL% RATE EXEC TIME UTIL% RATE EXEC TIME UTIL% RATE EXEC TIME UTIL% RATE EXEC TIME UTIL%

CEX2A 0 0.49 0.3 0.0 0.00 0.0 0.0 0.00 0.0 0.0 0.49 0.3 0.0 0.00 0.0 0.0

------ICSF SERVICES ------DES ENCRYPTION DES DECRYPTION ----- MAC ------HASH ------PIN ------

SINGLE TRIPLE SINGLE TRIPLE GENERATE VERIFY SHA-1 SHA-256 TRANSLATE VERIFY RATE 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 SIZE 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00

ICSF counters Figure 3-3 Structure of the Crypto Hardware Activity report

Cryptographic Coprocessor section The recorded activity relates to secure key symmetric cryptographic functions, clear and secure key asymmetric operations, and the calls to the user-defined extension (UDX) functions, if any, installed in the coprocessor.

RSA key generation is given special attention because this operation consumes a large amount of the coprocessors computing capacity.

The fields in the Cryptographic Coprocessor section are: TYPE specifies the type of cryptographic coprocessor, which must be CEX2C on System z9. ID specifies the index number of the coprocessor (also known as the adjunct processor number). TOTAL RATE indicates the global arrival rate - that is, the average number of requests per second - for the total operations executed by the cryptographic coprocessor in the RMF time interval. TOTAL EXEC TIME indicates the global average execution time in milliseconds of elapsed time for all operations performed on this cryptographic coprocessor in the time interval. TOTAL UTIL% gives the total utilization percentage of this processor - that is, the hundredths of seconds of time spent per elapsed second by the coprocessor executing requests - on average in this interval.

Chapter 3. Measuring hardware cryptography activity on z/OS with RMF 71

Note: The following formula applies for the calculation of the coprocessor utilization percentage:

TOTAL UTIL% = TOTAL RATE x TOTAL EXEC TIME /10

Note that the result is always produced with only one single digit after the decimal point.

KEY-GEN RATE gives the occurrence rate of RSA key generation operations.

Cryptographic Accelerator section The CEX2C in accelerator mode (CEX2A) performs the public key cryptography operations used with the Secure Sockets Layer (SSL) or Transport Layer Security (TLS) protocols. These protocols are widely used to help secure e-business applications.

The activity data for the cryptographic accelerators provides details on the RSA key format used: the Modulus exponent (ME) and the Chinese Remainder Theorem (CRT) formats. The data also indicates the key lengths (1024 and 2048 bit) used with each format. The fields in this section are: TYPE specifies the type of cryptographic accelerator, which should be CEX2A on System z9. ID specifies the index number, or AP number, of the cryptographic accelerator. TOTAL RATE indicates the global average arrival rate - that is, the number of requests received per second - for the total of the operations performed by this cryptographic accelerator during the RMF time interval. ME (1024) RATE, EXEC TIME, and UTIL% fields indicate the total rate, average execution time in milliseconds of elapsed time, and utilization percentage of the cryptographic accelerator for all RSA operations with 1024-bit keys, or less, in the Modulus exponent (ME) format. ME (2048) RATE, EXEC TIME, and UTIL% fields indicate the total rate, average execution time in milliseconds of elapsed time and utilization percentage of the cryptographic accelerator for all RSA operations with 2048-bit keys in the Modulus exponent (ME) format. CRT(1024) RATE, EXEC TIME, and UTIL% fields give the total rate, average execution time in milliseconds of elapsed time, and utilization percentage of the cryptographic accelerator for all RSA operations with 1024-bit keys in the Chinese Remainder Theorem (CRT) format. CRT(2048) RATE, EXEC TIME, and UTIL% fields give the total rate, average execution time in milliseconds of elapsed time, and utilization percentage of the cryptographic accelerator for all RSA operations with 2048-bit keys in the Chinese Remainder Theorem (CRT) format.

Note: the following formula applies: TOTAL UTIL% = TOTAL RATE x TOTAL EXEC TIME /10

Note that the result is always produced with only one single digit after the decimal point.

72 System z Cryptographic Services and z/OS PKI Services

Important: The Cryptographic Coprocessor and Cryptographic Accelerator activity figures are built from the data provided by the hardware counters of the CEX2C feature, and

therefore show activities originated from all logical partitions in the system that sends requests to a specific hardware cryptographic coprocessor.

ICSF Services section In this section, the activities of the predetermined set of ICSF services are displayed. The fields in this section are: DES ENCRYPTION, SINGLE and TRIPLE, RATE indicate the rate of requests to CEX2C to encrypt data with the Single-DES or Triple-DES algorithms. These are secure key operations only. DES ENCRYPTION, SINGLE and TRIPLE, SIZE indicate the average number of bytes per request that have been encrypted, using secure keys, with the Single-DES or Triple-DES algorithms. DES DECRYPTION, SINGLE and TRIPLE, RATE indicate the rate of requests to CEX2C to decrypt data with the Single-DES or Triple-DES algorithms. These are secure key operations only. DES DECRYPTION, SINGLE and TRIPLE, SIZE indicate the average number of bytes per request that have been decrypted, using secure keys, with the Single-DES or Triple-DES algorithm. MAC GENERATE and VERIFY RATE indicate the rate of requests to respectively generate or verify MACs. MAC GENERATE and VERIFY SIZE indicate the average number of bytes per request for which MACs have been respectively generated or verified. HASH SHA-1 and SHA-256 RATE indicate the rate of requests to hash data using respectively the SHA-1 or SHA-256 hash algorithms. HASH SHA-1 and SHA-256 SIZE indicate the average number of bytes that were hashed per request using respectively the SHA-1 or SHA-256 hash algorithms. PIN TRANSLATE and VERIFY RATE indicate the rate of requests to respectively translate or verify Personal Identification Numbers.

Important: Again, RMF does not report any activity data for the CPACF other than data imbedded in the CPU time, except, implicitly, when the CPACF is invoked via the CSNBOWH ICSF callable service for SHA-1 or SHA-256 computations. Even in that case, the CPACF utilization cycles are reported in CPU time.

Chapter 3. Measuring hardware cryptography activity on z/OS with RMF 73 3.4.2 Crypto Hardware Activity report example

In this section we provide an example of a Crypto Hardware Activity report (see Figure 3-4) and its interpretation.

C R Y P T O H A R D W A R E A C T I V I T Y PAGE 1 z/OS V1R8 SYSTEM ID SC60 START 04/03/2007-12.42.00 INTERVAL 000.01.00 RPT VERSION V1R8 RMF END 04/03/2007-12.43.00 CYCLE 1.000 SECONDS ------CRYPTOGRAPHIC COPROCESSOR ------TOTAL ------KEY-GEN TYPE ID RATE EXEC TIME UTIL% RATE 0CEX2C 1 763.0 1.3 99.9 0.70

------CRYPTOGRAPHIC ACCELERATOR ------TOTAL ------ME(1024) ------ME(2048) ------CRT(1024) ------CRT(2048) ------TYPE ID RATE EXEC TIME UTIL% RATE EXEC TIME UTIL% RATE EXEC TIME UTIL% RATE EXEC TIME UTIL% RATE EXEC TIME UTIL% CEX2A 0 575.9 0.3 18.2 575.9 0.3 18.2 0.00 0.0 0.0 0.00 0.0 0.0 0.00 0.0 0.0 ------ICSF SERVICES ------DES ENCRYPTION DES DECRYPTION ----- MAC ------HASH ------PIN ------SINGLE TRIPLE SINGLE TRIPLE GENERATE VERIFY SHA-1 SHA-256 TRANSLATE VERIFY RATE 70.90 63.45 70.92 63.43 72.85 72.85 16263 15415 0.00 0.00 SIZE 32.00 32.00 32.00 32.00 32.00 32.00 1257 1256

Figure 3-4 Crypto Hardware Activity report example

This report shows a configuration of two CEX2C cards - one card in coprocessor mode (CEX2C) with index number 1, the other one in accelerator mode (CEX2A) with index number 0. The RMF time interval is one minute.

The CEX2C in coprocessor mode has been utilized at an average of 99.9% during the time interval, having received on average 763 requests per second, each of them consuming on average 1.3 msec of elapsed time. Among these requests, RSA key pair-generation requests were received at a rate of 0.70 request per second, or 42 RSA key-generation requests during the interval.

Remember that this data pertains to coprocessor utilization as induced by all logical partitions that are active in the system during the collection of hardware cryptography activity data.

The CEX2A has been used for 18.2% of the time interval to serve on average 575.9 requests per second, each request taking an average of 0.3 msec of elapsed time. The CEX2A can perform the following clear key services: Digital Signature Verify PKA Decrypt PKA Encrypt (ZERO-PAD and MRP only)

It is not possible to tell, from the report, how the CEX2A utilization breaks down into each one of these services; however, we can see in the report that all operations involved 1024-bit RSA keys in the Modulus exponent format.

Remember that this data pertains to the accelerator utilization as induced by the all the logical partitions active in the system during the RMF interval.

The ICSF services section of the report shows a CEX2C (in coprocessor mode) activity with DES and Triple-DES encryption and decryption, each request processing on average 32 bytes, and MAC Generate and Verify with 32 bytes as the average length of processed data.

The report also shows SHA-1 and SHA-256 activity.

74 System z Cryptographic Services and z/OS PKI Services

Note: The RATE column shows a value of “<0,01” when the crypto activity in the RMF interval is too low to yield a significant measure. This can be seen in Figure 3-5 for the

Cryptographic Accelerator ME(2048) and CRT(1024) activity.

3.4.3 Crypto Hardware Activity report without local activity

In Figure 3-5, we illustrate the case where the CEX2C feature reports an activity that was recorded by RMF; however, no requests are shown for the local ICSF. The CEX2C activity is therefore induced by other logical partitions in the system that share this coprocessor, or it may be ICSF calls that are not part of the set of callable services reported to RMF. This might be a way for tracking, from z/OS, hardware cryptography activity initiated from a Linux logical partition in the same physical system (this assumes, however, a somewhat ideal environment where it is proven that only the Linux logical partition issues requests to the hardware coprocessors).

z/OS V1R7 SYSTEM ID MVO6 START 04/06/2007-14.20.00 INTERVAL 000.20.00 CONVERTED TO z/OS V1R8 RMF END 04/06/2007-14.40.00 CYCLE 1.000 SECONDS 0------CRYPTOGRAPHIC ACCELERATOR ------TOTAL ------ME(1024) ------ME(2048) ------CRT(1024) ------CRT(2048) ------TYPE ID RATE EXEC TIME UTIL% RATE EXEC TIME UTIL% RATE EXEC TIME UTIL% RATE EXEC TIME UTIL% RATE EXEC TIME UTIL% 0PCICA 0 0.01 6.5 0.0 0.01 3.3 0.0 <0.01 15.6 0.0 <0.01 4.5 0.0 0.00 0.0 0.0

------ICSF SERVICES EXECUTED ON CCF ------DES ENCRYPTION DES DECRYPTION ----- MAC ------HASH ------PIN ------SINGLE TRIPLE SINGLE TRIPLE GENERATE VERIFY SHA-1 SHA-256 TRANSLATE VERIFY RATE 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 SIZE 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 ******************************** BOTTOM OF DATA ********************************************************************************

Figure 3-5 Crypto Hardware Activity report without local activity.

3.4.4 Workload Activity report

The reports examples we show in this section have been generated with assembler loops that call the cryptographic services being almost the only activity in the system, and the hardware cryptography reported figures are relatively exaggerated when compared to the figures that we can get in a real production environment.

Chapter 3. Measuring hardware cryptography activity on z/OS with RMF 75 The Workload Activity report provides information about the flow of the requests sent to the CEX2C or CEX2A - that is, how often, on a sampling basis, they are immediately served or, on the contrary, put in a wait queue by ICSF. This appears in the report shown in Figure 3-6 at the bottom right-hand corner (see the fields CRYPTO% USG and DLY).

1 W O R K L O A D A C T I V I T Y PAGE 1 z/OS V1R8 SYSPLEX PLEX60 START 04/05/2007-07.43.00 INTERVAL 000.01.00 MODE = GOAL RPT VERSION V1R8 RMF END 04/05/2007-07.44.00

POLICY ACTIVATION DATE/TIME 09/06/2006 23.03.35

------SERVICE CLASS PERIODS

REPORT BY: POLICY=WLMPOL WORKLOAD=BAT_WKL SERVICE CLASS=BATHI RESOURCE GROUP=*NONE PERIOD=1 IMPORTANCE=3 CRITICAL =NONE

TRANSACTIONS TRANS-TIME HHH.MM.SS.TTT --DASD I/O-- ---SERVICE---- SERVICE TIMES ---APPL %--- PAGE-IN RATES ---STORAGE--- AVG 9.84 ACTUAL 0 SSCHRT 0.0 IOC 0 CPU 2.3 CP 3.85 SINGLE 0.0 AVG 296.73 MPL 9.84 EXECUTION 0 RESP 0.0 CPU 65483 SRB 0.0 AAPCP 0.00 BLOCK 0.0 TOT 2921.19 ENDED 0 QUEUED 0 CONN 0.0 MSO 0 RCT 0.0 IIPCP 0.00 SHARED 0.0 CEN 2921.19 END/S 0.00 R/S AFFIN 0 DISC 0.0 SRB 8 IIT 0.0 HSP 0.0 EXP 0.00 #SWAPS 0 INELIGIBLE 0 Q+PEND 0.0 TOT 65491 HST 0.0 AAP N/A HSP MISS 0.0 EXCTD 0 CONVERSION 0 IOSQ 0.0 /SEC 1092 AAP N/A IIP N/A EXP SNGL 0.0 SHR 9.84 AVG ENC 0.00 STD DEV 0 IIP N/A EXP BLK 0.0 REM ENC 0.00 ABSRPTN 111 EXP SHR 0.0 MS ENC 0.00 TRX SERV 111

GOAL: EXECUTION VELOCITY 30.0% VELOCITY MIGRATION: I/O MGMT 46.7% INIT MGMT 46.7%

RESPONSE TIME EX PERF AVG ------USING% ------EXECUTION DELAYS % ------DLY%-- -CRYPTO%- % SYSTEM VEL% INDX ADRSP CPU AAP IIP I/O TOT CPU UNKN IDLE USG DLY QUIE

SC60 --N/A-- 46.7 0.6 9.8 0.9 N/A N/A 0.0 1.1 1.1 98.0 0.0 40.0 10.2 0.0

Figure 3-6 Workload Activity report - period 1

The fields in the Workload Activity report are: USG reports the percentage of time a TCB or SRB was found to be using a cryptographic processor - that is, the application request to ICSF has been sent to the coprocessor and occupies one entry among N in the structure maintained by ICSF (refer to “Overview of ICSF cryptographic workload balancing” on page 66 for an explanation of cryptographic requests queuing). DLY reports the percentage of time a TCB or SRB was found to be waiting for a cryptographic processor queue - that is, the application request is being kept in a wait queue by ICSF.

Note: The USG and DLY values are based on state samples provided by WLM that pertain to work units running in service or report class periods. If the work unit holds an entry in the structure of N operations in process (see the description of this structure in 3.1, “Overview of ICSF cryptographic workload balancing” on page 66), using state count is increased for the service or report class period the work unit belongs to. Likewise, if a work unit is found to be queued waiting behind a coprocessor, it is then reported as an additional point in a delay count.

The CRYPTO %USG and %DLY values in the WLM report are the percentages of the TOTAL using or delay samples. TOTAL is the sum of all using and delay state samples counted by WLM for all work units in the system. Refer to z/OS V1R9.0 RMF Report Analysis, SC33-7991, for a complete list of sampled states in the “WLMGL - Workload Activity report” chapter.

76 System z Cryptographic Services and z/OS PKI Services These report examples pertain to the service class BATHI, which was defined with two periods. The first part of the report (see Figure 3-6 on page 76) shows that on average during the interval, the local instance of ICSF was participating for 10.2% of the work units held in wait in the system while it was contributing for 40% of the work units that were executing in period 1. The second part (see Figure 3-7) shows that ICSF was holding 9.7% of the work

units in wait while 40.3% were being executed by the coprocessors in period 2.

REPORT BY: POLICY=WLMPOL WORKLOAD=BAT_WKL SERVICE CLASS=BATHI RESOURCE GROUP=*NONE PERIOD=2 IMPORTANCE=4 CRITICAL =NONE

TRANSACTIONS TRANS-TIME HHH.MM.SS.TTT --DASD I/O-- ---SERVICE---- SERVICE TIMES ---APPL %--- PAGE-IN RATES ---STORAGE--- AVG 0.16 ACTUAL 0 SSCHRT 0.0 IOC 0 CPU 0.1 CP 0.09 SINGLE 0.0 AVG 327.16 MPL 0.16 EXECUTION 0 RESP 0.0 CPU 1427 SRB 0.0 AAPCP 0.00 BLOCK 0.0 TOT 50.77 ENDED 0 QUEUED 0 CONN 0.0 MSO 0 RCT 0.0 IIPCP 0.00 SHARED 0.0 CEN 50.77 END/S 0.00 R/S AFFIN 0 DISC 0.0 SRB 26 IIT 0.0 HSP 0.0 EXP 0.00 #SWAPS 0 INELIGIBLE 0 Q+PEND 0.0 TOT 1453 HST 0.0 AAP N/A HSP MISS 0.0 EXCTD 0 CONVERSION 0 IOSQ 0.0 /SEC 24 AAP N/A IIP N/A EXP SNGL 0.0 SHR 0.16 AVG ENC 0.00 STD DEV 0 IIP N/A EXP BLK 0.0 REM ENC 0.00 ABSRPTN 156 EXP SHR 0.0 MS ENC 0.00 TRX SERV 156

GOAL: EXECUTION VELOCITY 20.0% VELOCITY MIGRATION: I/O MGMT 0.0% INIT MGMT 0.0%

RESPONSE TIME EX PERF AVG ------USING% ------EXECUTION DELAYS % ------DLY%-- -CRYPTO%- % SYSTEM VEL% INDX ADRSP CPU AAP IIP I/O TOT CPU UNKN IDLE USG DLY QUIE

SC60 --N/A-- 0.0 0.0 0.2 0.0 N/A N/A 0.0 16.7 16.7 77.8 0.0 40.3 9.7 0.0

Figure 3-7 Workload Activity report - period 2

3.4.5 Overview report

The RMF post-processor overview report may prove to be an appropriate way of tracking hardware cryptography activity. Figure 3-8 shows the control statements used for such an Overview report and the resulting reported data.

OVW(APUSG1 (APUSGP(S.BATHI.1))) OVW(APDLY1 (APDLYP(S.BATHI.1))) OVW(APUSG2 (APUSGP(S.BATHI.2))) OVW(APDLY2 (APDLYP(S.BATHI.2))) OVW(CCUTIL (CRYCTU(1))) ....

DATE TIME INT APUSG1 APDLY1 APUSG2 APDLY2 CCUTIL MM/DD HH.MM.SS HH.MM.SS 04/05 07.41.00 00.01.00 0.0 0.0 0.0 0.0 0.0 04/05 07.42.00 00.00.59 40.5 10.0 0.0 0.0 50.7 04/05 07.43.00 00.01.00 40.0 10.2 40.3 9.7 98.6 04/05 07.44.00 00.01.00 42.5 7.5 40.1 10.0 98.7 04/05 07.45.00 00.00.59 0.0 0.0 40.3 9.7 72.5

Figure 3-8 RMF Overview report

The control statements collect: The using% for the period 1 in service class BATHI The delay% for the period 1 in service class BATHI The delay% for the period 2 in service class BATHI The utilization% for the CEX2C coprocessor id=1

Chapter 3. Measuring hardware cryptography activity on z/OS with RMF 77 The output data of this Overview report can be interpreted as: Interval ending 07.41 - no crypto load. Interval ending 07.42 - some crypto load with 50% utilization of coprocessor USING and DELAY samples only in period 1. No work spills over into period 2. Interval ending 07.43 - a heavy crypto load, the coprocessor is almost 100% utilized. We can now see USING and DELAY samples in period 1 and 2. Interval ending 07.44 - similar to the previous interval. Interval ending 07.h45 - the cryptographic workload is decreasing. Actually the only workload left is the one that already spilled over into period 2.

78 System z Cryptographic Services and z/OS PKI Services

Chapter 4. Assessing activity with OMEGAMON XE on z/OS and RMF

In this chapter, we provide an overview of using Tivoli OMEGAMON XE on z/OS to monitor and assess the hardware cryptography activity on z/OS. The documentation to refer to for OMEGAMON XE on z/OS is: IBM Tivoli OMEGAMON XE on z/OS: Planning and Configuration Guide, SC32-1822 IBM Tivoli OMEGAMON XE on z/OS: User’s Guide, SC32-1821

Tivoli OMEGAMON XE on z/OS support for IBM cryptographic coprocessors provides an infrastructure that gives the user, via a graphical interface, insight into the initial installation and configuration of the cryptographic coprocessors, as well as ongoing insight into their performance. Figure 4-1 illustrates the Tivoli OMEGAMON XE on z/OS infrastructure.

z/OS Omegamon XE workstation For z/OS TCP/IP Web Services + Exits Monitoring interface Agents Java based ICSF + Tivoli GUI Enterprise Monitoing server

Tivoli Enterprise Portal Server + Tivoli Enterprise client Figure 4-1 The OMEGAMON XE on z/OS infrastructure we used in ITSO

The infrastructure shown in Figure 4-1 provides the functions required to: Monitor the ICSF subsystem of z/OS for coprocessor status, configuration errors, and service call performance. Monitor the arrival rates of requests, queue lengths, and service calls. Scan for enabled or disabled public keys, active or inactive Public Key Dataset (PKDS), and valid or invalid master keys, and issue an alert for any discrepancies. Speed problem identification and resolution with Situation Editor, Expert Advice, Take Action, automated alert notification and customizable workspaces.

The infrastructure we used for the discussions in this chapter has been “compacted” so that functional participants - such as the Tivoli Enterprise Monitoring Server and the Tivoli Enterprise Portal Server, which usually reside on distributed hosts of their own - share hosts with other elements of the infrastructure.

Note: Tivoli OMEGAMON on z/OS reports the hardware cryptography activity initiated by the ICSF callable services. ICSF service exits are being installed when installing OMEGAMON on z/OS. The OMEGAMON XE on z/OS reporting therefore pertains only to the local hardware cryptography activity as initiated by the local instance of ICSF.

80 System z Cryptographic Services and z/OS PKI Services 4.2 OMEGAMON XE on z/OS graphical interface

OMEGAMON XE on z/OS can display information related to the ICSF status and environment, in the graphical format shown in Figure 4-2.

Figure 4-2 Tivoli OMEGAMON XE on z/OS - ICSF status display

Chapter 4. Assessing activity with OMEGAMON XE on z/OS and RMF 81 It can also provide a view of the cryptographic workload performance, per callable service, as shown in Figure 4-3.

Figure 4-3 OMEGAMON XE on z/OS - Cryptographic workload performance

4.3 Measuring activity with RMF and OMEGAMON XE on z/OS

In this section, we provide example‘s of hardware cryptography activities that have been measured both with RMF and OMEGAMON XE on z/OS.

4.3.1 SHA-1 activity (CPACF activity)

As previously mentioned, SHA-1 on System z9 is performed by the CPACF facility in the PU, and you cannot differentiate the CPACF activity from other PU activity in the activity reports. That also is true for the reporting done by OMEGAMON XE on z/OS. However, when SHA-1 or SHA-256 functions are called via the ICSF CSNBOWH callable service, ICSF provides

82 System z Cryptographic Services and z/OS PKI Services accounting information. Figure 4-4 shows the SHA-1 activity reported by RMF in the ICSF SERVICES section without showing, however, any activity recorded in the CRYPTOGRAPHIC COPROCESSOR section.

C R Y P T O H A R D W A R E A C T I V I T Y PAGE 1 z/OS V1R8 SYSTEM ID SC60 START 03/28/2007-09.56.00 INTERVAL 000.00.59 RPT VERSION V1R8 RMF END 03/28/2007-09.57.00 CYCLE 1.000 SECONDS ------CRYPTOGRAPHIC COPROCESSOR ------TOTAL ------KEY-GEN TYPE ID RATE EXEC TIME UTIL% RATE CEX2C 1 0.00 0.0 0.0 0.00 2 0.00 0.0 0.0 0.00 3 0.00 0.0 0.0 0.00

------ICSF SERVICES ------DES ENCRYPTION DES DECRYPTION ----- MAC ------HASH ------PIN ------SINGLE TRIPLE SINGLE TRIPLE GENERATE VERIFY SHA-1 SHA-256 TRANSLATE VERIFY RATE 0.00 0.00 0.00 0.00 0.00 0.00 52795 0.00 0.00 0.00 SIZE 0.00 0.00 0.00 0.00 0.00 0.00 1256 0.00 ******************************** BOTTOM OF DATA ***********************************************************************************

Figure 4-4 RMF reporting of SHA-1 requests

Chapter 4. Assessing activity with OMEGAMON XE on z/OS and RMF 83 The OMEGAMON XE on z/OS online monitor provides the snapshot shown in Figure 4-5 for the same activity.

Figure 4-5 OMEGAMON XE on z/OS graphical display of SHA-1 activity

84 System z Cryptographic Services and z/OS PKI Services 4.3.2 CEX2C activity

In this example, an application is requesting DES encryption and decryption using a secure key. This service is provided by the CEX2C, and RMF displays the coprocessor activity as shown in the post-processor report in Figure 4-6.

C R Y P T O H A R D W A R E A C T I V I T Y PAGE 1 z/OS V1R8 SYSTEM ID SC60 START 03/28/2007-07.33.00 INTERVAL 000.00.59 RPT VERSION V1R8 RMF END 03/28/2007-07.34.00 CYCLE 1.000 SECONDS ------CRYPTOGRAPHIC COPROCESSOR ------TOTAL ------KEY-GEN TYPE ID RATE EXEC TIME UTIL% RATE CEX2C 1 767.8 0.9 69.8 0.00

Figure 4-6 RMF reporting of CEX2C activity

Chapter 4. Assessing activity with OMEGAMON XE on z/OS and RMF 85 The OMEGAMON XE on z/OS interface displays this activity as shown in Figure 4-7. Note that this display shows “residual” key generation operations. We explain why we see this kind of residual display in “Residual activity” on page 88.

Figure 4-7 OMEGAMON XE on z/OS graphical display of CEX2C activity

4.3.3 CEX2A activity

The CEX2A is actually a CEX2C that has been manually reconfigured into “accelerator mode.” In this mode the CEX2C, now CEX2A, supports a limited set of RSA operations using a clear key only. The Digital Signature Verify is one of the few functions supported by a

86 System z Cryptographic Services and z/OS PKI Services CEX2A. In this example the application is calling the Digital Signature Verify service, and the CEX2A activity is recorded by RMF as shown in Figure 4-8.

C R Y P T O H A R D W A R E A C T I V I T Y PAGE 1 z/OS V1R8 SYSTEM ID SC60 START 03/30/2007-08.51.00 INTERVAL 000.01.00 RPT VERSION V1R8 RMF END 03/30/2007-08.52.00 CYCLE 1.000 SECONDS ------CRYPTOGRAPHIC COPROCESSOR ------TOTAL ------KEY-GEN TYPE ID RATE EXEC TIME UTIL% RATE CEX2C 1 0.00 0.0 0.0 0.00

Figure 4-8 RMF reporting of CEX2A activity

The CEX2A activity is displayed by OMEGAMON XE on z/OS as shown in Figure 4-9.

Figure 4-9 OMEGAMON XE on z/OS graphical display of CEX2A activity

Chapter 4. Assessing activity with OMEGAMON XE on z/OS and RMF 87 4.4 Using the OMEGAMON XE on z/OS Service Call Performance workspace

The Service Call Performance workspace displays bar charts of the top ten service calls by Arrival Rate, Service Time, Pending, and Bytes Processed. The lower right table in Figure 4-10 shows details of all 78 service calls monitored. The monitored service calls are also shown.

Figure 4-10 The Service Call Performance workspace

Residual activity We used several assembler loops of ICSF calls in parallel to obtain the display shown in Figure 4-10. However, even after stopping all our loops, the Service Call Performance workspace still shows hardware cryptography activity. The reason for this residual display is because the performance data shown in this workspace report is the last 10 minutes rolling average of collected data, and historical sampling by OMEGAMON XE on z/OS occurs at 5-minute intervals (half the length of the data-averaging interval). Therefore, the figures for Arrivals are computed across the last 10 minutes and continue to be computed as rolling averages after the job completes. The previously collected minutes of activity continue to be included in the rolling average until they are “old” enough. Hence the user should expect all the activity numbers to show as zero only after a period where no cryptographic activity is issued.

88 System z Cryptographic Services and z/OS PKI Services In practice, however, it is highly unlikely that a cryptographic coprocessor workload is submitted in such high rates as with assembler loops. A more likely workload issues cryptographic services requests followed by some interleaving I/O operations, and the rolling average method more closely depicts the actual arrival of hardware cryptography requests.

Chapter 4. Assessing activity with OMEGAMON XE on z/OS and RMF 89

90 System z Cryptographic Services and z/OS PKI Services

Chapter 5. Java cryptography

In this chapter, we present the Java perspective on leveraging the encryption capabilities of z/OS.

We begin by describing the different Java cryptography concepts, implementations, providers, and keystores on z/OS. In doing so, we place special emphasis on the hardware cryptography providers. This discussion is followed by descriptions of the different kinds of keystores and the algorithms supported. We also demonstrate how easy it is to set up the system to utilize these capabilities. To verify our description of system capabilities, we present Java examples that provide instructions for implementing the Java cryptography concepts in real-world scenarios and projects. Finally, we outline the benefits of using the hardware cryptography capabilities of z/OS.

The examples listed in this chapter have been created using IBM JDK™ Version 1.5.

Using cryptographic algorithms in Java applications is simple due to the Java Cryptography Extension (JCE). IBM Java Development Kit (JDK) provides IBMJCE, an IBM implementation of the JCE specification. This implementation provides encryption features, digital signatures, and hash functions. A key-exchange scheme is also included within IBMJCE.

Due to the nature of the cryptographic algorithms, managing cryptographic keys can generate a large amount of computations; so, when cryptography is involved, performance and key-management issues should be considered as well.

IBM Common Cryptographic Architecture (CCA) is a set of software elements that provide common application interfaces to secure, high-speed cryptographic services on various platforms via hardware cryptographic devices. To exploit this feature, IBM Java provides IBMJCECCA, which is am implementation of JCE using hardware cryptography via CCA interfaces.

In this section, we provide an overview of cryptography and its related topics and discuss the issues involved when using cryptography in Java applications. Following that discussion, we explore hardware cryptography support for Java in z/OS using IBMJCECCA.

5.1.1 Cryptography overview

Because a number of businesses use information technology for their mission-critical operations, information security has become an essential part of IT. Among many types of information security technologies, cryptography is one of the most essential. It provides data confidentiality, data integrity, data and identity authentication, and nonrepudiation services via encryption, digital signatures, and hash functions. Before discussing Java cryptography on z/OS, we provide an overview of cryptography and related issues.

Security services You should consider many security services when you design security architecture. In this section, we explain five basic security services that can be implemented using cryptography: Confidentiality: Ensures that data is available only to authorized parties. Data integrity: Ensures that data is modified only by authorized parties. Data authentication: Ensures the origin of data is correct. Identity authentication: Ensures that the identity in question is correct. Nonrepudiation: Proves an action is performed by the party in question.

92 System z Cryptographic Services and z/OS PKI Services Types of cryptographic algorithms To implement the previously listed security services, different types of cryptographic algorithms are required because each algorithm has a specific purpose. Encryption and digital signature algorithms are the most widely used. Encryption Data confidentiality is provided by encryption. Using an encryption algorithm and encryption key, plaintext is converted into ciphertext. To get the original message from the ciphertext, a decryption key corresponding to the encryption key is required. In Figure 5-1, the flow of encryption and decryption flow is depicted, where two keys are used: an encryption key and its corresponding decryption key.

Encryption Key

Encryption Algorithm

Original Message Encrypted message This is a plain text QWE!@#T$!121%HTz

Decryption Algorithm

Decryption Key

Figure 5-1 Flow of encryption and decryption

Chapter 5. Java cryptography 93 Depending on key types, encryption schemes can be categorized into symmetric and asymmetric schemes, which are explained later in this section. DES, TDES, AES, RSA, and ECC are well-known encryption schemes. Digital signatures In the real world, we sign a document to authenticate it. Digital signatures authenticate digital documents or data. The difference between signatures in the real world and digital signatures is that distinctive digital signatures are used for each piece of digital data. DSA and RSA signatures are the most well-known schemes. Figure 5-2 shows the overall process of using digital signatures and of their verification.

Alice’s Signature Bob’s Verification

Alice’s Verification Key Message

Balance Balance $100 $100

Verification Signature Algorithm Algorithm Not valid

Valid

Deny Accept Message

Alice’s Signing Key

Figure 5-2 Flow of digital signatures and verification

In Table 5-1, possible combinations of cryptographic techniques are presented for each security service.

Table 5-1 Cryptographic techniques for security services Security service Cryptographic techniques required

Confidentiality Encryption

Data integrity Digital signature

Data authentication Digital signature

Identity authentication Digital signature

Nonrepudiation Digital signature

Public Key Cryptography Standards (PKCS) Public Key Cryptography Standards (PKCS) is a set of de-facto standards widely used for public key cryptography. PKCS1 - RSA cryptography PKCS5 - Password-based encryption PKCS7 - Cryptographic message syntax PKCS8 - Private key information syntax

94 System z Cryptographic Services and z/OS PKI Services PKCS9 - Selected attribute types PKCS10 - Certificate request syntax PKCS12 - Personal information exchange syntax

Additional information about PKCS can be found at:

http://www.rsasecurity.com/rsalabs/pkcs

5.1.2 Types of encryption algorithms

Encryption algorithms are classified into two types based on the relationship between an encryption key and its corresponding decryption key. Symmetric key encryption and asymmetric key encryption are two classes of encryption. In this section, we first explain the two classes and then compare the two encryption types.

Symmetric key encryption In symmetric key encryption, an encryption key and a decryption key are the same or sometimes easily transformed into each other, which means knowing one of the keys reveals the other key without difficulty.

A key used in symmetric key encryption is called a shared secret key.

Figure 5-3 depicts how symmetric key cryptography works.

Secret key

Encryption algorithm

Original message Encrypted message

This is plaintext. QWE!@#T$!121%HTz

Decryption algorithm

Secret key

Figure 5-3 Flow of symmetric key encryption

To share a secret message among participants, they have to share the secret key in advance. For example, two people meet in the real world and exchange a secret key, which will be used as a secret key later. The key should not be disclosed to others. If disclosed, the message is no longer secure. Besides sharing a key securely, the key should be regularly changed. Due to advanced cryptanalysis, the same key used over a long time period could be revealed or the cryptosystem could be broken.

Data Encryption Standard (DES), Triple-DES (TDES), and Advanced Encryption Standard (AES) are the well-known algorithms. These encryption algorithms are block ciphers, which means they encrypt a fixed-size block at a time. Each algorithm has its supporting block size. If the length of message to be encrypted is not a multiple of the predefined block size,

Chapter 5. Java cryptography 95 additional data must be added to make it so. This process is called padding. PKCS5Padding is an example of padding.

The length of secret keys differs among symmetric key encryption algorithms. DES supports a 56-bit length key; TDES, 168-bit length; and AES key supports 128, 192, or 256-bit length keys. Currently, DES using a 56-bit length key is easily broken because of the advance of cryptanalysis and increased computing power. We recommend using TDES or AES because they had not yet been broken at the time this document was written.

Last, suppose you want blocks of the same data in your message to be encrypted into the same cipher blocks? For example, consider a message “ABCDEFGHABCD” and an block encryption algorithm of a 4-byte length block. Because the first block and the third block of the message are the same, these blocks will be encrypted to the same ciphertext. A pattern such as this could reveal to an adversary an idea of your encrypted message.

Various modes of operation - Electronic Codebook (ECB), cipher-block chaining (CBC), Cipher Feedback (CFB), and Output Feedback (OFB) - can be used to chain the blocks resulting in different encrypted blocks for blocks of the same data. They also make the block cipher work on a different length of block from that which the cipher algorithm originally supports.

Asymmetric key encryption Another class of encryption algorithm is asymmetric key encryption, or public key encryption. In this cryptosystem, an encryption key and its related decryption key are not identical nor easily transformed - that is, knowing one of the keys does not reveal the other key. The keys that make up the key pair used by an asymmetric algorithm are usually called the private and public keys. As named, a public key is not a secret, but publicly known information and the private key are known only by the owner of the key pair.

Consider a situation in which Bob wants to send a secret message to Alice. First, Alice sets up the public key and private key in advance and publishes the public key to the world. If Bob wants to send a secret message to Alice, Bob encrypts the message using Alice’s public key. Receiving the ciphertext, Alice decrypts it using the private key. Figure 5-4 depicts this scenario.

Public key

Encryption algorithm

Original message Encrypted message

This is plaintext. QWE!@#T$!121%HTz

Decryption algorithm

Private key

Figure 5-4 Flow of public key encryption and decryption

96 System z Cryptographic Services and z/OS PKI Services In a situation where two or more people exchange secure messages. When they are using symmetric key encryption, each of the parties should share the common secret key in advance. To establish a secure channel between the two parties, prior key agreement or exchange, unlike symmetric key encryption, is not required, which is a powerful feature of public key encryption. Each party simply sets up its key pair and publishes its public key to anyone else.

In this world of cryptosystems, key management is definitely required. The integrity of a public key must be assured. Public Key Infrastructure (PKI) is best suited for key management in public key cryptosystems.

In addition, the confidentiality of a private key must be maintained. This issue is similar to the case of symmetric key encryption. The private key must not be disclosed to others. The keystore concept of IBMJCE is for this purpose. For a higher level of security, you can choose different keystore types provided by IBMJCECCA.

Whereas symmetric key encryption is most often achieved by binary logical operations, asymmetric key encryption is based on calculations of large integers (that is, integers of 1024-bit length), which requires more computation time and resources than bit operations. For this reason, symmetric key encryption is much slower than asymmetric key encryption in achieving a similar level of security.

Well-known examples of asymmetric key algorithms are: RSA Diffie-Hellman Elliptic Curve Cryptography (ECC) ElGamal

Hybrid encryption approach As we described, neither symmetric key encryption nor asymmetric key encryption is a complete solution for building secure channels among large numbers of entities. Each pair of entities should share a common key and manage it in symmetric key encryption, whereas asymmetric key encryption does not require a common key between two entities in advance. However, the speed of symmetric key encryption is faster than that of asymmetric key encryption.

To exploit the advantages of the two types of encryption algorithms, the two can be combined. Asymmetric key encryption is used for exchanging keys that will be used for encrypting messages using symmetric key cryptography.

Chapter 5. Java cryptography 97 Figure 5-5 depicts this hybrid approach. Alice and Bob have their own public and private key pairs, and they want to exchange secure messages over the network without sharing a secret key in advance.

Alice’s encryption Bob’s decryption

Original Encrypted Decrypted message message message

$100 AES encryption @3z9K AES decryption $100

AES key

RSA encryption RSA decryption AES key Encrypted AES key

Bob’s public key Bob’s private key

Figure 5-5 Flow of hybrid encryption

The hybrid encryption scheme works as follows: 1. Alice selects a secret key, k, for TDES. 2. Alice encrypts the secret key k using RSA encryption with Bob’s public key. 3. Alice sends the encrypted secret key to Bob. 4. Bob decrypts the encrypted secret key using its private key. 5. Alice and Bob share the secret key k. 6. At this point, Alice or Bob can share a secret message using TDES with the secret key k.

5.1.3 Key-management challenge

A cryptographic scheme consists of an algorithm and keys. Since the cryptographic algorithm itself is open to the world, the well-known cryptography schemes are proven to be secure at the current technology level. Therefore, the security of cryptography depends on the security of the keys. The encryption and decryption key of DES and the private key of RSA must be managed securely, which means the keys should not be disclosed to unauthorized parties. Knowing the key enables an adversary to decrypt the ciphertext and even impersonate your identity in the digital world.

However, the fact keys may be hard-coded in an application does not necessarily mean that the application provides security. For secure management of cryptographic keys, Java introduces the keystore. IBMJCE provides a keystore and its management tool called a keytool. The keystore is a password-protected file, and contains certificates and cryptographic keys. These keys are also protected by another password, a keypass.

98 System z Cryptographic Services and z/OS PKI Services This approach has weaknesses too. One is that passwords are easily broken due to the nature of password selection. Because passwords are often chosen from dictionary words or some combination of them, passwords can be guessed or can be broken via dictionary attacks. The other weakness is that once the key is retrieved from the keystore, the key is seen as cleartext. Using a memory dump and analysis technique, an adversary can identify

the key.

IBMJCECCA provides two keystore types, JCECCAKS and JCECCARACFK, to overcome these weaknesses. The level of security can be selected according to the security requirements. We explore these keystore types and their benefits in the following section, 5.1.4, “Java cryptography in z/OS” on page 99.

In addition to the secure key-management feature, using IBMJCECCA on z/OS enables faster cryptographic calculations and more secure computation.

5.1.4 Java cryptography in z/OS

In general, the Java Cryptography Extension (JCE) in the Java 2 Platform Standard Edition (JCE in J2SE™) provides a framework and implementation for encryption, key generation, and key agreement, and for MAC algorithms. Support for encryption includes symmetric, asymmetric, block, and stream ciphers. The software also supports secure streams and sealed objects. JCE in J2SE supplements the Java 2 platform, which already includes interfaces and implementations of message digests and digital signatures.

The IBMJCECCA implementation extends JCE seamlessly to add the capability of using hardware cryptography via the IBM Common Cryptographic Architecture (CCA) interfaces. This provider takes advantage of hardware cryptography within the existing JCE architecture and gives Java 2 programmers the significant security and performance advantages of hardware cryptography with minimal changes to existing Java applications. Just as the complexities of hardware cryptography are taken care of within the standard Java Cryptography Architecture, IBMJCECCA makes advanced security and performance easily available using hardware cryptographic devices.

In Figure 5-6, the overall architecture is shown with interactions among the components.

Java application Assembler stub RACF JCE provider keyrings (IBMJCECCA) JVM

PKDS CKDS

ICSF

Master key CPACF CEX2C

Figure 5-6 z/OS hardware cryptography for Java

Chapter 5. Java cryptography 99 IBM CCA is a set of software elements that provide common application interfaces to secure, high-speed cryptographic services on various platforms using hardware cryptographic devices. On z/OS, ICSF is the element that provides callable services that comply with the IBM Common Cryptographic Architecture (CCA). To add a high-security environment to your z/OS server systems for DES and RSA cryptographic functions and sensitive applications,

use the PCI X Cryptographic Coprocessor (PCIXCC) or Crypto Express2 Coprocessor (CEX2C). Until 2005, z890 and z990 machines took advantage of the PCIXCC feature, which was replaced by the CEX2C feature available on z890 and z990 servers and those developed subsequently.

In addition to configuring the correct hardware for your environment, if you want to use symmetric keys longer than 64 bits, you must install the unrestricted policy files in your JVM™ to allow the IBMJCECCA provider to load and to function.

The IBMJCECCA provider supports the following: Message digest via the MD2, MD5, and SHA-1 algorithms Signature and KeyFactory classes Symmetric algorithms DES, Triple-DES (also known as TDES), HMAC, and PBE Asymmetric algorithms RSA encryption and decryption with zero padding and PKCS 1 type 2 padding Digital signature creation and verification using the RSA and DSA algorithms (note that DSA is not supported on z890 or z990 hardware) True random-number generation Key generation via key factories Generation and management of keys and certificates using the keytool application

Considering cryptographic algorithms Following is a list of considerations for evaluating cryptographic algorithms: Not all the DES and TDES ciphers are available via hardware devices. The hardware devices support only the cipher block chaining (CBC) version of DES and TDES. Although the hardware devices only support CBC, IBM did implement all the DES ciphers within the hardware-capable provider. For performance reasons, the size of the data you are processing is important. Sometimes it is faster to use software DES to process small amounts of data. We use a clip level to check the data size, and based on that, the code uses either hardware or software cryptography. IBM implemented this as a system property called “ibm.DES.usehdwr.size” with a default value of 60 bytes. By default, data that is 60 bytes or less is processed via software DES. Data above 60 bytes is processed by hardware cryptography for CBC only. For the other secondary ciphers, this system property has no function. You can change this clip level by simply changing the system property to the level you desire. It is also possible to set the system property to zero, in which case all DES CBC processing is performed by the hardware. java -Dibm.DES.usehdwr.size=80 We recommend you set the key pair type to KEYMANAGEMENT when an RSA key pairkey pair is generated as regard to an asymmetric algorithm. Also, text being encrypted or decrypted is limited to 245 bytes or 11 bytes smaller than the modulus size of the key in bytes, whichever is smaller.

100 System z Cryptographic Services and z/OS PKI Services Key-management tools Key-management tools are discussed in the sections that follow. keytool A keytool is a key and certificate-management utility. It enables users to administer their own public and private key pairs and associated certificates. It also enables users to cache the public keys (in the form of certificates) of their communicating peers. keytool stores the keys and certificates in a keystore. The default keystore implementation implements the keystore as a file. hwkeytool hwkeytool is the equivalent of keytool, with the ability to access cryptographic hardware. hwkeytool stores the keys and certificates in a hwkeystore; in additional, hwkeytool can use cryptographic hardware to generate keys, It can also store keys in cryptographic hardware or in hardware-protected files (PKDS).

Using keytool and hwkeytool, it is possible to display, import, and export certificates. It is also possible to generate self-signed certificates. keytool and hwkeytool currently handle X.509 certificates.

Differences between software and hardware implementations of JCE There are few differences between the software cryptography implementation of JCE (IBMJCE) and the hardware implementation (IBMJCECCA). For example, DES and Triple-DES keys are the same in the IBMJCECCA provider as in the IBMJCE provider. One difference, discussed in the following section, is in the required key attribute restrictions for the RSA cipher algorithm.

A more important difference is in the list of supported cryptographic algorithms. The IBMJCECCA provider supports fewer algorithms than the IBMJCE provider, due to limitations in the currently available hardware. The cryptographic operations provided by the IBMJCECCA are the same as for previous versions of JCE. Therefore, you can easily migrate an existing application from a software JCE provider, such as IBMJCE, to the hardware JCE environment, IBMJCECCA. To migrate, you need only generate new key pairs for RSA or DSA with appropriate attributes (see the section that follows) and to change the security provider.

Key-pair generation has default values that allow most types of key-pair generation used for a software JCA or JCE provider to be functional in the IBMJCECCA provider with no changes. In addition, the hardware representation of the key (label or internal CCA token) is accepted by all JCE APIs in IBMJCECCA.

Benefits from hardware-based cryptography Using a dedicated hardware-based cryptography device and IBMJCECCAKS or IBMJCECCARCKKS on z/OS, advanced security features are provided, which are hard to get from software-based cryptography or on other platforms.

Key Confidentiality One of the main benefits of hardware-based cryptography is that keys are managed securely throughout their life cycles. z/OS hardware cryptography forces a secret or private key to be stored as encrypted format using the master key. Moreover, cryptographic keys are never exposed to the system memory because cryptographic processing is performed by dedicated hardware, An application uses a reference to the encrypted key instead of the key itself.

Chapter 5. Java cryptography 101 Table 5-2 describes different security levels for each key pair type. The levels of security and speed are compared among JCECCAKS key types.

Table 5-2 Key pair characteristics for keystore types Keystore Key type Private key Encrypted Level of Multiple Speed location private key security crypto hardware support

JCECCAKS RETAINED Crypto Ye s High No Slowest hardware

PKDS token RACF- Ye s Medium Ye s Medium protected data set

Clear File No Low Ye s Fastest

JCECCARACFKS SAF keyring SAF --Yes- connected database or key PKDS token

Note: Most JCE providers using software cryptography support only the key pair type CLEAR. Initial testing indicates that the IBMJCECCA provider using PKDS key pairs (that add significant security to sensitive private keys) out-performs a JCE provider using software cryptography and CLEAR key pairs.

Access control to key and audit on key usage RACF on z/OS enables access control and audit features on key usage, which should be highly protected. Based on RACF configuration, different levels of security can be achieved.

Enhanced performance IBMJCE is a software implementation of cryptography algorithms. In case of asymmetric key encryption or digital signatures, large amounts of CPU time are consumed because these algorithms require integer computations of large numbers (that is, 1024-bit numbers are used for RSA). Delegating this heavy operation to a hardware cryptography device, the system frees up the system CPU for other activities. This performance enhancement is also true for symmetric encryptions like DES, TDES, and AES.

5.2 Cryptography providers on z/OS

A provider is a set of common APIs that extend Java by adding security capabilities. The provider architecture supplies algorithm implementations for service classes. A collection of all of the implementations is referred to as a service provider or simply a provider. The provider architecture supports the development of these plug-replaceable components. A set of security providers is included in the IBM Java SDKs.

More information about implementing your own security provider is at: http://java.sun.com/j2se/1.4.2/docs/guide/security/HowToImplAProvider.html

A list of sample IBM providers follows: IBMJCE Java Cryptographic Extension IBMJCECCA JCE using z/OS hardware cryptographic services JDK V5.0 and later.

102 System z Cryptographic Services and z/OS PKI Services IBMJSSE Java Secure Sockets Extension (SSL and TLS). IBMSJSSE2 Java Secure Sockets Extension (SSL and TLS). JSSE2 is aliased in JDK 5 and in the preceding item as JSSE. IBMJAAS Java Authentication and Authorization Service.

IBMJGSS Generic Security Services: Kerberos and GSS-API (JDK V1.4.0 and later only). IBMPKCS11 Use hardware cryptography using the Public Key Cryptography Standards# 11 (PKCS# 11 standard) IBMSASL Simple Authentication and Security Layer

5.2.1 How to select a provider (registering a provider in the java.security file)

All providers supported are listed in the java.security file. This file is located in the $JAVA_HOME/lib/security folder. A snapshot of the java.security file follows: # # List of providers and their preference orders (see above): # security.provider.1=com.ibm.crypto.hdwrCCA.provider.IBMJCECCA security.provider.2=com.ibm.jsse2.IBMJSSEProvider2 security.provider.3=com.ibm.crypto.provider.IBMJCE security.provider.4=com.ibm.security.jgss.IBMJGSSProvider security.provider.5=com.ibm.security.cert.IBMCertPath security.provider.6=com.ibm.security.sasl.IBMSASL

Many algorithms - as many as possible - are run using the hardware cryptography of the system. Requests for algorithms that are not supported by IBMJCECCA are automatically forwarded to the next provider in line - in this case, IBMJCE - (and the algorithm is therefore executed by software only). Because of the large scope of algorithms covered by IBMJCE, if IBMJCE had been first in the list, no request would be forwarded to IBMJCECCA, and the hardware cryptography would not be used.

It is important to note that the order in which the different security providers have been listed is significant. Incorrect ordering can result in exceptions that are difficult to troubleshoot. If a java program attempts to use a security provider that is not listed in the java.secuirty file, a java.security.NoSuchProviderException is thrown.

5.2.2 JCE - Java Cryptography Extension

The Java Cryptography Extension (JCE) is a set of packages that implement the cryptography API in Java. These packages were previously a part of the extension library, but they now form a part of the regular Java distribution. In general, Java Cryptography Extension provides a framework and implementation for encryption, key generation and key agreement, and MAC algorithms. Support for encryption includes symmetric, asymmetric, block, and stream ciphers. The software also supports secure streams and sealed objects. JCE supplements the Java 2 platform, which already includes interfaces and implementations of message digests and digital signatures. When the JCE APIs are used, cryptography is performed via software.

Chapter 5. Java cryptography 103 5.2.3 JCECCA - JCE using CCA hardware cryptographic devices on z/OS

The IBMJCECCA implementation adds a provider that extends JCE and Java Cryptography Architecture (JCA) to seamlessly add hardware cryptography capabilities via the IBM Common Cryptographic Architecture (CCA) interfaces. This provider takes advantage of hardware cryptography within the existing JCE architecture and gives Java 2 programmers the significant security and performance advantages of hardware cryptography with minimal changes to existing Java applications. Because the complexities of hardware cryptography are taken care of within the normal JCA, advanced security and performance using hardware cryptographic devices is made easily available.

The IBMJCECCA provides the following: Message digest via the MD2, MD5, and SHA-1 algorithms Signature and KeyFactory classes Symmetric algorithms DES, Triple-DES (also known as TDES), HMAC, and PBE Asymmetric algorithms RSA encryption and decryption with zero padding and PKCS 1 type 2 padding Digital signature and verification via the RSA and DSA algorithms

Note: DSA is not supported on a T-Rex.

True random-number generation, key generation via key factories, key and certificate generation, and key and certificate management via a keytool application IBMJCECCA uses hardware cryptography to implement those engines that can use the hardware function available through IBM CCA. Thus, some JCE functions are available through this hardware implementation (IBMJCECCA) and others - those functions that the CCA hardware cannot perform - are available only through a software cryptography provider such as IBMJCE.

Note: Consider the following when working with Java cryptography: IBMJCECCA provider extends and replaces the former IBMJCE4758 provider that was available with prior releases of the IBM SDK. At this time the IBMJCE4758 and the IBMJCECCA providers are functionally equivalent, however we strongly recommend that you install and use the IBMJCECCA.

IBM CCA is a set of software elements that provide common application interfaces to secure, high-speed cryptographic services on various platforms via hardware cryptographic devices. These devices include the IBM CCA PCICC and the Cryptographic Coprocessor Feature. The amount and type of hardware cryptographic services available depends on your platform and hardware device. For more information, refer to your platform’s hardware cryptography information and service and support organization and “Configuring and using hardware cryptographic devices” for more information.

5.2.4 CertPath - Certificate generation and path validation

The Java Certification Path (CertPath) defines a set of classes and interfaces to create, build, and validate digital certification paths. A digital certificate is a data structure of the binding between a subject and a public key signed by a certificate authority (CA). In practice the CAs may have their own certificates issued by a higher-level authority. To verify the binding, a value chain of certificates must be found from end entity certificates up to a CA that is

104 System z Cryptographic Services and z/OS PKI Services recognized and trusted. The process of validating certificate chains is an important part of PKI-enabled systems.

IBM provides Java Certification Path as a part of the standard distribution of the Java SDK platform. The ibmcertpathprovider.jar file contains the necessary interfaces and classes for CertPath. This file can be found in the $JAVA_HOME/lib folder on your machine.

CertPath uses services from the IBM PKCS package, which is pre-installed. The Java Certification Path API is based on the cryptographic service provider architecture.

5.2.5 JSSE - Java Secure Sockets Extension (SSL and TLS)

IBM Java Secure Sockets Extension (IBMJSSE) provider is an API that implements Secure Sockets Layer (SSL) V3.0 and Transport Layer Security (TLS) V1.0 as Java 2 standard extensions. The IBMJSSE provider is a 100% pure Java implementation, with no underlying calls to System SSL. The expense of using System SSL through JNI™ (Java Native Interface) to C and C++ is avoided when using IBMJSSE; IBMJSSE is the preferred method for making SSL and TLS connections for Java applications.

This API provides authentication, integrity, and privacy at the transport level. The code to establish a connection, exchange key information, and encrypt data is all run under the covers. Any data exchange between sockets can be secured using these APIs. Using SSL from the IBMJSSE provider secures browser-to-Web-server communication.

IBMJSSE supports common security algorithms including RSA, DSA, DES, AES, TDES, and RC4.

5.2.6 Map the providers and algorithms

The following list maps providers with supported algorithms: IBMJCE supported algorithms – AES (EBC, CBC, CFB, OFB, PCBC) – DES (EBC, CBC, CFB, OFB, PCBC) – DES-EDE (EBC, CBC, CFB, OFB, PCBC) – Password Based Encryption (PBE) – Blowfish – Diffie - Hellman Key Agreement – HMAC-MD5, HMAC-SHA-1 –MD2, MD5 – SHA-1, SHA-2, SHA-3, SHA-5 – MD2withRSA, MD5withRSA – SHA-1 with RSA, SHA-1 with DSA –RSA – PKCS5Padding – RC2 (EBC, CBC, CFB, OFB, PCBC) – RC4 –Seal –Mars IBMJCECCA supported algorithms – DES (EBC, CBC, CFB, OFB, PCBC) – DES-EDE (EBC, CBC, CFB, OFB, PCBC) – Password Based Encryption (PBE) – HMAC-MD2, HMAC-MD5, HMAC-SHA-1

Chapter 5. Java cryptography 105 –MD2, MD5 –SHA – MD2withRSA, MD5withRSA – SHA-1 with RSA, SHA-1 with DSA –RSA

– PKCS5Padding IBMJCE4578 supported algorithms –MD2, MD5 –SHA – MD2withRSA, MD5withRSA – SHA-1 with RSA – SecureRandom IBMJSSE supported algorithms –RSA –DSA – DES, TDES –SHA –MD5 – RC2, RC4 – Diffie-Hellman IBMSJSSE2 supported algorithms –RSA –DSA – DES, TDES –SHA –MD5 – RC2, RC4 – Diffie-Hellman IBMJGSS supported algorithms –DS –TDES – RC4-HMAC –HMAC-MD5 IBMPKCS11 supported algorithms – DES, TDES –RSA –DSA – PKCS11DeviceRNG – IBMSecureRandom – PKCS11MPLKS

5.3 Setting up hardware cryptographic features

Programmers have several options when customizing an application to take advantage of hardware cryptographic devices. This customization is all done through class loading the security providers in a specific order. IBM offers these options for customizing applications: Editing the java.security file Adding Java virtual machine (JVM) system arguments Programmatically loading the security provider list

106 System z Cryptographic Services and z/OS PKI Services

Note: In addition to setting up Java to take advantage of cryptographic hardware, ICSF must also be initialized and running.

The java.security file The java.security file can be found in the $JAVA_HOME/lib/security folder in your system. Before attempting to use any provider, make sure that the entry for that provider is made in this file. For example, if you wish to use the IBMJCCA provider, make sure that an entry is made in the java.security file. A snapshot of this file follows: # # List of providers and their preference orders (see above): # security.provider.1=com.ibm.crypto.hdwrCCA.provider.IBMJCECCA security.provider.2=com.ibm.jsse2.IBMJSSEProvider2 security.provider.3=com.ibm.crypto.provider.IBMJCE security.provider.4=com.ibm.security.jgss.IBMJGSSProvider security.provider.5=com.ibm.security.cert.IBMCertPath security.provider.6=com.ibm.security.sasl.IBMSASL

Important: The order in which the providers are listed may impact the operations of the applications on your system and may even lead to errors that are difficult to troubleshoot. Different types of applications may require that the security providers be listed in a different order. We have discovered several ways of working around this problem: 1. Maintain multiple security files. 2. Install multiple Java instances. 3. Add a provider at run time using the Security.insertProviderAt() method. 4. Maintain a list of providers using the JCE_PROVIDER_LIST when using OpenPGP.

5.3.1 Policy files

Due to governmental export regulations, JDKs are set up with limited cryptographic functionality. For fully functional cryptography, you must install the unrestricted policy files. They are located at: http://www.ibm.com/servers/eserver/zseries/software/java/j5jcecca.html

Copy the unrestricted policy files to $JAVA_HOME/lib/security. Make sure that the old policy files are replaced or moved out of the JDK file system.

Note: The policy files can also be located in: $JAVA_HOME/demo/jce/policy-files/unrestricted/

5.4 Keystore and SAF digital certificates (keyrings)

A keystore is a database that stores a collection of symmetric and asymmetric keys protected by a symmetric algorithm. Key entries hold sensitive cryptographic key information. Typically, key entries are secret keys or a private key and the certificate chain for the corresponding public key. Private keys and certificate chains are used by a given entity for authentication. A trusted certificate entry contains a single public key certificate belonging to another party. A

Chapter 5. Java cryptography 107 certificate is defined as trusted when the owner trusts the fact that the public key contained in the certificate corresponds to the identity in the subject of the certificate. This entry can be used to validate other parties. System Authorization Facility (SAF) digital certificates are created and stored in the System Authorization Facility. They are aggregated for applications that use via SAF keyrings. In addition to implementing SAF interfaces for certificate and key management, storing certificate and keymaterial in a SAF database adds another layer of security for protecting keys.

SAF does not support symmetric keys. Certificates stored in a RACF keyring are always accompanied by a public key and optionally accompanied by a private key to create an asymmetric key pair.

SAF digital certificates can also take advantage of ICSF and hardware cryptographic functions.

5.4.1 JCEKS

Java Cryptographic Extension Keystore (JCEKS) is a UNIX System Services Java file-based keystore that is supported on all platforms where the an IBM SDK runs. This keystore is password protected and Triple Data Encryption Standard (DES) encrypted. You can use several ways to transport and share a JCEKS, including but not limited to FTP and e-mail. Public and private keys can be exported from a JCEKS keystore and imported into a JCEKS or RACF keyring (using the JCECCAKS keystore).

iKeyman and the Java keytool command can be used to manipulate a JCEKS keystore.

Additional information about keytool can be found at: ftp://ftp.software.ibm.com/s390/java/jce/keytool.html

In the examples in the sections that follow, we generate a public and private key pair, create a self-signed certificate, and export a self-signed certificate. The exported self-signed certificate can be submitted to a third-party certificate authority. When the certificate authority sends back a certificate response, it can then be imported back into the JCEKS keystore.

Script notes You can cut and paste the following examples into script files and execute them. If you plan to run them from the command line, make sure to strip out the backslash characters (\). If you plan to enter these commands in the OMVS command line, you might run out of space. If that happens, either run the commands from a script, or create environment variables to shorten the commands. Using a telnet daemon, rlogin daemon, or SSH daemon does not present these problems.

In Example 5-1, we generate an RSA algorithm private and public key pair. The keypass flag is used to protect the private key with a password, and the storepass value flag is used to set the password of the keystore itself. In Example 5-1, the key alias is rsa2048Cert, the distinguished name of the subject is IBM, and the keystore file name is testkeys.jcks. The password used to protect this keystore is passphrase, and the expiration of the certificate is 999 days. The key size generated is 2048 bits in length.

Example 5-1 Keytool generating a public and private key pair keytool -genkey \ -alias rsa2048Cert \ -dname "CN=IBM"

108 System z Cryptographic Services and z/OS PKI Services -keystore testkeys.jcks \ -provider IBMJCE \ -keyalg RSA \ -keysize 2048 -keypass "passphrase" \

-storepass "passphrase" \ -storetype JCEKS \ -validity 999

Tip: Keytool commands must be typed on a single line. If you choose to copy these examples into a script file, the backslash character (\) can be used to span lines and improve readability. When you use OEDIT in OMVS, watch out for hidden characters that might break the script. You can use the following command to view all hidden characters: hex on

The caveat, however, is that hex on does not show if spaces are included at the end of the line. If you use telnet/rlogin/ssh to connect to OMVS vi or emacs, make sure no characters at all, including spaces, follow the backslash character.

In Example 5-2, the certificate with an alias of rsa2048Cert1 is exported to the file rsa2048Cert1.cer. This is a binary certificate format and does not include private key information. If the -rfc flag is used, the certificate is exported in a printable encoding format, as defined by the Internet RFC 1421 standard. If the -pkcs12 flag is used, the certificate created conforms to the pkcs12 file format, and both public and private keymaterial are exported and symmetrically encrypted.

Example 5-2 Export public key into a file keytool -export \ -file rsa2048Cert1.cer \ -keystore testkeys.jcks \ -alias rsa2048Cert1 \ -storepass passphrase \ -storetype JCEKS \ -provider IBMJCE \ -keypass passphrase

In Example 5-3, we import our certificate back into the keystore, as a trusted certificate entry. If we had sent the exported certificate to a third-party certificate authority (CA), we would import the fulfilled certificate returned to us. This certificate file can be imported into other keystores.

Example 5-3 Import a trusted certificate keytool -import \ -file rsa2048Cert1.cer \ -keystore testkeys.jcks \ -alias CArsa2048 \ -storepass passphrase \ -storetype JCEKS \ -provider IBMJCE \ -keypass passphrase

Chapter 5. Java cryptography 109 Example 5-4 shows the command for listing a JCEKS keystore. This command does not list private key information.

Example 5-4 List a keystore keytool -list \ -keystore testkeys.jcks \ -storetype jceks \ -storepass passphrase

Output from the list command looks similar to Example 5-5.

Example 5-5 Output from keytool list Keystore type: jceks Keystore provider: IBMJCE

Your keystore contains 2 entries

rsa2048Cert1, Sep 18, 2006, keyEntry, Certificate fingerprint (MD5): 93:CB:BB:04:B4:A5:9B:42:D6:C9:3C:05:FF:8B:E8:15 CArsa2048, Sep 18, 2006, trustedCertEntry, Certificate fingerprint (MD5): E0:BD:75:2B:50:06:EA:C9:F7:BE:5E:8D:EC:4B:11:A3

5.4.2 JCECCAKS

JCECCAKS is a Java file keystore type, which is supported by the Java Development Kit (JDK) V5.0, that takes advantage of ICSF. This keystore is password protected and Triple DES encrypted, and the keymaterial is protected by hardware in one of three ways: CLEAR (or LABEL), PKDS, or RETAINED. We suggest that you do not use RETAINED with most cryptographic applications. You can also create JCECCAKS keystores using the script in Example 5-6 on page 112. To use it, you must replace the provider with the IBMJCECCA provider and replace the keystore type with JCECCAKS. The hardware type can be changed from PKDS to CLEAR or RETAINED, depending on the type and level of hardware security you want.

If JCECCAKS is specified with the CLEAR option, a public and private key pair can be exported in a pkcs12 file using the IBMJCECCA provider. This option is supported only in JDK V5.0 and later.

110 System z Cryptographic Services and z/OS PKI Services Figure 5-7 provides a graphic overview of IBMJCECCA.

Figure 5-7 JCECCAKS overview

Script notes You can cut and paste the following examples into script files and execute them. If you plan to run them from the command line, make sure to strip out the backslash characters (\). If you plan to enter these commands in the OMVS command line, you might run out of space. If that happens, either run the commands from a script or create environment variables to shorten the commands. Using a telnet daemon, rlogin daemon, or SSH daemon does not present these problems.

Note: To create and use keystores of type JCECCAKS, the java.security file located in $JAVA_HOME/lib/security/ needs to include the JCECCA provider in the list - similar to this: security.provider.1=com.ibm.jsse.IBMJSSEProvider security.provider.2=com.ibm.crypto.hdwrCCA.provider.IBMJCECCA security.provider.3=com.ibm.crypto.provider.IBMJCE

The script in Example 5-6 on page 112 demonstrates how to generate a public and private key pair using the hwkeytool. In this example, we create an alias of rsa2048hdwrCert1 with a distinguished name of IBM and store the certificate in the keystore testkeys.cca. The IBMJCE4758 provider is used with the RSA algorithm and a key size of 2048 bits. The store type is JCE4758KS; the private keymaterial is stored in a PKDS. The keypass and keystore

Chapter 5. Java cryptography 111 password are both passphrase. The IBMJCE4758 used in the samples is now obsolete and has currently been replaced by IBMJCECCA, providing the same functionalities.

Example 5-6 Generate a JCE4758KS public and private key pair hwkeytool -genkey \ -alias rsa2048hdwrCert1 \ -dname "CN=IBM" \ -keystore testkeys.cca \ -provider IBMJCE4758 \ -keyalg RSA \ -keysize 2048 \ -storetype JCE4758KS \ -keypass "passphrase" \ -storepass "passphrase" \ -hardwaretype PKDS

In Example 5-7, the certificate with an alias of rsa2048hdwrCert1 is exported to the file rsa2048hdwrCert1.cer. This is a binary certificate format and does not include private key information. If the -rfc flag is used, the certificate is exported in a printable encoding format, as defined by the Internet RFC 1421 standard. If the -pkcs12 flag is used, the certificate created conforms to the pkcs12 file format, and both public and private keymaterial is exported but only if the specified alias is of type CLEAR.

Example 5-7 Export a certificate from a JCE4758KS hwkeytool -genkey \ -alias rsa2048hdwrCert1 \ -dname "CN=IBM" \ -keystore testkeys.cca \ -provider IBMJCE4758 \ -keyalg RSA \ -keysize 2048 \ -storetype JCE4758KS \ -keypass "passphrase" \ -storepass "passphrase" \ -hardwaretype PKDS

In Example 5-8, we import our certificate back into the keystore as a trusted certificate entry. If we had sent the exported certificate to a third-party CA, we would import the fulfilled certificate that was returned to us. This certificate file can be imported into other keystores. The noprompt flag tells the hwkeytool that we will import the trusted entry without prompting, even though a copy of the public key already exists in the keystore.

Example 5-8 Importing a trusted certificate using hwkeytool hwkeytool -import \ -alias CArsa2048hdwr \ -noprompt \ -file rsa2048hdwr.cer \ -storetype jce4758ks \ -storepass passphrase \ -keypass passphrase \ -keystore testkeys.cca \ -hardwaretype PKDS \ -provider IBMJCE4758 -v

112 System z Cryptographic Services and z/OS PKI Services Example 5-9 shows the command for listing a JCE4758KS keystore. Use the -v flag to print extended information. This command does not list private key information. If the private key information is stored in PKDS or RETAINED, the tool prints the pointer to the key entry. Example 5-9 Listing a keystore with hwkeytool hwkeytool -list \ -keystore testkeys.cca \ -storetype jce4758ks

Sample output from the hwkeytool is shown in Example 5-10.

Example 5-10 Output from hwkeytool

Keystore type: JCE4758KS Keystore provider: IBMJCE4758

Your keystore contains 2 entries

Alias name: rsa2048ccacert1 Creation date: Sep 18, 2006 Entry type: keyEntry Certificate chain length: 1 Certificate[1]: Owner: CN=rsa4758Cert1 Issuer: CN=rsa4758Cert1 Serial number: 450f2c79 Valid from: Mon Sep 18 16:32:09 MST 2006 until: Sun Dec 17 16:32:09 MST 2006 Certificate fingerprints: MD5: 07:0A:29:00:F7:3D:AB:02:1E:2A:A5:A8:ED:F9:E3:C4 SHA1: E3:80:25:32:8E:A3:C4:05:5B:EF:3F:5E:F8:40:ED:C1:6C:5A:47:5E

******************************************* *******************************************

Alias name: carsa2048 Creation date: Sep 18, 2006 Entry type: trustedCertEntry

Owner: CN=rsa4758Cert1 Issuer: CN=rsa4758Cert1 Serial number: 450f2c79 Valid from: Mon Sep 18 16:32:09 MST 2006 until: Sun Dec 17 16:32:09 MST 2006 Certificate fingerprints: MD5: 07:0A:29:00:F7:3D:AB:02:1E:2A:A5:A8:ED:F9:E3:C4 SHA1: E3:80:25:32:8E:A3:C4:05:5B:EF:3F:5E:F8:40:ED:C1:6C:5A:47:5E ******************************************* *******************************************

Chapter 5. Java cryptography 113 5.4.3 JCERACFKS JCERACFKS uses SAF and RACF services to protect keymaterial and certificates. For SAF

and RACF stored keyrings, the RACF RACDCERT command is the interface used to manage the keyring. The RACDCERT command is discussed in 6.3.2, “RACF panels and RACDCERT commands” on page 171 and in the z/OS Security Server RACF Command Language Reference, SA22-7687. This publication can be found in the z/OS Internet library at the Web site: http://publibz.boulder.ibm.com/epubs/pdf/ichza460.pdf

The following facility classes control access to RACDCERT command: IRR.DIGTCERT.ADD IRR.DIGTCERT.ALTER IRR.DIGTCERT.DELETE IRR.DIGTCERT.LIST IRR.DIGTCERT.ADDRING IRR.DIGTCERT.DELRING IRR.DIGTCERT.LISTRING IRR.DIGTCERT.CONNECT IRR.DIGTCERT.REMOVE IRR.DIGTCERT.MAP IRR.DIGTCERT.LISTMAP IRR.DIGTCERT.ALTMAP IRR.DIGTCERT.DELMAP IRR.DIGTCERT.REKEY IRR.DIGTCERT.ROLLOVER IRR.DIGTCERT.LIST IRR.DIGTCERT.LISTRING

The command used in Example 5-11 generates a self-signed certificate authority certificate. You can use the MatchKeys tool to check the public and private key pairs.

Example 5-11 Generate a CA RACDCERT CERTAUTH GENCERT SUBJECTSDN(CN(‘ITSO’)O(‘IBM’)C(‘US’)) WITHLABEL(‘LocalCertAuth’) SIZE(1024)

Tip: In OMVS, a single quote and a parenthesis must be preceded by a backslash (\). The command given in Figure 5-11 should look as follows: SYS1> tso “RACDCERT CERTAUTH GENCERT SUBJECTSDN$CN\(\'ITSO\'$O$\'IBM\'$C$\'US\'$\) WITHLABEL$\'LocalCertAuth\'$ SIZE$1024$

The command in Example 5-12 generates an RSA key pair signed with the local certificate authority certificate that was created with the previous command.

Example 5-12 Generate a personal certificate RACDCERT GENCERT SUBJECTSDN(CN(‘ITSO’) O(‘IBM’) C(‘US’)) WITHLABEL(‘RSACert1’) SIZE(1024) SIGNWITH(CERTAUTH LABEL(‘LocalCertAuth’))

114 System z Cryptographic Services and z/OS PKI Services If you are going to send the certificate for third-party verification, it must be exported as a certificate request. The command in Example 5-13 generates the request and stores it into the data set hlq.PUBKEY.REQUEST.ITSO. Example 5-13 Generate a certificate request

RACDCERT GENREQ (LABEL(‘RSACert1’)) DSN(’hlq.PUBKEY.REQUEST.ITSO’)

After this certificate is sent to a third party and verified, a response is sent, and we can receive it into hlq.THIRD.PARTY.CERT. You should also add to the ring the CA that signed this certificate. The command in Example 5-14 adds the certificate response into RACF.

Example 5-14 Import a certificate from a data set RACDCERT ADD(‘hlq.THIRD.PARTY.CERT’) TRUST WITHLABEL(’RSACert1’)

Next, we must create a keyring and connect our certificates to the keyring. The command in Example 5-15 creates the ITSOring keyring.

Example 5-15 Create a new ring RACDCERT ADDRING(ITSOring)

Now that we have created the keyring, we can add our certificates to it using the two commands in Example 5-16.

Example 5-16 Connect certificates to a ring RACDCERT CONNECT(CERTAUTH LABEL(‘LocalCertAuth’) RING(ITSOring)) RACDCERT CONNECT(LABEL(‘RSACert1’)RING(ITSOring) USAGE(PERSONAL) DEFAULT)

Note: When using a RACF keyring with Java applications, a keyring is not read successfully, unless a CERTAUTH certificate is on the ring. When the CERTAUTH certificate is not present, you will receive a CertPath not verified error.

This error also occurs if a SITE certificate that signed the personal certificate is on the ring: A CERTAUTH certificate must be on the ring.

To share data with Business Partners, their public keys are imported into RACF and connected to the keyring that an application is set up to use. To export a public key to send to a Business Partner, issue the command shown in Example 5-17.

Example 5-17 Export a certificate with a public key

RACDCERT EXPORT (LABEL(‘RSACert1’)) DSN(’hlq.PUBKEY.1024.ITSO’) FORMAT(CERTDER)

This data set is then sent to Business Partners, and they can add it to their keystore and use the label to encrypt data that they send to you. You should validate with your Business Partners or remote sites where you trust a common certificate authority (CA), whether third-party or self-signed, depending on your business and security practices. This certificate can be imported into the keystore that is used by an application at your Business Partners’ locations. This enables everyone in the trust network to verify that the keys used to encrypt data are in fact part of the trust network.

Chapter 5. Java cryptography 115

Note: The RACDCERT command can be used to list other users’ certificates and keyrings when the appropriate permissions to the irr.digtcert.* classes are added. However, another

user’s private key information can never be read. You must consider this when setting up an application to run under a specific user account.

Best practices When connecting certificates to a keyring, the whole certificate chain should be connected to the ring. This allows the Certificate Path to be verified.

TIP: To verify that the user ID running Java has sufficient authority, you can issue the following hwkeytool command from OMVS: hwkeytool -debug -J-Djava.protocol.handler.pkgs=com.ibm.crypto.provider -list -keystore safkeyring://USERID/ITSOring -storetype JCERACFKS

5.4.4 JCECCARACFKS

The JCECCARACFKS SAF keyrings store certificate information in RACF, securing private keymaterial in a PKDS protected by ICSF. These keyrings are available on z/OS only. They are created and managed through the RACDCERT or equivalent SAF certificate-management command. Figure 5-8 illustrates an overview of JCECCARACKFKS.

Figure 5-8 JCECCARACFKS overview

JCECCARACFKS keyrings are similar to keystores created with the PKDS option to the hwkeytool command. Instead of storing certificates in a file stored in UNIX System Services, the certificates are stored in a RACF keyring, protected by and managed with RACF or an equivalent SAF provider. The JCECCARACFKS keyring is supported in JDK V5.0.

The following facility classes control access to RACDCERT command: IRR.DIGTCERT.ADD IRR.DIGTCERT.ALTER IRR.DIGTCERT.DELETE

116 System z Cryptographic Services and z/OS PKI Services IRR.DIGTCERT.LIST IRR.DIGTCERT.ADDRING IRR.DIGTCERT.DELRING IRR.DIGTCERT.LISTRING IRR.DIGTCERT.CONNECT

IRR.DIGTCERT.REMOVE IRR.DIGTCERT.MAP IRR.DIGTCERT.LISTMAP IRR.DIGTCERT.ALTMAP IRR.DIGTCERT.DELMAP IRR.DIGTCERT.REKEY IRR.DIGTCERT.ROLLOVER IRR.DIGTCERT.LIST IRR.DIGTCERT.LISTRING

RACDCERT keywords Two keywords used in conjunction with the RACDCERT command take advantage of cryptographic hardware: ICSF PCICC

They specify how RACF should generate the key pair and how the private key should be stored for future use. If PCICC is specified, the key pair is generated using PCICC, PCIXCC, or CEX2. When ICSF is specified, the key pair is generated using software. In either case, the resulting private key is generated with the RSA algorithm and stored in the ICSF PKDS.

If either keyword, PCICC or ICSF, is specified and ICSF is not operational or is not configured for PKA operations, processing stops, and an error message displays. If the PCICC keyword is specified, a PCI, PCI-X, or Express2 cryptographic coprocessor must also be present and operational. Otherwise, processing stops and an error message displays.

If the key is stored as either an ICSF key or a PCICC key, any system using the key in the future is required to have ICSF operational and configured for PKA operations with this PKDS. For a PCICC key, any system using the key in the future would also need to have PCICC, PCIXCC, or CEX2 present and operational with this PKDS.

The ICSF keyword adds private keymaterial to the PKDS with a generated label. The PCICC keyword enables you to specify the PKDS label. The command in Example 5-18 generates a personal certificate that is signed with the CA LocalRACF CA and stores it in a PKDS with the PKDS label ITOPS.EKM.CERT with the EKMServer alias.

Example 5-18 .Generate a personal certificate with an alias of EKMServer RACDCERT ID(EKMSERV) GENCERT SUBJECTSDN(CN(‘ITOperations’) O(‘MyCo’) C(‘US’)) WITHLABEL(‘EKMServer’) PCICC(ITOPS.EKM.CERT) SIZE(2048) SIGNWITH(CERTAUTH LABEL(‘LocalRACF CA’))

Note that the following options of the GENCERT command are release dependent: For z/OS R1.8 [ PCICC[(pkds-label | * )] | ICSF[(pkds-label | * )] | DSA ] For z/OS R1.7 [ PCICC | ICSF | DSA]

In the following examples, the key label is automatically generated.

Chapter 5. Java cryptography 117 This command (see Example 5-19) generates a self-signed certificate authority certificate. Example 5-19 Generate a CA

RACDCERT CERTAUTH GENCERT SUBJECTSDN(CN(‘ITSO’)O(‘IBM’)C(‘US’)) PCICC WITHLABEL(‘LocalCertAuth’) SIZE(1024)

Tip: In OMVS, a single quote and a parenthesis must be preceded by a backslash (\). SYS1> tso “RACDCERT CERTAUTH GENCERT SUBJECTSDN$CN\(\'ITSO\'$O$\'IBM\'$C$\'US\'$\) PCICC WITHLABEL$\'LocalCertAuth\'$ SIZE$1024$

The command shown in Example 5-20 generates a RSA key pair signed with the local certificate authority certificate created with the command shown in Example 5-19.

Example 5-20 Generate a personal certificate RACDCERT GENCERT SUBJECTSDN(CN(‘ITSO’) O(‘IBM’) C(‘US’)) PCICC WITHLABEL(‘RSACert1’) SIZE(1024) SIGNWITH(CERTAUTH LABEL(‘LocalCertAuth’))

If you are going to send the certificate to third-party verification, it has to be exported as a certificate request. The command shown in Example 5-21 generates the request and stores it into the data set hlq.PUBKEY.REQUEST.ITSO.

Example 5-21 Generate a certificate request RACDCERT GENREQ (LABEL('RSACert1')) DSN('hlq.PUBKEY.REQUEST.ITSO')

After this certificate is sent to a third party and verified, a response is sent, and we can receive it into hlq.THIRD.PARTY.CERT. The command in Example 5-22 adds the certificate response into RACF. You should also add the CA that was used to sign this certificate to the ring.

Example 5-22 Import a certificate from a data set RACDCERT ADD(‘hlq.THIRD.PARTY.CERT’) TRUST ICSF WITHLABEL(’RSACert1’)

Next, we must create a keyring and connect our certificates to the keyring. The command shown in Example 5-23 creates the ITSOring keyring.

Example 5-23 Create a new ring RACDCERT ADDRING(‘ITSOring’)

Now that we have a keyring, we can add our certificates to it using the two commands in Example 5-24.

Example 5-24 Connect certificates to a ring RACDCERT CONNECT(CERTAUTH LABEL(‘LocalCertAuth’) RING(‘ITSOring’)) RACDCERT CONNECT(LABEL(‘RSACert1’)RING(ITSOring) USAGE(PERSONAL) DEFAULT)

118 System z Cryptographic Services and z/OS PKI Services

Note: When using a RACF keyring with Java applications, a keyring is not read successfully, unless a CA is on the ring. If a CA is not on the ring, you receive a CertPath

not verified error.

This error also occurs when a SITE certificate that signed the personal certificate is on the ring. A CA must be on the ring.

To share data with Business Partners, their public keys are imported into RACF and connected to the keyring that the application is set up to use. To export a public key to send to a Business Partner, issue the command shown in Example 5-25.

Example 5-25 Export a certificate with a public key RACDCERT EXPORT (LABEL(‘RSACert1’)) DSN(’hlq.PUBKEY.1024.ITSO’) FORMAT(CERTDER)

This data set is then sent to a Business Partner. The Business Partner adds it to the Business Partner’s keystore and uses the label to encrypt data that the Business Partner sends to you. t Note: Use the RACDCERT command to list other users’ certificates and keyrings when the appropriate permissions to the irr.digtcert.* classes are added. However, another user’s private key information can never be read. When setting up an application to run under a specific user account, you must consider this.

You should validate with your Business Partners or remote sites that you trust a common certificate authority (CA), whether third-party or self-signed, depending on your business and security practices. This CA certificate can be imported into the keystore that is used by the application at your Business Partners’ locations. This enables everyone in the trust network to verify that the keys used to encrypt data are in fact part of the trust network.

Best practices When connecting certificates to a keyring, the whole certificate chain should be connected to the ring. This allows the Certificate Path to be verified.

TIP: To verify a Java application has sufficient authority, the following hwkeytool command can be issued from OMVS: hwkeytool -debug -J-Djava.protocol.handler.pkgs=com.ibm.crypto.hdwrCCA.provider -list -keystore safkeyring://USERID/ITSOring -storetype JCERACFKS

The provider list in the java.security file located in $JAVA_HOME/lib/security directory should contain the com.ibm.crypto.hdwrCCA.provider.IBMJCECCA hardware provider for a JCECCARACFKS. The provider should be defined according to the following syntax: security.provider.1=com.ibm.jsse.IBMJSSEProvider security.provider.2=com.ibm.crypto.hdwrCCA.provider.IBMJCECCA security.provider.3=com.ibm.crypto.provider.IBMJCE security.provider.4=com.ibm.security.cert.IBMCertPath

Chapter 5. Java cryptography 119 5.5 Tools

The following sections describe the software and hardware tools available for managing keys and certificates.

5.5.1 Software keytool

A keytool is a key and certificate-management utility. It enables users to administer their own public and private key pairs and associated certificates. It also enables users to cache the public keys (in the form of certificates) of their communicating peers.

keytool stores the keys and certificates in a keystore. The default keystore implementation implements the keystore as a file. Using keytool, it is possible to display, import, and export certificates. It is also possible to generate self-signed certificates. keytool currently handles X.509 certificates.

5.5.2 Hardware keytool

You can secure the keymaterial using hardware cryptographic services on z/O: CLEAR Stores the key in an external hardware key structure where cleartext is tokenized into a CCA external token. This service provides the greatest hardware performance and most vulnerable hardware security. PKDS Public and private key data set. This hardware type encrypts the private key with the system master key. The cleartext version of this key can never be viewed or retrieved. The key pair is stored in a system key storage area. Compared with CLEAR and RETAINED key types, PKDS provides medium hardware security and medium throughput. RETAINED This hardware type stores the private key actual hardware device and can never be viewed or retrieved in the clear. It offers the maximum security for keys. It is also the slowest because cryptographic calls for a specific key pair must go to the hardware device that holds that key pair. When using this hardware type, applications are completely tied to the physical device.

5.5.3 Different characteristics of keystores

On WebSphere Application Server distributed systems, the certificates in a keystore are usually stored in a file. In WebSphere Application Server V6.1 for z/OS the certificates in a keystore can be stored in a file or in the SAF database. The actual public and private keys for the corresponding certificates can be stored in a file or SAF database, or in hardware, depending on the provider and keystore being used. The IBMJCE and IBMJCECCA providers support various keystore types that can be selected depending on the use of the location of certificates and keys.

Table 5-3 compares the characteristics of the IBMJCE and IBMJCECCA providers based on the keystore types.

Table 5-3 IBMJCE and IBMJCECCA comparison based on keystore types Provider Keystore Certificate Key Use WebSphere Tooling name type location location hardware path

IBMJCECCA JCERACFKS RACF RACF Yes safkeyring:// RACF

120 System z Cryptographic Services and z/OS PKI Services Provider Keystore Certificate Key Use WebSphere Tooling name type location location hardware path

JCECCARA RACF Hardware Yes safkeyringhw:// RACF CFKS

JCECCAKS File Hardware Yes path/file hwkeytool

IBMJCE JKS File File system No path/file WAS JCEKS ikeyman keytool

JCERACFKS RACF RACF No safkeyring:// RACF

5.6 Java examples

The sections that follow provide Java examples that illustrate cryptographic features on z/OS. We begin by presenting examples of standalone Java programs using different keystores and algorithms for signing and encryption. We also present an example for generating random numbers, which is followed by SOAP examples to demonstrate hardware cryptography for message-level and transport layer encryption. All the examples in the sections that follow have been created on the following software versions: IBM Java (JDK V5.0) RAD V7.1 WebSphere Application Server V6.1

Note: For a description of the error codes you can receive while executing the hardware crypto APIs, refer to Appendix A, “ICSF and TSS Return and Reason Codes” in the z/OS V1R6.0 ICSF Application Programmer’s Guide, SA22-7522: http://publibz.boulder.ibm.com/cgi-bin/bookmgr_OS390/BOOKS/CSFB4Z50

5.6.1 RSA encryption and decryption

This section describes how to encrypt and decrypt using RSA.

Using IBMJCECCAKS In Example 5-26, a certificate and a reference to its corresponding private key are obtained from a file, /u/kimmh/crypto/testkeys.cca. To gain an access to the file, a password is required as a store password. Once the keystore is loaded, a certificate can be retrieved, and then the public key can also be available for use. In the same way, a reference to the private key for RSA is obtained using the same label name as it is created. Keystore Type: IBMJCECCAKS Keystore: PKDS

Example 5-26 RSA encryption and decryption using IBMJCECCAKS import java.io.FileInputStream; import java.security.KeyStore; import java.security.PrivateKey; import java.security.PublicKey;

Chapter 5. Java cryptography 121 import java.security.cert.Certificate; import java.security.Signature; import javax.crypto.Cipher; public class RSACryptoPKDS {

public byte[] encrypt(byte[] plainText) throws Exception { FileInputStream storeStreamHW; KeyStore keyStoreHW; char[] storepass = "passphrase".toCharArray(); Certificate cert; PublicKey pubKey; byte[] cipherText;

Cipher rsaCipherHW = Cipher.getInstance("RSA", "IBMJCECCA");

// Load keystore from IBMJCECCAKS, and get the public key from the cerficate keyStoreHW = KeyStore.getInstance("JCECCAKS", "IBMJCECCA"); storeStreamHW = new FileInputStream("/u/kimmh/crypto/testkeys.cca"); keyStoreHW.load(storeStreamHW, storepass); storeStreamHW.close(); cert = keyStoreHW.getCertificate("rsa2kcert"); pubKey = cert.getPublicKey();

// Encrypt the requested message by RSA algorithm rsaCipherHW.init(Cipher.ENCRYPT_MODE, pubKey); cipherText = rsaCipherHW.doFinal(plainText);

return cipherText; }

public byte[] decrypt(byte[] cipherText) throws Exception { KeyStore keyStoreHW; FileInputStream storeStreamHW; char[] storepass = "passphrase".toCharArray(); Cipher rsaCipherHW = Cipher.getInstance("RSA", "IBMJCECCA"); PrivateKey privKey; byte[] decryptedText;

// Load keystore from IBMJCECCAKS, and get the private key for RSA decryption keyStoreHW = KeyStore.getInstance("JCECCAKS", "IBMJCECCA"); storeStreamHW = new FileInputStream("/u/kimmh/crypto/testkeys.cca"); keyStoreHW.load(storeStreamHW, storepass); storeStreamHW.close();

// Decrypt the encrypted text by RSA decryption algorithm privKey = (PrivateKey)keyStoreHW.getKey("rsa2kcert", storepass); rsaCipherHW.init(Cipher.DECRYPT_MODE, privKey); decryptedText = rsaCipherHW.doFinal(cipherText);

return decryptedText; }

public static void main(String[] args) throws Exception { byte[] plainText = "This is a secure message.".getBytes();

122 System z Cryptographic Services and z/OS PKI Services byte[] cipherText, decryptedText;

RSACryptoPKDS rsaCryptoPKDS = new RSACryptoPKDS(); cipherText = rsaCryptoPKDS.encrypt(plainText); decryptedText = rsaCryptoPKDS.decrypt(cipherText);

System.out.println("Original text : " + new String(plainText)); System.out.println("Decrypted text : " + new String(decryptedText)); } }

IBMJCECCARACFKS In Figure 5-27 on page 150, RACFInputStream is used to access and load a RACF keystore.

RACFInputStream contains three parameters: user ID- A string containing the ID of the user that owns the keyring ring ID- A string containing the name of the RACF keyring password - A character array containing the password for the keystore

The rest of the RSA encryption and decryption is the same as shown in Example 5-27.

Example 5-27 RSA encryption and decryption using IBMJCECCARACFKS import java.security.KeyStore; import java.security.PrivateKey; import java.security.PublicKey; import java.security.cert.Certificate; import java.security.Signature; import javax.crypto.Cipher; import com.ibm.crypto.hdwrCCA.provider.RACFInputStream; public class RSACryptoRACF {

public byte[] encrypt(byte[] plainText) throws Exception { RACFInputStream ksStream; KeyStore keyStoreRACF; Certificate cert; PublicKey pubKey; byte[] cipherText;

Cipher rsaCipherHW = Cipher.getInstance("RSA", "IBMJCECCA");

// Load keystore from IBMJCECCARACFKS, // and get the public key from the cerficate ksStream = new RACFInputStream("kimmh", "Java.test", null); keyStoreRACF = KeyStore.getInstance("JCECCARACFKS"); keyStoreRACF.load(ksStream, null); ksStream.close(); cert = keyStoreRACF.getCertificate("rsa2048cert"); pubKey = cert.getPublicKey();

// Encrypt the requested message by RSA algorithm rsaCipherHW.init(Cipher.ENCRYPT_MODE, pubKey);

Chapter 5. Java cryptography 123 cipherText = rsaCipherHW.doFinal(plainText);

return cipherText; }

public byte[] decrypt(byte[] cipherText) throws Exception { RACFInputStream ksStream; KeyStore keyStoreRACF; Cipher rsaCipherHW = Cipher.getInstance("RSA", "IBMJCECCA"); PrivateKey privKey; byte[] decryptedText;

// Load keystore from IBMJCECCARACFKS, // and get the private key for RSA decryption ksStream = new RACFInputStream("kimmh", "Java.test", null); keyStoreRACF = KeyStore.getInstance("JCECCARACFKS"); keyStoreRACF.load(ksStream, null); ksStream.close(); privKey = (PrivateKey)keyStoreRACF.getKey("rsa2048cert", null);

// Decrypt the encrypted text by RSA decryption algorithm rsaCipherHW.init(Cipher.DECRYPT_MODE, privKey); decryptedText = rsaCipherHW.doFinal(cipherText);

return decryptedText; }

public static void main(String[] args) throws Exception { byte[] plainText = "This is a secure message.".getBytes(); byte[] cipherText, decryptedText;

RSACryptoRACF rsaCryptoRACF = new RSACryptoRACF(); cipherText = rsaCryptoRACF.encrypt(plainText); decryptedText = rsaCryptoRACF.decrypt(cipherText);

System.out.println("Original text : " + new String(plainText)); System.out.println("Decrypted text : " + new String(decryptedText)); } }

5.6.2 RSA signature

This section describes how to use an RSA signature.

IBMJCECCAKS In Example 5-28, SHA-1 with the RSA signature algorithm is used.

Example 5-28 Retrieving a certificate with SHA-1 and RSA signature import java.io.FileInputStream; import java.security.KeyStore; import java.security.PrivateKey; import java.security.PublicKey; import java.security.cert.Certificate; import java.security.Signature;

124 System z Cryptographic Services and z/OS PKI Services import javax.crypto.Cipher; public class RSASignPKDS { public byte[] sign(byte[] message) throws Exception {

KeyStore keyStoreHW; FileInputStream storeStreamHW; char[] storepass = "passphrase".toCharArray(); Signature rsaSignHW = Signature.getInstance("SHA1withRSA", "IBMJCECCA"); PrivateKey privKey; byte[] rsaSignature;

// Load the keystore from PKDS and sign the message keyStoreHW = KeyStore.getInstance("JCECCAKS", "IBMJCECCA"); storeStreamHW = new FileInputStream("/u/kimmh/crypto/testkeys.cca"); keyStoreHW.load(storeStreamHW, storepass); storeStreamHW.close(); privKey = (PrivateKey)keyStoreHW.getKey("rsa2kcert", storepass);

// Sign the requested message using RSA signing algorithm rsaSignHW.initSign(privKey); rsaSignHW.update(message); rsaSignature = rsaSignHW.sign();

return rsaSignature; }

public boolean verify(byte[] message, byte[] rsaSignature) throws Exception { KeyStore keyStoreHW; FileInputStream storeStreamHW; char[] storepass = "passphrase".toCharArray(); Signature rsaSignHW = Signature.getInstance("SHA1withRSA", "IBMJCECCA"); Certificate cert; PublicKey pubKey; boolean isVerified;

/* Load the keystore from PKDS and verify the signature */ keyStoreHW = KeyStore.getInstance("JCECCAKS", "IBMJCECCA"); storeStreamHW = new FileInputStream("/u/kimmh/crypto/testkeys.cca"); keyStoreHW.load(storeStreamHW, storepass); storeStreamHW.close(); cert = keyStoreHW.getCertificate("rsa2kcert"); pubKey = cert.getPublicKey();

// Verify the RSA signature with the given message // using RSA signature verification algorithm rsaSignHW.initVerify(pubKey); rsaSignHW.update(message); isVerified = rsaSignHW.verify(rsaSignature);

return isVerified; }

public static void main(String[] args) throws Exception { RSASignPKDS rsaSignPKDS = new RSASignPKDS();

Chapter 5. Java cryptography 125 byte[] message = "This is a signature using SHA1-RSA.".getBytes(); byte[] rsaSignature; boolean rsaVerified;

rsaSignature = rsaSignPKDS.sign(message);

rsaVerified = rsaSignPKDS.verify(message, rsaSignature);

System.out.println("verification result = " + rsaVerified); } }

IBMJCECCARACFKS

in the RSA encryption and decryption example. In Example 5-29, SHA-1 with RSA signature algorithm is used.

Example 5-29 Retrieving a certificate using SHA-1 and RSA signature import java.io.FileInputStream; import java.security.KeyStore; import java.security.PrivateKey; import java.security.PublicKey; import java.security.cert.Certificate; import java.security.Signature; import javax.crypto.Cipher; import com.ibm.crypto.hdwrCCA.provider.RACFInputStream;

public class RSASignRACF {

public byte[] sign(byte[] message) throws Exception { RACFInputStream ksStream; KeyStore keyStoreRACF; Signature rsaSignHW = Signature.getInstance("SHA1withRSA", "IBMJCECCA"); PrivateKey privKey; byte[] rsaSignature;

// Load the keystore from RACFKS and sign the message ksStream = new RACFInputStream("kimmh", "Java.test", null); keyStoreRACF = KeyStore.getInstance("JCECCARACFKS"); keyStoreRACF.load(ksStream, null); ksStream.close(); privKey = (PrivateKey) keyStoreRACF.getKey("rsa2048cert", null);

// Sign the requested message using RSA signing algorithm rsaSignHW.initSign(privKey); rsaSignHW.update(message); rsaSignature = rsaSignHW.sign();

return rsaSignature; }

public boolean verify(byte[] message, byte[] rsaSignature) throws Exception { RACFInputStream ksStream; KeyStore keyStoreRACF; Signature rsaSignHW = Signature.getInstance("SHA1withRSA", "IBMJCECCA");

126 System z Cryptographic Services and z/OS PKI Services Certificate cert; PublicKey pubKey; boolean isVerified;

// Get a certificate from RACF keyring,

// and obtain the public key from the certificate ksStream = new RACFInputStream("kimmh", "Java.test", null); keyStoreRACF = KeyStore.getInstance("JCECCARACFKS"); keyStoreRACF.load(ksStream, null); ksStream.close(); cert = keyStoreRACF.getCertificate("rsa2048cert"); pubKey = cert.getPublicKey();

// Verify the RSA signature with the given message // using RSA signature verification algorithm rsaSignHW.initVerify(pubKey); rsaSignHW.update(message); isVerified = rsaSignHW.verify(rsaSignature);

return isVerified; }

public static void main(String[] args) throws Exception { RSASignRACF rsaSignRACF = new RSASignRACF(); byte[] message = "This is a signature using SHA1-RSA algo.".getBytes(); byte[] rsaSignature; boolean rsaVerified;

rsaSignature = rsaSignRACF.sign(message); rsaVerified = rsaSignRACF.verify(message, rsaSignature);

System.out.println("verification result = " + rsaVerified); } }

5.6.3 Symmetric key encryption

The sections that follow provide examples of symmetric key encryption.

DES with CKDS Example 5-30 demonstrates the use of CKDS, where the DES key is stored. To access CKDS, the SecretKeyFactory class is used. Notice that the algorithm parameters used for encryption should be stored and passed to the decryption function.

Example 5-30 DES encryption/decryption using keys in CKDS import javax.crypto.Cipher;

import javax.crypto.SecretKey; import java.security.AlgorithmParameters; import com.ibm.crypto.hdwrCCA.provider.*; import javax.crypto.SecretKeyFactory; import java.security.KeyFactory;

public class DESwithCKDS {

Chapter 5. Java cryptography 127 static final byte[] plainText = "secret Message".getBytes();

public static void main(String argv[]) throws Exception { SecretKeyFactory keyFactory; Cipher aliceCipher;

SecretKey DESKey; KeyLabelKeySpec spec; SecretKeyFactory KeyFactory;

byte[] cipherText, decryptedText;

// Retrieve encrypted DES Key from CKDS keyFactory = SecretKeyFactory.getInstance("DES", "IBMJCECCA"); spec = new KeyLabelKeySpec("KAPRE.DATAKEY"); DESKey = keyFactory.generateSecret(spec);

// Encrypt the message using DES encryption algorithm aliceCipher = Cipher.getInstance("DES/CBC/PKCS5Padding", "IBMJCECCA"); aliceCipher.init(Cipher.ENCRYPT_MODE, DESKey); cipherText = aliceCipher.doFinal(plainText);

// For decryption, algorithm parameters used for encryption should be stored byte[] encodedParams = aliceCipher.getParameters().getEncoded(); AlgorithmParameters params = AlgorithmParameters.getInstance("DES"); params.init(encodedParams);

// DES decryption using encrypted DES Key within CKDS aliceCipher.init(Cipher.DECRYPT_MODE, DESKey, params); decryptedText = aliceCipher.doFinal(cipherText);

System.out.println("Original text : " + new String(plainText)); System.out.println("Decrypted text : " + new String(decryptedText)); } }

TDES with CKDS Using Triple-DES (or TDES - see Example 5-31) is the same process as shown in Example 5-30 on page 127.

Example 5-31 TDES encryption/decryption using keys in CKDS import javax.crypto.Cipher; import javax.crypto.SecretKey; import java.security.AlgorithmParameters; import com.ibm.crypto.hdwrCCA.provider.*; import javax.crypto.SecretKeyFactory; import java.security.KeyFactory;

public class TDESwithCKDS { static final byte[] plainText = "secret Message".getBytes();

public static void main(String argv[]) throws Exception { SecretKeyFactory keyFactory; Cipher aliceCipher; SecretKey TDESKey;

128 System z Cryptographic Services and z/OS PKI Services KeyLabelKeySpec spec; SecretKeyFactory KeyFactory;

byte[] cipherText, decryptedText;

// Retrieve encrypted 3DES Key from CKDS keyFactory = SecretKeyFactory.getInstance("DESede", "IBMJCECCA"); spec = new KeyLabelKeySpec("ITSO.CLEAR.TDESKEY"); TDESKey = keyFactory.generateSecret(spec); System.out.println("Key : " + TDESKey);

// Encrypt the message using 3DES encryption algorithm aliceCipher = Cipher.getInstance("DESede/CBC/PKCS5Padding", "IBMJCECCA"); aliceCipher.init(Cipher.ENCRYPT_MODE, TDESKey); cipherText = aliceCipher.doFinal(plainText);

// DES decryption using encrypted 3DES Key within CKDS aliceCipher.init(Cipher.DECRYPT_MODE, TDESKey, params); decryptedText = aliceCipher.doFinal(cipherText);

System.out.println("Original text : " + new String(plainText)); System.out.println("Decrypted text : " + new String(decryptedText)); } }

AES with CKDS Using AES (see Example 5-32) is the same process as shown in the DES example (Example 5-31 on page 128).

Example 5-32 AES encryption/decryption using keys in CKDS import javax.crypto.Cipher; import javax.crypto.SecretKey; import java.security.AlgorithmParameters; import com.ibm.crypto.hdwrCCA.provider.*; import javax.crypto.SecretKeyFactory; import java.security.KeyFactory; public class AESwithCKDS { static final byte[] plainText = "secret Message".getBytes();

public static void main(String argv[]) throws Exception { SecretKeyFactory keyFactory; Cipher aliceCipher; Cipher bobCipher; SecretKey AESKey = null; KeyLabelKeySpec spec = null; SecretKeyFactory KeyFactory = null; byte[] encodedParams;

Chapter 5. Java cryptography 129

byte[] cipherText, decryptedText;

// Retrieve encrypted AES Key from CKDS keyFactory = SecretKeyFactory.getInstance("AES", "IBMJCECCA");

spec = new KeyLabelKeySpec("ITSO.CLEAR.AES128"); AESKey = keyFactory.generateSecret(spec);

// Encrypt the message using AES encryption algorithm aliceCipher = Cipher.getInstance("AES/CBC/PKCS5Padding", "IBMJCECCA"); aliceCipher.init(Cipher.ENCRYPT_MODE, AESKey); cipherText = aliceCipher.doFinal(plainText);

// For decryption, algorithm parameters used for encryption should be stored encodedParams = aliceCipher.getParameters().getEncoded(); AlgorithmParameters params = AlgorithmParameters.getInstance("AES"); params.init(encodedParams);

// AES decryption using encrypted AES Key within CKDS bobCipher = Cipher.getInstance("AES/CBC/PKCS5Padding", "IBMJCECCA"); bobCipher.init(Cipher.DECRYPT_MODE, AESKey, params); decryptedText = bobCipher.doFinal(cipherText);

System.out.println("Cipher text : " + new String(cipherText)); System.out.println("Decrypted text : " + new String(decryptedText)); } }

5.6.4 Generating a true random number

A true random-number generator is offered by the hardware cryptography (see Example 5-33). The SecureRandom class is used for this purpose.

Example 5-33 Generate a true random number via cryptographic hardware import java.security.*;

public class GenRandomNumber {

public static byte[] getRandomNumber() throws Exception { SecureRandom secRandom;

secRandom = SecureRandom.getInstance("IBMSecureRandom", "IBMJCECCA"); byte bytes[] = new byte[20]; secRandom.nextBytes(bytes);

System.out.println(toHexString(bytes));

return bytes; }

public static void main(String args[]) throws Exception { GenRandomNumber.getRandomNumber(); }

130 System z Cryptographic Services and z/OS PKI Services // Converts a byte to hex digit and writes to the supplied buffer private static void byte2hex(byte b, StringBuffer buf) { char[] hexChars = { '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'A', 'B', 'C', 'D', 'E', 'F'}; int high = ((b & 0xf0) >> 4);

int low = (b & 0x0f); buf.append(hexChars[high]); buf.append(hexChars[low]); }

// Converts a byte array to hex string private static String toHexString(byte[] block) { StringBuffer buf = new StringBuffer(); int len = block.length; for (int i = 0; i < len; i++) { byte2hex(block[i], buf); if (i < len-1) { buf.append(":"); } } return buf.toString(); } }

5.6.5 Hashing a message

Example 5-34 is a SHA-1 hashing example using the IBMJCECCA provider.

Example 5-34 Hash a message using SHA-1 via IBMJCECCA provider import java.security.*;

public class SHA1Hash {

public static byte[] doSHA1(byte[] message) throws Exception { byte[] hashValue;

MessageDigest md = MessageDigest.getInstance("SHA1", "IBMJCECCA"); md.update(message); hashValue = md.digest();

return hashValue; }

public static void main(String argv[]) throws Exception { byte[] message = "This is a messaged to be hased using SHA1.".getBytes(); byte[] hashValue;

hashValue = SHA1Hash.doSHA1(message); System.out.println("Message : " + new String(message)); System.out.println("Hash : " + toHexString(hashValue)); }

// Converts a byte to hex digit and writes to the supplied buffer

Chapter 5. Java cryptography 131 private static void byte2hex(byte b, StringBuffer buf) { char[] hexChars = { '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'A', 'B', 'C', 'D', 'E', 'F'}; int high = ((b & 0xf0) >> 4); int low = (b & 0x0f);

buf.append(hexChars[high]); buf.append(hexChars[low]); }

5.6.6 Exporting keys from software to hardware keystores

Exporting a key from the software to hardware keystores involves first exporting the software key to a PKCS12 format and then importing the key into the hardware keystore.

We begin by generating a key using the keytool utility as follows: keytool -genkey -alias rsa2048Cert -dname "CN=IBM" -keystore testkeys.jcks -provider IBMJCE -keyalg RSA -keysize 2048 -keypass "passphrase" -storepass "passphrase" -storetype JCEKS -validity 999

The execution of this command generates the key in the file testkeys.jkcs. Once this key has been generated, we can export it to a PKCS12 format. The following command exports the software key generated previously to a PKCS12 format: keytool -export -file rsa2048Cert2.p12 -keystore testkeys.jcks -alias rsa2048Cert -storepass passphrase -storetype JCEKS -provider IBMJCE -keypass passphrase -pkcs12

The rsa2048Cert2.p12 file contains the key in PKCS12 format. At this point we import the key to the hardware keystore, which we can do by using the hwkeytool utility using the following command: hwkeytool -import -alias rsa2048Cert -noprompt -file rsa2048Cert2.p12 -storetype JCECCAKS -storepass passphrase -keypass passphrase -keystore testkeys.cca -hardwaretype PKDS -provider IBMJCECCA -v -pkcs12 Note that a file called testkeys.cca was created. This file contains the public key and certificate corresponding to the private key stored in the hardware.

132 System z Cryptographic Services and z/OS PKI Services We can use the software public key to encrypt some text and the hardware key to decrypt this text. Example 5-35 uses the keys generated previously to illustrate the use of software and hardware keys. Example 5-35 Use software and hardware keys import java.io.FileInputStream; import java.security.KeyStore; import java.security.PrivateKey; import java.security.PublicKey; import java.security.cert.Certificate; import javax.crypto.Cipher; public class SwEncryptHwDecrypt { /* * In this example will demonstrate encryption * with software key and ecryption with hardware * key. */ public static void main(String[] args) { try { byte[] plainText = "This is plain text".getBytes(); KeyStore keyStore2 = KeyStore.getInstance ("JCEKS", "IBMJCE");

char[] storePass = "passphrase".toCharArray(); char[] keyPass = "passphrase".toCharArray(); FileInputStream fis = new FileInputStream ("/u/kapre/testkeys.jcks"); keyStore2.load(fis, storePass);

//Retrieve the private key PrivateKey privKey = (PrivateKey)keyStore2.getKey ("rsa2048Cert", keyPass);

//Retrieve the public key Certificate cert2 = keyStore2.getCertificate ("rsa2048Cert"); PublicKey pubKey =(PublicKey)cert2.getPublicKey();

//Use public key for encryption Cipher cp1 = Cipher.getInstance("RSA", "IBMJCE"); cp1.init(Cipher.ENCRYPT_MODE, pubKey); byte[] cipherText = cp1.doFinal(plainText);

System.out.println ("Encrypted text : " + new String(cipherText));

//Use private key for decryption Cipher cp2 = Cipher.getInstance("RSA", "IBMJCECCA"); cp2.init(Cipher.DECRYPT_MODE, privKey); byte[] convertedText = cp2.doFinal(cipherText);

Chapter 5. Java cryptography 133

System.out.println ("Decrypted text : " + new String(convertedText)); } catch (Exception ex)

{ ex.printStackTrace(); }

} }

5.6.7 Hybrid encryption

Example 5-36 illustrates the hybrid encryption approach explained in “Hybrid encryption approach” on page 97. Alice encrypts a message using the TDES key and encrypts the TDES key using Bob’s public key, which is called key wrapping. Alice sends the ciphertext and the wrapped TDES key to Bob. Receiving them, Bob unwraps the TDES key using its private key and then decrypts the cipher test via TDES.

Example 5-36 Hybrid encryption example import java.security.Key; import java.security.KeyPairGenerator; import java.security.KeyPair; import java.security.PublicKey; import java.security.PrivateKey; import java.security.AlgorithmParameters; import javax.crypto.KeyGenerator; import javax.crypto.Cipher;

public class HybridEncryption {

public static void main(String args[]) throws Exception { byte[] cipherText, decryptedText; byte[] wrappedKey; AlgorithmParameters params;

Bob bob = new Bob(); Alice alice = new Alice();

String message = "This is a message from Muhyun Kim to Wooyoung Kwon" + " using 3DES and RSA Key wrapping technique.";

System.out.println("Original message : " + message);

// Alice encrypts a message and send it to Bob as follows // 1. Obtain Bob's public key // 2. Encrypt a message using 3DES // 3. Encrypt 3DES key using Bob's public key (Key Wrapping) // 4. Store the algorithm parameter used to 3DES encryption alice.setPublicKeyofBob(bob.getPublicKey()); cipherText = alice.encrypt(message); wrappedKey = alice.getWrapped3DESKey();

134 System z Cryptographic Services and z/OS PKI Services params = alice.getAlgoParams();

// Bob decrypts the received cipher text and wrapped 3DES key bob.init3DES(wrappedKey, params); decryptedText = bob.decrypt(cipherText);

System.out.println("Decrypted message : " + new String(decryptedText)); } } class Alice { Key tdesKey; PublicKey bobPublicKey; AlgorithmParameters params;

// Alice creates 3DES key for encryption public Alice() throws Exception { KeyGenerator keyGen;

keyGen = KeyGenerator.getInstance("DESede", "IBMJCECCA"); tdesKey = keyGen.generateKey(); }

// Set Bob's public key for Wrapping 3DES key public void setPublicKeyofBob(PublicKey rsaPub) { bobPublicKey = rsaPub; }

// Encrypt the given message using 3DES public byte[] encrypt(String message) throws Exception { Cipher aliceCipher; byte[] plainText; byte[] cipherText; byte[] encodedParams;

plainText = message.getBytes();

aliceCipher = Cipher.getInstance("DESede/CBC/PKCS5Padding", "IBMJCECCA"); aliceCipher.init(Cipher.ENCRYPT_MODE, tdesKey); cipherText = aliceCipher.doFinal(plainText);

encodedParams = aliceCipher.getParameters().getEncoded(); params = AlgorithmParameters.getInstance("DESede"); params.init(encodedParams);

return cipherText; }

// Returns the algorithm parameters public AlgorithmParameters getAlgoParams() { return params; }

// Wrap the 3DES key using RSA encryption public byte[] getWrapped3DESKey() throws Exception {

Chapter 5. Java cryptography 135 Cipher rsaCipher; byte[] wrappedKey; rsaCipher = Cipher.getInstance("RSA","IBMJCECCA"); rsaCipher.init(Cipher.WRAP_MODE, bobPublicKey,

(AlgorithmParameters)null, null); wrappedKey = rsaCipher.wrap(tdesKey); return wrappedKey; } }

class Bob { Key unwrappedDesKey; AlgorithmParameters params;

PublicKey rsaPub; PrivateKey rsaPriv;

// Bob creates its RSA key pair via IBMJCECCA (hardware crypto) public Bob() throws Exception { KeyPairGenerator rsaKeyPairGen; KeyPair rsaKeyPair;

rsaKeyPairGen = KeyPairGenerator.getInstance("RSA","IBMJCECCA"); rsaKeyPairGen.initialize(1024); rsaKeyPair = rsaKeyPairGen.generateKeyPair(); rsaPub = rsaKeyPair.getPublic(); rsaPriv = rsaKeyPair.getPrivate(); }

// Returns Bob's public key public PublicKey getPublicKey() { return rsaPub; }

// Initialize 3DES using the given wrapped 3DES key, and algorithm parameters public void init3DES(byte[] wrappedKey, AlgorithmParameters algoParams) throws Exception { Cipher rsaCipher; rsaCipher = Cipher.getInstance("RSA","IBMJCECCA"); rsaCipher.init(Cipher.UNWRAP_MODE, rsaPriv,(AlgorithmParameters)null, null); unwrappedDesKey = rsaCipher.unwrap(wrappedKey, "DESede", Cipher.SECRET_KEY); params = algoParams; }

// Decrypt the given cipher text public byte[] decrypt(byte[] cipherText) throws Exception { Cipher bobCipher; byte[] decryptedText; bobCipher = Cipher.getInstance("DESede/CBC/PKCS5Padding", "IBMJCECCA"); bobCipher.init(Cipher.DECRYPT_MODE, unwrappedDesKey, params); decryptedText = bobCipher.doFinal(cipherText);

136 System z Cryptographic Services and z/OS PKI Services return decryptedText; } }

5.7 SOAP examples

This section discusses the use of cryptography features to achieve message-level encryption. We begin by creating a small Web service application using Rational® Application Developer (RAD) V7.0, and then we test this application on a local machine before deploying it to WebSphere Application Server V6.1.

Suppose a customer wants to enquire about details related to a credit card. The details may include sensitive information such as an outstanding balance. In such communications, we cannot pass values in the clear. We therefore encrypt the messages originating from the customer and the server.

This exercise is divided into the following parts: “Setting up the servers” “Creating the Web service project”

Setting up the servers To set up the servers, complete the following steps: 1. Start RAD and access the File → New → Other menu option (see Figure 5-9).

Figure 5-9 Set up the server using RAD

Chapter 5. Java cryptography 137 2. Double-click the Server option (see Figure 5-10).

Figure 5-10 Define a new server

3. Leave the server name as localhost and the server type as WebSphere V6.1 Server. In addition, leave all the other settings at their default values and click the Finish button. This should create the server for the test environment.

Creating the Web service project To create the Web service project, complete the following steps: 1. From the RAD, choose the File → New → Project menu option. You should access a panel where you can select Dynamic Web Project and then click the Next button (see Figure 5-11).

Figure 5-11 Define a new project

138 System z Cryptographic Services and z/OS PKI Services 2. Enter the name of the project as CreditCardEnquiryService, leave the other entries at their default values, and click the Finish button (see Figure 5-12).

Figure 5-12 Project details definition

3. Right-click the CreditCardEnquiryService project in the Project Explorer and select New → WSDL from the Web Services node (see Figure 5-13).

Figure 5-13 Select the WSDL wizard

Chapter 5. Java cryptography 139 4. Enter the file name as CreditCardEnquiryService.wsdl and press the Next button (see Figure 5-14).

Figure 5-14 Define the WSDL file

5. Leave all the values as defaults and click the Finish button (see Figure 5-15).

Figure 5-15 WSDL definition

6. Make sure you change the wsdl definitions to match the code in Example 5-37.

Example 5-37 WSDL definition sample

140 System z Cryptographic Services and z/OS PKI Services

Chapter 5. Java cryptography 141 7. The WSDL file was used to create the Web service. Right-click the WSDL file and click the Web Services → Generate JavaBean Skeleton menu option (see Figure 5-16).

Figure 5-16 Generate the JavaBean skeleton

142 System z Cryptographic Services and z/OS PKI Services 8. Set the two sliders to Test Service and Test Client, respectively (see Figure 5-17). Also click the Monitor the Web service option. Then click the Next button.

Figure 5-17 Web services definition

Chapter 5. Java cryptography 143 9. From the Security Configuration drop-down (see Figure 5-18), select the Encryption option and click the Next button. A warning dialog is displayed indicating that the Web service may not comply with the WS-I simple SOAP binding profile. Click the Ignore All button.

Figure 5-18 Web services JavaBean configuration

10.In the next panel, click the Start Server button. 11.After the server has started, you are prompted to choose the platform where the Web service should be tested. Leave the selection at its default value and click the Next button (see Figure 5-19).

Figure 5-19 Test the Web service

144 System z Cryptographic Services and z/OS PKI Services 12.On the next panel, leave the different options at their default values and click the Next button. You are prompted with a warning that the Web service may not comply with the WS-I simple SOAP binding profile. Click the Ignore All button. 13.In the next panel (see Figure 5-20), uncheck all the methods except the creditCardEnquiry method and click the Finish button.

Figure 5-20 Test the generated code

14.The Web services utility generated a lot of code. You can find the file CreditCardEnquirySOAPImpl.java and make sure the creditCardEnquiry() method contains the code shown in Example 5-38. The server automatically takes care of deploying the new code.

Example 5-38 Verify the generated code public com.ibm.itso.www.CreditCardEnquiryResponseParams creditCardEnquiry (com.ibm.itso.www.CreditCardEnquiryRequestParams parameters) throws java.rmi.RemoteException { com.ibm.itso.www.CreditCardEnquiryResponseParams responseParams = new CreditCardEnquiryResponseParams();

responseParams.setCreditCardActiveOrNot("Y"); responseParams.setCreditCardHolderAddress("Sample Address"); responseParams.setCreditCardHolderName("First Middle Last"); responseParams.setCreditCardNumber("1234-5678-9012-3456"); responseParams.setCreditCardOutstandingBalance(3245.12);

return responseParams; }

Chapter 5. Java cryptography 145 15.In the project explorer, right-click CreditCardEnquiryService.wsdl and select the Generate Client option from the Web Services menu (see Figure 5-21).

Figure 5-21 Test the new application

16.Set the slider on Test client and check the Monitor Service check box. Click the Next button (see Figure 5-22.

Figure 5-22 Start monitoring

146 System z Cryptographic Services and z/OS PKI Services 17.In the panel shown in Figure 5-23, set the Security configuration as XML Encryption and click the Next button.

Figure 5-23 Set the security configuration

18.In the panel shown in Figure 5-24, uncheck all methods but the creditCardEnquiry method and click the Finish button.

Figure 5-24 Test the generated application

19.Enable monitoring on the server for which you plan to deploy this application. Make sure that monitoring is enabled for the correct ports.

Chapter 5. Java cryptography 147 20.In the generated test client, click the creditCardEnqiry link in the Methods frame. Enter any dummy value in the Inputs frame and click the Invoke button (see Figure 5-25).

Figure 5-25 Click the creditCardEnquiry link

148 System z Cryptographic Services and z/OS PKI Services 21.The panel shown in Figure 5-26 displays the TCP/IP Monitor, from which it can be clearly seen that the requests and responses are encrypted.

Figure 5-26 Monitor and verify the application

22.Now we can deploy and use hardware cryptography on z/OS. We start by creating the EAR file for this application, deploying it on the server. Make sure that the correct server addresses are updated in the WSDL file before deploying the application on the server. The client will be running on the local box. 23.In the Java instance in $WAS_INSTALL_ROOT, edit the java.security file and make sure that the IBMJCECCA provider is uncommented and is the first provider in the listing (with the index 1). This file is in the EBCDIC format and must be converted to ASCII format before editing. Restart the WebSphere Application Server V6.1 instance. 24.Access Enterprise Applications → CreditCardEnquiryServiceEAR → Manage Modules → CreditCardEnquiryService.war → Web services: Server security bindings → Request consumer (receiver) binding → Key locators page and make

Chapter 5. Java cryptography 149 sure that a key locator with the settings displayed in Figure 5-27 is created for Request consumer (receiver) bindings.

Figure 5-27 Verify the key locator definition

150 System z Cryptographic Services and z/OS PKI Services 25.Similarly, make sure that settings set in the previous step are created for Response generator (sender) binding (see Figure 5-28).

Figure 5-28 Verify the response generator binding definition

26.Save the configurations and close the Integrated Solutions Console. 27.Now access the client from RAD and try to access the service that is deployed on WebSphere Application Server V6.1 running on z/OS. The encrypted messages can be viewed from the TCP/IP Monitor.

5.8 Configuring SLL for WebSphere Application Server hardware cryptography

This section explains how to enable hardware cryptography in SSL for WebSphere Application Server V6.1.

As described in 5.7, “SOAP examples” on page 137, hardware-based cryptography is automatically used when the IBMJCECCA provider is listed at the top of the java.security file. In addition to the JCEKS keystore, other keystore types can be used. For information about configuring the JCE provider, refer to step 23 on page 149. Hardware cryptography for HTTPS Web services Web services messages also can be secured by TLS (Transport Layer Security). Because HTTP is the Web service most widely used, we briefly describe how to configure HTTPS for Web services in this section.

Chapter 5. Java cryptography 151 A minimal setup procedure for enabling HTTPS Web services involves the following steps: 1. Enable SSL in WebSphere Application Server. 2. Add the certificate of the Web services server into the trust store of the Web services client.

3. Change WSDL file of the Web services client to use HTTPS instead of HTTP.

The following is a list of tasks that you can perform to register the Web services server certificate for a Web service client in a WebSphere Application Server V6.1 environment. 1. Check the SSL configuration for a trust store name: a. In the WebSphere Administrative Console, go to Security → SSL certificate and key management → SSL configurations → NodeDefaultSSLSettings. b. Under the Trust store name field (see Figure 5-29), you can check the keystore for the trust store, which is used to register the server’s certificate. In this example, NodeDefaultTrustStore is used.

Figure 5-29 SSL configuration

152 System z Cryptographic Services and z/OS PKI Services 2. Retrieve the Web services server’s certificate online: Go to SSL certificate and key management → Key stores and certificates → NodeDefaultTrustStore → Signer certificates → Retrieve from port. Fill in the Host, Port, and Alias fields, and click the Retrieve signer information button. Then, the certificate is retrieved from the server and its detail information is shown. Then click the Apply button (see Figure 5-30).

Figure 5-30 Retrieved certificate of Web services server

Chapter 5. Java cryptography 153 3. Change the WSDL file of web service client. 4. Finally, you must modify the WSDL file of the Web services client to use HTTPS. In this SOAP example, we changed the address from http://wtsc60.itso.ibm.com:9108 to https://wtsc60.itso.ibm.com:9109, where 9109 is the SSl port in the ITSO configuration. The port binding definition for HTTP Web services is shown in Example 5-39 (the address location changes are in bold).

Example 5-39 Port binding definition for HTTP Web service

The port binding definition for HTTPS Web services is shown in Example 5-40 (again, (the address location changes are in bold).

Example 5-40 Port binding definition for HTTPS Web service

For more information about Web services TLS, refer to “Securing Web services applications at the transport level” at: http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp

154 System z Cryptographic Services and z/OS PKI Services

Chapter 6. z/OS PKCS#11

With z/OS V1.9, ICSF supports PKCS#11, providing an alternative to the IBM Common Cryptographic Architecture and broadening the scope of cryptographic applications that can make use of System z cryptography.

In this chapter, we describe PKCS#11 support and discuss the following topics: “Public Key Cryptography Standard #11 (PKCS#11)” on page 156 “z/OS PKCS#11 infrastructure and setup” on page 158 “z/OS PKCS#11 token administration” on page 163 “z/OS PKCS#11 programming example” on page 194

RSA Laboratories of RSA Security, Inc., offers its Public Key Cryptography Standards (PKCS) to developers of computers that use public key and related technology. PKCS#11, also known as Cryptoki, is the cryptographic token interface standard. It specifies an API to devices, referred to as tokens, that hold cryptographic information and perform cryptographic functions.

The PKCS#11 API is an industry-accepted standard commonly used by cryptographic applications. The PKCS#11 standard is defined on the RSA Laboratories Web site at: http://www.rsasecurity.com/rsalabs/PKCS/

6.1.1 PKCS#11 concepts

On most single-user systems, a token is a smart card or other plug-installed cryptographic device, accessed through a card reader or slot. The PKCS#11 specification assigns numbers to slots, known as slot IDs. An application identifies the token that it wants to access by specifying the appropriate slot ID. On systems that have multiple slots, the application determines which slot to access.

PKCS#11 tokens are typically created in a factory and initialized either before they are installed or upon their first use. Because PKCS#11 token are usually physical hardware devices, the PKCS#11 specification provides no mechanism for deleting tokens.

The PKCS#11 logical view of a token is a device that stores objects and can perform cryptographic functions. PKCS#11 defines three types of objects: A data object that is defined by an application. A certificate object that stores a certificate. A key object that stores a key. The key can be a public key, a private key, or a secret key.

Objects are also classified according to their lifetime and visibility. Token objects are visible to all applications connected to the token that have sufficient permission and remain on the token even after the sessions - connections between an application and the token - are closed, and the token is removed from its slot. Session objects are more temporary, and when a session is closed by any means, all session objects created by that session are automatically destroyed. Furthermore, session objects are visible only to the application that created them.

Attributes are characteristics that distinguish an instance of an object. General attributes in PKCS#11, distinguish, for example, whether the object is public or private. Other attributes are specific to a particular type of object, such as a Modulus or exponent for RSA keys.

The PKCS#11 standard was designed for systems that grant access to token information based on a PIN. The standard recognizes two types: Security officer (SO) Standard user (USER)

The role of the SO is to initialize a token (zeroize the content) and set the User’s PIN. The SO can also access public objects on the token but not private ones. The User can access private objects on the token. Access is granted only after the User has been authenticated. Users can also change their own PINs. Users cannot, however, re-initialize a token.

156 System z Cryptographic Services and z/OS PKI Services 6.1.2 Benefits of PKCS#11 on z/OS

On z/OS V1.9, ICSF supports PKCS#11, providing an alternative to the IBM Common Cryptographic Architecture (CCA) and broadening the scope of cryptographic applications that make use of System z cryptography. PKCS#11 applications developed for other platforms can be recompiled and run on z/OS. Java can use a common PKCS#11 keystore.

With minor exceptions, RACF and System SSL use different keystores (RACF keyrings and System SSL key databases). Providing PKCS#11 to ICSF provides common key storage, which both RACF and System SSL can use.

6.1.3 Mapping PKCS#11 concepts to z/OS cryptographic technology

On z/OS PKCS#11 tokens are not cryptographic devices but rather virtual smart cards. New tokens can be created at any time. The tokens can be application specific or system-wide, depending on access control definitions, which are used instead of PINs. Because z/OS PKCS#11 tokens are virtual, z/OS also provides a way to delete them.

In z/OS PKCS#11, which is a new subcomponent of ICSF, tokens and their contents are stored in a new VSAM data set, the Token Key Data Set (TKDS). TKDS serves as the repository for cryptographic keys and certificates used by PKCS#11 applications.

z/OS provides several facilities to manage tokens: A C language applications interface (API) that implements a subset of the PKCS#11 specification. Token management ICSF callable services, which are also used by the C API. The ICSF ISPF panels, called Token Browser, which provide the capability to see a formatted view of TKDS objects and make minor, limited updates to them. The RACF RACDCERT command supports the certificate, public key, and private key objects and provides subfunctions to manage these objects together with tokens. The gskkyman command supports management of certificates and keys similar to the way RACFDCERT does.

ICSF supports PKCS#11 session objects and token objects. A session object exists for the life of a PKCS#11 session. ICSF creates a session object database to hold session objects. They are not maintained on the direct access storage device (DASD). An application has only one session objects database, even if the application spawns multiple PKCS#11 sessions. Token objects are stored in the TKDS with one record per object. They are visible to all applications having sufficient permission to the token. The objects are persistent and remain associated with the token even after a session is closed.

The PKCS#11 standard was designed for systems that grant access to token information based on a PIN. z/OS does not use PINs; instead, profiles in the SAF CRYPTOZ class control access to tokens. Each token has two resources in the CRYPTOZ class: The resource USER.token-name controls the access of the user role to the token. The resource SO.token-name controls the access of the SO role to the token. A user’s access level to each of these resources (read, update, and control) determines the user’s access level to the token.

Chapter 6. z/OS PKCS#11 157 6.2 z/OS PKCS#11 infrastructure and setup

The infrastructure of the PKCS#11 implementation in z/OS is shown in Figure 6-1. The main component is the Token Key Data Set. If TKDS is not available, any PKCS#11 application cannot work. Everything below the dashed line in Figure 6-1 is the ICSF address space; above the dashed line is the user’s space.

z/OS PKCS11 New “C” Applications SSL (gskkyman) Token Management PKCS #11 “C” Interface C_function() RACF (RACDCERT) Token Management Token Browser (ISPF Panels) RACF (R_Datalib) Callable Servces Key ring Services PC Interface SSL (runtime) Assembler ICSF Programs s es cc (z/OS PKCS11) A Hardware Existing SSL ck he Applications C Cache RACF Session Object Token Key Dataspace •TKDS – VSAM KSDS Data Set •Each record holds one object (TKDS)

Figure 6-1 Architectural view of z/OS PKCS#11 support

The user interfaces are the Token Browser panels, RACDCERT, and gskkyman. The others are programming interfaces - at callable level and at the C application level. Note that existing SSL applications (both System SSL and JSSE) can make use of tokens in place of keystores.

6.2.1 Tokens

The PKCS#11 tokens on z/OS are virtual, conceptually similar to RACF (SAF) keyrings. An application can have one or more z/OS PKCS#11 tokens, depending on its need. z/OS PKCS#11 tokens are created using system software such as RACF, the gskkyman utility or by applications using the C API. Also ICSF panels can be used for token management with limited usability, see 6.3.1, “ICSF panels, token browser” on page 163.

Each token has a unique token name or label that is specified by the user or application when the token is created. The following rules apply to token names: Names can be up to 32 characters in length.

Permitted characters are: –Alphanumeric – National: @ (x’5B’), # (x’7B’), or $ (x’7C’) – Period: . (x’4B’)

158 System z Cryptographic Services and z/OS PKI Services The first character must be alphabetic or national. Lowercase letters can be used but are changed to uppercase. The IBM1047 code page is assumed.

Similar to the way that z/OS PKCS#11 supports token creation, the PKCS#11 tokens can be deleted using the same system software tools used when created.

6.2.2 Token Key Data Set (TKDS)

The Token Key Data Set (TKDS) is a VSAM data set that serves as the repository for cryptographic keys and certificates used by z/OS PKCS#11 applications. Before an installation can run PKCS#11 applications, the TKDS must be created, and the ICSF installation options data set updated to identify the name of the TKDS data set.

The following rules govern token data sets: The token data set must be a key-sequenced VSAM data set with spanned variable-length records. The token data set must be allocated on a permanently resident volume.

Important: Keys in the token data set are not encrypted. Therefore it is important that the RACF profile be created to protect the token data set from unauthorized access.

To create the TKDS, we used sample JCL from SYS1.SAMPLIB, member CSFTKDS, shown in Figure 6-2, and modified it for our purposes.

//CSFTKDS JOB //* //DEFINE EXEC PGM=IDCAMS,REGION=4M //SYSPRINT DD SYSOUT=* //SYSIN DD * DEFINE CLUSTER (NAME(CSF.CSFTKDS) - VOLUMES(XXXXXX) - RECORDS(100 50) - RECORDSIZE(2200 32756) - KEYS(72 0) - FREESPACE(0 0) - SPANNED - SHAREOPTIONS(2 3)) - DATA (NAME(CSF.CSFTKDS.DATA) - BUFFERSPACE(100000) - ERASE - WRITECHECK) - INDEX (NAME(CSF.CSFTKDS.INDEX)) /* Figure 6-2 JCL example - creating TKDS in SYS1.SAMPLIB, member CSFTKDS

To optimize performance, ICSF creates a data space containing an in-storage copy of the TKDS.

Chapter 6. z/OS PKCS#11 159 Options for the TKDS in the ICSF installation options data set The ICSF installation option data set contains two options related to the token data set: TKDSN

SYSPLEXTKDS The TKDSN option identifies the VSAM data set that will be the token data set. The format of this option is: TKDSN(data_set_name)

data_set_name is the existing token data set or an empty VSAM data set to be used as the token data set.

Important: If the TKDSN option is not specified in the ICSF installation option data set, ICSF does not provide any PKCS#11 services.

The SYSPLEXTKDS option specifies whether the token data set should have sysplex-wide data consistency. The SYSPLEXTKDS option is in effect only if the TKDSN option has also been specified. The format of this option is: SYSPLEXTKDS(YES|NO,FAIL(YES|NO)

The SYSPLEXTKDS option can be YES or NO: If SYSPLEXTKDS(NO,FAIL(fail-option)) is specified, no XCF signalling is performed when an update to a TKDS record occurs. If SYSPLEXTKDS(YES,FAIL(fail-option)) is specified, the system is notified of updates made to the TKDS by other members of the sysplex who have also specified SYSPLEXTKDS(YES,FAIL(fail-option)).

The value of FAIL can be YES or NO. If FAIL(YES) is specified, ICSF initialization terminates abnormally when a failure creating the TKDS latch set occurs. If FAIL(NO) is specified, ICSF initialization processing continues even if the request to create a TKDS latch set fails. The system is not notified of updates to the TKDS by other members of the ICSF sysplex group.

The possible combinations are as follows: SYSPLEXTKDS(NO,FAIL(NO)) SYSPLEXTKDS(YES,FAIL(NO)) SYSPLEXTKDS(YES,FAIL(YES))

The default value is SYSPLEXTKDS(NO,FAIL(NO)

Serialization of resources for the TKDS To serialize updates to the TKDS and in-storage copies of the TKDS, ICSF uses sysplex-wide ENQs on the resource QNAME SYSZTKT and resource RNAME SYSZTCKDS.TKDSdsn, where dsn is the data set name of the active TKDS. In addition, a latch set is defined for the serializing reads to TKDS records.

160 System z Cryptographic Services and z/OS PKI Services 6.2.3 Controlling access to tokens

The PKCS#11 standard was designed for systems that grant access to token information based on a PIN. The standard defines two type of users, the standard user (User) and the security officer (SO), each having its own personal identification number (PIN). z/OS does not use PINs. Instead, profiles in the SAF CRYPTOZ class control access to tokens. For each token, there are two resources in the CRYPTOZ class: The resource USER.token-name controls the access of the User role to the token. The resource SO.token-name controls the access of the SO role to the token.

A user’s access level to each of these resources (read, update, and control) determines the user’s access level to the token.

Of the six possible token access levels, three are defined by the PKCS#11 standard, and three are unique to z/OS. The PKCS#11 token standard access levels are: User R/O: Allows the user to read the token including its private objects, but the user cannot create a new token or session objects or alter existing ones. User R/W: Allows the user read/write access to the token object including its private objects. SO R/W: Allows the user to act as the security officer for the token and to read, create, and alter public objects on the token.

The token access levels unique to z/OS are: Weak SO: A security officer that can modify CA certificates contained in a token but not initialize the token (for example, a system administrator who determinates the trust policy for all applications on the system). Strong SO: A security officer that can add, generate, or remove private objects in a token but cannot use the keys (for example, a server administrator). Weak User: A User that has access to everything in a token but cannot alter the trust policy of the token (for example, the server daemon user ID).

The user access level to a token is derived from the user’s access level to a resource in the SAF CRYPROZ class, shown in Table 6-1. The CRYPTOZ class resource names are formed from the label of the token being protected: SO.token-label for the security officer role and USER.token-label for the User role. Generic profiles can be used to protect multiple tokens.

Table 6-1 Token access levels SAF access level

CRYPTOZ resource READ UPDATE CONTROL

SO.token-label Weak SO SO R/W Strong SO

Can read, create, Same ability as Weak Same ability as SO delete, modify, and use SO, plus can create R/W, plus can read, public objects. and delete tokens. create, delete, and modify private objects but not use them (see the note that follows).

Chapter 6. z/OS PKCS#11 161 SAF access level

USER.token-label User R/O Weak User User R/W Can read and use (see Same ability as User Same ability as Weak the note that follows) R/O, plus can create, User, plus can add, public and private delete, and modify delete, and modify objects. public and private certificate authority objects. Cannot add, objects. delete or modify certificate authority objects.

Note: “Use” is defined as any of the following: Performing any cryptographic operation involving the key object - for example, C_Encrypt. Searching for key objects using sensitive search attributes. Retrieving sensitive key object attributes, such as CKA_VALUE for the secret key.

For help in controlling access to tokens, follow these guidelines: The CRYPTOZ class supports generic profiles. We suggest that this advantage is used by creating token-naming conventions for the organization that enforces generic profiles. For example, users and applications are required to precede their token name with their user ID. For server applications, grant security officers (server administrators) Strong SO access and their users (server daemon user IDs) Weak User or User R/W access. For applications for which it is not necessary to separate the security officer and user roles, grant user IDs the appropriate access level to both SO and USER profiles.

6.2.4 ICSF services provided by z/OS PKCS#11

The C API provided by ICSF in z/OS V1.9 is a subset of the PKCS#11 V2.20. The PKCS#11 standard is flexible in this respect. The primitive functions needed by the C API are backed by new and existing services in ICSF. Of these new callable services, only the ones needed for token management are externalized: C API: – Subset of the C functions defined in the PKCS#11 V2.20 specification. – Most functions supported. • C_Login, C_Logout supported but not operational. – Algorithms supported by conventional ICSF are mapped to PKCS#11 mechanisms. The new token management callable services: – For non-Language-environment-enabled applications (for example, Assembler). – Operational services are not externalized.

162 System z Cryptographic Services and z/OS PKI Services Consult ICSF Writing PKCS #11 Applications (SA23-2231) for the following information: – Functions and mechanisms supported – Return codes – Trace and troubleshooting information – Test PKCS#11 code

Token management callable services The token management callable services provide an API for managing z/OS PKCS#11 tokens. The C API uses these services. Calls to the System Authorization Facility (SAF) determine access authorization for the callable services using CSFSERV class. The user requires READ access to the appropriate CSFSERV class resource.

These callable services and the resources to protect them are shown in Table 6-2.

Table 6-2 Callable services and resources in CSFSERV class Callable service Service Name of protecting resource

CSFPTRC Token record or object create CSF1TRC

CSFPTRD Token record or object delete CSF1TRD

CSFPTRL Token record or object list CSF1TRL

CSFPSAV Set object attribute value CSF1SAV

CSFPGAV Get object attribute value CSF1GAV

Tip: Defining generic profiles helps protect ICSF callable services. For example, a profile name CSF* covers all ICSF services. A profile name CSF1* covers the PKCS#11 subset of the ICSF services with the exception of CSFOWH and CSFIQF. See more details in ICSF Writing PKCS #11 Applications, SA23-2231.

6.3 z/OS PKCS#11 token administration

z/OS PKCS#11 token administration can be performed several ways: using ICSF token browser panels, using RACF, or using gskkyman. The differences in these methods are explained in the sections that follow.

The ability to administer the tokens depends on the access right level defined in the CRYPTOZ SAF class using the resources SO.token-name and USER.token-name. If CSFSERV class is active, ICSF performs access control checks to resources shown in “Token management callable services” on page 163.

6.3.1 ICSF panels, token browser

On z/OS V1.9, ICSF is updated to support PKCS#11. This ICSF version, HCR7740, includes changes in ICSF services, which were discussed earlier, and in ICSF panels. In addition, two existing panels have been changed. Option 4, ADMINCNTL, from the primary panel, and

Chapter 6. z/OS PKCS#11 163 option 3.1, OPSTAT.OPTIONS from the primary panel, shown in Figure 6-3, now display the active TKDS name if it is defined. If TKDS is not defined, ISCF does not support PKCS#11.

------ICSF - Installation Option Display -- Row 1 to 14 of 14 COMMAND ===> SCROLL ===> PAGE Active CKDS: SYS1.SC60.SCSFCKDS Active PKDS: SYS1.SC60.SCSFPKDS Active TKDS: SYS1.SC60.SCSFTKDS OPTION CURRENT VALUE ------CHECKAUTH RACF check authorized callers YES COMPAT Allow CUSP/PCF compatibility NO DOMAIN Current domain index or usage domain index 8 KEYAUTH Key Authentication in effect YES CKTAUTH CKT Authentication in effect NO SSM Allow Special Secure Mode YES TRACEENTRY Number of trace entries active 1000 USERPARM User specified parameter data USERPARM REASONCODES Source of callable services reason codes ICSF PKDSCACHE PKDS Cache size in records 64 SYSPLEXCKDS Sysplex consistency for CKDS updates NO,FAIL(NO) SYSPLEXTKDS Sysplex consistency for TKDS updates NO,FAIL(NO) WAITLIST Source of CICS Wait List if CICS installed default

******************************* Bottom of data *******************************

Figure 6-3 Installation options showing TKDS name

164 System z Cryptographic Services and z/OS PKI Services To access the new Token Management panels, select option 5, Utility, from the ICSF primary panel, and an update panel is shown, as in Figure 6-4.

------ICSF - Utilities ------OPTION ===>

Enter the number of the desired option.

1 ENCODE - Encode data 2 DECODE - Decode data 3 RANDOM - Generate a random number 4 CHECKSUM - Generate a checksum and verification and hash pattern 5 PPKEYS - Generate master key values from a pass phrase 6 PKDSKEYS - Manage keys in the PKDS 7 PKCS11 TOKEN - Management of PKCS11 tokens

Press ENTER to go to the selected option. Press END to exit to the previous menu.

Figure 6-4 Utilities panel with token management selection

Select option 7, PKCS11 TOKEN, from the Utilities panel, and the ICSF Token Management main panel is shown, as in Figure 6-5.

------ICSF Token Management - Main Menu ------OPTION ===>

Enter the number of the desired option.

1 Create a new token 2 Delete an existing token 3 Manage an existing token 4 List existing tokens

Full or partial token name: ______

Figure 6-5 Token Management main panel

The Token Management main panel has options to create, delete, and manage an existing token. All these options require the exact name of the token. Option 4, list existing tokens, can use partial token names - for example, indicating that token name begins with given characters. If the token name is not given with option 4, all tokens are shown to which the user has required access.

Chapter 6. z/OS PKCS#11 165 To create a token, select option 1 and specify the token name. The resource definitions on the CRYPTOZ class might not give you permission to create the token. In our case, we created a token with the name TESTING.TOKEN. The token name must follow the rules shown in 6.2.1, “Tokens” on page 158.

For testing purposes, we deleted the same token TESTING.TOKEN selecting option 2, delete, from the Token Management panel. A pop-up panel is displayed, as shown in Figure 6-6, to confirm that the correct token will be deleted. All certificates, keys, or data, if any, stored in the token container will be lost.

------ICSF - Delete Confirmation ------

Are you sure you want to delete token TESTING.TOKEN?

===> Y_ Enter Y to confirm

Figure 6-6 A pop-up panel confirms token delete

A successful message is displayed after the deletion (see Figure 6-7). The token is deleted from the in-storage copy and from TKDS. If the SYSPLEXTKDS(YES,FAIL(xxx)) option is effect in the installation options data set, a sysplex broadcast message is issued, informing other sysplex members of the TKDS update and requesting them to update their in-storage TKDS copy.

------ICSF - PKCS11 Token Delete Successful ------COMMAND ===>

Token name ==> TESTING.TOKEN

Token was deleted successfully

Figure 6-7 Token delete successful

To list available tokens in TKDS, select option 4, List existing tokens, from the Token Management panel, If the name or part of the name is given, a filter selects which tokens are listed.

166 System z Cryptographic Services and z/OS PKI Services In our case, access to the tokens was limited using CRYPTOZ class resource definitions, as shown in Figure 6-8. As you can see, tokens that start with the characters F51. are not listed. You can see only the tokens you have access to. Tokens that you are not allowed to access do not appear in the list.

BROWSE - RACF COMMAND OUTPUT------LINE 00000000 COL 001 080 COMMAND ===> SCROLL ===> CSR ********************************* Top of Data ********************************* SO.F51.* (G) SO.* (G) USER.F51.* (G) USER.* (G) ******************************** Bottom of Data *******************************

Figure 6-8 CRYPTOZ class definitions to limit user access

Important: We suggest creating a naming standard for the tokens to prevent unauthorized access to the tokens and their contents.

In our case, a list of the tokens was displayed, shown inFigure 6-9, where four tokens are available.

------ICSF Token Management - List Tokens ---- Row 1 to 4 of 4 COMMAND ===> SCROLL ===> PAGE

Select a token to manage(M) or delete(D) then press ENTER

Press END to return to the previous menu.

_ GSKKYMAN.TOKEN _ JAVA.TEST _ PEKKA _ TEST ******************************* Bottom of data *******************************

Figure 6-9 List available tokens

On this panel, the tokens can be deleted by inserting D in front of the token name. A pop-up panel confirms the token delete request.

Chapter 6. z/OS PKCS#11 167 To manage the content of the token, insert M in front of the token name, We selected the token JAVA.TEST for viewing, shown in Figure 6-10.

------ICSF Token Management - Token Details ------COMMAND ===> SCROLL ===> PAGE

Token name: JAVA.TEST Manufacturer: RACF HRF7740 Model: HCR7740 Serial Number: 0 Number of objects: 0

Select objects to process then press ENTER

Press END to return to the previous menu.

------******************************* Bottom of data *******************************

Figure 6-10 Token JAVA.TEST selected for managing

This token did not have any objects, and the display shows only token meta information. These field names sound “hardware” like because they come from the PKCS#11 standard. On z/OS a PKCS#11 token is not hardware, so those fields are used for other purposes.

On z/OS, the Manufacturer field indicates how the token was created and can have the following values depending on the creation of the token: ICSF PKCS11 token browser: When the token was created using ICSF panels RACF HRF7740: When the token was created using RACF panels or commands z/OS PKCS11 API: When the token was created using the C API or the gskkyman utility.

The Model field indicates ICSF FMID (= version) information, and the Serial number field indicates the version number.

168 System z Cryptographic Services and z/OS PKI Services When we selected the token TEST with M, shown in Figure 6-11, the display shows that this token has three objects stored in the token. In our case, the panel displays Certificate object and Public key object. More objects can be seen by scrolling down the panel.

------ICSF Token Management - Token Details --- Row 1 to 2 of 3 COMMAND ===> SCROLL ===> PAGE

Token name: TEST Manufacturer: ICSF PKCS11 token browser Model: HCR7740 Serial Number: 0 Number of objects: 3

Select objects to process then press ENTER

Press END to return to the previous menu.

------_ Object 1 CERTIFICATE PRIVATE: FALSE MODIFIABLE: TRUE DEFAULT: FALSE CATEGORY: User LABEL: Test certificate SUBJECT: CN=Pekka Hanninen, O=IBM Finland, L=Helsinki, C=Finland ID: BCB184FE5FEE8CD43773201322EE0B15373E4DA1 ISSUER: CN=Pekka Hanninen, O=IBM Finland, L=Helsinki, C=Finland SERIAL NUMBER: 00

_ Object 2 PUBLIC KEY PRIVATE: FALSE MODIFIABLE: TRUE LABEL: Test certificate SUBJECT: CN=Pekka Hanninen, O=IBM Finland, L=Helsinki, C=Finland ID: BCB184FE5FEE8CD43773201322EE0B15373E4DA1 MODULUS: D0DDCD940311DD8455357DC15A293F6501BDD476F9DB73F706AF2182... MODULUS BITS: 1024 USAGE FLAGS: Enc(T),Verify(T),VerifyR(T),Wrap(T),Derive(F)

Figure 6-11 Token TEST selected with option M from List Token display

The other possible objects are private key, secret key, and data. For each object, a summary of the objects’s attributes is displayed.

Note that periods at the end of the Modulus field in the Public key object indicate that only a part of the modulus is displayed.

Chapter 6. z/OS PKCS#11 169 To view the object content in detail, select the object with S and press Enter. We selected the Certificate object, shown in Figure 6-12. The panel displays the selected certificate object and all of its attributes. To see all object details, scroll down the panel.

------ICSF Token Management - Certificate Object Details ------COMMAND ===> SCROLL ===> PAGE Object 1 from token label: TEST

Select an Action: 1 Process select DER fields(*) using external command. Enter UNIX command pathname (see panel help for details):

2 Modify one or more fields with the new values specified 3 Delete the entire object ------More: + OBJECT CLASS: CERTIFICATE PRIVATE: FALSE MODIFIABLE: TRUE LABEL: Test certificate New value: CERTIFICATE TYPE: X.509 TRUSTED: TRUE SUBJECT*: CN=Pekka Hanninen, O=IBM Finland, L=Hels inki, C=Finland ID: BCB184FE5FEE8CD43773201322EE0B15373E4DA1 New value: ISSUER*: CN=Pekka Hanninen, O=IBM Finland, L=Hels inki, C=Finland SERIAL NUMBER: 00 CERTIFICATE CATEGORY: User New value: Unspecified User Authority Other APPLICATION: RACF HRF7740 DEFAULT: FALSE New value: TRUE VALUE*: 30820280308201E9A003020102020100 |0...0...... | 300D06092A864886F70D010105050030 |0...*.H...... 0| 543110300E0603550406130746696E6C |T1.0...U....Finl| 616E643111300F060355040713084865 |and1.0...U....He| 6C73696E6B6931143012060355040A13 |lsinki1.0...U...|

Figure 6-12 Certificate Object detail view

Some attribute values can be modified. To modify a value, select a listed value (for example, TRUE for Boolean attributes) or type a new value in the field provided. The following rules apply to changes:

The ID input is a hex string with an even number of digits. The LABEL input is an EBCDIC string. To set an attribute value to a null string, specify two consecutive single quotes.

170 System z Cryptographic Services and z/OS PKI Services Some of the field objects are DER encoded (those marked with an asterisk - *). If you have a UNIX-based DER encoding utility, you can direct the browser to run the utility by entering the name of the utility on the UNIX line and selecting the field to decode.

Important: Incorrect object modification or object deletion could make other objects unusable, because of the close relationship some objects might have - for example, certificate objects and Private key and Public key objects.

6.3.2 RACF panels and RACDCERT commands

z/OS V1.9 supports PKCS#11 tokens with tokens provided and managed by ICSF. Tokens are containers that hold digital certificates and keys. RACF can be used in the following ways to define and manage certain certificate objects in a token (objects such as certificates, public keys, and private keys). Use the following RACDCERT command functions: ADDTOKEN: Defines a new empty token. DELTOKEN: Deletes an existing token and all its contents. LISTTOKEN: Displays information about the objects contained in the token. BIND: Connects a RACF certificate, its public key, and (in some cases) its private key to an existing token. UNBIND: Removes a certificate and its keys from an existing token. IMPORT: Adds a certificate to RACF from an existing token.

Because tokens are managed by ICSF, not RACF, other applications can use ICSF functions to change tokens without updating the certificate information in the RACF database. Similarly, RACF changes to digital certificates already bound to a token are not reflected in the token information maintained by ICSF. Therefore, the following restrictions apply: Deleting, altering, or renewing a RACF certificate that is bound to a token has no effect on the equivalent token objects managed by ICSF. Deleting or altering a certificate object in a token has no effect on the following objects: – The equivalent RACF certificate – The equivalent certificate objects in other tokens

Chapter 6. z/OS PKCS#11 171 RACF panels have been changed to support tokens. Selecting option 7, digital certificates, keyrings, and tokens, from the RACF main panel displays the updated digital certificate administration main panel, shown in Figure 6-13.

RACF - Digital Certificates and Related Functions OPTION ===>

Select one of the following:

1. Digital Certificate Functions

2. Key Ring Functions

3. Certificate Name Filtering Functions

4. Token Functions

Figure 6-13 RACF digital certificate administration main panel

To manage tokens, select option 4, Token Functions, and the RACF - Token Functions panel is displayed (see Figure 6-14).

RACF - Token Functions OPTION ===>

Enter one of the following:

1 List all tokens you have permission to read 2 List an existing token by name 3 Create a new token 4 Delete an existing token 5 Bind a RACF certificate to an existing token 6 Unbind a RACF certificate from an existing token 7 Import a token certificate into RACF

Figure 6-14 Token Functions main panel

The panel provides options to manage tokens - options such as create, list, and delete tokens - and options to manage certificates.

172 System z Cryptographic Services and z/OS PKI Services Selecting option 1 from the Token Functions main panel displays the panel shown in Figure 6-15, listing those tokens which you have permission to view.

********************************* Top of Data ******************************** Token: GSKKYMAN.TOKEN

*** No certificates associated with token ***

Token: JAVA.TEST

*** No certificates associated with token ***

Token: PEKKA

*** No certificates associated with token ***

Token: TEST

Seq Num Attributes Labels ------00000004 Default: NO Priv Key: YES TKDS: Test certificate Usage: PERSONAL Pub Key: YES RACF: New certificate Owner: ID(PEKKA)

******************************** Bottom of Data ******************************

Figure 6-15 List tokens you have permission to view

Also if a token contains a certificate, the basic certificate information is shown. In our case, the following information was displayed: The certificate sequence number, which is required on UNBIND and IMPORT processes. The certificate attributes, such as the default certificate and usage and owner information. The certificate label information. In our case, the certificate label has been modified so it has a different value in TKDS than in RACF. If the certificate is stored only in the token, the RACF label information displays N/A.

The list of the available tokens is limited according to the profile definitions on the CRYPTOZ SAF class.

Note: If the token contains only key values, not a certificate, the listing does not show the token content, and a message - such as No certificates associated with token - is shown. ICSF panels can be used to managed those tokens, as described in 6.3.1, “ICSF panels, token browser” on page 163.

If you use the RACF command RACFDCERT LISTTOKEN(*), the panel displays information similar to that shown in Figure 6-15.

To list certain individual tokens, use option 2 from the RACF token functions main panel or use the RACF command RACDCERT LISTTOKEN(token-name).

To create a new token, use option 3 from the RACF token functions main panel or the RACF command RACDCERT ADDTOKEN(token-name), where token-name is the token to be created.

Chapter 6. z/OS PKCS#11 173 To delete the token and all its content, select option 4 from RACF token functions main panel, and the panel shown in Figure 6-16 is displayed. Enter the token name and push enter to delete the token. If the token contains certificate which is not saved into RACF, indicate this by entering YES to the panel. Deleting the token does not affect any way to certificate saved in RACF, only token and its content are deleted.

Attention: Token delete does not make any confirmation to verify the deletion request. Pushing the Enter on the panel or after command, will destroy the token and its content.

To delete the individual token with RACF command, enter command RACDCERT DELTOKEN(token-name), where the token-name indicates toke to be deleted. If there is a certificate stored in the token which is not defined in RACF, use keyword FORCE in the command, like RACDCERT DELTOKEN(token-name) FORCE

To bind a digital certificate to the specified, existing token, select option 5 from the RACF token functions main panel, and new panel is displayed, as shown in Figure 6-17 on page 175. Enter the certificate label, token name, and certificate usage information to bind the certificate to the token.

RACF - Delete an Existing Token COMMAND ===>

Enter the name of the token to be deleted:

TEST.TOKEN______

___ Force the delete even if some of the token's objects have not been saved to RACF.

Figure 6-16 Delete a token

When a certificate is bound to a token, RACF creates the following objects in the token: A certificate object A public key object A private key object (when the certificate has an associated private key and the BIND USAGE is PERSONAL)

When a certificate must be the default certificate, select the default option at the bottom of the panel.

Restriction: Certificates created with a private key in the Public Key Dataset (PKDS), with ICSF or the PCICC option, are not supported. The target private key of the bind operation must be a non-ICSF RSA key.

174 System z Cryptographic Services and z/OS PKI Services To bind the certificate to the token with a RACF command, enter the following command (see Figure 6-17): RACDCERT BIND(ID(PEKKA) LABEL(‘Second certificate’) TOKEN(TEST.TOKEN.TWO) USAGE(PERSONAL))

RACF - Bind a RACF Certificate to an Existing Token COMMAND ===>

Identify the RACF certificate that is to be bound:

Enter the certificate label: 'Second certificate'______(in quotes) More: +

Enter the certificate type:

Owning user ID: PEKKA___ (The default is your user ID)

OR Select one of the following: _ CERTAUTH certificate OR _ SITE certificate

Identify the token to which the certificate should be bound:

Enter the token name: TEST.TOKEN.TWO______

Determine the usage for the certificate within the token:

_ Don't change the certificate's installed usage (Recommended) S Use the certificate as a PERSONAL certificate _ Use the certificate as a CERTAUTH certificate _ Use the certificate as a SITE certificate

Determine other certificate attributes:

_ This certificate should be the default certificate for the token

Figure 6-17 Bind a certificate to an existing token

We recommend that the USAGE keyword have the same value as defined in the certificate in RACF.

Chapter 6. z/OS PKCS#11 175 To remove (that is, unbind) a digital certificate from the specified z/OS PKCS#11 token, select option 6 from the RACF token functions main panel, and a panel similar to that shown in Figure 6-18 is displayed.

RACF - Unbind a RACF Certificate from a Token COMMAND ===>

Identify the token containing the certificate:

Enter the token name: TEST.TOKEN.TWO______

Identify the certificate that is to be unbound:

Use the certificate's RACF identity:

Enter the certificate label: 'Second certificate'______(in quotes)

Enter the certificate type:

Owning user ID: ______(The default is your user ID)

OR Select one of the following: _ CERTAUTH certificate OR _ SITE certificate

OR Enter the certificate sequence number within the token:

Sequence Number: ______

YES Force the unbind even if the certificate (or its private key) has not been saved to RACF.

Figure 6-18 Remove certificate from a token

The certificate to be removed must be uniquely identified in one of the following ways: By its RACF label name (if defined to RACF), and optionally you should identify it as a user, SITE, or CERTAUTH certificate. (The certificate must be defined to RACF when you specify the label name.) By its sequence number within the token. (The certificate need not be defined to RACF when you specify the sequence number.)

The sequence number can be found by listing the token content, as shown earlier in Figure 6-15 on page 173. When searching, you can use either the sequence number or the label. You cannot use both on the same query.

If the certificate (or its associated private key, if any) is not currently defined to RACF, specify FORCE; otherwise, the remove process will fail. Specifying FORCE prevents you from inadvertently deleting a certificate that is not defined to RACF.

176 System z Cryptographic Services and z/OS PKI Services To remove the certificate from the token with a RACF command, enter the following command (assuming that the sequence number is 4): RACDCERT UNBIND(ID(PEKKA) LABEL(‘Second certificate’) TOKEN(TEST.TOKEN.TWO)) or RACDCERT UNBIND(ID(PEKKA) TOKEN(TEST.TOKEN.TWO) SEQNUM(4))

To import a digital certificate from a specified z/OS PKCS#11 token, select option 7 from the RACF token functions main panel, and the panel shown in Figure 6-19 is displayed. The import function processes the certificates in the same way the ADD function in RACDCERT does.

RACF - Import a certificate from a Token COMMAND ===>

Identify the source certificate:

Enter the token name: TEST.TOKEN.TWO______

Enter the certificate sequence number within the token: 00000004 More: +

Specify how the certificate should be added to RACF:

Enter the label to be assigned to the certificate in RACF: 'New certificate'______(in quotes)

Enter the certificate type: User ID that will own the certificate: PEKKA___ (The default is your user ID)

OR Select one of the following: _ CERTAUTH certificate OR _ SITE certificate

Enter the certificate trust status or leave blank to have RACF determine the trust status: T ( N = NOTRUST, T = TRUST, H = HIGHTRUST)

Specify how the private key (if any) should be saved:

S Save as a software key (default) _ Save as an Integrated Cryptographic Services Facility key (ICSF) with an optional PKDS label or *: ______Save as a PCI Cryptographic Coprocessor key (PCICC) with an optional PKDS label or *: ______

Figure 6-19 Import a certificate from a token to RACF

Enter the name of the token that contains the certificate to be imported. The sequence number identifies the correct certificate. You can find the sequence number by listing the token content, as shown earlier in Figure 6-15 on page 173.

Chapter 6. z/OS PKCS#11 177 The label is associated with the imported certificate. Up to 32 characters can be specified. If the label is not specified, a label is generated for the certificate. The generated label is of the form LABELnnnnnnnn, where nnnnnnnn is the first integer value, starting at 00000001, that generates a unique label name. You can also define the certificate type and trust status if the default values are not acceptable.

Private key storage is stored by default in RACF as a software key. If you want to store the private key in ICSF PKDS, define ICSF or the PCICC option with the PKDS label value; otherwise, RACF generates the label.

Keep in mind the following guidelines: For private keys, the PCICC option is desirable for performance reasons and is required for RSA private keys 1025–2048 bits in length. Certificates with private keys greater than 2048 bits in length cannot be processed by RACF. To import the certificate from the token with a RACF command, enter the following command (assuming the certificate sequence number is 4): RACDCERT IMPORT(TOKEN(TEST.TOKEN.TWO) SEQNUM(4) ID(PEKKA) WITHLABEL(‘New certificate’) TRUST)

More information about the RACDCERT command can be found in z/OS V1R9.0 Security Server RACF Command Language Reference, SA22-7687.

6.3.3 gskkyman panels

gskkyman is a z/OS shell-based program that creates, fills in, and manages a z/OS file or z/OS PKCS#11 token that contains PKI private keys, certificate requests, and certificates. ICSF manages and protects tokens. ICSF uses the CRYPTOZ SAF class to determine whether the issuer of gskkyman is permitted to perform the operation against a z/OS PKCS#11 token.

You can use the gskkyman Key/Token Management menus to create, delete, and manage certificates within a key database file or z/OS PKCS#11 token. Once you have created the key database or token, managing the certificates is a very similar task: You use either the key database or token.

178 System z Cryptographic Services and z/OS PKI Services When you enter a gskkyman command, an updated menu is displayed, as shown in Figure 6-20.

PEKKA @ SC60:/u/pekka>gskkyman

Database Menu

1 - Create new database 2 - Open database 3 - Change database password 4 - Change database record length 5 - Delete database 6 - Create key parameter file 7 - Display certificate file (Binary or Base64 ASN.1 DER)

11 - Create new token 12 - Delete token 13 - Manage token 14 - Manage token from list of tokens

0 - Exit program

Enter option number: ===>

Figure 6-20 gskkyman main panel

Chapter 6. z/OS PKCS#11 179 To create a new token, select option 11 from the gskkyman main menu, and press Enter. You will be prompted for the token name, as shown in Figure 6-21. Follow the same naming rules as those provided in 6.2.1, “Tokens” on page 158. When you enter the token name is entered in lowercase characters, the name is changed to uppercase when processed.

Database Menu

11 - Create new token 12 - Delete token 13 - Manage token 14 - Manage token from list of tokens

0 - Exit program

Enter option number: 11 Enter token name (press ENTER to return to menu): ===> TEST.TOKEN.THREE

Figure 6-21 Create a new token

180 System z Cryptographic Services and z/OS PKI Services To delete the token, select option 12 from the gskkyman main menu, and press Enter. You are prompted for the name of the token to be deleted. A new token name prompt verifies the deletion (see Figure 6-22).

Database Menu

11 - Create new token 12 - Delete token 13 - Manage token 14 - Manage token from list of tokens

0 - Exit program

Enter option number: 12 Enter token name (press ENTER to return to menu): TEST.TOKEN.THREE To confirm token delete, enter token name again (press ENTER to cancel delete): ===> TEST.TOKEN.THREE INPUT

Figure 6-22 Token deletion must be confirmed

Chapter 6. z/OS PKCS#11 181 Selecting option 14 from the gskkyman main menu displays the list of tokens that you are permitted to access, as shown in Figure 6-23.

Database Menu

11 - Create new token 12 - Delete token 13 - Manage token 14 - Manage token from list of tokens

0 - Exit program

Enter option number: ===> 14

Token List

1 - GSKKYMAN.TOKEN 2 - JAVA.TEST 3 - PEKKA 4 - TEST

0 - Return to selection menu

Enter list-entry number (press ENTER to return to menu, p for previous list): ===>

Figure 6-23 List of tokens the user has permission to manage

182 System z Cryptographic Services and z/OS PKI Services To manage an individual token, select the number that corresponds to the token you want to manage, and the Token Management menu is displayed, as in Figure 6-24. We selected token TEST for a closer view.

Token Management Menu

Token: TEST

Manufacturer: ICSF PKCS11 token browser Model: HCR7740 Flags: x00000509 (INITIALIZED,PROT AUTH PATH,USER PIN INIT,RNG)

1 - Manage keys and certificates 2 - Manage certificates 3 - Manage certificate requests 4 - Create new certificate request 5 - Receive requested certificate or a renewal certificate 6 - Create a self-signed certificate 7 - Import a certificate 8 - Import a certificate and a private key 9 - Show the default key 10 - Delete Token

0 - Exit program

Enter option number (press ENTER to return to previous menu): 1

Token Key and Certificate List

Token: TEST

1 - Test certificate

0 - Return to selection menu

Enter label number (ENTER to return to selection menu, p for previous list): ===> 1

Figure 6-24 Manage keys and certificates of the TEST token

Token management can be performed from the gskkyman main menu, using option 13, which prompts you for the target token name. If you have permission to access the token, the Token Management menu is shown, as shown in the upper part of Figure 6-24.

The Token Management menu shows that the token has been created using ICSF panels, which is indicated by the Manufacturer field. The Model field indicates ICSF FMID.

The Token Management menu enables you to manage certificates and keys, create and receive certificates or certificate requests, import a certificate, and even delete a token. The menu works similar to the way we described earlier.

Chapter 6. z/OS PKCS#11 183 To obtain a closer view of what is stored in token TEST, we selected option 1, Manage keys and certificates; the Token Key and Certificate menu is shown, as in Figure 6-25.

Token Key and Certificate Menu

Label: Test certificate

1 - Show certificate information 2 - Show key information 3 - Set key as default 4 - Set certificate trust status 5 - Copy certificate and key to another database/token 6 - Export certificate to a file 7 - Export certificate and key to a file 8 - Delete certificate and key 9 - Change label 10 - Create a signed certificate and key 11 - Create a certificate renewal request

0 - Exit program

Enter option number (press ENTER to return to previous menu): ===> 1

Figure 6-25 Display certificate information

This menu enables you to view certificate and key information, set the certificate status and change the label, export a certificate, and copy a certificate and its keys, for example, into another token.

184 System z Cryptographic Services and z/OS PKI Services We selected option 1 from the Token key and Certificate menu to view the certificate in more detail. A new panel is displayed, as shown in Figure 6-26. The Certificate Information panel displays issuer and subject information, dates when the certificate is valid, and the public key size and its content.

Issuer name: Pekka Hanninen IBM Finland Helsinki Finland Subject name: Pekka Hanninen IBM Finland Helsinki Finland Effective date: 2007/06/26 Expiration date: 2008/06/27 Signature algorithm: sha1WithRsaEncryption Issuer unique ID: None Subject unique ID: None Public key algorithm: rsaEncryption Public key size: 1024 Public key: 30 81 89 02 81 81 00 D0 DD CD 94 03 11 DD 84 55 35 7D C1 5A 29 3F 65 01 BD D4 76 F9 DB 73 F7 06 AF 21 82 A9 4E 66 12 3A 02 84 35 1E AF 17 01 D2 38 97 B6 52 5E 21 D0 6A 8D 56 DD 31 CB 3A 12 74 4F C0 C2 51 B5 AE 8B BF 49 E8 FE 8B EE 31 79 03 E4 61 EB 7B 18 E9 5A 8E 8B 1F 18 CE E2 90 06 A3 72 15 B4 CE 54 0D 4E 41 3A E6 3E ED AC A7 1E 3C 49 61 A1 8D 61 0E 77 84 03 E5 F4 25 72 94 9B E9 5D 81 90 2A 18 04 AD 02 03 01 00 01 Number of extensions: 2

Enter 1 to display extensions, 0 to return to menu: ===>

Figure 6-26 Display certificate information

For more details refer to z/OS V1R9.0 Cryptographic Services System SSL Programming, SC24-5901.

6.3.4 Examples

In this section, we provide examples of ICSF panels that you access using RACDCERT commands when managing tokens. In the command sequence, we create a working token, a certificate, bind the certificate to the token, edit the certificate label information in the token, delete the original certificate from RACF, and finally import the certificate from the token to RACF. We also provide examples of accessing the status of the certificate using RACDCERT commands.

Add a token Use the RACDCERT ADDTOKEN command to add a token: TSO RACDCERT ADDTOKEN(ITSO.TEST.TOKEN)

Chapter 6. z/OS PKCS#11 185 Generate a certificate You can generate a certificate using the RACDCERT GENCERT command: TSO RACDCERT GENCERT ID(PEKKA) SUBJECTSDN(CN('TEST ITSO PERSON') O('IBM ITSO') L('POUGHKEEPSIE') C('USA')) WITHLABEL('TEMPORARY CERTIFICATE')

This command creates a new profile in the DIGTCERT class, which must be refreshed.

List a certificate in RACF Use the RACDCERT LIST command to list certificates: TSO RACDCERT LIST(LABEL('TEMPORARY CERTIFICATE'))

This command creates the display shown in Figure 6-27.

Digital certificate information for user PEKKA:

Label: TEMPORARY CERTIFICATE Certificate ID: 2QXXxdLSwePF1NfW2cHZ6EDDxdnjycbJw8HjxUBA Status: TRUST Start Date: 2007/07/18 00:00:00 End Date: 2008/07/18 23:59:59 Serial Number: >00< Issuer's Name: >CN=TEST ITSO PERSON.O=IBM ITSO.L=POUGHKEEPSIE.C=USA< Subject's Name: >CN=TEST ITSO PERSON.O=IBM ITSO.L=POUGHKEEPSIE.C=USA< Private Key Type: Non-ICSF Private Key Size: 1024 Ring Associations: *** No rings associated ***

Figure 6-27 List digital certificate information

Bind certificate information to a token You can bind (or copy) certificate information to a token using the RACDCERT BIND command: TSO RACDCERT BIND(ID(PEKKA) LABEL('TEMPORARY CERTIFICATE') TOKEN(ITSO.TEST.TOKEN) USAGE(PERSONAL))

Display certificate information using ICSF and RACF To view certificate information using ICSF, complete these steps: 1. Select option 5, ICSF Utilities, from the ICSF main panel. 2. Select option 7, Management of PKCS11 tokens, from the ICSF - Utilities panel. 3. Select option 3, Manage an existing token, from the ICSF Token Management - Main Menu panel, with the correct token name, ITSO.TEST.TOKEN. Or select option 4, List existing tokens. From the list of tokens that is displayed, selected the correct token, inserting M next to the token name.

186 System z Cryptographic Services and z/OS PKI Services The Token Details panel is shown in Figure 6-28.

------ICSF Token Management - Token Details --- Row 1 to 2 of 3 COMMAND ===> SCROLL ===> PAGE

Token name: ITSO.TEST.TOKEN Manufacturer: RACF HRF7740 Model: HCR7740 Serial Number: 0 Number of objects: 3

Select objects to process then press ENTER

Press END to return to the previous menu.

------_ Object 1 CERTIFICATE PRIVATE: FALSE MODIFIABLE: TRUE DEFAULT: FALSE CATEGORY: User LABEL: TEMPORARY CERTIFICATE SUBJECT: CN=TEST ITSO PERSON, O=IBM ITSO, L=POUGHKEEPSIE, C=USA ID: EC04C7D6966608FF0BF436F32C33E0BF194C171B ISSUER: CN=TEST ITSO PERSON, O=IBM ITSO, L=POUGHKEEPSIE, C=USA SERIAL NUMBER: 00

_ Object 2 PUBLIC KEY PRIVATE: FALSE MODIFIABLE: TRUE LABEL: TEMPORARY CERTIFICATE SUBJECT: CN=TEST ITSO PERSON, O=IBM ITSO, L=POUGHKEEPSIE, C=USA ID: EC04C7D6966608FF0BF436F32C33E0BF194C171B MODULUS: 9B5AEFF724375C17B0ED04537626C98C1A3F1D0979EC6651C5E646D6... MODULUS BITS: 1024 USAGE FLAGS: Enc(T),Verify(T),VerifyR(T),Wrap(T),Derive(F)

_ Object 3 PRIVATE KEY PRIVATE: TRUE MODIFIABLE: TRUE EXTRACTABLE: TRUE SENSITIVE: FALSE LABEL: TEMPORARY CERTIFICATE SUBJECT: CN=TEST ITSO PERSON, O=IBM ITSO, L=POUGHKEEPSIE, C=USA ID: EC04C7D6966608FF0BF436F32C33E0BF194C171B MODULUS: 9B5AEFF724375C17B0ED04537626C98C1A3F1D0979EC6651C5E646D6... USAGE FLAGS: Dec(T),Sign(T),SignR(T),Unwrap(T),Derive(F)

******************************* Bottom of data ********************************

Figure 6-28 Display certificate information using ICSF panels

Chapter 6. z/OS PKCS#11 187 Use the RACDCERT LISTTOKEN command to access certificate information about a specific token: TSO RACDCERT LISTTOKEN(ITSO.TEST.TOKEN)

The RACDCERT LISTTOKEN command accesses the display shown in Figure 6-29.

Token: ITSO.TEST.TOKEN

Seq Num Attributes Labels ------00000001 Default: NO Priv Key: YES TKDS: TEMPORARY CERTIFICATE Usage: PERSONAL Pub Key: YES RACF: TEMPORARY CERTIFICATE Owner: ID(PEKKA)

Figure 6-29 Display certificate information about a token

Modify the certificate label To modify the certificate label, you can use any of the three objects in the token - certificate, public key, and private key - because they all contain the label information. Select each one of them to make the modification with option 2 and provide the new label information, SHORT TIME CERTIFICATE, in the New value field, as shown in Figure 6-30 on page 189, in

188 System z Cryptographic Services and z/OS PKI Services Figure 6-31 on page 190, and in Figure 6-32 on page 191.Figure 6-30 shows the Certificate Object Details panel.

------ICSF Token Management - Certificate Object Details ------COMMAND ===> SCROLL ===> PAGE Object 1 from token label: ITSO.TEST.TOKEN

Select an Action: 2 1 Process select DER fields(*) using external command. Enter UNIX command pathname (see panel help for details):

2 Modify one or more fields with the new values specified 3 Delete the entire object ------More: + OBJECT CLASS: CERTIFICATE PRIVATE: FALSE MODIFIABLE: TRUE LABEL: TEMPORARY CERTIFICATE New value: SHORT TIME CERTIFICATE CERTIFICATE TYPE: X.509 TRUSTED: TRUE _ SUBJECT*: CN=TEST ITSO PERSON, O=IBM ITSO, L=POUGH KEEPSIE, C=USA ID: EC04C7D6966608FF0BF436F32C33E0BF194C171B New value: _ ISSUER*: CN=TEST ITSO PERSON, O=IBM ITSO, L=POUGH KEEPSIE, C=USA SERIAL NUMBER: 00 CERTIFICATE CATEGORY: User New value: Unspecified _ User _ Authority _ Other _ APPLICATION: RACF HRF7740 DEFAULT: FALSE _ New value: TRUE _ VALUE*: 30820282308201EBA003020102020100 |0...0...... | 300D06092A864886F70D010105050030 |0...*.H...... 0| 55310C300A0603550406130355534131 |U1.0...U....USA1| 1530130603550407130C504F5547484B |.0...U....POUGHK| 45455053494531133011060355040A13 |EEPSIE1.0...U...| 0A49424D2020204954534F3119301706 |.IBM ITSO1.0..| 03550403131054455354204954534F20 |.U....TEST ITSO | 504552534F4E301E170D303730373138 |PERSON0...070718| 3034303030305A170D30383037313930 |040000Z..0807190| 33353935395A3055310C300A06035504 |35959Z0U1.0...U.| 06130355534131153013060355040713 |...USA1.0...U...| 0C504F5547484B454550534945311330 |.POUGHKEEPSIE1.0| 11060355040A130A49424D2020204954 |...U....IBM IT|

Figure 6-30 Modify label information in a certificate object

Chapter 6. z/OS PKCS#11 189 Figure 6-31 shows the Public Key Object Details panel.

------ICSF Token Management - Public Key Object Details ------COMMAND ===> SCROLL ===> PAGE Object 2 from token label: ITSO.TEST.TOKEN

Select an Action: 2 1 Process select DER fields(*) using external command Enter UNIX command pathname (see panel help for details):

2 Modify one or more fields with the new values specified 3 Delete the entire object ------More: + OBJECT CLASS: PUBLIC KEY PRIVATE: FALSE MODIFIABLE: TRUE LABEL: TEMPORARY CERTIFICATE New value: SHORT TIME CERTIFICATE______TRUSTED: TRUE _ SUBJECT*: CN=TEST ITSO PERSON, O=IBM ITSO, L=POUGH KEEPSIE, C=USA ID: EC04C7D6966608FF0BF436F32C33E0BF194C171B New value: ______KEY TYPE: RSA START DATE: New value: ______YYYYMMDD END DATE: New value: ______YYYYMMDD DERIVE: FALSE LOCAL: FALSE KEY GEN MECHANISM: UNAVAILABLE INFORMATION ENCRYPT: TRUE New value: FALSE _ VERIFY: TRUE New value: FALSE _ VERIFY RECOVER: TRUE New value: FALSE _ WRAP: TRUE New value: FALSE _ APPLICATION: RACF HRF7740 MODULUS BITS: 1024 PUBLIC EXPONENT: 010001

MODULUS: 9B5AEFF724375C17B0ED04537626C98C1A3F1D0979EC6651C5E646D60E761AD5 DA853D6ABB226EE8571C6ADD58D660EF85FFEC3D1650E251575D7E16C255E2B3

932FA285A753F6B7259D53126ED0BE6E59656A40101CD5DDCEE57F7ED7D44D67 C37BBA03405BDDD1E1F4AEC0458E99FC873DEBBE18ED5F34F827092F3088104F

Figure 6-31 Modify label information in the public object

190 System z Cryptographic Services and z/OS PKI Services Figure 6-32 shows the Private Key Object Details panel.

------ICSF Token Management - Private Key Object Details ------COMMAND ===> SCROLL ===> PAGE Object 3 from token label: ITSO.TEST.TOKEN

Select an Action: 2 1 Process select DER fields(*) using external command Enter UNIX command pathname (see panel help for details):

2 Modify one or more fields with the new values specified 3 Delete the entire object ------More: + OBJECT CLASS: PRIVATE KEY PRIVATE: TRUE MODIFIABLE: TRUE LABEL: TEMPORARY CERTIFICATE New value: SHORT TIME CERTIFICATE______SUBJECT*: CN=TEST ITSO PERSON, O=IBM ITSO, L=POUGH KEEPSIE, C=USA ID: EC04C7D6966608FF0BF436F32C33E0BF194C171B New value: ______KEY TYPE: RSA START DATE: New value: ______YYYYMMDD END DATE: New value: ______YYYYMMDD DERIVE: FALSE LOCAL: FALSE KEY GEN MECHANISM: UNAVAILABLE INFORMATION DECRYPT: TRUE New value: FALSE _ SIGN: TRUE New value: FALSE _ SIGN RECOVER: TRUE New value: FALSE _ UNWRAP: TRUE New value: FALSE _ EXTRACTABLE: TRUE (Cannot be changed from FALSE New value: FALSE _ to TRUE) SENSITIVE: FALSE (Cannot be changed from TRUE New value: TRUE _ to FALSE) ALWAYS SENSITIVE: FALSE NEVER EXTRACTABLE: FALSE APPLICATION: RACF HRF7740 PRIVATE EXPONENT: Not displayable PRIME 1: Not displayable PRIME 2: Not displayable EXPONENT 1: Not displayable EXPONENT 2: Not displayable COEFFICIENT: Not displayable PUBLIC EXPONENT: 010001

MODULUS: 9B5AEFF724375C17B0ED04537626C98C1A3F1D0979EC6651C5E646D60E761AD5 DA853D6ABB226EE8571C6ADD58D660EF85FFEC3D1650E251575D7E16C255E2B3 932FA285A753F6B7259D53126ED0BE6E59656A40101CD5DDCEE57F7ED7D44D67 C37BBA03405BDDD1E1F4AEC0458E99FC873DEBBE18ED5F34F827092F3088104F

Figure 6-32 Modify label information in the private object

Chapter 6. z/OS PKCS#11 191 Delete the certificate from RACF Use the following command to delete a certificate from RACF: TSO RACDCERT DELETE(LABEL('TEMPORARY CERTIFICATE'))

This command deletes the profile in the DIGTCERT class, which must be refreshed.

Display certificate information using RACF The following command displays certificate information about a token: TSO RACDCERT LISTTOKEN(ITSO.TEST.TOKEN)

This command accesses the panel shown in Figure 6-33.

Token: ITSO.TEST.TOKEN

Seq Num Attributes Labels ------00000001 Default: NO Priv Key: YES TKDS: SHORT TIME CERTIFICATE Usage: PERSONAL Pub Key: YES

Figure 6-33 Display certificate information after deleting the certificate from RACF

Import the certificate to RACF without using the WITHLABEL parameter Use the following command to import the certificate to RACF without using the WITHLABEL parameter: TSO RACDCERT IMPORT(TOKEN(ITSO.TEST.TOKEN) SEQNUM(01)) ID(PEKKA) TRUST

The sequence number, which is mandatory when using the IMPORT command, can be found with the LISTTOKEN command view, shown in Figure 6-33.

Display certificate information using the token You can display certificate information by entering the following command: TSO RACDCERT LISTTOKEN(ITSO.TEST.TOKEN)

RACF creates a certificate label because the WITHLABEL keyword was missing in the IMPORT command. The RACDCERT LISTTOKEN command accesses the panel shown in Figure 6-34.

Token: ITSO.TEST.TOKEN

Seq Num Attributes Labels ------00000001 Default: NO Priv Key: YES TKDS: SHORT TIME CERTIFICATE Usage: PERSONAL Pub Key: YES RACF: LABEL00000001 Owner: ID(PEKKA)

Figure 6-34 Display certificate information after importing the certificate to RACF

Display certificate information about RACF Enter the following command to display certificate information: TSO RACDCERT LIST(LABEL('LABEL00000001'))

192 System z Cryptographic Services and z/OS PKI Services The RACDCERT LIST command accesses the panel shown in Figure 6-35.

Digital certificate information for user PEKKA:

Label: LABEL00000001 Certificate ID: 2QXXxdLSwdPBwsXT8PDw8PDw8PFA Status: TRUST Start Date: 2007/07/18 00:00:00 End Date: 2008/07/18 23:59:59 Serial Number: >00< Issuer's Name: >CN=TEST ITSO PERSON.O=IBM ITSO.L=POUGHKEEPSIE.C=USA< Subject's Name: >CN=TEST ITSO PERSON.O=IBM ITSO.L=POUGHKEEPSIE.C=USA< Private Key Type: Non-ICSF Private Key Size: 1024 Ring Associations: *** No rings associated ***

Figure 6-35 Display certificate information after importing the certificate to RACF

Import the certificate to RACF using the WITHLABEL parameter Enter the following command with the WITHLABEL parameter to import the certificate: TSO RACDCERT IMPORT(TOKEN(ITSO.TEST.TOKEN) SEQNUM(01)) WITHLABEL('SHORT TIME CERTIFICATE') ID(PEKKA) TRUST

The sequence number, which is mandatory when using the IMPORT command, can be found with the LISTTOKEN command view, shown previously in Figure 6-33 on page 192.

Display certificate information using a token You can access certificate information by entering the following command: TSO RACDCERT LISTTOKEN(ITSO.TEST.TOKEN)

This command accesses the panel shown in Figure 6-36.

Token: ITSO.TEST.TOKEN

Seq Num Attributes Labels ------00000001 Default: NO Priv Key: YES TKDS: SHORT TIME CERTIFICATE Usage: PERSONAL Pub Key: YES RACF: SHORT TIME CERTIFICATE Owner: ID(PEKKA)

Figure 6-36 Display certificate information after importing a certificate with WITHLABEL

Display certificate information about RACF To display certificate information about RACF, enter the following command: TSO RACDCERT LIST(LABEL('SHORT TIME CERTIFICATE'))

Chapter 6. z/OS PKCS#11 193 This command accesses the panel shown in Figure 6-37.

Digital certificate information for user PEKKA:

Label: SHORT TIME CERTIFICATE Certificate ID: 2QXXxdLSweLI1tnjQOPJ1MVAw8XZ48nGycPB48VA Status: TRUST Start Date: 2007/07/18 00:00:00 End Date: 2008/07/18 23:59:59 Serial Number: >00< Issuer's Name: >CN=TEST ITSO PERSON.O=IBM ITSO.L=POUGHKEEPSIE.C=USA< Subject's Name: >CN=TEST ITSO PERSON.O=IBM ITSO.L=POUGHKEEPSIE.C=USA< Private Key Type: Non-ICSF Private Key Size: 1024 Ring Associations: *** No rings associated ***

Figure 6-37 Display certificate information about RACF after importing the certificate with WITHLABEL

6.4 z/OS PKCS#11 programming example

We provide a sample PKCS#11 program called tstpkcs11. The program is passed the name of a PKCS#11 token to be created and performs the following tasks: 1. Creates a token with the name passed to the program. If the token already exists or the token name is invalid, an error message is displayed, and the program stops. A token name can be invalid because, for example, the naming convention has not been followed correctly or a user does not have permission to create certain token names (CRYPTOZ definitions). 2. Opens a session. 3. Generates an RSA key pair, which is stored in the created token. 4. Encrypts test data using the public part of the key pair. 5. Decrypts the data using the private part of the key pair and verifies that the result is correct, comparing the deciphered output to the original source text. 6. Closes the session.

194 System z Cryptographic Services and z/OS PKI Services After running this sample program, it produced the log shown in Figure 6-38.

SC60:/u/pekka>tstpkcs11 -t pkcs11.test.token Getting the PKCS11 function list... Initializing the PKCS11 environment... Creating a token... Opening a session... Generating keys. This may take a while... Enciphering data... Deciphering data... Closing the session... Test completed successfully! SC60:/u/pekka>

Figure 6-38 Test code execution log

As a result of running the test program, a new token was been created, which is shown in the List Tokens ICSF panel in Figure 6-39.

------ICSF Token Management - List Tokens ---- Row 1 to 5 of 5 COMMAND ===> SCROLL ===> PAGE

Select a token to manage(M) or delete(D) then press ENTER

Press END to return to the previous menu.

_ GSKKYMAN.TOKEN _ JAVA.TEST _ PEKKA _ PKCS11.TEST.TOKEN _ TEST ******************************* Bottom of data *******************************

Figure 6-39 PKCS11.TEST.TOKEN has been created by the test program

Chapter 6. z/OS PKCS#11 195 To view the content of the newly created token in more detail, we inserted M next to the name of the new token to access the Token Details panel shown in Figure 6-40. The token has two objects, a public key and a private key.

------ICSF Token Management - Token Details --- Row 1 to 2 of 2 COMMAND ===> SCROLL ===> PAGE

Token name: PKCS11.TEST.TOKEN Manufacturer: z/OS PKCS11 API Model: HCR7740 Serial Number: 0 Number of objects: 2

Select objects to process then press ENTER

Press END to return to the previous menu.

------_ Object 1 PUBLIC KEY PRIVATE: FALSE MODIFIABLE: TRUE LABEL: SUBJECT: ID: MODULUS: C00D0D46F9E84C27E1053B4F81C6AB02A17F5BD6EDC475D6B4AFAD73... MODULUS BITS: 1024 USAGE FLAGS: Enc(T),Verify(T),VerifyR(T),Wrap(T),Derive(F)

_ Object 2 PRIVATE KEY PRIVATE: TRUE MODIFIABLE: TRUE EXTRACTABLE: TRUE SENSITIVE: FALSE LABEL: SUBJECT: ID: MODULUS: C00D0D46F9E84C27E1053B4F81C6AB02A17F5BD6EDC475D6B4AFAD73... USAGE FLAGS: Dec(T),Sign(T),SignR(T),Unwrap(T),Derive(F)

Figure 6-40 Token Details panel

The test program can be used as an example of how to build a PKCS#11 application or as a test utility to test the system configuration for PKCS#11 settings. The source code listing is shown in Example 6-1.

Example 6-1 Sample test program /*********************************************************************/ /* */ /* COMPONENT_NAME: tstpkcs11.c */ /* */ /* Licensed Materials - Property of IBM */ /* Copyright IBM Corp. 2007 */ /* Status = HCR7740 */ /* */ /*********************************************************************/ /*********************************************************************/ /* */ /* This file contains sample code. IBM PROVIDES THIS CODE ON AN */ /* 'AS IS' BASIS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR */ /* IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES */

196 System z Cryptographic Services and z/OS PKI Services /* OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. */ /* */ /*********************************************************************/

#ifdef IBM /* Customers may remove this copyright statement */ #pragma comment (copyright,"\ Licensed Materials - Property of IBM \ 5694-A01 Copyright IBM Corp. 2007 \ All Rights Reserved \ US Government Users Restricted Rights - \ Use, duplication or disclosure restricted by \ Use, duplication or disclosure restricted by \ GSA ADP Schedule Contract with IBM Corp.") #endif

/* Execute test for PKCS #11 */

#define _UNIX03_SOURCE #include #include #include #include #include #include #include int skip_token_obj;

CK_FUNCTION_LIST *funcs; CK_SLOT_ID slotID = CK_UNAVAILABLE_INFORMATION; CK_BYTE tokenName[32];

void ProcessRetCode( CK_RV rc ) { switch (rc) { case CKR_OK: printf(" CKR_OK"); break; case CKR_CANCEL: printf(" CKR_CANCEL"); break; case CKR_HOST_MEMORY: printf(" CKR_HOST_MEMORY"); break; case CKR_SLOT_ID_INVALID: printf(" CKR_SLOT_ID_INVALID"); break; case CKR_GENERAL_ERROR: printf(" CKR_GENERAL_ERROR"); break; case CKR_FUNCTION_FAILED: printf(" CKR_FUNCTION_FAILED"); break; case CKR_ARGUMENTS_BAD: printf(" CKR_ARGUMENTS_BAD"); break; case CKR_NO_EVENT: printf(" CKR_NO_EVENT"); break; case CKR_NEED_TO_CREATE_THREADS: printf(" CKR_NEED_TO_CREATE_THREADS"); break; case CKR_CANT_LOCK: printf(" CKR_CANT_LOCK"); break; case CKR_ATTRIBUTE_READ_ONLY: printf(" CKR_ATTRIBUTE_READ_ONLY"); break; case CKR_ATTRIBUTE_SENSITIVE: printf(" CKR_ATTRIBUTE_SENSITIVE"); break; case CKR_ATTRIBUTE_TYPE_INVALID: printf(" CKR_ATTRIBUTE_TYPE_INVALID"); break; case CKR_ATTRIBUTE_VALUE_INVALID: printf(" CKR_ATTRIBUTE_VALUE_INVALID"); break; case CKR_DATA_INVALID: printf(" CKR_DATA_INVALID"); break; case CKR_DATA_LEN_RANGE: printf(" CKR_DATA_LEN_RANGE"); break; case CKR_DEVICE_ERROR: printf(" CKR_DEVICE_ERROR"); break; case CKR_DEVICE_MEMORY: printf(" CKR_DEVICE_MEMORY"); break; case CKR_DEVICE_REMOVED: printf(" CKR_DEVICE_REMOVED"); break; case CKR_ENCRYPTED_DATA_INVALID: printf(" CKR_ENCRYPTED_DATA_INVALID"); break; case CKR_ENCRYPTED_DATA_LEN_RANGE: printf(" CKR_ENCRYPTED_DATA_LEN_RANGE"); break; case CKR_FUNCTION_CANCELED: printf(" CKR_FUNCTION_CANCELED"); break;

Chapter 6. z/OS PKCS#11 197 case CKR_FUNCTION_NOT_PARALLEL: printf(" CKR_FUNCTION_NOT_PARALLEL"); break; case CKR_FUNCTION_NOT_SUPPORTED: printf(" CKR_FUNCTION_NOT_SUPPORTED"); break; case CKR_KEY_HANDLE_INVALID: printf(" CKR_KEY_HANDLE_INVALID"); break; case CKR_KEY_SIZE_RANGE: printf(" CKR_KEY_SIZE_RANGE"); break; case CKR_KEY_TYPE_INCONSISTENT: printf(" CKR_KEY_TYPE_INCONSISTENT"); break; case CKR_KEY_NOT_NEEDED: printf(" CKR_KEY_NOT_NEEDED"); break; case CKR_KEY_CHANGED: printf(" CKR_KEY_CHANGED"); break; case CKR_KEY_NEEDED: printf(" CKR_KEY_NEEDED"); break; case CKR_KEY_INDIGESTIBLE: printf(" CKR_KEY_INDIGESTIBLE"); break; case CKR_KEY_FUNCTION_NOT_PERMITTED: printf(" CKR_KEY_FUNCTION_NOT_PERMITTED"); break; case CKR_KEY_NOT_WRAPPABLE: printf(" CKR_KEY_NOT_WRAPPABLE"); break; case CKR_KEY_UNEXTRACTABLE: printf(" CKR_KEY_UNEXTRACTABLE"); break; case CKR_MECHANISM_INVALID: printf(" CKR_MECHANISM_INVALID"); break; case CKR_MECHANISM_PARAM_INVALID: printf(" CKR_MECHANISM_PARAM_INVALID"); break; case CKR_OBJECT_HANDLE_INVALID: printf(" CKR_OBJECT_HANDLE_INVALID"); break; case CKR_OPERATION_ACTIVE: printf(" CKR_OPERATION_ACTIVE"); break; case CKR_OPERATION_NOT_INITIALIZED: printf(" CKR_OPERATION_NOT_INITIALIZED"); break; case CKR_PIN_INCORRECT: printf(" CKR_PIN_INCORRECT"); break; case CKR_PIN_INVALID: printf(" CKR_PIN_INVALID"); break; case CKR_PIN_LEN_RANGE: printf(" CKR_PIN_LEN_RANGE"); break; case CKR_PIN_EXPIRED: printf(" CKR_PIN_EXPIRED"); break; case CKR_PIN_LOCKED: printf(" CKR_PIN_LOCKED"); break; case CKR_SESSION_CLOSED: printf(" CKR_SESSION_CLOSED"); break; case CKR_SESSION_COUNT: printf(" CKR_SESSION_COUNT"); break; case CKR_SESSION_HANDLE_INVALID: printf(" CKR_SESSION_HANDLE_INVALID"); break; case CKR_SESSION_PARALLEL_NOT_SUPPORTED: printf(" CKR_SESSION_PARALLEL_NOT_SUPPORTED"); break; case CKR_SESSION_READ_ONLY: printf(" CKR_SESSION_READ_ONLY"); break; case CKR_SESSION_EXISTS: printf(" CKR_SESSION_EXISTS"); break; case CKR_SESSION_READ_ONLY_EXISTS: printf(" CKR_SESSION_READ_ONLY_EXISTS"); break; case CKR_SESSION_READ_WRITE_SO_EXISTS: printf(" CKR_SESSION_READ_WRITE_SO_EXISTS"); break; case CKR_SIGNATURE_INVALID: printf(" CKR_SIGNATURE_INVALID"); break; case CKR_SIGNATURE_LEN_RANGE: printf(" CKR_SIGNATURE_LEN_RANGE"); break; case CKR_TEMPLATE_INCOMPLETE: printf(" CKR_TEMPLATE_INCOMPLETE"); break; case CKR_TEMPLATE_INCONSISTENT: printf(" CKR_TEMPLATE_INCONSISTENT"); break; case CKR_TOKEN_NOT_PRESENT: printf(" CKR_TOKEN_NOT_PRESENT - ICSF is not active or not configured for TKDS operations"); break; case CKR_TOKEN_NOT_RECOGNIZED: printf(" CKR_TOKEN_NOT_RECOGNIZED - You are not authorized to perform the token operation"); break; case CKR_TOKEN_WRITE_PROTECTED: printf(" CKR_TOKEN_WRITE_PROTECTED"); break; case CKR_UNWRAPPING_KEY_HANDLE_INVALID: printf(" CKR_UNWRAPPING_KEY_HANDLE_INVALID"); break; case CKR_UNWRAPPING_KEY_SIZE_RANGE: printf(" CKR_UNWRAPPING_KEY_SIZE_RANGE"); break; case CKR_UNWRAPPING_KEY_TYPE_INCONSISTENT: printf(" CKR_UNWRAPPING_KEY_TYPE_INCONSISTENT"); break; case CKR_USER_ALREADY_LOGGED_IN: printf(" CKR_USER_ALREADY_LOGGED_IN"); break; case CKR_USER_NOT_LOGGED_IN: printf(" CKR_USER_NOT_LOGGED_IN"); break; case CKR_USER_PIN_NOT_INITIALIZED: printf(" CKR_USER_PIN_NOT_INITIALIZED"); break; case CKR_USER_TYPE_INVALID: printf(" CKR_USER_TYPE_INVALID"); break; case CKR_USER_ANOTHER_ALREADY_LOGGED_IN: printf(" CKR_USER_ANOTHER_ALREADY_LOGGED_IN"); break; case CKR_USER_TOO_MANY_TYPES: printf(" CKR_USER_TOO_MANY_TYPES"); break; case CKR_WRAPPED_KEY_INVALID: printf(" CKR_WRAPPED_KEY_INVALID"); break; case CKR_WRAPPED_KEY_LEN_RANGE: printf(" CKR_WRAPPED_KEY_LEN_RANGE"); break; case CKR_WRAPPING_KEY_HANDLE_INVALID: printf(" CKR_WRAPPING_KEY_HANDLE_INVALID"); break; case CKR_WRAPPING_KEY_SIZE_RANGE: printf(" CKR_WRAPPING_KEY_SIZE_RANGE"); break; case CKR_WRAPPING_KEY_TYPE_INCONSISTENT: printf(" CKR_WRAPPING_KEY_TYPE_INCONSISTENT"); break; case CKR_RANDOM_SEED_NOT_SUPPORTED: printf(" CKR_RANDOM_SEED_NOT_SUPPORTED"); break; case CKR_RANDOM_NO_RNG: printf(" CKR_RANDOM_NO_RNG"); break; case CKR_BUFFER_TOO_SMALL: printf(" CKR_BUFFER_TOO_SMALL"); break; case CKR_SAVED_STATE_INVALID: printf(" CKR_SAVED_STATE_INVALID"); break; case CKR_INFORMATION_SENSITIVE: printf(" CKR_INFORMATION_SENSITIVE"); break;

198 System z Cryptographic Services and z/OS PKI Services case CKR_STATE_UNSAVEABLE: printf(" CKR_STATE_UNSAVEABLE"); break; case CKR_CRYPTOKI_NOT_INITIALIZED: printf(" CKR_CRYPTOKI_NOT_INITIALIZED"); break; case CKR_CRYPTOKI_ALREADY_INITIALIZED: printf(" CKR_CRYPTOKI_ALREADY_INITIALIZED"); break; case CKR_MUTEX_BAD: printf(" CKR_MUTEX_BAD"); break; case CKR_MUTEX_NOT_LOCKED: printf(" CKR_MUTEX_NOT_LOCKED"); break; /* Otherwise - Value does not match a known PKCS11 return value */ } }

void showError( char *str, CK_RV rc ) { printf("%s returned: %d (0x%0x)", str, rc, rc ); ProcessRetCode( rc ); printf("\n"); }

CK_RV createToken( void ) { CK_VOID_PTR p = NULL; // @D1C CK_RV rc; CK_FLAGS flags = 0;

printf("Creating a token... \n"); /* wait for slot event. On z/OS this creates a new slot synchronously */ rc = funcs->C_WaitForSlotEvent(flags, &slotID, p); if (rc != CKR_OK) { showError(" C_WaitForSlotEvent #1", rc ); return !CKR_OK; } /* The slot has been created. Now initialize the token in the slot */ /* On z/OS no PIN is required, so we will pass NULL. */ rc= funcs->C_InitToken(slotID, NULL, 0, tokenName); if (rc != CKR_OK) { showError(" C_InitToken #1", rc ); if (rc == CKR_ARGUMENTS_BAD) { printf(" Make sure your the token name you specified meets ICSF rules:\n"); printf(" Contains only alphanumeric characters, nationals (@#$), and periods.\n"); printf(" The first character cannot be a numeric or a period.\n"); } return !CKR_OK; }

return CKR_OK; }

CK_RV encryptRSA( void ) { CK_BYTE data1[100]; CK_BYTE data2[256]; CK_BYTE cipher[256]; CK_SLOT_ID slot_id; CK_SESSION_HANDLE session; CK_MECHANISM mech; CK_OBJECT_HANDLE publ_key, priv_key; CK_FLAGS flags; CK_ULONG i; CK_ULONG len1, len2, cipherlen; CK_RV rc;

Chapter 6. z/OS PKCS#11 199 static CK_OBJECT_CLASS class = CKO_PUBLIC_KEY; static CK_KEY_TYPE type= CKK_RSA; static CK_OBJECT_CLASS privclass = CKO_PRIVATE_KEY; static CK_BBOOL true = TRUE; static CK_BBOOL false = FALSE;

static CK_ULONG bits = 1024; static CK_BYTE pub_exp[] = { 0x01, 0x00, 0x01 };

/* Attributes for the public key to be generated */ CK_ATTRIBUTE pub_tmpl[] = { {CKA_MODULUS_BITS, &bits, sizeof(bits) }, {CKA_ENCRYPT, &true, sizeof(true) }, {CKA_TOKEN, &true, sizeof(true) }, {CKA_VERIFY, &true, sizeof(true) }, {CKA_PUBLIC_EXPONENT, &pub_exp, sizeof(pub_exp) } };

/* Attributes for the private key to be generated */ CK_ATTRIBUTE priv_tmpl[] = { {CKA_DECRYPT, &true, sizeof(true) }, {CKA_TOKEN, &true, sizeof(true) }, {CKA_SIGN, &true, sizeof(true) } };

slot_id = slotID; flags = CKF_SERIAL_SESSION | CKF_RW_SESSION; printf("Opening a session... \n"); rc = funcs->C_OpenSession( slot_id, flags, (CK_VOID_PTR) NULL, NULL, &session ); if (rc != CKR_OK) { showError(" C_OpenSession #1", rc ); return !CKR_OK; }

printf("Generating keys. This may take a while... \n"); mech.mechanism = CKM_RSA_PKCS_KEY_PAIR_GEN; mech.ulParameterLen = 0; mech.pParameter = NULL;

rc = funcs->C_GenerateKeyPair( session, &mech, pub_tmpl, 4, priv_tmpl, 2, &publ_key, &priv_key ); if (rc != CKR_OK) { showError(" C_GenerateKeyPair #1", rc ); return !CKR_OK; }

/* now, encrypt some data */ len1 = sizeof(data1); len2 = sizeof(data2); cipherlen = sizeof(cipher);

for (i=0; i < len1; i++) data1[i] = (i) % 255;

mech.mechanism = CKM_RSA_PKCS;

200 System z Cryptographic Services and z/OS PKI Services mech.ulParameterLen = 0; mech.pParameter = NULL;

printf("Enciphering data... \n"); rc = funcs->C_EncryptInit( session, &mech, publ_key ); if (rc != CKR_OK) { showError(" C_EncryptInit #1", rc ); funcs->C_CloseSession( session ); return !CKR_OK; }

rc = funcs->C_Encrypt( session, data1, len1, cipher, &cipherlen ); if (rc != CKR_OK) { showError(" C_Encrypt #1", rc ); funcs->C_CloseSession( session ); return !CKR_OK; }

/* now, decrypt the data */ printf("Deciphering data... \n"); rc = funcs->C_DecryptInit( session, &mech, priv_key ); if (rc != CKR_OK) { showError(" C_DecryptInit #1", rc ); funcs->C_CloseSession( session ); return !CKR_OK; }

rc = funcs->C_Decrypt( session, cipher, cipherlen, data2, &len2 ); if (rc != CKR_OK) { showError(" C_Decrypt #1", rc ); funcs->C_CloseSession( session ); return !CKR_OK; }

/* PKCS - returns clear data as is */ if (len1 != len2) { printf(" ERROR: lengths don't match\n"); printf(" Length of original data = %d, after decryption = %d\n",len1, len2); funcs->C_CloseSession( session ); return !CKR_OK; }

for (i=0; i C_CloseSession( session ); return !CKR_OK; } }

printf("Closing the session... \n"); rc = funcs->C_CloseSession( session ); if (rc != CKR_OK) { showError(" C_CloseSession #1", rc ); return !CKR_OK; }

return CKR_OK; }

Chapter 6. z/OS PKCS#11 201

CK_RV getFunctionList( void ) { CK_RV rc; CK_RV (*pFunc)(); void *d; #ifdef _LP64 char e[]="CSNPCA64"; #elif _XPLINK_ /* @D2A */ char e[]="CSNPCA3X"; /* @D2A */ #else char e[]="CSNPCAPI"; #endif

printf("Getting the PKCS11 function list...\n");

d = dlopen(e,RTLD_NOW); if ( d == NULL ) { printf("%s not found in linklist or LIBPATH\n",e); // @D1A return !CKR_OK; }

pFunc = (CK_RV (*)())dlsym(d,"C_GetFunctionList"); if (pFunc == NULL ) { printf("C_GetFunctionList() not found in module %s\n",e); // @D1A return !CKR_OK; } rc = pFunc(&funcs);

if (rc != CKR_OK) { showError(" C_GetFunctionList", rc ); return !CKR_OK; }

return CKR_OK;

} void displaySyntax(char *pgm) { printf("usage: %s { -t | -h }\n\n", pgm ); printf(" -t = The name of a permanent token to create for the test. The\n"); printf(" name must be less than 33 characters in length and contains only alphanumeric\n"); printf(" characters, nationals (@#$), and periods. The first character cannot be a\n"); printf(" numeric or a period. The token should not exists before this test.\n\n"); printf(" -h = Displays this help.\n\n"); }

void main( int argc, char **argv ) { CK_C_INITIALIZE_ARGS cinit_args; CK_RV rc, i;

memset(tokenName, ' ', sizeof(tokenName)); /* Token name is left justified, padded with blanks */

if (argc == 3) { if (strcmp(argv[1], "-t") == 0)

202 System z Cryptographic Services and z/OS PKI Services if (strlen(argv[2]) > 0 && strlen(argv[2]) < 33) { memcpy(tokenName, argv[2], strlen(argv[2])); } else { displaySyntax(argv[0]); return; } else { displaySyntax(argv[0]); return; } } else { displaySyntax(argv[0]); return; }

rc = getFunctionList(); if (rc != CKR_OK) { printf("getFunctionList failed!\n"); // @D1C return; }

memset( &cinit_args, 0x0, sizeof(cinit_args) ); cinit_args.flags = CKF_OS_LOCKING_OK;

printf("Initializing the PKCS11 environment...\n"); rc = funcs->C_Initialize( &cinit_args ); if (rc != CKR_OK) { showError(" C_Initialize", rc ); return; }

rc = createToken(); if (rc != CKR_OK) { funcs->C_Finalize( NULL ); return; }

rc = encryptRSA(); if (rc != CKR_OK) { funcs->C_Finalize( NULL ); return; }

rc = funcs->C_Finalize( NULL ); if (rc != CKR_OK) { showError(" C_Initialize", rc ); return; } printf("Test completed successfully!\n");

}

In ICSF Writing PKCS #11 Applications, SA23-2231, you can find another PKCS#11 test program example.

Chapter 6. z/OS PKCS#11 203

204 System z Cryptographic Services and z/OS PKI Services

Part 2

Part 2 Managing keys

This session of the book discusses the following: PKI services A sample scenario using PKI services to provide a certificate though a Web browser interface and exploiting the SSL and PKCS#11 APIs.

206 System z Cryptographic Services and z/OS PKI Services

Chapter 7. z/OS PKI Services

z/OS PKI Services deploys a full certificate authority solution running on z/OS. It was introduced as a base element at z/OS V1.3. The product has evolved since then with several new functions incorporated in each release. Customers have taken advantage of this solution to issue and manage thousands of digital certificates in-house. z/OS PKI Services is a competitive solution exploiting the robustness, availability, scalability, and security provided by System z.

This chapter provides an overview of the z/OS PKI Services solution, describing each of its components and providing step-by-step guidance to its implementation. A description of the evolution of z/OS PKI Services, including the new functions deployed at each release, is also provided.

Public Key Infrastructure (PKI) is the infrastructure based on public key cryptography to create, manage, store, distribute, and verify digital certificates. In summary, it is the infrastructure that manages the entire digital certificate life cycle.

7.1.1 Certificate life cycle

The digital certificate life cycle (see Figure 7-1) begins when a user requests a certificate. When the request reaches the certificate authority, the infrastructure administrator can approve or reject the request. When the request is approved, the CA generates and distributes the digital certificate. The certificate owner uses the certificate until it expires or until it is revoked by the administrator or its owner. If the certificate expires, the owner has the chance to renew it and the life cycle starts again.

ƒ User Requests Certificate

ƒ User Renews Certificate

re jects ƒ Administrator Approves the request

ƒ CA Generates and distributes ƒ Certificate Expires certificate Or ƒ Owner uses the ƒ Administrator or certificate User Revokes Certificate

Figure 7-1 Digital certificate life cycle

7.1.2 z/OS PKI Services

z/OS PKI Services is a complete solution for managing the digital certificate life cycle running under z/OS V1.3 and later.

Certificate generation and administrative functions are driven via customizable Web pages. z/OS PKI Services supports browser and server digital certificates. It provides an automatic or administrator approval process, as well as user or administrator revocation process. It deploys e-mail notification for requestors and administrators, informing them about certificate request completion, certificate rejects, expiration warnings, and pending requests.

z/OS PKI Services is closely tied to RACF or any equivalent product that supports R_PKIServ callable services. It supports more functions than the RACDCERT command.

z/OS PKI Services supports multiple revocation-checking mechanisms. It deploys CRLs (Certificate Revocation Lists) and OCSP (Online Certificate Status Protocol). These functions

208 System z Cryptographic Services and z/OS PKI Services are not supported through RACDCERT commands. z/OS PKI Services provides the Trust Policy plug-In. It is an application interface for checking the certificate validation.

z/OS PKI Services is compliant with the PKIX architectural model, which was built by the IETF (Internet Engineering Task Force) PKIX working group. The PKIX working group was established in 1995 with the intent of developing Internet standards needed to support an x.509-based PKI (see Figure 7-2).

http://www.ietf.org/internet-drafts/draft-ietf-pkix-roadmap-06.txt

PKIX: PKIX: Format of Certificate Certificate Revokation List Management Certification Authority Certificate Revocation Lists CA Policy for the Domain Issuance is X.509 V2 Protocol (CMP) and (optionally with a Certificate Message Registration Authority)) Syntax (CMS, PKCS-10) Certificates and 2-Certificate Issuance CRLs 1-Certificate Request Repository PKIX: 4-Certificate Revocation Format of Certificate Checking is X.509 V3 Cerificate Certificate, Owning exploiting Entity Entity PKIX: CRL repository 3-Certificate Utilization PKI (LDAP directory) Online Certificate Status Protocol (OCSP) Figure 7-2 PKIX architectural model

According to this open standard, the digital certificate request has to be in PKCS#10 format; the Certificate Revocation List (CRL) has to be in x.509 V2 format within an LDAP directory as repository. The digital certificate format has to be x.509 V3.

7.1.3 z/OS PKI Services structure

Before describing the z/OS PKI Services structure, let us list the z/OS PKI Services solution requirements, and then we will fit these elements inside the structure. IBM HTTP Server for z/OS RACF of any functional equivalent supporting R_PKIServ callable services PKI Services daemon OCSF - Open Cryptographic Services Facility OCEP - Open Cryptographic Enhanced Plug-in (optional) sendmail (optional) LDAP directory ICSF (optional)

Chapter 7. z/OS PKI Services 209 You can see, illustrated in Figure 7-3, how these elements fit together.

RA HTTP server for z/OS Admin Browser Static Web Install/Config: H Pages T SMP/E Install End User T Browser P D CGI Scripts Post Apply Script/Job OCSP OCSP CGI Requester PKI Exit z/OS PKI Services RACF Set up Daemon exec RACF Glue Rtn Combined RA/CA process PC SAF R_PKIServ VSAM RACF Services System SSL OCSF Request Queue ICSF LDAP PKI DL VSAM TP z/OS Issued RACF Cert List DB LDAP - New code SMF Directory - Updated code Audit SMF Records Unload Figure 7-3 PKI Services structure

IBM HTTP Server for z/OS User certificate generation and administrative functions are performed through customizable Web pages. IBM HTTP Server for z/OS is the Web page interface for z/OS PKI Services. It is a z/OS base element.

The Web page logic and contents are defined in a certificate template file. This file contains a mixture of true HTML and HTML-like tags. The Common Gateway Interface (CGI) script tasks read the template file to form the Web pages and to control the flow. It also reads all the input values from the Web page and constant values from the template file to built the parameter list to call R_PKIServ callable services.

The CGI task also provides a hook to call PKI Exit, an installation-provided exit routine available for: Providing additional authorization checking Validating and changing parameters Capturing certificates for further processing

SCEP (Simple Certificate Enrollment Protocol) and OCSP (Online Certificate Status Protocol) client interfaces run on CGIs under IBM HTTP Server, but no Web pages are associated with these services.

The IBM HTTP Server for z/OS is not involved in generating key pairs for users or for server certificates. This function is driven by the browser Cryptographic Service Provider (CSP) to the device selected by the user (e.g., smart card, token, or the browser software itself). Key pairs for server certificates are generated by the software in the server that is going to use the certificate.

210 System z Cryptographic Services and z/OS PKI Services RACF RACF provides support for the R_PKIServ callable services that is the core component of z/OS PKI Server solution.

R_PKIServ callable services is the interface between the CGIs and the PKI Services daemon. It performs authorization checking and parameter validation.

User functions such as those that request, export, verify, revoke, renew, and suspend certificate and respond to certificate are performed by RACF through R_PKIServ callable services. Administrator functions such as query, approve, modify, reject, suspend, resume, and revoke are also performed by R_PKIServ callable services. RACF is the only z/OS PKI Services component that is licensed.

PKI Services daemon The PKI Services daemon is provided by the z/OS PKI Services code. It is responsible for managing the services threads for incoming requests. It also controls the background threads for certificate approval and for issuing the Certificate Revocation List (CRL). The PKI Services daemon manages the VSAM databases for certificate requests (Object Store) and Issued Certificate List (ICL).

Figure 7-4 depicts the flow of z/OS PKI Services.

VSAM

HTTP 1 2 Object PKCS#10 PKCS#10 Store

6 End User x.509 z/OS PKI Services

VSAM Issued 5 Certificate 3 x.509 List

4 HTTPS

DB2 CRL z/OS PKI 7 LDAP x.509 Administrator Directory

Figure 7-4 Flow of z/OS PKI Services

Open Cryptographic Services Facility (OCSF) PKI Services requires OCSF to be installed and configured so that the user ID under which the PKI Services daemon runs can use required services.

Chapter 7. z/OS PKI Services 211 OCEP - Open Cryptographic Enhanced Plug-in (optional) You need to install and configure OCEP if your installation plans to write an application to implement the use of PKI Trust Policy (PKITP).

sendmail (optional) You need to configure sendmail if your installation plans to send e-mail notifications to users for certificate-related events, such as certificate expiration.

LDAP directory Use of an LDAP server is required to maintain information about PKI Services certificates in a centralized location. The z/OS LDAP server is preferred, but you can use a non-z/OS LDAP server if it can support the objectClass and attributes that PKI Services uses. Typical PKI Services usage requires an LDAP directory server that supports the LDAP (Version 2) protocol (and the PKIX schema), such as the z/OS LDAP server.

If you intend to use the z/OS LDAP server, you can configure it to use the TDBM back end or, as of z/OS V1.8 and the new ITDS server, the LDBM may also be used. Through the integration of the z/OS LDAP server with DB2®, the directory can support millions of directory entries. It also enables client applications, such as PKI Services, to perform database storage, update, and retrieval transactions.

ICSF (optional) ICSF is preferred but not required. You can begin using PKI Services without installing ICSF and install it later without reinstalling PKI Services. We strongly suggest you use ICSF to store and protect your certificate authority’s private key.

Note: For more information about these prerequisites and how to install and customize them, see z/OS V1R9.0 Cryptographic Services PKI Services Guide and Reference, SA22-7693.

212 System z Cryptographic Services and z/OS PKI Services 7.1.4 Scalability and availability

Starting with the z/OS V1.4, PKI Services can take advantage of the VSAM Record Level Sharing capability for the VSAM database. In this way, as illustrated in Figure 7-5, an installation can scale up to multiple z/OS PKI Services instances sharing the same VSAM databases.

LPAR LPAR LPAR z/VM Guest Guest Guest z/OS V1R9 LINUX z/OS V1R9 z/OS V1R9 z/OS V1R9 PKI Server 5 PKI Server 1 PKI Server 2 PKI Server 3 PKI Server 3

PKI data set VSAM RLS

Figure 7-5 A scalable solution

Chapter 7. z/OS PKI Services 213 Taking advantage of the z/OS infrastructure, PKI Services relies on a highly available infrastructure. In Figure 7-6 you can see how an installation can build a robust solution across multiple servers, providing hardware and software fail-over capability.

Contingency LDAP Connection LDAP LDAP Replication Implementation Master Master

ESCON ESCON /FICON /FICON ISC-3 Links

LPARLPAR LPAR LPAR LPAR Coupling PKIPKI 1 PKI 2 Coupling PKI 3 PKI 4 Facility Facility ( ICF ) z/OSz/OS V1R9V1R9 z/OS V1R9 ( ICF ) z/OS V1R9 z/OS V1R9 DB2DB2 forfor DB2 for LDAPLDAP VSAM Record LDAP ServerServer Level Sharing VSAM Record Server Level Sharing HTTPHTTP ServerServer HTTP Server HTTP Server HTTP Server

ISC-3 Links

VSAM Remote Copy Secondary VSAM ESCON ICSF VSAM /FICON Contingency CKDS VSAM ICSF VSAM ICSF Connection CKDS VSAM PKDS VSAM ICSF ICL PKDS VSAM Object VSAM Store ICL Object VSAM Remote Copy Implementation VSAM Remote ICL Store Copy VSAM PKI 4 Object ICL Store Primary PKI 1 Object RACF Store PKI 3 RACF PKI 2

Figure 7-6 Highly available infrastructure

7.2 A product in constant evolution

z/OS PKI Services was introduced as a base element at z/OS V1.3. and since then it has been constantly evolving. New functions have been deployed in almost every release.

7.2.1 z/OS V1.4 enhancements

The main change introduced in z/OS V1.4 is Parallel Sysplex architecture support. In this release, multiple z/OS PKI Services instances can share the same VSAM databases. z/OS V1.4 requires a VSAM Record Level Sharing implementation to share access to the VSAM database.

Starting with z/OS V1.4, PKI Services exploits sendmail for sending e-mail notifications to users. It provides notification when a certificate is ready for retrieval or is expiring or when a certificate request has been rejected.

To authenticate the PKI Services daemon to access the LDAP server, a bind password is required. This password is stored in clear format in the pkiserv.conf file. The RACF LDAPBIND class and the IRR.PROXY.DEFAULTS profile in the RACF FACILITY class support was introduced in z/OS V1.4 to enable PKI Services to use encrypted LDAP bind passwords.

214 System z Cryptographic Services and z/OS PKI Services Additional minor changes were introduced in z/OS V1.4: Support for MAIL, STREET and POSTALCODE distinguished name qualifiers. Digital certificate serial numbers and event files previously maintained as separate files were moved to the VSAM object store.

7.2.2 z/OS V1.5 enhancements

The vast majority of changes in PKI Services on z/OS V1.5 were introduced to support IdenTrust requirements.

IdenTrust, Inc. (http://www.identrust.com) is a global provider in trusted identity solutions that are endorsed by global financial institutions, government agencies, and commercial entities in 160 countries. It was established as Identrus, Inc., and the corporate name was changed to IdenTrust, Inc., in March 2006.

IdenTrust has created a framework for the provision of certification authority services to its participating financial institutions (see Figure 7-7). IBM received official certification through the Identrus Compliant Program for its PKI Services at z/OS V1.5 and later. The press release stating this certification can be found at: http://www.identrust.com/company/press_releases/2005/release_050706.html

To Identrus Root

Issuing Participant Relying Participant

CA Identrus FI Environment Identrus FI Environment

Registration Certification Validation Finance Local RA Finance Backend Authority Authority Authority Client Backend (RA) (CA) (VA) (LRA) Systems Systems OCSP Responder Ident Pay Warr ... Ident Pay Warr ...

Transaction Coordinator (TC) Transaction Coordinator (TC)

Smart Card (SC)

... Ident Pay Warr Signing Interface Library Digital Signature Messaging (SIL) System (DSMS)

Web browser SC Reader Web App.Srv. HSM

Client Apps e-business Apps

Subscriber Relying Customer

Figure 7-7 IdenTrust architecture

As illustrated in Figure 7-7, the certificate authority plays a central role. IdenTrust divides the function of the CA into three subcomponents: Registration Authority (RA) - Determines who gets a certificate and the information it should contain (usually manually driven.) Certificate authority (CA) - Process that creates and manages certificates and revocation information. Validation Authority (VA) - Process that can be invoked to verify the validity of a certificate using the Online Certificate Status Protocol (OCSP).

Chapter 7. z/OS PKI Services 215 In PKI Services the RA and CA are combined in one component. All other components must be supplied by other vendors, including the VA. PKI Services publishes its certificate revocation information to LDAP to make it available to the VA vendor. Figure 7-8 illustrates combining the PKI Services structure with the IdenTrust architecture.

To Identrus Root Issuing Participant Relying Participant

z/OS - PKI Services Identrus FI Environment Identrus FI Environment Finance Validation Local RA Finance Backend Registration Client Backend Authority Systems Authority (VA) (LRA) Systems (RA) Certification OCSP ...... Authority Responder Ident Pay Warr Ident Pay Warr (CA) Transaction Coordinator (TC) Transaction Coordinator (TC)

Smart Card (SC) LDAP

... Ident Pay Warr Signing Interface Library Digital Signature Messaging (SIL) System (DSMS)

Web browser SC Reader Web App.Srv. HSM

Client Apps e-business Apps -PKI Services Subscriber Relying Customer -Other Vendor

Figure 7-8 IdenTrust and PKI Service

To be IdenTrust compliant, PKI Services added additional support for certificate extension. This support included more granularity for the KeyUsage extension and support for new extensions, ExtKeyUsage and AuthorityInfoAccess (AIA). The AIA extension holds the URL of the (vendor-supplied) OCSP responder. IdenTrust also mandates that certain extensions must be marked critical. Thus IBM now supports that requirement with a new %%Critical%% directive. These directives are normally hard-coded in the certificate templates, or, in the case of KeyUsage and ExtKeyUsage, may be selectable by the user.

The following is a list of the new and enhanced certificate extensions: – KeyUsage - New values for this extension were introduced, adding support for all RSA-related flags as defined by RFC2459. Examples of these new values are digitalsignature in certificates intended for authentication and keyencipherment in certificates intended for key transport. – ExtKeyUsage - Allows additional key usages to be defined serverauth, clientauth, codesigning, emailprotection, timestamping, and ocspsigning. This extension is also related to the intended purpose of the certificate and allows more granularity to the key usage to be defined. Possible values for the x.509 ExtKeyUsage certificate extension are: • clientauth, for client-side authentication • codesigning, for code signing • emailprotection, for e-mail protection • ocspsigning, for OCSP response signing • serverauth, for server-side authentication • timestamping, for digital timestamping

216 System z Cryptographic Services and z/OS PKI Services – AuthorityInfoAccess - Needed for vendor VA support (OCSP) – Extensions critical marking - Support on a per template basis (ExtKeyUsage, CertPolicies, HostIdMappings, SubjectAltName)

The Identrus Compliant Program requires that certain certificate extensions be marked critical. z/OS V1.5 introduced support for specifying which certificate extensions are marked critical. Prior to z/OS V1.5, PKI Services could only be configured to have a global set of policies. Support was included at z/OS V1.5 PKI Services to permit unique policies for each certificate type on a certificate-template basis.

A new certificate template provides the IdenTrust-standardized two-year PKI Authenticode–code signing server certificates.

The support for temporarily suspending and resuming certificates was added at z/OS V1.5. This function temporarily revokes a certificate. Users may suspend their own browser certificates via a Web interface; it requires SSL with client authentication. The PKI Administrator also may suspend users’ certificates, but only the PKI Administrator may resume users’ certificates.

This feature may be useful in some situations - for example, when users do not want to leave their certificates active while on vacation. In this case, the certificate may be suspended and then resumed when the vacation is over. Along with the suspend and resume support, a grace period is also included.

The grace period is the time elapsed since a certificate was suspended until it is resumed. If the grace period has been exceeded, the certificate is permanently revoked the next time the Certificate Revocation List (CRL) is issued. The grace period is a customizable configuration file directive. Along with suspend and resume support, the PKI Administrator panel was enhanced to include a query on suspended certificates. z/OS PKI Services produces SMF records type 80. Introduced at z/OS V1.5, an SMF record is written whenever a CRL is published on the LDAP for internal auditing.

The multiple application domain support added at z/OS V1.5 is a way of subdividing customers. This function enables each customer to have a unique home page and a set of certificate templates.

All CGIs reside under a common URL - http(s):///PKIServ - by default. A single application domain (PKISERV) is used for users’ and administrators’ pages. z/OS V1.5 PKI Services now supports multiple application domains.The sample PKI Services template file contains two application sections: PKISERV and CUSTOMERS. The PKISERV application includes all templates and functions. The CUSTOMERS application contains all templates and functions, but it does not contain the button at the bottom of the home page that links to the Administration home page.

PKI Services performance enhancements Significant performance support was introduced at z/OS V1.5 PKI Services. Among these enhancements, CRL Distribution Point (DP) is the most important one.

Certificate Revocation Lists (CRLs) contain the serial numbers of the certificates that have been revoked. According to the PKIX architectural mode, the CRLs have to be published in an LDAP directory. The LDAP directory address is stored in each issued certificate, in a standard x.509 V3 certificate extension. To validate a certificate, an application checks for revocation by retrieving and examining the appropriate CRL. On a system that has issued a large number of certificates, the number of certificates that are revoked at any given time can result in a large global CRL.

Chapter 7. z/OS PKI Services 217 Prior to z/OS V1.5, PKI Services published one global CRL per certificate authority. z/OS V1.5 introduced CRL Distribution Point (DP) support. DPs are locations where partial CRLs are stored. They are stored in separate LDAP entries directly below the CA’s entry. To validate a certificate, an application need only retrieve the appropriate DP CRL. This CRL is pointed to by the CRLDistributionPoint extension within the certificate.

The number of certificates managed by each distribution point is customizable by the statement CRLDistSize in the configuration file. For example, if you specify CRLDistSize=500, each distribution point will contain up to 500 certificate entries. In summary, the digital certificates from serial number 001 to serial number 500, if revoked, have an entry at CRL Distribution Point 1. Digital certificates from serial number 501 to 1000 contain the entry in CRL Distribution Point 2, and so forth. If an application is trying to check whether the digital certificate serial number 700 is revoked, for example, only the CRL Distribution Point 2 is retrieved and examined.

Additional VSAM Alternate Indexes were introduced to improve the search performance in ObjectStore and ICL data sets. Optional VSAM buffering was also introduced. It reduces the access to the ObjectStore and Issued Certificate List (ICL) data sets, improving performance.

An ICL data set holds a copy of every certificate issued by PKI Services. By default, this includes expired certificates as well. To save space in the ICL and improve I/O performance, PKI Services can be configured to remove expired certificates after a specified time period through the RemoveExpiredCerts keyword in pkiserv.conf. However, the copy stored in LDAP is still available.

System SSL performs better than OCSF. In z/OS V1r5, System SSL replaced the vast majority of functions performed by OCSF. The certificate validation API (pkitp) still uses OCSF cryptography.

218 System z Cryptographic Services and z/OS PKI Services 7.2.3 z/OS V1.7 enhancements

z/OS V1.7 introduced two major changes: support for OCSP (Online Certificate Status Protocol) and creation of the OtherName format in the SubjectAltName extension. Figure 7-9 summarizes the PKI Services architecture distributed in z/OS V1.7.

Note: No PKI Service change was deployed at z/OS V1.6.

Figure 7-9 PKI Services architecture available in z/OS V1.7

Online Certificate Status Protocol (OCSP) is a dynamic way to validate the revoke status of a digital certificate online in opposite to the static mechanism provided by Certificate Revocation Lists.

Let us assume that our PKI Services issues a CRL every six hours. If a digital certificate is revoked just after a CRL is published, this certificate is valid until the next CRL is issued and published. This time lapse provides a large window of time for possible unwanted use of this certificate. OCSP fixes this problem, checking the certificate status online.

The z/OS V1.7 PKI Services daemon operates as an OCSP responder for the certificates it issues. The OCSP responder function is enabled and disabled by the OCSPType keyword in the configuration file.

R_PKIServ callable services was updated to include the RESPOND function code. Also, caocsp, a new CGI program, was introduced to GET or POST OCSP requests at the HTTP server and call the R_PKIServ callable services RESPOND function. The callable services performs parameter and authority checks and passes control to the PKI Services daemon for processing. The daemon returns a response to the callable services, which is passed back to the CGI and the original requestor. A new audit record is created when a valid response is generated.

Chapter 7. z/OS PKI Services 219 The PKI Services Trust Policy (PKITP) is an OCSF plug-in for performing certificate validation. It can validate the certificates issued by PKI Services and other certificate authorities. Prior to z/OS V1.7, applications running on z/OS could validate the revocation status of a digital certificate, retrieving the CRL from the LDAP repository. In sync with the introduction of OCSP support at z/OS V1.7, PKITP was enhanced to permit applications running on z/OS to invoke an online validation service that uses OCSP.

In z/OS V1.7, certificate revocation status checking has changed with OCSP support. Now the following sequence is performed: 1. The OCSP responder performs a check based on the AuthorityInfoAccess extension provided in the certificate. 2. A check is performed on the URI format CRL/ARL distribution points (ARL, Authority Distribution List) based on the CRLDistributionPoint extension information provided in the certificate. This information includes the server location. 3. The Distinguished Name has the format for the CRL/ARL distribution points. No server location is indicated in the certificate extension. 4. The Master CRL/ARL is obtained.

Previously, only steps 3 and 4 were performed.

Another improvement in the revocation-checking arena is the enhanced CRL Distribution Point deployed at z/OS V1.7.

The CRL Distribution Point is an extension in the certificate pointing to where the CRL repository is located. Prior to z/OS V1.7, its format was a Directory Name; CN=CRL1,O=IBM,C=BR is an example of a directory name. Now z/OS V1.7 introduces support for providing the CRL location in a URI form using the LDAP or HTTP protocol.

URI-formatted distribution points do not support secure protocols such as HTTPS or LDAP.

Certificate validation applications can now get the CRL location information straight from the certificate itself. The PKI Services Trust Policy was also updated to support the new distribution point formats.

Authority Revocation List, ARL Distribution Points support was also introduced in z/OS V1.7. ARLs are the Certificate Revocation Lists for certificate authority digital certificates.

New configuration file keywords were added to support these new DP formats. CRLDistURIn indicates the creation of the CRLDistributionPoint extension in the URI format. You can have more than one URI, and the n value indicates the URI number. CRLDistDirPath indicates the HFS directory where the CRL Distribution Point is stored for the HTTP protocol, and ARLDist indicates whether a CRLDistributionPoint extension should be created for CA certificates.

The Subject AltName is an extension in a digital certificate. Prior to z/OS V1.7, only e-mail addresses, domain server names, and URI and IP address formats were supported in it.

220 System z Cryptographic Services and z/OS PKI Services In addition, z/OS V1.7 added the OtherName format. The creation of the OtherName format in the SubjectAltName extension brought great flexibility to z/OS PKI Services. The OtherName format is free formed. The format of an OtherName is a dotted decimal OID followed by a comma, followed by data specific to the OID. (See Figure 7-10.)

All these are different forms in the Subject Alternate Name extension

Figure 7-10 OtherName format in SubjectAltName extension

Customers determine the OID and data format to use in the extension and design their own PKI Services web page dialogs to enable the creation and display of the field(s). It is possible to customize this format to hold any kind of data.

To support this new extension, R_PKIServ callable services had to be modified to understand and include this new extension inside the certificate.

Now any information can be included in the OtherName format for the SubjectAltName extension. The same applies when the customer’s driver license number and its expiration date must be included. The OtherName format is used in some countries to include a set of personal document numbers inside a digital certificate.

R_PKIServ callable services were modified to support the new OtherName format. It is a free-formed format capable of containing any data without requiring changes to R_PKIServ callable services.This support provided the flexibility required by users of the PKI Services solution. z/OS V1.7 PKI Services deployed support for the Digital Signature Algorithm (DSA). DSA is a signing algorithm defined by the National Institute of Standards and Technology (NIST).

Chapter 7. z/OS PKI Services 221 This support was also deployed to RACF. It permits the RACDCERT command to generate DSA public/private key pairs for use in certificates.This algorithm cannot be used with RACDCERT ICSF and PCICC keywords because ICSF does not support the DSA algorithm. Due to this limitation, DSA key pairs are generated via software.

DSA key length is up to 2048 bits, and digital certificates with DSA keys may only be used for signing and signature verification.

A z/OS PKI Services certificate authority key can be a DSA key. It also can generate certificates on request with DSA keys.

Some minor usability enhancements were introduced at z/OS V1.7: All PKI Services daemon-created threads are now managed in the same manner and prevent the daemon from hanging when a stop command is issued from the console. During PKI Services initialization, errors detected in the pkiserv.conf file are logged as error-level messages in the job log of the daemon. The R_PKIServ callable services VERIFY function code was enhanced to accept PKCS#7 certificate packages, in addition to x509 certificates, as input. To debug a problem in the z/OS PKI Services Web pages prior to z/OS V1.7, customers had to edit each REXX exec to set the debug flag on. This is not the recommended place for modifications. z/OS V1.7 has the same debug option, but in addition, debug can be enabled for all Web pages by updating the pkiserv template file.

7.2.4 z/OS V1.8 enhancements

By far the most important enhancement introduced in z/OS V1.8 is the capability of running multiple z/OS PKI Services instances on a single z/OS image.

Prior to z/OS V1.8, the PKI Services started task could not be configured to have more than one signing CA certificate and key. On a single image, only one copy of the PKI Services started task could run at any given time.

V1.8 PKI Services introduces multi-CA mode. Multiple PKIServ daemons may be started, each pointing to its own set of resources. Each set of resources is a CA domain (as opposed to an application domain). Multi-CA comes in two different configurations: Completely independent CAs (see Figure 7-11 on page 223) Each CA has its own administrators and users, and administrators may not be aware of other CAs. With independent mode, everything is separated, including the PKI administrators. Each CA has one certificates template file that has separate APPLICATION sections for the administrators and users

222 System z Cryptographic Services and z/OS PKI Services

Webserver _PKISERV_CONFIG_PATH_CUSTADMIN=/etc/pkiserv/customers Envars: _PKISERV_CONFIG_PATH_CUSTOMERS=/etc/pkiserv/customers _PKISERV_CONFIG_PATH_EMPLADMIN=/etc/pkiserv/employees _PKISERV_CONFIG_PATH_EMPLOYEES=/etc/pkiserv/employees /etc/pkiserv/customers/pkiserv.tmpl

http:///CustAdmin/* Admin … CADomain=CUSTOMER http:///Customers/* Users …

/etc/pkiserv/employees/pkiserv.tmpl Admin http:///EmplAdmin/* CADomain=EMPLOYEE http:///Employees/* … Users … Independent CAs RACF

LDAP LDAP RACF PKIServ Daemon - DB PKIServ Daemon - Customers Employees VSAM VSAM

S PKISERVD.CUSTOMER,DIR=‘/etc/pkiserv/customers’ S PKISERVD.EMPLOYEE,DIR=‘/etc/pkiserv/employees’ /etc/pkiserv/customers/pkiserv.conf /etc/pkiserv/employees/pkiserv.conf Figure 7-11 z/OS V1.8 PKI Services with independent CAs

Each CA has its own administrators and users, and administrators may not be aware of other CAs. With independent mode, everything is separated, including the PKI administrators. Each CA has one certificates template file that has separate APPLICATION sections for the administrators and users. This configuration could be used for services hosting CAs for other companies, for example. Loosely coupled CAs (see Figure 7-12)

Webserver _PKISERV_CONFIG_PATH=/etc/pkiserv _PKISERV_CONFIG_PATH_CUSTOMERS=/etc/pkiserv/customers Envars: _PKISERV_CONFIG_PATH_EMPLOYEES=/etc/pkiserv/employees /etc/pkiserv/customers/pkiserv.tmpl http:///Customers/* Admin Users … CADomain=CUSTOMER Users http:///PKIServ/* /etc/pkiserv/employees/pkiserv.tmpl http:///Employees/* /etc/pkiserv/pkiserv.tmpl … CADomain=EMPLOYEE … Loosely-Coupled CAs

CADomain= RACF

LDAP LDAP RACF PKIServ Daemon - PKIServ Daemon - DB Customers VSAM VSAM Employees

S PKISERVD.CUSTOMER,DIR=‘/etc/pkiserv/customers’ S PKISERVD.EMPLOYEE,DIR=‘/etc/pkiserv/employees’ /etc/pkiserv/customers/pkiserv.conf /etc/pkiserv/employees/pkiserv.conf

Figure 7-12 z/OS V1.8 PKI Services with loosely coupled CAs

Chapter 7. z/OS PKI Services 223 Multiple CAs can have a set of administrators, and while users may not be aware of other CAs, administrators are. Loosely coupled mode is similar to multiple application domains except that each domain is a separate CA, instead of just looking like one. Each CA has one unique certificates template file. Each user’s home page URL drives down to a separate PKIServ daemon courtesy of environment variables in the Web server address

space that locate the certificates template file for the CA domain. The CAs are loosely coupled in that there is only one set PKI administrators for all the CA domains. . This configuration can be a good sample for CA hierarchy.

Another enhancement in z/OS V1.8 is support for the Simple Certificate Enrollment Protocol (SCEP). SCEP has been codesigned by Cisco and Verisign as a semi-automated HTTP-based means of acquiring certificates for Cisco routers. The SCEP message bodies contain binary PKCS#7 encodings.

Figure 7-13 represents the flow of requesting and receiving a certificate using SCEP.

HTTP message flows

Get CA Certificate Send CA Certificate Manually Check Hash Save CA Certificate Generate Key Pair z/OS Save Non-z/OS Send PKCSREQ PKI Reply PENDING SCEP Services Client Send GETCERT

Certificate Issued VSAM Polling Loop... VSAM

Reply PENDING LDAP File

Device Admin Send GETCERT Reply SUCCESS Save Certificate Manual or Automatic Conduct Business Approval Process PKI Admin Figure 7-13 Overview of SCEP - Simple Certificate Enrollment Protocol

The person assigned to administer the device (the Device Admin in Figure 7-13) issues config commands to make various things happen: Get the SCEP CA’s certificate. (Configuration requires knowledge of the CA’s URL.) Generate and save a new key pair. Encrypt and sign a new certificate request (PKCSREQ), which is encrypted under the public key of the SCEP CA. From here, either the certificate is fulfilled immediately (automatically approved), or the request is queued for pending approval by the PKI administrator. If queued, the client enters a polling loop until an event happens (for example, the request is canceled by the administrator, the request is rejected by the administrator, or a timeout occurs). If fulfilled, the client saves the certificate and uses it to conduct business.

224 System z Cryptographic Services and z/OS PKI Services 7.2.5 z/OS V1.9 enhancements

Following is a list of the PKI Services enhancements provided in z/OS V1.9: Automatic certificate renewal processing. This process uses the current sendmail mechanism to send the expiration warning message. The automatic certificate renewal process is set up respectively in: – pkiserv.conf with a definition of the time to send the warning and a specification of a file where the new certificate will be stored. – pkiserv.tmpl for the AUTORENEW definition, the setup of the autoRenew flag, and the presence of the notification e-mail address of the receiver. Support for SDBM credentials to enable the LDAP administrator RACF-style user ID to be specified in the PKI Services configuration file. The LDAP user ID is used during CRL postings to LDAP. This support enhances the usability of the PKI Services environment. E-mail notification for an administrator when requests are waiting for approval. This process requires two new keywords specifying the e-mail addresses in the configuration file: – AdminNotifyNew to notify the administrator immediately – AdminNotifyReminder to accumulate the requests and notify the administrator on a daily base Longer validity period for certificates to easily accommodate a 10-year period. Certificate life is now be up to 9999 days, which corresponds to more than 27 years. This new function is supported in the GENCERT/REQCERT, GENRENEW/REQRENEW API through the NotAfter parameter. Query on expiring certificates. In previous versions, administrators could not query about expiring certificates in order to plan in advance. z/OS V1.9 enables administrators to specify a future date as a search criteria on the Web page to perform searches on requests and certificates.

7.3 z/OS R9 PKI Services deployment

The focus of this section is to provide a straight implementation of the z/OS PKI Services solution, keeping the implementation as simple as possible, while taking advantage of the available samples and REXX code provided by z/OS.

7.3.1 IBM HTTP servers

z/OS PKI Services requires two IBM HTTP server instances to be deployed.

The first IBM HTTP server instance is used as a user and administrator interface. It requires a nonsecure port for user access and a secure port for administrator access. A second IBM HTTP server instance is required just for user revocation and renewal processes. This server is configured with a secure port, and client authentication is required. To revoke or renew its digital certificate, users have to present their digital certificates. The revocation and renewal processes initiated by the PKI administrator is performed on the first server.

Chapter 7. z/OS PKI Services 225 Example 7-1 provides a copy of our secure and nonsecure IBM HTTP server httpd.conf file for reference:

Example 7-1 Secure and nonsecure server httpd.conf file InstallPath /usr/lpp/internet ServerRoot server_root Hostname 9.12.4.18 BindSpecific off DNS-Lookup off Port 1080 imbeds on SSIOnly PidFile /u/pkiuser/PKI1/PKI1WEB/httpd-pid SysDumpName LBS AccessLog /u/pkiuser/PKI1/PKI1WEB/logs/httpd-log AgentLog /u/pkiuser/PKI1/PKI1WEB/logs/agent-log RefererLog /u/pkiuser/PKI1/PKI1WEB/logs/referer-log ErrorLog /u/pkiuser/PKI1/PKI1WEB/logs/httpd-errors CgiErrorLog /u/pkiuser/PKI1/PKI1WEB/logs/cgi-error LogFormat Common LogTime LocalTime LogToSyslog off AccessLogArchive none ErrorLogArchive none AccessLogExpire 2 ErrorLogExpire 2 AccessLogSizeLimit 0 ErrorLogSizeLimit 0 AccessLogExcludeUserAgent ICS-ProxyAgent/4.2 AccessReportDoDnsLookup off AccessReportRoot /u/pkiuser/PKI1/PKI1WEB/reports AccessReportTemplate Top50 { AccessReportDescription Top 50 most frequently requested files and most frequent visitors AccessReportTopList 50 } ReportProcessOldLogs append ReportDataArchive none ReportDataExpire 2 ReportDataSizeLimit 0 DoReporting off Enable GET Enable HEAD Enable POST Enable TRACE Enable OPTIONS Disable PUT Disable DELETE Disable CONNECT Welcome Welcome.html Welcome welcome.html Welcome index.html Welcome Frntpage.html AlwaysWelcome on DirAccess off DirReadme top DirShowIcons on

226 System z Cryptographic Services and z/OS PKI Services DirShowDate on DirShowSize on DirShowDescription on DirShowBrackets on DirShowCase on

DirShowHidden off DirShowBytes off DirShowMaxDescrLength 25 DirShowMaxLength 25 DirShowMinLength 15 UseMetaFiles off MetaDir .web MetaSuffix .meta Protection IMW_Admin { ServerId IMWEBSRV_Administration AuthType Basic PasswdFile %%SAF%% Mask WEBADM,webadm } Protect /admin-bin/* IMW_Admin WEBADM Protect /Docs/admin-bin/* IMW_Admin WEBADM Protect /reports/* IMW_Admin WEBADM Protect /Usage* IMW_Admin WEBADM

######################################################################## # Begin of z/OS PKI Services Directives ########################################################################

Protection PublicUser { ServerId PublicUser Userid PKI1SRV Mask Anyone } Protect /PKIServ/public-cgi/* PublicUser Protect /PKIServ/ssl-cgi-bin/* PublicUser Protect /PKIServ/* PublicUser

Protect /PKI1/public-cgi/* PublicUser Protect /PKI1/ssl-cgi-bin/* PublicUser Protect /PKI1/* PublicUser

Protect /Customers/public-cgi/* PublicUser Protect /Customers/ssl-cgi-bin/* PublicUser Protect /Customers/* PublicUser

Protection AuthenticatedUser { ServerId AuthenticatedUser AuthType Basic PasswdFile %%SAF%% UserID %%CLIENT%% Mask All } Protect /PKIServ/ssl-cgi-bin/auth/* AuthenticatedUser

Protect /PKI1/ssl-cgi-bin/auth/* AuthenticatedUser

Chapter 7. z/OS PKI Services 227

Protect /Customers/ssl-cgi-bin/auth/* AuthenticatedUser

Protection SurrogateUser { ServerId SurrogateUser

AuthType Basic PasswdFile %%SAF%% UserID PKI1SRV Mask All } Protect /PKIServ/ssl-cgi-bin/surrogateauth/* SurrogateUser

Protect /PKI1/ssl-cgi-bin/surrogateauth/* SurrogateUser

Protect /Customers/ssl-cgi-bin/surrogateauth/* SurrogateUser

Redirect /PKIServ/ssl-cgi/* https://9.12.4.18:1443/PKIServ/ssl-cgi-bin/* Redirect /PKIServ/ssl-cgi/auth/* https://9.12.4.18:1443/PKIServ/ssl-cgi-bin/auth/* Redirect /PKIServ/ssl-cgi/surrogateauth/* https://9.12.4.18:1443/PKIServ/ssl-cgi-bin/surrogateauth/*

Redirect /PKI1/ssl-cgi/* https://9.12.4.18:1443/PKI1/ssl-cgi-bin/* Redirect /PKI1/ssl-cgi/auth/* https://9.12.4.18:1443/PKI1/ssl-cgi-bin/auth/* Redirect /PKI1/ssl-cgi/surrogateauth/* https://9.12.4.18:1443/PKI1/ssl-cgi-bin/surrogateauth/*

Redirect /Customers/ssl-cgi/* https://9.12.4.18:1443/Customers/ssl-cgi-bin/* Redirect /Customers/ssl-cgi/auth/* https://9.12.4.18:1443/Customers/ssl-cgi-bin/auth/* Redirect /Customers/ssl-cgi/surrogateauth/* https://9.12.4.18:1443/Customers/ssl-cgi-bin/surrogateauth/*

Redirect /PKIServ/clientauth-cgi/* https://9.12.4.18:2443/PKIServ/clientauth-cgi/*

Redirect /PKI1/clientauth-cgi/* https://9.12.4.18:2443/PKI1/clientauth-cgi/*

Redirect /Customers/clientauth-cgi/* https://9.12.4.18:2443/Customers/clientauth-cgi/*

Exec /PKIServ/public-cgi/* /usr/lpp/pkiserv/PKIServ/public-cgi/* Exec /PKIServ/ssl-cgi-bin/* /usr/lpp/pkiserv/PKIServ/ssl-cgi-bin/* Pass /PKIServ/cacerts/* /var/pkiserv/*

Exec /PKI1/public-cgi/* /usr/lpp/pkiserv/PKIServ/public-cgi/* Exec /PKI1/ssl-cgi-bin/* /usr/lpp/pkiserv/PKIServ/ssl-cgi-bin/* Pass /PKI1/cacerts/* /var/pkiserv/*

Exec /Customers/public-cgi/* /usr/lpp/pkiserv/PKIServ/public-cgi/* Exec /Customers/ssl-cgi-bin/* /usr/lpp/pkiserv/PKIServ/ssl-cgi-bin/* Pass /Customers/cacerts/* /var/pkiserv/*

######################################################################## # End of z/OS PKI Services Directives ######################################################################## service /cgi-bin/htimage* INTERNAL:HTImage* service /cgi-bin/imagemap* INTERNAL:HTImage*

228 System z Cryptographic Services and z/OS PKI Services service /Usage* INTERNAL:UsageFn service /admin-bin/trace* INTERNAL:TraceFn Pass /admin-bin/webexec/* /usr/lpp/internet/server_root/admin-bin/webexec/* Exec /cgi-bin/* /usr/lpp/internet/server_root/cgi-bin/* Exec /admin-bin/* /usr/lpp/internet/server_root/admin-bin/*

Exec /Docs/admin-bin/* /usr/lpp/internet/server_root/admin-bin/* Pass /icons/* /usr/lpp/internet/server_root/icons/* Pass /Admin/*.jpg /usr/lpp/internet/server_root/Admin/*.jpg Pass /Admin/*.gif /usr/lpp/internet/server_root/Admin/*.gif Pass /Admin/*.html /usr/lpp/internet/server_root/Admin/*.html Pass /Docs/* /usr/lpp/internet/server_root/Docs/* Pass /reports/javelin/* /usr/lpp/internet/server_root/pub/reports/javelin/* Pass /reports/java/* /usr/lpp/internet/server_root/pub/reports/java/* Pass /reports/* /usr/lpp/internet/server_root/pub/reports/* Pass /img-bin/* /usr/lpp/internet/server_root/img-bin/* Pass /ServletExpress/* /usr/lpp/WebSphere/AppServer/web/* Pass /docs/* /u/pkiuser/PKI1/PKI1WEB/docs/* Pass /* /usr/lpp/internet/server_root/pub/*

MaxActiveThreads 100 MaxPersistRequest 5 ServerPriority -10 InputTimeout 30 secs OutputTimeout 2 minutes ScriptTimeout 2 minutes PersistTimeout 5 secs sslmode on sslport 1443 normalmode on keyfile WEB1RING SAF UserId %%SERVER%% SSLClientAuth off SSLX500CARoots local_only UseACLs protectonly SSLV2Timeout 100 SSLV3Timeout 1000 SSLCipherSpec 27 SSLCipherSpec 21 SSLCipherSpec 23 SSLCipherSpec 26 SSLCipherSpec 22 SSLCipherSpec 24 SSLCipherSpec 3A SSLCipherSpec 35 SSLCipherSpec 34 SSLCipherSpec 39 SSLCipherSpec 33 SSLCipherSpec 36 MaxContentLengthBuffer 100 K CacheDefaultExpiry http:* 0 day CacheDefaultExpiry ftp:* 1 day CacheDefaultExpiry gopher:* 2 days CacheExpiryCheck on CacheNoConnect off CacheTimeMargin 2 minutes

Chapter 7. z/OS PKI Services 229 CacheLastModifiedFactor 0.14 CacheLimit_2 4000 K CacheSize 5 M Gc on GcDailyGc 03:00

GcMemUsage 500 LiveLocalCache off CacheLocalMaxFiles 200 CacheLocalMaxBytes 2 M CacheLocalFile /usr/lpp/internet/server_root/pub/Frntpage.html CacheLocalFile /usr/lpp/internet/server_root/Admin/lgmast.gif CacheLocalFile /usr/lpp/internet/server_root/Admin/lgsplash.gif SMF None SMFRecordingInterval 00:15 SNMP off SNMPCommunity public WebMasterEMail webmaster AddIcon /icons/html.gif HTML text/html AddIcon /icons/html.gif HTML text/x-ssi-html AddIcon /icons/text.gif TXT text/* AddIcon /icons/image.gif IMG image/* AddIcon /icons/sound.gif AU audio/* AddIcon /icons/movie.gif MOV video/* AddIcon /icons/tar.gif TAR multipart/*tar AddIcon /icons/compress.gif CMP x-compress x-gzip AddIcon /icons/telnet.gif TEL application/telnet AddIcon /icons/index.gif SRCH application/search AddIcon /icons/ls123.gif 123 application/x-123 AddIcon /icons/lsflw.gif FLW application/x-freelance AddIcon /icons/acrobat.gif PDF application/pdf AddIcon /icons/binary.gif BIN binary AddDirIcon /icons/dir.gif DIR AddBlankIcon /icons/blank.gif AddParentIcon /icons/back.gif UP AddUnknownIcon /icons/unknown.gif ??? SuffixCaseSense off AddType .arm application/x-x509-ca-cert ebcdic 1.0 # Browser Certificate AddType .cer application/x-x509-user-cert ebcdic 0.5 # Browser Certificate AddType .crt application/x-x509-ca-cert ebcdic 1.0 # Browser Certificate AddType .der application/x-x509-ca-cert binary 1.0 # CA Certificate AddType .mime www/mime binary 1.0 # Internal -- MIME is AddType .bin application/octet-stream binary 1.0 # Uninterpreted binary AddType .class application/octet-stream binary 1.0 # Java applet or application AddType .pdf application/pdf binary 1.0 AddType .ai application/postscript ebcdic 0.5 # Adobe Illustrator AddType .PS application/postscript ebcdic 0.8 # PostScript AddType .eps application/postscript ebcdic 0.8 AddType .ps application/postscript ebcdic 0.8 AddType .rtf application/x-rtf ebcdic 1.0 # RTF AddType .csh application/x-csh ebcdic 0.5 # C-shell script AddType .latex application/x-latex ebcdic 1.0 # LaTeX source AddType .cdf application/x-cdf ebcdic 1.0 # Channel Definition Format AddType .sh application/x-sh ebcdic 0.5 # Shell-script AddType .tcl application/x-tcl ebcdic 0.5 # TCL-script AddType .tex application/x-tex ebcdic 1.0 # TeX source

230 System z Cryptographic Services and z/OS PKI Services AddType .t application/x-troff ebcdic 0.5 # Troff AddType .roff application/x-troff ebcdic 0.5 AddType .tr application/x-troff ebcdic 0.5 AddType .man application/x-troff-man ebcdic 0.5 # Troff with man macros AddType .me application/x-troff-me ebcdic 0.5 # Troff with me macros

AddType .ms application/x-troff-ms ebcdic 0.5 # Troff with ms macros AddType .gtar application/x-gtar binary 1.0 # Gnu tar AddType .shar application/x-shar ebcdic 1.0 # Shell archive AddType .wrl x-world/x-vrml binary 1.0 # VRML AddType .snd audio/basic binary 1.0 # Audio AddType .au audio/basic binary 1.0 AddType .aiff audio/x-aiff binary 1.0 AddType .aifc audio/x-aiff binary 1.0 AddType .aif audio/x-aiff binary 1.0 AddType .wav audio/x-wav binary 1.0 # Windows+ WAVE format AddType .bmp image/bmp binary 1.0 # OS/2 bitmap format AddType .gif image/gif binary 1.0 # GIF AddType .ief image/ief binary 1.0 # Image Exchange fmt AddType .jpg image/jpeg binary 1.0 # JPEG AddType .JPG image/jpeg binary 1.0 AddType .JPE image/jpeg binary 1.0 AddType .jpe image/jpeg binary 1.0 AddType .JPEG image/jpeg binary 1.0 AddType .jpeg image/jpeg binary 1.0 AddType .tif image/tiff binary 1.0 # TIFF AddType .tiff image/tiff binary 1.0 AddType .ras image/cmu-raster binary 1.0 AddType .pnm image/x-portable-anymap binary 1.0 # PBM Anymap format AddType .pbm image/x-portable-bitmap binary 1.0 # PBM Bitmap format AddType .pgm image/x-portable-graymap binary 1.0 # PBM Graymap format AddType .ppm image/x-portable-pixmap binary 1.0 # PBM Pixmap format AddType .rgb image/x-rgb binary 1.0 AddType .xbm image/x-xbitmap ebcdic 1.0 # X bitmap AddType .xpm image/x-xpixmap binary 1.0 # X pixmap format AddType .xwd image/x-xwindowdump binary 1.0 # X window dump (xwd) AddType .html text/html ebcdic 1.0 # HTML AddType .htm text/html ebcdic 1.0 # HTML on PCs AddType .htmls text/x-ssi-html ebcdic 1.0 # Server-side includes AddType .shtml text/x-ssi-html ebcdic 1.0 # Server-side includes AddType .c text/plain ebcdic 0.5 # C source AddType .h text/plain ebcdic 0.5 # C headers AddType .C text/plain ebcdic 0.5 # C++ source AddType .cc text/plain ebcdic 0.5 # C++ source AddType .hh text/plain ebcdic 0.5 # C++ headers AddType .java text/plain ebcdic 0.5 # Java source AddType .m text/plain ebcdic 0.5 # Objective-C source AddType .f90 text/plain ebcdic 0.5 # Fortran 90 source AddType .txt text/plain ebcdic 0.5 # Plain text AddType .css text/css 8bit 1.0 # W3C Cascading Style Sheets AddType .rtx text/richtext ebcdic 1.0 # MIME Richtext format AddType .tsv text/tab-separated-values ebcdic 1.0 # Tab-separated values AddType .etx text/x-setext ebcdic 0.9 # Struct Enchanced Txt AddType .MPG video/mpeg binary 1.0 # MPEG AddType .mpg video/mpeg binary 1.0 AddType .MPE video/mpeg binary 1.0

Chapter 7. z/OS PKI Services 231 AddType .mpe video/mpeg binary 1.0 AddType .MPEG video/mpeg binary 1.0 AddType .mpeg video/mpeg binary 1.0 AddType .qt video/quicktime binary 1.0 # QuickTime AddType .mov video/quicktime binary 1.0

AddType .avi video/x-msvideo binary 1.0 # MS Video for Windows AddType .movie video/x-sgi-movie binary 1.0 # SGI moviepalyer AddType .zip multipart/x-zip binary 1.0 # PKZIP AddType .Z application/x-compress gzip 1.0 # PKZIP AddType .gz application/x-compress gzip 1.0 # PKZIP AddType .tar multipart/x-tar binary 1.0 # 4.3BSD tar AddType .ustar multipart/x-ustar binary 1.0 # POSIX tar AddType *.* www/unknown binary 0.2 # Try to guess AddType * www/unknown binary 0.2 # Try to guess AddType .cxx text/plain ebcdic 0.5 # C++ AddType .for text/plain ebcdic 0.5 # Fortran AddType .mar text/plain ebcdic 0.5 # MACRO AddType .log text/plain ebcdic 0.5 # logfiles AddType .com text/plain ebcdic 0.5 # scripts AddType .sdml text/plain ebcdic 0.5 # SDML AddType .list text/plain ebcdic 0.5 # listfiles AddType .lst text/plain ebcdic 0.5 # listfiles AddType .def text/plain ebcdic 0.5 # definition files AddType .conf text/plain ebcdic 0.5 # definition files AddType . text/plain ebcdic 0.5 # files with no extension AddType .JP932 text/x-DBCS binary 1.0 IBM-932 # Japanese DBCS AddType .JPeuc text/x-DBCS binary 1.0 IBMeucJP # Japanese DBCS AddEncoding .Z gzip 1.0 # Compressed data AddEncoding .gz gzip 1.0 # Compressed data AddEncoding .ascii 8bit 1.0 # stored in ASCII AddEncoding .asc8 8bit 1.0 # stored in ASCII AddEncoding .asc7 7bit 1.0 # stored in ASCII AddEncoding .ebcdic ebcdic 1.0 # stored in EBCDIC

Example 7-2 shows a sample of our secure only IBM HTTP server httpd.conf file for reference:

Example 7-2 Secure and nonsecure server httpd.conf file with client authentication set up InstallPath /usr/lpp/internet ServerRoot server_root Hostname 9.12.4.18 BindSpecific off DNS-Lookup off imbeds on SSIOnly PidFile /u/pkiuser/PKI1/PKI1WEBS/httpd-pid SysDumpName LBS AccessLog /u/pkiuser/PKI1/PKI1WEBS/logs/httpd-log AgentLog /u/pkiuser/PKI1/PKI1WEBS/logs/agent-log

RefererLog /u/pkiuser/PKI1/PKI1WEBS/logs/referer-log ErrorLog /u/pkiuser/PKI1/PKI1WEBS/logs/httpd-errors CgiErrorLog /u/pkiuser/PKI1/PKI1WEBS/logs/cgi-error LogFormat Common LogTime LocalTime LogToSyslog off AccessLogArchive none

232 System z Cryptographic Services and z/OS PKI Services ErrorLogArchive none AccessLogExpire 2 ErrorLogExpire 2 AccessLogSizeLimit 0 ErrorLogSizeLimit 0

AccessLogExcludeUserAgent ICS-ProxyAgent/4.2 AccessReportDoDnsLookup off AccessReportRoot /u/pkiuser/PKI1/PKI1WEBS/reports AccessReportTemplate Top50 { AccessReportDescription Top 50 most frequently requested files and most frequent visitors AccessReportTopList 50 } ReportProcessOldLogs append ReportDataArchive none ReportDataExpire 2 ReportDataSizeLimit 0 DoReporting off Enable GET Enable HEAD Enable POST Enable TRACE Enable OPTIONS Disable PUT Disable DELETE Disable CONNECT Welcome Welcome.html Welcome welcome.html Welcome index.html Welcome Frntpage.html AlwaysWelcome on DirAccess off DirReadme top DirShowIcons on DirShowDate on DirShowSize on DirShowDescription on DirShowBrackets on DirShowCase on DirShowHidden off DirShowBytes off DirShowMaxDescrLength 25 DirShowMaxLength 25 DirShowMinLength 15 UseMetaFiles off MetaDir .web MetaSuffix .meta Protection IMW_Admin { ServerId IMWEBSRV_Administration AuthType Basic PasswdFile %%SAF%% Mask WEBADM,webadm } Protect /admin-bin/* IMW_Admin WEBADM Protect /Docs/admin-bin/* IMW_Admin WEBADM Protect /reports/* IMW_Admin WEBADM

Chapter 7. z/OS PKI Services 233 Protect /Usage* IMW_Admin WEBADM

######################################################################## # Begin of z/OS PKI Services Directives ########################################################################

Protection RenewRevokeUser { ServerId RenewRevokeUser AuthType Basic UserID PKI1SRV SSL_CLIENTAUTH Client Mask Anyone }

Protect /PKIServ/clientauth-cgi/* RenewRevokeUser

Protect /PKI1/clientauth-cgi/* RenewRevokeUser

Protect /Customers/clientauth-cgi/* RenewRevokeUser

Protection AuthenticatedAdmin { ServerId AuthenticatedAdmin AuthType Basic UserID %%CERTIF%% SSL_CLIENTAUTH Client Mask Anyone }

Protect /PKIServ/clientauth-cgi/auth/* AuthenticatedAdmin

Protect /PKI1/clientauth-cgi/auth/* AuthenticatedAdmin

Protect /Customers/clientauth-cgi/auth/* AuthenticatedAdmin

Redirect /PKIServ/public-cgi/* http://9.12.4.18:1080/PKIServ/public-cgi/* Redirect /PKIServ/ssl-cgi/* https://9.12.4.18:1443/PKIServ/ssl-cgi-bin/*

Redirect /PKI1/public-cgi/* http://9.12.4.18:1080/PKI1/public-cgi/* Redirect /PKI1/ssl-cgi/* https://9.12.4.18:1443/PKI1/ssl-cgi-bin/*

Redirect /Customers/public-cgi/* http://9.12.4.18:1080/Customers/public-cgi/* Redirect /Customers/ssl-cgi/* https://9.12.4.18:1443/Customers/ssl-cgi-bin/*

Exec /PKIServ/clientauth-cgi/* /usr/lpp/pkiserv/PKIServ/clientauth-cgi-bin/*

Exec /PKI1/clientauth-cgi/* /usr/lpp/pkiserv/PKIServ/clientauth-cgi-bin/*

Exec /Customers/clientauth-cgi/* /usr/lpp/pkiserv/PKIServ/clientauth-cgi-bin/*

234 System z Cryptographic Services and z/OS PKI Services service /Usage* INTERNAL:UsageFn service /admin-bin/trace* INTERNAL:TraceFn Pass /admin-bin/webexec/* /usr/lpp/internet/server_root/admin-bin/webexec/* Exec /cgi-bin/* /usr/lpp/internet/server_root/cgi-bin/* Exec /admin-bin/* /usr/lpp/internet/server_root/admin-bin/*

Exec /Docs/admin-bin/* /usr/lpp/internet/server_root/admin-bin/* Pass /icons/* /usr/lpp/internet/server_root/icons/* Pass /Admin/*.jpg /usr/lpp/internet/server_root/Admin/*.jpg Pass /Admin/*.gif /usr/lpp/internet/server_root/Admin/*.gif Pass /Admin/*.html /usr/lpp/internet/server_root/Admin/*.html Pass /Docs/* /usr/lpp/internet/server_root/Docs/* Pass /reports/javelin/* /usr/lpp/internet/server_root/pub/reports/javelin/* Pass /reports/java/* /usr/lpp/internet/server_root/pub/reports/java/* Pass /reports/* /usr/lpp/internet/server_root/pub/reports/* Pass /img-bin/* /usr/lpp/internet/server_root/img-bin/* Pass /ServletExpress/* /usr/lpp/WebSphere/AppServer/web/* Pass /docs/* /u/pkiuser/PKI1/PKI1WEBS/docs/* Pass /* /usr/lpp/internet/server_root/pub/*

MaxActiveThreads 100 MaxPersistRequest 5 ServerPriority -10 InputTimeout 30 secs OutputTimeout 2 minutes ScriptTimeout 2 minutes PersistTimeout 5 secs sslmode on sslport 2443 normalmode off keyfile WEB1RING SAF UserId %%SERVER%% SSLClientAuth strong SSLX500CARoots local_and_x500 SSLX500Host 9.12.4.18 SSLX500Port 1389 SSLX500UserID cn=LDAP Administrator SSLX500Password secret UseACLs protectonly SSLV2Timeout 100 SSLV3Timeout 1000 SSLCipherSpec 27 SSLCipherSpec 21 SSLCipherSpec 23 SSLCipherSpec 26 SSLCipherSpec 22 SSLCipherSpec 24 SSLCipherSpec 3A SSLCipherSpec 35 SSLCipherSpec 34 SSLCipherSpec 39 SSLCipherSpec 33 SSLCipherSpec 36 MaxContentLengthBuffer 100 K CacheDefaultExpiry http:* 0 day CacheDefaultExpiry ftp:* 1 day

Chapter 7. z/OS PKI Services 235 CacheDefaultExpiry gopher:* 2 days CacheExpiryCheck on CacheNoConnect off CacheTimeMargin 2 minutes CacheLastModifiedFactor 0.14

CacheLimit_2 4000 K CacheSize 5 M Gc on GcDailyGc 03:00 GcMemUsage 500 LiveLocalCache off CacheLocalMaxFiles 200 CacheLocalMaxBytes 2 M CacheLocalFile /usr/lpp/internet/server_root/pub/Frntpage.html CacheLocalFile /usr/lpp/internet/server_root/Admin/lgmast.gif CacheLocalFile /usr/lpp/internet/server_root/Admin/lgsplash.gif SMF None SMFRecordingInterval 00:15 SNMP off SNMPCommunity public WebMasterEMail webmaster AddIcon /icons/html.gif HTML text/html AddIcon /icons/html.gif HTML text/x-ssi-html AddIcon /icons/text.gif TXT text/* AddIcon /icons/image.gif IMG image/* AddIcon /icons/sound.gif AU audio/* AddIcon /icons/movie.gif MOV video/* AddIcon /icons/tar.gif TAR multipart/*tar AddIcon /icons/compress.gif CMP x-compress x-gzip AddIcon /icons/telnet.gif TEL application/telnet AddIcon /icons/index.gif SRCH application/search AddIcon /icons/ls123.gif 123 application/x-123 AddIcon /icons/lsflw.gif FLW application/x-freelance AddIcon /icons/acrobat.gif PDF application/pdf AddIcon /icons/binary.gif BIN binary AddDirIcon /icons/dir.gif DIR AddBlankIcon /icons/blank.gif AddParentIcon /icons/back.gif UP AddUnknownIcon /icons/unknown.gif ??? SuffixCaseSense off AddType .arm application/x-x509-ca-cert ebcdic 1.0 # Browser Certificate AddType .cer application/x-x509-user-cert ebcdic 0.5 # Browser Certificate AddType .crt application/x-x509-ca-cert ebcdic 1.0 # Browser Certificate AddType .der application/x-x509-ca-cert binary 1.0 # CA Certificate AddType .mime www/mime binary 1.0 # Internal -- MIME is AddType .bin application/octet-stream binary 1.0 # Uninterpreted binary AddType .class application/octet-stream binary 1.0 # Java applet or application AddType .pdf application/pdf binary 1.0 AddType .ai application/postscript ebcdic 0.5 # Adobe Illustrator AddType .PS application/postscript ebcdic 0.8 # PostScript AddType .eps application/postscript ebcdic 0.8 AddType .ps application/postscript ebcdic 0.8 AddType .rtf application/x-rtf ebcdic 1.0 # RTF AddType .csh application/x-csh ebcdic 0.5 # C-shell script AddType .latex application/x-latex ebcdic 1.0 # LaTeX source

236 System z Cryptographic Services and z/OS PKI Services AddType .cdf application/x-cdf ebcdic 1.0 # Channel Definition Format AddType .sh application/x-sh ebcdic 0.5 # Shell-script AddType .tcl application/x-tcl ebcdic 0.5 # TCL-script AddType .tex application/x-tex ebcdic 1.0 # TeX source AddType .t application/x-troff ebcdic 0.5 # Troff

AddType .roff application/x-troff ebcdic 0.5 AddType .tr application/x-troff ebcdic 0.5 AddType .man application/x-troff-man ebcdic 0.5 # Troff with man macros AddType .me application/x-troff-me ebcdic 0.5 # Troff with me macros AddType .ms application/x-troff-ms ebcdic 0.5 # Troff with ms macros AddType .gtar application/x-gtar binary 1.0 # Gnu tar AddType .shar application/x-shar ebcdic 1.0 # Shell archive AddType .wrl x-world/x-vrml binary 1.0 # VRML AddType .snd audio/basic binary 1.0 # Audio AddType .au audio/basic binary 1.0 AddType .aiff audio/x-aiff binary 1.0 AddType .aifc audio/x-aiff binary 1.0 AddType .aif audio/x-aiff binary 1.0 AddType .wav audio/x-wav binary 1.0 # Windows+ WAVE format AddType .bmp image/bmp binary 1.0 # OS/2 bitmap format AddType .gif image/gif binary 1.0 # GIF AddType .ief image/ief binary 1.0 # Image Exchange fmt AddType .jpg image/jpeg binary 1.0 # JPEG AddType .JPG image/jpeg binary 1.0 AddType .JPE image/jpeg binary 1.0 AddType .jpe image/jpeg binary 1.0 AddType .JPEG image/jpeg binary 1.0 AddType .jpeg image/jpeg binary 1.0 AddType .tif image/tiff binary 1.0 # TIFF AddType .tiff image/tiff binary 1.0 AddType .ras image/cmu-raster binary 1.0 AddType .pnm image/x-portable-anymap binary 1.0 # PBM Anymap format AddType .pbm image/x-portable-bitmap binary 1.0 # PBM Bitmap format AddType .pgm image/x-portable-graymap binary 1.0 # PBM Graymap format AddType .ppm image/x-portable-pixmap binary 1.0 # PBM Pixmap format AddType .rgb image/x-rgb binary 1.0 AddType .xbm image/x-xbitmap ebcdic 1.0 # X bitmap AddType .xpm image/x-xpixmap binary 1.0 # X pixmap format AddType .xwd image/x-xwindowdump binary 1.0 # X window dump (xwd) AddType .html text/html ebcdic 1.0 # HTML AddType .htm text/html ebcdic 1.0 # HTML on PCs AddType .htmls text/x-ssi-html ebcdic 1.0 # Server-side includes AddType .shtml text/x-ssi-html ebcdic 1.0 # Server-side includes AddType .c text/plain ebcdic 0.5 # C source AddType .h text/plain ebcdic 0.5 # C headers AddType .C text/plain ebcdic 0.5 # C++ source AddType .cc text/plain ebcdic 0.5 # C++ source AddType .hh text/plain ebcdic 0.5 # C++ headers AddType .java text/plain ebcdic 0.5 # Java source AddType .m text/plain ebcdic 0.5 # Objective-C source AddType .f90 text/plain ebcdic 0.5 # Fortran 90 source AddType .txt text/plain ebcdic 0.5 # Plain text AddType .css text/css 8bit 1.0 # W3C Cascading Style Sheets AddType .rtx text/richtext ebcdic 1.0 # MIME Richtext format AddType .tsv text/tab-separated-values ebcdic 1.0 # Tab-separated values

Chapter 7. z/OS PKI Services 237 AddType .etx text/x-setext ebcdic 0.9 # Struct Enchanced Txt AddType .MPG video/mpeg binary 1.0 # MPEG AddType .mpg video/mpeg binary 1.0 AddType .MPE video/mpeg binary 1.0 AddType .mpe video/mpeg binary 1.0

AddType .MPEG video/mpeg binary 1.0 AddType .mpeg video/mpeg binary 1.0 AddType .qt video/quicktime binary 1.0 # QuickTime AddType .mov video/quicktime binary 1.0 AddType .avi video/x-msvideo binary 1.0 # MS Video for Windows AddType .movie video/x-sgi-movie binary 1.0 # SGI moviepalyer AddType .zip multipart/x-zip binary 1.0 # PKZIP AddType .Z application/x-compress gzip 1.0 # PKZIP AddType .gz application/x-compress gzip 1.0 # PKZIP AddType .tar multipart/x-tar binary 1.0 # 4.3BSD tar AddType .ustar multipart/x-ustar binary 1.0 # POSIX tar AddType *.* www/unknown binary 0.2 # Try to guess AddType * www/unknown binary 0.2 # Try to guess AddType .cxx text/plain ebcdic 0.5 # C++ AddType .for text/plain ebcdic 0.5 # Fortran AddType .mar text/plain ebcdic 0.5 # MACRO AddType .log text/plain ebcdic 0.5 # logfiles AddType .com text/plain ebcdic 0.5 # scripts AddType .sdml text/plain ebcdic 0.5 # SDML AddType .list text/plain ebcdic 0.5 # listfiles AddType .lst text/plain ebcdic 0.5 # listfiles AddType .def text/plain ebcdic 0.5 # definition files AddType .conf text/plain ebcdic 0.5 # definition files AddType . text/plain ebcdic 0.5 # files with no extension AddType .JP932 text/x-DBCS binary 1.0 IBM-932 # Japanese DBCS AddType .JPeuc text/x-DBCS binary 1.0 IBMeucJP # Japanese DBCS AddEncoding .Z gzip 1.0 # Compressed data AddEncoding .gz gzip 1.0 # Compressed data AddEncoding .ascii 8bit 1.0 # stored in ASCII AddEncoding .asc8 8bit 1.0 # stored in ASCII AddEncoding .asc7 7bit 1.0 # stored in ASCII AddEncoding .ebcdic ebcdic 1.0 # stored in EBCDIC

To run both IBM HTTP servers, a procedure is required. Example 7-3 is a sample of the procedure used in our system. In this sample, the -vv option is used. In your installation, evaluate whether you really need the -vv option because it might generate a hugh job log file.

Example 7-3 IBM HTTP Server start procedure //PKI1WEB PROC P1='-vv -B', //* PKI1WEB PROC P1='-B', // P2='-r /u/pkiuser/PKI1/PKI1WEB/httpd.conf', // P3='', // LEPARM='ENVAR("_CEE_ENVFILE=/u/pkiuser/PKI1/httpd.envvars")'

//**************************************************************** //* //* z/OS PKI Services //* //* PKI1WEB HTTP Server //* SECURE / NON-SECURE PORTS //*

238 System z Cryptographic Services and z/OS PKI Services //* //**************************************************************** //PKI1WEB EXEC PGM=IMWHTTPD,REGION=0K,TIME=NOLIMIT, // PARM=('&LEPARM/&P1 &P2 &P3') //*

//SYSIN DD DUMMY //OUTDSC DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSERR DD SYSOUT=* //STDOUT DD SYSOUT=* //CEEDUMP DD SYSOUT=*

Some RACF commands must be issued to define the HTTP servers started tasks user IDs. These commands are not performed by IKYSETUP REXX, described in 7.3.2, “IKYSETUP REXX” on page 240. The RACF commands were issued in batch mode. Example 7-4 provides a sample JCL to run along with the commands.

Example 7-4 RACF command for setting up HTTP servers //RACFWEB JOB MSGCLASS=A,CLASS=A,MSGLEVEL=(1,1),NOTIFY=&SYSUID //STEP1 EXEC PGM=IKJEFT01 //SYSTSPRT DD SYSOUT=* //ISFOUT DD SYSOUT=* //ISFIN DD DUMMY //SYSTSIN DD *

/* ADDING PKI1WEB (non Secure http) USER TO RACF */

ADDUSER PKI1WEB name('PKI1 Web Daemon') dfltgrp(SYS1) nopassword + omvs(uid(63103)home(/usr/lpp/internet)program(/bin/sh))

/* ADDING PKI1WEBS (Secure http) USER TO RACF */

ADDUSER PKI1WEBS name('PKI1 Webs Daemon') dfltgrp(SYS1) nopassword + omvs(uid(63104)home(/usr/lpp/internet)program(/bin/sh))

/* CREATING PKI1WEB STARTED TASK */

RDEFINE STARTED PKI1WEB.* STDATA(USER(PKI1WEB))

/* CREATING PKI1WEBS STARTED TASK */

RDEFINE STARTED PKI1WEBS.* STDATA(USER(PKI1WEB))

/* ADDING PKI1ADM USER TO RACF */

ADDUSER PKI1ADM name('PKI1 Adminitrator') dfltgrp(SYS1) + omvs(uid(63105)home(/u)program(/bin/sh))

/* ADDING WEBADM USER TO RACF */

ADDUSER WEBADM name('WEB Adminitrator') dfltgrp(SYS1) + omvs(uid(63106)home(/u)program(/bin/sh))

//STEP1 EXEC PGM=IKJEFT01 //SYSTSPRT DD SYSOUT=*

Chapter 7. z/OS PKI Services 239 //ISFOUT DD SYSOUT=* //ISFIN DD DUMMY //SYSTSIN DD * PERMIT BPX.SERVER CLASS(FACILITY) ID(PKI1WEB) ACCESS(READ) PERMIT BPX.DAEMON CLASS(FACILITY) ID(PKI1WEB) ACCESS(READ)

PERMIT BPX.SERVER CLASS(FACILITY) ID(PKI1WEBS) ACCESS(UPDATE) PERMIT BPX.DAEMON CLASS(FACILITY) ID(PKI1WEBS) ACCESS(READ) PERMIT BPX.SERVER CLASS(FACILITY) ID(PKI1SRV) ACCESS(UPDATE) PERMIT BPX.DAEMON CLASS(FACILITY) ID(PKI1SRV) ACCESS(READ)

7.3.2 IKYSETUP REXX

IKYSETUP is a REXX script that performs the RACF administration tasks required for setting up PKI Services. It is provided in the IKYSETUP member in SYS1.SAMPLIB.

Remember to copy the sample member in your own data set before making any updates. Edit the configurable section of the REXX and assign values to the variables. Example 7-5 shows the configurable section with the values provided in our system:

Example 7-5 IKYSETUP configurable section /*------*/ /* 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=,O=, */ /* C= */ /* */ /* 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 */

240 System z Cryptographic Services and z/OS PKI Services /* 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 = "PKI1SRV" /* @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 "ITSO PKI Services CA1") /* @L4A*/ ca_dn= "O('ITSO PKI1SRV')", "C('US')" /* @L4C*/ ca_label = STRIP(ca_domain "PKI1 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 "PKI1 RA") /*Label for RA Certificate @01C*/ if (ra_label = "") then /* If no RA Label ... @L4A*/ ra_dn="" /*@L4A*/ else /*@L4A*/ ra_dn=, /*@L4A*/ "CN('ITSO PKI Services RA1')", 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="". */ /****************************************************************/

Chapter 7. z/OS PKI Services 241 web_dn=, "CN('wtscnet.itso.ibm.com')", "O('ITSO')", "L('Poughkeepsie')", "SP('New York')",

"C('US')"

/****************************************************************/ /* 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 add the CA's certificate to the webserver's */ /* keyfile manually */ /****************************************************************/ web_ring = "WEB1RING" /* SAF keyring for web server */

/****************************************************************/ /* You must provide UID and GID values for the user IDs and */ /* groups being created below */ /****************************************************************/ daemon="PKI1SRV" /* user ID for PKI daemon */ daemon_uid="63101" /* uid for PKI daemon */ surrog="PKI1SUR" /* user ID for the surrogate */ surrog_uid="63102" /* 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="PKI1GRP" /* PKI Services Admin group name */ pki_gid="63100" /* PKI Services Admin group id */ pkigroup_mem.0=2 /* Number of pkigroup members to connect */ pkigroup_mem.1="PKI1ADM" pkigroup_mem.2="PKIUSER"

/*------*/ /* Part 2 - Questions you must answer */ /*------*/

/****************************************************************/ /* Question 1 - Restrict the surrogate user ID? */

242 System z Cryptographic Services and z/OS PKI Services /* */ /* 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=1

/****************************************************************/ /* Question 2 - Use ICSF? */ /* */ /* There are four possible choices for generation and */ /* 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 key using software then store the key in */ /* ICSF. (Option 1) */ /* */ /* - Generate the key through ICSF using the PCI cryptographic */ /* coprocessor (PCICC) then store the key in ICSF. (Option 2) */ /* */ /* - Generate the DSA key using software and retain it as a */ /* software key. This key cannot be saved in ICSF. (Option 3) */ /* */ /* Notes: */ /* */ /* - For options 1 and 2, ICSF must be configured for PKA */ /* support and running. Additionally, for option 2, a PCICC */ /* must be present and operational. */ /* */ /* - Option 2 is the only way to generate a private key larger */ /* than 1024 bits. @01C */ /* */ /* - If option 2 is selected, the certificate and private key */ /* will not be backed up by this exec. */ /* */ /* - 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, 1, 2 or 3. */ /****************************************************************/ key_type=0

/****************************************************************/ /* If you set key_type=1 or key_type=2 above, you will need to */ /* restrict access to the CA's private key. Unless you indicate */ /* otherwise, this exec will activate the CSFKEYS class, */

Chapter 7. z/OS PKI Services 243 /* create a profile in the CSFKEYS class to protect the CA's */ /* private key, and permit the PKI Services daemon to use it. */ /* */ /* If you are already using ICSF, then you may have profiles in */ /* the CSFSERV class protecting ICSF services. The PKI Services */

/* daemon would need access to the profile that covers the */ /* CSFDSV and CSFDSG services. Also, the PKI Services surrogate */ /* ID would need access to the profile that covers the */ /* CSFENC and CSFDEC services. You may also have a RACF group */ /* for authorized ICSF users. Both of these user IDs */ /* would need to be added to this group. */ /* */ /* 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.*' csfserv_profile='CSF*' csfusers_grp=''

/****************************************************************/ /* Question 3 - 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 above. */ /* **************************************************************/ key_backup=1

/****************************************************************/ /* Question 4 - 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 */

244 System z Cryptographic Services and z/OS PKI Services /* 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=1 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.SEZATCP'" /* @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"

/*------*/ /* 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 qulified @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='PKI1SRV' /* HLQ for VSAM data sets. Same as daemon ID */ web_label = "PKI1WEB SSL Cert" /* Label for web server cert */ ca_expires ="2020/01/01" /* date the CA certificate for

Chapter 7. z/OS PKI Services 245 certificate authority should expire */

web_expires ="2020/01/01" /* date the certificate for web server SSL should

expire */

if (ca_domain = "") then /* If no CA Domain... @L4A*/ ca_ring="PKI1ring" /* keyring name for PKI Srvs */ else /* Else use CA Domain @L4A*/ ca_ring="PKI1ring."||ca_domain /* CA Domain qualified @L4A*/

/****************************************************************/ /* You can select the size (in bits) of your CA's private key. */ /* The range is 512-2048. The default is 1024. Note, if you */ /* wish the key size to be greater than 1024, you must select */ /* key_type=2 above. @01C*/ /****************************************************************/ ca_keysize="1024"

/****************************************************************/ /* 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 = "'PKI1SRV.KEY.BACKUP.P12BIN'" /* @L5C*/ else /* Else use CA Domain @L4A*/ backup_dsn = "'PKI1SRV.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 be OPUT to an HFS file later to */ /* enable easy downloading by clients. */ /****************************************************************/ if (ca_domain = "") then /* If no CA Domain... @L4A*/ export_dsn = "'PKI1SRV.CACERT.DERBIN'" else /* Else use CA Domain @L4A*/ export_dsn = "'PKI1SRV.CACERT.DERBIN'" /* CA Domain qualify export dsn @L4A*/

/****************************************************************/ /* 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 = "'PKI1SRV.RAKEY.BACKUP.P12BIN'" /* @L5C*/ else /* Else use CA Domain @01A*/ ra_backup_dsn = "'PKI1SRV.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. */

246 System z Cryptographic Services and z/OS PKI Services /* If the user ID assigned to the IBM HTTP Server Daemon is not */ /* WEBSRV, please update the assignment below. */ /****************************************************************/ webserver="PKI1WEB"

/*------*/ /* End of configurable section */ /*------*/

To execute this script, you require the SPECIAL attribute in RACF. Perform a simulation of the IKYSETUP through the following command: EXECUTE data-set-name(IKYSETUP) ’RUN(NO)’

If you decided to create a backup copy of your CA digital certificate, a password is required to create a PKCS#12 certificate during IKYSETUP execution. Check the messages displayed.

After checking that the simulation is running successfully, execute the REXX script again, changing the RUN parameter to YES this time: EXECUTE data-set-name(IKYSETUP) ’RUN(YES)’.

7.3.3 UNIX environment configuration

Copy the UNIX files required to set up z/OS PKI Services into your own directory: cp -p /install-dir/samples/pkiserv.conf myPKIdirectory/ cp -p /install-dir/samples/pkiserv.tmpl myPKIdirectory cp -p /install-dir/samples/pkiserv.envars myPKIdirectory

Edit the configuration file, pkiserv.conf, and assign values to the variables. Example 7-6 is a copy of our configuration file.

Example 7-6 PKI Services configuration file [OIDs] # # Supported Distinguished Name OIDs # C=2.5.4.6 O=2.5.4.10 OU=2.5.4.11 CN=2.5.4.3 L=2.5.4.7 ST=2.5.4.8 TITLE=2.5.4.12 POSTALCODE=2.5.4.17 STREET=2.5.4.9 MAIL=0.9.2342.19200300.100.1.3 EMAIL=1.2.840.113549.1.9.1 SERIALNUMBER=2.5.4.5 UNSTRUCTUREDNAME=1.2.840.113549.1.9.2 UNSTRUCTUREDADDRESS=1.2.840.113549.1.9.8

# # Signature Algorithm OIDs

Chapter 7. z/OS PKI Services 247 # sha-1WithRSAEncryption=1.2.840.113549.1.1.5 md-5WithRSAEncryption=1.2.840.113549.1.1.4 md-2WithRSAEncryption=1.2.840.113549.1.1.2 id-dsa-with-sha1=1.2.840.10040.4.3

MyPolicy=1.2.3.4

[ObjectStore] # Data set name of the VSAM request (object store) base CLUSTER ObjectDSN='pki1srv.vsam.ost'

# Data set name of the VSAM object store PATH for the transaction ID (TID) # alternate index. ObjectTidDSN='pki1srv.vsam.ost.path'

# Data set name of the VSAM object store PATH for the status alternate index ObjectStatusDSN='pki1srv.vsam.ost.status'

# Data set name of the VSAM object store PATH for the requestor alternate index ObjectRequestorDSN='pki1srv.vsam.ost.requestr'

# Data set name of the VSAM issued certificate list (ICL) base CLUSTER ICLDSN='pki1srv.vsam.icl'

# Data set name of the VSAM ICL PATH for the status alternate index ICLStatusDSN='pki1srv.vsam.icl.status'

# Data set name of the VSAM ICL PATH for the requestor alternate index ICLRequestorDSN='pki1srv.vsam.icl.requestr'

# How days (d) or weeks (w) should completed requests remain in the object store # Specify 0d to indicate completed requests should not be removed RemoveCompletedReqs=1w

# How days (d) or weeks (w) should inactive requests remain in the object store? # Specify 0d to indicate inactive requests should not be removed RemoveInactiveReqs=4w

# How many days (d) or weeks (w) should expired certificates remain in the ICL? # Specify 0d to indicate expired certificates should not be removed #RemoveExpiredCerts=26w

# Are the VSAM data sets shared in a sysplex with other instances # of PKI Services. True (T) or False (F) SharedVSAM=F

[CertPolicy] SigAlg1=sha-1WithRSAEncryption CreateInterval=30s

# When the warning message should be issued. (i.e. the number of days # or weeks before the certificate expiration date/time). Defaults to never ExpireWarningTime=4w

248 System z Cryptographic Services and z/OS PKI Services TimeBetweenCRLs=1d CRLDuration=2d

# Maximum number of certificates that may appear on one distribution point CRL. # The default is 0 which indicates distribution point CRLs should not be created

CRLDistSize=500

# Constant portion of the CRL distribution point leaf-node relative # distinguished name. The distribution point number is appended to this value # to form the common name. The default value is "CRL". CRLDistName=CRL

# Authority Revocation List(ARL) Distribution Point. 'F' (default) indicates # no ARL distribution point will be created. 'T' indicates ARL distribution # point will be created IF CRLDistSize is greater than zero. ARLDist=F

# Full path of the HFS Directory where PKI Services is to save each # distribution point CRL specified by the CRL distribution point extension # "Uniform Resource Identifier" fields(URI) for the http protocols. Defaults # to /var/pkiserv/. It will be ignored if you do not create the extension # for the http protocol. CRLDistDirPath=/var/pkiserv/

# Values for the CRL distribution point extension URI fields for the # protocols(ldap, http) you choose. This is repeatable. The first one # always starts with CRLDistURI1, followed by CRLDistURI2, 3, ...n, # if necessary. Uncomment and update the desired directive to enable # URI CRL distribution point that you need. If more than one URI field # is needed, remember to increase the field number sequentially by the # order of one, e.g. CRLDistURI2, CRLDistURI3...

# For ldap protocol, you may specify the LDAP server indicated in the LDAP # section below, e.g., #CRLDistURI1=LdapServer1

# or specify a skeleton URL which contains the protocol type, the domain # name and the port, if needed, e.g., #CRLDistURI1=ldap://myotherldapserver.mycompany.com:389/

# For http protocol, specify the complete URL minus the file name of the # distribution point CRL file, e.g., CRLDistURI1=http://9.12.4.18:1080/PKIServ/cacerts/

# What type of OCSP request is desired? # 'none' - No OCSP responder support (This is the default) # or # 'basic' - the signature in the request(if there is one) will be ignored OCSPType=none

# # Enable the Simple Certificate Enrollment Protocol (SCEP) # T = True, SCEP is enabled # F = False, SCEP is disabled (default if not specified) #

Chapter 7. z/OS PKI Services 249 EnableSCEP=F

PolicyRequired=F PolicyCritical=F

PolicyName1=MyPolicy Policy1Org=MyOrganization Policy1Notice1=3 Policy1Notice2=17 UserNoticeText1=This is some very lawyerly statement for the relying party to re CPS1=http://9.12.4.18:1080/cps.html

# Length of certificate suspension grace period in day or weeks (d,w). # Certificates which remained suspended for longer than this period are # automatically revoked. # The default value is 0d which indicates the grace period is unlimited. MaxSuspendDuration=120d

# Specify the email address(es) of the administrator(s) who will receive # an email notification on pending requests immediately. This is repeatable. # The first one always starts AdminNotifyNew1, followed by # AdminNotifyNew2, 3, ...n, if necessary. The field number increases # sequentially by the order of one. Uncomment and update the desired # email address(es) to enable the notification. #[email protected]

# Specify the email address(es) of the administrator(s) who will receive # an email notification on pending requests every day. This is repeatable. # The first one always starts AdminNotifyReminder1, followed by # AdminNotifyReminder2, 3, ...n, if necessary. The field number increases # sequentially by the order of one. Uncomment and update the desired email # address(es) to enable the notification. #[email protected]

[General] InitialThreadCount=10

# Timeout value for the exit program. Default is 30 seconds (30s). ExitTimeout=30s

# full pathname or data set name containing the 'your certificate is ready' # message form. Defaults to no message issued ReadyMessageForm=/var/pkiserv/readymsg.form

# full pathname or data set name containing the 'your certificate request # has been rejected' message form. Defaults to no message issued RejectMessageForm=/var/pkiserv/rejectmsg.form

# full pathname or data set name containing the 'your certificate is about # to expire' message form. Defaults to no message issued ExpiringMessageForm=/var/pkiserv/expiringmsg.form

# full pathname or data set name containing the request(s) pending for approval # message form. Defaults to no notification sent.

250 System z Cryptographic Services and z/OS PKI Services AdminNotifyForm=/var/pkiserv/pendingmsg.form

# full pathname or data set name containing the renewed certificate. Defaults to # no certificate sent. RenewCertForm=/var/pkiserv/renewcertmsg.form

[SAF] KeyRing=PKI1SRV/PKI1ring.PKI1SRV

# The Label name for the PKI RA certificate connected to the Key ring # specified in the KeyRing value above # RALabel=PKI1 RA

[LDAP] NumServers=0 PostInterval=5m Server1=9.12.4.18:389 AuthName1=CN=root AuthPwd1=root CreateOUValue= Created by ITSO PKI Services RetryMissingSuffix=T # Name of the LDAPBIND Class profile containing the bind information for LDAP # server 1. This key is optional. Used in place of keys Server1, AuthName1. # and AuthPwd1 #BindProfile1=LOCALPKI.BINDINFO.LDAP1

In our configuration, we did not deploy sendmail for e-mail communication with users and administrators.

Edit the environment variables file and make any necessary changes. Example 7-7 shows a copy of our system pkiserv.envars.

Example 7-7 PKI Services environment variables file # Language and Path configurations # LANG=En_US.IBM-1047 PATH=/usr/sbin LIBPATH=/usr/lpp/pkiserv/lib:/usr/lib NLSPATH=/usr/lib/nls/msg/%L/%N:/usr/lpp/pkiserv/lib/nls/msg/%L/%N

# # When running as a CA Domain, set the CA Domain name by assigning # desired value to the _PKISERV_CA_DOMAIN variable. # Note: The first eight characters must be unique. # # example: _PKISERV_CA_DOMAIN=WebAppCA

# # Configuration File location and Message configuration Options # _PKISERV_CONFIG_PATH=/u/ranieri/PKI1/ _PKISERV_MSG_LOGGING=stdout_logging _PKISERV_MSG_LEVEL=*.d

Chapter 7. z/OS PKI Services 251

# # Set up a directory for PKI Services to write persistent data. The # maximum length is 256 characters including the trailing /. # The default is /var/pkiserv/.

# # example: _PKISERV_VARDIR=/var/pkiserv/

# # Set up an exit program for autorenew. The maximum length is 256 # characters including the program name. # # example: _PKISERV_EXIT=/mydir/renewexit

# # Location of the OCSF Registry (/var/ocsf is the default location) # OCSFREGDIR=/var/ocsf

It is necessary to set the file security packet information for the file containing the certificate authority digital certificate backed up at IKYSETUP. Use the following command to perform the task: 1. First run: chown PKISRVD /var/pkiserv 2. Copy the certificate authority certificate from its MVS data set to the cacert.der file in the /var/pkiserv directory. 3. Run: cp "//’pkisrvd.cacert.derbin’" /var/pkiserv/cacert.der 4. Run: chmod 644 /var/pkiserv/cacert.der 5. Run: chown pkisrvd /var/pkiserv/*

7.3.4 OCSF and OCEP

The Open Cryptographic Services Facility (OCSF) is a derivative of the IBM Keyworks technology, which is an implementation of the Common Data Security Architecture (CDSA) for applications running in the UNIX System Services environment. Open Cryptographic Enhanced Plug-in (OCEP) is also exploited by the PKI Services Trust Policy to access the RACF database.

To customize both products, follow the steps described in Chapter 1, “Configuring and Getting Started,” in z/OS Open Cryptographic Services Facility Application Programming, SC24-5899.

252 System z Cryptographic Services and z/OS PKI Services 7.3.5 LDAP directory

This document does not cover LDAP directory installation and customization. For this exercise, we actually used an existing LDAP.

7.3.6 VSAM ObjectStore and ICL data sets

During this step, we allocate ObjectStore and ICL data sets. A sample JCL at IKYCVSAM member is in SYS1.SAMPLIB. Copy the member to your own data set and adapt it to your own environment. In Example 7-8, you can find the JCL we ran on our system.

Example 7-8 IKYCVSAM to allocate ObjectStore and ICL VSAM data sets //IKYCVSAM JOB MSGCLASS=A,CLASS=A,MSGLEVEL=(1,1),NOTIFY=&SYSUID //DELCLUST EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=* //SYSIN DD * DELETE - PKI1SRV.VSAM.OST CLUSTER PURGE ERASE DELETE - PKI1SRV.VSAM.ICL CLUSTER PURGE ERASE IF MAXCC LT 9 THEN SET MAXCC = 0 /* //*------* //* Define KSDS * //*------* //DEFKSDS EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=* //SYSIN DD * DEFINE CLUSTER - (NAME(PKI1SRV.VSAM.OST) - VOL(CONSY1) RECSZ(1024 32756) INDEXED NOREUSE - KEYS(4 0) SHR(2) CYL(3,1) LOG(NONE) OWNER(PKI1SRV) ) - DATA - (NAME(PKI1SRV.VSAM.OST.DA) CISZ(1024) SPANNED) - INDEX - (NAME(PKI1SRV.VSAM.OST.IX))

DEFINE CLUSTER - (NAME(PKI1SRV.VSAM.ICL) - VOL(CONSY1) RECSZ(1024 32756) INDEXED NOREUSE - KEYS(4 0) SHR(2) CYL(3,1) LOG(NONE) OWNER(PKI1SRV) ) - DATA - (NAME(PKI1SRV.VSAM.ICL.DA) CISZ(1024) SPANNED) - INDEX - (NAME(PKI1SRV.VSAM.ICL.IX)) /* //*------* //* Repro record of all binary zeros into KSDS * //*------* //MKZEROS EXEC PGM=IEBGENER //SYSPRINT DD SYSOUT=* //SYSUT1 DD *

//SYSUT2 DD DSN=&&GENTMP,UNIT=SYSDA,DISP=(,PASS),

Chapter 7. z/OS PKI Services 253 // DCB=(RECFM=FB,LRECL=80,BLKSIZE=640),SPACE=(TRK,(1,1)) //SYSIN DD * GENERATE MAXFLDS=4,MAXLITS=80 RECORD FIELD=(20,X'0000000000000000000000000000000000000000',,1), FIELD=(20,X'0000000000000000000000000000000000000000',,21),

FIELD=(20,X'0000000000000000000000000000000000000000',,41), FIELD=(20,X'0000000000000000000000000000000000000000',,61) /* //REPROKSD EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=* //SYSDATA DD DSN=*.MKZEROS.SYSUT2,DISP=(OLD,DELETE) //SYSIN DD * REPRO INFILE(SYSDATA) OUTDATASET(PKI1SRV.VSAM.OST) REPRO INFILE(SYSDATA) OUTDATASET(PKI1SRV.VSAM.ICL) /* //*------* //* Define ALTERNATE INDEX and PATH * //*------* //DEFALTDX EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=* //SYSIN DD * DEFINE ALTERNATEINDEX - (NAME(PKI1SRV.VSAM.OST.AIX) RELATE(PKI1SRV.VSAM.OST)- VOL(CONSY1) TRK(5,1) KEYS(24 44) ) - DATA (NAME(PKI1SRV.VSAM.OST.AIX.DA)) - INDEX (NAME(PKI1SRV.VSAM.OST.AIX.IX)) DEFINE PATH - (NAME(PKI1SRV.VSAM.OST.PATH) PATHENTRY(PKI1SRV.VSAM.OST.AIX)) DEFINE ALTERNATEINDEX - (NAME(PKI1SRV.VSAM.OST.STATAIX) RELATE(PKI1SRV.VSAM.OST)- VOL(CONSY1) TRK(5,1) KEYS(40 4) ) - DATA (NAME(PKI1SRV.VSAM.OST.STATAIX.DA)) - INDEX (NAME(PKI1SRV.VSAM.OST.STATAIX.IX)) DEFINE PATH - (NAME(PKI1SRV.VSAM.OST.STATUS) - PATHENTRY(PKI1SRV.VSAM.OST.STATAIX)) DEFINE ALTERNATEINDEX - (NAME(PKI1SRV.VSAM.ICL.STATAIX) - RELATE(PKI1SRV.VSAM.ICL) VOL(CONSY1) TRK(5,1) KEYS(40 4) ) - DATA (NAME(PKI1SRV.VSAM.ICL.STATAIX.DA)) - INDEX (NAME(PKI1SRV.VSAM.ICL.STATAIX.IX)) DEFINE PATH - (NAME(PKI1SRV.VSAM.ICL.STATUS) - PATHENTRY(PKI1SRV.VSAM.ICL.STATAIX)) DEFINE ALTERNATEINDEX - (NAME(PKI1SRV.VSAM.OST.REQAIX) - RELATE(PKI1SRV.VSAM.OST) VOL(CONSY1) TRK(5,1) KEYS(32 12) ) - DATA (NAME(PKI1SRV.VSAM.OST.REQAIX.DA)) - INDEX (NAME(PKI1SRV.VSAM.OST.REQAIX.IX)) DEFINE PATH - (NAME(PKI1SRV.VSAM.OST.REQUESTR) - PATHENTRY(PKI1SRV.VSAM.OST.REQAIX)) DEFINE ALTERNATEINDEX - (NAME(PKI1SRV.VSAM.ICL.REQAIX) - RELATE(PKI1SRV.VSAM.ICL) VOL(CONSY1) TRK(5,1) KEYS(32 12) ) -

254 System z Cryptographic Services and z/OS PKI Services DATA (NAME(PKI1SRV.VSAM.ICL.REQAIX.DA)) - INDEX (NAME(PKI1SRV.VSAM.ICL.REQAIX.IX)) DEFINE PATH - (NAME(PKI1SRV.VSAM.ICL.REQUESTR) - PATHENTRY(PKI1SRV.VSAM.ICL.REQAIX))

/* //*------* //* BUILD ALTERNATE INDEX * //*------* //BLDINDEX EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=* //SYSIN DD * BLDINDEX INDATASET(PKI1SRV.VSAM.OST) - OUTDATASET(PKI1SRV.VSAM.OST.AIX) BLDINDEX INDATASET(PKI1SRV.VSAM.OST) - OUTDATASET(PKI1SRV.VSAM.OST.STATAIX) BLDINDEX INDATASET(PKI1SRV.VSAM.ICL) - OUTDATASET(PKI1SRV.VSAM.ICL.STATAIX) BLDINDEX INDATASET(PKI1SRV.VSAM.OST) - OUTDATASET(PKI1SRV.VSAM.OST.REQAIX) BLDINDEX INDATASET(PKI1SRV.VSAM.ICL) - OUTDATASET(PKI1SRV.VSAM.ICL.REQAIX) /* //*------* //* Print out the cluster * //*------* //PRTCLUST EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=* //SYSIN DD * PRINT INDATASET(PKI1SRV.VSAM.OST) CHAR PRINT INDATASET(PKI1SRV.VSAM.ICL) CHAR /*

7.3.7 Starting and stopping PKI Services

z/OS PKI Services procedures can be found at member PKISERVD in SYS1.PROCLIB. The PKISERVD procedure contains the time zone environment variable, which is the environment variable most likely to change.

Start z/OS PKI Services started task issuing the S PKISERVD command. To stop the server, issue the P PKISERVD command.

7.4 Accessing our z/OS PKI Services Home page

After completing the customization tasks, you can start the server and connect to it. If successful, you can see the z/OS PKI Services home page. The home page URL for the domain is http:////public-cgi/camain.rexx where appl-domain-name corresponds to the section name defined in the template file in httpd.conf.

Chapter 7. z/OS PKI Services 255 Figure 7-14 shows our home page, which is displayed at: http://9.12.4.18:1080/PKI1/public-cgi/camain.rexx

Figure 7-14 z/OS PKI Services home page

256 System z Cryptographic Services and z/OS PKI Services

Chapter 8. Sample scenario

This chapter describes the scenario and the implementation we created in the International Technical Support Organization (ITSO) environment. The objective of describing this sample scenario is to demonstrate the possibility of using a modern browser-based interface to z/OS PKI Services. We also demonstrate how the new services and technology available in z/OS V1.9 can be used in an installation.

This sample implementation demonstrates the capability of System z to provide PKI support through advanced Web technology. Perhaps you wonder why this infrastructure should be pursued in light of similar capabilities on other platforms. The answer to this question is simple: In an environment that is becoming increasingly automated, the demand for a security bastion supporting this effort becomes paramount.

Today system managers rely on user knowledge (primarily passwords) to assure secure access on remote platforms. With the advent of cloud computing, and similar distributed technologies, it becomes increasingly important to automate management of clusters to ensure efficiency. If systems are managed by other machines directly, as apposed to traditional operations requiring direct operator control, a cohesive process is required for managing the machine identities and their life cycles. Adding people to this process compromises the overall integrity of the system.

Clients who buy into servers managing servers are looking for a secure solution for managing identities between servers. The system cries out for a solution that mutually authenticates partners with a third-party player vouching for each participant. As the infrastructure grows, it becomes increasingly apparent that people cannot play an efficient role in this process. An automated third party that has a reputation for security and an ability to manage the system with continuous availability is needed.

The exercise in this chapter combines the capabilities of RACF with WebSphere Application Server to manage the PKI infrastructure. The exercise demonstrates with Web pages what could have easily been implemented with Web services. Imagine System z as the entire PKI infrastructure servicing a large compute cloud. Each server could request its own certificate, manage its life cycle, and communicate with its peers using RACF as the repository and third-party verifier.

An entire management infrastructure that leverages a z/OS-based security infrastructure with Linux on System z-based management tools operating on the all the nodes in a cluster provides a centralized management model with distributed flexibility. Because Linux images can segment the community of servers being managed and z/OS can provide an always available security environment, the System z platform can become the full service hub of the enterprise infrastructure.

8.1.1 Structure of sample scenario

From an architectural point of view, we can see the two different roles interacting with the PKI environment: the user who initiates the request for a certificate and the administrator who is responsible for managing the certificate requests and specially responsible for the approval of certificates.

In the sample scenario, the user role is the only flow that was implemented to demonstrate the possibility of the architected solution: The user requesting a certificate The user retrieving the certificate (a certificate that has been implicitly approved because the sample scenario does not include administrator tasks)

258 System z Cryptographic Services and z/OS PKI Services Figure 8-1 depicts the flow of the process that begins when a user requests a certificate. The user requests a key pair and a certificate from the browser, and z/OS PKI Services returns a transaction ID that eventually is used to retrieve the PKCS12-generated certificate.

WebSphere Application Server wrapper PKIExit

Cert Collect PKCS#11 API to request generate Key pair parameters Build PKCS10 R_PKISERV request (PKCS10) PKCS#11 API to store TransId with Key pair TransId in PKCS11 token

TransId

PKI Daemon

Figure 8-1 Overview of user certificate request

Chapter 8. Sample scenario 259 Figure 8-2 shows the flow of retrieving the generated PKCS12 file, providing as input the transaction ID previously issued by z/OS PKI Services, along with the passphrase the user has specified at the time of the request.

WebSphere Application Server wrapper PKIExit

Cert request Collect parameters

R_PKISERV PKCS#11 API to get export private key matching the End user TransId

Build PKCS12 using PKCS12 certificate certificate + private key + password

certificate

PKI Daemon

Figure 8-2 User certificate retrieval

In the following sections, you learn how the elements have been implemented as part of the sample solution.

8.2 ITSO implementation

To demonstrate the possibilities of a J2EE front end for the z/OS PKI services, we created a scaled-down example application. For the purposes of this demonstration, we limited our implementation to only the user function: In our scenario, the user can request a certificate and retrieve the certificate without needing administrator approval. Our environment

260 System z Cryptographic Services and z/OS PKI Services consisted of a single z/OS V1.9 LPAR running WebSphere Application Server V6.1. See Figure 8-3.

z/OS J2EE Container

User SSL Java EJB PKI Browser Native Servlet Session Service Interface Facade Core (JNI)

Pre/Post Admin User SSL Plugins Browser

Wrapper C exit

RACF Service (R_PKISERV)

Figure 8-3 ITSO implementation

We examine certain components of the sample application to describe how to implement such a solution as well as to suggest necessary improvements.

8.2.1 Java implementation

The Java components follow the traditional Java Enterprise Edition (J2EE) pattern, consisting of a servlet communicating to an Enterprise JavaBean (EJB™) business layer. That business layer contains various extension points wrapped around a Java Native Interface (JNI) call to the C implementation discussed in the section that follows.

Chapter 8. Sample scenario 261 Object model The PKI Services object model (see Figure 8-4) consists of a set of Java interfaces and JavaBeans™ that represent the various activities allowed by the RACF service R_PKISERV. These classes are contained in the com.ibm.pkisvcs.model package, and they implement the PKIServicesRequest interface. The PKCS12 object is represented by the com.ibm.pkisvcs.model. PKCS12KeyStore class provides much of the same functionality as the java.security.KeyStore class.

Figure 8-4 Class diagram representing the PKI Services object model

Servlet layer The servlet tier of the application acts as an interface between the user and the business application. The servlet tier takes input in the form of a secure HTTP request and performs the required validations on the data. After validating the request, the servlet layer marshalls the data into object representations of the PKI Services object model. The servlet layer calls a method in the EJB layer by looking up the EJB reference in the Java Naming and Directory Interface (JNDI). The servlet layer should also control authentication and access to interface components if those tasks are not delegated to outside programs.

During the process of certificate retrieval, the PKCS12 message must be returned to the browser in binary form. This is accomplished by setting the content type of the response to application/x-pkcs12 and writing the byte array representing the binary-encoded PKCS12 message to the output stream. The source code used to return the PKCS12 message to the browser follows: response.setContentType("application/x-pkcs12"); BufferedOutputStream out = new BufferedOutputStream(response.getOutputStream()); out.write(keystore.getPkcs12()); out.flush(); out.close();

The example implementation uses a standard servlet/JSP approach for simplicity's sake. For your production implementation, we recommend that you consider leveraging a Web application framework such as Struts or Java Server Faces (JSF). A further enhancement is to use a templating engine such as Velocity to enable the same level of customizations as the current CGI implementation.

262 System z Cryptographic Services and z/OS PKI Services In our example, security is handled through standard J2EE mechanisms. A single role, CertificateRequester, is used to constrain access to all requests through the servlet through this excerpt of the web.xml: CertificateRequests PKIServicesServlet /PKIServicesServlet Users who are can request certificates CertificateRequester NONE CertificateRequester

In a full implementation, a second role is required to protect administrative functions.

The IBM Rational suite of development tools includes enhanced editors to ease the creation of security controls. For more information about using Rational products for securing J2EE applications, refer to Chapter 11, “Implement Core Security,” in Experience J2EE! Using WebSphere Application Server V6.1, SG24-7297.

Enterprise JavaBeans Enterprise JavaBeans™ implements the Session Facade design pattern as described in the classic book Design Patterns.1 The Session Facade design pattern simply delegates the completion of the work to the PKI Service Core code. An additional security check is performed at this layer with access control defined at the method level using J2EE security.

Access is defined in the META-INF/ejb-jar.xml file with the following snippet: Users who can request certificates CertificateRequester CertificateRequester PKIServicesSessionFacade Remote requestCertificate com.ibm.pkisvcs.model.CertificateRequest

1 Gamma, Erich, Richard Helm, Ralph Johnson, John Vlissides. Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley, Boston 1995

Chapter 8. Sample scenario 263 PKIServicesSessionFacade Remote

retrieveCertificate com.ibm.pkisvcs.model.RetrieveCertificateRequest PKIServicesSessionFacade Remote revokeCertificate com.ibm.pkisvcs.model.RevocationRequest PKIServicesSessionFacade ServiceEndpoint requestCertificate com.ibm.pkisvcs.model.CertificateRequest PKIServicesSessionFacade ServiceEndpoint retrieveCertificate com.ibm.pkisvcs.model.RetrieveCertificateRequest PKIServicesSessionFacade ServiceEndpoint revokeCertificate com.ibm.pkisvcs.model.RevocationRequest As with the servlet layer, it is necessary to add security controls for the administrative functions in the production application.

The EJB methods can also be exposed as Web services, allowing access either directly by a service consumer or through an enterprise service bus. This can be easily accomplished through the Rational suite of development tools. For additional information and examples,

264 System z Cryptographic Services and z/OS PKI Services refer to the IBM developerWorks® article, “IBM Rational Application Developer Web services tooling tips and tricks: Part 1: Be aware of the preferences page” at: http://www.ibm.com/developerworks/rational/library/07/0508_cui/index.html

8.2.2 PKI Services core

The core components include the plug-in framework (discussed in the section that follows) and the PKIServicesDelegate class that invokes the JNI code. It provides a level of abstraction between the EJB and the JNI code to limit the influence of changes to the business logic. It also provides a location to add any business rules that should be handled in the Java code.

Plug-in framework The plug-in framework is a method for replicating and expanding upon the C exit functionality delivered with the native PKI services implementation. The framework enables developers to create classes that implement the com.ibm.pkisvcs.plugins.Plugin interface to dynamically load methods that are called either before or after processing the services request. Plug-in classes are specified in a plugin.properties file. This file is deployed in the classpath of the JVM using a comma-separated string keyed by pkiservices.plugin.classes and containing the fully qualified class names of the plug-in classes.

Each class that implements the Plug-in interface must implement the registerPlugins method. Within that method, the developer must register each method with the singleton instance of the com.ibm.pkisvcs.plugins.PluginRegistry using the following code: PluginRegistry.getInstance().registerPlugin(Integer phase, Integer function, String className, String methodName)

Each plug-in method must accept the arguments String userID and PKIServicesRequest request and must return a boolean value indicating whether processing should continue. All possible phases and functions are defined as constants in the PluginRegistry class and are reflected in Table 8-1 and Table 8-2.

Table 8-1 Plug-in description Phase Description

PREPROCESSING Plug-in is invoked before making the service call to the C wrapper POSTPROCESSING Plug-in is invoked after the service call returns from the C wrapper

Table 8-2 PKI Services Function Description GENCERT Creates the certificate

EXPORT Retrieves the certificate

REQCERT Requests the certificate

REVOKE Revokes the certificate

GENRENEW Creates a certificate renewal

Chapter 8. Sample scenario 265 Function Description

REQRENEW Requests renewal of a certificate AUTORENEW Triggers an automatic renewal of a certificate

Plug-in example The following is the source code of a sample plug-in that checks whether a certificate requester is from a valid organization: public class SamplePlugin implements Plugin { public void registerPlugins() {

PluginRegistry.getInstance().registerPlugin(PluginRegistry.PREPROCESSING, PluginRegistry.GENCERT, this.getClass().getName(), "checkValidOrg"); }

public boolean checkValidOrg(String userID, PKIServicesRequest request) { if (!(request instanceof CertificateRequest)) { return false; } CertificateRequest certReq = (CertificateRequest)request; String org = certReq.getOrganization(); if (org != null && !"".equals(org) && isValidOrg(org)) { return true; } else { return false; } }

The registerPlugins method retrieves the singleton instance of the PluginRegistry and requests that the SamplePlugin.checkValidOrg method be called before processing the GENCERT function.

The checkValidOrg method simply invokes the relevant business logic and returns true if the processing should continue and false if it should halt.

The corresponding entry in the plugin.properties file, which indicates this plug-in should be loaded is: pkiservices.plugin.classes = com.ibm.pkisvcs.plugins.SamplePlugin

Java Native Interface JNI code transforms the Java objects from the data model into a format that can be passed to the C wrapper code and then invokes the C code. Because WebSphere Application Server uses an ASCII encoding scheme, it is necessary to translate the parameters to EBCDIC through the C method: jint GetStringPlatformLength(JNIEnv* env, jstring instr, jint* outlen, const char* encoding);

where the value of the encoding argument is IBM-1047 for EBCDIC.

266 System z Cryptographic Services and z/OS PKI Services To support the processing of the byte array returned from the C code on certificate retrieval, it is necessary to install the IBM Unrestricted JCE Policy Files, which can be found at https://www.software.ibm.com/webapp/iwm/web/reg/pick.do?source=jcesdk&lang=en_US

The files at this location work for both Java V1.4 and Java V5.0.

8.2.3 C code implementation

The back-end code initiated by the JNI is composed of two sections: the wrapper and the PKI exit. The wrapper provides the interface between the J2EE worlds and the customizable C exit.

Our sample PKI exit collects the additional information needed to issue the R_PKISERV API and handle saving and retrieving the generated certificates exploiting the PKCS#11 capability. The PKI exit code is isolated from the wrapper to facilitate an easy merge with the installation’s current PKI exit.

We discuss two main flows coming from the WebSphere Application Server: the request for (in our sample, it is the generation of) a certificate and the certificate retrieval.

Certificate request and generation This process receives the certificate request and, after the requests passes through the PKI user exit, presents the request to the PKI daemon via the R_PKISERV API. Once the certificate request has been submitted, the wrapper stores the certificate ID as part of the PKCS#11 token and returns the information to the user.

Chapter 8. Sample scenario 267 Figure 8-5 illustrates the wrapper process for the certificate request function.

Get Parms from Java The Java unicode is translaletd -Type of call into EBCDIC using a etStringPlatform() -Passphrase -Parameters Note: WebSphere Application Server JVM uses getStringPlatform() (ASCII char set)

The Shared Memory Object is used to pass data between the JNI code and the Wrapper. In our sample, we use SHM for simplicicity Create SHM Object of coding. We define a unique SHM header to allow multiple requests to flow concurrently. Another method could be to use piping between the wrapper and the PKI exit.

Spawn the exit The spawn is generated to maintain separation with the 1 Exit user code.

Wait for the certifcate from The Exit will create a Public/Private Key pair the exit 2 (PKCS#11) and will build a PKCS10 certificate request.

Call RACF (Gencert) and move A call is made to RACF to create a certificate request, the certificate-id passed back using the passphrase and the parms passed in by Into the SHM the user. A Certificate-ID will be returned.

Move the Certificate ID into We pass the Certificate_ID to the exit. The exit will the SMH save it as an attribute of the key pair just generated.

Post the Exit Wait until the exit terminates to save the 3 attributes.

Wait for the termination of the Exit 4

The wrapper returns the Certificate ID associated with the Pass back to the user the Ceritificate ID and Terminate certificate just created to the JAVA code.

Figure 8-5 Certificate request wrapper flow chart

268 System z Cryptographic Services and z/OS PKI Services Figure 8-6 illustrates the flow chart of the PKI exit to support the certificate request.

Get Parms - Type of Call (Generate/Retrieve) -Parms (i.e. OU,DN)

Generate a Public/Private Invoke the PKCS#11 API to generate Key pair a Private/Public Key Pair

Build a Certificate request Build a PKCS10 using the just generated keys

We use the shared memory object to pass the Move the certificate just certificate to the wrapper created Into the SHM object

Post the wrapper The exit informs the JNI wrapper that the certificate 2 is ready

Wait for the certificate_ID The JNI wrapper calls RACF to create a certificate 3 request and pass back to the exit the related Certificate_ID

Store the certificate_ID as attribute of the key Invoke the PKCS#11 API to store the Certificate ID Objects just created as attribute of the key objects just created

Post to the wrapper 4 Inform the JNI wrapper we are terminating

Exit

Figure 8-6 Certificate request PKI exit flow chart

Certificate retrieval The wrapper collects information, such as the certificate ID and the passphrase, and retrieves the certificate. Once the certificate has been obtained, the wrapper builds a PKCS12 certificate to be presented back to the user.

Chapter 8. Sample scenario 269 Figure 8-7 illustrates the wrapper flow for the certificate retrieval function.

Retrieve JNI code

Get Parms from Java The Java unicode is translated -Type of call into EBCDIC using etStringPlatform() -Passphrase -Parameters Note: WebSphere Application Server JVM uses an ASCII char set

The Shared Memory Object is used to pass data between Create SHM Object the JNI code and the Exit.

Call RACF (Export) and move Th wrapper calls RACF to create a certificate export request. the certificate ID passed back We use the passphrase and the certificate ID passed in by into the SHM the user. A certificate is returned.

The exit retrieves the keys previously saved Spawn the exit 10 associated with the certificate ID passed as input by the user (PKCS#11) and builds a PKCS12. The Shared Memory Object is used to pass the Wait for the certifcate from 11 PKCS12 back to the JNI code. the exit

Figure 8-7 Certificate retrieval wrapper flow chart

Figure 8-8 illustrates the flow chart of the PKI exit to support certificate retrieval.

Retrieve Exit

Get Parms - Type of Call (Generate/Retrieve) - Parms (certificate ID)

Retrieve public/private Invoke the PKCS#11 API to retrieve the keys key pair associated with the Certificate_ID passed.

Build a certificate Build a PKCS12 using the keys just retrieved.

We use the shared memory object to pass the Move the certificate just certificate to the JNI code. created into the SHM

Post the JNI 11

Exit

Figure 8-8 Certificate retrieval PKI exit flow chart

270 System z Cryptographic Services and z/OS PKI Services

Note: You can download the code associated with the ITSO scenario. For instructions on how to do so, refer to Appendix A, “Additional material” on page 273.

Chapter 8. Sample scenario 271

272 System z Cryptographic Services and z/OS PKI Services

Appendix A. Additional material

This IBM Redbook refers to additional material that can be downloaded from the Internet as described in the sections that follow.

Locating the Web material

The Web material associated with this Redbook is available in softcopy on the Internet from the IBM Redbooks Web server. Point your Web browser at: ftp://www.redbooks.ibm.com/redbooks/SG247470

Alternatively, you can go to the IBM Redbooks Web site at: ibm.com/redbooks

Select Additional materials and open the directory that corresponds with the IBM Redbooks form number, SG24-7470.

Using the Web material

The additional Web material that accompanies this book includes the following files: File name Description sg247470.zip Zipped code and installation instructions

274 System z Cryptographic Services and z/OS PKI Services Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this book.

Publications

These publications are also relevant as further information sources: ICSF Overview, SA22-7519 ICSF System Programmer’s Guide, SA22-7520 ICSF Application Programmer’s Guide, SA22-7522 ICSF Administrator’s Guide, SA22-7521 ICSF Messages, SA22-7523 z/OS V1R6.0 ICSF TKE Workstation User’s Guide, SA22-7524

How to get Redbooks

You can search for, view, or download Redbooks, Redpapers, Technotes, draft publications and Additional materials, as well as order hardcopy Redbooks, at this Web site: ibm.com/redbooks

Help from IBM

IBM Support and downloads ibm.com/support

IBM Global Services ibm.com/services

276 System z Cryptographic Services and z/OS PKI Services Index

B BIND command (RACDCERT) 186 Numerics 0C6 abend 4 C 2096-R07/2096-S07 configurations, z9 BC 10 C API PKCS#11 162 token management callable services 163 A C code implementation, PKI Services example 267 accelerator mode 86 C_CloseSession service 201 ADDTOKEN command (RACDCERT) 185 CA certificate 119, 161, 220 adjunct processor (AP) 19, 58 backup copy/exported copy 246 hardware cryptography successful activity 61 CA domain 222 SMF reports and 68 CA See certificate authority z/VM and 62 cache consistency 40 AdminNotify keywords (z/OS PKI Services) 225 callable services 11, 75 Advanced Encryption Standard (AES) 95 access authorization 163 CKDS and 129 categories of 21 AES algorithm 96 CCA 21–24 callable service parameters 23 CCA cryptographic API 20, 35 AES See Advanced Encryption Standard CCA cryptographic API, key types 24 AES with CKDS 129 ISCF 37 AES-128 algorithm 5 parameters 23 AIA (AuthorityInfoAccess) 216 preprocessing exit 23 algorithms 15, 100 Public Key Decrypt 13 AES 24, 96 to symmetric key encipher 23 AES-128 5 token management, See token management callable asymmetric 95, 97 services asymmetric, IBMJECCA support for 100 Trusted Block Create 67 callable services and 23 See also ICSF callable services CEX2A and 39 case CKR_CANT_LOCK 197 CEX2C and 18 CBC See cipher block chaining IBMJCECCA, support for 100 CCA cryptographic API Java cryptography and 93–98 callable services See callable services JCE support for 99 DES key forms 27–30 mapping to providers 105 DES key management 24–30 Otello chip and 15 interoperability 21 restrictions on 100 key separation and 24–27 symmetric, IBMJECCA support for 100 key types supported by 24 types of 93, 95 portability 21 z/OS support for 105 See also Common Cryptographic Architecture AP numbers 19 CCA See Common Cryptographic Architecture AP See adjunct processor CCF See Cryptographic Coprocessor Feature APDEDICATED operand 62 CDSA See Common Data Security Architecture application programs, invoking callable services 37 Central Processor Assist for Cryptographic Functions APVIRTUAL operand 62 (CPACF) 9, 44, 56 ARLDist keyword (z/OS PKI Services) 220 hardware cryptography 42 asymmetric algorithms 95 ICSF and 36 IBMJCECCA support for 100 cert.getPublicKey 122 asymmetric-keys master key (ASYM-MK) 15, 31 CERTAUTH certificate 115, 175 ASYM-MK See asymmetric-keys master key CERTAUTH LABEL (RACDCERT) 115, 117 AUDIT(ALL) command 47 certificate authority (CA) 108, 118 Authority Revocation List (ARL) 220 certificate life cycle 208 AuthorityInfoAccess (AIA) 216 exporting with public key 115 generating, RACDCERT 114

© Copyright IBM Corp. 2008. All rights reserved. 277 global CRL 218 RMF data-collection infrastructure 69 z/OS PKI Services 220 SMF reports 67 certificate information 171 Chinese Remainder Theorem (CRT) binding to tokens 186 CEX2A 39 displaying 186 cryptographic accelerators 72 viewing 188, 192 PKA 32 certificate object 156 cipher block chaining (CBC) 24, 96 certificate requests 115, 178, 211, 258 support for 100 certificates exported as 118 CIPHER MESSAGEs 4 sample scenario 267 cipher text 93 certificate response 108, 115, 118 CKDS See Cryptographic Key Dataset Certificate Revocation List (CRL) 208 classes, IBMJCECCA, support for 100 CERTIFICATE TYPE field 170, 175 clear keys 11, 44, 86 certificate validation AES-128 encryption 19 API 218 asymmetric encryption 19 application 220 CCA callable services and 24 certificates DES encryption 54 CertPath 104 DES3 encryption 52 deleting 192 importing 21 deleting from z/OS PKCS#11 token 176 RSA 18 generating 186 CLEAR service, hardware keytool 120 generating, sample scenario 267 CMOS mainframe systems 12 importing 192–193 CN (Common Name) 241 information about, See certificate information Common Address Space Work, SMF reports 67 labels 173, 188 Common Cryptographic Architecture (CCA) 20–34, 42, listing in RACF 186 92, 157 PKI, life cycle 208 callable services 21–24 RACF panels 172 DES key management 24–30 retrieving, sample scenario 269 IBMJCECC and 99 revocation status 220 PCIXCC card and 17 SAF 108 PKA key management 30–34 self-signed 101 PKCS#11, as alternative to 155 serial numbers of 217 PowerPC 405GPr microprocessor and 14 type 217 rationale for design of 20 z/OS PKI Services 207 Common Data Security Architecture (CDSA) 43, 252 CertPath 104 common key management 20 not verified error 119 Common Name (CN) 241 CEX2 17 COMPONENT TRACE SHORT FORMAT (CSF) 57 coprocessor mode 18 component trace, System SSL 54 CPACF, comparing to 19 COMPUTE MESSAGE AUTHENTICATION CODE CEX2A 9, 39 (KMAC instruction) 4 activity of, measuring 86 configuring Crypto Hardware Activity report 74 hardware cryptography on z/VM 61–63 hardware cryptography, detecting 61 Java hardware cryptography 106 performance and 18 SSL for WebSphere Application Server 151–154 RMF data-collection infrastructure 69 SSL with hardware cryptography 137 SMF reports 67 UNIX environment for z/OS PKI Services 247–252 CEX2C 9, 39 control vectors 25 activity of, measuring 85 master keys 26 CCA and 100 mechanism 30 coprocessor ID 77 coprocessors 12, 58 Crypto Hardware Activity report 74 accelerator mode 42, 56, 62, 67 DES key management 24 coprocessor mode 62 encryption request processing 27 ICSF cryptographic workload balancing 66 hardware counters 73 measurement data 67 hardware cryptography 42 OMEGAMON XE on z/OS, support for 80 ICSF and 36 SMF reports and 68 Java cryptography in z/OS 100 See also CEX2, CEX2A, CEX2C logical partitions and 38 CP Assist for Cryptographic Functions (CPACF) 10–11 performance data, collecting 39 CEX2C/CEX2A, comparing to 19

278 System z Cryptographic Services and z/OS PKI Services CP QUERY CRYPTO command 63 frastructure CPACF See Central Processor Assist for Cryptographic Cryptoki See PKCS#11 Functions CryptoVSE API 45 CRL (Certificate Revocation List) 208 CRYPTOZ class 157 CRL Distribution Point 218 resource definitions 166 extension 220 resource name 161 CRLDistDirPath keyword 220 CRYPTOZ SAF class, permissions 178 CRLDistributionPoint extension 218 CSF (COMPONENT TRACE SHORT FORMAT) 57 CRLDistURIn keyword 220 CSFKEYS class 36, 38, 243 CRT See Chinese Remainder Theorem CSFPCI (PCI Interface Callable Service) 67 CRT(1024) field, Cryptographic Activity report 72 CSFSERV class 36, 38, 47, 163, 244 CRYPTO %DLY/CRYPTO %USG fields, Workload Activ- discrete profiles 49 ity report 76 RACF profiles 48 Crypto Express2 Coprocessor See CEX2C CSNBOWH callable services 70, 73, 82 Crypto Hardware Activity report 39, 70–75 CSNBYD/CSMBYE services 70 Cryptographic Accelerator section 72 CSP See Cryptographic Service Provider Cryptographic Coprocessor section 71 CUSTOMERS application, z/OS PKI Services 217 example 74 ICSF services section 73 without local activity 75 D RMF post-processor 70 DASD (direct access storage device) 157 structure of 71 data encryption algorithm (DEA) 4 crypto instructions 35 Data Encryption Standard (DES) 10 CRYPTO parameter 61 DEA (data encryption algorithm) 4 CRYPTO% DLY/CRYPTO%USG fields, Workload Activi- debug flag 222 ty report 76 default value 100, 160 Cryptographic Coprocessor Feature (CCF) 9, 12 DELETE command (RACDCERT) 192 cryptographic hardware and 31 DER encoding 171 DES key management and 24 DES algorithm 15, 18, 95 features, evolving 13 callable service parameters 23 PKA key forms 32 CKDS and 127 CRYPTOGRAPHIC COPROCESSOR section, RMF re- Crypto Hardware Activity report 39 ports 83 DES/TDES ciphers and 100 Cryptographic Express 2 Accelerator See CEX2A ICSF callable services 70 cryptographic hardware 9–20 key forms 27–30 CCF 12, 31 keys 12 comparison of 19 keys, external key tokens 28 CPACF 10–11 keys, managing 24–30 CPAF, CEX2C, CEX2A, comparing 19 keys, SMF reports 67 exploiting 38 DES DECRYPTION fields, Cryptographic Activity report flexibility 13 73 hwkeytool 101 DES keys monitoring 39 CKDS and 127 Otello chip 15 key separation 24–27 PCIXCC 14–16 DES/TDES Enablement Feature 10 secure area within 24 device drivers sysplex 40 PCIXCC card and 17 See also hardware cryptography z90crypt 46, 59 Cryptographic Key Dataset (CKDS) 11, 35 zcrypt 46 ICSF and 36 Diffie-Hellman algorithm 97 key labels and 28 digital certificate See certificates SMF reports 67 Digital Signature Algorithm (DSA) 221 cryptographic keys See keys Digital Signature Verify service 74, 86 cryptographic operations 11, 38 digital signatures 12, 87, 92 IBMJCECCA 101 algorithms 93 Cryptographic Service Provider (CSP) 43, 210 CCA callable services 22 cryptographic services 15, 41 generating 30 requests 66 IBMJCECCA support for 100 software implementation 44 process of using 94 cryptography, System z See System z, cryptography in- direct access storage device (DASD) 157 Distinguished Name, OIDs 247

Index 279 DOMAIN operand 61 HTTPS Web services 151 domains 38 IBMJCECCA 99 Double-DES encryption, ICSF callable services 70 Java features, setting up 106 DRAM (dynamic random access memory) 14 JCE and 92 DSA algorithm, z/OS PKI Services 221 key confidentiality on z/OS 101 DSA keys 222 measuring activity on z/OS 65–78 dynamic random access memory (DRAM) 14 performance and 99, 102 RMF data collection infrastructure 69 software cryptography and 100 E hash 39 ECB (electronic code book) 24 HASH fields, Cryptographic Activity report 73 ECC (Elliptic Curve Cryptography) 97 HTTP protocol 220 EIGamal algorithm 97 hwkeytool 101 EJBs (Enterprise JavaBeans), z/OS PKI Services, sample scenario 263 EKM (Encryption Key Manager) 115 I EKM server 116, 119 IBM CCA See Common Cryptographic Architecture electronic code book (ECB) 24 IBM HTTP servers 51, 225 Elliptic Curve Cryptography (ECC) 97 z/OS PKI Services 225–240 e-mail notification 208, 225 IBM Java Cryptography Extension See IBMJCE encrypting messages See messages, encrypting IBM Java Cryptography Extension via CCA See IB- Encryption Key Manager (EKM) 115 MJCECCA Enterprise JavaBeans (EJBs), z/OS PKI Services sample IBM Java Secure Sockets Extension See IBMJSSE scenario 263 IBM Redbooks Web site 273 environment variables, System SSL 50 IBM SDK 43, 104 ERBRMFxx member (SYS1.PARMLIB) 70 IBM Tivoli OMEGAMON XE See OMEGAMON XE on Expert Advice workspace, OMEGAMON XE on z/OS 80 z/OS exportable keys ibm.DES.usehdwr.size property 100 DES 27 IBMJCE 92, 97–99, 103 PKA 31 access to, IBM SDK 43 ExtKeyUsage extension 216 ciphers supported 99 hardware and software implementations, differences between 101 F provider 101 FB 0011 58 IBMJCECCA 92, 97, 104 Federal Information Processing Standards (FIPS) 12 features supported 100 field-programmable gate array (FPGA) 15 Java cryptography and 100 FIPS (Federal Information Processing Standards) 12 as JCE extension 99 FIPS 140-2 standard, Level 4 18, 38 keystore types 99 flash EPROM 14 provider 101 FPGA (field-programmable gate array) 15 IBMJCECCAKS RSA and 121 G RSA signature 124 GENCERT command (RACDCERT) 186 IBMJCECCARACFKS GSK_HW_CRYPTO variable 54 RSA and 123–124 GSK_SSL_HW_DETECT_MESSAGE variable 51 RSA signature 126–127 GSK_TRACE variable 52 IBMJSSE 103, 105 GSK_TRACE_FILE variable 52 tokens and 158 GSK01052W message 52 IBMPKCS11Impl cryptographic API (Java) 46 gskkyman utility 178–185 ICL data set 218 GSKSRVR command 51 ICL See Issued Certificate List ICSF administrator 24 keys and services, controlling 36 H ICSF callable services 11, 36, 47, 100, 163, 244 hardware cryptographic devices 120 activities reported to RMF 70 hardware cryptography 41, 65, 75 cryptographic functions 34 activity assessment 41–63 hardware cryptography, OMEGAMON on z/OS 80 applications/middlewares, exploiting 42 PKCS#11, provided by 162 assessing activity 79–89 predetermined set 73 benefits of 101, 154 SMF reports 67 features, setting up 106 ICSF Coprocessor Management panel 19

280 System z Cryptographic Services and z/OS PKI Services ICSF FMID 9 examples 121–151 ICSF keyword (RACDCERT) 117 features, setting up 106 ICSF panels 24 hardware keytool 120 token management 158, 173 hardware-based, benefits of 101 ICSF See Integrated Cryptographic Service Facility IBMJCECCAKS example 121 ICSF SERVICES section, RMF reports 83 IBMJCECCARACFKS example 123, 126 ICSF status display, OMEGAMON XE on z/OS 81 key management 98 ICSF Token Management 165 keys, exporting 132 ID field, Cryptographic Activity report 71 keystores 107–119 IKYSETUP REXX script 240–247 message hashing 131 IMPORT command (RACDCERT) 192 PKCS 94 import java.security.Key 134 providers 102–106 imprinting 16 providers, mapping 105 IMW_Admin WEBADM 227 RSA signature example 124 in-storage copy (CKDS) 67 security 92 Integrated Cryptographic Service Facility (ICSF) 34–38, SOAP examples 137–151 209 software keytools 120 audit trails 38 SSL for WebSphere Application Server, configuring component trace 56 151–154 instances running 38 symmetric key encryption 127 PKCS#11 and 155 TDES with CKDS example 128 RMF reports 69 in z/OS 99–102 workload balancing 66 See also IBMJCE z/OS hardware cryptography for Java 100 Java Cryptography Extension (JCE) 103 Integrated Cryptographic Service Facility (ICSF)) See also IBMJCE See also ICSF callable services Java Cryptography Extension via CCA See IBMJCECCA Interactive Problem Control System (IPCS) Java Development Kit (JDK) 92, 110 ICSF component trace 56 examples created using 91 System SSL component trace 55 IBM providers and 103 internal key token Java examples 124, 127, 137 DES 28 true random-number generation 130 PKA keys 31 Java Naming and Directory Interface (JNDI) 262 interoperability, CCA cryptographic API 21 Java Native Interface (JNI), z/OS PKI Services sample IPCS See Interactive Problem Control System scenario 266 IRR.DIGTCERT.LIST class (RACDCERT) 117 Java Secure Sockets Extension (JSSE) 105 IRR.DIGTCERT.LISTRING class (RACDCERT) 117 See also IBMJSSE Issued Certificate List (ICL) 211, 218 Java Server Faces (JSF) 262 java.security file 107 JCE (Java Cryptography Extension) 103 J See also IBMJCE J2EE (Java 2 Platform, Enterprise Edition) 260 JCECCA See IBMJCECCA Java JCECCAKS 110–113 implementation, z/OS PKI Services sample scenario See also IBMJCECCAKS 261 JCECCAKS keystore 99 SDKs, security providers 102 JCECCAKS See IBMJCECCAKS See also Java cryptography JCECCARACFK keystore 99 Java 2 Platform Standard Edition (JCE in J2SE) 99 JCECCARACFKS 116 Java 2 Platform, Enterprise Edition (J2EE) 260 See also IBMJCECCARACFKS Java applications 92 JCECCARACFKS keyrings 116 cryptographic algorithms 92 JCECCARACFKS See IBMJCECCARACFKS keyrings, RACF 119 JCEKS See Java Cryptographic Extension Keystore keyrings, using with 115 JCERACFKS keystore 114–116 SSL/TLS connections 105 best practices 119 Java Certification Path See CertPath JCERACFKS See IBMJCERACFKS Java Cryptographic Extension Keystore (JCEKS) JNDI (Java Naming and Directory Interface) 263 108–110 JNI (Java Native Interface), z/OS PKI Services sample Java Cryptographic Extension using CCA See IBMJCEC- scenario 266 CA JSF (Java Server Faces) 263 Java cryptography 91–154 JSSE (Java Secure Sockets Extension) 105 algorithms, types of 93–98 See also IBMJSSE architecture 99

Index 281 K KMMK (Key Management Master Key) 31 KEKs See key-encrypting keys key entry unit (KEU) 67 L key forms LDAP directory 209, 212 DES keys 27–30 address 217 external key tokens 28 libica 46 PKA keys 31–34 Linux on System z Key Generate Utility Program (KGUP) 11 hardware cryptography, assessing use of 58–61 Key Import service, PKA 34 hardware cryptography, collecting activity information key labels 60–61 DES 28 hardware cryptography, exploiting 42, 46, 58 generating automatically 117 hardware cryptography, utilization and measure- Key Management Master Key (KMMK) 31 ment 46 key pairs 96, 210, 259 LPAR 75 asymmetric keys 96, 108 PCIXCC card and 17 cryptographic calls 120 Linux on System z9 40 JCECCAKS 110 Linux on zSeries, System z9 software requirements 40 RACDCERT 114 LIST command (RACDCERT) 186, 192 RSA 118 LISTTOKEN command (RACDCERT) 188, 192 key tokens See tokens logical partition sharing 38 key wrapping 134 logical partitions (LPARs) 38, 58, 66 key-encrypting keys (KEKs) 24 Linux 75 ICSF callable services and 34 sharing 38 key forms 27, 29 LPARs See logical partitions PKA keys 31 KEY-GEN RATE field, Cryptographic Activity report 72 KEYMANAGEMENT key pair 100 M keypass 98 MAC 4, 8, 73 keyrings 102, 107–119 Crypto Hardware Activity report 39 certificates, connecting to 116 ICSF callable services reported to RMF 70 JCERACFKS 114 instructions 8 new, creating 115 MAC GENERATE/VERIFY SIZE fields, Cryptographic Ac- RACF 108, 115 tivity report 73 SAF 108 master keys 14, 31 keys 14 CEX2C 36 access control to 102 CEX2C card protection 18 CCA types of 24 control vectors 26 confidentiality of 101 DES key management and 24 control vectors 25 encrypting keys with 26 exporting from software to hardware keystores 132 logical partitions and 38 importing, DES 28 z/OS hardware cryptography 101 importing, PKA 31 MD5 algorithm 15 KEKs 24 ME (1024)/ME (2048) fields, Cryptographic Activity report managing 20–21, 31, 98, 101 72 managing, CCA callable services 22 MESSAGE AUTHENTICATION CODE See MAC master See master keys message digest, generating 4 size of 111 message security assist (MSA) 4–9 types of 24, 94, 190 extensions 4 types of, supported by CCA cryptographic API 24 ICSF callable services and 70 keystores 97–98, 101, 107–119 instructions 4, 10, 42, 49 characteristics of 120 messages exporting keys 132 encrypting, MSA DEA functions for 4 IBMJCE 97 hashing 131 RACF and System SSL differences 157 Miniboot 16 keytool utility 98, 109 modular exponentiation (ME) 39 hardware 120 Modulus Exponent (ME) IBMJCECCA support for 100 cryptographic accelerators 72 KeyUsage extension 216 Modulus Exponent (ME), cryptographic accelerators 72 keywords, RACDCERT command 117 MSA See message security assist KGUP (Key Generate Utility Program) 11

282 System z Cryptographic Services and z/OS PKI Services N CCF functions and 12 NOCRYPTO keyword 70 CEX2A and 39 creating TKDS 159 cryptographic workload panel 82 O hardware cryptography and 99, 102 object model, z/OS PKI Services sample scenario 262 PCICC option, private key storage 178 object protection key (OPK) 33 Rigoletto FPGA and 15 ObjectStore data set 218 SMF reports data 66 OCEP (Open Cryptographic Enhanced Plug-in) 252 z/OS cryptographic workload 39 OCSF API 43 z/OS PKI Services 217 OCSF See Open Cryptographic Services Facility Peripheral Component Interconnect - Extended Crypto- OCSP responder function 219 graphic Coprocessor (PCIXCC) 9 OCSP See Online Certificate Status Protocol DES key management 24 OCSPType keyword (z/OS PKI Services) 219 hardware cryptography, detecting 61 OMEGAMON XE on z/OS 43, 55, 79 See also PCIXCC card coprocessor support 80 Peripheral Component Interconnect Cryptographic Accel- GUI 81 erator (PCICA) 9, 13 hardware cryptography, assessing 79–89 Peripheral Component Interconnect Cryptographic Co- historical sampling 88 processor (PCICC) 9 ICSF status display 81 DES key management 24 online monitor 84 hardware cryptography, detecting 61 Service Call Performance panel 88 SMF reports 67 workload performance 82 See also PCICC card Online Certificate Status Protocol (OCSP) 208, 215, 219 PERMIT command 36 online devices, z90crypt device driver and 60 personal certificates 115 Open Cryptographic Enhanced Plug-in (OCEP) 252 CertPath not verified error 119 Open Cryptographic Services Facility (OCSF) 209, 252 generating with RACDCERT 114, 117 performance, z/OS PKI Services and 218 PIN (personal identification number) 73 operational keys PKCS#11 and 156 DES 27 PIN TRANSLATE/VERIFY RATE fields, Cryptographic PKA 31 Activity report 73 OPK (object protection key) 33 PKA Decrypt/PKA Encrypt services 74 options data set 36, 38 PKA keys Otello chip 15 forms of 31–34 Overview report 77 managing 30–34 SMF reports 67 PKA See public key algorithm P PKCS (Public Key Cryptography Standard) 103 parameter block 5 PKCS#11 128-bit chaining value 6 gskkyman panels 178–185 64-bit chaining value 6 objects defined by 156 chaining value field 8 RACF panels 171–178 initial hash value 7 tokens 157 Payment Card Industry (PCI) 117 PKCS#11 cryptography API 42, 46, 155–203 PCI (Payment Card Industry) 100, 117 benefits on z/OS 157 PCI Cryptographic Accelerator (PCICA) 13, 60, 67 infrastructure and setup 158–163 z/VSE and 58 programming example 194–203 PCI Interface Callable Service (CSFPCI), SMF reports RACDCERT commands, examples 185–194 67 TKDS and 159 PCI X 117 token administration 163–194 PCICA See PCI Cryptographic Accelerator tokens 158 PCICC card, PKA and 117 tokens, access to 161 PCICC keyword (RACDCERT) 117 pkcs12 file 109–112 PCICC option 174 PKCS12 format 132 PCI-X card 14–17 PKDS service, hardware keytool 120 PCIXCC card 14 PKI Administrator 217 CCA and 100 PKI exit 210 components of 14 C code implementation, sample scenario 267 secure module 15 PKI Services 205, 211 per-device count 60 certificate extensions, support for 216 performance

Index 283 daemon, R_PKIServ callable services 219 data set 120 PKI Services Trust Policy (PKITP) 220 keypairs, generating 111 PKISERV application, z/OS PKI Services 217 PublicUser 227 PKITP (PKI Services Trust Policy) 220 pkitp API 218 PKIX architectural model 209 Q plug-in QUERY VIRTUAL CRYPTO command 63 example, z/OS PKI Services sample scenario 266 framework, z/OS PKI Services sample scenario 265 R portability, CCA cryptographic API 21 R_PKISERV API 267 POST (power-on self-test) 16 R_PKIServ callable services 208, 211 power-on self-test (POST) 16 RACDCERT commands 119, 157 PowerPC microprocessor 14–16 access to 114 interface 15 certificate requests, generating 115 POST and 17 examples 185–194 private keys 30, 107, 156, 212, 222 facility classes 116 asymmetric key encryption 96 functions 171 asymmetric key pair 108 JCERACFKS provider 114 JCECCAKS 110 keywords 117–119 keystores, listing 110 PKCS#11 and 171–178 protecting with passwords 108 z/OS PKI Services and 208 See also public/private keys RACDCERT ID 117 program status word (PSW) 4 RACF commands 36, 173, 239 providers 102 RACF keyring 108, 116, 119 algorithms supported 105 RACF profile 47, 159 list of IBM 102 RACFInputStream ksStream 123 mapping to algorithms 105 RACLIST command (SETROPTS) 36, 47 selecting 103 RAD See Rational Application Developer pseudorandom numbers 5 random numbers, generating 130 PSW (program status word) 4 RATE column, Crypto Hardware Activity report 75 public byte 122 Rational Application Developer (RAD) 121, 137 Public Cryptography Key Standards (PKCS), Java cryp- SOAP and 137 tography 94 Rational development tools 263 public key 94, 96, 156 RDEFINE command 36 encryption 54, 96 Redbooks Web site 275 hardware support 51 Contact us xi public key algorithm (PKA) 12, 30 RemoveExpiredCerts keyword (pkiserv.conf) 218 CEX2C card support for 18 Resource Measurement Facility (RMF) 43, 65, 68 See also PKA keys data collection infrastructure 69 Public Key Cryptography Standard #11 See PKCS#11 hardware cryptography activity, assessing 79–89 cryptography API ICSF callable services reported to 70 Public Key Cryptography Standard (PKCS) 103 measuring hardware cryptography activity on z/OS Public Key Dataset (PKDS) 33, 35 65–78 hwkeytool 101 RETAINED service, hardware keytool 120 JCECCAKS 110 Rigoletto chip 15 JCECCARACFKS 116 Rivest-Shamir-Adleman See RSA OMEGAMON XE on z/OS 80 RMF Crypto Hardware Activity report 74 RACDCERT keywords 117 RMF Monitor 1 70 SMF reports 67 RMF Processor Activity record, SMF reports 67 Public Key Infrastructure (PKI) 97, 208–214 RMF reports 69–78 certificate life cycle 208 Crypto Hardware Activity 71–75 See also z/OS PKI Services Overview 77 public keys 18, 31, 107, 208 SHA-1 requests 83 algorithm 185 Workload Activity 75–77 exporting to Business Partners 115, 119 RMF See Resource Measurement Facility Object Detail ICSF panel 190 RMF Spreadsheet Reporter for Windows 68 sizes 185 RMF Workload Activity report 39 Token Details ICSF panel 169 RSA acceleration 44 See also public/private keys RSA algorithm 15, 18, 97 public/private keys 108 CEX2A card and 18

284 System z Cryptographic Services and z/OS PKI Services RSA encryption 121–124 See also SOAP examples RSA keys 15, 69, 134, 156, 243 Situation Editor workspace, OMEGAMON XE on z/OS format 72 80 generating, Crypto Hardware Activity report 71 SMF generation requests 74 Common Address Space Work type 30 67 pair 31 ICSF record type 82 66 public key token 34 records 217 RSA operations 72, 86 reports, Common Address Space Work 67 RSA private keys reports, RMF and 69 external key token 33 reports, RMF Processor Activity 67 forms of 32 Workload Activity type 72 68 internal key token 31 SMF records RSA signature 44, 94, 124 ICSF audit trails 38 IBMJCECCAKS 124 SMF reports 66–68 rule array, CCA cryptographic API 21 SMK (Signature Master Key) 31 SO See security officer SO.token-name resource 157 S SOAP (Simple Object Access Protocol) 137 SAF (System Authorization Facility) 108 See also SOAP examples SAF database 102 SOAP examples 137 sample JCL 159, 239 Java cryptography 137–151 secret keys 11, 39, 95 servers, setting up 137 key objects and 156 web service project, creating 138–151 secure keys 20 software cryptography, hardware cryptography and 100 asymmetric encryption 19 software keys 132 high security environment 39 private key storage as 178 Secure Sockets Layer (SSL) 72, 205 software keytools, Java cryptography 120 security software requirements, System z 40 CEX2 card 18 Special Secure Mode (SSM) 164 CEX2C and 39 specification exception 4 CPACF and 11 SSL (Secure Sockets Layer) 72 cryptography providers on z/OS 102 SSL applications 13 DES key management 24–30 SSL Daemon (SSLD) 45 J2EE 263 SSL for VSE API 45 Java cryptography 92 SSL for WebSphere Application Server, configuring key type control vectors and 26 151–154 master keys 15 SSL handshake 49 Miniboot and 17 SSL Started Task 50–51 SAF keyrings 108 SSL/TLS protocol 18, 43 tamper-detection circuitry 15 SSLD (SSL Daemon) 45 z/OS 258 SSM (Special Secure Mode) 164 security officer (SO) 36, 38, 156 STDERR file 51 self-signed certificates 101, 108, 183 Struts 262 keytool 120 symmetric algorithms sequence number 173 IBMJCECCA support for 100 serial number 168 symmetric key encryption 95, 129 Service Call Performance panel, OMEGAMON XE on DES keys, CKDS and 127 z/OS 88 TDES with CKDS 128 servlet layer, z/OS PKI Services sample scenario 262 symmetric-keys master key (SYM-MK) 15 SETROPTS command 36 DES key management 24 SHA-1 74, 82 ICSF and 36 algorithm 4, 15, 18 SYM-MK See symmetric-keys master key ICSF callable services and 70 sysplex, hardware cryptography 40 measuring CPACF activity 82 SYSPLEXTKDS option 160 SHA-256 73–74, 82 System Authorization Facility (SAF) 108, 163 algorithm 4 System Management Facility (SMF) 43 ICSF callable services and 70 System SSL 43, 49–56, 157 sharing logical partition, individual master keys 38 API 45 Signature Master Key (SMK) 31 calls, tracing 52–55 Simple Certificate Enrollment Protocol (SCEP) 210, 224 component 47 Simple Object Access Protocol (SOAP) 137

Index 285 component trace 52 TOTAL UTIL% field, Cryptographic Activity report 71 cryptographic service provider example 43 Transport Layer Security (TLS) 72 environment variables 50 Web services 151 example 49 Triple-DES (TDES) hardware cryptography, measurement data 56 hybid encryption approach 134 infrastructure 49 ICSF callable services, activities reported by 70 key database 157 Trust Policy Plug-In 209 performance, z/OS PKI Services and 218 Trusted Block Create callable service 67 run-time environment 50 trusted certificate entries 107 software 49 Trusted Key Entry (TKE) 24, 36 Task element 51 SMF reports 67 tokens and 158 TYPE fields, Cryptographic Activity report 71 trace 52 Version 3 53 System SSL API 43 U System z UDX (user-defined extension) 71 cryptography infrastructure 3–40 UNIX System Services 108, 116 hardware cryptography See hardware cryptography environment, running scripts in 108 MSA and 4–9 UNIX, configuring for z/OS PKI Services 247–252 software requirements 40 URI format, distribution point 220 See also z9 server user IDs System z9 35 ICSF task 35 CCA cryptographic API calls 35 UID and GID values 242 CEX2C 40 USER.token-name resource 157 SHA-1 82 user-defined extension (UDX) 71 System z9 Business Class See z9 server V T Velocity 262 Take Action workspace, OMEGAMON XE on z/OS 80 virtual machine 62 tamper detection 15 VM guest 60 TDEA algorithm 6 machine directory 61 TDES algorithm 18 VSAM callable service parameters 23 alternate indexes 218 TDES key 134 data set 33, 35, 157 TDES See Triple-DES data set, See also Public Key Dataset TDES with CKDS, symmetric key encryption 128 database 211 TEMPORARY CERTIFICATE label 186 VSE Security Server 58 Tivoli Enterprise Monitoring Server 80 VSE/ESA V2.7 40 Tivoli Enterprise Portal Server 80 Tivoli OMEGAMON XE See OMEGAMON XE on z/OS W TKDS See Token Key Data Set Web services TKDSN option 160 creating 142 TLS See Transport Layer Security EJB methods 264 Token Key and Certificate List panel 183 TLS and 151 Token Key and Certificate Menu panel 184 WebSphere Application Server 137 Token Key Data Set (TKDS) 158–159 Version 6.1 121, 151, 261 certificate labels 173 See also SSL for WebSphere Application Server PKCS#11 and 157, 159 WITHLABEL parameter (RACDCERT) 192 token management callable services 163 WLM (Workload Manager) 66 token names 158, 165 WLM report 76 tokens 35 WLMGL report 76 adding 185 Workload Activity report 68, 75–77 external 28 RMF post-processor 70 external, DES keys 28 workload balancing 66 managing, in z/OS 157 Workload Manager (WLM) 66 PKCS#11 and 158 WSDL file 140, 142 PKCS#11 and, token access 161 VSAM data sets 35 TOTAL EXEC TIME field, activity report 71 Z TOTAL RATE field, activity reports 72 z/Architecture 4

286 System z Cryptographic Services and z/OS PKI Services z/OS 120 z/VSE hardware cryptography algorithms supported 105 assessing use of 58 cryptographic services, querying 51 exploiting 42–43 cryptographic workload on, monitoring 39 infrastructure 45 DES key management 24 utilization and measurement 45 Java cryptography in 99–102 z800/z890 platforms 35 Java cryptography, providers 102–106 z890 servers, coprocessors, evolution of 100 JCECCA hardware cryptography on 104 z9 BC server 10 key storage 28 z9 server 10 management facility 43 CEX2 features, support for 18 RACF cryptographic resources, detecting use of CPs, connection to 18 47–49 z900/z990 platforms 35 RMF, measuring hardware cryptography activity z90crypt device driver 46, 59 65–78 status of 59 security infrastructure 258 z990 servers, coprocessors, evolution of 100 System SSL See System SSL zcrypt device driver 46 z/OS hardware cryptography zSeries 890 mainframe, successor to 10 assessing use of 47–57 exploiting 42–46 messages on use of 51 switching to software cryptography 52 utilization and measurement 43 z/OS PKI Services 207–256, 259 availability 213 certificate extensions 216 deploying 225–255 evolution of 214–225 home page, accessing 255 IBM HTTP servers 225–240 IKYSETUP REXX 240–247 J2EE front end 260 object representations 262 performance enhancements 217 sample scenario 257–271 scalability 213 starting/stopping 255 structure 209–212 UNIX configuration 247–252 versions, enhancements to 214–225 Web page interface 210 z/OS V1.4, enhancements to PKI services 214 z/OS V1.5, enhancements to PKI Services 215–218 z/OS V1.6 40 z/OS V1.7, enhancements to PKI Services 219–222 z/OS V1.9 257 System SSL 52 z/OS V1.9, enhancements to PKI Services 225 z/OS.e V1.6/V1.7 40 z/VM CP QUERY CRYPTO command 63 hardware cryptography, configuring 61–63 hardware cryptography, physical devices 63 QUERY VIRTUAL CRYPTO command 63 versions 40 z/VM CP planning 61 QUERY CRYPTO command 63 z/VSE RSA acceleration 44 Version 3.1 40

Index 287

288 System z Cryptographic Services and z/OS PKI Services

System z Cryptographic Services and z/OS PKI Services

(0.5” spine) 0.475”<->0.873” 250 <-> 459 pages

System z Cryptographic Services and z/OS PKI Services

Back cover ® System z Cryptographic

Services and z/OS PKI Services ®

Hardware This IBM Redbook describes System z cryptographic services and technologies. This document also discusses INTERNATIONAL cryptography TECHNICAL monitoring the cryptographic support available for Java and J2EE applications and the new support introduced in z/OS V1.9 SUPPORT for PKCS#11. We briefly describe the new PKI Services ORGANIZATION PKCS#11 support on enhancement introduced with z/OS V1.9. Finally we z/OS provide a sample scenario of how an installation can use this technology, and we explain how to download the Java cryptography sample. BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization. Experts from IBM, Customers and Partners from around the world create timely technical information based on realistic scenarios. Specific recommendations are provided to help you implement IT solutions more effectively in your environment.

For more information: ibm.com/redbooks

SG24-7470-00 ISBN 0738485411