System z Cryptographic Services and z/OS PKI Services · ibm.com/redbooks Front cover System z Cryptographic Services and z/OS PKI Services Guillaume Hoareau Nikhil V Kapre MuHyun

ibm.com/redbooks

Front cover

System z Cryptographic Services and z/OS PKI Services

Guillaume HoareauNikhil V Kapre

MuHyun KimGerard Laumay

Joel PorterieVicente Ranieri, Jr.Dominique Richard

Daniel L. Turkenkopf

Hardware cryptography monitoring

PKCS#11 support on z/OS

Java cryptography

Patrick KappelerJonathan BarneyJean Marc DareesPekka HanninenRobert Herman

http://www.redbooks.ibm.com/ http://www.redbooks.ibm.com/

International Technical Support Organization

System z Cryptographic Services and z/OS PKI Services

May 2008

SG24-7470-00

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 ScheduleContract with IBM Corp.

First Edition (May 2008)

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

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

Contents

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viiTrademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixThe team that wrote this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixBecome a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiComments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

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

Chapter 1. System z cryptography infrastructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.1 Message-security assist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.2 Cryptographic hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

1.2.1 CP Assist for Cryptographic Functions (CPACF) . . . . . . . . . . . . . . . . . . . . . . . . . 101.2.2 Cryptographic Coprocessor Feature (CCF) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.2.3 PCI Cryptographic Accelerator (PCICA) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131.2.4 PCI-X Cryptographic Coprocessor (PCIXCC). . . . . . . . . . . . . . . . . . . . . . . . . . . . 141.2.5 Crypto Express 2 Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171.2.6 Comparison of CPACF, CEX2C, and CEX2A. . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

1.3 IBM Common Cryptographic Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201.3.1 Rationale for the IBM CCA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201.3.2 CCA callable services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211.3.3 DES key management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241.3.4 PKA key management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

1.4 ICSF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341.4.1 Audit trails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

1.5 Logical partitioning and System z hardware cryptography exploitation. . . . . . . . . . . . . 381.6 Monitoring the cryptographic workload on z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391.7 Sysplex and System z hardware cryptography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401.8 Software requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Chapter 2. Hardware cryptography activity assessment on System z . . . . . . . . . . . . 412.1 What is exploiting the System z hardware cryptography?. . . . . . . . . . . . . . . . . . . . . . . 42

2.1.1 Hardware cryptography exploitation on z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422.1.2 Hardware cryptography exploitation in Linux on System z . . . . . . . . . . . . . . . . . . 46

2.2 Assessing the use of hardware cryptography on z/OS . . . . . . . . . . . . . . . . . . . . . . . . . 472.2.1 Detecting the use of RACF-protected cryptographic resources . . . . . . . . . . . . . . 472.2.2 z/OS System SSL example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492.2.3 The ICSF component trace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

2.3 Assessing the use of hardware cryptography on z/VSE . . . . . . . . . . . . . . . . . . . . . . . . 582.4 Assessing the use of hardware cryptography on Linux on System z . . . . . . . . . . . . . . 58

2.4.1 Status of the z90crypt device driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592.4.2 Collecting information about hardware cryptography activity . . . . . . . . . . . . . . . . 602.4.3 Programs that invoke hardware cryptography . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

2.5 Setting up hardware cryptography configuration of z/VM . . . . . . . . . . . . . . . . . . . . . . . 612.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 . . . . . . . . . 653.1 Overview of ICSF cryptographic workload balancing . . . . . . . . . . . . . . . . . . . . . . . . . . 663.2 SMF reporting of hardware cryptography activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663.3 Using RMF to measure the z/OS hardware cryptography activity. . . . . . . . . . . . . . . . . 68

3.3.1 RMF data collection infrastructure for hardware cryptography . . . . . . . . . . . . . . . 693.4 RMF post-processor reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

3.4.1 Crypto Hardware Activity RMF report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713.4.2 Crypto Hardware Activity report example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743.4.3 Crypto Hardware Activity report without local activity . . . . . . . . . . . . . . . . . . . . . . 753.4.4 Workload Activity report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753.4.5 Overview report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Chapter 4. Assessing activity with OMEGAMON XE on z/OS and RMF. . . . . . . . . . . . 794.1 Tivoli OMEGAMON XE on z/OS - Cryptographic coprocessor support . . . . . . . . . . . . 804.2 OMEGAMON XE on z/OS graphical interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 814.3 Measuring activity with RMF and OMEGAMON XE on z/OS . . . . . . . . . . . . . . . . . . . . 82

4.3.1 SHA-1 activity (CPACF activity) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824.3.2 CEX2C activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854.3.3 CEX2A activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

4.4 Using the OMEGAMON XE on z/OS Service Call Performance workspace. . . . . . . . . 88

Chapter 5. Java cryptography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 915.1 Java cryptography. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

5.1.1 Cryptography overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 925.1.2 Types of encryption algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 955.1.3 Key-management challenge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985.1.4 Java cryptography in z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

5.2 Cryptography providers on z/OS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1025.2.1 How to select a provider (registering a provider in the java.security file) . . . . . . 1035.2.2 JCE - Java Cryptography Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1035.2.3 JCECCA - JCE using CCA hardware cryptographic devices on z/OS . . . . . . . . 1045.2.4 CertPath - Certificate generation and path validation . . . . . . . . . . . . . . . . . . . . . 1045.2.5 JSSE - Java Secure Sockets Extension (SSL and TLS). . . . . . . . . . . . . . . . . . . 1055.2.6 Map the providers and algorithms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

5.3 Setting up hardware cryptographic features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1065.3.1 Policy files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

5.4 Keystore and SAF digital certificates (keyrings) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1075.4.1 JCEKS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1085.4.2 JCECCAKS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1105.4.3 JCERACFKS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1145.4.4 JCECCARACFKS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

5.5 Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1205.5.1 Software keytool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1205.5.2 Hardware keytool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1205.5.3 Different characteristics of keystores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

5.6 Java examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1215.6.1 RSA encryption and decryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1215.6.2 RSA signature. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1245.6.3 Symmetric key encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1275.6.4 Generating a true random number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1305.6.5 Hashing a message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1315.6.6 Exporting keys from software to hardware keystores . . . . . . . . . . . . . . . . . . . . . 1325.6.7 Hybrid encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

iv System z Cryptographic Services and z/OS PKI Services

5.7 SOAP examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1375.8 Configuring SLL for WebSphere Application Server hardware cryptography . . . . . . . 151

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

6.1.1 PKCS#11 concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1566.1.2 Benefits of PKCS#11 on z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1576.1.3 Mapping PKCS#11 concepts to z/OS cryptographic technology . . . . . . . . . . . . 157

6.2 z/OS PKCS#11 infrastructure and setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1586.2.1 Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1586.2.2 Token Key Data Set (TKDS). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1596.2.3 Controlling access to tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1616.2.4 ICSF services provided by z/OS PKCS#11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

6.3 z/OS PKCS#11 token administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1636.3.1 ICSF panels, token browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1636.3.2 RACF panels and RACDCERT commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1716.3.3 gskkyman panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1786.3.4 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

6.4 z/OS PKCS#11 programming example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

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

Chapter 7. z/OS PKI Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2077.1 Public Key Infrastructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

7.1.1 Certificate life cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2087.1.2 z/OS PKI Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2087.1.3 z/OS PKI Services structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2097.1.4 Scalability and availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

7.2 A product in constant evolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2147.2.1 z/OS V1.4 enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2147.2.2 z/OS V1.5 enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2157.2.3 z/OS V1.7 enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2197.2.4 z/OS V1.8 enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2227.2.5 z/OS V1.9 enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

7.3 z/OS R9 PKI Services deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2257.3.1 IBM HTTP servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2257.3.2 IKYSETUP REXX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2407.3.3 UNIX environment configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2477.3.4 OCSF and OCEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2527.3.5 LDAP directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2537.3.6 VSAM ObjectStore and ICL data sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2537.3.7 Starting and stopping PKI Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

7.4 Accessing our z/OS PKI Services Home page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

Chapter 8. Sample scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2578.1 Overall architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

8.1.1 Structure of sample scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2588.2 ITSO implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

8.2.1 Java implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2618.2.2 PKI Services core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2658.2.3 C code implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

Contents v

Appendix A. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275How to get Redbooks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275Help 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.

COPYRIGHT LICENSE:

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.

Copyright IBM Corp. 2008. All rights reserved. vii

Trademarks

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) AIXCICSDB2developerWorksEnterprise Systems

Architecture/370eServerFICONIBMMVSOMEGAMON

OS/390Parallel SysplexPowerPCRACFRationalRedbooksREXXRMFS/390System zSystem z9System/360

System/370TivoliVSE/ESAVTAMWebSpherez/Architecturez/OSz/VMz/VSEz9zSeries

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

http://www.ibm.com/legal/copytrade.shtml

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 Universitys 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 BariRichard ConwayRobert HaimowitzInternational Technical Support Organization, Poughkeepsie Center

Wai ChoiJohn DaykaFrank DeGilioAnne EmerickTerry GreenJim SweenyIBM Poughkeepsie

Alyson ComerIBM 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 OrganizationDept. HYTD Mail Station P0992455 South RoadPoughkeepsie, NY 12601-5400

Preface xi

http://www.redbooks.ibm.com/residencies.htmlhttp://www.redbooks.ibm.com/residencies.htmlhttp://www.redbooks.ibm.com/http://www.redbooks.ibm.com/http://www.redbooks.ibm.com/contacts.html

xii System z Cryptographic Services and z/OS PKI Services

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

Part 1

Copyright IBM Corp. 2008. All rights reserved. 1

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 systems 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.

1

Copyright IBM Corp. 2008. All rights reserved. 3

1.1 Message-security assist

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.


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.

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

R2R1op code

310 16 24 28

Function code

Function name

Function description Part of Parameter block for the function

Data block size

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

N/A

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

DEA Key (8 bytes) 8

Chapter 1. System z cryptography infrastructure 5

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

2 KM-TDEA-128 Encipher or decipher the 8 byte blocks in operand 2 using the TDEA algorithm with the two keys in the parameter block (key 3 = key 1). The operation is performed without chaining.

DEA Key 1 (8)Key 2 (8)

8

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

DEA Key 1 (8)Key 2 (8)Key 3 (8)

8

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

Ext 1 Key (16) 16

Function code

Function name


Data block size

Function code

Function name


Data block size

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

N/A

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

DEA Chaining value (8)Key (8)

8

2 KMC-TDEA-128

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

DEA Chaining value (8)Key 1 (8)Key 2 (8)

8

3 KMC-TDEA-192

Encipher or decipher the 8-byte blocks in operand 2 using the TDEA algorithm with the three keys and the 64-bit chaining value in the parameter block. The operation is performed with chaining.

DEA Chaining value (8)Key 1 (8)Key 2 (8)Key 3 (8)

8

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

Ext 1 Chaining value (16) Key (16)

16


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

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

67 KMC-PRNG Pseudorandom number generator. The algorithm is based on TDES using three 64-bit cryptographic keys and a 64-bit chaining value.

Ext 1 Chaining value (8)Key 1 (8)Key 2 (8)Key 3 (8)

8

Function code

Function name


Data block size

Function code

Function name


Data block size

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

N/A

1 KIMD-SHA-1 A 20-byte intermediate message digest is generated for the 64-byte (512-bit) message blocks in operand 2 using the SHA-1 algorithm with the 20-byte (160-bit) initial hash value in the parameter block. The generated intermediate message digest is stored in the parameter block.

Basic Initial hash value:H0=x67452301H1=xEFCDAB89H2=x98BADCFEH3=x10325476H4=C3D2E1F0

64

2 KIMD-SHA-256

A 32-byte intermediate message digest is generated for the 64-byte (512-bit) message blocks in operand 2 using the SHA-256 algorithm with the 32-byte (256-bit) initial hash value in the parameter block. The generated intermediate message digest is stored in the parameter block.

Ext 1 Initial hash value:H0=x6A09E667H1=xBB67AE85H2=x3C6EF372H3=xA54FF53AH4=x510E527FH5=x9B05688CH6=x1F83D9ABH7=x5BE0CD19

64

Function code

Function name


Data block size

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

N/A


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

1 KLMD-SHA-1 If the length in bytes of the message in operand 2 is greater than or equal to 64, an intermediate message digest is generated for each 64-byte (512-bit) message block using the SHA-1 algorithm with the 20-byte (160-bit) initial hash value in the parameter block. The generated intermediate message digest is stored in the initial hash value field of the parameter block. 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.

Basic Initial hash value:H0=x67452301H1=xEFCDAB89H2=x98BADCFEH3=x10325476H4=C3D2E1F0Length of total message in bits

64

2 KLMD-SHA-256

The description of KLMD-SHA-256 is the same as the description of KLMD-SHA-1 if you replace SHA-1 with SHA-256 and 20 with 32.

Ext 1 Initial hash value:H0=x6A09E667H1=xBB67AE85H2=x3C6EF372H3=xA54FF53AH4=x510E527FH5=x9B05688CH6=x1F83D9ABH7=x5BE0CD19Length of total message in bits

64

Function code

Function name


Data block size

Function code

Function name


Data block size

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

N/A

1 KMAC-DEA The MAC code for the 8-byte message blocks (M1, M2 , . ,, Mn) in operand 2 is computed 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.

DEA Chaining value(8)Key (8)

8

2 KMAC-TDEA-128

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

DEA Chaining value(8)Key1 (8)Key 2 (8)

8


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

3 KMAC-TDEA-192

The MAC code for the 8-byte message blocks in operand 2 is computed using the TDEA algorithm with the three 64-bit cryptographic keys and the 64-bit chaining value in the parameter block. The MAC is stored in the chaining value field of the parameter block.

DEA Chaining value(8)Key 1 (8)Key 2 (8)Key 3 (8)

8

Function code

Function name


Data block size

Server CPACF CCF(feature0800)

PCICC(feature0861)

PCICA(feature0862)

PCIXCC(feature0868)

CEX2C(feature0863)

CEX2A(feature0863)

9672 G5,G6 No Yes Yes No No No No

z800, z900 No Yes Yes(requires CCF)

Yes(requiresCCF)

No No No

z890, z990 Yes(requires z/OS 1.4 or later)

No No Yes(requires feature 3863)

Yes(requires feature 3863 and ICSF FMID HCR770A or later)

Yes(requires feature 3863 and z/OS 1.4 or later with ICSF FMID HCR7720 or later)

No


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.

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

z9 109z9 BCz9 EC

Yes(requires z/OS 1.6 or later)

No No No No Yes(requires feature 3863 and z/OS 1.6 or later with ICSF FMID HCR7730 or later)

Yes(requires feature 3863 and z/OS 1.6 or later with ICSF FMID HCR7730 or later)

Server CPACF CCF(feature0800)

PCICC(feature0861)

PCICA(feature0862)

PCIXCC(feature0868)

CEX2C(feature0863)

CEX2A(feature0863)

I/O Cage

CEX2

PCIXCC

PCICA

STICEC Cage

MBA

Memory

...CPACFCPACF CPACF

CP CP CP ...


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.

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.

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.


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.

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.

Input DataBuffer

Output DataBuffer

PRNGAsynchronous1024-bitmodular exponentiation

SHA-1 PIN DES

Master key arrays (1 per LPAR)

CP


Figure 1-4 shows a z/800 or z/900 server with two CCFs.

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

CEC Cage

MBA

...CP1 CP2 CP3CP0

CCF1CCF0

Memory

PCICA

PCICC

I/O Cage

STI


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 overviewThe PCIXCC hardware is implemented as an adapter card for a PCI-X bus. Figure 1-5 shows the components that are on the card.

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,

FlashEPROM 3

Otello cryptographic processor 5

Battery-backed RAM 4

Rigoletto FPGA7

AVR securitymicrocontroller

9Random numbergenerator

6

Real-timeclock 8

PowerPC 405GPr microprocessor 1

Tamper-detectioncircuitry 10

SDRAM2

Securecryptomodule

PCI-X bus edge connector

Interconnect

PCI-X to PCI-X bridge

PCI-X base card

Powerdc/dc

Batteries


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


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 overviewThe software that runs on the PowerPC 405GPr microprocessor is divided into four separate components as shown in Figure 1-6.

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.

Digital certificate

Segment 3 (in flash, replaceable)

CCA application

Digital certificate


Operating system (Linux)and device drivers

Digital certificate


POST 1 Miniboot 1

Segment 0 (in ROM, permanent)

POST 0 Miniboot 0


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.

Figure 1-7 Layout of a CEX2 feature

PCIXCC card

PCI-Xbridge

PCIXCC card

Batte

ry

PCI-Xbridge

PCI-X (64-bit, 133 MHz)PCI-Xbridge

STI1/.5 GBpseach dir

STI1/.5 GBpseach dir

STIinterface1 GBps

STI = Self-timed interface

Bat

tery

Batte

ryBa

ttery


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.


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 ********************************

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,

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

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 encryption with clear key

X

Highest performance for asymmetric encryption with secure key

X

Physically imbedded on each CP X


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.)

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).

Function or attribute CPACF CEX2C CEX2A


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


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

Service pseudonym Service name


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 installations 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.


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 separationAn 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.


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

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.

Key type Control vector (in hex)

CIPHER64-bit128-bit

00 03 71 00 03 00 00 00 00 00 00 00 00 00 00 0000 03 71 00 03 41 00 00 00 03 71 00 03 21 00 00

DATA64-bit128-bit

00 00 7D 00 03 00 00 00 00 00 00 00 00 00 00 0000 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

DECIPHER64-bit128-bit

00 03 50 00 03 00 00 00 00 00 00 00 00 00 00 00 00 03 50 00 03 41 00 00 00 03 50 00 03 21 00 00

ENCIPHER64-bit128-bit

00 03 60 00 03 00 00 00 00 00 00 00 00 00 00 0000 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

Key type Attributes


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.

Figure 1-8 Using the master key to encrypt a key

MAC64-bit128-bit

00 05 4D 00 03 00 00 00 00 00 00 00 00 00 00 0000 05 4D 00 03 41 00 00 00 05 4D 00 03 21 00 00

MACVER64-bit128-bit

00 05 44 00 03 00 00 00 00 00 00 00 00 00 00 00 00 05 44 00 03 41 00 00 00 05 44 00 03 21 00 00

Key type Control vector (in hex)

Master key variant: IMPORTER keys

Master key variant: DATA keys

Master key variant:MAC keys

Master key

Control vector:IMPORTER keys

Control vector:DATA keys

Control vector:MAC keys

DES encryption algorithm

IMPORTER keyto be encrypted

DES encryption algorithm

Documents

System z Cryptographic Services and z/OS PKI Services · ibm.com/redbooks Front cover System z Cryptographic Services and z/OS PKI Services Guillaume Hoareau Nikhil V Kapre MuHyun