Front cover

ABCs of z/OS System

Programming
Volume 6
Security on z/OS, RACF, and LDAP

Kerberos and PKI

Cryptography and EIM

Paul Rogers
Rui Feio
Oerjan Lundgren
Rita Pleus
Karan Singh

ibm.com/redbooks
International Technical Support Organization

ABCs of z/OS System Programming Volume 6

August 2008

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

First Edition (August 2008)

This edition applies to Version 1, Release 7 of of z/OS (5694-A01), Version 1 Release 7 of z/OS.e (5655-G52),
and to all subsequent releases and modifications until otherwise indicated in new editions.

© 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

Chapter 1. Introduction to z/OS security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.1 z/OS basic security facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2 z/OS Security Server Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3 Integrated Security Services components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.4 Cryptographic Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Chapter 2. z/OS Security Server RACF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.1 What is RACF? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.2 RACF functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.3 RACF ISPF panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.4 RACF profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.5 RACF commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.6 User authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.7 Resource managers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.8 System Authorization Facility (SAF) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.9 RACF classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.10 Security administration with RACF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.11 RACF user identification and verification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.12 RACF user profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
2.13 RACF user attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.14 RACF user segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
2.15 RACF user ID and password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
2.16 Adding a new user to RACF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
2.17 Reset a user password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2.18 Alter a user ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
2.19 Change a user’s password interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
2.20 Delete a user ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
2.21 User related RACF commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
2.22 RACF groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
2.23 RACF group structure example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
2.24 RACF group related commands: Add a group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
2.25 RACF group related commands: Alter a group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
2.26 RACF group related commands: Delete a group . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
2.27 Connect a user to a group. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
2.28 Remove a user from a group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
2.29 Data sets and general resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
2.30 Data sets and general resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
2.31 Data set profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
2.32 Defining data set profiles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
2.33 Data set profile access list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
2.34 Add a data set profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

© Copyright IBM Corp. 2008. All rights reserved. iii

 2.35 Alter a data set profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
2.36 Search RACF database using a mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
2.37 Data set related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
2.38 Data set related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
2.39 General resources related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
2.40 General resources related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
2.41 General resources related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
2.42 SET RACF system options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
2.43 Statistic related options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
2.44 Password related options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
2.45 Data set related options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
2.46 Class related options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
2.47 Authorization checking related options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
2.48 Tape related options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
2.49 RVARYPW and other options for initial setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
2.50 Auditor related options(1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
2.51 Auditor related options(2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
2.52 SETROPTS: Display options (LIST) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
2.53 RACF monitoring. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
2.54 RACF monitoring. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
2.55 RACF monitoring. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
2.56 RACF auditing tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
2.57 RACF auditing - IRRADU00 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
2.58 RACF auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
2.59 RACF auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
2.60 RACF auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
2.61 RACF auditing - DSMON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
2.62 RACF auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
2.63 RACF auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
2.64 RACF auditing - IRRDBU00 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Chapter 3. Digital certificates and PKI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

3.1 The authentication problem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
3.2 Overview of digital certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
3.3 The public key cryptography trust model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
3.4 Elements of PKI in z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
3.5 The PKIX standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
3.6 The RSA public key cryptography standards (PKCS) . . . . . . . . . . . . . . . . . . . . . . . . . 124
3.7 The PKCS-10 certificate request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
3.8 The X.509 certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
3.9 X.509 certificate revocation list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
3.10 X.509 V3 certificate: Standard extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
3.11 Contents of the digital certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
3.12 Browser certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
3.13 Server certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
3.14 z/OS PKI services architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
3.15 Get PKI up and running. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
3.16 Setting up RACF environment for PKI prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . 137
3.17 Add RACF groups for PKI services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
3.18 RACF for PKI Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
3.19 Prepare and configure the UNIX System Services environment. . . . . . . . . . . . . . . . 160
3.20 Setting up the Web servers for PKI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
3.21 Setting up the LDAP server for PKI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

iv ABCs of z/OS System Programming Volume 6

3.22 Setting up the PKI Services task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
3.23 Configure OCSF and OCEP to work with PKI Services . . . . . . . . . . . . . . . . . . . . . . 177
3.24 Configure the PKI Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
3.25 PKI exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
3.26 Test for scenario one . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
3.27 Starting and stopping PKI Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Chapter 4. Kerberos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

4.1 Introduction to Kerberos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
4.2 Kerberos terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
4.3 Kerberos protocol overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
4.4 Get a ticket-granting ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
4.5 Request a service ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
4.6 Authenticate to target server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
4.7 Kerberos inter-realm trust relationship . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
4.8 Some assumptions to Kerberos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
4.9 Implementing Network Authentication Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
4.10 Setting up the Kerberos environment variable files. . . . . . . . . . . . . . . . . . . . . . . . . . 211
4.11 Setting up HFS for Kerberos cache files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
4.12 Kerberos integrated with RACF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
4.13 Define Kerberos local principals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
4.14 Define Kerberos foreign principals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
4.15 Kerberos user commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
4.16 Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Chapter 5. Cryptographic Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

5.1 Introduction to cryptography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
5.2 Cryptographic capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
5.3 Symmetric and asymmetric encryption algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
5.4 Symmetric encryption algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
5.5 Asymmetric encryption algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
5.6 Use of cryptosystems: Data privacy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
5.7 Use of cryptosystems: Data integrity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
5.8 Use of cryptosystems: Digital signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
5.9 IBM Common Cryptographic Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
5.10 IBM System z9: Cryptographic overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
5.11 CP Assist for Cryptographic Functions (CPACF) . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
5.12 Crypto Express 2 feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
5.13 PCIXCC hardware overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
5.14 PCIXCC software overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
5.15 DES key management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
5.16 DES encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
5.17 DES key forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
5.18 Key distribution: Key export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
5.19 Key distribution: Key import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
5.20 PKA key management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
5.21 ICSF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

Chapter 6. LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

6.1 What is LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
6.2 What is a directory service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
6.3 LDAP directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
6.4 How LDAP works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
6.5 LDAP functional model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

Contents v
 6.6 LDAP servers on z/OS (Integrated Security Server LDAP
plus IBM Tivoli Directory Server) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
6.7 LDAP server back ends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
6.8 Capabilities of the Tivoli Directory Server LDAP server (1/2) . . . . . . . . . . . . . . . . . . . 294
6.9 Capabilities of the Tivoli Directory Server LDAP server (2/2) . . . . . . . . . . . . . . . . . . . 297
6.10 LDAP configuration by utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
6.11 Utility ldapcnf restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
6.12 Utility dsconfig restrictions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
6.13 Utility invocation and outputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
6.14 Configuration roles and responsibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
6.15 The LDAP schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
6.16 Schema attribute types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
6.17 LDAP directory schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
6.18 Authentication with an LDAP server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
6.19 LDAP authentication with RACF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
6.20 z/OS LDAP server native authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
6.21 Enabling LDAP native authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
6.22 Native authentication configuration options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
6.23 More native authentication configuration options . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
6.24 LDAP server-side Kerberos bind. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
6.25 LDAP Kerberos configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
6.26 LDAP Kerberos directory schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
6.27 LDAP Kerberos: Mapping algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
6.28 LDAP Kerberos: LDBM and TDBM mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
6.29 Configuring access control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
6.30 How to set up a Kerberos directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
6.31 Access control lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
6.32 Access evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
6.33 Managing ACLs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
6.34 Running the LDAP server in z/OS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
6.35 Referrals and replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
6.36 LDAP change logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354

Chapter 7. EIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

7.1 Overview of EIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
7.2 EIM concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
7.3 Setting up EIM in z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
7.4 Installing and configuring EIM on z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
7.5 Domain authentication methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
7.6 EIM additional administration tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
7.7 RACF support for EIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
7.8 Storing LDAP binding information in a profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
7.9 Setting up a registry name for your local RACF registry . . . . . . . . . . . . . . . . . . . . . . . 394

Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399

IBM Redbooks publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Other publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
How to get IBM Redbooks publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401

vi ABCs of z/OS System Programming Volume 6

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:
AIX® MVS™ S/390®
CICS® NetView® System z™
DB2® OS/390® System z9®
DFSMS™ OS/400® Tivoli®
DFSORT™ Parallel Sysplex® TotalStorage®
Domino® PowerPC® VTAM®
eServer™ RACF® WebSphere®
IBM® RDN™ z/Architecture®
IMS™ Redbooks® z/OS®
Language Environment® Redbooks (logo) ® z9™
Lotus® REXX™ zSeries®
MQSeries® RMF™

The following terms are trademarks of other companies:

PostScript, and Portable Document Format (PDF) are either registered trademarks or trademarks of Adobe
Systems Incorporated in the United States, other countries, or both.

Novell, the Novell logo, and the N logo are registered trademarks of Novell, Inc. in the United States and other
countries.

SAP, and SAP logos are trademarks or registered trademarks of SAP AG in Germany and in several other
countries.

Active Directory, 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 ABCs of z/OS System Programming Volume 6

Preface

The ABCs of z/OS® System Programming is an 11-volume collection that provides an

introduction to the z/OS operating system and the hardware architecture. Whether you are a
beginner or an experienced system programmer, the ABCs collection provides the
information that you need to start your research into z/OS and related subjects. If you want to
become more familiar with z/OS in your current environment or if you are evaluating platforms
to consolidate your e-business applications, the ABCs collection can serve as a powerful
technical tool.

The contents of the volumes are:

 Volume 1: Introduction to z/OS and storage concepts, TSO/E, ISPF, JCL, SDSF, and z/OS
delivery and installation
 Volume 2: z/OS implementation and daily maintenance, defining subsystems, JES2 and
JES3, LPA, LNKLST, authorized libraries, Language Environment®, and SMP/E
 Volume 3: Introduction to DFSMS™, data set basics, storage management hardware and
software, VSAM, System-managed storage, catalogs, and DFSMStvs
 Volume 4: Communication Server, TCP/IP, and VTAM®
 Volume 5: Base and Parallel Sysplex®, System Logger, Resource Recovery Services
(RRS), global resource serialization (GRS), z/OS system operations, automatic restart
management (ARM), and Geographically dispersed Parallel Sysplex (GPDS)
 Volume 6: Introduction to security, RACF®, Digital certificates and PKI, Kerberos,
cryptography and z9™ integrated cryptography, LDAP, and Enterprise Identity Mapping
(EIM).
 Volume 7: Printing in a z/OS environment, Infoprint Server and Infoprint Central
 Volume 8: An introduction to z/OS problem diagnosis
 Volume 9: z/OS UNIX® System Services
 Volume 10: Introduction to z/Architecture®, System z™ processor design, System z
connectivity, LPAR concepts, HCD, and HMC
 Volume 11: Capacity planning, performance management, WLM, RMF™, and SMF

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 (ITSO), Poughkeepsie Center.

Paul Rogers is a is a Consulting IT Specialist at the ITSO, Poughkeepsie Center, and has
worked for IBM® for 39 1/2 years. He writes extensively and teaches IBM classes worldwide
on various aspects of z/OS, JES3, Infoprint Server, and z/OS UNIX. Before joining the ITSO
19 1/2 years ago, Paul worked in the IBM Installation Support Center in Greenford, England,
providing OS/390® and JES support for IBM EMEA and in the Washington Systems Center in
Gaithersburg, Maryland.

Rui Feio is an IT Specialist working at IBM Portugal. He has six years of experience in the
MVS™, OS/390, and z/OS fields. He provides support to IBM customers in Portugal. His

© Copyright IBM Corp. 2008. All rights reserved. ix

 areas of expertise include RACF, DFSMS, JES2, TSO, MVS, and UNIX System Services. He
holds a BSc in Computer Science.

Oerjan Lundgren joined IBM in 1969 and has focused on performance and security related
topics. Oerjan was on assignment in Poughkeepsie for three years during the 1980s and has
since participated in a number of IBM Redbooks® publication projects. Since 2000, Oerjan
has been working for Pulsen Systems AB, which is an IBM Business Partner in Sweden, as a
senior consultant in infrastructure design projects. Oerjan frequently teaches WLM and RMF
workshops for ITSO around the world and also all System z related courses for customers as
well as for universities.

Rita Pleus is a Senior IT Specialist in IBM Global Services in IBM Germany. She has IT
experience since 1986 in a variety of areas, including systems programming and operations
management. Before joining IBM in 2001, she worked for a German S/390® customer. Rita
holds a degree in Computer Science from the University of Applied Sciences in Dortmund.
Her areas of expertise include z/OS, its subsystems, and systems management. She was
one of the authors of ABCs of z/OS System Programming Volume 3, SG24-6983.

Karan Singh is a Project Leader with the ITSO, Poughkeepsie Center. He was formerly a
mainframe systems programmer with IBM Global Services with over 10 years of experience.
He holds an M.S. degree in the Teaching of English.

Thanks to the following people for their contributions to this project:

Paola Bari
ITSO, Poughkeepsie Center

Thanks to the authors of the IBM Redbooks publication, System z Cryptographic Services
and z/OS PKI Services:
 Patrick Kappeler
 Jonathan Barney
 Jean Marc Darees
 Pekka Hanninen
 Robert Herman
 Guillaume Hoareau
 Nikhil V Kapre
 MuHyun Kim
 Gerard Laumay
 Joel Porterie
 Vicente Ranieri Jr.
 Dominique Richard
 Daniel Turkenkopf

Thanks to the following for their comments:

Gregory P. Boyd
Advanced Technical Support, IBM

x ABCs of z/OS System Programming Volume 6

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 ABCs of z/OS System Programming Volume 6
 1

Chapter 1. Introduction to z/OS security

In today’s on demand environment, downtime is both unwelcome and costly. If your
applications are not consistently available, your business can suffer. IBM System z, along with
IBM software and the IBM TotalStorage® Resiliency family of offerings, provides a
comprehensive set of products and solutions to help address specific business resiliency
needs and to help protect your data, transactions, and the reputation of your business.

With estimates of over 80% of corporate data residing or originating on mainframes, security
and data integrity are on top of the list of critical business requirements. Thus, organizations
need to deliver advanced security features with an array of user identification, authentication,
auditing, and administration capabilities, combined with advancements in data encryption,
intrusion detection, and overall system integrity. These capabilities are designed to sustain
customer-facing, high-volume transaction rates at high service levels.

In this book, we explain how IBM System z is designed with built-in security capabilities to
help protect your business.

Traditionally, when we think of security, we often think of home security—keeping the doors
closed and locked, controlling access by limiting the number and distribution of keys, installing
burglar alarms to detect physical intrusion, and installing smoke and carbon monoxide alarms
to detect intrusion by other harmful substances. In many ways, IT security works in a similar
fashion. You need systems that are designed to control access to the system, to detect and
prevent intrusion into the system by unauthorized users, and to protect the system from
corruption by unauthorized programs and viruses. In other words, you need to close and lock
the doors and install a rigid and comprehensive set of fences and alarms to help protect
against various types of intrusion.

This chapter provides a brief overview of z/OS basic security and the additional Security
Services under z/OS. z/OS security services comprise a variety of security-related products,
which are grouped into three elements, which we explain in detail in the following chapters:
 Chapter 2, “z/OS Security Server RACF” on page 9, an optional feature of z/OS
 Integrated security services:
– Chapter 4, “Kerberos” on page 193
– Chapter 6, “LDAP” on page 283
– Chapter 7, “EIM” on page 357
 Chapter 5, “Cryptographic Services” on page 237, a base element

© Copyright IBM Corp. 2008. All rights reserved. 1

1.1 z/OS basic security facilities

Integrity
Program property table (PPT)
Authorized program facility (APF)
Authorized programs
System authorization facility (SAF)
Auditing
Logs (hardcopy, system)
Generalized trace facility (GTF)
System management facility (SMF)

Figure 1-1 z/OS basic security facilities

z/OS operating system

The operating system z/OS is designed, implemented, and maintained to protect itself
against unauthorized access, and thus security controls that are specified for that system
cannot be compromised. Thus, there is no way for any unauthorized program, using any
system interface, defined or undefined to:
 Bypass store or fetch protection
 Bypass the operating system password, VSAM password, or z/OS Security Server
Resource Access Control Facility (RACF) checking
 Obtain control in an authorized state

Program property table

The program properties table (PPT) contains a list of programs that require special attributes.
Among other things, the special attributes specify whether the programs can or cannot bypass
security protection (password protection and RACF) and whether they run in a system key.
Programs with the NOPASS parameter are able to bypass password protection for password
protected data sets and, thus, also bypass all RACF protection for RACF-protected
resources.

2 ABCs of z/OS System Programming Volume 6

The system key parameter indicates whether the program is authorized to run in a system key
(keys 0 through 7) and is thus able to bypass system security controls.

Important: You need to verify that only those programs that are authorized to bypass
password protection are, in fact, able to do so. Such programs are normally communication
and database control programs or other system control programs. You can also verify that
only those programs that need to run in a system key are authorized to do so.

Authorized program facility

Authorized program facility (APF) is a feature that allows system and user programs to use
sensitive system functions. To authorize a program, the following steps are required:
1. The program load module must be marked as authorized by the binder or have the APF
indicator if the program resides in a UNIX System Services file system.
2. If loaded from a load module library the load library must be flagged as authorized.
3. When the program is fetched, no non-authorized library can be part of the JOBLIB or
STEPLIB concatenation.

Authorized programs
Many system functions are sensitive (for example restricted SVCs). Therefore, these sensitive
functions can be used only by authorized programs. A program is authorized if one of the
conditions is true:
 Program runs in supervisor state (bit 15 in PSW=0).
 Program runs in system protection key (bits 8-11 in PSW contains key 0-7).
 Program runs as part of an authorized job step task (JSCBAUTH=1). This task is set if the
initial program is marked AC=1 and if it is loaded from an APF authorized library or from
the LPA.

System authorization facility

The system authorization facility (SAF) is part of the operating system. SAF is available
whether or not an additional security product such as RACF is installed. The different
resource managers contact SAF. If an additional security product is installed, SAF routes the
questions using the SAF router to the security product and routes the answer back to the
resource manager. Thus, SAF builds the interface between the resource managers and the
security product. The final decision, whether access will be granted, is made by the resource
manager, not by SAF or the security product. See also “System Authorization Facility (SAF)”
on page 21.

Auditing
z/OS has the following basic functions that provide information useful for auditing purposes:
 Logs (hardcopy and system)
 Generalized trace facility (GTF)
 System management facility (SMF)

Chapter 1. Introduction to z/OS security 3

1.2 z/OS Security Server Components

z/OS Security Server RACF

RESOURCE z/OS Security

Server
ACCESS RACF
CONTROL
FACILITY

Figure 1-2 z/OS Security Server components

z/OS Security Server RACF

Prior to z/OS V1R5, the z/OS Security Server consisted of several components. Now, RACF
is the only component.

The z/OS Security Server RACF is an optionally priced feature that allows an installation to
control access to protected resources.

RACF helps meet your needs for security by providing the ability to:
 Identify and verify users
 Authorize users to access the protected resources
 Control the means of access to resources
 Log and report attempts to access protected resources
 Administer security to meet an installation’s security goals

RACF provides these functions when the installation defines the users and the resources to
be protected.

4 ABCs of z/OS System Programming Volume 6

1.3 Integrated Security Services components

IBM Tivoli Directory Server (LDAP Server)

Network Authentication Service (Kerberos)

Enterpise identity mapping (EIM)

Open Cryptographic Enhanced Plug-ins (OCEP)

DCE Security Server

Figure 1-3 Integrated Security Services components

Integrated Security Services

The basic security functions are shipped as two separate parts:
 The Security Server (that is RACF)
 The Integrated Security Services

The Integrated Security Services consists of the components described in the remainder of
this section.

LDAP Server
The LDAP function was shipped originally as the base function of the z/OS Directory Server.
A new base element, IBM Tivoli® Directory Server for z/OS, was introduced in z/OS V1R8. It
contains a rewritten LDAP server, an LDAP client, and LDAP client utilities. The LDAP server
in Integrated Security Services continues to exist in V1R8 and later. However, the LDAP client
and LDAP client utilities do not. In V1R8 and later, they are only in IBM Tivoli Directory Server
for z/OS.

The LDAP server is required to maintain information about Public Key Infrastructure (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 object classes and attributes that PKI
Services requires. 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

Chapter 1. Introduction to z/OS security 5

 server. If you intend to use the z/OS LDAP server, you must configure it to use the TDBM
back end. We explain LDAP in more detail in Chapter 6, “LDAP” on page 283.

Network Authentication Service

Network Authentication Service for z/OS provides Kerberos security services without
requiring that you purchase or use a middleware product such as Distributed Computing
Environment (DCE). These services include native Kerberos application programming
interface (API) functions, as well as the Generic Security Service Application Programming
Interface (GSS-API) functions. Network Authentication Service uses the DES algorithm for
encryption. Before z/OS V1R2, this component was named Network Authentication and
Privacy Service.

Enterprise Identity Mapping EIM

This component allows you to map a user’s identity on one system to the user’s identity on
another system. Chapter 7, “EIM” on page 357 provides more information about this topic.

Open Cryptographic Services Facility OCEP

OCEP provides an application interface for managing server certificates and also helps
protect server private keys in a uniform and secure way. Applications that comply with
Common Data Security Architecture (CDSA) standard interfaces can use OCEP.
OpenCryptographic Services Facility, a base z/OS element, provides these interfaces.
Application developers and independent software vendors using OCEP can find it easier to
develop and port applications to the System z platform. It helps customers apply consistent
security rules to e-business applications that use digital certificates and helps protect server
private keys.

DCE Security Server

DCE Base Services is an exclusive, base element that provides services for developing and
running client/server applications, including remote procedure call, directory, security, and
distributed time services. DCE Base Services uses the limited DES algorithm for encryption.
This element is at the Open Group Open Software Foundation (OSF) DCE 1.2.2 level.

Note: The Firewall Technologies component was removed from the system with z/OS
V1R8.

6 ABCs of z/OS System Programming Volume 6

1.4 Cryptographic Services

Integrated Cryptographic Service Facility (ICSF)

Open Cryptographic Services Facility (OCSF)

Public Key Infrastructure (PKI) Services

System Secure Sockets Layer (SSL)

Figure 1-4 Cryptographic Services

Cryptographic Services
Cryptography is the transformation of data to conceal its meaning. In z/OS, the base element
Cryptographic Services provides the following cryptographic functions:
 Data secrecy
 Data integrity
 Personal identification
 Digital signatures
 The management of cryptographic keys

This base element supports keys as long as 56 bits. Keys longer than 56 bits are supported
by the optional feature z/OS Security Level 3.

Chapter 5, “Cryptographic Services” on page 237 provides more information about

cryptography.

Integrated Cryptographic Service Facility

Integrated Cryptographic Service Facility (ICSF) provides application programs with callable
service interfaces to support the encryption and decryption of data using the cryptographic
hardware in the IBM System z servers. ICSF adds support for callers running in 64-bit
addressing mode.

The application calls ICSF for a cryptographic function and provides the data to be processed
along with the cryptographic key to be used.

Chapter 1. Introduction to z/OS security 7

 ICSF drives the cryptographic operations at the coprocessors and transmits and receives the
processed data and the encrypted application key. Access to ICSF callable services and
application keys can be controlled by RACF profiles.

Open Cryptographic Services Facility

Open Cryptographic Services Facility (OCSF) is the z/OS implementation of Common Data
Security Architecture (CDSA) API from Intel®. OCSF actually uses ICSF to get access to the
cryptographic hardware coprocessor.

Public Key Infrastructure services

Digital certificates, in widespread use today, are becoming increasingly important as a means
of helping to secure transactions on the Internet. As such, digital certificates add capabilities
far superior to mere password protection. PKI provides a trusted infrastructure that can
manage and support the use of digital certificates. PKI services are provided as part of z/OS,
so you can act as your own Certificate Authority (CA). As a CA, you have the power to create,
approve or reject, and manage the life cycle of digital certificates. Using PKI can represent
significant savings to businesses currently purchasing digital certificates from third-party
vendors.

Chapter 3, “Digital certificates and PKI” on page 111 explains this topic.

System Secure Sockets Layer

Secure Sockets Layer (SSL) is a client-server protocol, with the client explicitly requesting an
SSL communication. The client initiates the “handshake” piece of the SSL communication.

System SSL invokes the hardware cryptographic coprocessor, if present on the system, to
assist in performing the asymmetric and symmetric cryptographic algorithms.

8 ABCs of z/OS System Programming Volume 6

 2

Chapter 2. z/OS Security Server RACF

The operating system provides integrity. By using a Security Server, in this case Resource
Access Control Facility (RACF), you can protect resources by defining which resources are
protected and which groups of users or which individual users have access to the defined
resources. The definitions are kept in the RACF database. A RACF administrator defines
users, user groups, and resources together with rules for how these resources can be used.
RACF is “invisible” for most users if a good security structure is put in place. Most companies
have well-documented policies for Information Security. All RACF definitions need to be
based on these policies.

RACF helps meet the needs for security by providing the ability to:
 Identify and verify users
 Authorize users to access the protected resources
 Control the means of access to resources
 Log and report attempts to access protected resources
 Administer security to meet an installation's security goals

RACF provides these functions when the installation defines the users and the resources to
be protected.

A specific RACF user, called the security administrator, has the responsibility to define users
and resources to RACF. The security administrator also specifies the rules that RACF uses to
control access to the resources.

The responsibility to implement the guidelines falls to the system programmer, who provides
technical support for RACF. The system programmer installs RACF on the system and
maintains the RACF database. This person oversees the programming aspects of system
protection and provides technical input on the feasibility of the implementation plan. In
addition, the technical support person can write and implement RACF installation exit
routines to extend the security infrastructure. RACF retains information about the users,
resources, and access authorities in profiles in the RACF database and refers to the profiles
when deciding which users are permitted access to a protected system resources. The
auditor monitors the security controls and examines that the security goals are met.

© Copyright IBM Corp. 2008. All rights reserved. 9

2.1 What is RACF?

RACF is an add-on product to RACF

implement and control the

installation's security policies on
z/OS systems.
Access to protected resources is
controlled by rules.
Access to resources are logged and
can easily be monitored by an
Auditor. RACF
Users, groups, and resources
together with access rules are
administrated by an administrator.

SECURITY
POLICIES

Figure 2-1 What is RACF?

What is RACF
RACF is an add-on software product that provides the basic security to a z/OS system. Other
security software products are available, such as from Computer Associates, ACF2, and Top
Secret. RACF is included as part of the base z/OS system but requires a separate licence to
be activated.

RACF provides the ability to implement the security policies that you choose on your system.

Note: Your system will not be secure by simply installing RACF. The quality of the system
protection depends on the way that you use the RACF functions.

10 ABCs of z/OS System Programming Volume 6

2.2 RACF functions

User identification
and authentication

Resource authorization
RACF checking and system
access control

RACF
Security administration
(local or remote)

RACF database
Audit reports Primary and backup Security console
integrity reports Local and remote sharing Violation reporting

Figure 2-2 RACF functions

RACF functions
RACF protects resources by granting access only to authorized users of the protected
resources. To accomplish this, RACF gives you the ability to accomplish the tasks described
in this section.

Identify and authenticate users

User authentication is validation of the user requesting access. The first step is to identify the
person who is trying to gain access to the system, and the second is to authenticate that the
user is really that person. The standard approach to RACF user identification is achieved by
the use of a user ID and password phrase or password to perform user identification and
authentication. Other options are available, such as digital certificate and smart card.

Resource authorization
Having identified and verified the user, RACF then controls interaction to the system
resources. RACF must authorize the users who can access resources and also the way users
can access them, which depends on the purpose of each user (for example, reading or
updating). RACF can also authorize when a user can access resources, by either time or day.

Chapter 2. z/OS Security Server RACF 11

 Log and report access to protected resources
RACF provides the ability to log information, such as an attempted access to a resource and
to generate reports containing that information which allows identification of users who
attempt to access resources. The logging and reporting functions are:
 Logging: RACF writes records to the system management facility (SMF) data set for
unauthorized attempts to enter the system and optionally RACF writes records to SMF for
authorized attempts. Other events can also be logged.
 Reporting: The SMF records can be analyzed by the RACF Report Writer or be
translated and followed up by other reporting packages such as DB2®.
 Sending Messages: RACF sends messages “real time” to the security console and, if
implemented, to RACF-defined TSO users as well.

Security administration
RACF can be administered either in a centralized or decentralized manner. In a centralized
approach, the RACF administrator (user attribute SPECIAL) controls the access to all users,
groups and resources.

In a decentralized approach, RACF administration can be delegated to administrators only at

a group level. These administrators have the group-SPECIAL attribute, which enables them
to control access only to their group or to be more precise to their scope of the group. The
scope of control of a group-level attribute percolates down through a group-ownership
structure from group to subgroup to subgroup and so on. Percolation is halted (and, therefore,
the scope of control of the group-level attribute is ended) when a subgroup is owned by a user
instead of a superior group.

Another way to implement decentralized administration is by use of class authorization. To do

this an administrator is authorized only for specific types of profiles, for example for user
profiles. In this case, the administrator can administrate user IDs but cannot define which user
IDs, how resources are protected, or who should have access to resources.

Control the means of access to resources

RACF retains information about the users, groups, resources, and access authorities in
profiles that are stored in the RACF database and refers to the profiles when deciding if users
are permitted access to protected system resources. Applications can request RACF
services. Most of these services can only be requested by authorized applications.

RACF database
The RACF database holds all RACF access control information. RACF processing uses the
information from the database each time a RACF-defined user enters a system and each time
a user wants to access a RACF-protected resource. Some of this information can be cached
in storage.

You maintain the RACF database through commands, macros, and utilities.

The RACF database is a non-VSAM, single extent data set that is made up of 4 KB blocks
and must be cataloged.

RACF allows you to provide a backup database to which you can switch without a re-IPL in
case your primary RACF database fail. A backup RACF database reflects the contents of the
primary database. After the installation has created the backup database, RACF can maintain
it automatically.

12 ABCs of z/OS System Programming Volume 6

2.3 RACF ISPF panel

Figure 2-3 RACF primary ISPF panel

How to use RACF ISPF panels

If your installation has installed the RACF panels, you can use them to perform security tasks.

To access the RACF panels, enter the following command:

ISPF

The Interactive System Productivity Facility (ISPF) primary menu displays. From this menu,
choose option R for RACF.

Note: Although this method is the usual way to access RACF panels, your installation
might have this implemented through a different path.

The RACF panel interface is similar in use to all other ISPF panel options. Therefore, we do
not go into detail here on to how to use it.

You can access help information for the RACF panels. Help panels exist for each individual
panel. If you have a question about the information that you should provide on the panel,
either press PF1 or type HELP on the command line. The help panels give more information
about the terms on the panel and the information that you need to enter.

Chapter 2. z/OS Security Server RACF 13

2.4 RACF profiles

Users

Groups

Connections
RRESOURCES
ESOURCES::USERS,
USERS,
GROUPS, DATASETS,
GROUPS, CONNECTIONS,
Data sets (Files) DATASETS, GENERAL
GENERESOURCES
RAL RESOURCES

General resources:
programs, transactions,
databases, etc.

Shareable among systems

Figure 2-4 RACF resource profiles

RACF resource profiles

RACF-protected resources can be divided into two categories:
 Data sets
 General resources

General resources are all of the resources that are defined in the class descriptor table. For
example, general resources include DASD and tape volumes, load modules (programs),
terminals, and others.

RACF maintains information entries, called profiles, in the RACF database. It uses profiles to
protect DASD and tape data sets and general resources, such as tape volumes and
terminals:
 Data set profiles contain security information about DASD and tape data sets.
 General resource profiles contain security information about general resources.

Each RACF-defined resource has a profile, though you can optionally use single profile to
protect multiple resources.

RACF commands or the RACF ISPF panels can be used to create and modify general
resource profiles.

14 ABCs of z/OS System Programming Volume 6

RACF provides discrete, generic, and grouped resource profiles for both data sets and
general resources, as follows:
Discrete Discrete profiles have a one-for-one relationship with a resource—one profile
for each resource. Discrete profiles provide very specific levels of control.
Use them for sensitive resources. They protect only the one identified data
set that is on the specified volume or that spans specific volumes. For
example, a single data set can be defined with a discrete profile to allow
access by one user.
Generic Generic profiles have a one-for-many relationship. One profile controls
access to one or more resources whose names contain patterns or character
strings that RACF uses to associate them with each other. They contain a list
of the authorized users and the access authority of each user. A single
generic profile can protect many data sets that have a similar naming
structure. For example, all data sets that have a high-level qualifier of SMITH
and the characters DATA as a second-level qualifier can be controlled with
one generic profile.
Grouped Another type of RACF profile is the grouped profile. There might be no way to
associate the resources with a common access list based on patterns in the
resource names. In this case, the many resource names can be associated
with a single RACF profile through the use of a grouping profile that contains
the names of the associated resources.
Some subsystems with high performance requirements, such as IMS™ and
CICS®, have the profiles resident in the subsystem address space. These
subsystems can save main storage by using grouped profiles.

Chapter 2. z/OS Security Server RACF 15

2.5 RACF commands

For resources administration:

RACF

FUNCTION USER GROUP DATASET GENERAL RESOURCE

DEFINE ADDUSER ADDGROUP ADDSD RDEFINE

ALTER ALTUSER ALTGROUP ALTDSD RALTER

LIST LISTUSER LISTGROUP LISTDSD RLIST

DELETE DELUSER DELGROUP DELDSD RDELETE

Figure 2-5 RACF commands

RACF commands
For each resource type, a set of commands is available to define, modify, list, and delete
resources.

There are several ways to enter RACF commands:

 RACF TSO commands
Easy and appropriate for ad hoc displays and update of user profiles and data set profiles,
for example:
RDEFINE FACILITY BPX.SUPERUSER UACC(NONE)

PERMIT BPX.SUPERUSER CLASS(FACILITY) ID(JANE) ACCESS(READ)

 RACF TSO commands in batch
Most appropriate for a set of displays that is run, unchanged, at regular intervals.
 RACF ISPF panels
Might be most appropriate for display of some of the more complex RACF general
resource profiles. They are also very useful if you do not know the syntax for a particular
command.

In general, you must have authority for a RACF entry in order to display it. A normal TSO user
can display only the RACF data relevant to himself. A user with SPECIAL authority can
display almost anything.

16 ABCs of z/OS System Programming Volume 6

 Note: We say almost because RACF has another authority named AUDITOR who can
uniquely display certain statistical data. A SPECIAL user can create AUDITOR authority,
so the SPECIAL user remains the ultimate controller of RACF.

Using RACF commands with TSO/E

You can enter RACF TSO commands from the ready prompt or by selecting Option 6 from the
ISPF menu.

You can get online help for RACF commands. To get online help for a command, type:
HELP command-name

For example, to see online help for the PERMIT command, enter:
HELP PERMIT

To limit the information displayed, use the SYNTAX operand on the HELP command:
HELP command-name SYNTAX

For example, to see only the syntax of the PERMIT command, enter:
HELP PERMIT SYNTAX

General use RACF commands include:

PASSWORD Change password/interval
CONNECT Associate user with group
REMOVE Disassociate user from group
PERMIT Modify resource profile access list
SEARCH Locate RACF information
SETROPTS Set/modify RACF system options
RVARY Switch RACF databases

You can use abbreviations for commands and parameters:

 AU for ADDUSER
 LG for LISTGROUP
 CO for CONNECT
 ID for USERID
 AC for ACCESS
 INT for INTERVAL

Chapter 2. z/OS Security Server RACF 17

 You can use any TSO commands in a batch job, using the JCL for executing the TSO monitor
in batch, as shown in Figure 2-6.

//P390S JOB 1,P390,MSGCLASS=X

//TSOBAT01 EXEC PGM=IKJEFT01
//SYSTSPRT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSUADS DD DSN=SYS1.UADS,DISP=SHR
//SYSLBC DD DSN=SYS1.BRODCAST,DISP=SHR
//SYSTSIN DD *
LD DA('MARTIN.*') AUTHUSER
LU MARTIN
/*
Figure 2-6 JCL example of executing RACF commands in a batch job

Where the following command lists generic profile MARTIN and its access list:
LD DA('MARTIN.*') AUTHUSER

And, the following command displays the basic RACF data for user ID MARTIN:
LU MARTIN

18 ABCs of z/OS System Programming Volume 6

2.6 User authentication

User authentication

logon
logon user ID Resource
manager

password /
password phrase
OID CARD
RACF

RACF DB

Figure 2-7 User authentication

RACF identifies and authenticates users accessing the system when the various system
resource managers (such as TSO logon) request it. RACF determines the following
conditions:
 Whether the user is defined to RACF.
 If the user has supplied a valid password or Pass Ticket or operator identification card
(OIDCARD) and belongs to a valid group. RACF has support for a password phrase that
can be up to 100 characters long.
 If the user accesses a UNIX System Services resources, then the user also must have a
valid UID and GID (if this is not provided by a default user and group ID).
 Whether the user ID is in REVOKE status, which prevents a RACF-defined user from
entering the system at all or entering the system with certain groups.
 If the user can use the system on this day and at this time of the day (an installation can
impose restrictions).
 If the user is authorized to access the terminal (which can also include day and time
restrictions for accessing that terminal).
 If the user is authorized to access the application.

Chapter 2. z/OS Security Server RACF 19

2.7 Resource managers

Users are authenticated by RACF

RACF is invoked by resource managers at system
security control points, typically using SAF interfaces.
Sample resource managers:
DFSMS RACROUTE Optional Exit
Exit
IMS Check
SAF Callable
CICS Services Exit RC

TSO S
DB2 A Access?
Unix System Services F
RACF call
JES RACF
Yes / No Check
Console Services RACF RC

VTAM
Figure 2-8 Resource managers

Resource validation overview

After the user has been authenticated, RACF controls access to resources. Before the user
can access a protected resource RACF makes sure that the user is authorized to use the
resource in the intended way (read, update, day, time, and so forth).

RACF can also authorize when a user can access resources, by either time or day as follows:
 A user is identified and verified to the RACF-protected system.
 A user wants to modify an existing RACF-protected resource.
 The user issues a command to the system to access the resource.
 The system resource manager (such as data management) processes the request.
 The resource manager “asks” RACF whether the user can access the resource.
 RACF checks one profile to verify that the user can access the resource and to determine
whether the user has the required authorization to modify the contents.
 RACF returns the results of its check to the resource manager.
 The resource manager, based on what RACF indicates, either grants or denies the
request.

20 ABCs of z/OS System Programming Volume 6

2.8 System Authorization Facility (SAF)

User Resource
Request Manager

S
A RACF
(IMS F
DFHSM
CICS JES
Request .....)
In-Storage
Response
Profiles

RACF Database
Figure 2-9 System Authorization Facility (SAF)

System Authorization Facility (SAF)

System Authorization Facility (SAF) is part of the operating system. SAF establishes default
security functions when RACF is not active. To enable this, SAF is initialized early in the NIP
process. SAF is also the interface between the resource managers and the security product.

Resource managers are responsible for calling SAF to determine whether a user or group is
allowed access to the system or resource.

Note: The resource manager is responsible for initiation of the authorization check.

Figure 2-9 illustrates the SAF function. Based on the original user’s request, the resource
manager formulates a request to SAF. Depending on the request, SAF can respond directly
or pass the request to RACF.

Note: In either case, the user receives the response from the resource manager.

Examples of resource managers are shown in 2.7, “Resource managers” on page 20.

Chapter 2. z/OS Security Server RACF 21

 Token support
SAF also creates and maintains security tokens. A security token is an 80-(decimal) byte
packet of security information that is associated to a unit of work. These tokens provide a
means by which all work, including input and output, can be identified as it flows around the
system.

Information contained in the token includes:

 Port of entry
 Submitting node
 User ID
 Group ID

22 ABCs of z/OS System Programming Volume 6

2.9 RACF classes

New Class?

RACF-Lab Developer
RACF-Database Product(XYZ)

class - USER
class - GROUP
class - DATASET
.
class -DASDVOL
New Class!
class - TAPEVOL
class - XYZ

Profile
Product
XYZ

RACF-Administrator User of XYZ

Figure 2-10 RACF classes

RACF database
RACF stores information about users, groups and resources in the RACF database. The
information is normally kept in storage to enhance performance. The drawback is that this
data has to be refreshed when data is changed.

RACF - Administrator
To protect resources the RACF Administrator needs to know in which classes a resource
manager keeps the RACF information. This information is normally documented in the
reference manuals.

The RACF administrator defines user profiles in the RACF class USER, group profiles in the
class GROUP, resource profiles for data sets in the class DATASET and resource profiles for
tapes in the class TAPEVOL.

It is possible to define additional classes. You can do this by modifying the Class Descriptor
Table and then activating the updated table. The IBM supplied class descriptor table can be
found in Appendix A of z/OS Security Server RACF Systems Programmer’s Guide,
SA22-7681.

Note: The class descriptor table can be updated dynamically.

Chapter 2. z/OS Security Server RACF 23

2.10 Security administration with RACF

Set RACF system options

Define users RA
R CFF
AC

Define groups
COMMANDS

Define Resource profiles

data sets
System
Options
general resources
RACF
DB
ISPF Panels, RACF
Profiles: Users,
commands, TSO
Groups, Data sets,
commands, optionally General Resources
additional product like Consul
Figure 2-11 Security administration with RACF

Security administration with RACF

The administrator is a user with the SPECIAL user attribute. As the security administrator, you
are the focal point for planning security at your installation. You need to:
 Determine which RACF functions to use and how these functions are to be used
 Identify the level of RACF protection
 Identify what resources RACF is to protect
 Identify administrative structures (centralized or decentralized)
 Decide on naming conventions (for example for groups and user IDs)

A RACF security administrator performs the tasks that we describe in this section.

Define RACF system options

The key factor is to understand what RACF functions to use and to use these functions to
achieve your security goals. Questions for the security administrator to consider and then set
the system wide options accordingly include:
 Data Set Protection for all data sets?
 Resource Protection for which classes?
 Group Structure?
 RACF Tailoring?
 Transparency?
 Recovery?
 Violation Detection?
 Subsystems?
 Networks?
 Data Sharing?

24 ABCs of z/OS System Programming Volume 6

Define user IDs and assign attributes
Individual accountability should be one of your installation’s prime security objectives. RACF
offers you the ability to assign each user a unique identifier. (Of course, whether you establish
this degree of accountability in all cases is an installation decision.) A RACF user is identified
by an alphanumeric user ID that RACF associates with the user. The maximum length of a
user ID from RACF’s point of view is eight characters, but the maximum length for TSO is
seven characters. Some users have particular tasks and, therefore, have attributes assigned.
Some examples of attributes include:
 SPECIAL for a system wide security administrator
 AUDITOR for a person who has overall responsibility to monitor the security guidelines
 REVOKED for a user ID who should be prevented from entering the system

The information about the user is stored in the user profile.

When defining a user it is mandatory to name the default group of the user. Each RACF
defined user belongs at least to his default group, but can be a member of multiple groups.
Furthermore it is necessary to have an owner of the user profile. Normally the default group is
chosen as owner.

Define groups
A user is connected to one or more groups. The information about the group is stored in the
group profile. A RACF group normally contains a number of users who share common
access requirements. It is important to consider the basic purpose of a group, for example
whether it is an administrative group, a holding group, a data control group, a functional group,
or a user group? Beyond this consideration, it is necessary to specify the owner of the group.

Important: The owner in RACF relates to the profile. The owner of a profile can update the
profile.

Define RACF resource profiles

Appropriate protection of resources is an important goal that the security administrator has to
achieve. RACF maintains these information entries in resource profiles in the RACF
database. It uses them to protect DASD and tape data sets and general resources, such as
transactions, programs, or spool output. RACF uses two kinds of resource profiles:
 Data set profiles contain security information about DASD and tape data sets.
 General resource profiles contain security information about general resources.

Note: In most cases, multiple resources are protected with a single profile, referred to as
generic profiles.

ISPF Panels and commands

You can define most RACF functions using RACF ISPF panels. This interface is very useful
for definitions or updates of a small number of entries. If you need to change a large number
of entries, then TSO commands, maybe in combination with REXX™, is often a better
alternative.

The RACF operator commands allow you to perform functions in the RACF subsystem. You
can enter these commands from an operator console. These commands allow an z/OS
operator to perform certain RACF operations in the RACF subsystem. The RACF subsystem
prefix in front of the command identifies the RACF subsystem as the processing environment.
Many RACF commands can be entered using TSO/E.

Chapter 2. z/OS Security Server RACF 25

2.11 RACF user identification and verification

User Identification
User ID = string of characters uniquely
identifying a user to a system ?
Uniqueness allows individual
accountability
Digital Certificate
User Verification
Via something the user knows - password
Via something the user has - magnetic
?
card, smart card, biometrics
RACF installation exits can augment

Valid User = Identification + Verification

Figure 2-12 RACF user identification and verification

RACF user
As a general objective, all users should be defined to RACF. Users who are not defined to
RACF can use the system virtually without verification, unless, of course, they attempt to
access data to which they are unauthorized.

You should consider defining the following users to RACF:

 Interactive users of CICS, IMS, TSO/E, NetView®, or other products that support logging
on at a terminal
 Users who submit batch jobs
 MVS or JES system operators
 Started procedures
 Node names in an NJE network
 RJP or RJE remote workstations or nodes

User identification
RACF uses an alphanumeric user ID for its user identification. The user ID identifies the
person to the system as a RACF user. From a security point of view, the user ID is unique and
must not be shared by different users. This uniqueness provides individual accountability.

In a client-server network environment, entities identify themselves using digital certificates.

The combination of a serial number and the name of the certificate authority (or issuer's
distinguished name) uniquely identifies a client's digital certificate.

26 ABCs of z/OS System Programming Volume 6

User verification
There are different techniques for user verification:
 Use a password phrase or password, something only the user knows
The system-encrypted password or password phrase is character strings that are known
only by the user (not even by the security administrator) and, therefore, verifying against
the system that the user is the actual person who owns that user ID. This can either be a
password that is a maximum of eight characters long or a password phrase that is
between nine and 100 characters long. The password can use uppercase or mixed
characters.
 Use something only the user has
This verification can be done with the use of a card with a magnetic stripe encoded with
unique characters and used to verify the identity of a user to RACF on a z/OS System.

Valid users
Normally, when you define a user to RACF, you assign a user ID and a temporary password.
There are exceptions. Therefore, RACF provides the RESTRICTED parameter, which we
explain in 2.13, “RACF user attributes” on page 29.

Furthermore, you can have installations exits that expand user verification.

Note: It is the installations responsibility to accomplish and monitor security guidelines (for
example, unique user IDs and password rules).

Chapter 2. z/OS Security Server RACF 27

2.12 RACF user profile

user ID owner password attributes groups security

classification

RACF- basic profile

TSO DFP CICS

Attributes
SPECIAL
segment segment segment
AUDITOR
OPERATIONS
profile expansions
REVOKE
AUTHORITY
CLAUTH
WHEN
RESTRICTED
PROTECTED
UAUDIT

Figure 2-13 RACF user profile

User profile
RACF stores information in its database. For each defined user ID, RACF keeps a user profile
in the class USER. The profile consists of the RACF base segment and optionally additional
segments which hold informations related to the different resource manager.
RACF base segment
The RACF base segment contains the following fields:
user ID The user ID is at the same time the name of the profile.
owner The owner of the profile has the authority to change the profile.
Every profile in RACF needs an owner.
password The password entry is one-way encrypted. It is not possible to
decrypt the password. If a user forgets the password phase or
password, the administrator has to set a new temporary password
and the user has to change this at the next logon.
attributes This field contains extraordinary attributes. The attributes
SPECIAL, OPERATIONS and AUDITOR should be given only to a
few selected user IDs. Further information is provided in 2.13,
“RACF user attributes” on page 29.
groups A user ID belongs at least to his default group, but can be a
member of more groups. This field contains the groups to which the
user ID is connected.
security classification Security classification is a further step of security and is described
as mandatory security control compared to the discretionary
security control.

Important: Ownership in RACF is of high importance. The owner of profiles can

manipulate the profiles. For example, the owner can change or delete a profile. Your
installation needs guidelines that define who is an owner of a profile.

28 ABCs of z/OS System Programming Volume 6

2.13 RACF user attributes

Extraordinary RACF privileges:

AT GROUP
SYSTEM WIDE LEVEL

security local security

SPECIAL administration administration

DASD group's DASD

OPERATIONS maintenance maintenance

system security group security

AUDITOR control control

Figure 2-14 RACF user attributes

User attributes
User attributes are extraordinary capabilities, limitations, or environments that can be
assigned to a user either system wide or when the user is connected to a specific group or
groups. When an attribute is to apply system wide, it is specified at the system level and is
called a user attribute. When an attribute is to apply only to a specified group or groups, it is
specified at the group level and is called a group-related user attribute.

User attributes that you specify in an ADDUSER or ALTUSER command are stored in the
user’s profile and are in effect regardless of the group to which the user is connected.
However, attributes that you specify in a CONNECT command are valid only for this group.

The user attributes are as follows:

SPECIAL A user who has the SPECIAL attribute at the system level can issue all
RACF commands and, therefore, is used only for special users, for example
administrator. This attribute gives the user full control over all of the RACF
profiles in the RACF database.
You can assign the SPECIAL attribute at the group level. When you do, the
group-SPECIAL user has full control over all of the profiles within the scope
of the group.

Note: Users with the SPECIAL attribute do not have access to all resources, but they can
use commands to give themselves access to all resources.

AUDITOR The AUDITOR attribute is given to users who are responsible for auditing
RACF security controls and functions. To provide a check and balance on
RACF security measures, you should give the AUDITOR attribute to

Chapter 2. z/OS Security Server RACF 29

 security or group administrators other than those who have the SPECIAL
attribute.
You can assign the AUDITOR attribute at the group level. When you do, the
group-AUDITOR user’s authority is limited to profiles that are within the
scope of that group.
OPERATIONS A user who has the system wide OPERATIONS attribute has full access
authorization to all RACF-protected resources in the classes DATASET,
DASDVOL, GDASDVOL, PSFMPL, TAPEVOL, VMBATCH, VMCMD,
VMMDISK, VMNODE, and VMRDR classes.
You can assign the OPERATIONS attribute at the group level. When you
do, the group-OPERATIONS user’s authority is limited to resources within
the scope of that group.

Note: Because the OPERATIONS attribute can permit access to a wide range of
resources, use this attribute very carefully. In some cases, you need to audit these users.

REVOKE You can prevent a RACF user from entering the system by assigning the
REVOKE attribute. This attribute is useful when you want to prevent a user
from entering the system, but you can or will not use the DELUSER
command because the user still owns RACF resource profiles.
You can also assign the REVOKE attribute on a group level by using the
CONNECT command. If the user has the REVOKE attribute for a group,
the user cannot enter the system by connecting to that particular group or
access resources as a member of that group.

Note: RACF allows you to specify a future date for a REVOKE to occur (at both the system
and the group level). You can also specify a future date to remove the REVOKE attribute by
using the RESUME operand on the ALTUSER command (for example, when you want to
inhibit a user from entering the system during a long absence).

CLAUTH Users receive the CLAUTH attribute on a class-by-class basis. You cannot
assign the CLAUTH attribute at the user or group level.
If a user has the CLAUTH attribute in a class, RACF allows the user to
define profiles in that class.
RESTRICTED You can prevent RACF users from gaining access to protected resources
they are not specifically authorized to access by assigning the
RESTRICTED attribute on the ADDUSER or ALTUSER command.
PROTECTED You cannot log on to a protected user. This attribute is used mainly for
started tasks to prevent a user ID from being revoked due to multiple
unsuccessful logon attempts.
WHEN Specifies days of the week and hours of the day during which the user has
access to the system.

30 ABCs of z/OS System Programming Volume 6

2.14 RACF user segments

RACF segment: Describe user's basic information

Other segments: Information related to other
software (resources managers)
Segments are also used for groups and resources

RACF TSO CICS OMVS NETVIEW

ACCTNUM CONSNAME
OPIDENT UID
COMMAND CTL
TIMEOUT HOME
PROC DOMAINS
And so PROGRAM
And so And so forth
forth
forth

Figure 2-15 RACF user segments

RACF users segments

When you define a user to RACF, you create a user profile in the RACF database. A user
profile consists of a RACF base segment and optionally any of the following segments:
 CICS
 DCE
 DFP
 LANGUAGE
 LNOTES
 NDS
 NETVIEW
 OMVS
 OPERPARM
 OVM
 TSO
 WORKATTR

The base RACF segment is the part of the RACF profile that contains the fundamental
information about a user, group, or resource and is common to several applications.

The other segments enable resource managers to keep related information.

The number of resource managers using RACF segments is continuously growing.

Chapter 2. z/OS Security Server RACF 31

 The following information is kept in the RACF base segment of the user profile:
USERID User’s identification
NAME User’s name
OWNER Owner of the user’s profile
DFLTGRP User’s default group
AUTHORITY User’s authority in the default group
PASSWORD User’s password (one-way encrypted)
PWD PHRASE Optionally a Password Phrase (one-way encrypted)
REVOKE Date on which RACF prevents the user from having access to the
system
RESUME Date on which RACF lets the user have access to the system again
UACC Default universal access authority for resources that the user defines
WHEN Days of the week and hours of the day during which the user has
access to the system
ADDCATEGORY User’s installation-defined security category
SECLEVEL User’s installation-defined security level
CLAUTH Classes in which the user can define profiles
SPECIAL Gives the user the system-wide SPECIAL attribute
AUDITOR Gives the user the system-wide AUDITOR attribute
OPERATIONS Gives the user the system-wide OPERATIONS attribute
DATA Installation-defined data
ADSP Indicates that all permanent data sets the user creates are to be
RACF-protected with discrete profiles
GRPACC Indicates that other group members can have access to any group
data set the user protects with a data set profile
MODEL Name of the data set model profile to be used when creating new data
set profiles, either generic or discrete
OIDCARD Indicates that the user must supply an operation ID card when logging
on to the system
SECLABEL User’s default security label
CERTNAME The names of the profiles in the DIGTCERT class that are related this
RACF user ID
CERTLABL The certificate labels associated with the profiles in the DIGTCERT
class that are related to this RACF user ID

32 ABCs of z/OS System Programming Volume 6

2.15 RACF user ID and password

Password Management
Allows user to select own password phrase and/or
password
Only user knows his password phrase and/or
password
Security administrator cannot read, but can reset
password and password phrase
Password and Password Phrase Control
Interval, history, syntax rules, expiration warning,
suppression
Last logon message
Revoke invalid attempts
DES one-way encryption
EXIT - check or generate passwords

Figure 2-16 RACF user ID and password

RACF user ID passwords

User identification is achieved using the user ID, which is a string of characters that uniquely
identifies a user to a system.

In RACF, users select their own password (and optionally a password phrase) and only the
user knows these values. If a password or password phrase needs to be reset, the security
administrator either resets it to the default or sets a temporary password (and optionally a
password phrase). This profile is normally in an expired state, thus forcing the user to enter a
new password or password phrase on the first logon.

You can set a variety of rules for forming valid passwords, using the SETROPS command (for
system-wide settings) or the PASSWORD command (to affect only one user). You can
change such things as the number of days a password is valid, how long to maintain
password history to prevent the user from reusing the same password again, and so on.

The syntax rules for password phrases are “hard coded” but can be controlled by use of an
exit.

The password and password phrase is one-way encrypted using a DES algorithm. The key
being used is the password itself. The encrypted password and password phrase are stored
in the user profile.

Chapter 2. z/OS Security Server RACF 33

 Alternatives to password verification
Alternative to password verification include:
1. RACF allows workstations and client machines in a client-server environment to use a
PassTicket in place of a password. A PassTicket can be generated by an authorized
routine in z/OS or on any other platform. The creator of the PassTicket and the verifier of
the PassTicket must share a “common secret.” In addition the creator and verifier must
have the same user ID, Application Name, and time. The PassTicket is valid for +/- 10
minutes. You can enforce that a PassTicket is only valid for one logon.
2. RACF allows the use of an operator identification card (OIDCARD) in place of, or in
addition to, the password during terminal processing. By requiring that a person not only
know a password but also furnish an OIDCARD, an installation has increased assurance
that the user ID was entered by the proper user.
3. z/OS UNIX users are also identified with numeric user identifiers (UIDs), and z/OS UNIX
groups are identified with numeric group identifiers (GIDs). Unlike user names or group
names, these numeric IDs can be shared by more than one user. However, this practice is
not recommended.
4. In a client/server environment, RACF can identify a RACF user ID by extracting
information from the digital certificate. A digital certificate or digital ID, issued by a
certifying authority, contains information that uniquely identifies the client.
5. The Lotus® Domino® Go Web server authenticates a client using the client’s certificate
and the Secure Sockets Layer (SSL) protocol. Domino Go Web server passes the client’s
digital certificate to z/OS UNIX for validation. z/OS UNIX passes the certificate to RACF.
Thus, the RACF user ID and password of each client do not need to be supplied when
accessing secure Web pages.

34 ABCs of z/OS System Programming Volume 6

2.16 Adding a new user to RACF

Add a new user:

ADDUSER JAMES NAME('BROWN JAMES') DFLTGRP(MFG)
OWNER(ADMUSERS) PASSWORD(NEW2DAY)
List the user:
LISTUSER JAMES
USER=JAMES NAME=BROWN JAMES OWNER=ADMUSERS CREATED=99.041
DEFAULT-GROUP=MFG PASSDATE=00.000 PASS-INTERVAL=186
ATTRIBUTES=NONE
O REVOKE DATE=NONE RESUME DATE=NONE
U LAST-ACCESS=UNKNOWN
CLASS AUTHORIZATIONS=NONE
T NO-INSTALLATION-DATA
NO-MODEL-NAME
P LOGON ALLOWED (DAYS) (TIME) ----------------------------------
ANYDAY ANYTIME
U GROUP=MFG AUTH=USE CONNECT-OWNER=ADMIN CONNECT-DATE=99.041

T CONNECTS= 00 UACC=NONE LAST-CONNECT=UNKNOWN

CONNECT ATTRIBUTES=NONE
REVOKE DATE=NONE RESUME DATE=NONE
SECURITY-LEVEL=NONE SPECIFIED
CATEGORY-AUTHORIZATION
NONE SPECIFIED
SECURITY-LABEL=NONE SPECIFIED

Figure 2-17 Adding a new user to the RACF database

How to add a user

When you define a user’s profile (using the ADDUSER command) or change a user’s profile
(using the ALTUSER command), you can specify the information contained in each field of
each segment of the profile.

The command adds a profile for the new user to the RACF database and creates a connect
profile that connects the user to whichever default group you specify. The user profile consists
of a RACF segment and, optionally, other segments such as a TSO segment, a DFP
segment, or an OMVS segment. You can use this command to define information in any
segment of the user’s profile.

Figure 2-17 shows sample output from the following ADDUSER command when the
LISTUSER is issued:
ADDUSER JAMES NAME('BROWN JAMES') DFLTGRP(MFG)
OWNER(ADMUSERS) PASSWORD(NEW2DAY)

This command adds a new user ID, JAMES, into default group, MFG.

Chapter 2. z/OS Security Server RACF 35

2.17 Reset a user password

How to Reset a Password :

List the user : LISTUSER JAMES
ALU James RESUME PASS(NEW PASSWORD) => If REVOKED
ALU James PASS(new password) => If not REVOKED
ALU James PASS(new password)NOEXPIRED => If not REVOKED
USER=JAMES NAME=BROWN JAMES OWNER=ADMUSERS CREATED=99.041
DEFAULT-GROUP=MFG PASSDATE=00.000 PASS-INTERVAL=186
ATTRIBUTES=REVOKED
REVOKE DATE=NONE RESUME DATE=NONE Note this line
O LAST-ACCESS=UNKNOWN
U CLASS AUTHORIZATIONS=NONE
NO-INSTALLATION-DATA
T NO-MODEL-NAME
LOGON ALLOWED (DAYS) (TIME) ----------------------------------
P ANYDAY ANYTIME
GROUP=MFG AUTH=USE CONNECT-OWNER=ADMIN CONNECT-DATE=99.041
U CONNECTS= 00 UACC=NONE LAST-CONNECT=UNKNOWN

T CONNECT ATTRIBUTES=NONE
REVOKE DATE=NONE RESUME DATE=NONE
SECURITY-LEVEL=NONE SPECIFIED
CATEGORY-AUTHORIZATION
NONE SPECIFIED
SECURITY-LABEL=NONE SPECIFIED

Figure 2-18 Resetting a password

Reset a user password

A system administrator is often asked to reset a user’s password. There are two common
reasons for resetting a password:
1. The user forgot the password (or made too many errors when attempting change it).
2. The user ID was REVOKED for some reason.

You can use the RACF ISPF panels to reset passwords but it is easier to use the following
commands:
PASSWORD When used to reset another user’s password, the only option is to set the
password equal to the user’s default group name. The default group name
is often SYS1. So, if the PASSWORD command is used to reset a user’s
password, the password is probably SYS1, which has obvious security
consequences.
ALTUSER You set the password phrase or the password. You can also specify
whether the user must specify the passwords again. This is indicated by
EXPIRED or NOEXPIRED.

In both cases, the password is marked automatically as expired, by default. Thus, the user is
forced to select a new password when logging on to the system the next time. With the ALU
command, you can also set an unexpired password, which is password one that the user can
use until changing it for some reason.

36 ABCs of z/OS System Programming Volume 6

Before resetting a password, we suggest that you always use the LISTUSER command to
verify that the user definition exists and to determine if the user is REVOKED. For example,
we can use this command:
ALU martin RESUME PASS(newpwd) <== if REVOKED
ALU martin PASS(newpwd) <== if not REVOKED
ALU martin PASS(newpwd) NOEXPIRED <== if not REVOKED

PASSWORD NOINTERVAL USER(martin) <== if you want this

You need to tell Martin the new password that you assigned. Martin needs the new password
to log on but is forced to change the password immediately to a password of his own selection
(unless you used the NOEXPIRED option). The PASSWORD NOINTERVAL command
prevents this user’s password from ever expiring. You need SPECIAL authority to issue these
commands.

How to reset a password with ISPF panels

You can also use the RACF ISPF panels to change or reset passwords. The end result is the
same as using the direct commands discussed previously.

The path to the appropriate RACF ISPF panels is:

ISPF Primary Option Menu
RACF (select RACF from the primary ISPF menu)
RACF - Services Option Menu
User Profiles and Your Own Password
RACF - User Profile Services
CHANGE (and enter target userid in the USER field)

When the panel shown in Figure 2-19 displays, carry on from this point.

Figure 2-19 RACF CHANGE USER menu

Remember that the password that you assign must be changed by the user when that user
logs on to the system the next time. You can use this same panel, and other panels that
displays after you press Enter, to change the same elements as the ALTUSER command.

Chapter 2. z/OS Security Server RACF 37

2.18 Alter a user ID

Alter a user: ALTUSER JAMES AUDITOR

List the user: LISTUSER JAMES

USER=JAMES NAME=BROWN JAMES OWNER=ADMUSERS CREATED=99.041

DEFAULT-GROUP=MFG PASSDATE=00.000 PASS-INTERVAL=186
O ATTRIBUTES=AUDITOR
...
U ...
T
P
U
T

Figure 2-20 Altering a user ID

How to alter a user ID segment

Use the ALTUSER command to change the information in a user’s profile, including the user’s
system-wide attributes and authorities. The user profile consists of a RACF segment and,
optionally, other segments such a TSO segment or a DFP segment. You can use this
command to change information in any segment of the user’s profile.

When you change a user’s level of authority in a group (using the AUTHORITY operand),
RACF updates the appropriate group profile. When you change a user’s default universal
access authority for a group (using the UACC operand), RACF changes the appropriate
connect profile. For all other changes, RACF changes the user’s profile.

Figure 2-20 shows sample output from the following ALTUSER command which adds the
attribute of AUDITOR to the user ID ROGERS:
ALTUSER ROGERS AUDITOR

38 ABCs of z/OS System Programming Volume 6

2.19 Change a user’s password interval

Change password interval:

PASSWORD USER(JAMES) INTERVAL(60)
List the user: LISTUSER JAMES

O
U USER=JAMES NAME=BROWN JAMES OWNER=ADMUSERS CREATED=99.041
T DEFAULT-GROUP=MFG PASSDATE=00.000 PASS-INTERVAL=60
ATTRIBUTES=NONE
P
...
U ...
T

Figure 2-21 Changing a user’s password interval

How to a change a user’s password interval

The interval indicates the number of days during which a password remains valid. The range
is from one through 254 days.

The value that you specify here cannot exceed the value, if any, that your installation has
specified using the INTERVAL operand on the SETROPTS command. The initial system
default after RACF initialization is 30 days.

If you specify INTERVAL on the PASSWORD command without a change-interval value,

RACF uses the installation-specified maximum.

Figure 2-21 shows sample output from the following PASSWORD command, which sets the
password expiration date for user ID James to 60 days:
PASSWORD USER(JAMES) INTERVAL(60)

Overriding any system default password expiring setting is set by the SETROPTS command.

Chapter 2. z/OS Security Server RACF 39

2.20 Delete a user ID

Delete a user: DELUSER JAMES

List the user: LISTUSER JAMES

O
U
T UNABLE TO LOCATE USER ENTRY JAMES
P
U
T

Figure 2-22 Deleting a user from the RACF database

How to a delete a user

Use the DELUSER command to delete a user from RACF. This command removes the user’s
profile and all user-to-group connections for the user. (The connect profiles define the user’s
connections to various RACF groups.)

There are, however, other places in the RACF database where the user’s user ID might
appear. The DELUSER command does not delete the user ID from all these places.
Specifically, the user could be the owner of a group, the owner of a user’s profile, the owner of
a group data set, or in an access list for any resource. Before issuing DELUSER, you must
first issue the REMOVE command to assign new owners for any group data sets the user
owns in groups other than his default group. You can use the RACF Remove ID utility
(IRRRID00) to remove all of the occurrences of a user ID. For information about using the
RACF Remove ID utility, see z/OS Security Server RACF Security Administrator's Guide,
SA22-7683.

To use the DELUSER command, at least one of the following must be true:
 You must have the SPECIAL attribute.
 The user profile to be deleted must be within the scope of a group in which you have the
group-SPECIAL attribute.
 You must be the owner of the user’s profile.

Figure 2-22 shows sample output from the following DELUSER command, which deletes the
user ID James.
DELUSER JAMES

40 ABCs of z/OS System Programming Volume 6

2.21 User related RACF commands

User related RACF commands

ADDUSER
ALTUSER
CONNECT
DELUSER
REMOVE
LISTUSER
PERMIT
PASSWORD

Figure 2-23 User-related RACF commands

RACF commands
You define users to RACF by issuing RACF commands that include various user attributes, as
well as other control information that RACF uses. Some of the commands that you might use
in your user-definition tasks include:
ADDUSER Add a user profile to RACF.
ALTUSER Change a user’s RACF profile.
CONNECT Connect a user to a group.
DELUSER Delete a user profile from RACF and remove connection to a group.
REMOVE Remove a user from a group and assign a new owner for group data sets
owned by the removed user.
LISTUSER Display the contents of a user’s profile.
PERMIT Permit a user to access a resource (or deny access to a resource).
PASSWORD Change a user’s password.

In addition to defining individual users, you can define groups of users. Group members can
share common access authorities to a protected resource.

Chapter 2. z/OS Security Server RACF 41

2.22 RACF groups

Group = A collection of users

Every user belongs to one or more groups
Groups can correspond to department,
organization, function, product, and so forth
Resultant "tree" structure of related groups

Group advantages:
Reduces administrative efforts
Allows decentralized administration by delegation of
administrative authority

Figure 2-24 RACF groups

RACF groups
With RACF, all defined users belong to at least one group. You can think of the groups forming
a hierarchical, or “tree” structure, where each group is owned by a superior group. Groups
can also own resources as well as users in another group.

RACF has the following types of groups:

Administrative You can create a group simply as an administrative convenience. For
example, you might create a group to represent an organizational
entity, such as a region or a division. With RACF delegation, you can
create this kind of group for each group administrator. Operating from
such groups, the group administrators can then define other groups
needed by their local users.
Holding This is a technique that retains user definition centrally, yet allows the
effective use of group administrators to establish a holding group. You
define all users centrally and initially connect them to a group named
HOLD with the minimum of authorities. HOLD does not appear in any
access lists and, therefore, has no real significance to the user.

42 ABCs of z/OS System Programming Volume 6

Group administrators, to whom you give CONNECT (but not JOIN) authority, can connect the
appropriate users to the groups under their control and change the user’s default group name
as appropriate. This technique allows the installation to assign correct account numbers and
control other installation considerations while allowing flexibility in the grouping of the user
population.
Data Control You can create a group to act as a control point for the protection of
data. For example, by using the group SYS1, you can determine which
users are permitted to protect the SYS1 data sets. Only users with
CREATE authority or higher in this group can protect system data sets.
At your location, you might consider defining one such group for every
high level qualifier representing data that is to be protected.
Functional A group can represent a functional area of the installation for the
purpose of data sharing. For example, a financial analyst might need
to access a variety of resources across many groups, such as
accounting, payroll, marketing, and others. Of course, the owners of
each resource could permit the financial analyst to access their
resources by placing the analyst’s user ID on an access list. But if a
new financial analyst takes over the job, it is then necessary to add the
new user ID to each RACF profile. Likewise, the RACF profiles must
be updated when the analyst no longer has a need to access the data.
This arrangement involves a great deal of unnecessary activity by the
resource owners.
Instead, you can create a group that represents the financial analyst
function and permits access to the data defined to the group. Access
to the entire range of data can then be managed by controlling the
user population in the defined group. For cases involving one-time
access, owners of the needed data would simply PERMIT access by
the defined group. Where appropriate, the group name could be
included in profile access lists to ensure automatic availability of
needed data to the financial analyst group. New financial analysts
could be connected to the group, as required, to gain access to the
entire range of data. Likewise, analysts could be removed from the
group whenever necessary. By controlling the user population of such
a functional group, resource profile changes on a day-to-day basis
becomes unnecessary.
User You can define a group to serve as an anchor point for users who
otherwise have no common access requirements. For example,
engineers and scientists, as well as other problem-solving users,
might have no need to access application-related data in the system.
Their only interest might be in their own personal data. You can place
this set of users in a single group that has no access to other data.
You can also define groups based on access level. For example, if
PAY.DATA is a RACF-defined data set, two groups could be defined,
PAYREAD and PAYUPDTE, both of which would appear in the
PAY.DATA access list, but with READ and UPDATE access,
respectively. Any users requiring access would be connected as
appropriate, by the group administrator.

Chapter 2. z/OS Security Server RACF 43

2.23 RACF group structure example

SYS1

PROD DEVELOP

POU KGN
- TOM (with group special
attribute)

TEST MFG
- JOE - SALLY
- MARY - FRANK
- SALLY - RICH

Figure 2-25 RACF group structure example

RACF group structure

The group structure of RACF can be mapped to the organizational structure that exists at
your installation. That is, RACF conforms naturally to a tree structure of groups, where each
group (except SYS1, which is predefined as the highest group) has a superior, or owning,
group. Groups can correspond directly to business entities such as divisions, departments,
and projects. Users can be connected to one or more groups.

When you define a group, consider the basic purpose of the group. Is it an administrative
group, a holding group, a data control group, a functional group, or a user group? When
setting up RACF groups, keep in mind that the maximum number of users that you can
connect to any one group is approximately 5900.

You should map your groups to your organization’s structure and arrange them hierarchically,
with the IBM-supplied SYS1 group as the highest group, so that each group is a subgroup of
another group.

A user can be connected in more than one group (in Figure 2-25, SALLY is connected to MFG
and TEST groups).

In Figure 2-25, GROUP, DESIGN, TEST, and MFG are all owned by group POU. Tom is
connected to group POU as special, which gives Tom (who is the RACF administrator) control
over all POU resources DESIGN, TEST, and MFG.

44 ABCs of z/OS System Programming Volume 6

2.24 RACF group related commands: Add a group

Add a group:
ADDGROUP EXPED OWNER(ADMGRPS)
SUPGROUP(POU)
List the group:
LISTGRP EXPED

O INFORMATON FOR GROUP EXPED

SUPERIOR GROUP=POU OWNER=ADMGRPS
U NO INSTALLATION DATA
NO MODEL DATA SET
T TERMUACC
NO SUBGROUPS
P NO USERS
U
T

Figure 2-26 Add a group

How to add a group

Use the ADDGROUP command to define a new group to RACF. The command adds a profile
for the new group to the RACF database. It also establishes the relationship of the new group
to the superior group you specify.

Group profiles consist of a RACF segment and, optionally, other segments such as DFP and
OMVS. You can use this command to specify information in any segment of the profile.

To use the ADDGROUP command, you must meet at least one of the following conditions:
 Have the SPECIAL attribute
 Have the group-SPECIAL attribute and the superior group is within your group-SPECIAL
scope
 Be the owner of the superior group
 Have JOIN authority in the superior group

Figure 2-26 shows sample output from the ADDGROUP command, adds a new group named
EXPED and is a subgroup to group POU:
ADDGROUP EXPED OWNER(ADMGRPS) SUPGROUP(POU)

Chapter 2. z/OS Security Server RACF 45

2.25 RACF group related commands: Alter a group

Alter a group:
ALTGROUP EXPED SUPGROUP(KGN)
List the group:
LISTGRP EXPED

O
INFORMATION FOR GROUP EXPED
U SUPERIOR GROUP=KGN OWNER=ADMGRPS
T NO INSTALLATION DATA
NO MODEL DATA SET
P TERMUACC
U NO SUBGROUPS
NO USERS
T

Figure 2-27 Alter a group

How to alter a group

Use the ALTGROUP command to change:
 The superior group of a group
 The owner of a group
 The terminal indicator for a group
 A model profile name for a group
 The installation-defined data associated with a group
 The default segment information for a group (for example, DFP or OMVS)

To change the superior group of a group, you must meet at least one of the following
conditions:
 You must have the SPECIAL attribute
 All the following group profiles must be within the scope of a group in which you have the
group-SPECIAL attribute:
– The group whose superior group you are changing
– The current superior group
– The new superior group
 You must be the owner of, or have JOIN authority in, both the current and the new superior
groups.

46 ABCs of z/OS System Programming Volume 6

 Note: You can have JOIN authority in one group and be the owner of, or have the
group-SPECIAL attribute in, the other group.

Figure 2-27 shows sample output from the ALTGROUP command, which moves the group
named EXPED from being a subgroup of group PGN to a subgroup to group KGN:
ALDGROUP EXPED SUPGROUP(KGN)

Chapter 2. z/OS Security Server RACF 47

2.26 RACF group related commands: Delete a group

Delete a group:
DELGROUP EXPED
List the group:
LISTGRP EXPED
O
U
T NAME NOT FOUND IN RACF DATA SET
P
U
T

Figure 2-28 Delete a group

How to delete a group

Use the DELGROUP command to delete a group and its relationship to its superior group
from RACF.

There are, however, other places in the RACF database where the group name might appear,
and DELGROUP processing does not delete these other occurrences of the group name. For
example, the group name could be in the access list for any resource. You can use the RACF
Remove ID utility (IRRRID00) to remove all occurrences of a group name. For information
about using the RACF Remove ID utility, see z/OS Security Server (RACF) Security
Administrator’s Guide, SA22-7683.

Figure 2-28 shows sample output from the DELGROUP command, which deletes the EXPED
group:
DELGROUP EXPED

48 ABCs of z/OS System Programming Volume 6

2.27 Connect a user to a group

Connect the user to a group:

CONNECT JAMES GROUP(TEST)
List the user: LISTUSER JAMES
USER=JAMES NAME=BROWN JAMES OWNER=ADMUSERS
CREATED=99.041
DEFAULT-GROUP=MFG PASSDATE=00.000 PASS-INTERVAL=186
ATTRIBUTES=NONE
O ...
U ...
GROUP=MFG AUTH=USE CONNECT-OWNER=ADMIN
T CONNECT-DATE=99.041
P CONNECTS= 00 UACC=NONE LAST-CONNECT=UNKNOWN
CONNECT ATTRIBUTES=NONE
U REVOKE DATE=NONE RESUME DATE=NONE
T GROUP=TEST AUTH=USE CONNECT-OWNER=ADMIN
CONNECT-DATE=99.041
CONNECTS= 00 UACC=NONE LAST-CONNECT=UNKNOWN
CONNECT ATTRIBUTES=NONE
REVOKE DATE=NONE RESUME DATE=NONE
...

Figure 2-29 Connecting a user to a group

How to connect a user to a group

Use the CONNECT command to connect a user to a group, modify a user’s connection to a
group, or assign the group-related user attributes. If you are creating a connection, defaults
are available as stated for each operand. If you are modifying an existing connection, no
defaults apply.

To use the CONNECT command, one of the following conditions must be true:
 The SPECIAL attribute
 The group-SPECIAL attribute in the group
 The ownership of the group
 JOIN or CONNECT authority in the group

Figure 2-29 shows sample output from the CONNECT command, which connects user
James to group TEST:
CONNECT JAMES GROUP(TEST)

Chapter 2. z/OS Security Server RACF 49

2.28 Remove a user from a group

Remove a user from a group: REMOVE JAMES

GROUP(TEST)
List the user: LISTUSER JAMES

USER=JAMES NAME=BROWN JAMES OWNER=ADMUSERS CREATED=99.041

DEFAULT-GROUP=MFG PASSDATE=00.000 PASS-INTERVAL=186
ATTRIBUTES=NONE
O ...
...
U GROUP=MFG AUTH=USE CONNECT-OWNER=ADMIN CONNECT-DATE=99.041
T CONNECTS= 00 UACC=NONE LAST-CONNECT=UNKNOWN
CONNECT ATTRIBUTES=NONE
P REVOKE DATE=NONE RESUME DATE=NONE
U GROUP=TEST AUTH=USE CONNECT-OWNER=ADMIN CONNECT-DATE=99.041
CONNECTS= 00 UACC=NONE LAST-CONNECT=UNKNOWN
T CONNECT ATTRIBUTES=NONE
REVOKE DATE=NONE RESUME DATE=NONE

...
...

Figure 2-30 Removing a user from a group

How to remove a user from a group

You can use the REMOVE command to remove a user from a group, and to assign a new
owner to any group data set profiles the user owns on behalf of that group.

To use the REMOVE command, one of the following conditions must be true:
 The SPECIAL attribute
 The group-SPECIAL attribute in the group
 The ownership of the group
 JOIN or CONNECT authority in the group

Figure 2-30 shows sample output from the following REMOVE command:
REMOVE JAMES GROUP(TEST)

50 ABCs of z/OS System Programming Volume 6

2.29 Data sets and general resources

Classes of resources profiles:

Data set
Tape data set
DASD data set
General resources
Terminals
Programs
IMS transactions
etc
PROGRAM

Three types of profiles: CALL ABC

...
...
END
DISCRETE profiles
GENERIC profiles
GROUPED profiles

Figure 2-31 Data sets and general resources

Controlling access to resources

To protect a general resource, create a general resource profile using the RDEFINE
command. When you create a general resource profile, you must specify a general resource
class for the profile. IBM supplies a list of the general resource classes in the class descriptor
table (CDT). The classes for z/OS systems are relevant to the system on which you are
running the z/OS Security Server (RACF).

RACF-protected resources can be divided into two categories: data sets and general
resources. General resources are all of the resources that are defined in the class descriptor
table. For example, general resources include DASD and tape volumes, load modules
(programs), terminals, and others.

RACF allows the installation to set its own rules for controlling the access to its resources by
defining what is controlled at what level. The installation can tailor RACF to interact with its
present operating environment and assign security responsibilities either on a system-wide or
a group-wide basis.

Your installation can add new class descriptor table (CDT) entries or modify or delete existing
entries that you have added in the installation-defined class descriptor table (ICHRRCDE).
When you define a new resource class, you can optionally designate that class as either a
resource group class or a resource member class. For a resource group class, each user or
group of users that is permitted access to that resource group is permitted access to all

Chapter 2. z/OS Security Server RACF 51

 members of the resource group. Note that for each resource group class you create, you must
also create a second class that represents the members of the group.

It is possible to define dynamic class descriptor table (CDT) entries. This is done by defining
profiles in the CDT class. Profiles in this class have a CDTINFO segment which contains all
the parameters that could be defined in the installation-defined class descriptor table
(ICHRRCDE).

52 ABCs of z/OS System Programming Volume 6

2.30 Data sets and general resources

Profiles contain:
The owner of the profile
The auditing parameters
The Universal Access authority
An access list with users and groups
A "warning" indicator
A security classification
A real-time notification information
An erase-on-scratch indication for PROGRAM
CALL ABC
data sets ...
...
END

A volume and a unit (if data set)

A security retention period (if tape
data set)
Access statistics

Figure 2-32 Resource profiles

Resource profiles contain:

 The owner of the profile
 The auditing parameters
 The Universal Access authority
 An access list with users and groups
 A “Warning” indicator
 A security classification
 A real-time notification information
 An erase-on-scratch indication for data sets
 A volume and a unit (if data set)
 A security retention period (if tape data set)
 Access statistics

Chapter 2. z/OS Security Server RACF 53

2.31 Data set profiles

Resource-to-Profile Matching
Rule (if generic is active for the class):
Discrete profile - If it does not exist
Fully qualified generic profile - If it does not exist
The most specific generic profile
Example : SALES.YEARLY.QUOTA data set =>
profile ??
1. Discrete profile SALES.YEARLY.QUOTA
SALES.YEARLY.QUOTA ?

2. Fully qualified generic profile

SALES.YEARLY.QUOTA ? SALES.YEARLY.QUOTA (G)

3. The most specific generic

SALES.YEARLY.* (G) X
profile? SALES.YEARLY.%%%%% (G)
SALES.* (G) X

Figure 2-33 Locating a resource profile

RACF data sets and general resources

To locate a resource profile:
 RACF looks for a discrete profile, if no discrete profile is found.
 RACF looks for a generic profile and will then use the most qualified generic profile
available.

See z/OS Security Server (RACF) Security Administrator's Guide, SA22-7683, for more detail
about how this process works.

Some of the generic profile naming for general resources has been enhanced with some of
the same concepts as generics for data set profiles as valid generic characters as follows:
* You can have an asterisk (*) within a profile name, representing one qualifier of a
resource name, or specify * in the profile name to match more than one character in
the same position of the resource name.
** You can also use a double asterisk (**) to represent zero or more qualifiers within a
general resource generic profile or at the end of such a profile, or specify ** in the
profile name to match more than one character in the same position of the resource
name. Use of the double asterisk (**) in general resource generic profiles is not
controlled by the SETROPTS EGN option, which applies only to the data set profiles.
% Specify % any single non-blank character (except a period) in the same position of
the resource name

54 ABCs of z/OS System Programming Volume 6

Choosing between discrete and generic data set profiles
Decide which type of profile to create as follows:
 Generic
Choose a generic profile for the following reasons:
– If you want to protect more than one data set with the same security requirements.
– If you have a single data set that might be deleted, then re-created, and you want the
protection to remain the same, you can create a fully qualified generic profile. The
name of a fully qualified generic profile matches the name of the data set it protects.
Unlike a discrete profile, a fully qualified generic profile is not deleted when the data set
itself is deleted.
 Discrete
Choose a discrete profile for the following reasons:
– To protect one data set that has unique security requirements. The name of a discrete
profile matches the name of the data set it protects.
– To allow changes to a data set profile to take effect immediately, without needing to
refresh in-storage copies of the profile.

In Figure 2-33, a resource manager issues a security check for the data set
SALES.YEARLY.QUOTA. Three different types of profiles can be defined in the RACF
database:
 A discrete profile
 A fully qualified generic profile
 The most specific generic profile

The example shows that RACF looks for a profile in the order shown. If no discrete profile is
found, check for a fully qualified profile. If not found, then find the most specific generic profile,
which is the second one in the example, SALES.YEARLY.%%%%%.

Note: By using generic profiles, your installation can reduce both the number of profiles
that are required to protect data sets and the size of the RACF database, thus making
RACF protection easier to administer. In addition, generic profiles are loaded into storage
when first needed, are not deleted when the data set they protect is deleted, and are not
volume-specific (that is, data sets protected by a generic profile can reside on any volume).

You can create a profile with a generic name when the following is true for the class of the
profile:
SETROPTS GENERIC(DATASET) option is in effect.

This option allows the creation of generic profiles and also causes RACF to use generic
profiles during authorization checking.

Chapter 2. z/OS Security Server RACF 55

2.32 Defining data set profiles

Define a data set profile

ADDSD 'SALES.YEARLY.QUOTA' UACC(NONE)
Define who has access to data set
PERMIT SALES.YEARLY.QUOTA
CLASS(DATASET) ID(JANE) ACCESS(READ)
PERMIT places specified users into an access list

Figure 2-34 Defining data set profiles

Defining data set profiles

Use the ADDSD command to add RACF protection to data sets with either discrete or generic
profiles.

The ADDSD command adds a profile for the data set to the RACF database to control access
to the data set. It also places the user ID on the access list and gives ALTER authority to the
resource unless SETROPTS NOADDCREATOR is in effect.

Data set profiles

By default, RACF expects a data set name (and the data set profile name) to consist of at
least two qualifiers. RACF also expects the high-level qualifier of the data set profile name to
be either a RACF-defined user or a RACF-defined group name.

Each data set profile defined to RACF requires a RACF-defined user or group as the owner of
the profile. The owner (if a user) has full control over the profile, including the access list.

If the owner of the data set profile is a group, users with group-SPECIAL in that group have
full control over the profile.

Ownership of data set profiles is assigned when the profiles are defined to RACF. Note that
ownership of a data set profile does not mean that the owner can automatically access that
data set. To access a data set, the owner must still be authorized in the profile’s access list,
unless the high-level qualifier of the profile name is the owner's user ID.

56 ABCs of z/OS System Programming Volume 6

Data set profile examples
The ADDSD command in Figure 2-34 specifies that no users have access to the data set
except the creator of the profile, because the universal access, UACC, is none.

To allow users to have access to the data set, the PERMIT command shown specifies that
user ID JANE has only READ access to the data set, ACC(READ). User ID JANE exists in the
access list for the data set profile using the PERMIT command.

Chapter 2. z/OS Security Server RACF 57

2.33 Data set profile access list

Determines WHO can access the resource:

Users
Groups
Users/groups, under specific conditions U
And HOW they can access the resource:
Valid (hierarchical) levels are:
R
NONE
EXECUTE (z/OS only) U
READ N
UPDATE N
CONTROL PROGRAM
CALL ABC
...
...

ALTER END

R
Meaning of each access level depends on
the resource type

Figure 2-35 Data set profile access list

Data set profile access list

When a user requests access to a RACF-protected resource (such as a data set), the
resource manager issues a RACF authorization request. RACF then performs two checks.

Using the PERMIT command maintains a list of users and groups authorized to access a
particular resource. RACF provides two types of access lists:
Standard The standard access list includes the user IDs and group names
authorized to access the resource and the level of access granted to
each.
Conditional The conditional access list includes the user and group names
authorized to access the resource and the level of access granted to
each when a certain condition is met.

Types of access levels

Types of access levels include:
ALTER ALTER allows users to read, update, delete, rename, move, or scratch
the data set.
When specified in a discrete profile, ALTER allows users to read, alter,
and delete the profile itself including the access list.
ALTER does not allow users to change the owner of the profile using
the ALTDSD command. However, if a user with ALTER access

58 ABCs of z/OS System Programming Volume 6

 authority to a discrete data set profile renames the data set, changing
the high-level qualifier to his or her own user ID, both the data set and
the profile are renamed, and the OWNER of the profile is changed to
the new user ID.
When specified in a generic profile, ALTER gives users no authority
over the profile itself.
NONE The specified user or group is not permitted to access the resource or
list the profile.
EXECUTE For a private load library, EXECUTE allows users to load and execute,
but not to read or copy programs (load modules) in the library.
READ Allows users to access the data set for reading only. (Note that users
who can read the data set can copy or print it.)
UPDATE Allows users to read from, copy from, or write to the data set. UPDATE
does not, however, authorize a user to delete, rename, move, or
scratch the data set.
CONTROL For VSAM data sets, CONTROL is equivalent to the VSAM CONTROL
password; that is, it allows users to perform improved control interval
processing. This is control-interval access (access to individual VSAM
data blocks), and the ability to retrieve, update, insert, or delete
records in the specified data set. For non-VSAM data sets, CONTROL
is equivalent to UPDATE.

Chapter 2. z/OS Security Server RACF 59

2.34 Add a data set profile

Add a data set profile: ADDSD 'JAMES.*'

List the data set profile: LISTDSD 'JAMES.*'

INFORMATION FOR DATASET JAMES.* (G)

LEVEL OWNER UNIVERSAL ACCESS WARNING ERASE

O 00 JAMES NONE NO NO

U AUDITING
T FAILURES(READ)

P NOTIFY
NO USER TO BE NOTIFIED
U
YOUR ACCESS CREATION GROUP DATASET TYPE
T NONE SYS2 NON-VSAM

GLOBALAUDIT
NONE

NO INSTALLATION DATA

Figure 2-36 Add a data set profile

How to add a data set profile

When you define data set profiles to RACF, you can use either standard or nonstandard
naming conventions. If you use nonstandard naming conventions, the data set naming
convention table and the single-level data set names option are ways to help “fit” RACF
standard naming conventions.

The descriptions of naming conventions are followed by rules for protecting and allocating
user and group data sets.

By default, RACF expects a data set name (and the data set profile name) to consist of at
least two qualifiers. RACF also expects the high-level qualifier of the data set profile name to
be either a RACF-defined user or a RACF-defined group name.

This command added a generic profile for data sets with a high level qualifier of JAMES.*.
The asterisk (*) character is a valid generic character for more than one character in this
position.
ADDSD 'JAMES.*'

Figure 2-36 shows sample output from the LISTDSD command.

60 ABCs of z/OS System Programming Volume 6

2.35 Alter a data set profile

Alter a data set profile:

ALTDSD 'JAMES.*' AUDIT(S(U),F(R))
List the data set profile: LISTDSD 'JAMES.*'
INFORMATION FOR DATASET JAMES.* (G)

LEVEL OWNER UNIVERSAL ACCESS WARNING ERASE

00 JAMES NONE NO NO
O
U AUDITING
SUCCESS(UPDATE),FAILURES(READ)
T
P NOTIFY
NO USER TO BE NOTIFIED
U
T YOUR ACCESS CREATION GROUP DATASET TYPE
NONE SYS2 NON-VSAM

GLOBALAUDIT
NONE

NO INSTALLATION DATA

Figure 2-37 Alter a data set profile

How to alter a data set profile

Use the ALTDSD command to:
 Modify an existing discrete or generic data set profile.
 Protect a single volume of either a multivolume tape data set or a multivolume, non-VSAM
DASD data set. At least one volume must already be RACF-protected.
 Remove RACF-protection from either a single volume of a multivolume tape data set or a
single volume of a multivolume, non-VSAM DASD data set. You cannot delete the last
volume from the profile.

Figure 2-37 shows the output for the following command to alter the auditing options for the
previously data set, JAMES.*:
ALTDSD'JAMES.*' AUDIT(S(U),F(R))

The command also specifies which new access attempts you want to log to the SMP data set.
SUCCESS S(U) Indicates that you want to log authorized accesses to UPDATE
FAILURES F(R) Indicates that you want to log detected unauthorized access attempts
to read

Figure 2-37 shows a sample output from the ALTDSD command, which shows the auditing
options as:
SUCCESS(UPDATE),FAILURE(READ)

Chapter 2. z/OS Security Server RACF 61

2.36 Search RACF database using a mask

List the data set profile(s) matching a mask:

SEARCH MASK(JAMES) CLASS(DATASET)

O
U JAMES.PRIVATE.RECORDS
T JAMES.PRIVATE.* (G)
discrete
P JAMES.* (G)
U
T generic

Can be used for all other resouces

Similar command: FILTER
SEARCH MASK(JAMES) CLASS(DATASET)

Figure 2-38 Search the RACF database

List a data set profile matching a mask

The SEARCH command obtains a list of RACF profiles, users, and groups from the RACF
DATABASE using search criteria specified.

MASK specifies the strings of alphanumeric characters used to search the RACF database.
This data defines the range of profile names selected. The two-character strings together
must not exceed 44 characters for a tape or DASD data set name, or, for general resource
classes, the length specified in the class descriptor table.

The visual shows a SEARCH command with the search criteria, MASK.
SEARCH MASK(JAMES) CLASS(DATASET)

This command allows RACF to list profiles starting with the MASK, in this case JAMES.

A second example allows RACF to list all profiles containing the filter string.
SEARCH FILTER(JAMES) CLASS(DATASET)

62 ABCs of z/OS System Programming Volume 6

2.37 Data set related commands

List the cataloged data set(s) protected by a profile:

LISTDSD 'JAMES.*' DSNS

I NFORMATI ON FOR DATASET JAMES. * ( G)

LEVEL OWNER UNI VERSAL ACCESS WARNI NG ERASE

00 J AMES NONE NO NO
O
U AUDI TI NG
SUCCESS( UPDATE) , FAI LURES( READ)
T ...
...
P
U CATALOGUED DATA SETS AFFECTED BY PROFI LE CHANGE
-----------------------------------------------
T JAMES. PGMLI B
JAMES. WORK. EXEC

Figure 2-39 List a data set

List a cataloged data set

Figure 2-39 shows sample output from the following LISTDSD command, which allows RACF
to list data sets protected by a profile (in this case, the JAMES.* data set profile):
LISTDSD'JAMES.*'DSNS

DSNS specifies that you want to list the cataloged data sets protected by the profile specified
in the DATASET, ID, or PREFIX operand.

Chapter 2. z/OS Security Server RACF 63

2.38 Data set related commands

Allow access to a data set profile:

PERMIT 'JAMES.*' ID(BILL,DESIGN)
ACCESS(UPDATE)
PERMIT 'JAMES.*' ID(PAT) ACCESS(READ)
List the data set profile access list:
LISTDSD 'JAMES.*' AUTHUSER
INFORMATION FOR DATASET JAMES.* (G)
...
O ...
DESIGN
- MARK
U ID ACCESS
- LAURIE
- WALT
T -------- -------
BILL UPDATE
P DESIGN UPDATE
U PAT READ

T ID ACCESS CLASS ENTITY NAME

-------- ------- -------- -----------------
NO ENTRIES IN CONDITIONAL ACCESS LIST

Figure 2-40 List who has access to a data set

List who has access to a data set profile

Figure 2-40 shows sample output from the following PERMIT command:
PERMIT 'JAMES.*' ID(BILL,DESIGN) ACCESS(UPDATE)DSNS

This command allows Bill and the DESIGN group update access to the files protected by the
James.* data set profile. Mark, Laurie, and Walt part of the DESIGN group will have UPDATE
access, unless the access list contains their user ID with another level of access.
PERMIT 'JAMES.*' ID(PAT) ACCESS(READ)DSNS

Pat has read access to the files that are protected by the JAMES.* profile.

64 ABCs of z/OS System Programming Volume 6

2.39 General resources related commands

Add a general resource profile:

RDEF PROGRAM MYMUSIC
ADDMEM('JAMES.PGMLIB'/VOL123/NOPADCHK)
List the data set profile: RL PROGRAM MYMUSIC
CLASS NAME
----- ----
PROGRAM MYMUSIC

O MEMBER CLASS NAME

------ ----- ----
U PMBR

T DATA SET NAME VOLSER PADS CHECKING

P -------------------------------------------- ------ -------------

JAMES.PGMLIB VOL123 NO

U LEVEL OWNER UNIVERSAL ACCESS YOUR ACCESS WARNING

T ----- -------- ---------------- ----------- -------

00 JAMES NONE NONE NO

INSTALLATION DATA
-----------------
NONE .../...

Figure 2-41 Add a general resource profile

How to add a general resource profile

Figure 2-41 shows sample output from the following RDEFINE command, which defines a
new resource profile called MYMUSIC that will run in PROGRAM class:
RDEF PROGRAM MYMUSIC ADDMEM('JAMES.PGMLIB'/VOL123/NOPADCHK)

The program MYMUSIC is located in JAMES.PGMLIB member on DASD volume VOL123.

Setting NOPADCHK means that RACF will not check for program-accessed data sets when a
user is executing the control programs.

Chapter 2. z/OS Security Server RACF 65

2.40 General resources related commands

Alter a general resource profile:

RALT PROGRAM MYMUSIC UACC(READ)
List the data set profile: RL PROGRAM MYMUSIC
CLASS NAME
----- ----
PROGRAM MYMUSIC
...
O ...
DATA SET NAME VOLSER PADS CHECKING
U ------------------------------------- ------ -------------
T JAMES.PGMLIB VOL123 NO

P LEVEL OWNER UNIVERSAL ACCESS YOUR ACCESS WARNING

----- -------- ---------------- ----------- -------
U 00 JAMES READ READ NO
T INSTALLATION DATA
-----------------
NONE
...

Figure 2-42 Change universal access authority

How to change universal access authority

Figure 2-42 shows sample output from the following RALTER command, which sets the
Universal Access Authority (UACC) to read:
RALT PROGRAM MYMUSIC UACC(READ)

The UACC is the default access to a resource if the user or group is not specifically permitted
access to the resource. The ALTER command has set the default access of MYMUSIC at
READ.

66 ABCs of z/OS System Programming Volume 6

2.41 General resources related commands

Allow access to a general resource profile:

PERMIT MYMUSIC CLASS(PROGRAM) ID(MARVIN)
ACCESS(NONE)
List the data set profile access list:
RL PROGRAM MYMUSIC AUTHUSER
CLASS NAME
----- ----
PROGRAM MYMUSIC
O Specifically
Disallow
U MEMBER CLASS NAME
------ ----- ----
Access

T PMBR
...
P ...
ID ACCESS
U -------- -------
T MARVIN NONE

ID ACCESS CLASS ENTITY NAME

-------- ------- -------- -----------------
NO ENTRIES IN CONDITIONAL ACCESS LIST

Figure 2-43 Permit access to a resource

How to permit access to a resource profile

Figure 2-43 shows sample output from the PERMIT command:
PERMIT MYMUSIC CLASS(PROGRAM) ID(MARVIN) ACCESS(NONE)

Despite the UACC(READ) on the resource profile, MARVIN cannot access the resource
because NONE is specified in the access list.

Chapter 2. z/OS Security Server RACF 67

2.42 SET RACF system options

SETROPTS - set system-wide RACF

options
PASSWORD rules: syntax, historic,
number of attempts, etc. SYSTEM
OPTIONS
CLASSACT: activate new classes
RACLIST(classname) REFESH:
update in-storage information

Authorization required

Shareable among systems

Figure 2-44 SET RACF system options

SETROPTS command
RACF provides many system-wide options for controlling the way it works on your system.
You specify most of these options by issuing the SETROPTS command with the appropriate
operands. One example is to set the system-wide valid password interval:
SETROPTS PASSWORD INTERVAL(30)

The INTERVAL suboperand specifies the system default for the number of days that the
user’s password is to remain valid. The example specifies that each user’s password remains
valid for 30 days.

CLASSACT parameter
When you install a new RACF system, initially only a few RACF classes are active (for
example USER, GROUP, and DATASET), other classes (for example TAPEVOL and
TSOPROC) are inactive. For example, if you want your tape volumes to be protected by
RACF, you have to activate the TAPEVOL class using the following command:
SETROPTS CLASSACT(TAPEVOL)

RACLIST REFRESH parameter

The system options are stored in the RACF database and if your installation has activated
SETROPTS RACLIST processing for a particular resource class, the information is stored in

68 ABCs of z/OS System Programming Volume 6

in-storage profiles too. Using the SETROPTS command with the REFRESH parameter
allows these profiles to be updated dynamically.

The following example updates the profile in the class TSOPROC dynamically:
SETROPTS RACLIST(TSOPROC) REFRESH

Authorization
The SETROPTS command is very powerful and, therefore, most of the options require the
SPECIAL attribute.

Note: For further information about the required authority, refer toz/OS Security Server
RACF Command Language Reference, SA22-7687. The description for each RACF
command contains a heading called Authorization Required.

The following pages show some examples (but not all) of system-wide settings. They are
grouped to:
 STATISTIC related options
 PASSWORD options
 Data set related options
 CLASS related options
 AUTHORIZATION Checking options
 TAPE related options
 Other initial setup related options
 Security Label related options
 AUDITOR related options

Chapter 2. z/OS Security Server RACF 69

2.43 Statistic related options

Activating statistics Collection

(STATISTICS)
SYSTEM
Activating statistics for user verification OPTIONS

(INITSTATS)
Revoking unused user IDs (INACTIVE)

Figure 2-45 Statistic related options

An installation can record two types of RACF statistics:

 STATISTICS, which records access to resources in specific classes that are protected by
discrete profiles
 INITSTATS, which records user logon information

Activating statistics collection (STATISTICS option)

For some reasons (for example if a specific resource has unique security concerns and,
therefore, is protected by a discrete profile) it might be useful to have statistic data about a
resource concerning how that resource is being accessed and how many times it is being
accessed. The SETROPTS STATISTICS options provides this information. RACF maintains
two sets of statistics in a discrete resource profile. One set counts all activity for the resource
or profile. The other set counts activity for each entry in the access list. The following
command turns STATISTICS on for the resources in the class TSOPROC:
SETROPTS STATISTICS(TSOPROC)

Attention: Remember that the initiation of STATISTICS is system-wide for all discrete
profiles within a particular resource class across your system. Depending on the number of
discrete profiles in the various resource classes, turning on STATISTICS can negatively
affect performance.

70 ABCs of z/OS System Programming Volume 6

When a new RACF database is initialized, the default is STATISTICS off (NOSTATISTICS) for
all classes.

Tip: It is recommended that you keep STATISTICS off until your installation has had an
opportunity to evaluate the need for STATISTICS versus the potential impact on
performance.

For details seez/OS Security Server RACF Systems Programmer’s Guide, SA22-7681.

Activating statistics for user verification (INITSTATS option)

When a new RACF database is initialized, the default is INITSTATS on. INITSTATS records
statistics on all user profiles in the system.

Note: Although INITSTATS affects performance because of I/O to the database, it is

recommended that INITSTATS stays on, because it allows you to use other options to
provide additional security at logon.

INITSTATS is required if your installation wants to take advantage of the following options:
 SETROPTS INACTIVE option
 SETROPTS PASSWORD option with parameter REVOKE, HISTORY, and WARNING

Revoking unused user IDs (INACTIVE option)

The INACTIVE operand of the SETROPTS command causes RACF to revoke the user’s right
to use the system if the user ID has remained unused beyond a specified number of days.
The following command causes RACF to revoke a user ID if it is unused for over 30 days:
SETROPTS INACTIVE(30)

If you issue the SETROPTS INACTIVE(30) command and if a user has not done any of the
following activities in 31 days, that user is considered revoked:
 Logged on
 Submitted a job
 Changed the user’s password by any method
 Attempted an unsuccessful logon
 Received a directed command or output from RACF

The INACTIVE option applies also to new RACF defined user IDs if the new user ID is not
used within the number of days specified by SETOPTS INACTIVE.

Note: The user is not actually revoked. RACF revokes the user the next time the user
attempts to enter the system.

Chapter 2. z/OS Security Server RACF 71

2.44 Password related options

SETROPTS PASSWORD
Allowing mixed-case passwords
SYSTEM
SYSTEM
Establishing syntax rules OPTIONS
OPTIONS

Setting the maximum and minimum change

interval

Extending password and user ID processing

warning in relation to change interval
password and password phrase history
revoking user IDs using consecutive incorrect
passwords or password phrases

Figure 2-46 Password related options

SETROPTS PASSWORD
The examples in this section show some of the SETROPTS PASSWORD parameter, which
gives you the possibility to specify system-wide options regarding passwords. An optional
password phrase can be used. Most of the information for password also controls password
phrases.

Allowing mixed-case passwords

By default, NOMIXEDCASE is in effect and mixed-case passwords are not supported.
Mixed-case passwords are more secure and harder to guess than uppercase passwords. You
can allow mixed-case passwords with the following command.
SETROPTS PASSWORD(MIXEDCASE)

Attention: If you want to allow mixed-case passwords, be sure that mixed-case content is
permitted by your password syntax rules.

Note: z/OS 1.7 is the first release that supports mixed-case passwords. If you share the
RACF database with downlevel systems that do not support mixed-case RACF passwords
or if you use a mix of applications that do and do not support mixed-case passwords, do
not activate the SETROPTS PASSWORD(MIXEDCASE) option.

72 ABCs of z/OS System Programming Volume 6

Establishing syntax rules
You can establish up to eight password syntax rules to verify that new passwords meet the
installation standards. These rules allow you to control:
 The minimum and maximum length of passwords
 The character content of installation-selected positions in the passwords

Note: Your changes will take effect for current users only when they change their
passwords. For new users, the changes will take effect when the new user logs on for the
first time.

Setting the maximum and minimum change interval

The INTERVAL suboperand specifies the system default for the maximum number of days
that a user’s password is to remain valid. The MINCHANGE suboperand specifies the system
default for the minimum number of days that must pass between a user’s password changes.
To specify that each user’s password remains valid for 45 days and that no user can change
passwords more often than every sever days, use the following command:
SETROPTS PASSWORD(INTERVAL(45) MINCHANGE(7))

Note: z/OS 1.7 is the first release that supports MINCHANGE. The installation default is
zero (0) days for minimum change interval. The value MINCHANGE(0) allows users to
change passwords more than once each day.

Extending password and user ID processing

The WARNING suboperand specifies when RACF issues a password expiration message
each time a user logs on to TSO or submits a batch job with a password within a specified
number of days (in the following example, five days) before the password expires:
SETROPTS PASSWORD(WARNING(5))

The HISTORY suboperand specifies the number of previous passwords (in the following
example, 10) that RACF saves and compares with an intended new password:
SETROPTS PASSWORD(HISTORY(10))

REVOKE specifies how many consecutive password verification attempts RACF permits
before it revokes a user ID on the next attempt:
SETROPTS PASSWORD(REVOKE(3))

Note: Option INITSTATS is prerequisite of the options WARNING, HISTORY, and

REVOKE.

Chapter 2. z/OS Security Server RACF 73

2.45 Data set related options

Activating Enhanced Generic Naming for the DATASET Class

(EGN)

RACF-Protecting All Data Sets (PROTECTALL) SYSTEM

SYSTEM
OPTIONS
OPTIONS
Bypassing Automatic Data Set Protection (NOADSP)

Preventing Access to Uncataloged Data Sets (CATDSNS)

Displaying and Logging Real Data Set Names (REALDSN)

Protecting Data Sets with Single-Qualifier Names (PREFIX)

Erasing Scratched or Released DASD Data (ERASE)

Protecting DFP-Managed Temporary Data Sets(TEMPDSN)

Figure 2-47 Data set related options

Enhanced generic naming for the DATASET class (EGN option)

When you first initialize the RACF data base, enhanced generic naming is not in effect
(NOEGN). Using the following command so that RACF allows you to specify the generic
character, double asterisks (**), in addition to the generic characters, asterisk (*) and
percentage (%).
SETROPTS EGN

Note: IBM strongly recommends that you do not deactivate enhanced generic naming
after data set profiles have been created while enhanced generic naming was active.

RACF-protecting all data sets (PROTECTALL option)

If PROTECTALL is active, a user can create or access a data set only if the data set is
RACF-protected. Use the following command to activate this option:
SETROPTS PROTECTALL

Note: Before activating this option, activate generic profile checking also for the DATASET
class as shown in the following command:
SETROPTS GENERIC(DATASET)

74 ABCs of z/OS System Programming Volume 6

PROTECTALL also has a warning option that allows the request even though the data set is
not protected but sends a warning message to the user and the MVS console. For example:
SETROPTS PROTECTALL(WARNING)

For further considerations on the PROTECTALL option, see z/OS Security Server RACF
Security’s Administrator’s Guide, SA22-7683.

Bypassing automatic data set protection (NOADSP option)

With the installation default ADSP operand in effect, RACF creates discrete data set profiles
automatically when users who have the ADSP attribute create new data sets.

Note: We recommend the NOADSP option because it reduces the number of data set
profiles in the RACF database. Using generic data set profiles is generally more efficient.

You can change the installation default using the following command:
SETROPTS NOADSP

Preventing access to uncataloged data sets (CATDSNS option)

You can use the CATDSNS operand of the SETROPTS command to keep users who do not
have the SPECIAL attribute from gaining access to data sets that DFP controls. These data
sets include system temporary data sets and data sets that are not cataloged. Users cannot
read data sets from tape, and they cannot read from or write to DASD data sets.

Note: Because of the big impact this option can have on data processing, it might be
reasonable to specify CATDSNS(WARNING) before you plan to activate it in failure mode.

Displaying and logging real data set names (REALDSN option)

Putting the REALDSN option into effect ensures that log printouts and operator messages
identify data sets by their real names rather than by the data set names that are created by
installation exit routines to conform to RACF naming conventions.

Protecting data sets with single-qualifier names (PREFIX option)

If your installation has data sets names consisting of only a single qualifier (that is,
single-level names) and if you want RACF to protect this data set, you have to specify the
PREFIX option:
SETROPTS PREFIX(myhlq)

RACF internally modifies single-qualifier names by adding the high-level qualifier (in this case
myhlq) when it processes requests for the data set. The prefix must be an existing group
name and cannot be the name used as the high-level qualifier of any actual data sets or data
set profiles.

Erasing scratched or released DASD data (ERASE option)

If erase-on-scratch is active and a DASD data set profile has the erase indicator set, ERASE
specifies that data management is to erase the contents of any scratched or released data
set extents that are part of a DASD data set protected by that profile.

Protecting DFP-managed temporary data sets

You can protect DFP-managed temporary data sets. Normally, these data sets are
considered protected from any accesses except by the job or session that created them and,

Chapter 2. z/OS Security Server RACF 75

 therefore, do not need to be protected by RACF. However, the following situations can leave a
temporary data set unprotected:
 A system failure
 An initiator failure or initiator termination by the FORCE command
 An automatic restart—between the failure and the restart

In these cases, if the TEMPDSN class is active, only users with the OPERATIONS attribute
can scratch any residual DFP-managed temporary data sets remaining on a volume.

Note: The user with the OPERATIONS attribute can access the data set only to scratch the
data set. No other access is allowed (such as would be allowed by READ or UPDATE
access authority to the data set).

To activate the TEMPDSN class, enter:

SETROPTS CLASSACT(TEMPDSN)

Important: Plan carefully when to activate the TEMPDSN class to avoid a situation where
current users or jobs are using temporary data sets. Otherwise, you might cause users or
jobs to receive an ABEND.

76 ABCs of z/OS System Programming Volume 6

2.46 Class related options

Activating General Resource Classes (CLASSACT)

Activating Generic Profile Checking and Generic
Command (GENRIC and GENCMD)
SYSTEM
SYSTEM
Processing Activating Global Access Checking (GLOBAL) OPTIONS
OPTIONS

Activate In-Storage Profile Processing (RACLIST and

GENLIST)
Refreshing In-Storage Profiles (REFRESH)
Restricting the Creation of General Resource Profiles
(GENERICOWNER)
Automatic Omission of Creator’s User ID from Access List
(NOADDCREATOR)

Figure 2-48 Class related options

Activating general resource classes (CLASSACT)

The system-wide security administrator specifies in which general resource classes RACF
provides access authorization checking.You can specify this option for selected general
resource classes with the CLASSACT operand of the SETROPTS command. The following
example shows how to specify RACF access authorization checking for the TERMINAL and
CONSOLE resource classes:
SETROPTS CLASSACT(TERMINAL CONSOLE)

Important: We do not recommend that you activate all RACF classes. Activate only those
classes that are important to your installation, because some classes have a default return
code of eight. Activate those classes only after you define the necessary profiles to allow
access to resources, using the following command:
SETROPTS NOCLASSACT(TERMINAL)

This NOCLASSACT operand indicates that RACF performs no access authorization

checking for the specified general resource classes.

Chapter 2. z/OS Security Server RACF 77

 Attention: If you activate a class using SETROPTS CLASSACT, RACF activates all
classes in the class descriptor table that have the same POSIT value as the class that you
specify. The same effect is true for the other class related options. Thus, we do not mention
this note in every topic. For details see z/OS Security Server RACF Command Language
Reference, SA22-7687

Activating generic profile checking and generic command processing

(GENRIC and GENCMD)
You can activate or deactivate generic profile checking and generic command processing on a
class-by-class basis. The following example shows how to activate generic profile checking
and generic command processing for the DATASET class:
SETROPTS GENERIC(DATASET)

Generic profile command processing is activated automatically for all classes for which
generic profile checking is activated.

NOGENERIC and NOGENCMD are in effect when a RACF database is first initialized using
IRRMIN00.

Tip: We recommend that you use generic profiles, if possible, to protect multiple resources
and, thus, to ease the administration. Consider issuing SETROPTS GENERIC(*) so that
generic profiles and generic command processing are usable in all classes.

The following command might be helpful in case of maintenance:

SETROPTS NOGENERIC(classname) GENCMD(classname)

For more information, see z/OS Security Server RACF Security’s Administrator’s Guide,
SA22-7683.

Activating global access checking (GLOBAL)

RACF provides global access checking to improve performance of RACF authorization
checking for selected resources. You can use global access checking for public resources that
are accessed frequently. The global access checking table is maintained in storage and is
checked early in the RACF authorization checking sequence. If an entry in the global access
checking table allows the requested access to a resource, RACF performs no further
authorization checking.

Attention: Because RACF performs global access checking before many of the other
kinds of access authority checks, such as security label checking or access list checking,
global access checking might allow access to a resource you are otherwise protecting. To
avoid a security exposure to a sensitive resource, do not create an entry in the global
access checking table for a resource that is protected by a profile containing a security
level, security category, or security label.

Important: When global access checking allows a request, RACF performs no logging
other than that requested by the SETROPTS LOGOPTIONS command. See also
“LOGOPTIONS: Activating auditing for access attempts by class” on page 90.

For further consideration before activation of global access checking, see z/OS Security
Server RACF Security’s Administrator’s Guide, SA22-7683.

78 ABCs of z/OS System Programming Volume 6

Activate in-storage profile processing (RACLIST and GENLIST)
In-storage profiles can help the administrator maximize performance of the RACF database.
RACF provides processing to activate in-storage profiles. The SETROPTS operands are
GENLIST and RACLIST.

Note: RACF does not allow you to specify SETROPTS GENLIST and SETROPTS
RACLIST for the same general resource class at the same time.

For more information about when to use RACLIST and GENLIST processing, see z/OS
Security Server RACF Systems Programmer’s Guide, SA22-7681. Classes for which
RACLIST processing is recommended are listed there.

Note: A general resource class must be active before you can activate SETROPTS
GENLIST or SETROPTS RACLIST processing for that class.

Refreshing in-storage profiles (REFRESH)

If your installation maintains in-storage copies of resource profiles through the SETROPTS
RACLIST or SETROPTS GENLIST command, changes to those profiles do not take effect on
the system until a SETROPTS RACLIST REFRESH or SETROPTS GENERIC REFRESH
command is issued. For details, see z/OS Security Server RACF Security’s Administrator’s
Guide, SA22-7683.

To activate refreshing of SETROPTS RACLIST processing for the TSOPROC and TSOAUTH
classes, use this command:
SETROPTS RACLIST(TSOPROC TSOAUTH) REFRESH
Restricting the creation of general resource profiles (GENERICOWNER)
RACF provides the possibility to restrict the creation of profiles in general resource
classes.You have to issue the SETROPTS GENERICOWNER command and define a double
asterisk (**) profile for the class with yourself as owner.

Note: The GENERICOWNER operand does not affect the DATASET class. It cannot be
activated for individual classes. When active, GENERICOWNER affects all general
resource classes except the PROGRAM class and general resource grouping classes.

Automatic omission of creator’s user ID from access list

(NOADDCREATOR)
The SETROPTS options ADDCREATOR and NOADDCREATOR allow you to specify whether
the user ID of the person who defines a resource profile is placed on the access list for that
resource automatically with ALTER authority. The following command causes RACF not to
place the profile creator’s user ID on the profile access list:
SETROPTS NOADDCREATOR

Note: We recommend that you use the NOADDCREATOR option. If the creating user
needs access to the profile being defined, then access to the profile should be done
separately, and if possible, by specifying a group and not an individual user ID.

Chapter 2. z/OS Security Server RACF 79

2.47 Authorization checking related options

Activating List-of-Groups Checking

(GRPLIST)
SYSTEM
Activating Program Control SYSTEM
OPTIONS

(WHEN(PROGRAM))
Activating Terminal Control
(TERMINAL(READ/NONE))

Figure 2-49 Authorization checking related options

Activating list-of-groups checking (GRPLIST)

A RACF defined user can be a member of different RACF groups. If list-of-groups checking is
activated, a user’s authority to access or define a resource is not based only on the authority
of the user’s current logon group. Access is based on the authority of any group to which the
user is connected.

Note: If list-of-groups checking is activated and if a user is in more than one group and
tries to access a resource, RACF uses the highest authority that is allowed by the user’s list
of groups and the resource’s access list.

NOGRPLIST is in effect when RACF is using a newly-initialized database. You can change
this option using the following command:
SETROPTS GRPLIST

Tip: We recommend that you use the GRPLIST option because it eases administration
and minimizes the number of times the user might have to log off and log back on to
access resources.

80 ABCs of z/OS System Programming Volume 6

Activating program control (WHEN(PROGRAM))
There are some specifics with the general resource class PROGRAM. One of these is the
kind how program control is activated using SETROPTS:
SETROPTS WHEN(PROGRAM)

When program control is active, RACF provides access control to load modules, and program
access sets and SERVAUTH resources.

Access control to load modules allows only authorized users to load and execute specified
load modules (programs). RACF uses profiles in the PROGRAM general resource class to
control access to programs.

Program access to data sets allows an authorized user or group of users to access specified
data sets in conjunction with the user’s authority to execute a certain program. That is, some
users can access specified data sets at a specified access level only while executing a certain
program.

Program access to SERVAUTH class resources allows an authorized user or group of users
to access certain IP addresses in conjunction with the user’s authority to execute a certain
program. That is, some users can access specified IP addresses at a specified access level
only while executing a certain program.

NOWHEN(PROGRAM) is in effect when a RACF database is first initialized using IRRMIN00.

Note: We recommend that you implement the general resource class PROGRAM from a
security point of view. There are a lot of system programmer related programs, for example
AMASPZAP or some RACF utilities, which should not be used by unauthorized users.

For details on program control, seez/OS Security Server RACF Security’s Administrator’s
Guide, SA22-7683.

Activating terminal control (TERMINAL(READ/NONE))

RACF provides the general resource class TERMINAL to control the use of terminals. The
system-wide option TERMINAL(READ) or TERMINAL(NONE) is used to set the universal
access authority (UACC) associated with undefined terminals.

The following command sets the TERMINAL class of resource in RACF to an active,
system-wide status:
SETROPTS CLASSACT(TERMINAL) TERMINAL(READ)

All subsystems that use RACF to control access to terminals now have terminal checking
active when this command is issued. The READ option of the TERMINAL operand indicates
how RACF is to view terminals that are not defined to RACF. READ indicates that if RACF
cannot find a profile for that terminal, access to the terminal is to be allowed.

To prevent undefined terminals from being used for logging on, use the following command:
SETROPTS TERMINAL(NONE)

Attention: Before you specify NONE, be sure that you define some terminals to RACF and
give the appropriate users and groups proper authorization to use them. Otherwise, no one
can log on to your system.

If your installation uses dynamic IP addresses instead of static VTAM defined terminal names,
it is not easy to administrate profiles in the RACF class TERMINAL.

Chapter 2. z/OS Security Server RACF 81

2.48 Tape related options

Activating Tape Data Set Protection

(TAPEDSN)
SYSTEM
Activating Tape Volume Protection SYSTEM
OPTIONS
OPTIONS

(TAPEVOL )
Establishing a Security Retention Period
for Tape Data Sets (RETPD)

Figure 2-50 Tape related options

RACF allows you to establish access requirements for both tape data sets and tape volumes.

Activating tape data set protection (TAPEDSN)

RACF provides means of tape data set protection if you use the TAPEDSN operand of the
SETROPTS command. When you activate tape data set protection, RACF refers to profiles in
the DATASET class when verifying a user’s access authority to a tape data set. The following
example shows how to specify this option:
SETROPTS TAPEDSN

NOTAPEDSN is in effect when a RACF database is first initialized using IRRMIN00. In this
case, RACF cannot protect individual tape data sets, although it can protect tape volumes.

Activating tape volume protection (TAPEVOL)

You can activate tape volume protection using the CLASSACT(TAPEVOL) operand of the
SETROPTS command. When you activate tape volume protection, RACF refers to profiles in
the TAPEVOL class when verifying a user’s access authority to a tape volume.

If both the TAPEVOL class and TAPEDSN are active, RACF maintains profiles in both the
TAPEVOL and DATASET classes. Data fields within these two profiles (data set name in the
TAPEVOL profile and volume serial in a discrete data set profile) link the two profiles to each
other. The following example shows how to activate tape volume protection:
SETROPTS CLASSACT(TAPEVOL)

82 ABCs of z/OS System Programming Volume 6

 Note: If your installation has a tape management system, you might consider running with
TAPEDSN active and TAPEVOL inactive. In this case, your tape management system, not
RACF, maintains tape volume security and controls access to tape volumes.

For more information, see “Choosing Which Tape-Related Options to Use” in z/OS Security
Server RACF Security’s Administrator’s Guide, SA22-7683.

Establishing a security retention period for tape data sets (RETPD)

The RACF security retention period is the number of days that RACF protection remains in
effect for a tape data set. RACF stores the value in the tape data set profile. If you specify
RETPD, you must also activate TAPEDSN. The following example shows how to specify a
RACF security retention period of 365 days:
SETROPTS RETPD(365)

Chapter 2. z/OS Security Server RACF 83

2.49 RVARYPW and other options for initial setup

RVARY command - background information

Importance
SYSTEM
SYSTEM
OPTIONS
Authorization required OPTIONS

Setting the RVARY passwords

(RVARYPW)
Activating JES2 or JES3 RACF Support
(JES)
Establishing National Language Defaults
(LANGUAGE)
Controlling Data Set Modeling (Model)

Figure 2-51 RVARYPW and other options for initial setup

RVARY command background information

This section provides some background information about the RVARY command.

Importance of the RVARY command

The RVARY command is a very important command for the system programmer and helpful
for maintenance of the RACF data base. With the RVARY command you can:
 Deactivate and reactivate the RACF function.
 Switch from using a specific primary data set to using its corresponding backup data set,
perhaps because of a failure that is related to the primary data set.
 Deactivate or reactivate primary or backup RACF data sets. (Deactivating a specific
primary data set causes all RACF requests for access to that data set to fail. Deactivating
a specific backup data set causes RACF to stop duplicating information about that data
set.)
 Deactivate protection for any resources belonging to classes defined in the class
descriptor table while RACF is inactive.
 Select the mode of operation when RACF is enabled for sysplex communication.

Authorization required
Unlike the SETROPTS command, the RVARY command needs no special user attribute for
the submitting user ID. However, the operator (at the operator console or security console)

84 ABCs of z/OS System Programming Volume 6

must approve the RVARY command unless it is a RVARY LIST before RACF allows the
command to complete.

If the RVARY command changes RACF or its database status (ACTIVE/INACTIVE), RACF
issues an informational message, and the operator is required to enter the password that is
defined by RVARYPW STATUS(status-pw) to authorize the change.

If the RVARY command switches the RACF data sets (SWITCH) or changes the RACF
operating mode (DATASHARE/NODATASHARE), RACF issues an informational message,
and the operator is required to enter the password that is defined by RVARYPW
SWITCH(switch-pw).

Setting the RVARY passwords (RVARYPW)

You use the SETROPTS command with the RVARYPW operand to specify the passwords
that are necessary for the RVARY command to succeed.

RACF allows you to specify separate passwords for switching the databases and for changing
RACF status. The following example specifies HAPPY as the switch password and RABBIT as
the status password:
SETROPTS RVARYPW(SWITCH(HAPPY) STATUS(RABBIT))

When RACF is first initialized, the switch password and the status password are both set to
YES.

Important: We strictly recommend to change the RVARY password, because of the

importance of the command. Otherwise, everyone reading RACF publications can
inactivate or influence security in your installation.

Activating JES2 or JES3 RACF support (JES)

The parameter JES of the SETROPTS command has several subcommands that control the
job entry subsystem (JES) options. The following subcommands are described in detail in
z/OS Security Server RACF Security’s Administrator’s Guide, SA22-7683, and z/OS Security
Server RACF Command Language Reference, SA22-7687:
BATCHALLRACF Forcing Batch Users to Identify Themselves to RACF
XBMALLRACF Support for Execution Batch Monitor (XBM) (JES2 Only)
EARLYVERIFY JES User ID Early Verification
NJEUSER Understanding Default User IDs
UNDEFINEDUSER Understanding Default User IDs

Establishing national language defaults (LANGUAGE)

With the LANGUAGE option of the SETROPTS command, you can specify the system-wide
defaults for national languages (such as American English or Japanese) that your system
uses. You can specify a primary language, a secondary language, or both. The languages
that you specify depend on which products, when installed on your system, check for primary
and secondary languages (using RACROUTE REQUEST=EXTRACT).

To specify the installation default languages, enter:

SETROPTS LANGUAGE(PRIMARY(language1) SECONDARY(language2))

Chapter 2. z/OS Security Server RACF 85

 Note: The SETROPTS LANGUAGE operand does not affect the language in which the
RACF ISPF panels are displayed. The order in which the RACF ISPF panel libraries are
allocated determines the language that is used. If your installation ordered a translated
feature of RACF, the RACF program directory gives instructions for setting up the ISPF
panels.

Controlling data set modeling (Model)

The MODEL operand of the SETROPTS command allows you to supplement the information
that is normally placed in new data set profiles automatically by ADSP, PROTECT=YES, or
ADDSD.

NOMODEL is in effect when a RACF database is first initialized using IRRMIN00.

Note: The FROM(profile-name) operand on the ADDSD command overrides any

specifications from the MODEL(USER) or MODEL(GROUP) operands.

86 ABCs of z/OS System Programming Volume 6

2.50 Auditor related options(1)

AUDITOR Authorization required

General Audit controls for RACF
commands SYSTEM
OPTIONS

AUDIT: Logging RACF commands and

DEFINE requests
CMDVIOL: Logging RACF command violations
SAUDIT: Logging activities of users with the
SPECIAL attribute

Figure 2-52 Auditor related options(1)

AUDITOR authorization required

There are several system-wide audit controls using the SETROPTS command. General audit
controls direct RACF to log (or not to log) certain security-relevant events. To specify the
general audit controls, you must have the AUDITOR attribute.

This section describes the auditor control options which refer to security events in conjunction
with RACF commands.

AUDIT: Logging RACF commands and DEFINE requests

RACF provides means to specify individually for which classes RACF logs all detected
accesses to the RACF database through RACF commands and DEFINE requests. You can
specify the AUDIT operand on the SETROPTS command. Logging becomes effective
immediately. The following example specifies that you want RACF to log RACF commands
and define requests for users, groups, data sets, and the TERMINAL general-resource
classes.
SETROPTS AUDIT(USER GROUP DATASET TERMINAL)

If you specify AUDIT(*), logging occurs for all classes.

You deactivate logging for a class using the NOAUDIT operand. NOAUDIT(*) is in effect when
RACF is using a newly-initialized database.

Chapter 2. z/OS Security Server RACF 87

 Note: If you activate auditing for a class using SETROPTS AUDIT, RACF activates auditing
for all classes in the class descriptor table that have the same POSIT value as the class
you specify. For details, see z/OS Security Server RACF Command Language Reference,
SA22-7687.

CMDVIOL: Logging RACF command violations

A command violation can occur because RACF does not authorize a user to modify a
particular profile or to enter a particular operand on a command. If you specify the CMDVIOL
operand on the SETROPTS command, RACF logs all command violations (except for
LISTDSD, LISTGRP, LISTUSER, RLIST, and SEARCH, which are never logged). CMDVIOL
is in effect at RACF initialization.

Tip: We recommend that you keep CMDVIOL active and cause RACF to log all the
command violations that it detects. You can then use the RACF report writer to produce a
printed audit trail of command violations. You can determine how many command
violations are occurring and which users are causing the violations. A significant number of
command violations, especially when RACF is first installed, can indicate the need for
more user education. The report can also help you to identify any specific users who are
trying persistently to alter profiles without the proper authority.

If you decide to bypass logging of all violations that are detected by RACF commands (except
RVARY and SETROPTS, which are always logged) during RACF command processing, you
can specify the NOCMDVIOL operand on the SETROPTS command as shown in the
following example:
SETROPTS NOCMDVIOL

SAUDIT: Logging of activity of users with the SPECIAL attribute

The SETROPTS option SAUDIT specifies that RACF is to log RACF commands (except
LISTDSD, LISTGRP, LISTUSER, RLIST, and SEARCH) issued by users who either had the
SPECIAL attribute or who gained authority to issue the command through the
group-SPECIAL attribute. SAUDIT is in effect when RACF is using a newly initialized
database.

Tip: We recommend that you specify SAUDIT, because of the powerful commands a
SPECIAL user can submit. You can then use the RACF report writer to produce audit
reports.

If you decide to bypass this logging (for example, if you are concerned only with how
SPECIAL users change profiles and you have AUDIT(*) in effect), you can use the following
command:
SETROPTS NOSAUDIT

88 ABCs of z/OS System Programming Volume 6

2.51 Auditor related options(2)

AUDITOR Authorization required

General Audit controls for resource access:
SYSTEM
SYSTEM
OPERAUDIT: Logging activities of users with OPTIONS

the OPERATIONS attribute

LOGOPTIONS: Activating auditing for access
attempts by class
APPLAUDIT: Auditing for APPC/MVS
SECLABELAUDIT: Activating auditing for
security labels
SECLEVELAUDIT: Activating auditing for
security levels

Figure 2-53 Auditor related options(2)

AUDITOR authorization required

There are further system-wide audit controls using the SETROPTS command for which the
AUDITOR attribute is needed. This section describes the auditor control options which refer to
security events in conjunction with access to resources.

OPERAUDIT: Logging activities of users with the OPERATIONS attribute

The SETROPTS option OPERAUDIT specifies that RACF is to audit all accesses to
resources granted and all uses of the ADDSD, and RDEFINE commands allowed only
because the user has the OPERATIONS or group-OPERATIONS attribute. Without the
OPERATIONS attribute, the access is denied, because the user is not authorized over the
access list. The following example shows how to specify this option:
SETROPTS OPERAUDIT

NOOPERAUDIT is in effect at RACF initialization.

Tip: OPERAUDIT might be useful if you decide to remove the OPERATIONS attribute and
give those users access through the normal access list. You can then use the RACF report
writer or other auditing tools to produce a report on this events.

Chapter 2. z/OS Security Server RACF 89

 LOGOPTIONS: Activating auditing for access attempts by class
With the LOGOPTION operand you can cause RACF to audit attempts of accessing
resources in specified classes (whether or not successful). There are different options
available. You can specify the DATASET class and any active classes in the class descriptor
table. The resources need not have profiles created in order for the auditing to occur. The
following command specifies that auditing is to be done for all attempts to access the
TERMINAL class:
SETROPTS LOGOPTIONS(ALWAYS(TERMINAL))

In this case, auditing is done every time a user logs on at any terminal on the system,
regardless of whether that terminal is protected by a profile and regardless of whether that
profile specifies auditing. You can specify that auditing be done for the following conditions:
ALWAYS All attempts to access resources protected by the class are audited.
NEVER No attempts to access resources protected by the class are audited. (All
auditing is suppressed.)
SUCCESSES All successful attempts to access resources protected by the class are
audited.
FAILURES All failed attempts to access resources protected by the class are audited.
DEFAULT Auditing is controlled by the profile protecting the resource, if a profile exists.
You can specify DEFAULT for all classes by specifying an asterisk (*) with
DEFAULT.

Note: The SUCCESSES and FAILURES operands result in auditing in addition to any
auditing that is specified in profiles in the class. In contrast, the ALWAYS and NEVER
operands override any auditing specified in profiles in the class.

Note: When RACF grants access to a resource because of an entry in the global access
checking table, RACF does not log the event even if you request logging.

LOGOPTIONS(DEFAULT(*)) is in effect at RACF initialization.

APPLAUDIT: Auditing for APPC/MVS

Specifying the APPLAUDIT parameter on the SETROPTS command, you can request
auditing of APPC transactions. NOAPPLAUDIT is in effect at RACF initialization. See z/OS
Security Server RACF Auditor’s Guide, SA22-7684, for more information.

SECLABELAUDIT: Activating auditing for security labels

The SECLABELAUDIT option of the SETROPTS command specifies that the SECLABEL
profile’s auditing options are to be used in addition to the auditing options specified for the
user or resource. NOSECLABELAUDIT is in effect when RACF is using a newly-initialized
database. For more information, refer to z/OS Security Server RACF Auditor’s Guide,
SA22-7684.

SECLEVELAUDIT: Activating auditing for security levels

The SECLEVELAUDIT (security-level) operand of the SETROPTS command activates
auditing of access attempts to all RACF-protected resources based on the specified
installation-defined security level. RACF audits all access attempts for the specified security
level and higher. You can specify only a security level name defined by your installation as a
SECLEVEL profile in the SECDATA class. (For information about defining security levels, see

90 ABCs of z/OS System Programming Volume 6

the description of the RDEFINE and RALTER commands in z/OS Security Server RACF
Command Language Reference, SA22-7687.)

The NOSECLEVELAUDIT operand deactivates auditing of access attempts to

RACF-protected resources based on a security level. NOSECLEVELAUDIT is in effect when
RACF is using a newly-initialized database.

Chapter 2. z/OS Security Server RACF 91

2.52 SETROPTS: Display options (LIST)

SETROPTS LIST example:

ATTRIBUTES = INITSTATS WHEN(PROGRAM) SAUDIT CMDVIOL OPERAUDIT

STATISTICS = NONE
AUDIT CLASSES = DATASET USER GROUP DASDVOL GDASDVOL TAPEVOL DSNR
ACTIVE CLASSES = DATASET USER GROUP DASDVOL GDASDVOL TAPEVOL TIMS GIMS
AIMS DSNR TCICSTRN GCICSTRN PCICSPSB QCICSPSB FACILITY
GENERIC PROFILE CLASSES = DATASET DASDVOL TAPEVOL DSNR FACILITY OPERCMDS
AUTOMATIC DATASET PROTECTION IS NOT IN EFFECT
PROTECT-ALL IS ACTIVE, CURRENT OPTIONS:
PROTECT-ALL WARNING OPTION IS IN EFFECT
TAPE DATA SET PROTECTION IS ACTIVE
INACTIVE USERIDS ARE NOT BEING AUTOMATICALLY REVOKED.
PASSWORD PROCESSING OPTIONS:
PASSWORD CHANGE INTERVAL IS 62 DAYS.
6 GENERATIONS OF PREVIOUS PASSWORDS BEING MAINTAINED.
AFTER 4 CONSECUTIVE UNSUCCESSFUL PASSWORD ATTEMPTS,
A USERID WILL BE REVOKED.
PASSWORD EXPIRATION WARNING LEVEL IS 7 DAYS.
INSTALLATION PASSWORD SYNTAX RULES:
RULE 1 LENGTH(6:8) ********
LEGEND:
A-ALPHA C-CONSONANT L-ALPHANUM N-NUMERIC V-VOWEL W-NOVOWEL *-ANYTHING

Figure 2-54 SETROPTS: Display options (LIST)

SETROPTS LIST command

This command specifies that the current RACF options are displayed. If you specify operands
in addition to LIST on the SETROPTS command, RACF processes the other operands before
it displays the current set of options.

If RACF is enabled for sysplex communication and the system is in read-only mode, users on
that system can issue the SETROPTS LIST command. All other operands are ignored.

You must have the RACF SPECIAL, AUDITOR, group-SPECIAL, or group-AUDITOR attribute
to enter the LIST operand.

If you have the SPECIAL or group-SPECIAL attribute, and not the AUDITOR or
group-AUDITOR, RACF displays all operands except the auditing related operands.

Figure 2-54 shows sample output from the following SETROPTS command:
SETROPTS LIST

92 ABCs of z/OS System Programming Volume 6

2.53 RACF monitoring

Immediate notification of security events

Dynamic messages to security console

Unauthorized attempt to access system
Unauthorized attempt to access resource A
A B C

Invalid RACF operations D F

Optionally sent to the resource owner

Message information MONITOR
E !!
WHO user or job is
WHAT user/job attempted to do

Figure 2-55 RACF monitoring

RACF monitoring
For more immediate action, the user can request notification to the master terminal at the
time of violation. A non-zero value for the SECCNT keyword of the SECURITY macro causes
the master terminal to be notified.

Because the number of violations for a large network can be high due to misspelled
passwords, transaction codes, and commands, you can specify a threshold for notification.
The master terminal is not notified until the specified number of violations occur without a
valid input from a given terminal. You specify one to three invalid entries as the violation limit,
eliminating or reducing the number of notifications that are caused merely by operator error,
while still providing evidence of real attempts to avoid security safeguards.

Chapter 2. z/OS Security Server RACF 93

2.54 RACF monitoring

Immediate notification of security events

Examples:
Unauthorized attempt to access system:
ICH408I USER(JAMES ) GROUP(MFG ) NAME(BROWN JAMES )
LOGON/JOB INITIATION - INVALID PASSWORD ENTERED AT TERMINAL ABCDE123

ICH408I USER(JAMES ) GROUP(MFG ) NAME(ELECTIONS )

LOGON/JOB INITIATION - REVOKED USER ACCESS ATTEMPT

WHO Unauthorized attempt to access resource: WHAT

ICH408I USER(JAMES ) GROUP(MFG ) NAME(BROWN JAMES )
MARVIN.MAIN.CLIST CL(DATASET ) VOL(VOLXYZ)
INSUFFICIENT ACCESS AUTHORITY FROM MARVIN.* (G)
ACCESS INTENT(READ ) ACCESSALLOWED(NONE )

Figure 2-56 RACF monitoring example

Example of RACF immediate notification: Example 1

The explanation of the RACF message ICH408I is as follows:
ICH408I USER(userid) GROUP(group-name) NAME(user-name)

This message is issued when RACF detects an unauthorized request (a violation) made by a
user or job. The user and group indicated in the first line of the ICH408I message are the
execution user ID and group ID under which the job was to run.

94 ABCs of z/OS System Programming Volume 6

2.55 RACF monitoring

Immediate notification of security events

Examples:
Invalid RACF operations:
ICH408I USER(JAMES ) GROUP(MFG ) NAME(BROWN JAMES )
FULL VIOLATION ON COMMAND ALTDSD

ICH408I USER(JAMES ) GROUP(MFG ) NAME(BROWN JAMES )

PARTIAL VIOLATION ON COMMAND SETROPTS

WHO WHAT
Optionally sent to the resource owner:
ICH70004I USER(JAMES) GROUP(MFG) NAME(BROWN JAMES)
ICH70004I ATTEMPTED 'READ' ACCESS OF
ICH70004I ENTITY 'MARVIN.MAIN.CLIST
ICH70004I IN CLASS 'DATASET' AT 19:38:45 ON FEBRUARY 15, 1999

Figure 2-57 RACF immediate notification example

Example of RACF immediate notification: Example 2

The RACF message ICH70004I is as follows:
ICH70004I USER(accessor) GROUP(group-name)
NAME(user-name) ATTEMPTED 'access-type' ACCESS
OF ENTITY 'resource-name' IN CLASS 'class-name' AT
hh:mm:ss ON month day, year.

This message alerts a RACF user that an access violation has occurred against the indicated
resource. This message is routed to the user specified in the NOTIFY field of the resource
profile that denied the access.

Chapter 2. z/OS Security Server RACF 95

2.56 RACF auditing tools

Delayed investigations about security events

Auditing Tools:
Data Security Monitor (DSMON)
RACF Data Unload Utility (IRRDBU00)
Security data

SMF Data Unload Utility (IRRADU00)

RACF Report Writer (RACFRW)
Security events

Figure 2-58 RACF auditing tools

RACF auditing tools

RACF auditing is basically verifying that the principals set forth by the installations security
policy are not compromised. The issue with auditing is being able to reduce the amount of
information to something that can be easily analyzed.

Two types of auditing data exist:

 Security data content from the RACF database, which is a static image or a snapshot of
the system parameters at any one time.
 Security events data statistical information, such as the date, time, and the number of
times a specific resource was accessed by any one user.

RACF writes security log records when it detects:

 Unauthorized attempts to enter the system
 Authorized or unauthorized attempts to enter RACF commands
 RACF status changes
 Warning mode resource access attempts
 Failsoft operator access decisions
 Optional authorized or unauthorized attempts to access RACF-protected resources

96 ABCs of z/OS System Programming Volume 6

You can list the contents of these records to help you to detect possible security exposures or
threats and verify the security of the system.

Each of the following programs can help you accomplish your goals, depending on your
specific needs:
 SMF data unload utility
 RACF data unload utility
 RACF report writer
 Data security monitor (DSMON)

Chapter 2. z/OS Security Server RACF 97

2.57 RACF auditing - IRRADU00

SMF Unload Utility (IRRADU00

program):

Enables creation of sequential file from

security relevant audit events
RACF SMF
Allows processing of complex inquiries records
on SMF records in different ways

Allows creation of installation-tailored

reports

Figure 2-59 SMF unload utility

SMF data unload utility (IRRADU00 program)

The system management facility (SMF) data unload utility processes SMF records and
permits more complex auditing than the RACF report writer. Output from the SMF data
unload utility can be:
 Viewed directly
 Used as input for installation-written programs
 Manipulated by sort or merge utilities
 Uploaded to a database manager, such as DB2

You can process complex inquiries and generate custom-tailored reports from the output of
the SMF data unload utility. These reports can be useful in identifying suspicious patterns of
access by authorized users that another program might miss. Because data is more often
misused by authorized users than stolen by unauthorized users, reports such as this are
essential to security.

98 ABCs of z/OS System Programming Volume 6

2.58 RACF auditing

SMF Unload Utility output example:

JOBINIT SUCCESS 13:31:44 1996-10-08 9672 ADMIN
JOBINIT SUCCESS 13:31:46 1996-10-08 9672 ADMIN
JOBINIT SUCCESS 13:31:47 1996-10-08 9672 ADMIN
JOBINIT TERM 13:31:48 1996-10-08 9672 ADMIN
JOBINIT TERM 13:31:48 1996-10-08 9672 ADMIN
JOBINIT TERM 13:31:48 1996-10-08 9672 ADMIN
SETROPTS INSAUTH 13:39:12 1996-10-08 9672 YES NO NO JAMES MFG NO NO NO NO
ALTUSER SUCCESS 13:40:12 1996-10-08 9672 NO NO NO JAMES MFG NO YES NO NO
JOBINIT SUCCESS 13:40:46 1996-10-08 9672 JAMES MFG
SETROPTS SUCCESS 13:41:46 1996-10-08 9672 NO NO NO JAMES MFG NO NO NO YES
SETROPTS SUCCESS 13:42:17 1996-10-08 9672 NO NO NO JAMES MFG NO YES NO YES
DIRSRCH SUCCESS 13:43:11 1996-10-08 9672 NO NO NO ARTHUR FINC YES NO NO NO
DIRSRCH SUCCESS 13:43:11 1996-10-08 9672 NO NO NO ARTHUR FINC YES NO NO NO
DIRSRCH NOTAUTH 13:43:11 1996-10-08 9672 YES NO NO ARTHUR FINC YES NO NO NO
CHKFOWN OWNER 13:44:28 1996-10-08 9672 NO NO NO REBECCA SYS1 NO NO NO NO
CHMOD SUCCESS 13:44:28 1996-10-08 9672 NO NO NO REBECCA SYS1 NO NO NO NO
CHOWN SUCCESS 13:44:28 1996-10-08 9672 NO NO NO REBECCA SYS1 NO NO NO NO
FACCESS SUCCESS 13:44:28 1996-10-08 9672 NO NO NO REBECCA SYS1 NO NO NO NO
JOBINIT SUCCESS 13:44:30 1996-10-08 9672 REBECCA
SETEUID SUCCESS 13:44:31 1996-10-08 9672 NO NO NO REBECCA SYS1 NO NO NO NO
DIRSRCH SUCCESS 13:44:31 1996-10-08 9672 NO NO NO REBECCA SYS1 NO NO NO NO
DIRSRCH SUCCESS 13:44:31 1996-10-08 9672 NO NO NO REBECCA SYS1 NO NO NO NO
SMF Unload Utility

Figure 2-60 SMF unload utility example

How to run the SMF data unload utility (IRRADU00)

A RACF SMF data unload utility sample JCL is as follows:
//KHEWITT1 JOB (ITSO),'SMF FLAT',MSGCLASS=X
//SMFDUMP EXEC PGM=IFASMFDP
//SYSPRINT DD SYSOUT=*
//ADUPRINT DD SYSOUT=*
//OUTDD DD DISP=(NEW,CATLG),DSN=KHEWITT.RACF.IRRADU00,
// UNIT=SYSDA,SPACE=(CYL,(10,5),RLSE),
// LRECL=5096,RECFM=VB
//SMFDATA DD DISP=SHR,DSN=SYS1.SC42.MAN2
//SMFOUT DD DUMMY
//SYSIN DD *
INDD(SMFDATA,OPTIONS(DUMP))
OUTDD(SMFOUT,TYPE(000:255))
ABEND(NORETRY)
USER2(IRRADU00)
USER3(IRRADU86)
//SYSIN DD DUMMY

Chapter 2. z/OS Security Server RACF 99

 To display the active SMF data set, use the D SMF command from the system console as
follows:
IEE974I 10.12.27 SMF DATA SETS 796
NAME VOLSER SIZE(BLKS) %FULL STATUS
P-SYS1.SC42.MAN1 MVS004 1200 0 ALTERNATE
S-SYS1.SC42.MAN2 MVS004 1200 86 ACTIVE
S-SYS1.SC42.MAN3 MVS004 1200 0 ALTERNATE

MAN2 is the active SMF data set.

The output file in this example is KEWITT.RACF.IRRADU00.

100 ABCs of z/OS System Programming Volume 6

2.59 RACF auditing

RACF Report Writer (RACFRW):

Allows report generation from

SMF records RACF SMF
records

Figure 2-61 RACF report writer

RACF report writer

The RACF report writer lists the contents of SMF records in a format that is easy to read. It
also uses the same SMF data to generate the following specialized reports:
 Reports that describe attempts to access a particular RACF-protected resource in terms
of user identity, number and type of successful accesses, and number and type of
attempted security violations.
 Reports that describe user and group activity.
 Reports that summarize system use and resource use.

The RACF report writer is stabilized at the RACF 1.9.2 level, and is not able to report on many
of the later RACF functions.

Chapter 2. z/OS Security Server RACF 101

2.60 RACF auditing

RACF Report Writer report example:

199.049 00:24:29 RACF REPORT

0 ACCESSES TO MYMUSIC PROGRAM
0COMMAND GROUP ENTERED -
RACFRW LINECNT(60) FORMAT GENSUM
SELECT PROCESS
EVENT ACCESS CLASS(PROGRAM) NAME(MYMUSIC )
LIST TITLE('LIST ACCESSES TO MYMUSIC PROGRAM')
SUMMARY RESOURCE BY(USER) TITLE('SUMMARY BY USER')
END
.../...

RACF Report Writer

Figure 2-62 RACF report writer example

How to run RACF report writer

A RACF Report Writer sample JCL is as follows:
//KHEWITT1 JOB (ITSO),'RACF FLAT',MSGCLASS=X
//HEWITT EXEC PGM=IKJEFT01
//SYSTSPRT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSTSIN DD *
RACFRW DSNAME('KHEWITT.RACF.IRRADU00')
LIST
SUMMARY USER
END
/*

The RACF report writer can also be run from the TSO command line.

102 ABCs of z/OS System Programming Volume 6

2.61 RACF auditing - DSMON

DSMON = System Integrity Validation Tool

Shows current status of data security and system
integrity
Generates optional set of reports:
System report z/OS and
RACF
Selected data set report
Program properties table report (z/OS only)
Selected user attribute reports
RACF EXITS report
Started procedure table (z/OS only)
Class Descriptor Table
Global Access Checking table
Group tree report

Figure 2-63 RACF data security monitor

RACF data security monitor

The RACF data security monitor (DSMON) enables you to verify the basic system integrity
and data security controls.

RACF auditors can use the DSMON reports to evaluate the level of security at the installation
and to compare the actual level of security at an installation with the planned level of security.

DSMON reports
DSMON produces the following reports:
 System report
 Group tree report
 Program properties table report
 RACF authorized caller table report
 RACF class descriptor table report
 RACF exits report
 RACF global access checking table report
 Selected user attribute report
 Selected user attribute report summary report
 Selected data sets report

Chapter 2. z/OS Security Server RACF 103

 The system report
The system report contains information such as the identification and model of the processor
complex, and the name, version, and release of the operating system. This report also
specifies the RACF version and release number and whether RACF is active. If RACF is
inactive, DSMON prints a message that tells you whether RACF was not activated at IPL or
was deactivated by the RVARY command.

The group tree report

This report lists, for each requested group, all of its subgroups, all of the subgroups of the
subgroups, and so on, as well as the owner of each group that is listed in the report, if the
owner is not the superior group. You can use the group tree report to examine the overall
RACF group structure for your system. You can also determine the scope of the group for
group related user attributes (group SPECIAL, group OPERATIONS, and group AUDITOR).

The program properties table report

This report lists all of the programs in the MVS program properties table (PPT). The report
also indicates, for each program, whether the program is authorized to bypass password
protection and whether it runs in a system key.

You can use the program properties table report to verify that only those programs that the
installation has authorized to bypass password protection are, in fact able to do so. Such
programs are normally communication and database control programs and other system
control programs.

You can also verify that only those programs that the installation has authorized are able to
run in a system key.

The RACF authorized caller table report

This report lists the names of all of the programs in the RACF authorized-caller table. The
programs in this table are authorized to issue REQUEST=VERIFY (which performs user
verification) or REQUEST=LIST (which loads profiles into main storage).

You can use this report to verify that only those programs that are supposed to be authorized
to modify an ACEE (accessor environment element) are able to issue a REQUEST=VERIFY.
This verification is a particularly important security requirement because the ACEE contains a
description of the current user. This description includes the user ID, the current connect
group, the user attributes, and the group authorities. A program that is authorized to issue
REQUEST=VERIFY could alter the ACEE to simulate any user.

You can also use this report to verify that only those programs that are supposed to be
authorized to access profiles are able to issue REQUEST=LIST. Because profiles contain
complete descriptions of the characteristics that are associated with RACF-defined entities,
you must carefully control access to them.

The RACF class descriptor table report

This report lists, for each general resource class the class name, the default UACC, whether
the class is active, whether auditing is being done, whether statistics are being kept, and
whether OPERATIONS attribute users have access.

You can use the class descriptor table report to determine which classes (in addition to
DATASET) are defined to RACF and active and, therefore, can contain resources that RACF
protects.

104 ABCs of z/OS System Programming Volume 6

The RACF exits report
This report lists the names of all of the installation-defined RACF exit routines and specifies
the size of each exit routine module.

You can use the RACF exits report to verify that the only active exit routines are those that
your installation has defined. The existence of any other exit routines might indicate a system
security exposure, because RACF exit routines can be used to bypass RACF security
checking. Similarly, if the length of an exit routine module differs from the length of the module
when it was defined by your installation, the module might have unauthorized modifications.

The RACF global access checking table report

This report lists, for each resource class in the global access table, all of the entry names and
their associated resource access authorities.

Because global access checking allows anyone to access the resource at the associated
access authority, you should verify that each entry has an appropriate level of access
authority.

The RACF started procedures table reports RACF generates two reports about the started
procedures table.

If the STARTED class is active, the report uses the STARTED class profiles and contains the
TRACE attribute. The trace uses module ICHDSM00.

If the STARTED class is not active, the trace uses the installation replaceable load module,
ICHRIN03.

The reports list the procedure name, the user ID and group name to be associated with the
procedure, and whether the procedure is privileged or trusted.

You can use the report to determine which started procedures are defined to RACF, and
which have the privileged attribute. If a started procedure is privileged or trusted, it bypasses
all REQUEST=AUTH processing (unless the CSA or PRIVATE operand was specified on
REQUEST=AUTH), including checks for security classification of users and data.

Selected user attribute report

The selected user attribute report:
 Lists all RACF users with the SPECIAL, OPERATIONS, AUDITOR, or REVOKE attributes
 Specifies whether they possess these attributes on a system-wide (user) or group level
 Indicates whether they have any user ID associations

You can use this report to verify that only those users who need to be authorized to perform
certain functions have been assigned the corresponding attribute.

Selected user attribute summary report

The selected user attribute summary report shows the number of installation-defined users
and totals for users with the SPECIAL, OPERATIONS, AUDITOR, and REVOKE attributes, at
both the system and group level. You can use this report to verify that the number of users
with each of these attributes, on either a system or group level, is the number that your
installation wants. In particular, you should make sure that you have assigned the SPECIAL
attribute (on a system level) to at least one user and the AUDITOR attribute (on a system
level) to at least one user.

Chapter 2. z/OS Security Server RACF 105

 Selected data sets report
This report lists the names of selected system data sets and, for each data set, specifies the
criterion for selection, the serial number of the volume on which it resides, whether the data
set is RACF-indicated or RACF-protected, and the universal access authority (UACC). If a
data set meets more than one selection criterion, there is a separate entry in the report for
each criterion. The selected data sets include system data sets, the MVS master catalog,
user catalogs, the RACF primary and backup data sets, and user-specified data sets.

You can use the selected data sets report to determine which of these data sets are protected
by RACF and which are not. You can also check whether the UACC associated with each of
the data sets is compatible with your installation's resource access control requirements.

106 ABCs of z/OS System Programming Volume 6

2.62 RACF auditing

DSMON report example:

RACF DATA SECURITY MONITOR DATE: 12/15/04 TIME: 10:21:43 PAGE: 1

SYSTEM REPORT
------------------------------------------------------------------------------------------------------------------------------------
CPU-ID 0C6A3A
CPU MODEL 2084
OPERATING SYSTEM/LEVEL z/OS 1.6.0
SYSTEM RESIDENCE VOLUME Z16RD1
SMF-ID SC63
RACF (FMID HRF7709) IS ACTIVE
RACF DATA SECURITY MONITOR DATE: 12/15/04 TIME: 10:21:43 PAGE: 2

PROGRAM PROPERTIES TABLE REPORT

PROGRAM BYPASS PASSWORD SYSTEM
NAME PROTECTION KEY
------------------------------------------------------------------------------------------------------------------------------------
IEDQTCAM NO YES
ISTINM01 YES YES
IKTCAS00 NO YES

.../...
RACF DSMON

Figure 2-64 DSMON report example

How to run the DSMON program

DSMON runs as an authorized program facility (APF) authorized batch program. DSMON can
also be run on TSO if SYS1.PARMLIB(IKJTSO00) is configured correctly.

A sample DSMON JCL is as follows:

//P390S JOB 1,P390,MSGCLASS=X
//TSOBAT01 EXEC PGM=ICHDSM00
//SYSPRINT DD SYSOUT=*
//SYSUT2 DD SYSOUT=*
//SYSIN DD *
LINECOUNT 55
FUNCTION all
USEROPT USRDSN sivle.memo.text
/*

Chapter 2. z/OS Security Server RACF 107

2.63 RACF auditing

RACF DBU output example:

01xx GROUPrecords

0101 DIVISB POU

0101 DIVISB KGN
0100 DIVISB SYS1 1999-02-17 ADMGRPS NONE NO
0101 POU DESIGN
0101 POU TEST
0101 POU MFG
0100 POU DIVISB 1999-02-17 ADMGRPS NONE NO
0102 DESIGN MARK USE
0102 DESIGN LAURIE USE
0102 DESIGN WALT USE
0100 DESIGN POU 1999-02-17 ADMGRPS NONE NO
0101 SYS1 DIVISA
0101 SYS1 DIVISB
0103 SYS1 IDENTITY SYSTEM
0103 SYS1 ATTRIB JOBNAMEXBYPASSPW
0100 SYS1 1999-01-01 IBMUSER NONE NO
RACF DBU flat file

Figure 2-65 RACF DBU output example

How to run IRRDBU00

A RACF data unload utility sample JCL is as follows:
//KHEWITT1 JOB (ITSO),'RACF FLAT',MSGCLASS=X
//UNLOAD EXEC PGM=IRRDBU00,PARM=NOLOCKINPUT
//SYSPRINT DD SYSOUT=*
//INDD1 DD DISP=SHR,DSN=SYS1.RACFESA
//OUTDD DD DISP=(NEW,CATLG),DSN=KHEWITT.RACFDB.FLATFILE,
// UNIT=SYSDA,SPACE=(CYL,(70,10),RLSE),
// LRECL=4096,RECFM=VB
//SYSIN DD DUMMY

The output file name in this example is KHEWITT.RACFDB.FLATFIL.

108 ABCs of z/OS System Programming Volume 6

2.64 RACF auditing - IRRDBU00

RACF Database Unload Utility (IRRDBU00

program):
Enables creation of sequential file from the
RACF database
Allows processing of complex inquiries on
RACF records in different ways
Allows creation of installation-tailored reports
Can also be uploaded to a database RACF
manager

Figure 2-66 RACF Database Unload Utility

RACF Database Unload Utility

The RACF database unload utility (IRRDBU00 program) is used to unload data from the
RACF database (except password fields) into a flat file.

The output file from the database unload utility can be:
 Viewed directly
 Used as input to your own programs
 Manipulated with sort/merge utilities
 Used as input to a database management system

Installations can produce reports that are tailored to their requirements.

Using the database unload utility output with DB2, you can use the DB2 Load Utility or its
equivalent to process the records that are produced by the database unload utility. The
definition and control statements for a DB2 to use this output, are shipped with OS/390 in the
SYS1.SAMPLIB.

Chapter 2. z/OS Security Server RACF 109

110 ABCs of z/OS System Programming Volume 6
 3

Chapter 3. Digital certificates and PKI

This chapter discusses the Security Server Public Key Infrastructure (PKI) Services. We
discuss the following topics:
 Overview of digital certificates
 PKIX standards
 z/OS PKI Services

© Copyright IBM Corp. 2008. All rights reserved. 111

3.1 The authentication problem

Strong authentication in a distributed environment

requires cryptography
Today's trend to authentication standardization
Using symmetric algorithms (shared secret keys): MIT
Kerberos V5
Widely adopted
Practically constrained to corporate networks
Using asymmetric algorithms (public key
cryptography): Digital certificates
Very well fitted for world-wide communications
Standards in process, interoperability among vendors
to be established require a PKI

Figure 3-1 Authentication

Authentication
Authentication is one of the primary requirements to establish trust in e-business
transactions. The industry is looking for strong authentication and for standardization of the
authentication mechanisms. Strong authentication uses cryptography. Two prevalently
mechanisms exist today for strong authentication in a distributed environment. They differ by
the kind of cryptographic algorithms that they use, which is also their domain of application.

In this chapter, we explain digital certificates, which have a potentially unlimited scalability but
which need a PKI in place.

Cryptography
Security in communications over a non-secure network requires the use of cryptographic
procedures. If you send data in the clear over a network that is not completely under your
control from the receiver to the sender, you cannot assure the following security functions:
 Privacy: Anyone who is able to intercept your data might be able to read it.
 Integrity: An intermediary might be able to alter your data.
 Accountability or non-repudiation: It might be impossible to determine the originator of a
message with confidence, and the person who sent the message can disclaim being the
originator.

Security functions such as Identification and Authentication are also impacted because if
authentication data such as passwords are sent without integrity and privacy, they can be

112 ABCs of z/OS System Programming Volume 6

intercepted in transit between sender and receiver, making the authentication compromised
and worthless.

To ensure privacy, integrity, and accountability in non-secure networks, cryptographic

procedures need to be used.

Symmetric encryption algorithms

An encryption algorithm is called symmetric because the same key that is used to encrypt
the data is also used to decrypt the data and to recover the plain text. The cipher and
decipher processes are usually mathematically complex non-linear permutations.

Most symmetric ciphers that are used are block ciphers, which operate on a fixed number of
characters at a time.

With these ciphers, it can be assumed that a brute-force attack is the only means of breaking
the cipher. Therefore, the work factor depends on the length of the key. If the key length is n
bits, the work factor is proportional to 2**(n-1).

Asymmetric encryption algorithms

An encryption algorithm is called asymmetric because the key that is used to encrypt the
data cannot be used to decrypt the data. A different key is needed to recover the plain text.
This key pair is called a public key and a private key. If the public key is used to encrypt the
data, the private key must be used to recover the plain text. If data is encrypted with the
private key, it can only be decrypted with the public key.

Asymmetric encryption algorithms, commonly called Public Key Cryptosystems (PKCS), are
based on mathematical algorithms. The basic idea is to find a mathematical problem that is
very hard to solve.

Digital signatures
Digital signatures are an extension to data integrity. While data integrity only ensures that the
data received is identical to the data sent, digital signatures go a step further. Digital
signatures provide non-repudiation, which means that the sender of a message (or the signer
of a document) cannot deny authorship, similar to signatures on paper.

Digital certificates
The application of public-key technology requires the user of a public key to be confident that
the public key belongs to the correct remote person or system with which an encryption or
digital signature mechanism is used. This confidence is obtained through the use of
public-key certificates. A digital certificate is analogous to a passport—the passport certifies
the bearer’s identity, address and citizenship. The concepts behind passports and other
identification documents, such as drivers licenses, are very similar to those that are used for
digital certificates.

Identification documents are issued by a trusted authority, such as the Government passport
office or a Department of Motor Vehicles. A passport is not issued unless the person who
requests it can prove identity and citizenship to the authority. Specialized equipment is used
in the creation of passports to make it very difficult to alter the information in it or to forge a
passport altogether. Other authorities, for example the border police in other countries, can
verify a passport’s authenticity. If they trust the authority that issued the document, the
information contained in it is accepted as true.

Chapter 3. Digital certificates and PKI 113

 A digital certificate serves two purposes:
 It establishes the owner’s identity
 It makes the owner’s public key available

Similar to a passport, a certificate must be issued by a trusted authority, a Certification

Authority (CA) and, similar to a passport, it is issued only for a limited time. When its
expiration date has passed, it must be replaced.

The digital signature of the certification authority serves the same purpose as the special
measures taken for the security of passports, such as laminating pages with plastic material,
which allows others to verify the authenticity of the certificate. Using the public key of the
certification authority, the MIC can be decrypted. The message digest can be recreated. if it is
identical to the decrypted MIC, the certificate is authentic.

Trust is a very important concept in passports as well as in digital certificates. In the same
way as, for example, a passport that is issued by some governments, even if recognized to be
authentic, might not be trusted by U.S. authorities, so each organization or user has to
determine which certification authorities can be accepted as trustworthy.

114 ABCs of z/OS System Programming Volume 6

3.2 Overview of digital certificate

Authorize -
Request fulfillment of
request

Fulfillment

Revoke Used by
or owner
Renew
Figure 3-2 Overview of digital certificate

When compared to other known means of strong authentication, digital certificates (and the
underlying public key cryptography algorithm) appear to be probably the best solution to the
current authentication and encryption problem involving a very large population of users over
a non-secure network such as the Internet.

However, the use of digital certificates, over the Internet or in an intranet environment,
requires a supporting Public Key Infrastructure (PKI), which is the set of services, tools, and
policies that enable the use of public key cryptography and management of keys and
certificates in a PKI domain. The certificates and the associated key pairs are expected to
have a life cycle as described in Example 3-2 on page 146.

Life cycle stages of a digital certificate

The life cycle stages of a digital certificate are as follows:
1. Request phase
First there is the generation of an asymmetric algorithm key pair. Usually, this generation is
performed locally by the entity that requests the certificate, although some PKI
implementations can perform the key generation on behalf of the certificate requestor. In
that case, the PKI has to be able to deliver the generated private key securely to the
certificate’s owner.

Chapter 3. Digital certificates and PKI 115

 The generation of a certificate request usually contains the following elements, which are
signed by the requestor’s private key as a proof of origin of the certificate request:
– The distinct name of the requestor
– The value of the public key
– Miscellaneous additional fields
2. Authorize fulfillment of request and fulfillment phases
Generation and signature of the certificate itself by a CA. The CA, which can be assisted
by a Registration Authority (RA) in charge of verifying the validity and integrity of the
certificate request and approving it, is the pivotal entity in a PKI. The CA is in charge of
digitally signing the certificate (that is, vouching for the binding of the public key value to
the name of the certificate’s owner), thus making the certificate usable for strong
authentication or other cryptographic processes. Strictly speaking, the RA provides for the
Authorize fulfillment of request phase, and the CA performs the Fulfillment.
These two phases heavily engage the responsibility, and in many cases the liability, of the
CA, which is to use the proper administrative procedures and highly secure technologies
to ensure the integrity of its digital signature and of the signed contents.
Note that a certificate, as delivered by a CA, is granted a validity period determined by the
CA policy. Usually, a user certificate is valid for one year.
3. Used by owner phase
The certificate can now be used by the owner for the purpose of authentication, which
works as long as the requestor can demonstrate possession of the corresponding private
key or any other cryptographic process where the value of one’s public key is required.
Note that the recipient of a certificate must have the public key of the CA that signed this
certificate.
This public key itself is delivered in a CA’s certificate because, by the PKI principle, a CA is
the only entity delivering certificates in a PKI domain.
4. Revocation or renewal phase
The validity of a certificate can be denied in two ways:
– The validity period of the certificate is over
– The certificate is part of a Certificate Revocation List (CRL), which is issued by the CA
that initially issued the certificate, usually on request from the certificate’s owner
The owner can request the revocation of a certificate for many reasons, including:
– Change of name of the owner
– Change of association between the owner and the CA (for example, when an employee
leaves a company that is its own CA)
– Compromise or suspected compromise of the corresponding private key
The entity receiving a certificate checks for its expiration based on the receiver’s local time
and date. Verifying that a certificate is not part of a Certificate Revocation List requires the
receiving entity to fetch the CRL from its repository, which usually is an LDAP directory
(although some PKI implementations provide access to a CRL through the HTTP
protocol). A certificate becomes part of a CRL at the completion of the Revocation phase.
During its normal life cycle, a certificate is set to expire after a certain validity period that is
indicated in the certificate at its creation. The supporting PKI must then provide a way to
renew the certificate, keeping the same certificate but with a new validity period and a new
certificate serial number. This is the renewal phase.

116 ABCs of z/OS System Programming Volume 6

3.3 The public key cryptography trust model

The Certification Authority:

the trusted third party
VeriSign, Thawte, or your own CA

Certificate request
Mary's name
Mary's public
key
CA's Digital Verifies CA's
Signature Signature using
CA's public key

"Mary"

Mary's Digital Certificate

Mary's Check ownership of

Private
Key Mary's private key
then Authenticated

The certificate is intended for use by an application.

Creation, management, and exploitation of certificates are
performed within a PKI.

Figure 3-3 Public key cryptography trust model

Public key cryptography trust model

With public key cryptography, you rely on a CA. The CA provides a file that contains your
public key and your name digitally signed by the CA. You never give your public key value. You
give a digital certificate. The content of a certificate is public information, it is not encrypted.

A CA is just a piece in a bigger organization, that you need to put in place, or use an already
existing organization that we are calling a PKI.

Chapter 3. Digital certificates and PKI 117

3.4 Elements of PKI in z/OS

LDAP Certification
Directory Authority

X.509 V2 PKCS-10 X.509 V3

Certificate Certificate Signed
X.509 V3 Revokation List Request Certificate
CA Digital
Signature z/OS

Client's LDAP RACF

name Client X.509 V3
SSL System
Enabled SSL CA Digital
Signature
Server DLLs
SSL Client RACF
Server's DB
Hardware name
Cryptography
certificate mapping
to RACF userid Key Rings RACDCERT
Certificates command
Client Certificate Private Keys
Request and HTTP PKI
Generation Server Services Self
Signed
(PKIServ)
CA's
name

Figure 3-4 Elements of PKI in z/OS

PKI Services
PKI Services allow you to establish a PKI infrastructure and serve as a certificate authority for
internal and external users, issuing and administering digital certificates in accordance with
the organization’s policies. Users can use a PKI Services application to request and obtain
certificates through their own Web browsers, while authorized PKI administrators approve,
modify, or reject these requests through their own Web browsers. The Web applications that
are provided with PKI Services are highly customizable, and a programming exit is also
included for advanced customization. You can allow automatic approval for certificate
requests from certain users and, to provide additional authentication, add host IDs, such as
RACF user IDs, to certificates you issue for certain users. You can also issue certificates for
browsers, servers, and other purposes, such as virtual private network (VPN) devices, smart
cards, and secure e-mail.

PKI Services supports Public Key Infrastructure for X.509 version 3 (PKIX) and Common
Data Security Architecture (CDSA) cryptographic standards. It also supports:
 The delivery of certificates through the SSL for use with applications that are accessed
from a Web browser or Web server.
 The delivery of certificates that support the Internet Protocol Security standard (IPSEC)
for use with secure VPN applications or IPSEC-enabled devices.
 The delivery of certificates that support Secure Multipurpose Internet Mail Extensions
(S/MIME) for use with secure e-mail applications.

118 ABCs of z/OS System Programming Volume 6

Certificate authority (CA)
The CA acts as a trusted third party to ensure that users who engage in e-business can trust
each other. A certificate authority vouches for the identity of each party through the
certificates it issues. In addition to proving the identity of the user, each certificate includes a
public key that enables the user to verify and encrypt communications.

The trustworthiness of the parties depends on the trust that is placed in the CA that issued
the certificates. To ensure the integrity of a certificate, the CA digitally signs the certificate as
part of creating it, using its signing private key. Trying to alter a certificate invalidates the
signature and renders it unusable.

Protecting the CA’s signing private key is critical to the integrity of the CA. For this reason,
consider using ICSF to store PKI Services CA’s private key securely. As a CA using PKI
Services, you can:
 Track certificates that you issue with an issued certificate list (ICL) that contains a copy of
each certificate, indexed by serial number
 Track revoked certificates using certificate revocation lists (CRLs). When a certificate is
revoked, PKI Services updates the CRL during the next periodic update. Just as it signs
certificates, the CA digitally signs all CRLs to vouch for their integrity.

PKI
The PKI provides applications with a framework for performing the following types of
security-related activities:
 Authenticate all parties that engage in electronic transactions
 Authorize access to sensitive systems and repositories
 Verify the author of each message through its digital signature
 Encrypt the content of all communications

The PKIX standard evolved from PKI to support the interoperability of applications that
engage in e-business. Its main advantage is that it enables organizations to conduct secure
electronic transactions without regard for operating platform or application software package.

The PKIX implementation in PKI Services is based on the Common Data Security
Architecture (CDSA) from Intel Corporation. CDSA supports multiple trust models, certificate
formats, cryptographic algorithms, and certificate repositories. Its main advantage is that it
enables organizations to write PKI-compliant applications that support their business policies.

Chapter 3. Digital certificates and PKI 119

 Basic components of PKI services and related products
Table 3-1 lists the basic components of PKI services and related products.

Table 3-1 Basic components of PKI services and related products

Components Description

Administration Assists authorized administrators to review requests for certificates, approve or

Web application reject requests, renew certificates, or revoke certificates through their own Web
browsers. The application consists of sample screens that you can easily
customize to display your organization’s logo. It also supports the following tasks:
 Reviewing pending certificate requests
 Querying pending requests to process those that meet certain criteria
 Displaying detailed information about a certificate or request
 Monitoring certificate information, such as validity period
 Annotating the reason for an administrative action

User Web Guides users to request, obtain, and renew certificates through their Web
application browsers. The application consists of sample screens that you can easily
customize to meet your organization’s needs for certificate content and standards
for appearance. It offers several certificate templates that you can use to create
requests for a variety of certificate types, based on the certificate’s intended
purpose and validity period, and supports certificate requests that are
automatically approved.

Exit Provides advanced customization for additional authorization checking,

validating, and changing parameters on calls to the R_PKIServ callable service
(IRRSPX00), and capturing certificates for further processing. You can call this
exit from the PKIServ CGIs and use its IRRSPX00 pre-processing and
post-processing functions. A code sample in C language code is included.

ICSF (optional) Securely stores the PKI Services certificate authority’s private signing key.

LDAP The directory that maintains information about the valid and revoked certificates
that PKI Services issues in an LDAP-compliant format. You can use an LDAP
server such as z/OS Security Server LDAP.

PKI Services The server daemon that acts as your certificate authority, confirming the identities
daemon of users and servers, verifying that they are entitled to certificates with the
requested attributes, and approving and rejecting requests to issue and renew
certificates. It includes support for:
 An issued certificate list (ICL) to track issued certificates
 Certificate revocation lists (CRLs) to track revoked certificates

R_PKIServ The application programming interface (API) that allows authorized applications,
callable service such as servers, to programmatically request the functions of PKI Services to
(IRRSPX00) generate, retrieve and administer certificates.

RACF (or Controls who can use the functions of the R_PKIServ callable service and
equivalent) protects the components of your PKI Services system. RACF creates your
certificate authority’s certificate, key ring and private key. You can also use it to
store the private key, if ICSF is not available.

z/OS HTTP PKI Services uses the Web server to encrypt messages, authenticate requests,
Server and transfer certificates to intended recipients.

120 ABCs of z/OS System Programming Volume 6

Supported certificate types
Table 3-2 lists the types of certificates that you can request, based on the certificate
templates that are included with PKI Services. Certificate templates are samples of the most
commonly requested certificate types. You can add, modify, and remove certificate templates
to customize the variety of certificate types that you offer to users.

Table 3-2 Supported certificate types

Type of certificate Use

One-year PKI SSL browser certificate User client authentication using SSL

One-year PKI S/MIME browser certificate Browser-based e-mail encryption

Two-year PKI browser certificate for User client authorization using SSL when logging
authenticating to z/OS onto z/OS

Two-year PKI Authenticode–code signing server Software signing

certificate

Five-year PKI SSL server certificate SSL Web server certification

Five-year PKI IPSEC server (firewall) certificate Firewall server identification and key exchange

Five-year PKI intermediate CA certificate Subordinate (non-self-signed)

certificate-authority certification

One-year SAF browser certificate User client authentication where the security
product (RACF, not PKI Services) is the
certificate provider

One-year SAF server certificate Web server SSL certification where the security
product (RACF, not PKI Services) is the
certificate provider

Chapter 3. Digital certificates and PKI 121

3.5 The PKIX standards

PKIX:
PKIX:
Format of Certificate
Certificate
Revokation List
Management Certification Authority
CA Policy for the Domain Certificate Revocation Lists is X.509 V2
Protocol (CMP) and (optionally with a Issuance
Certificate Message Registration Authority))

Syntax (CMS, PKCS-10)

Certificates and
2-Certificate Issuance CRLs
Repository
1-Certificate Request
PKIX:
4-Certificate Revocation
Format of Certificate Checking
Cerificate Certificate,
is X.509 V3 exploiting
Owning
Entity Entity

PKIX: CRL repository

3-Certificate Utilization PKI (LDAP directory)
Online Certificate Status
Protocol (OCSP)

Figure 3-5 PKIX standards

The digital certificate life cycle as described previously is well documented and has been well
understood in the industry since the late 1980s. However, the design and implementation of
supporting technologies proved to vary from vendor to vendor. One of the early issues
encountered when attempting to implement a PKI was the lack of interoperability between
PKI products, hence the lack of potential scalability or capability to aggregate different PKI
domains. This issue proved to be a severe impediment to the development of PKI use in the
industry.

To address this issue, the Internet Engineering Task Force (IETF) launched the Public-Key
Infrastructure (X.509) Working Group (PKIX) in 1995.

A simplified graphical view of a PKIX-compliant PKI is shown in Example 3-5 on page 151.
The example does not fully representing all of the items that are addressed by the PKIX
Working Group but only the following items that are relevant to this book:
 The PKCS#10 format for the certificate request
 The X.509 V3 format for the signed certificate
 The X.509 V2 format for the CRL
 The LDAP protocol to reach the CRL residing in an LDAP directory
 The OCSP protocol for real-time access to revocation information

122 ABCs of z/OS System Programming Volume 6

In the this section, we discuss the set of definitions that the PKIX Working Group compiled.

Certification Authority (CA)

A CA is an authority trusted by one or more users to create and assign public key certificates.
Optionally, the CA can create the user’s keys. Note that the CA is responsible for public key
certificates during their lifetime, not just for issuing them, meaning that the CA also provides
certificate revocation information.

Public Key Certificate (PKC)

A PKC is a data structure that contains the public key of an end entity, and other information,
that is signed digitally with the private key of the CA that issued it. PKC should not be
confused with other types of certificates that the PKIX group is working on, such as the
Attribute Certificate (AC).

End Entity (EE)

The End Entity is the user of PKI certificates or the user system that is the subject of a
certificate.

Subject
The Subject is the entity named in a Public Key certificate. Subjects can be human users,
computers (represented by Domain Name Service [DNS] names or Internet Protocol [IP]
addresses), or even software agents. The subject is often referred to as the owner of the
certificate.

Registration Authority (RA)

The Registration Authority is an optional entity that is associated with the CA and that is
responsible for performing some of the administrative tasks that are necessary for registering
subjects, such as confirming the subject’s identity, validating that the subject is entitled to
have the values that are requested in a PKC, and verifying that the subject has possession of
the private key associated with the public key in the PKC request.

Public Key Infrastructure (PKI)

The PKI is a set of hardware, software, people, policies, and procedures that are needed to
create, manage, store, distribute, and revoke PKCs based on public-key cryptography.

Certificate Policy (CP)

The Certificate Policy is a named set of rules that indicates the applicability of a public key
certificate to a particular community or class of application with common security
requirements. For example, a particular certificate policy might indicate applicability of a type
of public key certificate to the authentication of electronic data interchange transactions for
the trading of goods within a given price range.

Certification Practice Statement (CPS)

The CPS is a statement of the practices that a CA employs in issuing public key certificates.

Top CA, or root CA

The Top CA (root CA) is a CA that is at the top of a PKI hierarchy.

Chapter 3. Digital certificates and PKI 123

3.6 The RSA public key cryptography standards (PKCS)

'Informal standards' developped in 199x by RSA Laboratories.

Used today in many different standards and products

PKCS #1: RSA Cryptography Standard

PKCS #2: Note below
general syntax of structures PKCS #3: Diffie-Hellman Key Agreement Standard
exchanged between entities PKCS #4: Note below
as PKCS #5: Password-Based Cryptography Standard
encrypted data, digested PKCS #6: Extended-Certificate Syntax Standard
data, PKCS #7: Cryptographic Message Syntax Standard
PKCS #8: Private-Key Information Syntax Standard
signed data, ...
PKCS #9: Selected Attribute Types
general syntax for
PKCS #10: Certification Request Syntax Standard
certification
PKCS #11: Cryptographic Token Interface Standard
request : distinguished PKCS #12: Personal Information Exchange Syntax Standard
name, PKCS #13: Elliptic Curve Cryptography Standard
public key, set of attributes. PKCS #15: Cryptographic Token Information Format Standard
Collectively signed by the
requesting entity
syntax for transfer of personal http://www.rsasecurity.com/rsalabs/pkc
identity information, private
keys,
certificates, ...

Figure 3-6 PKCS standards

PKCS standards
We mentioned the interoperability through commonly adopted standards. A set of standards,
actually exists—informal standards as RSA calls them. These standards are widely used in
current PKI products, but they do not cover all the aspects of PKIs and are only partially cover
the addressed aspects. However, most of the new PKI standards will integrate these
standards because of their de facto status.

124 ABCs of z/OS System Programming Volume 6

3.7 The PKCS-10 certificate request

commonName = kappeler
organizationalUnitName =
PSSC
organizationName = IBM
version : 0 localityName = Montpellier
countryName = FR
subject X.500 name
RSAEncryption
Digital signature
subject public key info FB 9F E4 A6 9D 28 E8 B1 80 C7 01 89 D0 CC DD
generate using algorithm id 38
public key value EA DD 8F 06 D4 6E C5 85 8C 1A 02 94 A7 19 1F
requestor's 43
DE B3 89 EE B9 CE 70 50 52 72 A5 7C 49 70 E6
private key Attributes 7A
75 66 16 A6 F4 00 67 A2 88 F6 2C A6 58 E2 74 36
signature algorithm
identifier md5withRSAEncryption
Signature

Typically sent after generating a private/public key pair

Part of the services provided by the key pair generation software, for example
GSKKYMAN or RACF on z/OS
Certification Authority is to verify signature using the public key in the request

Figure 3-7 PKCS-10 certificate request

Let us have a look now at the inside of a digital certificate, starting with PKCS-10 request.

After the key pair is generated, the public key and personal information are sent in a file that is
signed digitally with the private key that corresponds to the public key in the certificate. The
CA is going to use the information that is contained in the certificate request to build the final
certificate but will verify the digital signature as soon as it can using the public key in the
certificate request.

The PKCS#10 format is used for certificate requests only. It cannot be used for signed
certificates. It was created to allow for a certificate request format with a minimum of data to
be transferred.

Chapter 3. Digital certificates and PKI 125

3.8 The X.509 certificate

Certificate extension fields

Standard extensions
certificate version: V3 authority key identifier
subject key identifier
certificate serial number
key usage
signature algorithm private key usage period
identifier certificate policies
policy mappings
issuer (CA) X.500 name
subject alternative name
issuer alternative name
Digital signature validity period subject directory attributes
generate using
basic constraints
issuer's private subject x.500 name
name constraints
key subject public key info policy constraints
algorithm id extended key usage
public key value CRL distribution point
issuer unique identifier Private internet extensions
authority information access
subject unique identifiers
Each extension field is flagged
extensions 'critica'l or 'non-critical'
Issuer's digital signature

Figure 3-8 X.509 certificate

X.509 certificate
The PKIX documents emphasize the following basic principles when it comes to using a
digital certificate:
 Recipients of digital certificates must be confident that any time they rely on a public key,
the subject that they are communicating with owns the associated private key. This
concept applies whether an encryption or digital signature mechanism is used. This
confidence is obtained through the use of protocols (for example, SSL/TLS) that cannot
carry forward the communication if this condition is not fulfilled.
 A certificate has a limited valid lifetime, which is indicated in its signed contents. Because
a PKC’s signature and timeliness can be checked independently by a certificate-using
client, certificates can be distributed through untrusted communications and server
systems and can be cached in unsecured storage in certificate-using systems.
 Certificates are used in the process of validating signed data or securely transmitting
encryption keys. Specifics vary according to which algorithm is used, but the general
process works as follows:
a. The recipient of signed data verifies that the claimed identity of the user is in
accordance with the identity contained in the certificate.
b. The recipient validates that no certificate in the path is revoked (for example, by
retrieving a suitably current CRL or querying an online certificate status responder) and
that all certificates are within their validity periods at the time the data was signed.

126 ABCs of z/OS System Programming Volume 6

 c. The recipient verifies that the data is not claimed to have any values for which the
certificate indicates that the signer is not authorized.
d. The recipient verifies that the data has not been altered since signing, by using the
public key in the certificate.

If all of these checks pass, the recipient can accept that the data was signed by the purported
signer. As these basic principles always stand true, it appeared also during practical
experimentation of digital certificates that they had to be supported by more sophisticated
structures than initially planned. Actually, the X.509 digital certificate format had to go through
different evolutions, as explained in the following sections.

X.509 certificate version 1

The X.509 certificate version 1 was the initial version of 1988. The specified fields, which are
still in use today in the version 3 format, are:
 Version number (1).
 Serial number: The serial number assigned by the CA at signature time.
 Signature algorithm ID: An indication from the CA of which algorithm has been used to
signed the certificate.
 Issuer’s name: The name of the certification authority. The name appears as a
distinguished name in the X.500 syntax.
 Validity period: The CA imposes a limited validity period to the certificate, usually one year
from its signing date.
 Subject’s name: The owner of the public key, hence owner of the certificate as well. The
name appears as a distinguished name in the X.500 syntax.
 Subject’s public key information: The numeric, non-secret value of the certificate owner’s
public key, along with information about the algorithm this key is intended for.

Note: It takes only two pieces of information to uniquely identify a digital certificate:
 The Certification Authority’s (issuer’s) name
 The serial number assigned to the certificate by the CA

X.509 certificate version 2 (1993)

The X.509 certificate version 2 added two new fields to accommodate the fact that no one can
really expect that in the real word x.500 distinguished names will ever be unique:
 Issuer Unique Identifier: This optional field enables specifying a complementary unique
identifier to the Certification Authority in case the Issuer’s distinguished name could
already be in use by another entity.
 Subject Unique Identifier: This optional field enables specifying a complementary unique
identifier to the certificate owner in case the Subject’s distinguished name could be in use
already by another entity.

X.509 certificate version 3 (1995)

Still facing real-life facts, it appeared that new certificate fields were needed that could be
implemented and used as needed by specific applications. These extension fields appeared
in version 3, yielding a certificate format as shown in Example 3-13 on page 170. The intent
of version 3 was to address some of the security concerns and limited flexibility from versions
1 and 2.

Chapter 3. Digital certificates and PKI 127

3.9 X.509 certificate revocation list

CRL version : V2
CRL entry extensions
signature algorithm serial number
revocation date
CRL issuer name
certificate issuer
reason code
issuer (CA) X.500 name hold instruction code
invalidity date
this update (date/time)
next update (date/time)
Digital signature
generate using revoked certificate
serial number CRL extensions
issuer's private authority key identifier
revocation date
key CRL entry extensions issuer alternative name
CRL number
revoked certificate delta CRL indicator
serial number
Issuing distribution point
revocation date
CRL entry extensions
Each extension field is flagged
..... critical or non-critical
CRL extensions

CRL Issuer's digital signature

Figure 3-9 X.509 certificate revocation list

X.509 certificate revocation list

The certificate revocation list went under its own evolution. It is now at version 2, and it
contains the fields shown in Figure 3-9. Note that a CRL is intended to be stored in an LDAP
directory, from which it can be fetched, and because the CRL is signed by the issuing
certification authority, the CRL repository is not required to be secure. A CA uses the same
repository to make new certificates available and to publish CRLs.

More about the certificate revocation list

The following list provides more information about the certificate revocation list:
 The CRL is intended to be published. That is, it is updated regularly in the LDAP directory
by the CA. It is up to the CA to indicate the frequency of these updates in the CA
revocation policy.
 The implication of these periodic updates is that the revoked status of a certificate will be
known from potential recipients only after the CRL update that follows the revocation has
been issued, which can be several hours or days after the revocation request has been
successfully processed. To help circumvent this timeliness problem, another protocol has
been proposed by IETF, the Online Certificate Status Protocol (OCSP), through which the
revocation status of a certificate can be obtained in real time. However, the use of the CRL
(instead of OCSP) prevails in PKIs.

128 ABCs of z/OS System Programming Volume 6

 The CRL can be located in the LDAP directory:
– As an attribute in the CA entry (that is, the entry with the CA’s distinguished name).
This is known as the global CRL. The global CRL is added any new revoked certificate
information, whereas previously revoked certificate can be deleted, if appropriate, from
the list at each update. For large PKI domains, the global CRL can grow very large.
– As a directory entry by itself, called a distribution point. The distribution point approach
is intended to break down the complete CRL into smaller pieces, each one being a
separate directory entry easier to access than the whole global CRL. The distinguished
name of the distribution point entry to look into is indicated in an extension field of the
published certificate. The distribution point entries are leaf nodes in the directory that is
below the CA entry.

Chapter 3. Digital certificates and PKI 129

3.10 X.509 V3 certificate: Standard extensions

Subject and issuer attributes extensions

Issuer and subject alternative name: other name forms than X.500 (for example IP address)
Subject directory attributes (for example phone number)

Key and policy information extensions

Authority key identifier: Differentiates between different possible CA's keys
Subject key identifier: Differentiates between different subject's key pairs
Key usage: Purpose for which this public key is used (signature, encryption, and so forth)
Private key usage period: Period of use of the private key corresponding to the public key
Certificate policies: Set of policies identifier
Policy Mappings: To establish policies equivalency between CA's

Certification path constraints

Basic constraints: For CA certificates, indicates depth of certification path
Name constraints: For CA certificates, fixes name space for subsequent subjects in
certification path
Policy constraints: For CA certificates, to control policy mapping or presence of policies
identifiers
....

Figure 3-10 X.509 V3 certificate: Standard extensions

X.509 V3 certificate
PKI Services certificates support most of the fields and extensions that defined in the X.509
version 3 (X.509 v3) standard. This support lets you use these certificates for most
cryptographic purposes, such as SSL, IPSEC, VPN, and S/MIME.

This section discusses the types of extensions that PKI Services certificates can include.

Standard extensions
The standard X.509 v3 certificate extensions include:
 Authority information access
 Authority key identifier
 Basic constraints
 Certificate policies
 Certificate revocation list (CRL) distribution points
 Extended key usage
 Key usage
 Subject alternate name
 Subject key identifier

Other extensions
Other extensions are unique to PKI Services, such as host identity mapping. This extension
associates the subject of a certificate with a corresponding identity on a host system, such as
with a RACF user ID.

130 ABCs of z/OS System Programming Volume 6

3.11 Contents of the digital certificate

X.509 Version 1 (1988) 46 76 0C 47 89 9B 8E 8D 5C 1E DA EB AE 9A 06 F1

certificate version : 1 md5withRSAEncryption

certificate serial number organizationalUnitName =Secure Server
Certification Authrority
signature algorithm
organizationName = RSA Data Security, Inc
identifier
countryName = US
Digital signature issuer (CA) X.500 name
UTCTime '000801000000Z'
generate using UTCTime '010815235959Z'
issuer's private validity period
key commonName = kappeler
subject X.500 name organizationalUnitName = PSSC
organizationName = IBM
subject public key info localityName = Montpellier
algorithm id countryName = FR
public key value
Signature RSAEncryption

FB 9F E4 A6 9D 28 E8 B1 80 C7 01 89 D0 CC DD 38
EA DD 8F 06 D4 6E C5 85 8C 1A 02 94 A7 19 1F 43
DE B3 89 EE B9 CE 70 50 52 72 A5 7C 49 70 E6 7A
F3 AD E9 54 E4 A3 22 0D 75 66 16 A6 F4 00 67 A2 88 F6 2C A6 58 E2 74 36
B6 9F 17 0B BB B3 24 2B

A certificate is uniquely identified by the issuer's name and its serial number

Figure 3-11 Contents of the digital certificate

Contents of the digital certificate

A digital certificate, by nature, is intended to be public knowledge. That is, the enclosed
information appears unencrypted and the only piece of encrypted data is actually the CA’s
digital signature (of which content does not bring any additional functional information). A
simplified graphical view of a certificate and its contents is shown in Figure 3-11, where fields
contain numeric or alphanumeric values.

However, for interoperability reasons, the contents of a certificate must go through specific
syntax and encoding (not encryption) transformations that render a certificate readable by
software only.

The certification authority builds the certificate file based on the information in the certificate
request and offline checkings, which can done on your personal information.

The CA basically gives the certificate:

 A serial number
 The CA DN indication
 A validity period: not before / not after

The CA also signs the contents with its CA private key.

The couple CA DN + serial number identifies uniquely the certificate.

Chapter 3. Digital certificates and PKI 131

3.12 Browser certificates

Web User PKI Administrator

z/OS PKI Services
1
4
6

2
8 3
10 5
7 Request
DB
Issued
Cert DB
9
LDAP
Directory

SSL client auth

protected Web site

Figure 3-12 Browser certificates

Browser certificates
With a browser certificate, a certificate is requested to and obtained from the z/OS PKI
Services only using the HTTP/HTTPS protocol. This is a very straightforward process when
obtaining a browser (client) certificate, but it is more complicated to request, obtain, and
install a server certificate.

Browser (client) certificate process flow

Figure 3-12 shows the typical process flow for browser certificates:
 The Web user submits the PKCS#10 certificate request (1).
 The request is queued for approval by the administrator (2).
 The administrator reviews the request and approves or rejects it (3).
 If approved (4) it is issued and stored (5).
 The certificate is returned to the Web user when queried (6).
 It is also published to an LDAP directory (7). The certificate revocation list (CRL) is also
published to LDAP on a continuous basis.
 The Web user uses the certificate to authenticate to an SSL client authentication protected
Web site (8).
 The SSL handshake validates the certificate and checks the CRL (9).
 If everything is valid, the user gains access (10).

132 ABCs of z/OS System Programming Volume 6

3.13 Server certificates

Web Server Admin PKI Administrator

z/OS PKI Services
1c
6 4

Web User
2
1a 3

1b 8 5
7 Request
DB
9 Issued
Cert DB
10
11
LDAP
Directory

SSL Web site

Figure 3-13 Server certificates

Server certificates
Figure 3-13 shows the typical process flow for Web server certificates:
 The Web server administrator uses server-specific software to generate a PKCS#10
request (1a).
 This is copied (1b) and pasted (1c) into the certificate request Web page and submitted.
 Steps for queuing, approving, issuing, and retrieving the certificate are identical to the
preceding browser flow (2 through 7).
 The Web server administrator installs the certificate into the Web server (8) and brings it
online.
 Web users can now visit the SSL-protected Web site (9).
 If client authentication is enabled, the client's certificate is validated using the CRL in
LDAP (10).
 If all is valid, the user gains access (11).

Chapter 3. Digital certificates and PKI 133

3.14 z/OS PKI services architecture

RA
HTTP server for z/OS
Admin
Browser Static Web Install/Config:
H Pages
T
T
SMP/E Install
End User
P
Browser
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
LDAP Cert List
DB - New code
SMF Directory
- Updated code
Audit SMF
Records Unload

Figure 3-14 z/OS PKI services architecture

z/OS PKI services architecture

The z/OS HTTP server provides the user and administrator interface.The customizable Web
page makes use of CGI routines (also provided), and their contents are defined explicitly in a
template file that can be edited if necessary. The information in the template file is directly
related to each type of request that the PKI supports, and it is exploited by the Web
application (CGIs) to interface with the user or the administrator and to submit requests to
R_PKIServ SAF callable services interface when appropriate. CGIs are written in REXX, thus
requiring a RACF glue routine because REXX cannot create the structure parameters
required by the callable service. Optionally, you can use PKI exit if more customization is
needed.

The user administrative interface requires two instances of the z/OS Web server sharing the
same certificate and private key:
 Instance one: Supports HTTP and HTTPS for users and PKI administrator. It is set up to
prompt for SAF user ID and password depending on the requested URL.
 Instance two: Supports only HTTPS with client authentication. It is required for
authenticating a client certificate revocation request.

Any request for users and administrators is always directed to instance one of the HTTP
server first and can be redirected automatically to instance two depending on the type of
request.

134 ABCs of z/OS System Programming Volume 6

R_PKIServ is a problem program service backed by RACF. Requests are verified by RACF
and submitted to the PKI Services daemon, the core UNIX application in the z/OS PKI
Services. Additionally, RACF can create SMF auditing records.

User functions of the service are:

 Request
 Retrieve
 Verify
 Revoke
 Renew a certificate

Administrator functions of the service are:

 Query
 Approve
 Modify and reject certificate requests
 Query and revoke issued certificates

The PKI Services daemon is a multi-threaded server. It has service threads for incoming
requests and background threads for housekeeping tasks such as the periodic issuance of a
CRL and deletion of inactive requests. It maintains two VSAM data sets, one for storing all
requests it receives (ObjectStore) and the other for keeping a list of issued certificates (ICL).

Chapter 3. Digital certificates and PKI 135

3.15 Get PKI up and running

LDAP Certification
Directory Authority

X.509 V2 PKCS-10 X.509 V3

Certificate Certificate Signed
X.509 V3 Revokation List Request Certificate
CA Digital
Signature z/OS

Client's LDAP RACF

name Client X.509 V3
SSL System
Enabled SSL CA Digital
Signature
Server DLLs
SSL Client RACF
Server's DB
Hardware name
Cryptography
certificate mapping
to RACF userid Key Rings RACDCERT
Certificates command
Client Certificate Private Keys
Request and HTTP PKI
Generation Server Services Self
Signed
(PKIServ)
CA's
name

Figure 3-15 Get PKI up and running

Preparing the PKI Server installation

Security Services PKI Server has several requirements for running on the system:
 Two Web servers, the PKI server task, and one or more LDAP servers
 The first Web server runs on port 80 and 443
 The second Web server runs on port 1433

In a z/OS environment, you will most likely run the PKI Web servers that are already available
in your production LPAR. Because this LPAR can already host existing Web servers on port
80 and 443, we recommend that you set up TCP/IP environment additional domain names for
PKI Services. This setup enables the use of a hidden proxy server configuration on the
default ports to forward to the appropriate servers.

Steps to set up the PKI server

Take the following steps to set up your PKI server:
1. Create and adjust the appropriate security environment (RACF).
2. Prepare and configure the UNIX environment.
3. Set up the Web servers.
4. Configure the LDAP server.
5. Set up the PKI server task.
6. Configure OCSF and OCEP to work with PKI Services.
7. Configure the PKI Services.

136 ABCs of z/OS System Programming Volume 6

3.16 Setting up RACF environment for PKI prerequisites

The following products must be installed prior to

configuring PKI Services:
IBM z/OS HTTP Server
LDAP directory
Cryptographic Services:
Open Cryptographic Services Facility (OCSF)
Open Cryptographic Enhanced plug-in (OCEP)
Integrated Cryptography Service Facility (ICSF) (Optional)
RACF (or equivalent)

Figure 3-16 Setting up RACF for PKI

Setting up RACF for PKI

The implementation of PKI Services requires that z/OS UNIX System Services is active.
Therefore, we expect that most of the UNIX System Services RACF controls are in place as
per the content of member BPXISEC1 in SYS1.SAMPLIB.

The prerequisite products for PKI Services are z/OS HTTP Server or Web server, Lightweight
Directory Access Protocol (LDAP) server, Open Cryptographic Services Facility (OCSF), and
Open Cryptographic Enhanced Plug-ins (OCEP).

Integrated Cryptographic Services Facility (ICSF) and z/OS Communications Server’s

sendmail utility are optional.

z/OS UNIX level security

We recommend that you have z/OS level of UNIX security on your system. The RACF
controls necessary to establish the z/OS UNIX level of security are:
 Program control
 Daemon and server control

Chapter 3. Digital certificates and PKI 137

 Program control
For program control you have to create profile (** in class PROGRAM) and then ADDMEM
the following libraries:
RDEF PROGRAM ** OWNER(MVSMNT) UACC(READ)
RALT PROGRAM ** ADDMEM(‘CEE.SCEERUN’//NOPADCHK +
‘CBC.SCLBDLL’//NOPADCHK +
‘GLD.SGLDLNK’//NOPADCHK +
‘GSK.SGSKLOAD’//NOPADCHK +
‘SYS1.CSSLIB’//NOPADCHK +
‘TCPIP.SEZALOAD’//NOPADCHK +
‘SYS1.LINKLIB’//NOPADCHK +
‘CSF.SCSFMOD0’//NOPADCHK +
‘CSF.SCSFMOD1’//NOPADCHK)

Note: You might want to convert from an existing profile * to profile ** to prevent the output
of RLIST PROGRAM * ALL from displaying all profiles that are created in class PROGRAM
and displaying only the content of profile ** instead. However, be careful. You have to
ADDMEM to profile ** all already-ADDMEMed libraries to profile * (if additional to the ones
above) before issuing RDEL PROGRAM * and SETR WHEN(PROGRAM) REFRESH.

You also might ADDMEM the following libraries to profile ** in PROGRAM, replacing the italic
text (hlq) with HLQs that are used at your site, most likely SYS1:
 If using the Resource Measurement Facility (RMF), hlq.SERBLINK
 If using DB2, hlq.SDSNLOAD and hlq.SDSNEXIT
 If using MQSeries®, hlq.SESQLINK
 If using Run-Time Library Services (RTLS), hlq.SCEERTLS
 If you are obtaining an IEATDUMP by setting the SysDumpName directive and setting the
Recovery directive to Msg/Dump, Normal, or Full, hlq.MIGLIB

Daemon and server control

The command to create a profile for restricting your daemons from being able to change their
identity is:
RDEF FACILITY BPX.DAEMON UACC(NONE) OWNER(SECADM)

Place on the access list only daemons that are allowed to change their identity:
PE BPX.DAEMON CL(FACILITY) ID(daemon1 daemon2) ACC(READ)

Note: Replace daemon1, daemon2, and so forth with RACF user IDs for your respective
daemons.

The command to create a profile to set the scope of z/OS resources that the server can
access when acting as a surrogate for its clients is:
RDEF FACILITY BPX.SERVER UACC(NONE) OWNER(SECADM)

Then place on the access list only daemons that might act as surrogates:
PE BPX.SERVER CL(FACILITY) ID(daemon1 etc) ACC(READ)
PE BPX.SERVER CL(FACILITY) ID(daemon2 etc) ACC(UPDATE)

138 ABCs of z/OS System Programming Volume 6

In this command:
 READ: Both the server ID and the RACF ID of the client must be authorized to access
resources and the client must supply a password.
 UPDATE: The server acts as a surrogate of the client (uses the identity and access
granted to the client without the client’s password being specified).

RACF for Web server

Started task user ID
The command to create a started task user ID for your Web server is:
ADDUSER WEBSTU DFLTGRP(STG) OMVS(UID(0) HOME(’/usr/lpp/internet’)
PROGRAM(’/bin/sh’))

Note: To define your Web server user ID with a non-zero UID and according to your
naming standard for STUs, give this user ID appropriate permissions to directories and
files:
SETFACL -m u:WEBSTU:r-x /usr/lpp/internet/sbin/httpd_V5R3M0
SETFACL -m u:WEBSTU:r-x /web/pki1/httpd.conf
SETFACL -m u:WEBSTU:rwx /web/pki1/logs
SETFACL -m d:u:WEBSTU:rwx /web/pki1/logs
SETFACL -m f:u:WEBSTU:rwx /web/pki1/logs
SETFACL -m u:WEBSTU:rw- /web/pki1/httpd-pid

The Web server’s non-zero user ID must be given read/execute access to the security
DLLs, read/write access to the key database file, and read access to the stash file.

Profile in class STARTED

To create a profile in class STARTED for your Web server procedure, use:
RDEF STARTED WEB*.** STDATA(USER(WEBSTU) GROUP(STG))

Daemon and server control

The commands to control your Web server started task user ID are:
PERMIT BPX.DAEMON CLASS(FACILITY) ID(WEBSTU) ACCESS(READ)
PERMIT BPX.SERVER CLASS(FACILITY) ID(WEBSTU) ACCESS(READ)
SETROPTS RACLIST(FACILITY) REFRESH

Access to profiles in class CSFSERV

Use the following access only if ICSF is active:
PE CSF* CL(CSFSERV) ID(WEBSTU) ACC(R)

RACF for OCSF and OCEP

The use of Open Cryptographic Services Facility (OCSF) and Open Cryptographic Enhanced
Plug-ins (OCEP) is controlled by fixed-name profiles in class FACILITY:
CDS.CSSM Authorizes access to OCSF
CDS.CSSM.CRYPTO Authorizes access to Cryptographic Service Provider
CDS.CSSM.DATALIB Authorizes access to Data Library (DL) Service Provider

All of these resources probably have the same access list, so only one profile can be defined
as follows:
RDEF FACILITY CDS.** UACC(NONE) OWNER(SECADM)

Chapter 3. Digital certificates and PKI 139

 RACF for LDAP
The RACF setup for the LDAP server consists of the following commands:
1. Started task user ID:
ADDUSER LDAPSTU DFLTGRP(STG) NAME(LDAP Started Task User’) +
OMVS(AUTOUID) HOME(‘/’) PROG('/bin/sh'))
2. Profile in class STARTED:
RDEF STARTED LDAP*.** STDATA(USER(LDAPSTU) GROUP(STG))
SETR RACLIST(STARTED) REFR
3. Access to DB2 from TSO and BATCH:
PE DB2subsystem.BATCH ID(LDAPSTU) ACC(R)
4. Daemon and server control:
PE BPX.DAEMON CL(FACILITY) ID(LDAPSTU) ACC(R)
PE BPX.SERVER CL(FACILITY) ID(LDAPSTU) ACC(U)
SETR RACLIST(FACILITY) REFR
5. Access to OCSF:
PE CDS.** CL(FACILITY) ID(LDAPSTU) ACC(R)
6. Access to profiles in class CSFSERV:
PE CSF* CL(CSFSERV) ID(LDAPSTU) ACC(R)

This access is needed only if ICSF is active.

RACF for ICSF

Using ICSF is recommended, but not a prerequisite, for PKI Services. You can install and
configure ICSF before or after setting up PKI Services using these commands:
1. Started task user ID:
ADDUSER ICSFSTU DFLTGRP(STG) NOPASSWORD NAME(‘ICSF Started task user’)
2. ICSF data sets contain Cryptographic Keys (CKDS) and Public Keys (PKDS):
– ICSF.CKDS
– ICSF.PKDS
Use these commands:
AG ICSF SUPGROUP(DATA) OWNER(DATA)
AD ‘ICSF.** OWNER(SECADM) UACC(NONE)
3. Profile in class STARTED:
RDEF STARTED ICSF.** STDATA(USER(ICSFSTU) GROUP(STG))
4. Profiles in the General Resource Class CSFKEYS class protect labels for keys in the
format:
RDEF CSFKEYS label UACC(NONE) AUDIT(ALL)
PE label CL(CSFKEYS) ID(SECADM) ACC(R)
RDEF CSFKEYS ** UACC(NONE) OWNER(SECADM) AUDIT(ALL)
They permit one or several job role groups access.
5. Profiles in the General Resource Class CSFSERV class protect cryptographic services in
fixed-name format:
RDEF CSFSERV service-name UACC(NONE) OWNER(SECADM) AUDIT(ALL)
PE service-name CL(CSFSERV) ID(SECADM) ACC(R)

140 ABCs of z/OS System Programming Volume 6

 Similar to CSFKEYS, you can define a common generic profile:
RDEF CSFSERV ** UACC(NONE) OWNER(SECADM) AUDIT(ALL) or
RDEF CSFSERV CSF* UACC(NONE) OWNER(SECADM) AUDIT(ALL)

If you have not activated CSFKEYS and CSFSERV, issue the commands:
SETR CLASSACT(CSFKEYS CSFSERV)
SETR RACLIST(CSFKEYS CSFSERV)
SETR RACLIST(CSFKEYS CSFSERV) REFR

Chapter 3. Digital certificates and PKI 141

3.17 Add RACF groups for PKI services

IBM HTTP Server for z/OS

Static Web
Pages
SSL H
"Session" T
User T
Browser P
D
CGI Scripts
Generated
client's certificate

Rexx/Saf Interface

SAF Service

RACF Service

RACDCERT components

RACF
SMF DB
SMF
Unload
Client's certificate
Audit Records generated and registered
in the RACF DB

Figure 3-17 RACF groups for PKI services

PKI administrator group

PKI Services administrators play a very powerful role in your organization. The decisions they
make when managing certificates and certificate requests determine who will access your
computer systems and what privileges they will have when doing so. We recommend that you
appoint as PKI administrators one or more of your RACF administrators after some training,
mostly on the use of the RACDCERT command.

All RACF user IDs and groups used in PKI Services must have OMVS segments. The
command to add a specific job role group for PKI administrators is:
AG PKIADM SUPGROUP(JOBROLE) OMVS(AUTOGID)
CO (userid1 userid2 etc) GROUP(PKIADM)

If you need to assign an OMVS segment to your existing RACF admin group, issue the
following command:
ALG SECADM GID(AUTOGID)

PKI started task user ID group

If you need to assign an OMVS segment to your existing RACF default group for started task
user IDs, issue the following command:
ALG STG GID(AUTOGID)

142 ABCs of z/OS System Programming Volume 6

Adding RACF user IDs for PKI Services
PKI started task user ID
The command to create the user ID who runs the PKI procedure (see the PKI procedure in
SYS1.PROCLIB) is as follows:
AU PKISTU NAME(‘PKI SRVS DAEMON’) DFLTGRP(STG) OWNER(STG) + NOPASSWORD
OMVS(AUTOUID HOME(‘/web/pki1/’) PROG(‘/bin/sh’) + ASSIZE(256000000)
THREADS(512))

The ASSIZE and THREADS values are recommended, but you have to increase them if they
are not enough for your workload. The full list of keywords specifying various limits in the
OMVS segment is:
 ASSIZEMAX Maximum address space size
 CPUTIMEMAX Maximum CPU time
 FILEPROCMAX Maximum number of files per process
 MMAPAREAMAX Maximum memory map size
 PROCUSERMAX Maximum number of processes per UID
 THREADSMAX Maximum number of threads per process

After you have set individual user limits for users who require higher resource limits, consider
removing their superuser authority. You should also reevaluate your installation’s BPXPRMxx
limits and consider reducing them.

Surrogate user ID
A surrogate user ID is the identity assigned to client processes when they request PKI
Services. A surrogate user ID is required for external clients. For simplicity, we recommend
using surrogate user IDs for internal clients as well, rather than allowing them to access PKI
Services under their own identities. Our chosen name for surrogate user ID is PKISRV, and the
command to create it is:
AU PKISRV NAME ('PKI SRVS SURROG') DFLTGRP(MISC) OWNER(MISC) +
OMVS(AUTOUID HOME('/') PROG('/bin/sh') ASSIZE(256000000) +
THREADS(512)) NOPASSWORD RESTRICTED

We recommend that this user ID be RESTRICTED with the consequences that the user must
be explicitly permitted with READ to several resources having UACC(READ) or ID(*) with
access READ. The most obvious are:
 Profile ** in class PROGRAM
 A few profiles starting with IRR.DIGTCERT in class FACILITY
 Profile ** in class APPL

(If it has UACC(READ), this equivalent to not having this profile at all).

Adding PKI data set profiles

We recommend that data sets needed for PKI data be named yourprefix.PKI. Replace
yourprefix with a term of your choosing.

Alternatively, if you do not use prefixing, then use an HLQ of PKI.

To define a RACF profile for your PKI data sets, use:

AD ‘PKI.**’ OWNER (PKIADM) AUDIT(ALL)

We used PKI as HLQ.

Chapter 3. Digital certificates and PKI 143

 Note: In the command, we assume that you have turned EGN on, and we omitted UACC.
We recommend UACC(NONE), which is the default. We believe that by using AUDIT(ALL)
auditors will be happy if SMF records for SUCCESS READ and higher are made available.

The recommended permissions are:

PE ‘PKI.**’ ID(MVSMNT) ACC(ALTER)

Usually the MVSMNT group is required to create data sets (VSAM in the case of PKI
Services). Do not forget to place your group with ALTER if you plan to create these data sets
and you do not have OPERATIONS.

To allow your PKI administrators access to PKI data sets, issue this command:
PE ‘PKI.**’ ID(PKIADM) ACC(CONTROL)

Be aware also that the started task user ID for PKI Services (PKISTU) must be able to write
into the PKI data sets:
PE ‘PKI.**’ ID(PKISTU) ACC(CONTROL)

Using RACF to create certificates

The CA acts as a trusted party to ensure that users who engage in e-business can trust each
other. A CA vouches for the identity of each party through the certificates it issues. In addition
to proving the identity of the user, each certificate includes a public key that enables the user
to verify and encrypt communications.

You can use RACF to create, register, store, and administer digital certificates and their
associated private keys, and to build certificate requests that can be sent to a certificate
authority for signing. You can also use RACF to manage key rings of stored digital certificates.
Digital certificates and key rings are managed in RACF primarily by using the RACDCERT
command.

RACF enables you to manage three types of digital certificates:

 User certificate: Associated with a RACF user ID and is used to authenticate the user’s
identity.
 CA certificate: Associated with a certificate authority and is used to verify signatures in
other certificates.
 Site certificate: Associated with a server or network entity other than a user or certificate
authority.

Your organization might already have rules for creating certificates. If not, such rules should
be discussed and established.

The RACDCERT command enables a RACF-defined user ID to use a digital certificate as

identification. The certificate must be one of the supported formats contained in an MVS data
set.

RACDCERT is used to store and maintain digital certificates in RACF and should be used for
all maintenance of the DIGTCERT class profiles and related USER profile fields. However,
USER-related record type 0207 (User Certificate Name Record) provides user ID, certificate
name, and certificate label.

The RACDCERT command is your primary administrative tool for managing digital
certificates using RACF. Granular authorities for use of the RACDCERT command by users

144 ABCs of z/OS System Programming Volume 6

not having SYSTEM SPECIAL are controlled through profiles in the FACILITY class of the
type IRR.DIGTCERT.function.

The RACDCERT command is used to manage resources in these classes:

 DIGTCERT: Profiles contain information about digital certificates as well as the certificate
itself. The user ID associated with the certificate can be found in the APPLDATA field of the
profile.
 DIGTRING: Profiles contain information about key rings and the certificates that are part
of each key ring. Key rings are named collections of the personal, site, and CA certificates
associated with a specific user.
 DIGTNMAP: Profiles contain information about certificate name filters.

Note: Profiles in the DIGTCERT, DIGTRING, and DIGTNMAP classes are maintained
automatically through RACDCERT command processing. You cannot administer profiles in
these classes using the RDEFINE, RALTER, and RDELETE commands. These
commands do not operate with profiles in the DIGTCERT, DIGTRING, and DIGTNMAP
classes.

Create the CA certificate

We recommend that you set up a job to use the RACDCERT command when a long string of
keywords and their values is needed Example 3-1.

Example 3-1 Creating the CA certificate

//your job card
//STEP1 EXEC PGM=IKJEFT01
//SYSLBS DD DSN=SYS1.BRODCAST,DISP=SHR
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
RACDCERT GENCERT CERTAUTH SUBJECTSDN(OU('ITSO PSIE CA') +
O('IBM') C('US')) WITHLABEL('IBM ITSO PSIE PKI1') +
NOTAFTER(DATE(2020/01/01))

You can use the following keywords and values:

 GENCERT: Creates a digital certificate and, potentially, a public or private key pair.
 CERTAUTH: Relates to certificate of a Certificate Authority (CA).
 SUBJECTSDN: Specifies the subject’s distinguished name.
 WITHLABEL(label-name): Specifies the label assigned to this certificate. If specified, this
must be unique to the user ID with which the certificate is associated.
 NOTAFTER: Specifies the local date and time after which the certificate is no longer valid.

Making the CA Certificate HIGHTRUST

The subkeywords TRUST, NOTRUST, and HIGHTRUST indicate whether the status of the
certificate is trusted, not trusted, or highly trusted. Whether the certificate is not trusted or
trusted depends on whether the certificate is valid and whether the private key has been
compromised. Because highly trusted certificates are by definition trusted certificates, any
certificate usage that was enabled by marking the certificate trusted is also enabled by
marking the certificate highly trusted.

Chapter 3. Digital certificates and PKI 145

 However, only CA certificates can be highly trusted. The keyword ALTER is used to change
the status to HIGHTRUST as follows:
RACDCERT CERTAUTH ALTER(LABEL(‘IBM ITSO POK PKI1’)) HIGHTRUST

Backup to a data set

It is absolutely critical to back up the certificate into a data set with the PKCS12DER format.
The keyword is EXPORT:
RACDCERT CERTAUTH EXPORT(LABEL(‘IBM ITSO PSIE PKI1’)) +
DSN(‘PKI.CAPKI1.BACKUP.P12BIN’) +
FORMAT(PKCS12DER) PASSWORD(‘xxxxxxx’)

Note: Be careful when you issue this command because the password is unencrypted, so
you have to remember or find a secure place to store the password for future use. If the
password is lost, this backup becomes useless. Also the password value is case-sensitive.

Save the CA certificate to a data set for import to a UNIX file

Place the CA certificate in an MVS data set in the DER format and then copy it to the HFS file,
as shown in Example 3-2.

Example 3-2 Saving the CA certificate to a data set

RACDCERT CERTAUTH EXPORT(LABEL(‘IBM ITSO POK PKI1’)) +
DSN(‘PKI.CAPKI1.DERBIN’) FORMAT(CERTDER)
chown PKISTU /var/pkiserv
oput 'pki.capki1.derbin' '/var/pkiserv/pkiserv1/cacert.der' binary
chmod 755 /var/pkiserv/cacert.der
chown pkistu /var/pkiserv/*

Create PKI Services key ring

The RACDCERT command to create a key ring for the CA certificate is:
RACDCERT ADDRING(CARING) ID(PKISTU)

In this command:
 ADDRING(‘ring name’): Creates a key ring. Only users can have a key ring. Key ring
names become names of RACF profiles in the DIGTRING class and can contain only
characters that are allowed in RACF profile names. Although asterisks are allowed in ring
names, a single asterisk (*) is not allowed. For a CA certificate, the user who owns the ring
is the PKI daemon. Lowercase characters are permitted. A key ring name can be up to
237 characters in length. Because only user IDs can have key rings, neither CERTAUTH
nor SITE can be specified with ADDRING.
After creating the key ring, add the certificate to the key ring, as shown in Example 3-3.

Example 3-3 Creating PKI Services key ring

RACDCERT ID(PKISTU)
CONNECT(CERTAUTH LABEL(‘IBM ITSO PSIE PKI1’) +
RING(CARING) USAGE(PERSONAL) DEFAULT)

 ID(userid): Indicates that the certificate added to the key ring is a user certificate, and
userid is the user ID that is associated with this certificate. If the ID keyword is not
specified, it defaults to the value specified or the default value on the RACDCERT
command.
– CONNECT: Specifies that a digital certificate is being added to a key ring.

146 ABCs of z/OS System Programming Volume 6

 – CERTAUTH: Indicates that the certificate being added to the key ring is a CA
certificate.
– USAGE: Allows the altering of the trust policy within the confines of a specific key ring.
– DEFAULT: Specifies that the certificate is the default certificate for the ring. Only one
certificate within the key ring can be the default certificate. If a default certificate
already exists, its default status is removed, and the specified certificate becomes the
default certificate. If you want the specified certificate to be the default, DEFAULT must
be explicitly specified.

Create the Web server SSL certificate

After creating the CA certificate, you can issue other types of certificates, such as an SSL
certificate for the Web server started task user ID that is needed to process handshakes with
upcoming client certificates belonging to external or internal users. See Example 3-4.

Example 3-4 Creating the Web server SSL certificate

RACDCERT GENCERT ID(WEBSTU) +
SIGNWITH(CERTAUTH LABEL(‘IBM ITSO PSIE PKI1’)) +
SUBJECTSDN(CN('wtsc64oe.itso.ibm.com’) +
O('IBM') L(‘POUGHKEEPSIE’) SP(‘NEW YORK) C('US')) WITHLABEL('SSL PKI1’) +
NOTAFTER(DATE(2020/01/01))

In this example SIGNWITH(CERTAUTH(LABEL(‘label-name’)) specifies the certificate with

a private key that is signing the certificate. In this example, the private key certificate is the CA
certificate. If SIGNWITH is not specified, the default is to sign the certificate with the private
key of the certificate that is being generated.

Create the Web server key ring

Similar to the CA, you need to create a key ring for the certificates of the Web server with the
following command:
RACDCERT ADDRING(SSLRING) ID(WEBSTU)

Now, connect the CA certificate to the ring that belongs to the Web server:
RACDCERT ID(WEBSTU) CONNECT(CERTAUTH LABEL(‘IBM ITSO PSIE PKI1’) +
RING(SSLRING))

Note: In this example, we did not specify USAGE because the default value of USAGE is
the same as in the added certificate; That is, we preserved USAGE(CERTAUTH). We also
omitted DEFAULT, because we did not want to make the CA certificate be the DEFAULT in
this key ring.

Next, connect the Web server certificate to the Web server ring with this command:
RACDCERT ID(WEBSTU) CONNECT(ID(WEBSTU) LABEL(‘SSL PKI1’) + RING(SSLRING)
USAGE(PERSONAL) DEFAULT)

LIST the CA certificate

To list the CA certificate, use this command:
RACDCERT CERTAUTH LIST(LABEL('IBM ITSO PSIE PKI1'))

Note: You must use the keyword CERTAUTH when listing a CA certificate. The value of
LABEL is case sensitive, so type IBM and not ibm. Also, CERTAUTH can be placed after
list(label( ’ ‘)).

Chapter 3. Digital certificates and PKI 147

 LIST the Web server (SSL) certificate
The command to display the Web server certificate is as follows:
RACDCERT ID(WEBSTU) LIST(LABEL('SSL PKI1'))

Note: You must use the keyword ID( ) when listing a user certificate. Also, ID( ) can be
placed after list(label( ’ ‘)). Remember that the value of LABEL is case sensitive.

Now, we list our Web server certificate issued by our CA:

RL DIGTCERT 01.OU=ITSO¢PSIE¢CA.O=IBM.C=US ALL

Note: The only difference between the profile for our Web server certificate and the profile
for our CA certificate is the serial number. The APPLDATA field contains the user ID
associated with certificate: the Web server started task user ID: WEBSTU.

LIST key ring for user ID PKISTU

The command to list the key ring is:
RACDCERT ID(PKISTU) LISTRING(CARING)

Note: You must always use the keyword ID( ) to list any key ring. Also, ID( ) can be placed
after LISTRING( ). Again, the key ring name is case sensitive.

Daemon and server control for PKI user ID and surrogate user ID
We permit PKISTU read access to BPX.DAEMON and BPX.SERVER in the RACF class
FACILITY, and PKISRV read access to BPX.SERVER in the RACF class FACILITY:
PE BPX.DAEMON CL(FACILITY) ID(PKISTU) ACC(R)
PE BPX.SERVER CL(FACILITY) ID(PKISTU) ACC(R)
PE BPX.SERVER CL(FACILITY) ID(PKISRV) ACC(R)

Allow PKI user ID to act as CA

The following commands enable a PKI user ID to act as a CA:
RDEF FACILITY IRR.DIGTCERT.GENCERT UACC(NONE) OWNER(PKIADM)+
AUDIT(ALL)
RDEF FACILITY IRR.DIGTCERT.LIST UACC(NONE) OWNER(PKIADM)
RDEF FACILITY IRR.DIGTCERT.LISTRING UACC(NONE) OWNER(PKIADM)
PE IRR.DIGTCERT.GENCERT CL(FACILITY) ID(PKISTU) ACC(CONTROL)
PE IRR.DIGTCERT.LIST CL(FACILITY) ID(PKISTU) ACC(R)
PE IRR.DIGTCERT.LISTRING CL(FACILITY) ID(PKISTU) ACC(R)

Note: User IDs having SPECIAL can issue the RACDCERT command with all keywords
and parameters.

Allow a Web server to access its own key ring

To allow a Web server to access its own key ring, use this command:
PE IRR.DIGTCERT.LIST CL(FACILITY) ID(WEBSTU) ACC(R)
PE IRR.DIGTCERT.LISTRING CL(FACILITY) ID(WEBSTU) ACC(R)

Allow Web server user ID to switch identity to surrogate user ID

The commands to enable the Web server user ID to act on behalf of the surrogate user ID
PKISRV (or switch identity to surrogate user ID) are:

148 ABCs of z/OS System Programming Volume 6

 RDEF SURROGAT BPX.SRV.PKISRV
PE BPX.SRV.PKISRV CL(SURROGAT) ID(WEBSTU) ACC(R)

Profile for PKI Services procedure in class STARTED

To use a profile for PKI Services procedure in the class STARTED, use this command:
RDEF STARTED PKISRV*.** STDATA(USER(PKISTU) GROUP(STG)) + OWNER(PKIADM)

This command covers more than one PKI server (for example, if you want a few members in
SYS1.PROCLIB named PKISRV1, PKISRV2, and so on). However, you can run only one PKI
server per LPAR at a time.

Allow access for PKISTU to OCSF

For the PKI Services procedure to start, the PKI Services user ID must have access to the
OCSF services. This access is provided by issuing this command:
PE CDS.** CL(FACILITY) ID(PKISTU) ACC(R)

ICSF
With this command, we assume that ICSF is active. To store a certificate into ICSF, use:
RACDCERT CERTAUTH ADD('PKI.CAPKI1.BACKUP.P12BIN') +
PASSWORD('xxxxxxx') ICSF

In this command:
 ADD(data-set-name): Specifies that a digital certificate is to be defined. The specified
data set must contain the digital certificate. The data set containing the digital certificate or
certificate package must be cataloged and cannot be a PDS or a PDS member. The
RECFM expected by RACDCERT is VB. When the ADD keyword is specified, RACDCERT
allocates and opens the specified data set dynamically and reads the certificate from it as
binary data.
 PASSWORD(‘pkcs12-password’): Specifies the password that is associated with the
PKCS#12 certificate package. This keyword is required if the data set is PKCS#12, and it
must not be specified if the data set is not PKCS#12. The ‘pkcs12-password’ can be up to
255 characters in length, is case sensitive, and can contain blanks.

Note: The specified password is visible. So, take care to prevent it from being viewed when
entered. Because PKCS#12 passwords do not follow the normal TSO/E rules for password
content, they cannot be suppressed as they normally would be.

ICSF specifies that RACF attempts to store the private key that is associated with this
certificate in the ICSF PKDS. This attempt applies when the key is introduced to RACF by
issuing the ADD keyword for PKCS#12 certificate packages and when an existing certificate
profile containing a non-ICSF private key is replaced by issuing the ADD keyword.

If the GENCERT keyword creates a public/private key pair and if ICSF is used to store private
keys, then GENCERT creates an ICSF key label in the format
IRR.DIGTCERT.userid.CVTSNAME.ebcdic-stck-value, where userid is the owning user ID,
CVTSNAME is the system name as taken from the CVT, and ebcdic-stck-value is an EBCDIC
version of the current store clock value. If the key is associated with a CA certificate, then user
ID is set to CERTIFAUTH. If the key is associated with a site certificate, then user ID is set to
SITECERTIF.

Chapter 3. Digital certificates and PKI 149

 Ensure that you have created a profile in class CSFKEYS as follows:
RDEF CSFKEYS IRR.DIGTCERT.** OWNER(PKIADM)
PE IRR.DIGTCERT.** CL(CSFKEYS) ID(PKIADM) ACC(R)

Protect certificate functions

You have to allow the surrogate PKI user ID to use user certificate functions with the following
commands:
RDEF FACILITY IRR.RPKISERV.** OWNER(PKIADM)
PE IRR.RPKISERV.** CL(FACILITY) ID(PKISRV) ACC(CONTROL)

A single profile IRR.RPKISERV.PKIADMIN in class FACILITY can protect all six

administrative-user functions. To disallow access to the administrative-user functions of PKI
Services for the surrogate PKI user ID, place PKISRV on its access list with NONE:
RDEF FACILITY IRR.RPKISERV.PKIADMIN OWNER(PKIADM)
PE IRR.RPKISERV.PKIADMIN ID(PKISRV) ACC(NONE)

We assume that all members of your PKIADM group have SYSTEM SPECIAL. If this is not
the case, then members without SYSTEM SPECIAL must have UPDATE to profile
IRR.RPKISERV.PKIADMIN.

150 ABCs of z/OS System Programming Volume 6

3.18 RACF for PKI Services

Possible activity by RACF administrators after PKI

Services has been set up and customized:
Create a help desk function
Administer help desk with the HostIdMappings extension
Display the PKI Services certificates
Establish PKI Services as intermediate certificate
authority
Renew the PKI Services CA certificate
Recover a CA certificate profile
Control applications that call R_PKIServ
Use encrypted passwords for LDAP servers
Register a personal certificate with RACF

Figure 3-18 RACK for PKI Services

RACF for PKI Services

This section describes the possible activity by RACF administrators after PKI Services has
been set up and customized.

Creating a help desk function

Access CONTROL to the last two profiles ensures that help desk members can list anybody’s
certificates or key rings by issuing the following commands. See Example 3-5.

Example 3-5 Creating a help desk function

AG HELPDESK SUPGROUP(JOBROLE) OWNER(JOBROLE) + OMVS(AUTOGID)
AU HDUSR1 DFLTGRP(EMPL) OWNER(EMPL) OMVS(AUTOUID)
CO HDUSR1 GROUP(HELPDESK)
PE ‘PKI.**’ ID(HELPDESK) ACC(R)
PE IRR.RPKISERV.PKIADMIN CL(FACILITY) ID(HELPDESK) ACC(R)
PE IRR.DIGTCERT.LIST CL(FACILITY) ID(HELPDESK) ACC(C)
PE IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(HELPDESK) ACC(C)

For any user ID having certificates registered in RACF, use the following command:
RACDCERT ID(userid) LIST

If they want to find all CA certificates, use the following command:

RACDCERT CERTAUTH LIST

Chapter 3. Digital certificates and PKI 151

 Alternatively, the last two profiles in Example 3-5 must have UACC(READ) or ID(*) on their
access list with READ. Thus every user ID can display certificates or key rings by issuing:
 RACDCERT LIST: Obtains detailed information for each certificate
 RACDCERT LISTRING(*): Obtains detailed information for each key ring

Note: Help desk can use RACDCERT ID(userid) LISTRING(*) to find all rings that are
associated with a user ID, but a similar command, RACDCERT LIST(*), fails with the
following message:
IKJ56712I INVALID KEYWORD, *
IKJ56703A REENTER THIS OPERAND - .

Administering certificates with the HostIdMappings extension

You can add a HostIdMappings extension to certificates that you create for certain users,
enabling you to specify the user IDs for logging on to particular servers (or hosts). Controlling
an identity used for logon purposes is a very important security objective. Therefore, you must
exercise administrative control in the following areas by authorizing:
 PKI Services as a highly trusted certificate authority whose certificates are honored when
they contain HostIdMappings extensions
 Particular servers to accept logons from clients whose certificates contain
HostIdMappings extensions

To enable the Web server to accept logons from clients who have been issued PKI Services
certificates with HostIdMapping extensions, you must create profiles in the RACF class
SERVAUTH.

Note: Ensure that your CA certificate is altered to HIGHTRUST if it was not HIGHTRUST
when you created it.

Define a profile in class SERVAUTH for each server (host) name that you want your Web
server to honor when accepting logons for certificates containing HostIdMapping extensions.
The profile has the format IRR.HOST.hostname where the value of hostname usually is a
domain name, such as wtsc63oe.itso.ibm.com. This domain name must be entered in the
entry for HostIdMap in /web/pki1/pkiserv/pkiserv.tmpl but without the subject ID portion in the
APPL section.
RDEF SERVAUTH IRR.HOST.WTSC63OE.ITSO.IBM.COM UACC(NONE)

Permit your Web server started task user ID with READ with the following command:
PE IRR.HOST.WTSC63OE.ITSO.IBM.COM CL(SERVAUTH) ID(WEBSTU) ACC(R)

Now activate and raclist class SERVAUTH using the following commands:
SETR CLASSACT(SERVAUTH)
SETR RACLIST(SERVAUTH)
SETR RACLIST(SETRAUTH) REFR

Note: On a z/OS system, a HostIdMapping is not honored if the target user ID was created
after the start of the validity period for the certificate containing the HostIdMappings
extension. Therefore, if you are creating user IDs specifically for certificates with
HostIdMappings extensions, ensure that you create the user IDs before the certificate
requests are submitted.

152 ABCs of z/OS System Programming Volume 6

Display your PKI Services certificates
Often you might want to display your CA certificate or key ring, possibly to diagnose error
conditions.

Display CA certificate
You can display the CA certificate by using two RACF commands. The first is:
RACDCERT CHECKCERT(‘PKI.CAPKI1.DERBIN’)

In this command, PKI.CAPKI1.DERBIN is the data set to which we saved the CA certificate in
DER format.

It is important to note, when diagnosing errors, that:

 The first line must indicate that this is a CERTAUTH certificate.
 The Private Key Type and Size must be present.
 If the Serial Number is not equal to 00, this indicates that the certificate has been renewed
or was issued by another certificate authority.

The second RACF command to display the CA certificate uses the LIST keyword of
RACDCERT:
RACDCERT CERTAUTH LIST(LABEL(‘ITSO IBM PSIE PKI1’))

Display CA key ring

To display the CA key ring, enter the following command:
RACDCERT ID(PKISTU) LISTRING(CARING)

The ring information must have USAGE = PERSONAL and DEFAULT = YES.

Display certificates using utilities iclview and vosview

Sometimes you might want to display your Issued Certificates List (ICL) or your Certificates
Request List (CRL). These lists are kept respectively in VSAM data sets PKI.WEBPKI1.ICL
and PKI.WEBPKI1.OST. These lists are independent of RACF, although ICL may contain
certificates registered in RACF. To display ICL and CRL, two utilities can be used: iclview
and vosview, respectively. Issue the OMVS command and do the following to display all
certificates issued by PKI Services:
cd /usr/lpp/pkiswerv/lib
/usr/lpp/pkiserv/bin/iclview/ \’pki.webpki1.icl\’

To display all certificate requests received by PKI Services after issuing OMVS:
cd /usr/lpp/pkiswerv/lib
/usr/lpp/pkiserv/bin/vosview/ \’pki.webpki1.ost\’

Note: Records starting with Object key=1 and Object key =2 contain only system
data.Records starting with Object key=108 is a request sent by user ta for a 1-Year PKI
SSL Browser certificate. (The type of certificate is represented by appldata =1YBSSL).

Establishing PKI Services as intermediate certificate authority

The default setup for PKI Services establishes the PKI Services certificate authority as a root
CA, also known as a self-signed CA. Because there is no established trust hierarchy leading
to a self-signed certificate, it is impossible to verify that a self-signed certificate is genuine.
Accordingly, any person or application that wants to process certificates issued by a root
authority must explicitly trust the authenticity of the self-signed CA certificate.

Chapter 3. Digital certificates and PKI 153

 Alternately, you can establish the PKI Services certificate authority as an intermediate
(subordinate) certificate authority. An intermediate certificate authority is one whose
certificate is signed by another higher certificate authority.

Perform the following steps to establish PKI Services as an intermediate certificate authority:
1. Determine which certificate authority will be acting as a higher authority for your PKI
Services, which can be a public CA such as VeriSign.
2. Create a new certificate request from your self-signed CA certificate by entering the
following RACF command:
RACDCERT CERTAUTH GENREQ(LABEL(‘IBM ITSO PSIE PKI1’)) +
DSN(‘PKI.CAPKI1.BACKUP.P12BIN’)
3. Send the certificate request to the higher certificate authority, following its required
procedures.
4. After the certificate has been issued, receive the certificate back into the certificate data
set (PKI.CAPKI1.BACKUP.P12BIN).

Note: The procedure for receiving the certificate back into the certificate data set can
vary greatly depending on how the higher certificate authority delivers the new
certificate: If the certificate is delivered as base64 encoded text, the easiest way to
deposit the certificate into the data set is to copy and paste the certificate into the empty
data set. If the certificate is delivered as binary data (also called DER-encoded), the
easiest way to deposit the certificate into the data set is to use binary FTP.

5. Receive the certificate back into the RACF database by entering the following RACF
command:
RACDCERT CERTAUTH ADD(‘PKI.CAPKI1.BACKUP.P12BIN’)
6. Export the certificate in DER format to the export data set by entering the following RACF
command:
RACDCERT CERTAUTH EXPORT(LABEL(‘IBM ITSO PSIE PKI1‘))
DSN(‘PKI.CAPKI1.DERBIN’) FORMAT(CERTDER)
7. To make your new certificate available to your clients, set up the /var/pkiserv/ directory by
performing step 2 through step 4 in “Steps for setting up the /var/pkiserv directory” from
z/OS Security Server PKI Services Guide and Reference, SA22-7693.

Renewing your PKI Services CA certificate

Eventually, your PKI Services CA certificate will expire. To avoid complications related to its
expiration, you should renew the certificate before it actually expires.

Note: You will receive MVS console message IKYP026E as the expiration date
approaches.

154 ABCs of z/OS System Programming Volume 6

Perform the following steps to renew your PKI Services CA certificate:
1. Create a new certificate request from your self-signed CA certificate by entering the
following RACF command:
RACDCERT CERTAUTH GENREQ(LABEL(‘IBM ITSO PSIE PKI1‘)) +
DSN(‘PKI.CAPKI1.BACKUP.P12BIN’)
2. If your PKI Services certificate authority is a root CA (that is, it has a self-signed certificate,
which is the default), then generate the self-signed renewal certificate by entering the
following RACF command:
RACDCERT CERTAUTH GENCERT(‘PKI.CAPKI1.BACKUP.P12BIN’) + SIGNWITH(CERTAUTH +
LABEL(‘IBM ITSO PSIE PKI1‘))
3. Alternately, if your PKI Services certificate authority is an intermediate certificate authority,
repeat step 2 to step 4 in “Steps for setting up the /var/pkiserv directory” from z/OS
Security Server PKI Services Guide and Reference, SA22-7693.

Recovering a CA certificate profile

If the CA certificate profile in RACF is deleted accidentally, you can recover it from the backup
data set.

Perform the following steps to recover a CA certificate profile:

1. Enter the following RACF commands:
RACDCERT CERTAUTH ADD(‘PKI.CAPKI1.BACKUP.P12BIN’) +
PASSWORD(your-passphrase)
WITHLABEL(‘IBM ITSO PSIE PKI1‘) ICSF
RACDCERT CERTAUTH ADD(‘PKI.CAPKI1.DERBIN’)
RACDCERT ID(PKISTU) CONNECT(CERTAUTH LABEL(‘IBM ITSO PSIE PKI1‘)
RING(CARING) USAGE(PERSONAL) DEFAULT)
2. Perform the following steps to update the RACF profile with the serial number of the last
CA certificate PKI Services issued. (You must restore the certificate serial number
incrementer value that is stored in the profile because otherwise PKI Services resumes
issuing certificates starting from serial number 1.)
a. Ensure that PKI Services is stopped.
b. Enter the following command from the UNIX command line to change your directory:
cd /usr/lpp/pkiserv/lib
3. Now run the iclview utility:
/usr/lpp/pkiserv/bin/iclview \’pki.webpki1.icl\’
4. Record the serial number displayed (in hex) of the CA certificate listed under Cert 1. The
serial number (in hex) of our CA certificate was 0.
a. To determine your CA certificate’s profile name, issue the following command to
perform an unsuccessful add:
RACDCERT CERTAUTH ADD(’PKI.CAPKI1.DERBIN’) +
WITHLABEL(’*** Bad Label***’)
The unsuccessful add displays this error message:
IRRD109I The certificate cannot be added. Profile
00.OU=ITSO’PSIE’CA.O=IBM.C=US is already defined.
b. Record the profile name:
Our profile name was: 00.OU=ITSO’PSIE’CA.O=IBM.C=US

Chapter 3. Digital certificates and PKI 155

 5. Create the ICHEINTY ALTER job in your JCL data set, replacing the highlighted values
based on the information you recorded in the previous steps.

Controlling applications that call R_PKIServ

Authorized applications, such as servers, that invoke the R_PKIServ callable service
(IRRSPX00) can request the generation, retrieval, and administration of PKIX-compliant
X.509 Version 3 certificates and certificate requests.

Applications can request user functions or administrative functions related to these requests.
See z/OS Security Server RACF Callable Services, SA22-7691, for details of invoking
IRRSPX00. Authorize these applications by administering RACF profiles in the FACILITY
class, based on whether the application requests user functions or administrative functions.

R_PKIServ user functions

The user functions are:
 EXPORT: Retrieves (exports) a previously requested certificate.
 GENCERT: Generates an auto-approved certificate.
 GENRENEW: Generates an auto-approved renewal certificate.
 REQCERT: Requests a certificate that an administrator must approve before it is created.
 REQRENEW: Requests certificate renewal. The administrator must approve the request
before the certificate is renewed.
 REVOKE: Revokes a certificate that was issued previously.
 VERIFY: Confirms that a given user certificate was issued by this CA and, if so, returns the
certificate fields.

For user functions, FACILITY class profiles protect this interface. The form of the FACILITY
class profiles is:
IRR.RPKISERV.function

Here, function is one of the following user function names in the preceding list. The user ID for
the application (userid from the ACEE associated with the address space) is used to
determine access:
 NONE: Access is denied.
 READ: Access is permitted based on subsequent access checks against the caller’s user
ID. To determine the caller, the current TCB is checked for an ACEE. If one is found, the
authority of that user is checked. If there is no ACEE associated with the current TCB, the
ACEE associated with the address space is used to locate the user ID.
 UPDATE: Access is permitted based on subsequent access checks against the
applicant’s user ID.
 CONTROL (or user ID is RACF SPECIAL): Access is permitted, and no subsequent
access checks are made.

For SAF GENCERT and EXPORT requests where the application has READ and UPDATE
access, subsequent access checks are performed against the IRR.DIGTCERT.function
FACILITY profiles. These are identical to the checks the RACDCERT TSO command makes.
See z/OS Security Server RACF Command Language Reference, SA22-7867, for more
information.

156 ABCs of z/OS System Programming Volume 6

For PKI Services EXPORT, GENCERT, GENRENEW, REQCERT, REQRENEW, REVOKE,
and VERIFY requests in which the application has READ and UPDATE access, subsequent
access checks are performed against the IRR.DIGTCERT.function FACILITY profiles.

R_PKIServ administrative functions

The administrative functions are:
 CERTDETAILS: Get detailed information about one PKI Services issued certificate.
 MODIFYCERTS: Change PKI Services issued certificates.
 MODIFYREQS: Change PKI Services certificate requests.
 QUERYCERTS: Query PKI Services issued certificates.
 QUERYREQS: Query PKI Services about certificate requests.
 REQDETAILS: Get detail information about one PKI Services certificate request.

For the administrative functions, a single FACILITY class

profile—IRR.RPKISERV.PKIADMIN—protects this interface:
 If the caller is RACF SPECIAL, no further access is necessary.
 Otherwise, the caller needs:
– READ access to perform read operations (QUERYREQS, QUERYCERTS,
REQDETAILS, and CERTDETAILS)
– UPDATE access for the action operations, (MODIFYREQS and MODIFYCERTS)

To determine the appropriate access level of the caller, the current TCB is checked for an
ACEE. If one is found, the authority of that user is checked. If there is no ACEE associated
with the current TCB, the ACEE associated with the address space is used to locate the user
ID.

Attention: UPDATE access to the IRR.RPKISERV.PKIADMIN resource also controls who

can act as PKI Services administrators.

Recommendation: Give UPDATE authority only to those individuals whom you would trust
with the RACF SPECIAL attribute. If you do assign PKI Services administrators who do not
have the RACF SPECIAL attribute, do not also give these individuals direct access to the
user functions of the R_PKIServ callable service as described in “R_PKIServ user
functions” on page 156.

Using encrypted passwords for LDAP servers

PKI Services uses an LDAP directory to store certificates. LDAP requires authenticating
(binding) to the directory. You can do this by using a distinguished name and passwords.
Passwords for binding (to multiple LDAP directories) can be encrypted or in unencrypted text.
Your security policy should stipulate whether to use encrypted LDAP bind passwords. You
store information about passwords in the PKI Services configuration file, pkiserv.conf. If you
do not need the bind password for the LDAP server to be encrypted, you specify the values
for Server1, AuthName1 and AuthPwd1 in the pkiserv.conf configuration file, otherwise you
should comment them out.

Chapter 3. Digital certificates and PKI 157

 Perform the following steps to use encrypted LDAP bind passwords:
1. Define a fixed-name profile LDAP.BINDPW.KEY in RACF class KEYSMSTR by entering
the following command, replacing the highlighted value with your own key selected
randomly using hexadecimal values from 0 to F:
RDEFINE KEYSMSTR LDAP.BINDPW.KEY SSIGNON(KEYENCRYPTED(A7D8E09ACDEF35AC))
The SSIGNON segment has two possible keywords:
– KEYMASKED: Used when ICSF is not active
– KEYENCRYPTED: Used when ICSF is active
A7D8E09ACDEF35AC is the value of the key. (Replace this with your own key.)
2. Activate the KEYSMSTR class by entering the following command:
SETROPTS CLASSACT(KEYSMSTR)

Now, you have two alternatives:

 Use profiles in RACF class LDAPBIND for each LDAP directory.
 Use fixed-name profile IRR.PROXY.DEFAULTS in class FACILITY instead of LDAPBIND
class.

Profiles in class LDAPBIND

For each LDAP directory, create your own profile (in our case LDAPKI) in RACF class
LDAPBIND by entering the following command:
RDEFINE LDAPBIND LDAPKI + PROXY(LDAPHOST(ldap://wtsc64.itso.ibm.com:3389)
BINDDN('CN=LDAPADMIN') + BINDPW(LDAPADMIN))

Now you have to update the pkiserv.conf file as follows:

# Server1=wtsc64.itso.ibm.com:3389
# AuthName1=CN=LDAPADMIN
# AuthPwd1=LDAPADMIN
-------
BindProfile1=LDAPKI

Profile in Class FACILITY

If you intend to use profile IRR.PROXY.DEFAULTS in class FACILITY instead of the
LDAPBIND class for encrypted LDAP bind passwords, enter the following command to create
the profile:
RDEFINE FACILITY IRR.PROXY.DEFAULTS +
PROXY(LDAPHOST(ldap://wtsc64.itso.ibm.com:3389) +
BINDDN('CN=LDAPADMIN') +
BINDPW(LDAPADMIN))

You have to update pkiserv.conf by commenting out all four statements:

# Server1=wtsc64.itso.ibm.com:3389
# AuthName1=CN=LDAPADMIN
# AuthPwd1=LDAPADMIN
-------
#BindProfile1=LDAPKI

Using LDAPBIND is more flexible because it enables the creation of as many profiles for
LDAP servers to which you need to authenticate. (Using FACILITY provides only one LDAP
server.)

158 ABCs of z/OS System Programming Volume 6

You might want to list the segment PROXY to check your work with the RLIST command. If
you are using the LDAPBIND class, enter the following:
RLIST LDAPBIND LDAPKI PROXY NORACF

Register a Personal Certificate with RACF

This function is documented in member RACINSTL of SYS1.SAMPLIB under name
SELFREG number 33. The application consists of three HTML pages and a REXX routine.

To be able to use this application, you must:

 Have one or more Personal Certificates installed in your browser.
 Have a valid user ID in RACF.

This application enables you to register a Personal Certificate with RACF, which means that
you associate the certificate with your RACF user ID.

You can also deregister a previously registered Personal Certificate. When you do this, the
information about your certificate is removed from RACF.

To install this application into your two Web servers’ httpd.conf file:
1. Add into /web/pki1/pub/index.html and /web/pki1a/index.html reference to the application:
This is the <a href="selfreg.html"> RACF Selfreg Appl</a>
2. Create two new directories in /web/pki1 and /web/pki1a (ocgi and rar):
mkdir /web/pki1/ocgi and mkdir /web/pki1a/ocgi
mkdir /webpki1/rar and mkdir /web/pki1a/rar
3. Copy the three HTML pages from SYS1.SAMPLIB(RACFINSTL) - selfreg.html,
selfrgft.html, and selfrghd - as files of directory rar. Copy selfreg.rexx into directory ocgi.
4. Add the following into the /web/pki1/httpd.conf file:
Redirect /PKIServ/clientauth-cgi/* https://wtsc64oe.itso.ibm.com:8013/ +
PKIServ/clientauth-cgi/*
5. Add the following into the /web/pki1a/httpd.conf file:
Exec /ocgi/* /web/pki1a/ocgi/*
Pass /rar/* /web/pki1a/rar/*

Now start your browser and find your Web server address by typing:
http://wtsc64oe.itso.ibm.com:8010

The application requests a valid certificate to use it. Click the RACF Selfreg Appl.

When you click the Verify Personal Certificate button, you are presented with a list of the
personal certificates installed into your browser. After you have made a selection, you will be
prompted for your RACF user ID and password and after entering them, a confirmation panel
shows information from the certificate you selected and your RACF user ID.

If the data is correct, click Register Personal Certificate to associate your user ID with your
certificate. If you want to delete a previously registered certificate from RACF, go back, select
the certificate from the list kept in your browser, and click Deregister Personal Certificate.

Now you might want to use RACDCERT LIST to see your new certificate in RACF. It displays
last in the list of your certificates.

Chapter 3. Digital certificates and PKI 159

3.19 Prepare and configure the UNIX System Services
environment

Figure 3-19 Prepare and configure the UNIX System Services environment

As you prepare the environment, decide where to place your configuration files for the
location of additional run-time and configuration file directories for backup or failover reasons.

IBM z/OS Security Server PKI Services Guide and Reference, SA22-7693 defines the
following default locations for directories:
 PKI Services installation directory /usr/lpp/pkiserv
 PKI Services run-time directory /etc/pkiserv
In our setup, we used the corresponding Web server run-time directory /web/server1 to
host the PKI server configuration and run-time files.
 PKI Services variable directory /var/pkiserv
This is the place where you store your CA certificate for public download.

160 ABCs of z/OS System Programming Volume 6

Other products’ default directories are:
 Web server run-time directory /etc
As indicated in several other publications, you should define a schema that supports a
parallel run-time for many Web servers. We recommend using /web/server1, web/server2,
and more.
 OCSF and OCEP variables directory /var/ocsf
 LDAP server run-time /etc/ldap
You may set up several LDAP servers, so you might consider placing these config files into
a certain structure similar to the Web server config files.
This can be /ldap/ldap1, /ldap/ldap2, and so on.
Standard LDAP configuration is looking for a slapd.conf file or ldap.slapd.profile in this
directory.
 PKI object store (OST) PKISRVD.VSAM OST
 PKI issued certificate list (ICL) PKISRVD.VSAM.ICL

Note: In a single z/OS environment there can only be one active PKI server.

Chapter 3. Digital certificates and PKI 161

3.20 Setting up the Web servers for PKI

Setting up the web servers for PKI:

Setting up the web server as a secure web server
Customizing the web server for SSL
Customizing the first web server for PKI
Customizing the second web server for PKI

Figure 3-20 Setting up the Web servers for PKI

Setting up the Web servers for PKI

In this chapter, we make the assumption that you have already set up the IBM HTTP Server
for z/OS (Web server) to run as a standard Web server on port 80. The setup of this Web
server can be cloned to a second one because PKI Services must run at least two Web
servers.

We used the following names for our Web server run-time library in HFS:
 /web/pki1
 /web/pki1a

Benefit of using two Web servers

The first Web server is running normal mode (port 80) and standard secure mode (port 443).
It is used to request, administer, and obtain certificates.

The second Web server is running SSL mode only (normalmode off) on a special port (port
1443) and is used for client authentication. It is set up to authenticate client certificates by
using an X500 server (LDAP server). This Web server is used for renew and revoke certificate
actions.

162 ABCs of z/OS System Programming Volume 6

Setting up the Web server as a secure Web server
To enable the Web server for SSL, use a server certificate. This certificate could be obtained
from Certification Authorities (CAs) such as VeriSign. You can also generate a self-signed
certificate.

There are several ways to generate these certificates. On z/OS you could use either the
gskkyman utility or RACF services. In the next sections, we describe the RACF services
method of generating a self-signed certificate.

Customizing the Web server for SSL

If you have already created a self-signed certificate using RACF, then you have this certificate
in a key ring. If you obtained a certificate from an external source, ensure that it is received
into a key ring.

In IBM z/OS Security Server PKI Services Guide and Reference, SA22-7693, the RACF key
ring is named SSLring. We suggest giving this a more specific name, because there can be
more key rings for different purposes. We named our key ring webpki2, which is similar to the
Web server that we used to run the PKI Services.

To finalize your secure Web server setup, you must customize the Web server configuration
file /web/pki2/httpd.conf with the configuration directives shown in Example 3-6.

Example 3-6 Customizing the Web server configuration file

# keyfile key.kdb <- default
keyfile webpki2 SAF <- changed to RACF keyring
sslmode on <- default
sslport 443 <- default
normalmode on <- default

When you have made the changes to the httpd.conf file, restart the Web server to pick up the
changes. Then, you can test the secure Web server from a browser as follows:
 If you used the default SSL port 443:
https://<web-server-domain-name>
 If you are using a port number other than the default
https://<web-server-domain-name>:<SSL port number>

Set up the second Web server serving SSL only on port 1443 (or a different port such as
8443). In this case, the definitions in Example 3-7 must be customized in
/web/pki2/httpd.conf.

Example 3-7 Customizing the second Web server configuration file

# keyfile ley.kdb <- default
keyfile webpki2 CLINETAUTH <- changed to RACF keyring
sslmode on <- default
sslport 1443 <- changed to the another SSL port
normalmode off <- changed - no unencrypted mode

Chapter 3. Digital certificates and PKI 163

 Customizing the first Web server for PKI
All of the customization parameters for PKI Services are defined in a sample httpd.conf that
resides in /usr/lpp/pkiserv/samples.

We suggest that you split the file in several pieces and attach them in certain locations to your
existing httpd.conf.

In the following sequence, we assume the following:

 Web server runs on ports 80 and 443.
 The other Web server runs on port 1443.
 The domain name for our PKI servers is pki.itso.ibm.com.
 SSL setup is finished.
 PKI surrogate user ID is PKISRV.
 Web server config files are in /web/server1.
 The location of the CA certificate is /var/pkiserv.

For performance reasons, we changed the location of the redirect statements in httpd.conf so
that they appear before the protection statements. The following sequence illustrates how to
update your httpd.conf:
1. Search for the following lines in httpd.conf:
# =================================================================== #
#
# User authentication and document protection
#
# ================================================================== #
2. Scroll a little farther, then add the Protection statements just as shown here:
# The following rules allow anyone who knows your WEBADM
# password to use the Web Server remote configuration application.
#
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
3. Add the statements to your httpd.conf as shown in Example 3-8.

Example 3-8 Adding statements to httpd.conf

#-----------------------------------------------------------------
# Redirection directives for the PKI server
#-----------------------------------------------------------------
# make sure all requests come in through SSL
Redirect /PKIServ/ssl-cgi/* https://pki.itso.ibm.com:443/PKIServ/ssl-cgi-bin/*
#
# redirect client auth requests to the other Web server on port 1443

164 ABCs of z/OS System Programming Volume 6

Redirect /PKIServ/clientauth-cgi/*
https://pki.itso.ibm.com:1443/PKIServ/clientauth-cgi/*
#-----------------------------------------------------------------
# End of Redirection directives for the PKI server
#-----------------------------------------------------------------
#-----------------------------------------------------------------
# Protection directives for the PKI server
#-----------------------------------------------------------------
Protection PublicUser {
ServerId PublicUser
UserID PKISRV
Mask Anyone
}
Protect /PKIServ/public-cgi/* PublicUser
Protect /PKIServ/ssl-cgi-bin/* PublicUser
Protect /PKIServ/* PublicUser
Protection AuthenticatedUser {
ServerId AuthenticatedUser
AuthType Basic
PasswdFile %%SAF%%
UserID %%CLIENT%%
Mask All
}
Protect /PKIServ/ssl-cgi-bin/auth/* AuthenticatedUser
Protection SurrogateUser {
ServerId SurrogateUser
AuthType Basic
PasswdFile %%SAF%%
UserID PKISRV # <-check for your actual PKI Surrogate user ID
Mask All
}
Protect /PKIServ/ssl-cgi-bin/surrogateauth/* SurrogateUser
#-----------------------------------------------------------------
# End of protection directives for the PKI server
#-----------------------------------------------------------------

4. Now search for the following lines in httpd.conf:

# =================================================================== #
#
# Mapping rules
#
# =================================================================== #
5. Scroll a little farther, then add the mapping rules as shown Example 3-9.

Example 3-9 Add mapping rules

# *** ADD NEW PASS RULES HERE ***
#-----------------------------------------------------------------
# Mapping rules for the PKI server
#-----------------------------------------------------------------
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/*
#
#-----------------------------------------------------------------

Chapter 3. Digital certificates and PKI 165

 # End of mapping rules for the PKI server
#-----------------------------------------------------------------
# Note that we have set up the public Web pages to reside in
/web/server1/pub
#
Pass /* /web/server1/pub/*

6. The rest of the configuration directives mentioned in /usr/lpp/pkiserv/samples/httpd.conf

are already configured in the default setup for the Web server. You might want to check
them as follows:
AddType .cer application/x-x509-user-cert ebcdic 0.5 # Browser Certificate
AddType .der application/x-x509-ca-cert binary 1.0 # CA Certificate
7. Now add the additional variables to the httpd.envvars file as indicated in the sample
httpd.envvars file.
We suggest adding the following two variables to the end of the httpd.envvars:
_PKISERV_CONFIG_PATH=/etc/pkiserv
#_PKISERV_EXIT=/<full-path-to-pkiexit>/pkiexit
Here, _PKISERV_CONFIG_PATH should be the Web server run-time directory
(/web/pki2) where the PKI server configuration files reside.

Customizing the second Web server for PKI

This is the setup for the second Web server that runs in SSL mode only on port 1443. It is set
up to do client authentication and check the CRL against LDAP.

All the customization parameters for PKI Services are defined in a sample httpd.conf that
resides in /usr/lpp/pkiserv/samples.

We suggest that you to split the file into several pieces and add them in certain locations to
your existing httpd.conf.

In the following example, we assume the following:

 Web server runs on port 1443.
 The other Web server runs on ports 80 and 443.
 The domain name for our PKI servers is pki.itso.ibm.com.
 SSL setup is finished.
 PKI surrogate user ID is PKISRV.
 Web server config files are in /web/server2.

The following text illustrates how to update your httpd.conf. To update httpd.conf:
1. Search for the following lines in httpd.conf:
# =================================================================== #
#
# User authentication and document protection
#
# =================================================================== #

166 ABCs of z/OS System Programming Volume 6

2. Scroll a little farther, and add the Protection statements as shown in Example 3-10.

Example 3-10 Add the Protection statements

# The following rules will allow anyone that knows your WEBADM
# password to use the Web Server remote configuration application.
#
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
#-----------------------------------------------------------------
# Redirect directives for the PKI server
#-----------------------------------------------------------------
#
# redirects the public requests to the non SSL Web server
Redirect /PKIServ/public-cgi/* http://pki.itso.ibm.com:80/PKIServ/public-cgi/*
# redirects the non client auth SSL reuests to the Web server on port 443 *
Redirect /PKIServ/ssl-cgi/* https://pki.itso.ibm.com:443/PKIServ/ssl-cgi-bin/*
#-----------------------------------------------------------------
# End of Redirect directives for the PKI server
#-----------------------------------------------------------------
#-----------------------------------------------------------------
# Protection directives for the PKI server
#-----------------------------------------------------------------
Protection RenewRevokeUser {
ServerId RenewRevokeUser
AuthType Basic
UserID PKISRV
SSL_CLIENTAUTH Client
Mask Anyone
}
Protect /PKIServ/clientauth-cgi/* RenewRevokeUser
Protection AuthenticatedAdmin {
ServerId AuthenticatedAdmin
AuthType Basic
UserID %%CERTIF%%
SSL_CLIENTAUTH Client
Mask Anyone
}
Protect /PKIServ/clientauth-cgi/auth/* AuthenticatedAdmin
#-----------------------------------------------------------------
# End of protection directives for the PKI server
#-----------------------------------------------------------------

Chapter 3. Digital certificates and PKI 167

 3. Now search for the following lines in httpd.conf:
# =================================================================== #
#
# Mapping rules
#
# =================================================================== #
4. Scroll a little farther, then add the mapping rules as shown Example 3-11.

Example 3-11 Add mapping rules

# *** ADD NEW PASS RULES HERE ***
#-----------------------------------------------------------------
# Mapping rules for the PKI server
#-----------------------------------------------------------------
Exec /PKIServ/clientauth-cgi/* /usr/lpp/pkiserv/PKIServ/clientauth-cgi-bin/*
#-----------------------------------------------------------------
# End of mapping rules for the PKI server
#-----------------------------------------------------------------
# Note that we have set up the public Web pages to reside in
/web/server2/pub
Pass /* /web/server2/pub/*

5. Now search for the following lines in httpd.conf:

# SSLClientAuth directive:
#
6. Scroll a little farther, then add the SSLClientAuth statements as shown Example 3-12.

Example 3-12 Add the SSLClientAuth statements

...
# SSLClientAuth off
SSLClientAuth strong
...
# SSLX500CARoots local_only
SSLX500CARoots local_and_x500
...
# SSLX500Host my.x500host.com
# SSLX500Host <ldap-server-name>
SSLX500Host wtsc63.itso.ibm.com
...
# SSLX500Port 22343
# SSLX500Port <ldap-port-number>
SSLX500Port 22343
...
# SSLX500UserID myUserId
# SSLX500Password myPassword
# SSLX500UserID <ldap-distinguished-name>
# SSLX500Password <ldap-password>
SSLX500UserID ADMIN
SSLX500Password secret

Set up the httpd.envvars exactly as described in “Customizing the first Web server for PKI” on
page 164, but set the _PKISERV_CONFIG_PATH= variable to point to the second Web
server run-time /web/pki2.

168 ABCs of z/OS System Programming Volume 6

3.21 Setting up the LDAP server for PKI

Setting up the LDAP server for PKI:

LDAP setup: running the ldapcnf utility
DB2 (TDBM) for LDAP setup
LDAP proc and the configuration file
Starting the LDAP server and loading the schema
Defining the suffix and administrator

Figure 3-21 Setting up the LDAP server for PKI

Setting up the LDAP server for PKI

We suggest that you set up more than one LDAP server for availability purposes. The first one
can be local on the same image as PLI services, the other somewhere in the network. In the
PKI configuration you can define several LDAP servers. The first one that is found active is
the one that PKI Services uses to replicate the CA certificate and the CRL (Certificate
Revocation List).

For the PKI Services LDAP environment, you might set up a special LDAP database in the
TDBM back-end store. We called ours LDAPPKI.

Other information needed from the LDAP environment for PKI Services is:
 LDAP domain name and port number:
wtsc63.itso.ibm.com:3389
 An admin user ID and password:
ADMINDN='cn=Admin'
ADMINPW='secret'

Instead of setting up domain name, user ID, and port, as hard coded and in unencrypted text
as described here, you might choose to use a RACF definition instead.

Chapter 3. Digital certificates and PKI 169

 The other consideration for LDAP for PKI Services is how you set up your LDAP tree. We
decided to set up a tree based on the suffix cn=US, which allowed us to use just one suffix.
cn=US is the country definition for our CA setup.

The setup for the LDAP server follows the basic installation procedures for the TDBM as
described in z/OS Security Server LDAP Server Administration and Use, SC24-5923. Your
environment influences the way you set up your LDAP server, so we offer the base
requirements for the installation of the PKI LDAP server.

LDAP setup: Running the ldapcnf utility

The LDAP files are installed into the UNIX subdirectory /usr/lpp/ldap. To build the LDAP
server using the ldapcnf utility, copy the following files into a work directory from the
/usr/lpp/ldap/etc directory:
 ldap.profile
 ldap.db2.profile
 ldap.slapd.profile
 ldap.racf.profile

This section describes the DB2 and TCP/IP interfaces with the LDAP server. For a complete
explanation of these files and the use of ldapcnf, read z/OS Security Server LDAP Server
Administration and Use, SC24-5923. In the ldap.profile file, the important parameters that
must be set and matched with the PKI templates and your system environment are:
 TDBM_SUFFIX, which is the suffix that is created within the LDAP configuration file. It
should match the suffix with the PKI templates.
 LDAPUSRID and LDAPUSRGRP, which are the LDAP server’s RACF user ID and group.
These should match what was defined previously.
 ADMINDN and ADMINPW, which are the LDAP server’s administrator. This must match
what is in the PKI templates unless you are going to access controls within LDAP. The
ADMINPW is used for the initial installation of the LDAP server and will be changed when
the LDAP administrator is defined within the LDAP directory. Either the changed password
must match what is coded into the PKI templates, or you could use a RACF user ID if the
SDBM is set up, or you could use the new LDAPBIND features.
 The remainder of the parameters are HLQ for system data sets, locations of required
information for the ldapcnf utility, and so on. All of these must match what is in your
system environment for the ldapcnf utility to work correctly.
 One last important parameter is the location of the output from the ldapcnf utility. The
output is placed in the data set indicated by the OUTPUT_DATASET parameter.

In our case, the important part of the ldap.profile file appeared as shown in Example 3-13.

Example 3-13 The ldap.profile file

OUTPUT_DATASET='JJONES.LDAPOUT'
LDAPUSRID='LDAPSRV'
LDAPUSRGRP='LDAPGRP'
TDBM_SUFFIX='c=US'
ADMINDN='cn=Admin'
ADMINPW='secret'

Within the ldap.slapd.profile file, the following parameters must be set appropriately:
 LDAP_HOSTNAME, which is the IP address of your LDAP server.
 PORT, which is the unsecure port on which the LDAP server is listening.

170 ABCs of z/OS System Programming Volume 6

 There are other parameters that you can set if you are using SSL, replication, SDBM,
multiserver mode, password encryption, and so on. Because these parameters are not
required, we do not discuss them here.

In our case, the important part of the ldap.slapd.profile appeared as in Example 3-14.

Example 3-14 The ldap.slapd.profile

LDAP_HOSTNAME='wtsc63.itso.ibm.com'
PORT='3389'

Nothing within the ldap.db2.profile is required to match the PKI environment, but the LDAP
server and DB2 must communicate correctly for the LDAP server to be useful. If you are not
responsible for DB2 at your installation or if you do not have DBA authority, then the easiest
way to handle the ldap.db2.profile is to set the following parameters and run the rest with the
defaults:
 TDBM_DB2_LOCATION, which is the DDF location name. Run with the default of LOC1.
 TDBM_DB2_USERID, which is the HLQ of your DB2 tables. Set this the same as your
LDAP server RACF user ID.
 TDBM_DB2_DBNAME, which is the name of your DB2 database. Set this to the
appropriate value for your installation or something that is meaningful, such as PKILDAP.

In our case, the ldap.db2.profile looked similar to Example 3-15.

Example 3-15 The ldap.db2.profile

TDBM_DB2_LOCATION='DB2H'
TDBM_DB2_USERID='LDAPSRV'
TDBM_DB2_DBNAME='LDAPPKI'

Then, run the ldapcnf utility using the command from your work directory to create several
members in the output data set that you specified in the ldap.profile file:
/usr/lpp/ldap/sbin/ldapcnf -i ldap.profile

DB2 (TDBM) for LDAP setup

To build the DB2 environment, first you must have DBA authority. If you do not have the
authority to create and maintain databases, then hand over the DBCLI, DBSPUFI, and
DSNAOINI members to your DBA to create the appropriate databases. In return, you need:
 The data set with the DSNAOINI file
 The DB2 data source or location name
 The user ID that own or created the DB2 tables
 The database name
 The DB2 subsystem ID

The only authority that is required within the DB2 environment is that the LDAP server’s
RACF user ID must have DBADM authority to the newly created database, EXECUTE
authority on the CLI plan, and SELECT authority on SYSIBM.SYSCOLUMNS.

If you are the DBA for your installation, then review the DBSPUFI member of the output data
set. Ensure that the buffer pool and storegroup are set the way that you want them. Also,
review the sizes of the table spaces for your environment.

Chapter 3. Digital certificates and PKI 171

 The defaults are pretty good for a medium-size PKI environment if you are not sharing the
LDAP server with any other applications. Then run the DBSPUFI member using the SPUFI
application. This should get a zero return code on the COMMIT. If you have not run a CLI
plan, then run the DBCLI plan and ensure that the LDAP server’s RACF user ID has
EXECUTE authority to the plan name.

Finally, check the DSNAOINI file. It is critical that the DB1 subsystem name, location name,
and CLI plan name are correct. Also indicate whether you are using CAF or RRSAF in DB2.

LDAP PROC and the configuration file

When the DB2 environment is complete, review the JCL in the LDAP PROC. This is placed in
the output data set under the name you specified. Review this member to ensure that the JCL
is correct, and move it into the appropriate system proclib. As all of our system data sets are
in LINKLST but our DB2 data sets are not, a couple of changes were made to the default
PROC, and our final run-time LDAP PROC appeared as in Example 3-16.

Example 3-16 Our final run-time LDAP PROC

//LDAPCRL PROC REGSIZE=0M,
//*----------------------------------------------------------
// PARMS='',
// PCNFOUT='JJONES.LDAPOUT',
// OUTCLASS='H'
//*----------------------------------------------------------
//GO EXEC PGM=GLDSLAPD,REGION=&REGSIZE,TIME=1440,
// PARM=('/&PARMS >DD:SLAPDOUT 2>&1')
//*----------------------------------------------------------
//STEPLIB DD DSN=DB2H7.SDSNLOAD,DISP=SHR
//CONFIG DD DSN=&PCNFOUT.(SLAPDCNF),DISP=SHR
//ENVVAR DD DSN=&PCNFOUT.(SLAPDENV),DISP=SHR
//SLAPDOUT DD SYSOUT=&OUTCLASS
//SYSOUT DD SYSOUT=&OUTCLASS
//SYSUDUMP DD SYSOUT=&OUTCLASS
//CEEDUMP DD SYSOUT=&OUTCLASS

The other item to check here is the configuration and the environment variables files. The
environment variables file (envvars) are in the SLAPDENV member of the output data set.
There is nothing to change here at this time, but as you install OCSF and ICSF you might add
a LIBPATH parameter in this file. The other way to tell the LDAP server where these
executables are is using the PARM parameter within the PROC.

The LDAP configuration file is in the SLAPDCNF member of the output data set. The
important global parameters are:
 LISTEN, which defines the IP address and port of the LDAP server.
 ADMINDN, which defines the LDAP server’s administrator. On the initial installation of the
LDAP server, you also have to set up the adminPW parameter, which is the LDAP server’s
administrator’s password. This password is only needed for the administrator as defined
within the LDAP directory.

The important TDBM parameters are:

 SUFFIX, which is the beginning of this portion of the LDAP directory. There can be more
than one of these.
 SERVERNAME, which is the DB2 location.
 DBUSERID, which is the name of the creator of the DB2 tables.

172 ABCs of z/OS System Programming Volume 6

 DATABASENAME, which is the name of the DB2 database.
 DSNAOINI, which indicates where the CLI interface definition file is.

Our SLAPDCNF member appeared as in Example 3-17.

Example 3-17 SLAPDCNF member

maxConnections 200
listen ldap://wtsc63.itso.ibm.com:3389
adminDN cn=Admin
adminPW passon
# logfile //DD:LOGOUT
# ---------------------------------------
database tdbm GLDBTDBM
suffix "c=US"
dsnaoini JJONES.LDAPOUT(DSNAOINI)
servername DB2H
dbuserid JJONES
databasename LDAPPKI

Starting the LDAP server and loading the schema

With the RACF, TCP/IP, PROC, and DB2 features set up for LDAP, the server is now ready to
be started. Go into SDSF and issue the following command (assuming that ldapcrl is the
LDAP member within your proclib):
/s ldapcrl

As you watch the LDAP server come up, you should see the following message in either the
SYSLOG or the JES messages for the PROC:
GLD0122I Slapd is ready for requests.

Ensure that there were now DB2 error messages in the JES messages within the PROC.
Then go into OMVS and change directories to your work directory. Now issue the following
command:
ldapsearch -h wtsc63.itso.ibm.com -p 3389 -V 3 -b ““ -s base -L
“objectclass=*”

If your LDAP server is set up and communicating correctly, then the output looks similar to
that shown Example 3-18.

Example 3-18 Output from the LDAP server

dn:
supportedcontrol: 2.16.840.1.113730.3.4.2
supportedcontrol: 1.3.18.0.2.10.2
supportedcontrol: 1.3.18.0.2.10.10
supportedextension: 1.3.6.1.4.1.1466.20037
namingcontexts: c=US
subschemasubentry: CN=SCHEMA,c=US
supportedsaslmechanisms: EXTERNAL
supportedsaslmechanisms: CRAM-MD5
supportedsaslmechanisms: DIGEST-MD5
supportedldapversion: 2
supportedldapversion: 3
ibmdirectoryversion: z/OS V1R4

Chapter 3. Digital certificates and PKI 173

 ibm-sasldigestrealmname: wtsc63oe.itso.ibm.com

At this point the schema must be loaded into the LDAP directory. First, copy schema.user.ldif
and schema.IBM.ldif from the /usr/lpp/ldap/etc directory into your working directory. You really
only need the schema.user.ldif file to support the PKI environment, but in case you ever want
to use this LDAP server for anything else that requires a more extensive schema, you could
include both files. Edit each one of these files, changing <suffix> at the front of these files to
match the suffix in your configuration file. In our case, we issued this command while we were
editing the files:
c ‘<suffix>’ ‘c=US’

The top non-comment line in both files should be ‘cn=schema, c=US’. Save the files, then
from your working directory, issue the following commands (where cn=admin and secret match
up with your configuration file and /u/jjones/ldapprod is your working directory):
ldapmodify -h wtsc63.itso.ibm.com -p 3389 -D cn=admin -w secret \
-f /u/jjones/ldapprod/schema.user.ldif
ldapmodify -h wtsc63.itso.ibm.com -p 3389 -D cn=admin -w secret \
-f /u/jjoones/ldapprod/schema.IBM.ldif

The output from these commands is only one line, indicating that the LDAP server is being
modified. Any other message means that there is some sort of problem and it should be fixed.
You can view the schema that you have just loaded by issuing the following command:
ldapsearch -h wtsc63.itso.ibm.com -p 3389 -s base -b “cn=schema,c=US” \
“objectclass=subschema”

Be prepared for several screens of output.

Defining the suffix and administrator

The final step in making the LDAP server ready for PKI Services is to define the suffix. (This is
the suffix that was indicated in the PKI template.) To define the suffix and the administrator
that we are using in our examples, issue the following command from your OMVS
environment (where /u/jjones/ldapprod is your working directory):
ldapadd -h wtsc63.itso.ibm.com -p 3389 -D cn=admin -w secret \
-f /u/jjones/ldapprod/suffix_admin.ldif

The LDIF data in the suffix_admin.ldif file is as shown in Example 3-19.

Example 3-19 The LDIF data in the suffix_admin.ldif file

dn: c=US
objectclass: top
objectclass: country
c: us
dn: cn=admin,c=US
objectclass: top
objectclass: person
objectclass: inetorgperson
objectclass: organizationalPerson
cn: admin
sn: admin
userPassword: secret

This defines the suffix and the LDAP administrator, with its password, in the LDAP directory.
When you issue the command to add this data to the LDAP server you will get messages,

174 ABCs of z/OS System Programming Volume 6

outside of the message that you are adding data, from the LDAP server if there are errors. To
list the data and verify that your data has been added correctly, issue this command from the
OMVS environment (where ‘\’ is the UNIX continuation symbol):
ldapsearch -h wtsc63.itso.ibm.com -p 3389 -D cn=admin -w secret -b c=US \
“objectclass=*”

This command produces output that looks similar to that shown in Example 3-20.

Example 3-20 Output from the ldapsearch -h command

c=US
objectclass=top
objectclass=country
c=US
cn=admin,c=US
objectclass=top
objectclass=inetorgperson
objectclass=person
objectclass=organizationalPerson
cn=admin
sn=admin
userpassword=secret

Now we are ready to make the LDAP server production-ready. First, in SDSF, stop the LDAP
server with the /p ldapcrl command. When the LDAP server is stopped, edit the SLAPDCNF
member of your output data set to remove the adminPW parameter, and adjust the adminDN to
add the suffix to the DN. Now your SLAPDCNF member should look similar to Example 3-21.

Example 3-21 The modified SLAPDCNF member

maxConnections 200
listen ldap://wtsc63.itso.ibm.com:3389
adminDN cn=Admin,c=US
# logfile //DD:LOGOUT
# ---------------------------------------
database tdbm GLDBTDBM
suffix "c=US"
dsnaoini JJONES.LDAPOUT(DSNAOINI)
servername DB2H
dbuserid JJONES
databasename LDAPPKI

After you restart the LDAP server, it has the basic requirements to work with PKI Services.

Chapter 3. Digital certificates and PKI 175

3.22 Setting up the PKI Services task

Figure 3-22 Setting up the PKI services task

Setting up the PKI Services task

PKI Services use VSAM data sets for object store (OST) and issued certification list (ICL).
The PKISTU started task is used to manage these data bases.

To create these data sets, use the IKYCVSAM sample job in SYS1.SAMPLIB.

We changed the default VSAM data set names to fit our site standards. For this test, we
decided to prefix the data sets with PKI, using WEBPKI2 as the second qualifier.

After these data sets are created, set up the PKISRV2 started task.

We recommend that you copy PKISRVD to a started task procedure name that fits your
environment. In our case, we copied it to PKISRV1, PKISRV2.

Edit the appropriate PKISRVD procedure to configure the data set names such as those
shown in Figure 3-22.

176 ABCs of z/OS System Programming Volume 6

3.23 Configure OCSF and OCEP to work with PKI Services

HTTP server for z/OS

SMP/E Install
Static Web
RA Pages
Admin H Post Apply
Browser T
Script/Job
T
P
D RACF Set up
exec
End User CGI Scripts
Browser PKI Exit
z/OS PKI Services
Daemon

RACF Glue Rtn Combined RA/CA

process

PC
SAF R_PKIServ
VSAM
RACF
Services OCSF Request
HW- LDAP Queue
CSP TP VSAM
OCEP CSP DL
DL
Issued
z/OS Cert List
RACF LDAP
DB Directory
SMF
SMF
Unload
Audit
Records

Figure 3-23 Configure OCSF and OCEP to work with PKI Services

In this section, we assume that you have set up OCSF. So, ensure that the files in /var/ocsf
exist.

To run PKI Services with OCSF, you must set up the PKI Services Trust Policy (PKITP)
plug-in for OCSF. The PKITP performs certificate validation.

There are two shell scripts in /usr/lpp/pkiserv/bin that perform the installation and verification
of the PKITP setup. To install PKITP:
1. Run the PKITP installation routine:
su
cd /usr/lpp/pkiserv/lib
/usr/lpp/pkiserv/bin/install_pkitp
2. It returns some questions:
addin directory?
/usr/lpp/pkiserv/lib
addin filename?
pkitp.so
action? “install|uninstall¨
install

Chapter 3. Digital certificates and PKI 177

 3. After this is complete, you can run the verification:
TRAUNER:/Z04RC1/usr/lpp/pkiserv/lib: >/usr/lpp/pkiserv/bin/pkitp_ivp
Starting pkitp IVP
Initializing CSSM
CSSM Initialized
Attaching pkitp
Attach successful, Detaching pkitp
Detach of pkitp successful
Completed pkitp IVP
TRAUNER:/Z04RC1/usr/lpp/pkiserv/lib: >

178 ABCs of z/OS System Programming Volume 6

3.24 Configure the PKI Services

Configure the PKI Services:

Set up the environment variables for PKI services
Customizing the PKI services configuration file
Customizing the PKI template

Figure 3-24 Configure the PKI Services

Copy some of the sample files that are provided with PKI Services from the installation
directory /usr/lpp/pkiserv/samples to the run-time directory. We set this directory to be the
same as the Web server Cryptographic Coprocessor /web/pki2.

Be careful because the samples directory contains some files that will overwrite your Web
server configuration files if you copied all files. Therefore, we suggest:
1. In the UNIX shell, ensure that you have superuser authority (or at least authority to
rename and move files).
2. Copy all of the necessary files to your Cryptographic Coprocessor:
cd /usr/lpp/pkiserv/samples
cp pkis*.* /web/server1
The httpd configuration files are unnecessary because the Web servers are already
configured.
You copy the forms files later when needed.

Now set up the directory that hosts your CA certificate.

Chapter 3. Digital certificates and PKI 179

 Set up the environment variables for PKI Services
Now, configure the PKI environment variables file.

Note: The PKI environment variables file is called pki.envars instead of httpd.envvars,
which is the environment variables file for the Web server.

Verify or change the _PKISERV_CONFIG_PATH and the OCSFREGDIR directory

information (Example 3-22).

The variable _PKISERV_MSG_LEVEL defines the debug level for PKI Services. We
recommend using debug level D for all components when you install PKI Services for the first
time. The default level for all components is W.

You might change these values while the PKI server is running by using a modify command to
the PKI server.

Example 3-22 Verify or change the path and directory

#-------------------------------------------------------------------#
# #
# PKI Services sample environment variable file #
# #
# Licensed Materials - Property of IBM #
# 5694-A01 #
# (C) Copyright IBM Corp. 2001, 2002 #
# Status = HKY7707 #
# #
#-------------------------------------------------------------------#
#
# 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
#
# Configuration File location and Message configuration Options
#
#_PKISERV_CONFIG_PATH=/etc/pkiserv
_PKISERV_CONFIG_PATH=/web/server1 <- Change to the actual runtime directory
_PKISERV_MSG_LOGGING=stdout_logging
#_PKISERV_MSG_LEVEL=*.w
_PKISERV_MSG_LEVEL=*.d
#
# Location of the OCSF Registry (/var/ocsf is the default location)
#
OCSFREGDIR=/var/ocsf

Customizing the PKI Services configuration file

In this section, we describe the configuration directives that must be customized in order to
get PKI Services up and running.

The first directives to look at in the pkiserv.conf file are the VSAM file names that were
prepared in “Setting up the PKI Services task” on page 176 for the OST and the ICL. The

180 ABCs of z/OS System Programming Volume 6

default for these data sets is PKISRVD.VSAM.OST and PKISRVD.VSAM.ICL, which we
changed to PKI.WEBPKI(n). If you changed these names, then you must change the
configuration directives accordingly. If you defined the DD names of the VSAM data sets in
the procedure, then we recommend that you refer to the DD names:
[ObjectStore]
# Data set name of the VSAM request (object store) base CLUSTER
# ObjectDSN='pkisrvd.vsam.ost'
ObjectDSN=DD:OST
# Data set name of the VSAM object store PATH for the transaction ID (TID)
alternate index
# ObjectTidDSN='pkisrvd.vsam.ost.path'
ObjectTidDSN=DD:TID
# Data set name of the VSAM issued certificate list (ICL) base CLUSTER
# ICLDSN='pkisrvd.vsam.icl'
ICLDSN=DD:ICL
# Data set name of the VSAM ICL PATH for the status alternate index
# ICLStatusDSN='pkisrvd.vsam.icl.status'
ICLStatusDSN=DD:ISTAT
# Data set name of the VSAM ICL PATH for the requestor alternate index
# ICLRequestorDSN='pkisrvd.vsam.icl.requestr'
ICLRequestorDSN=DD:IREQ

In the [SAF] section of pkiserv.conf, define the right key ring to be used. This certificate had
been added to the key ring by the RACF setup using the RACDCERT ADDRING(CARING)
ID(PKISTU) command. In our example, we used the label ITSOCASC63 for our CA certificate:
RACDCERT ADDRING(ITSOCASC63) ID(PKISTU)
Now this information must be defined in pkiserv.conf:
[SAF]
#KeyRing=PKISRVD/CAring
KeyRing=PKISTU/ITSOCASC63

In the [LDAP] section, define the LDAP server information such as server-domain-name, port
name, admin user ID, and password. Ensure that this is consistent with the LDAP definition in
“Customizing the second Web server for PKI” on page 166.
[LDAP]
NumServers=1
PostInterval=5m
# Server1=myldapserver.mycompany.com:389
Server1=wtsc63.itso.ibm.com:3389 <- domain name and port of LDAP
AuthName1=CN=admin <- Authentification name
AuthPwd1=secret <- Password
CreateOUValue= Created by 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

For a more secure environment, we recommend using the LDAPBIND class instead of having
user IDs and passwords floating around unencrypted. Another parameter you might change
in this section is the number of LDAP servers, NumServers=1. For availability reasons, you
should refer to at least two LDAP servers.

If you want to post the information to LDAP in a time frame other than every five minutes, then
change PostInterval=5m to another value, such as PostInterval=3m (3 minutes).

Chapter 3. Digital certificates and PKI 181

 You can also configure the [General] section, even if you do not use its function for now, as
follows:
[General]
InitialThreadCount=10
# full pathname or data set name containing the 'your certificate is ready'
# message form. Defaults to no message issued
# ReadyMessageForm=/etc/pkiserv/readymsg.form
ReadyMessageForm=/web/pki2/readymsg.form <- runtime
# full pathname or data set name containing the 'your certificate request
# has been rejected' message form. Defaults to no message issued
# RejectMessageForm=/etc/pkiserv/rejectmsg.form
RejectMessageForm=/web/pki2/rejectmsg.form
# full pathname or data set name containing the 'your certificate is about
# to expire' message form. Defaults to no message issued
# ExpiringMessageForm=/etc/pkiserv/expiringmsg.form
ExpiringMessageForm=/web/pki2/expiringmsg.form

Customizing the PKI template

The PKI template file is used by the various REXX CGI programs to obtain variables and to
set up the HTML output for the Web pages.

PKI Services can create certificates through different ways. One way is purely through RACF
and is called a SAF certificate. It is approved automatically after host user ID and password
verification. This is the historic way versus the PKI certificates that can be issued and
administered now using PKI Services.

To enable SAF certificates, customize the %%SignWith=SAF:CERTAUTH/taca%%

parameters in pkiserv.tmpl. Change the taca parameter RACF label of your CA certificate.
This parameter is found two times in <CONSTANT> sections, as follows:
<CONSTANT>
%%KeyUsage=handshake%%
%%NotAfter=365%%
#%%SignWith=SAF:CERTAUTH/taca%%
%%SignWith=SAF:CERTAUTH/ITSO CA SC63%%
</CONSTANT>
<CONSTANT>
%%KeyUsage=handshake%%
%%NotAfter=365%%
%%OrgUnit=SAF template certificate%%
#%%OrgUnit=Nuts and Bolts Division%%
%%OrgUnit=ITSO Poughkeepsie, NY%%
#%%Org=The Firm%%
%%Org=IBM%%
%%Country=US%%
#%%SignWith=SAF:CERTAUTH/taca%%
%%SignWith=SAF:CERTAUTH/ITSO CA SC63%%
%%CommonName=%%
</CONSTANT>

182 ABCs of z/OS System Programming Volume 6

This label points to the CA in RACF that is needed to sign the certificates. The example also
shows the following modifications that you need to make:
 Change the Org parameter from The Firm to the name of your company or organization.
 Change the OrgUnit parameter in the same way, unless your organizational unit’s name
really is Nuts and Bolts Division.
 Change the Country parameter to the country you are located, or add a Country
parameter if it does not exist

There is no country definition for PKI certificates in the sample template file. We recommend
that you one and using this country (C=US) as the tree entry point in LDAP.

Note: Be aware that changes in these fields change the content of your certificates. This is
also sensitive to LDAP.

Search pkiserv.tmpl for <CONSTANT>. There are several places to modify:

<CONSTANT>
%%KeyUsage=handshake%%
%%NotAfter=365%%
%%OrgUnit=SAF template certificate%%
#%%OrgUnit=Nuts and Bolts Division%%
%%OrgUnit=ITSO Poughkeepsie, NY%%
#%%Org=The Firm%%
%%Org=IBM%%
%%Country=US%%
#%%SignWith=SAF:CERTAUTH/taca%%
%%SignWith=SAF:CERTAUTH/ITSO CA SC63%%
%%CommonName=%%
</CONSTANT>
<CONSTANT>
%%NotBefore=0%%
%%NotAfter=365%%
%%KeyUsage=handshake%%
#%%OrgUnit=Class 1 Internet Certificate CA%%
%%OrgUnit=ITSO Poughkeepsie, Class 1 Internet Certificate CA%%
#%%Org=The Firm%%
%%Org=IBM%%
%%Country=US%%
%%SignWith=PKI:%%
</CONSTANT>

Other customizations in pkiserv.temp can be done to add fields or to change the look.

Chapter 3. Digital certificates and PKI 183

3.25 PKI exit

Provides advanced customization for:

Additional authorization checking
Validating
Changing parameters on calls to the R_PKIServ
callable service
Capturing certificates for further processing

Exit can be called from the PKI CGIs

Figure 3-25 PKI exit

PKI exit
The PKI exit provides advanced customization for additional authorization checking,
validating, and changing parameters on calls to the R_PKIServ callable service (IRRSPX00),
as well as capturing certificates for further processing.

You can call this exit from the PKIServ CGIs and use its IRRSPX00 user preprocessing and
post-processing functions, except the VERIFY function.

PKI exit main routine

The main routine of the program determines which subroutine to call, based on the
R_PKIServ function being called and whether this is a preprocessing or post-processing call.
The individual subroutines in the program handle the following scenarios:
 Scenario 1: Allow only selected users to request PKI browser certificates for
authenticating to z/OS.
 Scenario 2: Maintain a customized certificate repository (DB2 database or file)
independent of PKI Services.
 Scenario 3: Mandate a policy for certificate renewal only within 30 days of expiration.

You can write your own exit to further customize your PKI Services as you see fit. For
example, you may imbed SQL statements in your C code to do additional checking when
users request certificates. This checking can be based on comparison between user-supplied

184 ABCs of z/OS System Programming Volume 6

values for mother’s maiden name, birthplace, date of birth, or other criteria with values
pre-stored in a DB2 table.

Steps for installing and modifying the exit code sample

The C source code for the sample exit and a file containing the UNIX make command reside in
the system-supplied directory /usr/lpp/pkiserv/samples. The steps to install and modify the
exit sample after issuing the TSO OMVS command and becoming a superuser (you also can
use the ISHELL command) are:
1. Copy the sample exit (pkiexit.c) and makefile (Makefile.pkiexit) to your first Web server
directory:
cd /web/pki1/
cp /usr/lpp/pkiserv/samples/pkiexit.c pkiexit.c
cp /usr/lpp/pkiserv/samples/Makefile.pkiexit Makefile.pkiexit
2. Copy the source code to another file for later reference and modify the source code
according to your needs:
cp pkiexit.c pkiexit.original
oedit pkiexit.c
3. Compile and link to produce the executable module pkiexit by issuing the following
command:
make pkiexit
The resulting UNIX command creates two files:
– The executable module pkiexit
– The object module pkiexit
The command is as follows:
c89 -O -o pkiexit pkiexit.c
4. Set the permission bits for the module pkiexit:
chmod 755 pkiexit
5. Make the module program-controlled:
extattr +p pkiexit

Note: If you omit this step, the following messages display in the syslog when you
restart the PKI Services to use the exit:
BPXP015I HFS PROGRAM /web/pki1/pkiexit IS NOT MARKED PROGRAM CONTROLLED.
BPXP014I ENVIRONMENT MUST BE CONTROLLED FOR SERVER (BPX.SERVER) PROCESSING.

6. Edit both Web servers’ environment variables files by issuing the following commands:
oedit /web/pki1/htppd.envvars
oedit /web/pki1a/httpd.envvars
At the end of both files, add:
_PKISERV_EXIT=/web/pki1/pkiexit

Chapter 3. Digital certificates and PKI 185

 7. Edit the PKI Services environment variable file:
oedit pkiserv.envars
At the end of the file, add:
#
# Pki Exit
#
_PKISERV_EXIT=/web/pki1/pkiexit
Now check the permission bits and the extended attributes by issuing:
ls -E pkiexit
The output is:
-rwxr-xr-x -ps- 1 HAIMO SYS1 94208 May 19 16:15 pkiexit

186 ABCs of z/OS System Programming Volume 6

3.26 Test for scenario one

Same pull-down menu for

requesting a certificate of
a certain type (template)

New shortcut to pickup

certificate with return
template pull-down menu

Link for renew/revoke forces

SSL client authentication

Admin link is either user ID and password

protected or forces SSL client authentication

Figure 3-26 Test for scenario one

Test for scenario one

This scenario is for allowing only selected local z/OS users to request PKI browser
certificates for authenticating to z/OS. Such a scenario might be useful to allow selected user
IDs to authenticate themselves from the Internet to log on remotely to z/OS LPARs.

Additionally, this scenario provides a customized TITLE value for the subject’s distinguished
name based on the user’s role in the organization. Permission and the user’s role in the
organization are indicated by the user’s level of access to profiles PROJ.MEMBER and
PROJ.PARTNER in RACF class FACILITY. The access values are shown in Table 3-3.

Table 3-3 Access values for scenario one

Access values Description

NONE No access for either resource. The user is not permitted to request
this type of certificate. The certificate request is denied.

READ to PROJ.MEMBER The user is a team member and is permitted to request the
certificate. TITLE value is set to Team Member. Certificate requests
for team members are automatically approved. (No administrator
approval is required.)

Chapter 3. Digital certificates and PKI 187

 Access values Description

UPDATE to PROJ.MEMBER The user is the team’s leader and is permitted to request the
certificate. TITLE value is set to Team Leader. A certificate request
by the team leader is automatically approved. (No administrator
approval is required.)

READ to PROJ.PARTNER The user is considered to be a general partner of the team, not an
active team member. The user is allowed to request certificates, but
the requests require administrator approval before being issued.
TITLE value is set to Team Partner.

UPDATE to PROJ.PARTNER The user is considered to be a trusted partner of the team, not an
active team member. The user is allowed to request certificates, and
unlike requests of the general partner, the certificate requests are
approved automatically. TITLE value is set to Team Trusted Partner.

The preprocessing exit call for the GENCERT and REQCERT functions (subroutine
preProcessGenReqCertExit) handles the previously described logic as follows:
1. The request values are passed into the exit through argv in field-name=fieldvalue pairs,
and the subroutine looks for Template= and Userid= in the input parameters.
2. When the exit code finds a Template= value containing PKI Browser Certificate For
Authenticating To z/OS, the _check_resource_auth_np() system function (refer to 3.8.59
in z/OS C/C++ Run-Time Library Reference, SA22-7821) examines the user ID to
determine the user’s access to the preceding profiles as follows:
– If the user has no access to either of these resources, return code 8 is set, causing the
request to be denied.
– Otherwise, the user’s TITLE is set by imbedding the TITLE=title-value string into the
certificate.

By default, administrator approval is not required for the PKI browser certificate for
authenticating to z/OS. When the user has only READ access to PROJ.PARTNER, the
function must be changed to require administrator approval. This is done by setting return
code 4. For all other accesses, the function does not have to be changed.

In this example, we did not make any changes to the exit code. To test its functionality, we
created the profiles in class FACILITY:
RDEF FACILITY PROJ.MEMBER OWNER(PKIADM)
RDEF FACILITY PROJ.PARTNER OWNER(PKIADM)

We started testing with nobody on the access list of the profiles. Then, we permitted user ID
ANTOFF gradually with READ and UPDATE to each of the profiles.

188 ABCs of z/OS System Programming Volume 6

Because user ID has the value ANTOFF and is not on the access list of either profile, we
requested 1 Year PKI Browser Certificate for Authenticating, as shown in Figure 3-27.

This is the certificate

request page. The
options dialogs that
display on this page
depend on the certificate
template that is chosen.

After you click the submit

button, the data that the user
enters and the data that is
hardcoded for this certificate
template are sent to PKI
Services for processing.

Figure 3-27 Browser Certificate request

Chapter 3. Digital certificates and PKI 189

 After clicking Submit certificate request, then clicking OK on the authentication insert, the
message in Figure 3-28 displays.

The request is queued

to PKI Services
request database for
approval. The result is
the return of a
transaction ID.

Figure 3-28 Request submitted successfully

Finally, click Continue.

190 ABCs of z/OS System Programming Volume 6

3.27 Starting and stopping PKI Services

PROC to Start The PKI Services Daemon

Must be started through a started procedure
SYS1.PROCLIB member IKYSPROC (alias PKISERVD)
Modify as needed - e.g., customized envars file
Start from MVS console "S PKISERVD"
The LDAP server and the two webservers need to be started as well.
Stop from the MVS console "P PKISERVD"
Change logging options from the MVS console
F PKISERVD,LOG sub-comp.level[,sub-comp.level...]

Figure 3-29 Starting and stopping PKI Services

Starting and stopping PKI Services

You start the PKI Services daemon or daemons the first time that you configure PKI Services
or if you add sysplex support to run multiple independent instances of PKI Services (one per
image) on a sysplex. The MVS programmer performs these tasks.

Steps for starting the PKI Services daemon

You need to start the PKI Services daemon if:
 You are configuring PKI Services for the first time.
 You want to use parallel sysplex support and need to run another instance of the PKI
Services on a different image in the sysplex.
 You stopped PKI Services and need to restart it.

Before you begin:

 Your z/OS HTTP Server should be SSL-enabled and the uncustomized PKISERV
application ready for use.
 If you are starting PKI Services for the first time, you need to know the runtime directory,
called runtime-dir, in the command that follows. The default is /etc/pkiserv/. The MVS
programmer is asked to record any changes to the default.

Chapter 3. Digital certificates and PKI 191

 Perform the following steps to start the PKI Services daemon and view your Web pages:
1. If you have not done so already, start the Web server and the LDAP server.
2. If you want to test the configuration to this point before customizing PKI Services
(recommended), you need to temporarily prevent PKI Services from posting issued
certificates to LDAP because posting to LDAP will not be successful. Have the UNIX
programmer perform the following steps to prevent PKI Services from posting issued
certificates to LDAP:
a. Edit the PKI Services configuration file (by default, this is: /etc/pkiserv/pkiserv.conf).
b. Set NumServers=0 in the LDAP section of the file.
c. Exit to save your changes.

Note: After testing the configuration, you need to stop PKI Services, undo the change
in this step, and then restart PKI Services.

3. Start the PKI Services daemon from the MVS console by entering the following command:
S PKISERVD

Note: You must start the PKI Services daemon only from a started procedure. PKI
Services rejects all other methods of starting the daemon (including INETD, /etc/rc,
UNIX shell, or submitted JCL job).

4. Go to your Web pages by entering the following URL from your browser:
http://webserver-fully-qualified-domain-name/PKIServ/public-cgi/camain.rexx
The webserver-fully-qualified-domain-name is the common name (CN) portion of the
Web server’s distinguished name. You should be able to go through your Web pages to
request, retrieve, and revoke a certificate of type PKI browser certificate for
authenticating to z/OS. Ensure that you can do this before trying to customize the
application.
5. If you elected to test the configuration, you need to stop PKI Services (see “Steps for
stopping the PKI services daemon” next), undo the change in step 2, and then restart PKI
Services.

Steps for stopping the PKI services daemon

Perform the following steps to stop the PKI Services daemon:
1. To stop the PKI Services daemon, enter one of the following two commands.
You can use either the following MODIFY (or F) console command:
F PKISERVD,STOP
Alternatively, you can use the STOP (P) command:
P PKISERVD
2. If you changed the PKI Services configuration file, have the UNIX programmer undo that
change now by performing the following steps:
a. Edit the PKI Services configuration file (by default /etc/pkiserv/pkiserv.conf).
b. Set NumServers=n in the LDAP section of the file, where n is the same number of LDAP
servers.
c. Exit to save your changes.

192 ABCs of z/OS System Programming Volume 6

 4

Chapter 4. Kerberos
This chapter examines the z/OS implementation of Kerberos.

© Copyright IBM Corp. 2008. All rights reserved. 193

4.1 Introduction to Kerberos

A distributed authentication service developed by MIT

Currently at Version 5
Allows user authentication over a physically untrusted
network without transmitting password
Tickets are issued by a Kerberos authentication server:
both users and servers are required to have keys
registered with the authentication server
Flows to and from the authentication server establish a
session key, used in a direct exchange between a user
and service
Provides optionally data privacy

Figure 4-1 Introduction to Kerberos

Introduction to Kerberos
Kerberos is a network authentication protocol that was developed in the 1980s by
Massachusetts Institute of Technology (MIT), in cooperation with IBM and Digital Equipment
Corporation. Data Encryption Standard (DES) cryptography and Advanced Encryption
Standard (AES) are used to provide data privacy, especially for the sensitive data such as
password to log into a server.

In z/OS, this component’s formal name is Integrated Security Services Network

Authentication Service for z/OS; however, in this book, we refer to it as Network
Authentication Service for z/OS. The GSS-APIs supports the SPKM-3/LIPKEY mechanisms.

Kerberos is an encryption-based security system that provides mutual authentication

between the users and the servers in a network environment. The assumed goals for this
system are as follows:
 Authentication to prevent fraudulent requests/responses between users and servers that
must be confidential and on groups of at least one user and one service.
 Authorization can be implemented independently from the authentication by each service
that wants to provide its own authorization system. The authorization system can assume
that the authentication of a user/client is reliable.
 Message confidentiality can also be used that provides assurance to a data sender that
the message's content is protected from access by entities other than the context's named
peer.

194 ABCs of z/OS System Programming Volume 6

The Kerberos authentication is based heavily on shared secrets, which are passwords stored
on the Kerberos server. Those passwords are encrypted with a symmetrical cryptographic
algorithm, which is DES and AES in this case, and decrypted when needed. This fact implies
that a decrypted password is accessed by the Kerberos server, which is not usually required
in an authentication system that exploits public key cryptography. Therefore, the servers must
be placed in secure locations with physical security to prevent an attacker from stealing a
password.

For a complete description of the supported RFCs, see:

http://www.ietf.org/

The following RFCs are supported by the Kerberos functions:

RFC 1510 The Kerberos Network Authentication Service V5
RFC 3962 Advanced Encryption Standard (AES) Encryption for Kerberos
RFC 3961 Encryption and Checksum Specifications for Kerberos 5 - description
of DES3 encryption
RFC 4120 The Kerberos Network Authentication Service (V5) - description of key
usage numbers.

The following RFCs supported by the GSS:

 RFC 2078
 RFC 2744
 RFC 1964
 RFC 4121
 RFC 2025
 RFC 2253
 RFC 2459
 RFC 2847

Chapter 4. Kerberos 195

4.2 Kerberos terminology

New RACF profile classes

RACF REALM
KERBLINK
Kerberos
Registry New KERB segment in user profile
SAF

R_kerbinfo
(AS)
Authenticates
Authentication Users
R_ticketserv Server Grants TGTs

R_usermap Ticket
(TGS)
Granting Generates Session Keys
Server Grants service tickets based on TGT
SKRBKDC
kerberos
enabled ticket from client
application
Hardware
Cryptography

Figure 4-2 Kerberos terminology

Kerberos terminology
Kerberos terminology includes:
 Realm: The Kerberos domain, that is the set of entities which authenticate using that
Kerberos key distribution center (KDC).
 Principal: A client or an application server in a Kerberos domain.
 Instance: Additional distinction between principals names.
 Kerberos name: principal_name.instance@realm
 Kerberos ticket: The ticket is encrypted under a key only known to the Kerberos KDC and
the end server. The ticket includes:
– Client’s identity
– A dynamically created session key
– A time stamp
– A lifetime for the ticket
– A service name
A ticket can be reused during its lifetime.
 Authenticator: Client’s name and IP address as well as a time stamp. Issued with each
client’s request. The authenticator must be different for each request and is used for replay
protection.

196 ABCs of z/OS System Programming Volume 6

4.3 Kerberos protocol overview

Log Me In

Client Kerberos Key Distribution Center

I recognize you, here is an Kerberos Server
Authentication
login Ticket Authentication
Server
Authorize Me
to Server B

Ticket Granting
Client Server
Application Ticket to server B

Ticket to server B

Server A Server B Server C

Kerberos KDC Security Realm

Uses symmetric algorithm (DES), for authentication and data privacy

No password in clear on the network
A KDC keeps a copy of DES keys for all entities in the KDC Realm
Transitive trust can be established between realms
Used by several OS (for exampleAIX, OS/400, WIN2K, ...) for network users
authentication

Figure 4-3 Kerberos protocol overview

Kerberos protocol overview

The Kerberos system consists of three components:
 A client
 A server
 A trusted third party, which is also known as a Key Distribution Center (KDC)

KDC interacts with both a client and server to accept the client’s request, to authenticate its
identity, and to issue tickets to it.

The domain served by a single KDC is referred to as a realm. A principal identifier is used to
identify each client and server in a realm. The principal name is uniquely assigned for all
clients and servers by the Kerberos administrator. All principals must be known to the KDC.
Kerberos realms can interoperate by establishing trust relationships, sharing secret keys,
between them.

All entities in the network, clients and servers, have their own secret symmetric key. A copy of
all the keys is kept in the Kerberos Key Distribution Center. Clients’ keys are actually derived
from their password.

Kerberos is intended for corporate networks or intranets, because the scalability of the
protocol is directly related to the amount of secret keys that can be managed in a KDC.

Chapter 4. Kerberos 197

 Although the Kerberos protocol consists of several sub-protocols, three exchanges are
particularly interesting to most readers. The first phase exchange takes place between a
client and the authentication server. In this phase, a client asks the authentication server that
knows the secret keys of all clients in the realm to authenticate himself and give the client a
ticket (called a ticket-granting ticket) to be used to get a secret key which is then shared with
an application server the client wants to access.

Upon receiving the ticket-granting ticket, the client sends a request that contains the
ticket-granting ticket, for a service ticket to the ticket-granting server, and waits for a service
ticket to be returned. Having the session ticket (service ticket) ready, the client is allowed to
communicate with the server that is providing a service he wants to use. Optionally, the
application server can perform further authentication processing against the client.

Message encoding defined in Kerberos Version 5 is described using the Abstract Syntax
Notation 1 (ASN.1) syntax, in accordance with ISO standards 8824 and 8825.

In the remainder of this chapter, we discuss the interactions in more detail. We use the
following notations:
 Kx: X’s symmetric encryption key
 Kx,y: Encryption key shared by X and Y (for example, a session key)
 Kx{data}: A message that contains data encrypted with X’s key

198 ABCs of z/OS System Programming Volume 6

4.4 Get a ticket-granting ticket

Kerberos Server
Log Me In 2
Authentication
Server Kerberos The user's password does
Database not flow over the network!
Client Authentication
Ticket 3 Ticket Granting
Server
login Authorize Me
to target server

Ticket to server

Ticket to server
Application Application
Client Targer Server

User

1
1. Log in to application username,password
2. Request: Kuser{timestamp},"username","ticket_granting_server"
3. Response: Kuser{Ksession1},TGT
where TGT = KTGS{"username",Ksession1}

Kuser is derived from user's password, which is known from the Kerberos KDC
Ksession1 is created dynamically by Kerberos
KTGS is known only from the Kerberos Server

Figure 4-4 Get a ticket-granting ticket

Phase 1: Authentication service exchange

To simplify our explanation, we us an example with a user named Alice (username=Alice). So,
in Figure 4-4 the numbered steps become:
1. Alice enters a user name and password.
2. KAlice{timestamp}, "Alice", tgs, nonce
3. KAlice{KAlice,KDC, nonce}, TGT, where TGT = KAlice{"Alice",KAlice,KDC}

The authentication service exchange is initiated by a client when it wants to get authentication
credentials for an application server but currently holds no credentials. Two messages are
exchanged between the client and the Kerberos authentication server, then credentials for a
ticket-granting server are given to the client. These credentials are the so-called
ticket-granting ticket, which is used subsequently to obtain credentials for other services.

This exchange is used for other services, such as the password-changing service, as well.

Note: The client’s secret key is used exclusively in this phase.

When a user logs into a client system and enters his password, a client sends the Kerberos
authentication server a message that includes a user name in plain text (“Alice”), the current
time encrypted with her secret key, and the identity of the server for which the client is
requesting credentials.

Chapter 4. Kerberos 199

 Upon receiving the request from the client, the authentication server looks up the client name
and the service name (the ticket-granting service in this case) in the Kerberos database, and
obtains an encryption key for each of them, KAlice and KKDC.

The authentication server then generates a response back to the client, which contains the
ticket-granting ticket and a session key KAlice,KDC, which is used in the subsequent secure
communication between the client and KDC. The ticket-granting ticket includes the session
key KAlice,KDC, the identities of the server and the client, lifetime, and some other information.
The authentication server then encrypts the ticket using its own key KKDC. This produces a
sealed ticket. The session key KAlice,KDC is also encrypted using the client’s key KAlice with
some other information, such as nonce.

The encrypted current time is also known as the authenticator, because the receiver can
assure that the sender knows the correct shared secret KAlice, which is the client’s encryption
key derived from her password (this key is also referred to as Alice’s long-term key), by
decrypting it and validating what is inside. Because the authentication server knows Alice’s
secret key, it can evaluate the time decrypted from the received authenticator.

Tip: You might have noticed that the clocks on the client system and the KDC must be
reasonably synchronized with each other. You can use a network time service to
synchronize the clocks.

An authenticator is also used to help the server detect message replays.

Nonce is information used to identify a pair of the Kerberos request and response. You can use
a time stamp or a random number generated by a client.

Tgs is the server’s identification, which is the Kerberos ticket-granting server in this case.

Because KAlice is known exclusively by Alice and the KDC, no one but Alice can extract the
critical information from the response message, such as the session key KAlice,KDC used in
the next phase.

When the client receives the authentication server’s response, it decrypts it using its secret
key KAlice and checks to see if the nonce matches the specific request. If the nonce matches,
the client caches the session key KAlice,KDC for future communications with the ticket-granting
server.

200 ABCs of z/OS System Programming Volume 6

4.5 Request a service ticket

Kerberos Server

Log Me In
Authentication
Server Kerberos
Database
Client Authentication
Ticket
4 Ticket Granting
Server
login Authorize Me
to target server
5
Ticket to server

Client Ticket to server

Application
Application Targer Server

User

4. Request: Ksession1{timestamp},TGT,"target_server"
5. Response: Ksession1{Ksession2,"target_server"},ticket to server
where ticket to server = Kserver{"username",Ksession2}

Conversation is encrypted with Ksession1

TGS gets Ksession1 from TGT, that it can read
Client is getting Ksession2 value
Kserver is known only from target server and Kerberos KDC

Figure 4-5 Request a service ticket

Phase 2: Ticket-granting service exchange

Because in our example username=Alice and server=Bob, in Figure 4-5 the numbered steps
become:
4. KAlice{timestamp}, TGT, "Bob", nonce
5. KAlice,KDC{KAlice,Bob,"Bob",nonce}, tkt_to_Bob, where tkt_to_Bob =
KBob{"Alice",KAlice,Bob}

When the ticket-granting server receives the message from the client, it first deciphers the
sealed ticket using its encryption key KKDC. From the deciphered ticket, the ticket-granting
server obtains the session-key KAlice,KDC. It uses this session key to decipher the
authenticator.

The validity checks that performed by the ticket-granting server include verifying the following:
 The client name and its realm in the ticket match the same fields in the authenticator.
 The address from which this message originates is found in the address field in the ticket,
which specifies addresses from which the ticket can be used.
 The user-supplied checksum in the authenticator matches the contents of the request.
This procedure guarantees the integrity of the message.

Chapter 4. Kerberos 201

 Finally, it checks the current time in the authenticator to make certain the message is recent.
Again, this requires that all the clients and servers maintain their clocks within some
prescribed tolerance.

Important: By checking the time stamp in the nanoseconds scale, replay attacks can be
detected.

The ticket-granting server now looks up the server name from the message in the Kerberos
database, and obtains the encryption key KBob for the specified service.

The ticket-granting server forms a new random session key KAlice,Bob for the benefit of the
client (Alice) and the server (Bob), and then creates a new ticket tkt_to_Bob that includes:
 The session key KAlice,Bob
 Identities of the service and the client
 Lifetime

Note: The format of the ticket for a particular service is identical to one of the
ticket-granting tickets.

The ticket-granting server then assembles and sends a message to the client.

202 ABCs of z/OS System Programming Volume 6

4.6 Authenticate to target server

Kerberos Server

Log Me In Authentication
Server Kerberos
Database
Client Authentication
Ticket Ticket Granting
Server
login Authorize Me
to target server

Ticket to server

Client Ticket to server 6

Application
Application Targer Server

User 7

6. Request: Ksession2{timestamp},ticket to server

7. Response: Ksession2{timestamp+1}
(optional; only when client specifies mutual authentication)

Conversation is encrypted with Ksession2

Application server gets Ksession2 from ticket to server, that it can read
Client is authenticated to server

Figure 4-6 Authenticate to a target server

Phase 3: The client/server authentication exchange

Following our example, in Figure 4-6 the numbered steps become:
6. KAlice,Bob{timestamp}, tkt_to_Bob
7. KAlice,KDC{timestamp} (optional)

The client/server authentication exchange is performed by the client and the server to
authenticate each other. The client has been issued credentials for the server using the
authentication service or ticket-granting service exchange before the client/server exchange
is initiated.

After receiving the ticket-granting server exchange response from the ticket-granting server,
the client deciphers it using the ticket-granting server session key KAlice,KDC that is exclusively
known by the client and the ticket-granting server. From this message it extracts a new
session key KAlice,Bob that is shared with the server (Bob) and the client (Alice). The sealed
ticket included in the response from the ticket-granting server cannot be deciphered by the
client, because it is enciphered using the server/s secret key KBob.

Then the client builds an authenticator and seals it using the new session key KAlice,Bob.
Finally, it sends a message containing the sealed ticket and the authenticator to the server
(Bob) to request its service.

When the server (Bob) receives this message, it first deciphers the sealed ticket using its
encryption key KBob, which is kept in secret between Bob and the KDC. It then uses the new

Chapter 4. Kerberos 203

 session key KAlice,Bob contained in the ticket to validate the authenticator in the same way as
the ticket-granting server does in the ticket-granting server exchange.

After the server has authenticated a client, an option exists for the client to validate the server
(this procedure is called mutual authentication). This prevents an intruder from impersonating
the server.

If mutual authentication is required by the client, the server has to send a response message
back to the client. The message has to contain the same time stamp value as one in the
client’s request message. This message is enciphered using the session key KAlice,Bob that
was passed from the client to the server.

If the response is returned, the client decrypts it using the session key KAlice,Bob and verifies
that the time stamp value matches one in the authenticator that was sent by the client in the
preceding client/server exchange. If it matches, then the client is assured that the server is
genuine.

When the client/server exchange has completed successfully, an encryption key is shared by
the client and server and can be used for the on-going application protocol to provide data
confidentiality.

204 ABCs of z/OS System Programming Volume 6

4.7 Kerberos inter-realm trust relationship

z/OS Realm
z/OS
9-MVS userid
DB2
Server

7- Here is a service ticket for DB2 8-map ticket to MVS userid

RACF
Database
Authentication
/ KDC
Server

6- Here is a service ticket for DB2 Ticket Granting

Server

5- Here is an inter-realm TGT, I want to use DB2

inter-realm
keys
Win2K/DB2 Connect Client WIN2K Realm
Win2K Domain Controller/KDC
4- Here is an inter-realm TGT

Ticket Granting
Server
DB2
Client 3- I'd rather go to the OS/390 realm

KDC
2- I recognize you, here is a TGT Authentication
Server
login
1- This is me

Figure 4-7 Kerberos inter-realm trust relationship

Kerberos inter-realm trust relationship

The Kerberos protocol is designed to operate across organizational boundaries. Each
organization that wants to run a Kerberos server establishes its own realm. The name of the
realm in which a client is registered is part of the client’s name and can be used by the
application server to decide whether to honor a request.

By establishing inter-realm keys, the administrators of two realms can allow a client
authenticated in one realm to use its credentials in the other realm. The exchange of
inter-realm keys registers the ticket-granting service of each realm as a principal in the other
realm. A client is then able to obtain a ticket-granting ticket for the remote realm’s
ticket-granting service from its local ticket-granting service. Tickets issued to a service in the
remote realm indicate that the client was authenticated from another realm.

This method can be repeated to authenticate throughout an organization across multiple

realms. To build a valid authentication path to a distant realm, the local realm must share an
inter-realm key with the target realm or with an intermediate realm that communicates with
either the target realm or with another intermediate realm.

Realms are typically organized hierarchically. Each realm shares a key with its parent and a
different key with each child. If an inter-realm key is not directly shared by two realms, the
hierarchical organization allows an authentication path to be easily constructed. If a
hierarchical organization is not used, it might be necessary to consult some database to
construct an authentication path between realms.

Chapter 4. Kerberos 205

 Although realms are typically hierarchical, intermediate realms can be bypassed to achieve
cross-realm authentication through alternate authentication paths. It is important for the
end-service to know which realms were transited when deciding how much faith to place in
the authentication process. To facilitate this decision, a field in each ticket contains the names
of the realms that were involved in authenticating the client.

206 ABCs of z/OS System Programming Volume 6

4.8 Some assumptions to Kerberos

z/OS Key RACF

Distribution
Center Kerberos
Servers Registry
KDCs
Clients Unix System
Services
SKRBKDC

Authentication
Server
TCP/IP
Ticket
Granting
Server

Figure 4-8 Some assumptions to Kerberos

Some assumptions to Kerberos

The following assumptions apply to the Kerberos security environment:
 Denial-of-service (DoS) attacks are not addressed by Kerberos. There are places in these
protocols where an intruder can prevent an application from participating in the proper
authentication steps. Detection and solution of such attacks (some of which can appear to
be “usual” failure modes for the system) is usually best left to human administrators and
users.
 The secret key must be kept secret by each principal (each client and server). If an
attacker steals a principal’s key, it can then masquerade as that principal or impersonate
any server of the legitimate principal.
 Kerberos does not address password guessing attacks. If a poor password is chosen, an
attacker might be able to mount an offline dictionary attack by repeatedly attempting to
decrypt messages that are encrypted with a key derived from the user’s password.
 Kerberos assumes a loosely synchronized clock in the whole system. Workstations might
be required to have a synchronization tool such as the time server provided.
 Principal identifiers should not be reused on a short-term basis. Instead, access control
lists (ACLs) can be used to grant permissions to particular principals.

Chapter 4. Kerberos 207

4.9 Implementing Network Authentication Service

New RACF profile classes

RACF REALM
KERBLINK
Kerberos
Registry New KERB segment in user profile
SAF

R_kerbinfo
(AS)
Authenticates
Authentication Users
R_ticketserv Server Grants TGTs

R_usermap
Ticket
(TGS)
Granting Generates Session Keys
Server Grants service tickets based on
TGT
SKRBKDC
kerberos
enabled ticket from client
application
Hardware
Cryptography

Figure 4-9 Implementing Network Authentication Service

Implementing Network Authentication Service

The implementation of Network Authentication Service introduces a new UNIX daemon to
provide the KDC services (authentication server and ticket-granting server). RACF has been
enhanced to provide KDC registry functions to store principals and keys.

This section details the setup of this UNIX daemon and the required configuration files.

SKRBKDC daemon setup

The following steps describe the setup of the Network Authentication Service UNIX daemon
called SKRBKDC:
1. Copy the SKRBKDC started task procedure (JCL) from EUVF.SEUVSAM to
SYS1.PROCLIB or the procedure library you use in your installation for started tasks.
Example 4-1 shows an example of the SKRBKDC started task procedure.

Example 4-1 Example of the SKRBKDC started task procedure

/SKRBKDC PROC REGSIZE=256M,OUTCLASS=A,PARMS=’-kdc’
//*********************************************************************
//* *
//* Procedure for starting the Kerberos Security Server *
//* *
//*********************************************************************
//GO EXEC PGM=EUVFSKDC,REGION=&REGSIZE,TIME=1440,

208 ABCs of z/OS System Programming Volume 6

// PARM=('ENVAR("LANG=En_US.IBM-1047"),TERM(DUMP) / &PARMS
// 1>DD:STDOUT 2>DD:STDERR')
//STDOUT DD SYSOUT=&OUTCLASS,DCB=LRECL=250,FREE=END,SPIN=UNALLOC
//STDERR DD SYSOUT=&OUTCLASS,DCB=LRECL=250,FREE=END,SPIN=UNALLOC
//SYSOUT DD SYSOUT=&OUTCLASS,FREE=END,SPIN=UNALLOC
//CEEDUMP DD SYSOUT=&OUTCLASS,FREE=END,SPIN=UNALLOC

2. Define a group for the started task user ID, with an OMVS segment with a GID value:
ADDGROUP SKRBGRP OWNER(STCGROUP) SUPGROUP(STCGROUP) + DATA(‘GROUP FOR
KERBEROS SKRBKDC User ID’) OMVS(GID(20))
The owner that we specify in our examples is for our installation only. You might want
change this owner according to your installation standards.
To verify the group is indeed defined correctly, display the group with all the attributes as
follows:
LISTGRP SKRBGRP OMVS
3. Define a started task User ID with an OMVS segment with the following values:
– UID value: 0
– HOME (directory) value: /etc/skrb/home/kdc
– PROGRAM value: /bin/sh

Attention: Both the HOME and PROGRAM values are case sensitive. You need to
define them in lower case.

An example definition is as follows:

ADDUSER SKRBKDC OW(SKRBGRP) DEFLTGRP(SKRGRP) +
NAME(‘KERBEROS User ID’) OMVS(UID(0) HOME(‘/etc/skrb/home/kdc’) +
PROG(‘/bin/sh’))
Use the RACF LISTUSER command to check that the user ID is correctly defined:
LISTUSER SKRBKDC OMVS
4. Activate the APPL class if not already active:
SETROPTS CLASSACT(APPL) RACLIST(APPL)
5. Define the SKRBKDC application universal read:
RDEFINE APPL SKRBKDC UACC(READ)
6. Activate the PTKTDATA class if not already active:
SETROPTS CLASSACT(PTKTDATA) RACLIST(PTKTDATA)
7. Define Passticket data to the SKRBKDC application.
RDEFINE PTKTDATA SKRBKDC UACC(NONE) SSIGNON(KEYMAKED(3734343237343131))
Pastickets are used internally by the Kerberos security server when the user password is
changed.

Chapter 4. Kerberos 209

 8. Define a profile for the SKRBKDC SKRBWTR started tasks in the RACF STARTED class:
RDEFINE STARTED SKRBKDC.** OWNER(STCGROUP) + STDATA(USER(SKRBKDC)
GROUP(SKRBGRP))
RDEFINE STARTED SKBRWTR.** OWNER(STCGROUP) +
STDATA(USER(SKBRKDC) GROUP(SKBRGRP))
Check the new defined profile by listing it:
RLIST STARTED SKRBKDC.** STDATA
RLIST STARTED SKBRWTR.** STDATA

210 ABCs of z/OS System Programming Volume 6

4.10 Setting up the Kerberos environment variable files

z/OS Key RACF

Distribution
Center Kerberos The z/OS realm is:
Servers Registry
KRB390.IBM.COM
KDCs
The IP address is:
Clients UNIX System
Services wtsc57.krb390.ibm.com
SKRBKDC

Authentication
Server
TCP/IP
Ticket
Granting
/etc/skrb/krb5.conf
Server

libdefaults¨

default_realm =KRB390.IBM.COM

realms¨

/etc/skrb/home/kdc/skrbkdc.envar KRB390.IBM.COM = {
kdc = wtsc57.krb390.ibm.com:88
kpasswd_server = wtsc57.krb390.ibm.comc:464
SKDC_DATABASE=SAF
SKDC_PORT=88
SKDC_KPASSWD_PORT=464
KERBERW2K.MOPWIN.IBM.COM = {
SKDC_NETWORK_THREADS=15
kdc =kerbsrv.kerberwin2k.mopwin.ibm.com:88
SKDC_LOCAL_THREADS=15
kpasswd_server =
SKDC_LOGIN_AUDIT=FAILURE
kerbsrv.kerberwin2k.mopwin.ibm.com:464

Figure 4-10 Setting up the Kerberos environment variable files

Setting up the Kerberos environment variable files

You must customize the Kerberos environment variable files /etc/skrb/krb5.conf and
/etc/skrb/home/kdc/envar for your environment. Samples of these configuration files are
supplied in /usr/lpp/skrb/examples. Copy the samples to the locations indicated previously.

The krb5.conf file requires the following updates:

1. Update the default_realm parameter with your installation’s Kerberos realm for the z/OS
system. Our DNS name for our z/OS system is WTSC57.KRB390.IBM.COM and our
Kerberos realm is KRB390.IBM.COM
2. Update the realms parameter with your z/OS realms and any other so-called peer realms.
We updated the realms parameter with our z/OS realm KRB390.IBM.COM and added the
DNS name for the z/OS KDC and the z/OS kpassw_server.
3. Update the domain_realm parameter to reflect the z/OS Realm in lowercase and
uppercase.

Chapter 4. Kerberos 211

 Example 4-2 displays the configuration file, /etc/skrb/krb5.conf, and displays our changes to
the configuration file.

Example 4-2 Our changes to the /etc/skrb/krb5.conf file

“libdefaults¨
default_realm = KRB390.IBM.COM
kdc_req_checksum_type = rsa-md5
ap_req_checksum_type = rsa-md5
default_tgt_enctypes = des-cbc-crc,des-cbc-md5
default-tgs_enctypes = des-cbc-crc,des-cbc-nd5
kdc_default_options = 0x40000010
use_dns_lookup = 0
“realms¨
KRB390.IBM.COM = {
kdc = wtsc57.krb390.ibm.com:88
kpasswd_server = wtsc57.krb390.ibm.com:464
}
KRB2000.IBM.COM = {
kdc = pauldeg.krb2000.ibm.com:88
kpasswd_server = pauldeg.itso.ibm.com:464
}
“domain_realm¨
.krb2000.ibm.com = KRB2000.IBM.COM
.krb390.ibm.com = KRB390.IBM.COM

The next step is to configure the environment variable file /etc/skrb/home/kdc/envar with the
required changes for your environment.

The defaults in this file are usually fine, except perhaps the time zone and the required
logging that you want to perform for the Kerberos server (SKRBKDC).

Example 4-3 shows an example of the environment variable definitions for the Kerberos
server.

Example 4-3 Example of the environment variable definitions

General server options
SKDC_DATABASE=SAF
SKDC_PORT=88
SKDC_KPASSWD_PORT=464
SKDC_NETWORK_THREADS=15
SKDC_LOCAL_THREADS=15
SKDC_LOGIN_AUDIT=FAILURE

System configuration options

LANG=En_US.IBM-1047
TZ=EST5EDT
NLSPATH=/usr/lib/nls/msg/%L/%N:/usr/lib/nls/msg/En_US.IBM-1047/%N

Message/debug options
_EUV_SVC_MSG_LOGGING=STDOUT_LOGGING
_EUV_SVC_DBG_MSG_LOGGING=1
_EUV_SVC_DBG=KRB_KDC.8,KRB_KDB.8
_EUV_EXC_ABEND_DUMPS=0

This completes the setup for the Kerberos server, but before you start the Kerberos server,
some additional RACF definitions are required.

212 ABCs of z/OS System Programming Volume 6

4.11 Setting up HFS for Kerberos cache files

z/OS Key RACF

Distribution
Center Kerberos
Servers Registry
KDCs
Clients UNIX System
Services
SKRBKDC

Authentication
Server
TCP/IP
Ticket
Granting
Server

Figure 4-11 Setting up HFS for Kerberos cache files

Setting up HFS for Kerberos cache files

The Kerberos runtime stores network credentials in so-called cache files. These are stored in
an HFS directory called /var/skrb/creds. This directory structure does not exit by default and
requires setup. Also, these files need to be erased periodically. There are several ways to
erase the files:
 Use a temporary file system mounted at /var/skrb/creds. This results in all the credentials
cache files being deleted each time the system is restarted.
 Erase all of the files in /var/skrb/creds when the /etc/rc initialization script is run. This
results in all of the credentials cache files being deleted each time the system is restarted.
 Set up a cron job to run the kdestroy command with the -e option. This results in the
deletion of only expired credentials cache files. This is the preferred method for managing
the credentials cache files. The cron job should run with UID 0 so that it can delete the
cache files.

The /var/skrb/creds directory permission bits should be set to 777 using the chmod command:
chmod 777 /var/skrb/creds

Chapter 4. Kerberos 213

4.12 Kerberos integrated with RACF

RACF must be setup as a local RRSF node

Definition of RACF profiles
Definition of the local Kerberos realm& foreign realms
REALM class
Local Kerberos principals (users)
KERB segment in user profile
KERBLINK class profiles
Definition of foreign Kerberos principals with a local identity
KERBLINK class profiles

Figure 4-12 Kerberos integrated with RACF

Kerberos integrated with RACF

The Kerberos security server supports two registry database types: SAF (for example RACF)
and NDBM (Kerberos principals stored in a UNIX System Services database using HFS or
zFS. IBM recommends that you use the SAF registry unless it is necessary to share the
Kerberos registry with one or more KDC instances running on another operating system.

If SAF is selected then RACF provides the functions to customize and access data for use
with Kerberos. Then the z/OS Network Authentication Service server will maintain registry of
principal and global information, which is stored using RACF through User and General
Resource Profiles.

You can administer the Network Authentication Service server through the RACF panels and
commands and obtain this information through an SAF callable service. Kerberos application
servers can use SAF callable services to parse Kerberos tickets to obtain principal names,
and to map from principal to RACF user and vice versa.

Local Kerberos principals are defined as RACF users with a KERB segment. The information
about the local and foreign realms are defined in the RACF class REALM in specific profiles.
The profiles contain:
 Local realm information, the name, key, and ticket lifetime (MIN, MAX, and DEFAULT in
seconds).
 Foreign realm trust relationships. These are defined in pairs, which also include a key.
RACF maps foreign Kerberos principals using the KERBLINK class profiles.

214 ABCs of z/OS System Programming Volume 6

The Kerberos principal’s password and the RACF user password are integrated. The
Kerberos password is subject to RACF SETROPTS rules and installation-defined rules.

Principals must keep their secret keys secret. If an intruder steals a principal’s key, it can then
masquerade as that principal or impersonate any server to the legitimate principal.

RACF Remote Sharing Facility (RRSF) has to be defined in local mode in order to generate
the corresponding Kerberos secret key whenever the user changes their password. Kerberos
uses RRSF services to make sure this happens.

Some RRSF RACF functions require a previously established user ID association. A user ID
association is an association between two or more user IDs on the same or different RRSF
nodes. There are two type of user ID associations:
 A peer association allows either of the associated user IDs to direct commands to the
other and allows password synchronization.
 In a managed association, one of the user IDs is designated as the managing ID, and the
other is designated as the managed ID. The managed ID cannot direct commands to the
managing ID. There is no password synchronization in a managed association.

To use the password synchronization and command direction functions, you need to activate
and define profiles in to the RRSFDATA class.

Defining RRSF in local mode

To define RRSF in local mode:
1. Activate the RACF RRSFDATA class if it is not activated already. The RRFSDATA class
needs to be RACLISTed and activated for generic command processing:
SETROPTS CLASSACT(RRSFDATA)
SETROPTS GENERIC(RRSFDATA)
SETROPTS GENCMD(RRSFDATA)
SETROPTS RACLIST(RRSFDATA)
2. Define a new member IRROPT01 in SYS1.PARMLIB and include the TARGET command
as shown in Example 4-4 to configure the RRSF in local mode.

Example 4-4 Define a new member

TARGET -
NODE(SC57) -
DESCRIPTION('WS57TS SYSTEM') -
PREFIX(SYS1.RACF) -
OPERATIVE LOCAL -
WORKSPACE(VOLUME(PDGTS1))

3. Modify the RACF procedure in SYS1.PROCLIB to process the updated RACF parameter
library by adding PARM=’OPT=01’ to the EXEC statement. Add the RACFPARM ddname to
point to SYS1.PARMLIB to identify the library that contains the RRSF parameters.
Example 4-5 shows the RACF procedure in SYS1.PROCLIB.

Example 4-5 The RACF procedure in SYS1.PROCLIB

//RACF PROC
//RACF EXEC PGM=IRRSSM00,REGION=0M,PARM='OPT=01'
//RACFPARM DD DSN=SYS1.PARMLIB,DISP=SHR

Chapter 4. Kerberos 215

 4. For these changes to take effect, refresh the RACF subsystem by stopping and restarting
the RACF started task using the locally defined RACF subsystem prefix.
Issue the MVS START command, specifying RACF as the procedure name:
S RACF,SUB=MSTR
5. You can check the status of the RRSF environment using the TARGET LIST command,
using the locally defined RACF subsystem prefix:
#TARGET LIST
6. You can also check the RACF subsystem using the SET LIST command:
#SET LIST

RACF setup for Kerberos realms

To set up RACF for Kerberos realms:
1. Before you define the local REALM, activate (CLASSACT) and RACLIST the REALM
class:
SETROPTS CLASSACT(REALM)
SETROPTS RACLIST(REALM)
2. Activate, if not already active, and RACLIST the PTKTDATA class as follows:
SETROPTS CLASSACT(PTKTDATA)
SETROPTS GENERIC(PTKTDATA)
SETROPTS GENCMD(PTKTDATA)
SETROPTS RACLIST(PTKTDATA)

Important: No profile is needed in the PTKTDATA class. The Kerberos server

(SKRBKDC) generates a temporary passticket under the covers to change a principal’s
password when the kpasswd command is issued.

3. A user must have access to the SKRBKDC application in order to use the kpasswd
command to change their password. By using the RACF RDEFINE command, you can
define the SKRBKDC application to the RACF APPL class:
RDEFINE APPL SKRBKDC OWNER(SYS1) UACC(READ) +
DATA(‘KERBEROS APPLID’)

Tip: Alternately, you can set the Universal Access to NONE and explicitly authorize
individual groups or users to the SKRBKDC application.

4. Define your local realm to the REALM class, using the RACF RDEFINE command to
define the KERBDFLT profile reflecting the default REALM and policy:
RDEFINE REALM KERBDFLT KERB(KERBNAME(KRB390.IBM.COM) PASSWORD(password)
MINTKTFLE(15) DEFTKTFLE(36000) + MAXTKTLFE(86400)UACC=NONE

Attention: Our z/OS environment has a domain name of WTSC57.KRB390.IBM.COM

and a REALM name of KRB390.IBM.COM

Use the RACF RLIST command to display the KERBDFLT profile in the REALM class:
RLIST REALM KERBDFLT KERB

216 ABCs of z/OS System Programming Volume 6

5. Define any foreign REALMs to the RACF REALM class.
Your local Network Authentication and Privacy Service (Kerberos) server can trust
authentications completed by other servers, and can be trusted by other servers, by
participating in trust relationships.
To participate in trust relationships, you must define each server as a foreign realm. Then,
you can allow users who are authenticated in foreign realms (foreign principals) to access
protected resources on your local z/OS system by mapping one or more RACF user IDs to
foreign principal names. You do not need to provide foreign principals with the ability to log
on to your local z/OS system. You can simply provide mapping to one or more local user
IDs so they can gain access privileges for local resources that are under the control of an
z/OS application server, such as DB2.
In our example, we defined a Windows® 2000 Realm to the RACF REALM class, so that
we can use it later for testing the Kerberos integration between Windows 2000 and the
z/OS Network Authentication and Privacy Services using DB2.
The Windows 2000 domain is called pauldeg.krb2000.ibm.com and the REALM is called
KRB2000.IBM.COM. We defined the following profiles to set up the trust relationship
between the z/OS REALM and the Windows 2000 REALM:
RDEFINE REALM /.../KRB390.IBM.COM/krbtgt/KRB2000.IBM.COM + KERB(PASSWORD(xx)
RDEFINE REALM /.../KRB2000.IBM.COM/krbtgt/KRB390.IBM.COM + KERB(PASSWORD(xx)

Attention: You need the password that is defined here later when you define the same
trust relationship on the Windows 2000 domain. This password is not associated with
any user ID and is not constrained to any SETROPTS rules for passwords.

6. Define Kerberos port 88 for the KDC and port 464 for the password server to your TCP/IP
profile to reflect the use of these ports, as shown in Example 4-6.

Example 4-6 Define Kerberos post 88 for the KDC and port 464 for the password server
88 TCP OMVS SAF KERB88 ; Kerberos Server
464 TCP OMVS SAF KERB464 ; Kerberos Server

7. Depending on your installation, you might or might not have started with the protection of
TCP/IP ports using the RACF SERVAUTH class. Accordingly, you should authorize the
SKRBKDC Started Task Userid to port 88 and 464, using the following commands:
PERMIT EZB.PORTACCESS.SC57.ITCPIP.KERB88 CLASS(SERVUATH) + ID(SKRBKDC)
ACCESS(READ)
PERMIT EZB.PORTACCESS.SC57.ITCPIP.KERB464 CLASS(SERVUATH) + ID(SKRBKDC)
ACCESS(READ)
The SKRBKDC started task also requires access to the TCP/IP stack itself, using a new
profile in the RACF SERVAUTH class:
PERMIT EZB.STACKACCESS.SC57.ITCPIP CLASS(SERVAUTH) ID(SKRBKDC) +
ACCESS(READ)

Chapter 4. Kerberos 217

 8. You are now ready to start your Kerberos server SKRBKDC. You receive the informational
messages shown in Example 4-7.

Example 4-7 Start Kerberos server: Informational messages

S SKRBKDC
$HASP100 SKRBKDC ON STCINRDR
IEF695I START SKRBKDC WITH JOBNAME SKRBKDC IS ASSIGNED TO USER
SKRBKDC , GROUP SKRBGRP
$HASP373 SKRBKDC STARTED EUVF04001I Security server version 2.10, Service
level OW45102.
EUVF04002I Security runtime version 2.10, Service level OW45102.
EUVF04018I Security server initialization complete.

218 ABCs of z/OS System Programming Volume 6

4.13 Define Kerberos local principals

Define local principals

ALTUSER user1 KERB(KERBNAME(KerbUSER1)) PASSWORD(usrp) NOEXPIRED

user profile SUPUSER, to be used as the DB2 server userid

kerbname = DBPRINCIPAL
password= password3

The service ticket that we receive

will address the DB2 server with
principal name 'DBPRINCIPAL'

Figure 4-13 Kerberos principals: Local principals

Define Kerberos principals

This section describes how to define Kerberos principals. We distinguish between two types
of principals:
 A local principal is a Kerberos user defined to the local REALM.
 A foreign principal is a Kerberos user from another Kerberos REALM.

Local principals
You define local principals as RACF users using the ADDUSER and ALTUSER commands
with the new KERB option. This creates a KERB segment for the user. Each local principal
must have a RACF password. Therefore, do not use the NOPASSWORD option when
defining local principals. You can specify the following information for your local principals:
 KERBNAME: Local principal name.
 MAXTKTLFE: Maximum ticket lifetime for the local principal.

Important: Upper and lower case letters are accepted and maintained in the case in which
they are entered.

Chapter 4. Kerberos 219

 Example 4-8 shows an example of defining a Kerberos principal.

Example 4-8 Defining a Kerberos principal

ALTUSER GRAAFF KERB(KERBNAME('Paul de Graaff'))

Restriction: You can define the local principal name that you specify only once. If you try
to define it to two RACF user IDs, you receive the following error message:
IRR52165I The value for the KERB segment KERBNAME operand must be unique.
Command processing ends.

Generating keys for local principals

Each local principal must have a key registered with the local Network Authentication and
Privacy Service (Kerberos) server in order to be recognized as a local principal. The user’s
definition as a local principal is not complete until the key is generated. The key is generated
from the principal’s RACF user password at the time of the user’s password change. If you
want a key to be generated, be sure to use a password change facility that will not result in an
expired password that the user must change at next logon. For example, you can use the
NOEXPIRED keyword of the ALTUSER command.

A local principal’s key is revoked whenever the user’s RACF user ID is revoked or the RACF
password is considered expired. If the user’s key is revoked, the server will reject ticket
requests from this user.

You can change a user’s password so that a key can be generated using the ALTUSER
command with the NOEXPIRED option, for example:
ALTUSER GRAAFF PASSWORD(new1pw)NOEXPIRED

Important: Do not use the NOPASSWORD option on the ALTUSER command.

Attention: You must specify a password value so that a key can be generated. All
characters of the password are folded to uppercase.

Users can change their own passwords by completing their own definitions as local principals
by using any standard RACF password-change facility, such as:
 TSO PASSWORD command (without the ID option)
 TSO logon
 CICS signon

Important: The RACF address space must be started for the password change to
complete and the key to be generated.

Password change requests from applications that encrypt the password prior to calling
RACF do not result in usable keys.

Automatic local principal name mapping

For each local principal that you define on your system using the KERB keyword of the
ADDUSER and ALTUSER commands, RACF creates a mapping profile in the KERBLINK
class automatically. When you issue the ALTUSER command with the NOKERB keyword or
issue a DELUSER for a user with a KERB segment, RACF deletes the KERBLINK profile
automatically.

220 ABCs of z/OS System Programming Volume 6

The KERBLINK profile maps the local principal name to the user’s RACF user ID. The name
of the KERBLINK profile for a local principal is the principal name specified as the
KERBNAME value with the ADDUSER or ALTUSER command. We show the KERBLINK
profile for user ID graaff in Example 4-9 as it was defined in Example 4-8 on page 220.

Example 4-9 The KERBLINK profile for user ID graaff

sr mask(P) class(kerblink)
Paul¢de¢Graaff

You can see in the profile Paul¢de¢Graaff that blanks are indeed replaced by the ¢ character.
If you list the profile, you notice a little quirk in the RACF command processing where it does
not accept mixed-case profile names, as shown in Example 4-10.

Example 4-10 Example with mixed-case profile names

rl KERBLINK Paul¢de¢Graaff
ICH13003I PAUL¢DE¢GRAAFF NOT FOUND

If you do a RLIST *, you see the output shown in Example 4-11.

Example 4-11 Output of RLIST *

RLIST *
CLASS NAME
----- ----
KERBLINK Paul¢de¢Graaff
LEVEL OWNER UNIVERSAL ACCESS YOUR ACCESS WARNING
----- -------- ---------------- ----------- -------
00 GRAAFF NONE NONE NO
INSTALLATION DATA
-----------------
NONE
APPLICATION DATA
----------------
GRAAFF

Example 4-11 shows that the local principal, Paul de Graaff, maps back to RACF user ID
GRAAFF.

Considerations for local principal names

The name of the KERBLINK profile contains the local principal name that is mapped. Local
principal names can contain imbedded blanks and lower case characters.

Blanks are not permitted as a part of a RACF profile name. Therefore, when building the
KERBLINK profile name, as a result of specifying KERBNAME with the ADDUSER or
ALTUSER command, RACF command processing will replace each blank with the X'4A'
character (which often resolves to the ¢ symbol), as shown in the output from the RLIST
KERBLINK * command shown in Example 4-9 on page 221 and in the output from the RACF
data base unload utility (IRRDBU00).

Restriction: RACF command processing also prevents the X'4A' character from being
specified as part of the actual local principal name.

Chapter 4. Kerberos 221

4.14 Define Kerberos foreign principals

Define foreign principals

RDEFINE KERBLINK /.../foreign_realm/foreign_principal APPLDATA('racf_user')
maps single principal to a RACF user
RDEFINE KERBLINK /.../foreign_realm/ APPLDATA('racf_user')
Maps all principals for a single realm to a RACF userid

KERBLINK /.../KERBERW2K.MOPWIN.IBM.COM/LAMBDA APPLDATA('CLIENT1')

RACF will map the Windows DB2 user Kerberos principal name LAMBDA to
RACF userid CLIENT1

Figure 4-14 Kerberos principals: Foreign principals

Kerberos foreign principals

You map foreign principal names to RACF user IDs on your local z/OS system by defining
general resource profiles in the KERBLINK class. You can map each principal in a foreign
realm to its own user ID on your local z/OS system, or you can map all principals in a foreign
realm to the same user ID on your system.

RACF user IDs that map to foreign principals do not need KERB segments. These user IDs
are intended to be used only to provide local z/OS identities to associate with access
privileges for local resources that are under the control of an z/OS application server, such as
DB2.

Each mapping profile in the KERBLINK class is defined and modified using the RDEFINE and
RALTER commands. The name of the KERBLINK profile for a foreign principal contains the
principal name, fully qualified with the name of the foreign realm. The profile name uses the
following format:
.../foreign_realm /[foreign-principal_name ]

If you want to map a unique RACF user ID to each foreign principal, you must specify the
foreign realm name and the foreign principal name. If you want to map the same RACF user
ID to every foreign principal in the foreign realm, you need only specify the foreign realm
name. In each case, you specify the local user ID using the APPLDATA keyword of the
RDEFINE or RALTER command.

222 ABCs of z/OS System Programming Volume 6

Example of mapping foreign principal names
In the following example, the users PAUL and VAL have their foreign principal names mapped
with individual user IDs on the local z/OS system. All other foreign principals presenting
tickets from the KERB2000.IBM.COM REALM are mapped to the KRB2000 user ID on the
local z/OS system.
RDEFINE KERBLINK /.../KERB2000.IBM.COM/PAUL APPLDATA('GRAAFF')
RDEFINE KERBLINK /.../KERB2000.IBM.COM/VAL APPLDATA('VALERIA')
RDEFINE KERBLINK /.../KERB2000.IBM.COM/ APPLDATA('KERB2000')

Attention: All characters of the foreign realm name and the foreign principal name are
folded to uppercase.

Chapter 4. Kerberos 223

4.15 Kerberos user commands

kinit
klist
kdestroy
keytab
ksetup
kpasswd
kvno
kadmin
Figure 4-15 Kerberos user commands

Description of the Kerberos commands

The following commands are supplied:
 kinit: Obtains or renews a Kerberos ticket-granting ticket. The KCD options specified in
the Kerberos configuration file are used if no ticket options are specified on the kinit
command.
 klist: Displays the contents of a Kerberos credentials cache or key table.
 kdestroy: Destroys a Kerberos credentials cache file. To delete a credentials cache, the
user must be the owner of the file or must be a root (uid) user.
 keytab: Used to add or delete a key from a key table or to display the entries in a key table.
 kpasswd: Changes the password for a kerberos principal using the password change
service.
 kvno: Displays the current key version number for a principal.
 kadmin: Is used to manage entries in the kerberos database. It prompts you to enter one or
more subcommands.

224 ABCs of z/OS System Programming Volume 6

To use these commands, you must update your PATH statement in your .profile with the full
path name of the directory (/usr/lpp/skrb/bin) containing the Kerberos commands. It also
requires updates to the NLSPATH statement to reflect the Kerberos message catalog.
Example 4-12 displays the required changes to your .profile.

Example 4-12 Required changes to .profile

# ====================================================
# Start of Kerberos section
# ====================================================
echo "--> Start of Kerberos Additions"
export PATH=$PATH:/usr/lpp/skrb/bin
echo "PATH:" $PATH
#
export NLSPATH=$NLSPATH:/usr/lpp/skrb/lib/nls/msg/%L/%N
echo "NLSPATH:" $NLSPATH
#

Kerberos command examples

This sections that follow lists some examples of Kerberos commands.

The kinit command

The kinit command obtains or renews the Kerberos ticket-granting ticket. The KDC options
specified by kdc_default_options in the Kerberos configuration file are used if no ticket
options are specified on the kinit command. The kinit command includes several keywords,
but we show only the following examples here:
 kinit -s: Obtains a ticket-granting ticket using the current signed-on RACF user ID
 kinit: Obtains a ticket-granting ticket and the principal name is obtained from the
credentials cache (if present)
 kinit -k: Obtains a ticket-granting ticket using a key table to obtain the principal
information

kinit -s example
To obtain a ticket-granting ticket for a Kerberos principal, you can either use RACF services to
obtain the principal associated or use a so-called key table. The kinit -s command obtains a
ticket-granting ticket for the current signed-on RACF User ID, as shown in Example 4-13.

Example 4-13 Example of kinit -s to obtain ticket-granting ticket

GRAAFF @ SC57:/u/graaff/kerberos>kinit -s
EUVF06014E Unable to obtain initial credentials.
Status 0x96c73a2d - Service key is not available.

When we issue the kinit -s command for the current signed-on RACF user ID GRAAFF, we
receive an error that the service key is not available. When we define the local principal for
user ID GRAAFF, a key is not generated for the local principal. When we issue the LU
GRAAFF KERB command, no key is generated, as shown in Example 4-14.

Example 4-14 Issuing the LU GRAFF KERB command

LU GRAAFF KERB NORACF
USER=GRAAFF
KERB INFORMATION
----------------
KERBNAME= Paul de Graaff

Chapter 4. Kerberos 225

 Keys only get generated when a RACF password change occurs. So after we change the
password for the RACF user ID GRAAFF, we receive a key generated, as shown in
Example 4-15.

Example 4-15 Generated key for user ID GRAAFF

LU GRAAFF KERB NORACF
USER=GRAAFF
KERB INFORMATION
----------------
KERBNAME= Paul de Graaff
KEY VERSION= 001

We can now try again to get a ticket-granting ticket issued, using the kinit -s command, as
shown in Example 4-16.

Example 4-16 Using the kinit -s command to get a ticket-granting ticket

GRAAFF @ SC57:/u/graaff/kerberos>kinit -s
GRAAFF @ SC57:/u/graaff/kerberos>klist
Ticket cache: FILE:/var/skrb/creds/krbcred_a9b31900
Default principal: Paul de [email protected]
Server: krbtgt/[email protected]
Valid 2001/02/26-23:48:16 to 2001/02/27-09:48:16

kinit with no keywords example

Next, we tested the kinit command without specifying any keywords. The kinit command
obtains the principal name from the credentials cache. If no credential cache exists, the
command fails, as shown in Example 4-17.

Example 4-17 Failure of the kinit command without specifying keywords

GRAAFF @ SC57:/u/graaff>kinit
EUVF06010E Principal name must be specified.

Example 4-18 shows the interaction with the user when issuing the kinit command and a
credential cache does exits. You are prompted for a password associated with the local
principal. If you are using RACF instead of a key table for storage of local principals, then this
is your RACF password associated with your RACF User ID.

Example 4-18 Using the kinit command when a credential cache does exist
GRAAFF @ SC57:/u/graaff>kinit
EUVF06017R Enter password:
GRAAFF @ SC57:/u/graaff>

Important: You must enter the password here in uppercase letters. RACF only accepts
uppercase passwords.

226 ABCs of z/OS System Programming Volume 6

kinit -k example
We then tested the use of a key table with the kinit command rather then using RACF. For
this example, we assume a principal is defined called [email protected]. Example 4-19
shows using a key table with the kinit command, by using the -k keyword.

Example 4-19 Using the kinit -k command

GRAAFF @ SC57:/u/graaff>kinit -k [email protected]
GRAAFF @ SC57:/u/graaff>klist
Ticket cache: FILE:/var/skrb/creds/krbcred_b210de60
Default principal: [email protected]
Server: krbtgt/[email protected]
Valid 2001/06/08-13:39:50 to 2001/06/08-23:39:50
GRAAFF @ SC57:/u/graaff>

Note: You must enter the password in uppercase letters.

When using the -k keyword, you do not need to specify the name and location of the key table
if you want to use the default key table. The default key table name is obtained from the
default_keytab_name configuration file (krb5.conf) entry. The default name is
/etc/skrb/krb5.keytab.

Tip: You can also change the default key table name using the environment variable
KRB5_KTNAME.

The klist command

Using the klist command displays the contents of a Kerberos credentials cache or key table.
We show the following examples of using the klist command:
klist Lists the tickets in the credentials cache (the default).
klist -e Displays the encryption type for the session key and the ticket.
klist -f Displays the ticket flags.
klist -k Displays the entries in the keytable.
klist -k -K Displays the encryption key value for each key table entry.

klist example
When you issue the klist command without any keywords, it actually is as though you had
issued a klist -c command. Example 4-20 shows the output of a klist command after a
ticket-granting ticket is obtained.

Example 4-20 The klist command example

GRAAFF @ SC57:/u/graaff/kerberos>kinit -s
GRAAFF @ SC57:/u/graaff/kerberos>klist
Ticket cache: FILE:/var/skrb/creds/krbcred_a9b31900
Default principal: Paul de [email protected]
Server: krbtgt/[email protected]
Valid 2001/02/26-23:48:16 to 2001/02/27-09:48:16

Chapter 4. Kerberos 227

 klist -e example
The klist -e command displays the encryption type for the session key and the ticket, as
shown in Example 4-21.

Example 4-21 The klist -e command example

GRAAFF @ SC57:/u/graaff>klist -e
Ticket cache: FILE:/var/skrb/creds/krbcred_b210de60
Default principal: [email protected]
Server: krbtgt/[email protected]
Valid 2001/06/08-13:39:50 to 2001/06/08-23:39:50
Encryption type: DES_CBC_CRC

Important: The -e option is valid only when listing a credentials cache.

klist -f example
The klist -f command displays the ticket flags, as shown in Example 4-22.

Example 4-22 The klist -f command example

GRAAFF @ SC57:/u/graaff>klist -f
Ticket cache: FILE:/var/skrb/creds/krbcred_b210de60
Default principal: [email protected]
Server: krbtgt/[email protected]
Valid 2001/06/08-13:39:50 to 2001/06/08-23:39:50
Flags: FIA

In this example, the flags indicate:

F Forwardable ticket
I Initial ticket
A Preauthentication used

Important: The -f option is valid only when listing a credentials cache.

klist -k example
The klist -k command lists the entries in a key table, as shown in Example 4-23.

Example 4-23 The klist -k example

GRAAFF @ SC57:/u/graaff>klist -k
Key table: /etc/skrb/krb5.keytab
Principal: [email protected]
Key version: 1

klist -k -K example
The klist -k -K command lists the entries in a key table and displays the encryption key
value for each key table entry, as shown in Example 4-24.

Example 4-24 The klist -k -K example

GRAAFF @ SC57:/u/graaff>klist -k -K
Key table: /etc/skrb/krb5.keytab
Principal: [email protected]
Key version: 1
Key: f1bc4fa49e4975ad

228 ABCs of z/OS System Programming Volume 6

The kdestroy command
The kdestroy command deletes a Kerberos credentials cache file.

The -e option causes the kdestroy command to check all of the credentials cache files in the
default cache directory (/etc/skrb/var/creds). Any file that contains only expired tickets that
have expired for the time delta are deleted. The time delta is expressed as nwndnhnmns,
where:
n Represents a number
w Indicates weeks
d Is days
h Is hours
m Is minutes
s Indicates seconds

The components must be specified in this order, but any component can be omitted (for
example, 4h5m represents 4 hours and 5 minutes, and 1w2h represents 1 week and 2 hours). If
only a number is specified, the default is hours.

Important: To delete a credentials cache, the user must be the owner of the file or must be
a root user (uid 0).

Example 4-25 shows an example of the kdestroy command that deletes the credentials
cache of principal Paul de Graaff.

Example 4-25 Example of the kdestroy command

GRAAFF @ SC57:/u/graaff>kinit -s
GRAAFF @ SC57:/u/graaff>klist
Ticket cache: FILE:/var/skrb/creds/krbcred_b2118de0
Default principal: Paul de [email protected]
Server: krbtgt/[email protected]
Valid 2001/06/08-14:26:38 to 2001/06/09-00:26:38
GRAAFF @ SC57:/u/graaff>kdestroy
EUVF06034I Credentials cache FILE:/var/skrb/creds/krbcred_b2118de0
destroyed.

The keytab command

The keytab command manages a key table. A key table can be used to define either local or
foreign principals. Key tables are traditionally used in UNIX-based environment. Support for
key tables here provides compatibility with these environments.

To define the local principal graaff to the default key table, issue the keytab command, as
shown in Example 4-26.

Example 4-26 The keytab command example

GRAAFF @ SC57:/u/graaff>keytab add paul -p paul
GRAAFF @ SC57:/u/graaff>keytab list paul
Key table: /etc/skrb/krb5.keytab
Principal: [email protected]
Key version: 1
Entry timestamp: 2001/06/08-15:08:12

Chapter 4. Kerberos 229

 You can now obtain a ticket-granting ticket using the key table instead of RACF. Next, issue
the kinit command to obtain a ticket-granting ticket using the key table, as shown in
Example 4-27.

Example 4-27 Using the kinit command to obtain a ticket-granting ticket using the key table
GRAAFF @ SC57:/u/graaff>kinit -k paul
EUVF06014E Unable to obtain initial credentials.
Status 0x96c73a06 - Client principal is not found in security registry.

After you run this command, an error indicates that the client principal is not found in the
security registry. So, what really happened here? When you look at the trace of the kinit
command, the issue becomes clear, as shown in Example 4-28.

Example 4-28 Trace of the kinit command

....
kdb_racf_get_principal(): No RACF profile for paul
kdc_as_process_request(): AS_REQ: kdb_get_principal() failed for
[email protected]
kdc_as_process_request(): AS_REQ: KDC error 6 processing request from
[email protected] for krbtgt/[email protected]

As shown in the trace output, it states no RACF profile was found for paul. Local Kerberos
principals are always defined in RACF, and foreign principals in their respective REALM
(KDC). The messages here indicate that the Kerberos server tried to map the local principal
to a RACF user ID and could not find a local principal named paul.

The next step is to define a RACF user ID with a KERB segment and a KERBNAME of paul.
We change the RACF user ID GRAAFF to reflect the local Kerberos principal paul, as shown
in Example 4-29.

Example 4-29 Changing the RACF user ID to GRAAFF

alu graaff kerb(kerbname(graaff) password(xxx) noexpired

We try to execute the kinit -k command again, as shown in Example 4-30.

Example 4-30 Issuing the kinit -k command again

GRAAFF @ SC57:/u/graaff>kinit -k paul
EUVF06016E Password is not correct for [email protected].

The password that we use to add the principal must match the RACF password for the RACF
user ID to which it is mapped. So, we have to redefine the local principal in the key table using
the correct (RACF) password. To redefine the local principal, delete and add the principal as
shown in Example 4-31.

Example 4-31 Redefining the local principal

GRAAFF @ SC57:/u/graaff>keytab delete paul
GRAAFF @ SC57:/u/graaff>keytab add paul -p racfpw
GRAAFF @ SC57:/u/graaff>klist -k
Key table: /etc/skrb/krb5.keytab
Principal: [email protected]
Key version: 1

230 ABCs of z/OS System Programming Volume 6

We can now issue the kinit -k paul command again. Example 4-32 shows that we still
receive a password error because we added the principal with the correct password, but
using lowercase letters.

Example 4-32 Issuing kinit -k paul again

GRAAFF @ SC57:/u/graaff>kinit -k paul
EUVF06016E Password is not correct for [email protected].

Again we need to redefine the principal, as shown in Example 4-31 on page 230, but we now
add the (RACF) password in uppercase. We obtain a ticket-granting ticket successfully, as
shown in Example 4-33.

Example 4-33 Receiving a ticket-granting ticket successfully

GRAAFF @ SC57:/u/graaff>kinit -k paul
GRAAFF @ SC57:/u/graaff>klist
Ticket cache: FILE:/var/skrb/creds/krbcred_b2a52720
Default principal: [email protected]

Server: krbtgt/[email protected]
Valid 2001/06/15-14:22:42 to 2001/06/16-00:22:42

The kadmin command

The kadmin command is used to manage entries in the Kerberos database. It prompts you to
enter one or more subcommands. The kadmin command can be used with any Kerberos
administration server supporting Version 2 of the Kerberos administration protocol. The
command has the following format:
kadmin [-r realm ][-p principal ][-k keytab ][-w password ][-A ][-e ]

Where:
-r realm Specifies the Kerberos administration realm. If this option is not specified, the
realm is obtained from the principal name. This option is meaningful only if the
administration server supports multiple realms.
-p principal Specifies the administrator principal. If this option is not specified, the string
/admin is appended to the principal name obtained from the default credentials
cache. If there is no credentials cache, the string /admin is appended to the
name obtained from the USER environment variable, or if the USER
environment variable is not defined, it is appended to the name obtained from
the getpwuid() function. The local realm is used if an explicit realm is not part
of the principal name.
The principal name is host or host name unless the -p option is specified. The
host name is the primary host name for the local system.
-k keytab Specifies the key table that contains the password for the administrator
principal. The user is prompted to enter the password if neither the -k nor the -w
option is specified.
-w password Specifies the password for the administrator principal. The user is prompted to
enter the password if neither the -k nor the -w option is specified.
-A Specifies that the initial ticket used by the kadmin command does not contain a
list of client addresses. If this option is not specified, the ticket contains the local
host address list. When an initial ticket contains an address list, it can be used
only from one of the addresses in the address list.

Chapter 4. Kerberos 231

 -e Echoes each command line to stdout. This is useful when stdout is redirected
to a file.

Note: Subcommand options start with a minus (-) character and principal attributes start
with a plus (+) character or a minus (-) character.

The kadmin command imposes no other restrictions on the characters used in names or
passwords, although it is recommended that you do not use any of the EBCDIC variant
characters. The Kerberos administration server can impose additional restrictions.

Time units
You can use time units such as dates, that are displayed as day-of-week, month,
day-of-month, hour:minute:second, time zone, or year using the local time zone, as specified
by the TZ environment variable. Durations are displayed as days-hours:minutes:seconds.

The kadmin command supports a number of date and duration formats and some examples
are as follows:
"15 minutes" - "7 days" - "1 month" - "2 hours" - "400000 seconds" - "next
year" - "this Monday"

Subcommands
The following subcommand descriptions assume that the administration server is using the
standard MIT Kerberos database for the registry. Other database implementations might not
support all of the subcommand options and attributes.

Principal-related commands

Note: In the subcommands that we describe in this section, name specifies a Kerberos
principal

There is a long list of options that you can use in defining a principal, such as the types of
tickets that it can use, what services it can provide, what encryption types are supported
for this principal, and what pre-authentication steps might be required.

The following subcommands are supported:

 help [subcommand]
The help subcommand displays the command syntax for the specified subcommand. If no
subcommand name is specified, the available subcommands are displayed.
 list_principals [expression]
The list_principals (also known as listprincs) subcommand lists all of the principals in
the Kerberos database that match the specified search expression. If no search
expression is provided, all principals are listed. You must have LIST authority.
 get_principal name
The get_principal (also known as getprinc) subcommand displays information for a
single principal entry. You must have GET authority, or the principal entry must be your
own entry.
 add_principal [options][attributes] name
The add_principal (also known as addprinc) subcommand adds a new principal entry to
the Kerberos database. The options and attributes can be specified before or after the
principal name and can be entered in any order. You must have ADD authority.

232 ABCs of z/OS System Programming Volume 6

 delete_principal name
The delete_principal (also known as delprinc) subcommand deletes a principal entry
from the Kerberos database. You must have DELETE authority.
 modify_principal [options][attributes] name
The modify_principal (also known as modprinc) subcommand modifies an existing
principal entry in the Kerberos database. The options and attributes can be specified
before or after the principal name and can be entered in any order. You must have
MODIFY authority.
 change_password [-randkey | -pw password] name
The change_password (also known as cpw) subcommand changes the password for a
principal. You must have CHANGEPW authority, or the principal entry must be your own
entry.
 rename_principal oldname newname
The rename_principal (also known as renprinc) subcommand changes the name of a
principal entry in the Kerberos database. You must have both ADD and DELETE authority.

Policy-related commands

Note: Policy is associated with a password. It specifies characteristics such as the

password lifetime, length, number of character classes that must be present, and number
of passwords kept in the password history. Passwords in the password history cannot be
reused.

 list_policies [expression]
The list_policies (also known as listpols) subcommand lists all of the policies in the
Kerberos database that match the specified search expression. All policies are listed if no
search expression is provided. You must have LIST authority.
 get_policy name
The get_policy (also known as getpol) subcommand displays information for a single
policy entry. You must have GET authority or the policy must be associated with your own
principal entry.
 add_policy [options] name
The add_policy (also known as addpol) subcommand adds a new policy to the Kerberos
database. The options can be specified before or after the policy name and can be
specified in any order. You must have ADD authority.
 modify_policy [options] name
The modify_policy (also known as modpol) subcommand modifies an existing policy in the
Kerberos database. The options can be specified before or after the policy name and can
be specified in any order. You must have MODIFY authority.
 delete_policy name
The delete_policy (also known as delpol) subcommand deletes a policy entry from the
Kerberos database. You must have DELETE authority.
 add_key [[-keytab|-k] keytab_name] principal_name
The add_key (also known as ktadd) subcommand generates a set of random encryption
keys for the named principal and then adds the generated keys to the specified key table.
The default key table is used if the -keytab option is not specified. A key table name prefix
of FILE is changed to FILE because the add_key subcommand must update the key table.

Chapter 4. Kerberos 233

 The kpasswd command
The kpasswd command changes the password for a Kerberos principal using the password
change service. You must supply the current password for the principal as well as the new
password. The password change server applies any applicable password policy rules to the
new password before changing the password. The command is issued as follows:
kpasswd [principal]

The principal option specifies the principal whose password is to be changed. The principal is
obtained from the default credentials cache if the principal is not specified on the command
line.

Note: You cannot change the password for a ticket-granting service principal (krbtgt/realm)
using the kpasswd command.

The kvno command

The kvno command displays the current key version number for a principal and is issued as
follows:
kvno [principal]

The principal option specifies the principal whose current key version number is to be
displayed. The principal is obtained from the default credentials cache if the principal is not
specified on the command line.

234 ABCs of z/OS System Programming Volume 6

4.16 Auditing

KTICKET FAILURE 14:19:08 2001-06-15 /.../KRB390.IBM.COM/paul GRAAFF 24

..................................
KTICKET SUCCESS 14:22:42 2001-06-15 /.../KRB390.IBM.COM/paul GRAAFF

Figure 4-16 Auditing

Auditing
SMF Type 80 records are created for login requests (Kerberos initial ticket requests). Both
success and failure events can be logged as determined by the SKDC_LOGIN_AUDIT
environment variable. The event code is 68 and the record includes relocate sections 333
(Kerberos principal name), 334 (request source), and 335 (KDC error code).

The Kerberos principal is stored as a global name (/.../realm-name/principal-name) and not

as a Kerberos name (principal-name@realm-name). This is done to avoid code page
problems caused by the at-sign variant character. If the request is received through TCP/IP,
the request source is the network address (nnn.nnn.nnn.nnn:ppppp). If the request is
received through Program Call, the request source is the system user ID of the requester. The
KDC error code is a value between 0 and 127.

Figure 4-16 shows the smf records (truncated) generated for the kinit commands issued in
Example 4-32 on page 231 and Example 4-33 on page 231. The first record shown in
Figure 4-16 indicates an error code of 24, which means that the reauthentication (password)
failed.

Chapter 4. Kerberos 235

236 ABCs of z/OS System Programming Volume 6
 5

Chapter 5. Cryptographic Services

This chapter examines the Crytographic Services that are available on System z9® servers.

© Copyright IBM Corp. 2008. All rights reserved. 237

5.1 Introduction to cryptography

n t i a l
n f id e
C o

Figure 5-1 Introduction to cryptography

Introduction to cryptography
The word cryptography literally means secret writing. Throughout history, information has
been an asset that provides the owner a competitive advantage.

Failure to adequately protect information has had significant consequences for countries.
Today, If an enterprise does not exercise due care in protecting sensitive information about
others, it risks losing its competitive advantage and market share through industrial
espionage or losses due to law suits.

Confidentiality important. In addition, the integrity (the assurance of validity) of information is

critical to business success around the world. Commercial enterprises send contracts, private
documents, money orders, and other legal documents across communication networks, all of
which must arrive with the same content with which they were dispatched. Before the
electronic age, paper, signatures, and seals were used to guarantee the integrity of a
document. With electronic communication, another mechanism is required.

Cryptography is the only known practical method of protecting information that is transmitted
electronically through communication networks. It can also be an economical way to protect
stored information. As computing systems become increasingly exposed through increased
computer literacy and reliance on distributed computing, the pervasiveness of cryptography
will increase as industry seeks ways to protect their information assets.

238 ABCs of z/OS System Programming Volume 6

5.2 Cryptographic capabilities

C ryptographic capabilites:
D ata confidentiality
D ata integrity
A uthentication and
Identification
E lectronic signature

Figure 5-2 Cryptographic capabilities

Cryptographic capabilities
The use of cryptography provides many data-handling capabilities, such as data
confidentiality, data integrity, authentication, and electronic signatures.

Data confidentiality
Traditionally, cryptography is a data scrambling method used to conceal the information
content of a message. When a message is encrypted, the input plain text (unencrypted text)
is transformed by an algorithm into enciphered text that hides the meaning of the message.
This process involves a secret key that is used to encrypt and (later) decrypt the data. Without
this secret key, the encrypted data is meaningless. To conceal a message without using
cryptography, a secure physical communication line is required. With cryptography, only the
secret data encryption key has to be transmitted by a secure method. The encrypted text can
be sent using any public mechanism.

Data integrity
Although cryptography is best known for its ability to protect the confidentiality of data, it is
also used to protect the integrity of data. For example, a cryptographic checksum, such as a
message authentication code (MAC), can be calculated on arbitrary user-supplied text. The
text and MAC are then sent to the receiver. The receiver of the message can verify the MAC
appended to a message by recalculating the MAC for the message using the appropriate
secret key and verifying that it matches the received MAC exactly.

Chapter 5. Cryptographic Services 239

 Authentication and Identification
Another use of cryptography is in personal identification where the user knows a secret that
can serve to authenticate his or her identity. For example, the user of an automatic teller
machine (ATM) enters a magnetic stripe card to identify the account and the corresponding
correct PIN to authenticate the user. An unauthorized person acquiring the card and
attempting to use it is reduced to guessing the correct PIN. Because a PIN is typically four
digits and because a user typically gets only three attempts to enter the correct PIN, this is
very unlikely to happen.

Electronic signature
In normal business, a legal transaction is completed by a verifiable authorized signature (just
sign on the dotted line). An analogous process is required by new electronic applications,
such as Electronic Data Interchange (EDI). A digital signature is a means of achieving this by
using cryptographic mechanisms. It assures the recipient that the message is authentic and
that only the owner of the key could have produced the digital signature. A digital signature,
such as the Rivest-Shamir-Adleman (RSA) algorithm, is well-suited for message
non-repudiation. Non-repudiation is the ability of a party to sign a message, such that he or
she is unable to later deny having signed the message.

240 ABCs of z/OS System Programming Volume 6

5.3 Symmetric and asymmetric encryption algorithms

Benefits of asymmetric-key encryption compared to symmetric-key

encryption:
Using the public key, anyone can create an encrypted message
which only the holder of the private key can decrypt.
Using the private key, an encrypted message can be created which
could have been created only by the holder of the private key.
Disadvantage of asymmetric-key encryption compared to
symmetric-key encryption:
Much more computing power is required to encrypt and decrypt (as
compared to symmetric-key encryption techniques)

Figure 5-3 Symmetric and asymmetric encryption algorithms

Symmetric and asymmetric encryption algorithms

Today, two distinct classes of encryption algorithms are in use:
 Symmetric encryption algorithms
 Asymmetric encryption algorithms

Their fundamental difference is in how keys are used with these encryption methods.

We discuss these algorithms in the next sections (5.4, “Symmetric encryption algorithms” on
page 242 and 5.5, “Asymmetric encryption algorithms” on page 244).

Chapter 5. Cryptographic Services 241

5.4 Symmetric encryption algorithms

Encryption Decryption
message algorithm Internet algorithm message

Key

Figure 5-4 Symmetric encryption algorithms

Symmetric encryption algorithms

An encryption algorithm is called symmetric when the same key that is used to encrypt the
data is also used to decrypt the data and recover the plain text (see Figure 5-4). The cipher
and decipher processes are usually mathematically-complex non-linear permutations.

Most symmetric ciphers are block ciphers. They operate on a fixed number of characters at a
time, usually eight bytes. Some frequently-used algorithms are:
 Data Encryption Standard (DES): Developed in the 1970s by IBM scientists, DES uses
an 8-byte key; however, one bit in each byte is used as a parity bit; so, the key length is 56
bits. Stronger versions called Triple DES, which use three operations in sequence, have
been developed:
– 2-key Triple DES encrypts with key 1, decrypts with key 2, and encrypts again with key
1. The effective key length is 112 bits.
– 3-key Triple DES encrypts with key 1, decrypts with key 2, and encrypts again with key
3. The effective key length is 168 bits.
 Advanced Encryption Standard (AES): Sometimes known as Rijndael, AES is a block
cipher adopted as an encryption standard by the US government. It is considered the
successor to DES and TDES and is expected to be used worldwide. AES uses a larger
block size than DES and TDES do. While DES uses a block size of 8 bytes (64 bits), AES
uses a block size of 16 bytes (128 bits) along with the capability of using longer keys than
DES or TDES. This block size should be acceptable for messages of up to 256 exabytes of

242 ABCs of z/OS System Programming Volume 6

 data, and the bigger length of the keys delays for quite a few years the possibility of finding
the key value using brute force.
 Commercial Data Masking Facility (CDMF): A version of the DES algorithm that is used
for export from the U.S. and uses 56-bit keys; however, 16 bits of the key are known. So,
the effective key length is 40 bits.
 RC2: Developed by Ron Rivest for RSA Data Security, Inc., RC2 is a block cipher with
variable key length operating on 8-byte blocks. Key lengths of 40 bits, 64 bits, and 128 bits
are used.
 RC4: Developed by Ron Rivest for RSA Data Security, Inc., RC4 is a stream cipher with
variable key length. Stream ciphers operate on each byte, not on blocks of data. Key
lengths of 40 bits, 64 bits, and 128 bits are used.

Note: Both RC2 and RC4 are proprietary confidential algorithms that have never been
published. They have been examined by a selected number of scientists working under
non-disclosure agreements.

With these ciphers, it can be assumed that a brute-force attack is the only means of breaking
the cipher; therefore, the work factor depends on the length of the key. If the key length is n
bits, the work factor is proportional to 2**(n-1).

Chapter 5. Cryptographic Services 243

5.5 Asymmetric encryption algorithms

Encryption Decryption
message algorithm Internet algorithm message

Public Key Private Key

Figure 5-5 Asymmetric encryption algorithms

Asymmetric encryption algorithms

An encryption algorithm is called asymmetric when the key that is used to encrypt the data
cannot be used to decrypt the data. A different key is needed to recover the plain text (see
Figure 5-5). This key pair is called a public key and a private key. If the public key is used to
encrypt the data, the private key must be used to recover the plain text. If data is encrypted
with the private key, it can only be decrypted with the public key.

Asymmetric encryption algorithms, commonly called Public Key Cryptosystems (PKCS), are
based on mathematical algorithms. The basic idea is to find a mathematical problem that is
very hard to solve. Only one algorithm, RSA, is in widespread use today. However, some
companies have begun to implement public-key cryptosystems based on so-called elliptic
curve algorithms. The following list provides a brief overview of asymmetric algorithms:
 RSA: RAS was invented in 1977 by Rivest, Shamir, and Adleman (who formed RSA Data
Security, Inc.). The idea behind RSA is that integer factorization of very large numbers is
extremely hard to do. Key lengths of public and private keys are typically 512 bits, 1024
bits, or 2048 bits.
 Elliptic Curve: Public-key cryptosystems based on elliptic curves use a variation of the
mathematical problem to find discrete logarithms. It has been stated that an elliptic curve
cryptosystem implemented over a 160-bit field has roughly the same resistance to attack
as RSA with a 1024-bit key length.
Elliptic curve cryptosystems are said to have performance advantages over RSA in
decryption and signing.

244 ABCs of z/OS System Programming Volume 6

While the possible differences in performance between the asymmetric algorithms are
somewhere in the range of a factor of 10, the performance differential between symmetric and
asymmetric cryptosystems is far more dramatic. It takes about 1000 times longer to encrypt
the same data with RSA as it does with DES, and implementing both algorithms in hardware
does not change the odds in favor of RSA.

Chapter 5. Cryptographic Services 245

5.6 Use of cryptosystems: Data privacy

Cryptosystems for data privacy

Key management in a closed environment
Distributed computing environment (DCE)
Public key infrastructure

Figure 5-6 Uses of cryptosystems

Uses of cryptosystems
Cryptosystems, both symmetric and asymmetric, are used for data privacy, data integrity, and
digital signatures.

Cryptosystems for data privacy

Encrypting and decrypting large amounts of data with asymmetric cryptosystems is
expensive (in reference to time and resources). Therefore, symmetric algorithms, such as
AES, DES, RC2, or RC4, are used for bulk data encryption. The disadvantage of symmetric
algorithms, however, is that both partners (the party that encrypts the data and the party that
decrypts the data) must be in possession of the same key. Key management or safe
distribution of keys in insecure networks is a problem with symmetric cryptosystems, even
more so because data encryption keys need to be changed frequently in order to make an
adversary’s task more difficult and limit the potential damage if a key is compromised.

Different solutions exist in different environments, and we list a few of these solutions in the
following sections.

Key management in a closed environment

In high-security environments using cryptographic hardware that is installed and managed by
a centralized security facility, Master Keys and key-exchange keys can be installed centrally,
and the hardware facility can be delivered to the users with the necessary keys installed.

246 ABCs of z/OS System Programming Volume 6

If tamper-resistant hardware is used, this solution can fulfill the highest security requirements
and can also be made secure against insider attacks. The amount of administrative effort and
cost, however, would be prohibitive for many environments.

Distributed Computing Environment

Distributed Computing Environment (DCE) is designed to provide secure client-server
computing in insecure networks. It uses DES, a symmetric cryptosystem.

Users (principals) are authenticated by a central authentication server (the DCE Security
Server) using the Kerberos V.5 third-party authentication method. All client and server
principals must be defined in the registry (the authentication server’s database). Client users
have a password that they must remember, and servers have a key that is normally stored in
a keyfile on the server’s computer. The passwords and server keys are stored in the registry
as the principals’ Master Keys.

During authentication, the security server can send information to the client encrypted under
the client's Master Key (password). A client who wants to communicate with an application
server needs a ticket for this application server from the security server. A ticket is a collection
of information about the client, encrypted by the security server with the Master Key of the
application server. The client cannot read or modify the ticket, which can be compared to a
sealed envelope that the client can forward to the server as a method for identify but which
the user cannot open, read, or modify.

The security server creates a random session key that the client and the application server
can use to encrypt the data that they send to each other. This session key is included in the
ticket and is also sent to the client encrypted under the client’s Master Key.

The authentication and key management method used by DCE can create a highly-secure
client-server environment. If all security features provided by DCE are used, a network can be
made impenetrable even to sophisticated intruders. A hacker would need a computer that is
defined in the registry with a valid Master Key to even be able to attempt to log in and make a
guess at a principal's password.

The use of symmetric encryption causes the overhead for the security functions, although too
large to be neglected, to be tolerable.

The downside is that all clients need to be defined and administered in the registry. This is
adequate for client-server computing within an enterprise but does not scale well into a user
population made up of large numbers of suppliers and customers on the Internet.

Public key infrastructure

Public key cryptosystems can be used to transmit the DES, RC2, or RC4 keys used to
encrypt data to the recipient. Data that has been encrypted with the public key of the recipient
can only be decrypted using the recipient’s private key. If someone makes the public key
publicly known, everybody can send that person’s encrypted data by using the following
procedure:
1. Create a random DES, RC2, or RC4 key to encrypt the data.
2. Encrypt the data using this key.
3. Encrypt the key with the RSA PKCS using the recipient's public key.
4. Append the encrypted key before or after the encrypted data.
5. Send to recipient.

The recipient uses the private key to decrypt the DES, RC2, or RC4 key and uses this key to
decrypt the data and recover the plain text. This method works very well and has reasonable
performance because RSA is used to encrypt or decrypt only small amounts of data. The
length of symmetric keys is typically between 8 and 32 bytes.

Chapter 5. Cryptographic Services 247

 The problem with this method arises from the question: How can someone publish a public
key in a secure manner? If I send you my public key, pretending it is the public key of
someone else (for example, Jack Jones), and trick you into believing me, you will then send
encrypted data to the person who you believe is Jack Jones, and I can decrypt that data. This
situation is one where Digital Certificates and a public key infrastructure (PKI), a hierarchy of
authorities that issue certificates and attest to their authenticity, can help.

248 ABCs of z/OS System Programming Volume 6

5.7 Use of cryptosystems: Data integrity

Cryptosystems for data integrity

Message authentication codes
Message digest algorithms

Figure 5-7 Data integrity

Cryptosystems for data integrity

Data integrity is the ability to assert that the data that is received over a communication link is
identical to the that is data sent. Data integrity in an insecure network requires the use of
cryptographic algorithms, but it does not imply that only the receiver can read the data, as is
the case with data privacy. Data can be compromised not only by an attacker, but it can also
be damaged by transmission errors (although these are normally handled by the transmission
protocols).

Message authentication codes

Symmetric cryptographic algorithms, such as DES, can be used for data integrity. Using a
variation of the DES algorithm and a secret key, an 8-byte Message Authentication Code
(MAC) is created from the data. The MAC is sent with the message. The receiver performs
the same operation using the same key and compares the resulting MAC with the MAC that
was sent with the data. If both match, the integrity of the data is assured.

MACs rely on the same secret key that is used by both the sender (to create the MAC) and
the receiver (to verify the MAC). Since the MAC is derived from a secret key known only to the
sender and receiver the MAC can be sent in the clear. An adversary sitting between the
sender and the receiver (a so-called “person-in-the-middle” attack) can alter the message but
cannot forge the MAC because the key to create the MAC is unknown. The mathematical
principle behind using the MAC is that finding a message that fits a certain MAC is as difficult
as breaking DES encryption.

Chapter 5. Cryptographic Services 249

 A disadvantage to this method is that, as in symmetric cryptosystems, secret keys must be
shared by sender and receiver. Furthermore, because the receiver has the key that is used in
MAC creation, it is very difficult to make it impossible for the receiver to forge a message and
claim it was sent by the sender.

Message digest algorithms

Message digesting algorithms are a different approach to data integrity. These are algorithms
that digest (condense) a block of data into a shorter string (usually 128 or 160 bits) called a
Message Digest, Secure Hash, or Message Integrity Code (MIC).

The principles behind message digesting algorithms are:

 The message cannot be recovered from the message digest.
 It is very hard to construct a block of data that has the same message digest as another
given block.

Some common message-digesting algorithms are:

 MD2: This algorithm was developed by Ron Rivest of RSA Data Security, Inc. The
algorithm is used mostly for PEM certificates. MD2 is fully described in RFC 1319.
Because weaknesses have been discovered in MD2, its use is discouraged.
 MD5: This algorithm was developed in 1991 by Ron Rivest. The algorithm takes a
message of arbitrary length as input and produces as output a 128-bit message digest of
the input. The MD5 message digest algorithm is specified by RFC 1321, The MD5
Message-Digest Algorithm.
 SHA-1 SHA-1: This algorithm was developed by the U.S. Government. The algorithm
takes a message of arbitrary length as input and produces as output a 160-bit hash of the
input. SHA-1 is fully described in standard FIPS 180-1.
 SHA-2: SHA-256 is an improved algorithm and generates a 32-byte hash value. SHA-256
is considered to generate message digest values that are less likely to yield collisions.
 MDC-4: The MDC-4 algorithm calculation is a one-way cryptographic function that is used
to compute the hash pattern of a key part. MDC uses encryption only, and the default key
is 5252 5252 5252 5252 2525 2525 2525 2525. It is used by the TKE.

The sender of a message (block of data) uses an algorithm (for example SHA-1) to create a
message digest from the message. The message digest is sent together with the message.
The receiver runs the same algorithm over the message and compares the resulting
message digest to the one sent with the message. If both match, the message is unchanged.

The message digest cannot be sent in the clear. Because the algorithm is well known and no
key is involved, a person-in-the-middle can forge the message and can also replace the
message digest with that of the forged message, making it impossible for the receiver to
detect the forgery. Depending on the application and the key management used, either
symmetric cryptosystems or public-key cryptosystems can be used to encrypt the message
digest.

Because a message digest is a relatively small amount of data, it is especially well-suited for
public-key encryption.

250 ABCs of z/OS System Programming Volume 6

5.8 Use of cryptosystems: Digital signatures

Digital signatures

Figure 5-8 Digital signatures

Digital signatures
Digital signatures are an extension of data integrity. While data integrity only ensures that the
data received is identical to the that is data sent, digital signatures go a step further. They
provide non-repudiation, which means that the sender of a message (or the signer of a
document) cannot deny authorship (similar to signatures on paper).

The creator of a message or electronic document that is to be signed uses a message

digesting algorithm, such as MD5 or SHA-1, to create a message digest from the data. The
message digest and some information that identifies the sender are then encrypted with the
sender's private key. This encrypted information is sent together with the data.

The receiver uses the sender’s public key to decrypt the message digest and sender’s
identification. The receiver then uses the message digesting algorithm to compute the
message digest from the data. If this message digest is identical to the one recovered after
decrypting the digital signature, the message is authentic, and the signature is recognized as
valid.

With digital signatures, only public-key encryption can be used. If symmetric cryptosystems
are used to encrypt the signature, it is very difficult to make sure that the receiver (having the
key to decrypt the signature) could not misuse this key to forge a signature of the sender. The
private key of the sender is not known to anyone else. So, nobody can forge the sender’s
signature.

Chapter 5. Cryptographic Services 251

 The difference between encryption using public key cryptosystems and digital signatures
includes:
 With encryption, the sender uses the receiver’s public key to encrypt the data, and the
receiver decrypts the data with a private key. Thus, everybody can send encrypted data to
the receiver that only the receiver can decrypt.
 With digital signatures, the sender uses the private key to encrypt the signature, and the
receiver decrypts the signature with the sender’s public key. Thus, only the sender can
encrypt the signature, but anyone who receives the signature can decrypt and verify it.

The tricky thing with digital signatures is the trustworthy distribution of public keys.

252 ABCs of z/OS System Programming Volume 6

5.9 IBM Common Cryptographic Architecture

CCA and extended services

Managing DES Cryptographic Keys
Protecting Data
Verifying Data Integrity and Authenticating
Messages
Financial Services
Using Digital Signatures
Managing PKA Cryptographic Keys
Utilities
Trusted Key Entry Workstation Interfaces

Figure 5-9 IBM CCA

IBM Common Cryptographic Architecture

The IBM Common Cryptographic Architecture (CCA), defines a set of cryptographic
functions, external interfaces, and key management rules that pertain both to the DES-based
symmetric algorithms and the Public Key Algorithm (PKA) asymmetric algorithms. These
provide a consistent, end-to-end cryptographic architecture across different platforms that
conforms to American and International Standards.

Functions of the CCA define services for:

 Key management, which includes generation and exchange of keys securely across
networks and between application programs. The exchanged key is encrypted securely
using either DES or a PKA used in the context of symmetric key management.
 Data integrity, with the use of a Message Authentication Code (MAC), Modification
Detection Code (MDC), or digital signature.
 Data confidentiality, with the use of encryption and decryption capabilities accessible at all
levels of a network protocol stack.
 Personal authentication, with PIN generation, verification, and translation.

CCA was introduced in October 1989 with the IBM Transaction Security System and the IBM
Integrated Cryptographic Facility (IBM ICSF) with its supporting Integrated Cryptographic
Services Facility/MVS (ICSF/MVS).

Chapter 5. Cryptographic Services 253

 These products and their follow-ons conform to the IBM CCA Application Programming
Interface.

CCA key management functions

Key management is essential to successful cryptography. Because the algorithm is usually
public knowledge, the security of the data depends on the security of the key that is used to
encipher the data. Enciphered data can be obtained by an adversary, but without access to
the cryptographic key, the data remains secure.

Key management in the IBM CCA includes the following:

 Master Key concept: Each cryptographic system has a Master Key that is kept in the
clear inside the cryptographic facility, which is a highly secured physical repository. Each
operational DES key is encrypted under the appropriate Master Key variant (see 5.15,
“DES key management” on page 269), allowing an installation to protect many keys while
providing physical protection for only one key.
 PKA keys: The concept of Master Key is also applied to PKA keys that are encrypted
under the PKA Master Key.
 Key separation: Cryptographic keys should be used only for their intended function. For
DES keys, the IBM CCA enforces key separation through the use of control vectors (CV).
A control vector is a fixed pattern defined for each key type that the cryptographic facility
exclusively ORs with the Master Key to produce a Master Key variant that is used to
encrypt the key. Effectively, this produces a unique Master Key for each key type. The
Master Key variants protect keys operating on the system; these are called operational
keys.
The control vector concept also applies to the secure transportation of symmetric keys,
where the transported key is encrypted under a variant of the key-encrypting-key. For
example, when a key is stored with a file or sent to another system, the key is encrypted
under a key-encrypting key.

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

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.

Table 5-1 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.

254 ABCs of z/OS System Programming Volume 6

Table 5-1 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/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

Chapter 5. Cryptographic Services 255

5.10 IBM System z9: Cryptographic overview

TKE Workstation
System z9 (optional)

TSO Terminal
Hardware Crypto
Other systems
Clear/Encrypted Data

? ? ? ?
...
Master Key
CPACF RACF z/OS
Crypto instructions
ICSF
Crypto IBM Exploiters
Callable
Express 2 Encryption/Decryption Services
Key to use
APIs Home Grown
Applications

clear application key

in storage
or instructions
in the application
Applications' asymmetric OPTIONS ICSF run-time
CKDS PKDS keys encrypted under DATA
options
SET
.... the crypto PKA Master Key
Applications' DES
keys encrypted under
the crypto Master Key

Figure 5-10 IBM System z9: Cryptographic overview

IBM System z9: Cryptographic overview

Two types of cryptographic hardware features are available on System z9.
 CP Assist for Cryptographic Function (CPACF)
 Crypto Express 2 feature configurable as a Crypto Express 2 Coprocessor (CEX2C) or as
a Crypto Express 2 Accelerator (CEX2A).

These features are usable only when explicitly enabled through Feature Code 3863, except
for the CPACF SHA-1 and SHA-256 functions, which are always enabled.

To fully exploit the z9 Cryptographic features requires the Integrated Cryptographic Service
Facility (ICSF), which is the support program for the cryptographic features CPACF, CEX2C,
and CEX2A. ICSF is integrated into z/OS.

Additionally, the optional (TKE) Trusted Key Entry workstation feature is part of a customized
solution for using the Integrated Cryptographic Service Facility for z/OS program product to
manage cryptographic keys of a System z9 that has CEX2C features installed and intended
for the use of DES and PKA with secure cryptographic keys.

The TKE workstation provides secure control of the CEX2C features, including loading of
master keys.

256 ABCs of z/OS System Programming Volume 6

Figure 5-10 on page 256 describes the overall hardware and software layout of the hardware
cryptography in System z9 and z/OS, as follows:
 The exploiters of the cryptographic services call the ICSF API. Some functions are
performed by the ICSF software without invoking the cryptographic coprocessor; other
functions result in ICSF going into routines containing the cryptographic instructions. The
cryptographic instructions to drive CEX2C are IBM proprietary and are not disclosed; the
cryptographic instructions to interface with CPACF are published in z/Architecture
Principles of Operation, SA22-7832.
 These instructions are executed by a CPU engine and, if not addressing the CPACF
functions, result in a work request being generated for a cryptographic coprocessor.

The cryptographic coprocessor is provided with the following:

 Data to encrypt or decrypt from the system memory.
 The key used to encrypt or decrypt provided by ICSF as per the exploiter’s request.

Note: The encryption or decryption keys are themselves encrypted and, therefore,
unusable when residing outside of the cryptographic coprocessor.

Physically, these keys can be stored in ICSF-managed VSAM data sets and pointed to by
the application using the label they are stored under. The Cryptographic Key Data Set
(CKDS) is used to store the symmetric keys in their encrypted form, and the Public Key
Data Set (PKDS) is used to store the asymmetric keys. The application also has the
capability of providing an encrypted encryption key or a clear encryption key directly in
memory (that is, to use as is) to the coprocessor.
For high-speed access to symmetric cryptographic keys, the keys in the CKDS are
duplicated into an ICSF-owned data space.

Chapter 5. Cryptographic Services 257

5.11 CP Assist for Cryptographic Functions (CPACF)

CEC Cage Memory

STI PCIXCC
MBA
PCICA
CP CP CP ...
CEX2

CPACF CPACF CPACF ... I/O Cage

Figure 5-11 CPACF hardware implementation

CPACF hardware implementation

CP Assist for Cryptographic Functions (CPACF) was first introduced on the z990 and z890.
CPACF provides for hash functions and clear key encryption and decryption functions. Each
system Central Processor (CP) has an assist processor on the chip in support of
cryptography.

CPACF operates with a specific set of machine instructions, the Message-Security Assist
(MSA) instructions, which are problem state instructions and therefore available to all
applications. Alternatively, these functions can also be called through the Integrated
Cryptographic Service Facility (ICSF) component of z/OS by an ICSF-aware application.The
MSA instructions are described in z/Architecture Principles of Operation, SA22-7832.

The MSA instructions are all executed synchronously with respect to the CP instruction
stream, contrary to the operations executed on the Crypto Express 2 cards, which execute
asynchronously. The CPACF operations are therefore quite fast and can be used to support a
high volume of cryptographic requests. Because the CPACF instructions are available on
every PU within System z9, as they are for the zSeries® z990 or z890, and because the
CPACF operates with clear keys only, there is no notion of logical partition sharing or
cryptographic domains with CPACF.

The CPACF provides the MSA instruction set on every central processor (CP) of a z9 109, z9
BC, and z9 EC server.

258 ABCs of z/OS System Programming Volume 6

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 of these instructions can perform several functions. Therefore, 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, his program will get a program interruption with interruption code
6 (specification exception). In z/OS this is normally presented as an 0C6 abend.

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

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 encryption operations 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 5. Cryptographic Services 259

5.12 Crypto Express 2 feature

Battery
PCI-X PCIXCC
STI bridge card
1/.5 GB/s

Battery
each dir
STI
interface
1 GB/s
PCI-X
PCI-X (64-bit, 133MHz)
bridge

Battery
STI
1/.5 GB/s PCI-X PCIXCC
each dir card
bridge

Battery
STI = Self Timed Interface

Figure 5-12 Crypto Express 2 feature

Crypto Express 2 Feature

The Crypto Express 2 (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 as having either two
coprocessors, two accelerators, or one of each. Figure 5-12 shows the layout of a CEX2
feature.

The CEX2 in coprocessor mode (CEX2C) provides specialized hardware that performs DES,
TDES, SHA-1, RSA, PIN and key management 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 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 offloaded
from the CP to the CEX2A, potentially increasing system throughput. The CEX2 in
accelerator mode works in clear key mode only.

260 ABCs of z/OS System Programming Volume 6

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 System z9 server can support a
maximum of 16 cryptographic coprocessors or accelerators.

The connection of the CEX2 feature to the System z9 CPs through 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 to 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 that are
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 eight 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 only provide a
subset of the CEX2C functions at enhanced speed. This reconfiguration is a manual process
performed at the System z9 Support Element.

Note that:
 The reconfiguration is done at the coprocessor level, that is, a CEX2C feature can host a
CEX2C coprocessor and a CEX2A accelerator, or two CEX2C coprocessors or two
CEX2A accelerators.
 The reconfiguration is working both ways, that is, from CEX2C to CEX2A, and from
CEX2A to CEX2C. Master keys in the CEX2C domains can be optionally preserved when
reconfiguring from CEX2C to CEX2A.
 The reconfiguration process is disruptive to the involved coprocessor or accelerator
operations. The coprocessor or accelerator must be deactivated using ICSF on all LPARS
where it is being used before engaging the manual reconfiguration process.
 The FIPS 140-2 certification is not relevant to CEX2A because it is operating with clear
keys only.
 The function extension capability through UDX is not available to CEX2A.
 A System z9 can support up to eight Crypto Express2 features (depending on the other
features are installed), and each engine can be configured independently as either a
coprocessor or accelerator.

Each PCIXCC has an 8-character serial number and a 2-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.

Crypto Express 2 Coprocessor functions

The optional Crypto Express 2 Coprocessor (CEX2C) comes as a Peripheral Component
Interconnect Extended (PCI-X) pluggable feature that provides a high performance and
secure cryptographic environment. The CEX2C Cryptographic Coprocessor consolidates the
functions previously offered on the z900 by the Cryptographic Coprocessor feature (CCF), the
PCI Cryptographic Coprocessor (PCICC), and the PCI Cryptographic Accelerator (PCICA)
feature. These features are not available on System z9.

Chapter 5. Cryptographic Services 261

 The CEX2C feature performs the following functions:
 Data encryption or decryption algorithms
– Data Encryption Standard (DES)
– Double length-key DES
– Triple length- key DES
 DES key generation and distribution
 PIN generation, verification, and translation functions
 Pseudo Random Number (PRN) Generator
 Public Key Algorithm (PKA) Facility
These commands are intended for application programs using public key algorithms,
including:
– Importing RSA public-private key pairs in clear and encrypted forms
– Rivest-Shamir-Adelman (RSA)
• Key generation, up to 4096-bit
• Signature Verification, up to 4096-bit
• Import and export of DES keys under an RSA key, up to 4096-bit
– Public Key Encrypt (CSNDPKE)
Public Key Encrypt service is provided for assisting the SSL/TLS handshake, and when
used with the Mod_Raised_to Power (MRP) function it can be used to offload compute
intensive portions of the Diffie-Hellman protocol onto the CEX2C features of System
z9.
– Public Key Decrypt (CSNDPKD)
Public Key Decrypt supports a zero-pad option for clear RSA private keys. PKD is used
as an accelerator for raw RSA private operations such as required by the SSL/TLS
handshake and digital signature generation. The zero-pad option is exploited on
Linux® to allow use of the CEX2C features of System z9 for improved performance of
the SSL/TLS handshake and digital signature generation.
– Derived Unique Key Per Transaction (DUKPT)
This service is provided to write applications that implement the DUKPT algorithms as
defined by the ANSI X9.24 standard. DUKPT provides additional security for
point-of-sale transactions that are standard in the retail industry. DUKPT algorithms are
supported on the CEX2C feature for triple-DES with double-length keys.
– Europay Mastercard VISA (EMV) 2000 standard
Applications can be written to comply with the EMV 2000 standard for financial
transactions between heterogeneous hardware and software. Support for EMV 2000
applies only to the CEX2C feature of System z9.

Other key functions of CEX2C serve to enhance the security of public/private key encryption
processing include:
 Retained key support (RSA private keys generated and kept stored within the secure
hardware boundary)
 Support for 4753 Network Security Processor migration
 User-Defined Extensions (UDX)
User-Defined Extensions to the Common Cryptographic Architecture (CCA) support
custom algorithms that execute within the CEX2C Cryptographic Coprocessor. The UDX

262 ABCs of z/OS System Programming Volume 6

 customized algorithm is added as specific coprocessor code built by IBM or by an
approved third party. Building a UDX is an IBM service offering performed under contract.

Crypto Express 2 Accelerator functions

Actually, the only functions that remain available when reconfigured into a Crypto Express 2
Acceloerator (CEX2A) are the former PCICA functions. These functions are 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 Verify

The Encrypt and Decrypt RSA functions support key lengths of 512 to 4096-bit, in the
Modulus Exponent (ME) and Chinese Remainder Theorem (CRT) formats.

The maximum number of SSL transactions per second that can be supported on a System z9
by any combination of CPACF and CEX2A coprocessors is limited by the amount of cycles
available to perform the software portion of the SSL/TLS transactions. When both PCI-X
coprocessors on a Crypto Express2 feature are configured as accelerators, the Crypto
Express 2 feature is designed to perform up to 6000 SSL handshakes per second. This
represents, approximately, a 3X performance improvement compared to z990 when using
either a PCI Cryptographic Accelerator (PCICA) feature or the current CEX2C feature.

Note: These performance values indicate a throughput. That is, it is necessary to initiate
several threads of parallel requests to the CEX2A to achieve this performance.

Chapter 5. Cryptographic Services 263

5.13 PCIXCC hardware overview

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

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

PowerPC 405GPr Otello cryptographic

Rigoletto FPGA
microprocessor 1 7 processor 5

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

Figure 5-13 PCIXCC hardware overview

PCIXCC hardware overview

The PCIXCC hardware is implemented as an adapter card for a PCI-X bus. Figure 5-13
shows the components that are on the card. The numbers in the figure correspond to the
following 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. 64 MB of dynamic random-access memory (DRAM).
3. 16 MB of flash-erasable programmable read-only memory (flash EPROM) for storage of
persistent data.
4. 128 KB of static CMOS RAM backed up with battery power when the card is powered off.
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,
and the asymmetric-keys master key (ASYM-MK) protects RSA keys. Because master key
protection is essential to the security of the other keys, the master keys are stored within

264 ABCs of z/OS System Programming Volume 6

 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
– The public-key unit
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.
When a request is in the card, software in the PowerPC microprocessor determines
what 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.

Chapter 5. Cryptographic Services 265

 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, there are attacks that are driven by manipulating the power-supply voltages to the
card, and these conditions are also detected to prevent the attacks from succeeding.

266 ABCs of z/OS System Programming Volume 6

5.14 PCIXCC software overview

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 5-14 PCIXCC software overview

PCIXCC software overview

The software that runs on the PowerPC 405GPr microprocessor is divided into four separate
components as shown in Figure 5-14:
 Segment 0 contains power-on self-test (POST) 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 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. 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

Chapter 5. Cryptographic Services 267

 implements the IBM CCA cryptographic API, which provides the functions accessible to
application programs and administrative software running in 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 there are serious faults.

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.

268 ABCs of z/OS System Programming Volume 6

5.15 DES key management

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 5-15 DES key management

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
there is any attempted attack. 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 PCIXCC/CEX2C, the master key is called the
Symmetric-keys Master Key (SYM-MK). In a z/OS environment, the SYM-MK is 128 bits (16
bytes) long.

Cryptographic key separation

An important concept used in the CCA cryptographic API is cryptographic key separation.
This concept provides for the creator of a cryptographic key (for example, using the Key
Generate service) to declare the intended usage of the key through a key type specification.

Chapter 5. Cryptographic Services 269

 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 5-2 shows some of the key types supported by the CCA.

Table 5-2 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.

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.

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. The
bits in a control vector specify the possible uses of the key in great detail. For example, there
are bits which 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 5-15.

270 ABCs of z/OS System Programming Volume 6

5.16 DES encryption

Encryption request 1

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

Control vector
2 checking

DES 5
Master key
encryption

3
4
Master key variant: DES
DATA keys decryption

Unencrypted
DATA key
CEX2C secure boundary

Figure 5-16 DES encryption

DES encryption
In Figure 5-16, we formulate a request to encrypt some plaintext using a DATA key K that has
already been encrypted under the SYM-MK master key of the CEX2C (1). K has an
associated control vector C. C is examined to see if it has attributes that qualify it to be used
in the called service in the requested way (2). 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 (3). Next it uses the master key
variant to decrypt our DATA key K (4). Finally it performs the requested encryption using the
decrypted DATA key (5).

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.

Chapter 5. Cryptographic Services 271

5.17 DES key forms

Control vector Control vector

Key encrypted Key encrypted

under under
master key exporter key

figure left:Internal Key Token figure right: External Key

Token

Figure 5-17 DES key forms

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

272 ABCs of z/OS System Programming Volume 6

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 5-17 on page 272, 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.
 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 Data Set, a VSAM
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, which is found in most of the cryptographic API callable
services, allows the programmer to pass keys to the service either directly by value or
indirectly through 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 5-17 on page 272.

Chapter 5. Cryptographic Services 273

5.18 Key distribution: Key export

Alice's system

Internal Internal External

key token key token key token
DATA
control
vector
DATA EXPORTER
control control
vector vector

Key Export

CEX2C
Maste 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 5-18 Key export

Key distribution: Key export

The CCA uses the exportable and importable key forms to support electronic key distribution
with minimal manual key installation. Suppose Alice wants 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 can be done electronically. For example, Alice can 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 Ks that are 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 where Alice sends a DATA key to Bob.

Note: Because the key-export service is performed in the CEX2C, the clear value of the
key to be exported is not revealed. Also note that 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.

274 ABCs of z/OS System Programming Volume 6

5.19 Key distribution: Key import

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 5-19 Key import

Key distribution: Key import

Bob’s system considers the key to be in importable form. An application on Bob’s system can
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.

Chapter 5. Cryptographic Services 275

5.20 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 there is any attempted attack.

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 key 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. This
rule greatly strengthens non-repudiation. 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. Similar to all CCA
data stored in that memory, they are securely encrypted under a TDES key that is destroyed if
there is any attempt to tamper with the device.

Conceptually, the master key used to protect DES keys could have also been 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-keys 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.

276 ABCs of z/OS System Programming Volume 6

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 only discuss the former. As shown in Figure 5-20 an RSA private
internal key token contains several sections:
– R indicates that the section is required
– O indicates that the section is optional
In Figure 5-20 and succeeding figures:
– d represents the RSA private exponent
– e represents the public exponent
– n represents the modulus

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 5-20 RSA private key: Internal key token

Chapter 5. Cryptographic Services 277

 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 the PCICC, PCIXCC, or CEX2C. See Figure 5-21.

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 5-21 1024-bit modulus exponent form for CEX2C

 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 Data Set, a VSAM data set
often called the PKDS).

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 through
a key label.

278 ABCs of z/OS System Programming Volume 6

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 only discuss the former. As shown in Figure 5-22, an RSA private external key token
contains several sections. Again, R indicates that the section is required and 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 5-22 RSA private key: external key token

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 5-23.

SHA-1 hash value of the next sub-section.

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 5-23 Chinese Remainder Theorem form

You can use the PKA Key Import callable service to do either of the following tasks:
 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.

Chapter 5. Cryptographic Services 279

 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.

280 ABCs of z/OS System Programming Volume 6

5.21 ICSF

System z9 TSO terminal (with optional

TKE workstation)

Hardware Crypto

CEX2C z/OS
Symmetric-keys
Master Key RACF
Plaintext Appl
Asymmetric-keys ICSF
Master Key Ciphertext

Segment 3
Crypto instruction 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
the SYM-MK the ASYM-MK

Figure 5-24 ICSF

ICSF
In the z/OS environment, it is the Integrated Cryptographic Service Facility (ICSF) that
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.

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 Data Set (CKDS) and the Public Key
Data Set (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 5-24 is a schematic view of the hardware cryptography implementation in the System z
environment.

Chapter 5. Cryptographic Services 281

 Note: The hardware cryptography technology that we discuss here is 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.

In the Figure 5-24, an application program 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 will give control to its routines that contain
the crypto instructions. (The cryptographic instructions that drive the CPACF are listed in
5.11, “CP Assist for Cryptographic Functions (CPACF)” on page 258.) ICSF routes the
request to the CEX2C and if 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 Keys Master Key(SYM-MK) stored in the CEX2C. The request proceeds as shown
previously in Figure 5-16 on page 271.

The interactions between the functional blocks shown in Figure 5-24 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 that
are 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. ICSF
requires a PKDS as well. The PKDS doesn’t need to contain any records, or even be
initialized, but it does need to be allocated by ICSF.
 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 there is more than one secure coprocessor to which ICSF has access, 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 Cryptographic Key Data Set
(CKDS) is used to store the symmetric keys in their encrypted form, and the Public Key Data
Set (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.

282 ABCs of z/OS System Programming Volume 6

 6

Chapter 6. LDAP
This chapter examines the Lightweight Directory Access Protocol (LDAP) as implemented on
z/OS.

© Copyright IBM Corp. 2008. All rights reserved. 283

6.1 What is LDAP

LDAP is a global directory model

Originally developed as front-end of X.500 (DAP)
The LDAP protocol runs over TCP
Global directory model is based on entries
Each entry is referred to by DN (distinguished name)
Each entry is a collection of attributes
cn (common name), ou (organization unit), o (organization)
Each attribute has a type and values
Attributes are grouped into object classes

DN: cn=Ulrich Boche,ou=eServer Sales Support,o=ibm

Figure 6-1 What is LDAP

What is LDAP
Today people and businesses rely on networked computer systems to support distributed
applications. These distributed applications might interact with computers on the same local
area network, within a corporate intranet, within extranets linking up partners and suppliers,
or anywhere on the worldwide Internet. To improve functionality and ease-of-use, and to
enable cost-effective administration of distributed applications, information about the services,
resources, users, and other objects accessible from the applications needs to be organized in
a clear and consistent manner. Much of this information can be shared among many
applications, but it must also be protected in order to prevent unauthorized modification or the
disclosure of private information.

Information describing the various users, applications, files, printers, and other resources
accessible from a network is often collected into a special database that is sometimes called
a directory. As the number of different networks and applications has grown, the number of
specialized directories of information has also grown, resulting in islands of information that
are difficult to share and manage. If all of this information could be maintained and accessed
in a consistent and controlled manner, it would provide a focal point for integrating a
distributed environment into a consistent and seamless system.

The LDAP is an open industry standard that has evolved to meet these needs. LDAP defines
a standard method for accessing and updating information in a directory.

284 ABCs of z/OS System Programming Volume 6

6.2 What is a directory service

A concept: a data repository accessible from anywhere,

across machines, networks and geographies. Leveraged
by the global connectivity provided by the Internet
Involves:
A set of services
An information model
An access protocol
APIs
With properties such as simplicity of use, scalability,
access control,... No transaction semantics, favors
static data
Makes the life much easier for application
programmers, users, all kind of administrators,...
Figure 6-2 What is a directory service

Directory service
A directory is a listing of information about objects arranged in some order that gives details
about each object. Common examples are a city telephone directory and a library card
catalog. For a telephone directory, the objects listed are people—the names are arranged
alphabetically, and the details given about each person are address and telephone number.
Books in a library card catalog are ordered by author or by title, and information such as the
ISBN number of the book and other publication information is given.

In computer terms, a directory is a specialized database, also called a data repository, that
stores typed and ordered information about objects. A particular directory might list
information about printers (the objects) consisting of typed information such as location (a
formatted character string), speed in pages per minute (numeric), print streams supported
(for example PostScript® or ASCII), and so on.

Directories allow users or applications to find resources that have the characteristics needed
for a particular task. For example, a directory of users can be used to look up a person's
e-mail address or fax number. A directory can be searched to find a nearby PostScript color
printer, or a directory of application servers can be searched to find a server that can access
customer billing information.

The information in a directory is generally read much more often than it is written. As a
consequence, directories do not usually implement the complicated transaction or rollback
schemes that relational databases use for doing high-volume complex updates. Directory

Chapter 6. LDAP 285

 updates are typically simple all-or-nothing changes, if they are allowed at all. Directories are
tuned to give quick-response to high-volume lookup or search operations. They might have
the ability to replicate information widely to increase availability and reliability, while reducing
response time. When directory information is replicated, temporary inconsistencies between
the replicas are considered acceptable, as long as they get in sync eventually.

Remember:

Directory is a hierarchy of entries:

 Entries contain attributes.
 Attributes have one or more values.
 An entry’s attributes (not their values) are defined by the entry’s object class.
 Each entry has a name relative to its parent. This is a relative distinguished name
(RDN™).
 All RDNs from root to entry put together form of distinguished name (DN).

286 ABCs of z/OS System Programming Volume 6

6.3 LDAP directory structure

Root

c=US c=CA c=SP c=DE

Hierarchical structure
o=IBM
All entries have attributes
Object class determines entry level
Object class determines mandatory ou=TMCC
and optional attributes for an entry
Distinguished name
cn=userid entry
Relative Distinguished name
RDN attribute 1
Attributes are protected by Access attribute 2
Control Lists ACLs attribute 3
attribute 4

Figure 6-3 LDAP directory structure

LDAP directory structure

LDAP was originally developed as a front end to X.500, the OSI directory service. X.500
defines the Directory Access Protocol (DAP) for clients to use when contacting directory
servers. DAP has been characterized as a heavyweight protocol that runs over a full OSI
stack and requires a significant amount of computing resources to run. LDAP runs directly
over TCP and provides most of the functionality of DAP at a much lower cost. An LDAP server
is meant to remove much of the burden from the server side just as LDAP itself removed
much of the burden from clients.

What kind of information can be stored in the directory

The LDAP directory service model is based on entries. An entry is a collection of attributes
that has a name, called a distinguished name (DN). The DN is used to refer to the entry
unambiguously. Each of the entry’s attributes has a type and one or more values. The types
are typically mnemonic strings, such as cn for common name, or mail for e-mail address. The
values depend on what type of attribute it is. For example, a mail attribute might contain an
e-mail address with an attribute value of [email protected]. A jpegPhoto attribute would
contain a photograph in binary JPEG format.

Chapter 6. LDAP 287

6.4 How LDAP works

"root"
Directory
Namespace
c=US c=UK
oc = country
c = US

o=IBM o=Lotus o=Tivoli

oc = organization
o = IBM

cn=Tim
Hahn
oc =person
cn =Tim Hahn
mail = [email protected]
mail = [email protected] All entries have attributes (and values)
Object class (oc) is an attribute in all entries
RDN: cn=Tim Hahn
Attributes grouped into mandatory and
DN: cn=Tim Hahn, o=IBM, optional
c=US

Figure 6-4 How it works

How the information is arranged

In LDAP, directory entries are arranged in a hierarchical tree-like structure that sometimes
reflects political, geographic or organizational boundaries. Entries representing countries
appear at the top of the tree. Below them are entries representing states or national
organizations. Below them might be entries representing people, organizational units,
printers, documents, or just about anything else you can think of. Figure 10-4 shows an
example LDAP directory tree.

In addition, LDAP allows you to control which attributes are required and allowed in an entry
through the use of a special attribute called objectClass. The values of the objectClass
attribute determine the attributes that can be specified in the entry.

How the information is referenced

An entry is referenced by its distinguished name, which is constructed by taking the name of
the entry itself (called the relative distinguished name or RDN) and concatenating the names
of its ancestor entries. For example, the entry for Tim Hahn in Figure 6-4 has an RDN of
cn=Tim Hahn and a DN of cn=Tim Hahn,o=IBM,c=US. The full DN format is described in IETF
RFC 2253, LDAP (V3): UTF-8 String Representation of Distinguished Names.

The z/OS LDAP server supports different naming formats. While naming based on country,
organization, and organizational unit is one method, another method is to name entries based
on an organization’s registered DNS domain name.

288 ABCs of z/OS System Programming Volume 6

Names of this form look similar to this:
cn=Tim Hahn,dc=vnet,dc=ibm,dc=com

These naming formats can be mixed as well, for example cn=Tim

Hahn,ou=Sales,dc=ibm,dc=com.

How the information is accessed

LDAP defines operations for interrogating and updating the directory. Operations are provided
for adding or deleting an entry to/from the directory, changing an existing entry, and changing
the name of an entry. Most of the time, however, LDAP is used to search for information in the
directory. The LDAP search operation allows some portion of the directory to be searched for
entries that match some criteria specified by a search filter. Information can be requested
from each entry that matches the criteria. The LDAP compare operation allows a value to be
tested in an entry without returning that value to the client.

An example of search is, you might want to search the entire directory subtree below IBM for
people with the name Tim Hahn, retrieving the e-mail address of each entry found. LDAP lets
you do this easily. Or you might want to search the entries directly below the c=US entry for
organizations with the string Acme in their name and that have a FAX number. LDAP lets you
do this also.

The LDAP bind operation is used to indicate to the LDAP server who is going to be making
add/modify/search/compare or delete requests. The LDAP bind operation is an
authentication process. This authentication process can be used by distributed applications
which need to implement some form of authentication.

How the information is protected from unauthorized access

An Access Control List (ACL) provides a means to protect information stored in an LDAP
directory. ACLs are used to restrict access to different portions of the directory, specific
directory entries, or information within an entry. Access control can be specified for individual
users or groups.

Chapter 6. LDAP 289

6.5 LDAP functional model

BIND, with client Dn + userpassword

or digital certificate
or anonymous

request directory service

(search, modify, delete, add, ...)
DATA

UNBIND,
ABANDON

LDAP Protocol on TCP/IP LDAP

LDAP Client Server
(API) (slapd)
LDAP
"root"
Directory
c=US
oc=country c=FR
c=US

o=IBM o=Tivoli
oc=organization o=Lotus
o=Tivoli
o=IBM
Schema
oc=person
cn=Tim Hahn
[email protected]
[email protected]
In z/OS can be:
DB2 tables
RACF data base
IODF data

Figure 6-5 LDAP functional model

LDAP functional model

The DAP Server communication stack was too large to run on most system so the industry
standards removed some protocols that were not used. As the DAP stack was reduced the
new industry standard stack was referred to as Lightweight DAP (LDAP). The new LDAP
stack was very similar to the standard TCP/IP stack, therefore most implementations of LDAP
use what is referred to as a Stand-Alone LDAP Environment with the TCP/IP stack. Thus the
LDAP Server and the X.500 Server have been combined. Figure 6-5 represents the most
common LDAP industry solutions including the IBM solution.

Overview of LDAP architecture

LDAP defines the content of messages exchanged between an LDAP client and an LDAP
server. The messages specify the operations requested by the client (that is search, modify,
and delete), the responses from the server, and the format of data carried in the messages.
LDAP messages are carried over TCP/IP, a connection-oriented protocol, so there are also
operations to establish and disconnect a session between the client and server.

However, for the designer of an LDAP directory, it is not so much the structure of the
messages being sent and received over the wire that is of interest. What is important is the
logical model that is defined by these messages and data types, how the directory is
organized, what operations are possible, how information is protected, and so forth.

290 ABCs of z/OS System Programming Volume 6

The general interaction between an LDAP client and an LDAP server takes the following form:
1. The client establishes a session with an LDAP server, which is known as binding to the
server. The client specifies the host name or IP address and TCP/IP port number where
the LDAP server is listening.
2. The client can provide a user name and a password to properly authenticate with the
server, or the client can establish an anonymous session with default access rights. The
client and server can also establish a session that uses stronger security methods such as
encryption of data.
3. The client then performs operations on directory data. LDAP offers both read and update
capabilities. This allows directory information to be managed as well as queried. LDAP
also supports searching the directory for data meeting arbitrary user-specified criteria.
Searching is a very common operation in LDAP. A user can specify what part of the
directory to search and what information to return. A search filter that uses Boolean
conditions specifies what directory data matches the search.
4. When the client is finished making requests, it closes the session with the server, which is
also known as unbinding.

Chapter 6. LDAP 291

6.6 LDAP servers on z/OS (Integrated Security Server LDAP
plus IBM Tivoli Directory Server)

z/OS
IODF
IODF Only in
schema
HCD IIS LDAP
RMF RMF
RMF DDS schema
LDAP client TCP/IP slapd SDBM RACF
LDAP client
stack daemon RACF schema
LDAP V3
Basic auth Only in
LDBM ACL
SSL/TLS HFS zFS ITDS
schema
Kerberos
CRAM-MD5 GDBM
config
Digest-MD5
TDBM ACL
LDAP DB2 schema
client EXOP
USS

OMVS / TSO Applications

ldapsearch
ldapmodify
ldapdelete
ldapmodrdn
ldapcompare

Figure 6-6 LDAP servers on z/OS

LDAP servers on z/OS

The z/OS LDAP is provided in two different flavours. The Integrated Security Server LDAP is
stabilized on z/OS 1.6 level. The IBM Tivoli Directory Server was introduced in z/OS 1.8. The
only reason to choose the old LDAP server is if you choose to store IODF or RMF in LDAP.
Both servers are based on a client/server model that provides client access to an LDAP
server. An LDAP directory provides an easy way to maintain directory information in a central
location for storage, update, retrieval, and exchange.

292 ABCs of z/OS System Programming Volume 6

6.7 LDAP server back ends

LDAP Server has multiple backends (data stores)

LDBM: General purpose directory (only in ITDS)
Modifiable schema, data stored in HFS or zFS. Full scalability,
full LDAP V3 support
TDBM: General purpose directory
Modifiable schema, data stored in DB2 database. Full
scalability, full LDAP V3 support
SDBM: RACF users, groups, and user-group connections
Fixed schema, data stored in RACF database
HCD: IODF (HCD) definitions (only in IIS LDAP)
Fixed schema, data stored in IODF
RMF: Metrics gathered by RMF III (only in IIS LDAP)
Fixed schema, data provided and stored by RMF DDS server.

Figure 6-7 LDAP server back ends

LDAP server back ends

LDAP data is stored in the directory which is nothing more than a hierarchical database.
LDAP is not the directory but the defined APIs to gain access to the data within the directory
(or database). The directory is also referred to as the back-end store. Each LDAP solution
supports its own back-end store. The data in the directory must have a schema (that is, a data
definition or layout) according to the LDAP standards.

Schemas are another important part of LDAP. Schemas define the type of objects that can be
stored in the directory. Schemas also list the attributes of each object type and wether these
attributes are required or optional.

Chapter 6. LDAP 293

6.8 Capabilities of the Tivoli Directory Server LDAP server (1/2)

Multiple concurrent database instances (backends)

Robust general-purpose database (DB2 or USS)
Access to RACF user, group and connect data (SDBM)
Loading and unloading data (TDBM, LDBM)
Access control
Multi-threading
Multiple concurrent servers (TDBM, LDBM, GDBM)
Replication
Referrals
Aliases
Change logging in GDBM for TDBM and LDBM
Simplified configuration
Secure communication
Dynamic workload management

Figure 6-8 Capabilities of the Tivoli Directory Server LDAP server

Capabilities of the Tivoli Directory Server LDAP server

You can use the z/OS LDAP server to provide a directory service of your very own. Your
directory can contain just about anything you want to put in it. Note that the IIS LDAP Server
is alone to support IODF and RMF data and the Tivoli Directory Server is the only one to
support LDBM and data store in UNIX System Services file system. The remainder of the
back ends are supported by both servers.

Features and capabilities of the z/OS LDAP server include:

 Multiple concurrent database instances (referred to as back ends): The LDAP server
can be configured to serve multiple databases at the same time. This means that a single
z/OS LDAP server can respond to requests for many logically different portions of the
LDAP tree. A z/OS LDAP server can be configured to provide access to RACF, as well as
store application-specific information.
 Robust database: The LDAP server comes with a TDBM back-end database based on
DB2. The TDBM database is a highly scalable database implementation. To use TDBM,
DB2 is required.

294 ABCs of z/OS System Programming Volume 6

 Access to RACF data: The LDAP server can be configured to provide read/write access
to RACF user, group, and connection profiles using the LDAP protocol. (RACF is a
component of the Security Server for z/OS.) If the RACF data is shared across the
sysplex, then users, groups, and connections in the sysplex can be managed using LDAP.
The LDAP server’s access to RACF is managed by an additional configurable back end
called SDBM. To use SDBM for only authentication (LDAP bind processing), any security
manager implementing the SAF service required by the __passwd() function call can be
used. To use SDBM for accessing and updating USER and GROUP profile information,
RACF is required.
 Loading and unloading data: The LDAP server can load a large number of entries into a
TDBM DB2 database using the ldif2tdbm utility. The LDAP server can also unload a large
number of entries from a TDBM DB2 database using the tdbm2ldif utility.
 Access control: The LDAP server provides a rich and powerful access control facility,
allowing you to control access to the information in your database or databases. You can
control access to entries based on LDAP authentication information, including users and
groups. Group membership can be either static, dynamic, or nested. Access control is
configurable down to individual attributes within entries. Also, access controls can be set
up to explicitly deny access to information.
 Threads: The LDAP server is threaded for high performance. A single multi-threaded
z/OS LDAP server process handles all incoming requests, reducing the amount of system
overhead required.
 Replication: The LDAP server can be configured to maintain replica copies of its
database. This master/subordinate replication scheme is vital in high-volume
environments where a single LDAP server just does not provide the necessary availability
or reliability. Peer to peer replication is also supported. This feature is contrasted with
multiple concurrent servers.
 Referrals: The LDAP server provides the ability to refer clients to additional directory
servers. Using referrals you can distribute processing overhead, distribute administration
of data along organizational boundaries, and provide potential for widespread
interconnection beyond an organization’s own boundaries.
 Aliases: An alias entry can be created in the directory to point to another entry in the
directory. During search operations, an alias entry can provide a convenient public name
for an entry or subtree, hiding the more complex actual name of the entry or subtree. It can
also avoid the need to duplicate an entry in multiple subtrees.
 Change Logging: The LDAP server can be configured to create change log entries in the
GDBM or LDBM back end. Each change log entry contains information about a change to
an entry in a TDBM back end or to a RACF user profile.
 Configuration: The LDAP server configuration process can be simplified by using the
ldapcnf configuration utility. This utility requires minimal user interaction and allows novice
LDAP users to configure an LDAP server quickly. If you do not use the dsconfig utility, the
LDAP server is highly configurable through a single configuration file which allows you to
change just about everything you would ever want to change. Configuration options have
reasonable defaults, making your job much easier.
 Secure communications: The LDAP server can be configured to encrypt data to and
from LDAP clients using the z/OS Cryptographic Services System SSL. The LDAP server
supports the Start TLS extended operation to switch a non-secure connection to a secure
connection. It has a variety of ciphers for encryption to choose from, all of which provide
server and optionally client authentication through the use of X.509 certificates.

Chapter 6. LDAP 295

  Multiple concurrent servers: The LDAP server can be configured to permit multiple
instances to serve the same DB2-based backing store at the same time. The multiple
server instances can run on the same z/OS image, and they can run on multiple z/OS
images in a Parallel Sysplex. This support is available for the TDBM and GDBM back
ends, improves availability, and can offer improved performance in certain configurations.
 Dynamic workload management: The LDAP server can be configured to participate in
dynamic workload management in a Parallel Sysplex by exploiting TCP/IP connection
optimization. With multiple concurrent server instances configured in this way, availability
is improved, as is resource utilization. In addition, performance improvements can be
experienced as sysplex resource utilization is more evenly balanced across z/OS systems
in the sysplex.

296 ABCs of z/OS System Programming Volume 6

6.9 Capabilities of the Tivoli Directory Server LDAP server (2/2)

Retrieve Policy Director data

Native authentication
LDAP version 3 support
Dynamic schema
UTF-8 support
Simple Authentication Security Layer (SASL) bind with certificate
SSL/TLS,
GSS API Kerberos, CRAM-MD5, DIGEST-MD5
Root DSE
Extended root membership searching
Support for many server control protocolls, extended operation
Attribute encryption
Multiple socket ports
Persistent search
ibm-entryuuid attribute
ibm-allMembers and ibm-allGroups

Figure 6-9 Capabilities of the ITDS LDAP server

Capabilities of the LDAP server

Features and capabilities of the LDAP server include:
 Retrieve Policy Director data: The z/OS LDAP server, when using the EXOP back end,
supports two LDAP extended operations, GetDnForUserid and GetPrivileges, that
retrieve Policy Director data from any LDAP server.
 Native authentication: The z/OS LDAP server allows clients to bind to entries in a TDBM
back end by using the system for verifying the authentication attempt. The client can
perform a simple bind supplying an LDAP DN of an entry in a TDBM back end along with a
security manager-maintained password. Password authentication is then performed by the
security manager. To use native authentication, any security manager implementing the
SAF service required by the __passwd() function call can be used.
 LDAP Version 3 protocol support: The LDAP server provides support for Version 3 of
the LDAP protocol, which includes:
– All protocol operations
– Implicit bind
– Certificate (or Simple Authentication and Security Layer) bind
– Version 3 referrals
– Aliases
– Controls
– Root DSE support
– Internationalization (UTF-8) support

Chapter 6. LDAP 297

 – Modify name supported for all entries including subtree move
– Schema publication (TDBM, SDBM, and GDBM)
– Additional syntax support (TDBM and GDBM)
 Dynamic schema: The LDAP server, when using the TDBM or GDBM back end, allows
the schema to be changed dynamically through the LDAP protocol.
 Internationalization (UTF-8) support: The LDAP server allows storage, update and
retrieval, through LDAP operations, of national language data using LDAP Version 3
protocol.
 SASL external bind and client and server authentication: The LDAP server allows
client applications to use a certificate when communicating with the server using SSL/TLS
communications. To use a certificate on bind, the server must be configured to perform
both client and server authentication. This ensures both entities are who they claim to be.
 SASL GSS API Kerberos bind with mutual authentication: The LDAP server allows
clients to bind to the server using Kerberos credentials. Mutual authentication is used to
verify both the client and server identities.
 SASL CRAM-MD5 and DIGEST-MD5 authentication: The LDAP server allows clients to
bind to the server using DIGEST-MD5 (RFC 2831) and Challenge-Response
Authentication Method - RFC 2195 (CRAM-MD5) authentication bind methods.
 Support for root DSE: The LDAP server supports search operations against the Root of
the Directory tree as described in IETF RFC 2251, The Lightweight Directory Access
Protocol (V3). The so-called Root DSE can be accessed using LDAP V3 search
operations.
 Extended group membership searching: The LDAP server supports extended group
membership searching which allows the LDAP server to find a DN that can be a member
of static and nested groups in a back end (TDBM) where the DN does not reside. The
LDAP server can find the group memberships for the DNs in the other back ends that are
configured.
 Supported server controls: The LDAP server supports the manageDsaIT,
authenticateOnly, IBMLDAPProxyControl, IBMModifyDNTimelimitControl,
IBMModifyDNRealignDNAttributesControl, persistentSearch, and
schemaReplaceByValueControl.
 Supported extended operations: The LDAP server supports the GetDnForUserid,
GetPrivileges, and changeLogAddEntryRequest extended operations.
 Password encryption: The LDAP server allows prevention of unauthorized access to
user passwords stored in the TDBM back ends.
 Multiple socket ports: The LDAP server can be configured to listen for secure and
non-secure connections from clients on one or more IPv4 or IPv6 interfaces on a system.
With the listen configuration option on the LDAP server, the host name or the IPv4 or IPv6
address, along with the port number, can target one or multiple IPv4 or IPv6 interfaces on
a system.
 Persistent search: The LDAP server provides an event notification mechanism for
applications, directories, and meta directories that need to maintain a cache of directory
information or to synchronize directories when changes are made to an LDAP directory.
Persistent search will allow these applications to be notified when a change has occurred.
 Ibm-entryuuid attribute: The LDAP server now generates a unique identifier for any entry
that is created or modified and does not already have a unique identifier assigned. The
unique identifier is stored in the ibm-entryuuid attribute. The ibm-entryuuid attribute is
replicated to servers that support the ibm-entryuuid attribute. A utility is provided to create
the ibm-entryuuids for existing entries when migrating from previous releases.

298 ABCs of z/OS System Programming Volume 6

 ibm-allMembers and ibm-allGroups: The LDAP server now supports the querying of the
members of static, dynamic, and nested groups in a TDBM back end through the
ibm-allMembers operational attribute. The LDAP server also supports the querying of the
static, dynamic, and nested groups that a user belongs to with the ibm-allGroups
operational attributes.

Chapter 6. LDAP 299

6.10 LDAP configuration by utility

ldapcnf and dsconfig

ldapcnf for IIS LDAP, dsconfig for IBM Tivoli Directory Server
z/OS UNIX utilities to assist customer for z/OS LDAP Server
configuration
Generates:
JCL jobs to accomplish the updates of all the z/OS components
Configuration files necessary for server to operate
Customer input into only one file for simple configuration, three additional
files allow for complex configuration input
Removes need for redundant updates
Establishes and segregates component updates
Generates jobs executed by user with proper authority for the different
components

Figure 6-10 LDAP configuration utility

LDAP configuration utility

Each of the LDAP servers, Integrated Security Server LDAP and IBM Tivoli Directory Server,
has its own configuration program. The input, output, and process is very similar but there are
some differences.

The LDAP configuration utility helps you configure new LDAP server instances with minimal
user interaction.

The LDAP configuration utility takes a profile file as input and generates a set of output
members in a data set to facilitate an LDAP server configuration. The profile file is targeted for
the System Administrator (or System Programmer) and the LDAP Administrator and it
contains statements that must be updated with appropriate values. The LDAP configuration
utility generates a series of JCL members, configuration files, and a procedure to start the
LDAP server. The JCL jobs are segregated based on typical administrative roles in a z/OS
installation and contain the required commands to configure the z/OS components used by
the LDAP server. Each administrator is responsible for reviewing and submitting their JCL job.
After all JCL jobs are submitted, each administrator is responsible for reviewing their job’s
output and addressing any errors that might have occurred. When all JCL jobs have
completed successfully, the LDAP server can be started.

The minimal user interaction with the utility and the jobs it produces to update the required
z/OS components results in a simplified approach to LDAP configuration. This approach
allows novice LDAP users and administrators and even novice z/OS users to quickly deploy
an LDAP server. In addition, the utility does not restrict the configuration of advanced LDAP
features, such as referrals, replication, password encryption, and sysplex setup.

300 ABCs of z/OS System Programming Volume 6

Capabilities of the LDAP configuration utility
Features and capabilities of the LDAP configuration utility include:
 Allows for the configuration of a TDBM (DB2-based), LDBM (file-based), SDBM
(RACF-based), Extended operations (EXOP) and change log GDBM (DB2-based) back
ends.
 Generates JCL jobs to accomplish the updates of all the z/OS components that are
required for an LDAP server.
 Can configure advanced LDAP server features, including:
– Password encryption (dsconfig does not generate certificates or passwords)
– Referrals
– Replication
– Change logging
– Secure Sockets Layer (SSL) or Transport Layer Security (TLS) (dsconfig does not
generate certificates or passwords)
– Kerberos authentication
– Native authentication
– Extended operations (EXOP) back end (used for accessing Policy Directory
information)

Chapter 6. LDAP 301

6.11 Utility ldapcnf restrictions

The ldapcnf utility has the following restrictions

Generates a procedure; must run as a started task.

Assumes that RACF is the security server in use. If not the resulting
JCL job needs to be converted to properly update the security server in
use.

Does not handle multiple TDBM (DB2-based) or

LDBM (file-based) backends.

All values in the input files must be less than 66 bytes in length
and must contain only printable characters in the IBM-1047 code page.

Cannot extend or enhance an existing LDAP server configuration.

Output will be lost if you run the utility again.

Does not support configuration for an LDAP server to listen on more

than one secure or non-secure port.

Figure 6-11 List of ldapcnf restrictions

Restrictions of the LDAP configuration utility

Restrictions of the LDAP configuration utility include:
 Generates a procedure; therefore, the LDAP server must run as a started task.
 Assumes that RACF is the security server in use. However, if RACF is not the security
server in use, ldapcnf could still be used. The resulting RACF JCL job needs to be
converted to properly update the security server in use.
 Does not handle multiple TDBM (DB2-based) or LDBM (file-based) back ends.
 All values in the input files must be less than 66 bytes in length and must contain only
printable characters in the IBM-1047 code page.
 Cannot extend or enhance an existing LDAP server configuration. Furthermore, any
manual updates to the output that the utility produces will be lost if you run the utility again
with the same output data set.
 Does not support configuration for an LDAP server to listen on more than one secure port.
 Does not support configuration for an LDAP server to listen on more than one non-secure
port.

302 ABCs of z/OS System Programming Volume 6

6.12 Utility dsconfig restrictions

The dsconfig utility has the following restrictions

Assumes that RACF is the security server in use.

If not the resulting JCL job needs to be converted to
properly update the security server in use.

Does not handle multiple TDBM (DB2-based) or

LDBM (file-based) backends.

All values in the input files must be less than 66 bytes in length
and must contain only printable characters in the IBM-1047 code page.

Cannot extend or enhance an existing LDAP server configuration.

Output will be lost if you run the utility again.

Figure 6-12 List of dsconfig restrictions

LDAP dsconfig restrictions

The dsconfig utility has the following restrictions:
 Assumes that RACF is the security server in use. If not, the resulting JCL job needs to be
converted to properly update the security server in use.
 Does not handle multiple TDBM (DB2-based) or LDBM (file-based) back ends.
 All values in the input files must be less than 66 bytes in length and must contain only
printable characters in the IBM-1047 code page.
 Cannot extend or enhance an existing LDAP server configuration.
 Output is lost if you run the utility again.

Chapter 6. LDAP 303

6.13 Utility invocation and outputs

Utilities are invoked by:

/usr/lpp/ldap/sbin/
ldapcnf -i ldap.profile (ISS LDAP) or
dsconfig -i profile_file (ITDS)

Utility input /usr/lpp/ldap/etc/ldap.profile or

/usr/lpp/ldap/etc/ds.profile
Environment variable file that the customer must update before invoking
the utility.

Outputs
Error messages if required variables are not assigned values in the input file or
fail simplified syntax checking
Warning messages if overwriting existing output data set
Multiple JCL jobs that will update the various z/OS components
PROG member to establish APF Authorization
Configuration files for various components
PROC to start the server

Figure 6-13 Utility invocations and outputs

Using the ldapcnf or dsconfig utility

The ldapcnf and dsconfig utilities are used to generate jobs to set up the system
environment and configuration for a new LDAP server. This utility is installed into the
/usr/lpp/ldap/sbin directory.

Format
The format of this command is as follows:
ldapcnf -i profile_file or dsconfig -i profile_file

where:
profile_file specifies the input file that contains statements necessary to configure the
LDAP server.

Example 6-1 shows an example using ldapcnf, where ldap.profile is in the /home/u
directory.

Example 6-1 Using the ldapcnf command

ldapcnf -i /home/u/ldap.profile

304 ABCs of z/OS System Programming Volume 6

Input file description
The input file, ldap.profile, shipped in the /usr/lpp/ldap/etc directory, contains the settings that
are necessary to set up an LDAP server. You must copy the ldap.profile file and then modify it
before you can run the LDAP configuration utility, ldapcnf.

In this file there are statements containing a keyword and value which must have the
appropriate value for the target system being configured.

Example 6-2 shows a sample portion of the ldap.profile file. The LDAPUSRID statement, as
shown in the example, has a pre-assigned value of GLDSRV. Above the statement there is
some commentary that describes the statement and its usage.

Example 6-2 Sample portion of the ldap.profile file

# LDAPUSRID <user_id>
#
# Description:
# User ID for the LDAP server to run under.
#
# Note:
# This variable’s value must be capitalized.
# ---------------------------------------
LDAPUSRID=’GLDSRV’

Most of the statements in the ldap.profile are required and those that are not required are
labelled as optional. Some statements in the ldap.profile have pre-assigned values; however,
they might not be valid on the target system being configured. Values must be provided for all
required statements in the ldap.profile file.

The ldap.profile file embeds three other advanced input files.All of the input files are in the
same format as an environment variable file.

The output from ldapcnf is written to an output data set that you specify in ldap.profile. If the
data set does not exist, the utility allocates the output data set for you.

Chapter 6. LDAP 305

6.14 Configuration roles and responsibilities

(if SDBM is being System

configured) Administrator LDAP
SLAPDCNF Administrator
APF
ldap.slapd.profile/
ds.slapd.profile
PROC
PROsuffix
(LDAPUSRID)

ldap.profile/
ds.profile SLAPDENV

ldapcnf

ldap.db2.profile/ DBCLI
ds.db2.profile

RACF
ldap.racf.profile/ DBSPUFI
ds.racf.profile
PRGMCTRL
DSNAOINI
Security
Database
Administrator Administrator

Figure 6-14 Configuration roles and responsibilities

Configuration roles and responsibilities

Use ldapcnf for IIS LDAP and dsconfig for the Tivoli Directory Server LDAP server. The
output from the LDAP configuration utility consists of jobs and configuration files that finalize
the LDAP server configuration. These jobs segregate z/OS updates based on typical
administrative roles, allowing each administrator to control their component’s updates. The
typical administrative roles that are assumed to exist to configure an LDAP server are:
 System Administrator (or System Programmer)
 Database Administrator
 LDAP Administrator
 Security Administrator

Each administrator is responsible for updating input files in addition to reviewing and
submitting jobs in the output members that the LDAP configuration utility produces for their
component.

Consult the reference manuals for a detailed description.

Note: If configuring SDBM and password encryption, the Security Administrator must have
read/write authority on all files in the /usr/lpp/ocsf/lib and /usr/lpp/ocsf/addins directories.

306 ABCs of z/OS System Programming Volume 6

6.15 The LDAP schema

"root"
Object Classes definitions
c=US c=UK objectclass person
oc=country
c=US
requires : cn
objectClass
o=IBM allows: mail
o=Lotus o=Tivoli
oc=organization
o=IBM

objectclass organization

cn=Tim Hahn Schema requires: o

objectClass
oc=person
cn=Tim Hahn allows: description
[email protected] businessCategory
[email protected]
.....

RDN: cn =Tim Hahn

DN: cn=Tim Hahn, o =IBM, c=US
Attribute types definitions
objectClass oc cis 128 normal
commonName cn cis 128 normal
organizationName o cis 128 normal
....

Figure 6-15 The LDAP schema

What is the schema

A schema is a set of rules that governs the way that data can be stored in the directory. The
schema defines the type of entries that are allowed, their attribute structure, and the syntax of
the attributes.

Data is stored in the directory using directory entries. An entry consists of an object class,
which is required, and its attributes. Attributes can be either required or optional. The object
class specifies the kind of information that the entry describes and defines the set of
attributes it contains. Each attribute has one or more associated values.

The schema is published as part of the directory information, and is available in the
Subschema entry (DN="cn=schema").

The schema has more configuration information than that included in the LDAP Version 3
Request For Comments (RFCs) or standard specifications. For example, for a given attribute,
you can state which indexes must be maintained. This additional configuration information is
maintained in the subschema entry as appropriate. An additional object class is defined for
the subschema entry IBMsubschema, which has MAY attributes that hold the extended schema
information.

Tivoli Directory Server requires that the schema that is defined for a naming context be stored
in a special directory entry, "cn=schema". The entry contains all of the schema defined for the
server. To retrieve schema information, you can perform an ldap_search using the following:
DN: "cn=schema", search scope: base, filter: objectclass=subschema
or
DN: "cn=schema", search scope: base, filter: objectclass=*

Chapter 6. LDAP 307

6.16 Schema attribute types

The schema provides values for the following

attribute types:

ObjectClasses
AttributeTypes
IBMAttributeTypes
Matching rules
LDAP syntaxes

Figure 6-16 Schema attribute types

Schema attribute types

Entries in the directory are made up of attributes that consist of an attribute type and one or
more attribute values. These are referred to as attribute=value pairs. Every entry contains
one or more objectClass attribute=value pairs that identify the type of information that the
entry contains. The object classes that are associated with the entry determine the set of
attributes that must or can be present in the entry.

The schema is represented and stored as another entry in the directory. Example 6-3 shows
a portion of the schema entry.

Example 6-3 Portion of the schema entry

cn=SCHEMA,o=Your Company,c=US subtreespecification=NULL
objectclass=TOP objectclass=SUBSCHEMA
objectclass=SUBENTRY objectclass=IBMSUBSCHEMA
...
attributetypes= ( 2.5.4.3 NAME ( ’cn’ ’commonName’ ) SUP name )
...
ibmattributetypes = ( 2.5.4.3 ACCESS-CLASS normal )
...
objectclasses = ( 2.5.6.0 NAME ’top’ ABSTRACT MUST objectclass )
...
ldapsyntaxes = ( 1.3.6.1.4.1.1466.115.121.1.15 DESC ’directory string’ )
...

308 ABCs of z/OS System Programming Volume 6

matchingrules = ( 2.5.13.5 NAME ’caseExactMatch’ SYNTAX
1.3.6.1.4.1.1466.115.121.1.15 )
...

The objectClass values specified for the schema entry are top, subEntry, subSchema, and
ibmSubschema. This set of object classes result in the objectClass, cn, and
subtreeSpecification attributes being required for a schema entry and the attributeTypes,
objectClasses, ldapSyntaxes, matchingRules, and ibmAttributeTypes attributes being
allowed in a schema entry.

Note: The ditContentRules, ditStructureRules, nameforms, and matchingRuleUse

attributes are allowed in a schema entry, but usage of these directives is not implemented
by the z/OS LDAP server.

Attribute types
Attribute types define the characteristics of the data values stored in the directory. Each
attribute type defined in a schema must contain a unique numeric object identifier and
optionally contain a textual name, zero or more alias names, and a description of the attribute
type. The characteristics defined for each attribute type include the syntax, length, and
matching rules.

Matching rules
Matching rules allow entries to be selected from the database based on the evaluation of the
matching rule assertion. Matching rule assertions are propositions that might evaluate to true,
false, or undefined concerning the presence of the attribute value or values in an entry.

The z/OS LDAP server is shipped with predefined supported matching rules. The set of
matching rules cannot be changed, added to, obsoleted, or deleted by users.

IBM attribute types

Additional information required by IBM LDAP servers for each attribute type defined in the
schema is specified using the ibmAttributeTypes schema attribute. The ibmAttributeTypes
schema attribute is an extension of the attributeTypes schema attribute. If the
attributeTypes value is not defined, then the corresponding ibmAttributeTypes value
cannot be defined. For the z/OS LDAP server, the additional information defined using this
attribute is the ACCESS-CLASS of the associated attribute type.

Object classes
Object classes define the characteristics of individual directory entries. The object classes
listed in a directory entry determine the set of required and optional attributes for the entry.
Each object class defined in a schema must contain a unique numeric object identifier and
optionally contain a textual name, zero or more alias names, a description of the object class,
and lists of required (MUST) or optional (MAY) attribute types.

LDAP syntaxes
Each attribute type definition includes the LDAP syntax which applies to the values for the
attribute. The LDAP syntax defines the set of characters which are allowed when entering
data into the directory. The z/OS LDAP server is shipped with predefined supported syntaxes.
The set of syntaxes cannot be changed, added to, or deleted by users.

Chapter 6. LDAP 309

6.17 LDAP directory schema

The z/OS LDAP server implements both schema

publication and update.

The z/OS LDAP server is initially started with an

internal minimal schema. This is sufficient for SDBM
and GDBM but updates are required for LDBM and
TDBM.

Access to the schema is controlled by an Access

Control List (ACL).

Figure 6-17 LDAP directory schema

LDAP directory schema

Schema publication provides the ability to query the active directory schema through the use
of the LDAP search function. Schema update is the ability to change the schema while the
directory server is running.

Setting up the schema for LDBM and TDBM new users

The LDAP server is shipped with two predefined schema files representing schema
definitions which the user might want to load as the LDAP schema LDBM or TDBM. These
files are schema.user.ldif and schema.IBM.ldif. The schema.IBM.ldif schema definitions
require that the definitions that are contained in schema.user.ldif are loaded prior to loading
schema.IBM.ldif. Determine which schema files will be used to represent the data that is
stored in the LDBM and TDBM directory. Copy the files from the /usr/lpp/ldap/etc directory to
a working directory, for example the /home/myuser directory.

For each file, find the following line and replace <suffix> with one of the suffixes defined for
the back end in the LDAP server configuration file:
“dn: cn=schema, <suffix>”

Make your updates, and then run the ldapmodify command from the z/OS shell specifying the
host, port, bind DN, password, and schema file for each schema file to load the schema into
the directory.

310 ABCs of z/OS System Programming Volume 6

6.18 Authentication with an LDAP server

LDAP is a stateful protocol

Session starts when client "binds" to server
Session can be unauthenticated (anonymous bind)
Authentication is performed during bind
LDAP supports different authentication protocols
Simple bind: Distinguished Name and password or passticket
Session can optionally be protected with SSL/TLS
Passwords can be stored in LDAP directory, optionally one-way
(MD5, SHA-1, crypt) or two-way (TDES) encrypted
Certificate bind: X.509 digital certificate over SSL
Distinguished name in certificate must conform with distinguished
name of person authenticating
Kerberos bind: Kerberos principal sends ticket for LDAP server
Attribute: ibm-kn = principal @ realm
SASL bind: CRAM-MD5, DIGEST-MD5

Figure 6-18 Authentication with an LDAP server

Authentication with an LDAP server

Authentication operations are used to establish and end a session between an LDAP client
and an LDAP server. The session can be secured at various levels ranging from an insecure
anonymous session, an authenticated session in which the client identifies itself by providing
a password, to a secure, encrypted session using SASL mechanisms. SASL was added in
LDAP Version 3 to overcome the weak authentication in LDAP Version 2.

Authentication operations:
 Bind: Initiates an LDAP session between a client and a server. Allows the client to prove
its identity by authenticating itself to the server.
 Unbind: Terminates a client/server session.
 Abandon: Allows a client to request that the server abandon an outstanding operation.

Security model
The security model is based on the bind operation. There are several different bind
operations possible, and thus the security mechanism applied is different as well. One
possibility is when a client requesting access supplies a DN identifying itself along with a
simple clear-text password. If no DN and password is declared, an anonymous session is
assumed by the LDAP server. The use of clear text passwords is strongly discouraged when
the underlying transport service cannot guarantee confidentiality and can, therefore, result in
disclosure of the password to unauthorized parties.

Chapter 6. LDAP 311

 LDAP V3 comes along with a bind command that supports the Simple Authentication and
Security Layer (SASL) mechanism. SASL is a general authentication framework, where
several different authentication methods are available for authenticating the client to the
server. One authentication method is Kerberos.

Furthermore, extended protocol operations are available in LDAP V3. An extension related to
security is the Extension for Transport Layer Security (TLS) for LDAPv3. This allow operations
too use TLS as a means to encrypt an LDAP session and protect against spoofing. TLS has a
mechanism which enables it to communicate to an SSL server so that it is backwards
compatible. The basic principles of SSL and TLS are the same.

312 ABCs of z/OS System Programming Volume 6

6.19 LDAP authentication with RACF

Enter userid : auster

Enter password : ********

dn="racfid=auster,profiletype=user,o=IBM"
pw=<password> bind request
ldap_bind_s(ld,host,port,dn,pw)

z/OS
LDAP LDAP Server
Client SDBM
(API)

successful bind

dn: racfid=auster,profiletype=user,o=IBM

objectclass=racfUser
objectclass=racfBaseCommon
objectclass=racfBaseUserSegment RACF userId
racfid=AUSTER
RACF DB
racfprogrammername=James Auster
racfdefaultgroup=racfid=groupid,profiletype=GROUP,sysplex=...

Figure 6-19 LDAP authentication with RACF

LDAP authentication with RACF

RACF provides definitions of users and groups, as well as access control for resources. The
LDAP server can provide LDAP access to the user and group information stored in RACF.

Using SDBM, the RACF database back end of the LDAP server, you can:
 Add new users and groups to RACF
 Add users to groups (connections)
 Modify RACF information for users and groups
 Retrieve RACF information for users and groups
 Delete users and groups from RACF
 Remove users from groups (connections)
 Retrieve RACF user password envelope

The SDBM database of the LDAP server implements portions of the adduser, addgroup,
altuser, altgroup, deluser, delgroup, listuser, listgrp, connect, remove, and search RACF
commands. An individual user has the same authority through SDBM as with normal RACF
commands. The SDBM database of the LDAP server makes use of the R_Admin run
command interface to accomplish its access to RACF data. As a result, this support is subject
to the restrictions of the R_Admin interface. One restriction in particular affects return of
search results.

Chapter 6. LDAP 313

 The SDBM database allows for directory authentication (or bind) using the RACF user ID and
password. The RACF user ID must have an OMVS segment defined and an OMVS UID
present. The RACF user and group information that make up an identity can be used to
establish access control on other LDAP directory entities. This expands use of the RACF
identity to the rest of the LDAP-managed namespace. Note the following information when
using RACF access:
 An LDAP simple bind to a z/OS LDAP server using RACF access support but having a
non-RACF security manager will succeed as long as the __passwd() call made by the
LDAP server is successful. However, no group membership information will be available
for the bound distinguished name if the security manager is not RACF.
 An LDAP simple bind made to a z/OS LDAP server using RACF access support continues
to provide a successful or unsuccessful LDAP return code. In addition, if the LDAP return
code being returned is LDAP_INVALID_CREDENTIALS, additional information is provided
in the “message” portion of the LDAP result. The additional information is an LDAP-unique
reason code and reason code text in the following format:
Rnnnnnn text

If the SDBM database is to be used for authentication purposes only, consider having your
clients use the authenticateOnly server control, to streamline bind processing. This
supported control overrides any extended group membership searching and default group
membership gathering and is supported for Version 3 clients.

Note: The SDBM back end only updates the default RACF on a given system. That is, the
AT and ONLYAT clauses of the RACF commands, used to redirect RACF commands, are
not exploited by SDBM.

Note: The use of RACF passtickets is supported by the z/OS LDAP server. It is
recommended that the LDAP server be run as a started task if RACF passticket support
will be used. The job name that is associated with the LDAP Server started task should be
used as the application name when generating RACF passtickets.

314 ABCs of z/OS System Programming Volume 6

6.20 z/OS LDAP server native authentication

Disadvantage of Authentication in RACF: SDBM backend required

Nonstandard Distinguished Name (racfid, profiletype)
Fixed schema: only RACF information is available, attribute names
cannot be changed
Native Authentication uses LDBM or TDBM backend
Standard Distinguished Name (cn, ou, o); can be adapted
Any schema supported by LDAP V3 for person entry can be used
Any information supported by the schema can be retrieved
Authentication (password verification) performed by RACF
No need for administration of multiple registries, no synchronization
of passwords, no confusion of end users
RACF authentication triggered by attribute ibm-nativeId
RACF users and non-RACF users in same LDAP directory

Figure 6-20 LDAP server native authentication

LDAP server native authentication

LDAP has the ability to authenticate to the Security Server through LDBM or TDBM by
supplying a Security Server password on a simple bind to a LDBM or TDBM back end.
Authorization information is still gathered by the LDAP server based on the DN that performed
the bind operation. The LDAP entry that contains the bind DN should contain either the
ibm-nativeId attribute or uid attribute to specify the ID that is associated with this entry. Note
that the SDBM back end does not have to be configured. The ID and password are passed to
the Security Server and the verification of the password is performed by the Security Server.
Another feature of native authentication is the ability to change your Security Server’s
password by issuing an LDAP modify command.

Chapter 6. LDAP 315

6.21 Enabling LDAP native authentication

Enter userid : auster

Enter password : ********

dn="cn=James Auster,ou=TMCC,o=IBM" z/OS

bind request LDAP Server
pw=<password>
LDBM/TDBM
ldap_bind_s(ld,host,port,dn,pw)

find entry, compare password

LDAP Client
(API)

successful bind
Directory

dn: cn=James Auster,ou=TMCC,o=IBM

objectclass: person RACF DB

objectclass: inetOrgPerson RACF userId
objectclass: ibm-nativeAuthentication
cn: James Auster
In LDBM or sn: Auster
TDBM directory ibm-nativeId: AUSTER

Figure 6-21 Enabling LDAP native authentication

Initializing native authentication

To enable native authentication, perform the following steps:
1. Install and configure RACF or another Security Server.
2. Configure an LDAP server to run LDBM or TDBM and start the server. Specify the native
authentication options in your configuration file. For example:
TDBM Section
useNativeAuth SELECTED
nativeAuthSubtree o=IBM,c=US
nativeAuthSubtree o=Lotus,c=US
nativeUpdateAllowed YES
3. Load the native authentication related schema elements into the TDBM back end.
4. Be sure that the entries that are to perform native authentication contain either the
ibm-nativeId attribute or a single-valued uid attribute with the appropriate Security Server
ID as its value. It is important to note that a multi-valued uid without an ibm-nativeId
causes the bind to fail because the LDAP server does not know which ID to use.

316 ABCs of z/OS System Programming Volume 6

Updating the schema for native authentication
To enable native authentication, the directory schema must contain the native authentication
related schema elements which are defined in schema.IBM.ldif.

The native authentication attribute type is as follows:

 ibm-nativeId: Allows you to specify the ID that is to be associated with this entry.

The native authentication object class is as follows:

 ibm-nativeAuthentication: Allows you to specify the ibm-nativeId attribute in entries.

Note: Entries that are added and subject to Native Authentication cannot contain the
userpassword attribute.

Note: RACF group gathering is not performed as a part of authentication.

Chapter 6. LDAP 317

6.22 Native authentication configuration options

LDBM or TDBM Section

nativeAuthSubtree <all|DN>
all - the entire TDBM directory will use Native Authentication
DN - subtree that contains entries that will use Native
Authentication

useNativeAuth <selected|all|off>
selected - entries located in native subtrees that contain the
ibm-nativeId attribute
all - every entry in native subtrees will use native authentication
with ibm-nativeId or uid attribute
off - Native Authentication is disabled

Figure 6-22 Native authentication configuration options

Native authentication configuration options

There are many different configuration options for native authentication. The main
configuration option, useNativeAuth, can be set to selected, all, or off. If you want all
entries in a certain subtree to participate in native authentication then you would choose all
for this option. However, if you want specific entries in the specific subtrees to be subject to
native authentication, then choose selected for the useNativeAuth option. When selected is
used, only entries with the ibm-nativeId attribute will be subject to native authentication.

In order for an entry to bind natively or perform a native password modify, that entry must
contain a mapping to the Security Server identity that is associated with the user. This can be
accomplished by using either the ibm-nativeId attribute or the uid attribute that is defined in
schema.user.ldif. If your directory entries already contain a single-valued uid attribute (which
holds the Security Server user ID), then these entries are already configured for native
authentication if you plan on using the useNativeAuth all option. If you do not plan on using
uids for mapping, then you can specify the ibm-nativeId attribute for your Security Server ID
associations and this attribute is used with selected or all specified for the useNativeAuth
option. If both the ibm-nativeId and uid attributes exist in an entry, the ibm-nativeId value is
used. The user ID specified by either the uid or ibm-nativeId attributes must contain a valid
OMVS segment in the Security Server.

If you use the useNativeAuth option, also specify the nativeUpdateAllowed option to enable
native password changes in the Security Server to occur through the TDBM back end.

318 ABCs of z/OS System Programming Volume 6

Next, consider what portions of your directory should have the ability to participate in native
authentication. If the entire directory should participate, then set the nativeAuthSubtree
configuration option to all. If there are different subtrees in your directory which contain
entries that need to bind natively or perform native password modifications, then you need to
list all the subtrees with the nativeAuthSubtree configuration option.

As mentioned, there are two LDAP operations affected: bind and password modify. There is a
set of criteria that is used to determine if an entry actually participates in native
authentication. This criteria changes depending on the configuration options that have been
selected.

Note: If the DN that is listed in the nativeAuthSubtree option contains a space character in
it, then the entire DN must be enclosed in quotation marks in the configuration file.

Chapter 6. LDAP 319

6.23 More native authentication configuration options

Allow native (RACF) passwords to be changed using an LDAP

modify to the LDBM or TDBM directory for entries where native
authentication applies.

LDBM or TDBM Section

nativeUpdateAllowed <on|yes|off|no>
on|yes - update of the native password is allowed
off|no - not allowed to update your native password

Issue a modify/delete with the old password followed by a modify/add

of the new password
-userpassword=<oldracfpassword>
+userpassword=<newracfpassword>

Figure 6-23 More native authentication configuration options

More native authentication configuration options

Performing a native password modify is as simple as issuing an ldapmodify command to
perform a delete followed by an add of the userpassword attribute. Specify the current
password on the delete statement followed by the new password on the add statement. The
delete must occur before the add for native password modify. In Example 6-4, the bind DN
has the authority to do this.

Example 6-4 Native password modify

If file pw.mod contains:

cn=You,o=IBM,c=US
-userpassword=oldpassword
+userpassword=newpassword

Then the following command modifies the native password:

ldapmodify ... -D cn=You,o=IBM,c=US -w oldpassword -f pw.mod

If the ldapmodify command fails with LDAP return code LDAP_INVALID_CREDENTIALS and the
following LDAP reason code, then it is possible to change the RACF password of a TDBM
entry participating in native authentication by doing an LDAP simple bind:
R004109 The password has expired.

320 ABCs of z/OS System Programming Volume 6

The simple bind can occur as part of an LDAP function such as search, add, or modify. The
password change is provided in the password portion of the LDAP simple bind. The password
must be in the following format:
password/newpassword

The forward slash (/) is used as the indication of a password change during the LDAP simple
bind. Password changes made using the LDAP simple bind to a TDBM entry participating in
native authentication are subject to the system password rules. A password change will fail
with LDAP return code LDAP_INVALID_CREDENTIALS and LDAP reason code of:
R004128 Native authentication password change failed: The new password is not
valid, or does not meet requirements.

if the new password does not pass the rules established on the system.

Note that when the bind succeeds, the password is changed even if the LDAP function
eventually fails.

Assuming TDBM entry cn=User1,ou=END,o=IBM,c=US is participating in native authentication,

the following command changes the RACF password for user USER1 from abc to def:
ldapsearch -h ldaphost -p ldapport -D "cn=User1,ou=END,o=IBM,c=US" -w abc/def
-b "ou=END,o=IBM,c=US"\ "objectclass=*"

Note: LDAP ACLs must be set properly to allow update of the userpassword attribute for
the password modification to complete successfully. The distinguished name provided on
the -D parameter of the ldapmodify command must have authority to update the
userpassword attribute. To allow each individual user to update their own password, an
LDAP ACL should be established to permit them to write userpassword attribute values.

You can also use the special cn=this identity entry to establish the LDAP ACL.

Run the following ldapmodify command to establish the LDAP ACL:

ldapmodify -D adminDN -w adminPW -f /tmp/aclmod.ldif

In this command, the file /tmp/aclmod.ldif looks similar to:

dn: o=Your Company
changetype: modify
add: x
aclEntry: access-id:cn=this:critical:rwsc
aclPropagate: TRUE

You should substitute the root of your directory tree for the dn: o=Your Company line in the
LDIF file to allow each user who is defined for native authentication to update the RACF
password through LDAP.

Chapter 6. LDAP 321

6.24 LDAP server-side Kerberos bind

Provide support for GSSAPI SASL binds and secure

authentication using Kerberos ticket

Publish Kerberos information in the servers rootDSE

supportedsaslmechanism=GSSAPI

ldapservicename=hostname@REALM

Kerberos is used only for LDAP authentication

No support for Kerberos integrity and confidentiality options

LDAP access control is performed on the basis of the

LDAP distinguished name

Figure 6-24 LDAP server-side Kerberos bind

LDAP server-side Kerberos bind

The z/OS LDAP server allows clients to authenticate to the server by using IBM Network
Authentication and Privacy Service which is better known as Kerberos Version 5. Kerberos is
a trusted third party, private-key, network authentication system. In Kerberos, a ticket, a
packet of information used by a client to prove its identity, is passed to a server in place of a
user name and password. This ticket is encrypted and cannot be duplicated. After the server
verifies the client ticket, it sends its own ticket to the client in order for the client to authenticate
it. Once the mutual authentication process is complete, the client and server have
authenticated each other.

In the z/OS LDAP server, Kerberos is used for authentication only. The Kerberos options for
integrity and confidentiality are not supported. Authorization information for ACLs is gathered
by the LDAP server after the authentication process has completed and is based on the
Kerberos identity of the bound client.

322 ABCs of z/OS System Programming Volume 6

6.25 LDAP Kerberos configuration

Install and configure the z/OS Network Authentication and Privacy Service
Kerberos on the machine where the LDAP server will run.
Create the LDAP servers Kerberos KDC account.
Optionally generate the servers keytab file (if not on the same system as
the KDC)
Specify the necessary Kerberos options in the slapd.conf file

Key Distribution Center (KDC)

Ticket
Kerberos Granting
Service
GLD0170I Kerberos authentication support has been enabled.
GLD0171I Kerberos authentication support has NOT been enabled
GLD0172E Dynamic load of Kerberos DLL failed
GLD0173E Server was unable to acquire Kerberos credentials
GSSAPI

User

LDAP Client LDAP Server

LDAP Server

Figure 6-25 LDAP Kerberos configuration

LDAP Kerberos configuration

Kerberos Version 5 binds, defined in IETF RFC 2222, are performed using the Generic
Security Services Application Programming Interface (GSS API) that is defined in IETF RFCs
2743 and 2744.

Note: From this point forward in this discussion, we use the phrase GSS API bind to refer
to Kerberos Version 5 binds.

Before you attempt to perform a Kerberos GSS API bind, be sure to:
1. Have the Network Authentication and Privacy Service (Kerberos 5) installed and
configured and the service started.
2. Create a Kerberos identity for the user ID that will start the LDAP server. For example:
ALTUSER LDAPSRV PASSWORD(password) NOEXPIRED
KERB(KERBNAME(ldap_prefix/hostname))
In this command, ldap_prefix is either “LDAP” or “ldap” and hostname is the primary host
name for the system in DNS.

Chapter 6. LDAP 323

 3. If the Key Distribution Center (KDC) is not located on the same machine as the LDAP
server, you have to generate a keytab file for the server. To generate a keytab for the
server, issue the following commands:
a. First check the version of the server’s Kerberos key because the version is updated
every time the password is changed:
LISTUSER LDAPSRV NORACF KERB
b. Now, issue the keytab command from the z/OS shell with the version from the
LISTUSER command:
keytab add LDAP/hostname -p password -v 001
You can also use the -k filename option if you want to use your own keytab file rather
than the Kerberos default keytab file.

Important: When issuing Kerberos commands all passwords must be in uppercase.

If the KDC and LDAP server are on the same system, you do not need a keytab file. If the
ID which starts the LDAP server has READ access to the IRR.RUSERMAP facility class in
RACF, then you can use this instead of a keytab file as follows:
RDEFINE FACILITY IRR.RUSERMAP UACC(NONE)
PERMIT IRR.RUSERMAP CLASS(FACILITY) ID(LDAPSRV) ACCESS(READ)
SETR RACLIST(FACILITY) REFRESH
4. Enable your configuration file for Kerberos authentication.
# Global Section
supportKrb5 yes
serverKrbPrinc LDAP/[email protected]
krbLDAPAdmin [email protected]
krbKeytab none
# TDBM Section
krbIdentityMap on
# SDBM Section krbIdentityMap on
5. Start your server. Your LDAP server is now configured with Kerberos support.

Note: The “LDAP” portion of the serverKrbPrinc identity can either be “ldap” or “LDAP” in
the configuration file and in the Kerberos segment of the RACF ID where it is defined.
Check your KDC for case requirements.

324 ABCs of z/OS System Programming Volume 6

6.26 LDAP Kerberos directory schema

New schema files that must be loaded into the LDAP Server to
enable GSSAPI authentication :
MS.ActiveDirectory.ldif and SecurityIdentities.ldif
Attributetypes
krbRealmName-V2
krbPrincSubtree
krbPrincipalName
krbAliasedObjectName
krbHintAliases
altSecurityIdentities
ibm-kn or ibm-kerberosName
Objectclasses
krbRealm-V2
ibm-securityIdentities
krbAlias

Figure 6-26 LDAP Kerberos directory schema

LDAP Kerberos directory schema

To enable Kerberos GSS API Authentication, the directory schema must contain the Kerberos
related schema elements which are defined in schema.user.ldif. Table 6-1 lists the Kerberos
related schema elements.

Table 6-1 Kerberos related schema elements

Attribute Object class Description

krbRealmName-V2 krbRealm-V2 This attribute represents the Kerberos Realms

of which entries in the LDAP server are
members. The entry that contains this attribute
also contains the krbPrincSubtree attribute.

krbPrincSubtree krbRealm-V2 This attribute is in the same entry as the

krbRealmName-V2 attribute and it identifies the
directory subtrees where entries can contain
Kerberos information.

krbPrincipalName (no object class) The attribute is used to define the entry’s
Kerberos identity. This attribute is used for
identity mapping. Currently this attribute is not
associated with an object class. This means that
for an entry to contain this attribute you can add
the object class extensibleObject or define and
add your own object class.

Chapter 6. LDAP 325

 Attribute Object class Description

krbAliasedObjectName krbAlias This attribute allows an entry to be mapped to

another entry’s DN.

krbHintAliases krbAlias This attribute is used as an authorization list. If

another entry’s DN is in this list and that entry
specified this entry as a krbAliasedObjectName
then the mapping is allowed.

altSecurityIdentities ibm-securityIdentities If a user is defined to a case-insensitive

Kerberos server, then the Kerberos identity
associated with this entry is stored as an
altSecurityIdentity rather than a
krbPrincipalName.

ibm-kn (no object class) This attribute is a pseudo-DN so that Kerberos

identities can be represented as DNs for access
control. Currently this attribute is not associated
with an object class. This means that for an entry
to contain this attribute you can add the object
class extensibleObject or define and add your
own object class.

326 ABCs of z/OS System Programming Volume 6

6.27 LDAP Kerberos: Mapping algorithms

Assume Kerberos principal "[email protected]"

Direct mapping in ACL

dn: cn=Scott,o=IBM,c=us
aclEntry: access-id:[email protected]...

SDBM (RACF) Mapping

RACF maps principal@REALM to a RACF userID from
Kerberos information in the USER or KERBLINK profiles.
It then provides an SDBM
distinguished name

racfId=JEFF,profiletype=user,sysplex=plex1

Figure 6-27 LDAP Kerberos: Mapping algorithms

Default mapping
The GSS API bind operation passes a Kerberos identity to the LDAP server which in its initial
form cannot be used for access control in the server. This Kerberos identity known as
<principal>@<REALM> is converted to a DN of the form ibm-kn=<principal>@<REALM>. Now
this Kerberos DN can be used in access control lists.

For example, if you performed a Kerberos bind as [email protected], you are mapped to
[email protected] and this DN is added to a list of DNs that are used for access control
throughout the server. This process is known as the default mapping and is always performed
when a SASL bind with a mechanism of GSS API is performed.

SDBM mapping
If an SDBM back end is configured and the krbIdentityMap configuration is on, then the
SDBM back end tries to map the Kerberos identity to the appropriate RACF ID. If a RACF ID
is found, then the SDBM DN that represents the RACF ID is added to the list of DNs.

Chapter 6. LDAP 327

6.28 LDAP Kerberos: LDBM and TDBM mapping

LDBM and TDBM Mapping

Search the entire database
dn: krbrealmname-V2=IBM.COM,o=Lotus,c=US
for the realm entry. objectclass: krbrealm-V2
krbrealmname-V2: IBM.COM
krbprincsubtree indicates a krbprincsubtree: o=Lotus,c=US
list of subtrees where principals
can be found

Look for an entry in the designated subtrees with

KrbPrincipalName:[email protected] dn: cn=Jeff,o=IBM,c=US
objectclass: extensibleObject
Add the entry's DN to the alternate krbPrincipalName:[email protected]
DN list - Perform group gathering using the list

Use DN cn=jeff,o=IBM,c=US and associated group(s) for ACL

checking

Figure 6-28 LDBM and TDBM mapping

LDBM and TDBM mapping

Another form of mapping is to map the Kerberos identity to LDBM or TDBM DNs. The
following algorithm is used to perform this type of identity mapping if the krbIdentityMap
configuration option is on for this back end:
1. Search the entire TDBM back end for the realm entry that corresponds to the Kerberos
identity by searching for objectclass=krbRealm and krbRealmName-V2=<REALM>, where
<REALM> is the realm portion of the bound Kerberos identity. If the realm is found in the
directory, then all of its krbPrincSubtree values are gathered for use in the next part of this
algorithm.
2. If krbPrincSubtree values exist, then each subtree is searched for the entry or entries that
contain the following attribute, where <principal>@<REALM> is the bound Kerberos identity:
krbPrincipalName = <principal>@<REALM>
3. If an entry or entries are found in the previous step with the correct krbPrincipalName,
their DNs are added to the DN list. If the krbAliasedObjectName attribute exists in the entry
that is found, then more work needs to be done. The entry specified as a
krbAliasedObjectName must allow this entry to use its DN. So, the entry that is specified in
the krbAliasedObjectName must have the DN of the entry in its list of krbHintAliases. If it
does, then the krbAliasedObjectName value is added to the DN list.

328 ABCs of z/OS System Programming Volume 6

4. Finally, the entire database is searched for entries that have an object class
objectclass=ibm-securityIdentities and the following attribute:
altSecurityIdentities = KERBEROS:<principal>@<REALM>
In this command, <principal>@<REALM> is the bound Kerberos identity.

Chapter 6. LDAP 329

6.29 Configuring access control

LDBM and TDBM mapping

krbAliasedObjectName
dn: cn=Jeff,o=Lotus,c=US
objectclass: krbAlias
objectclass: extensibleobject
krbPrincipalName: [email protected]
krbAliasedObjectName: cn=Tim,o=Lotus,c=US

dn: cn=Tim,o=Lotus,c=US
objectClass: krbAlias
krbHintAliases: cn=Jeff,o=Lotus,c=US

Results in cn=jeff,o=Lotus,c=US and cn=Tim,o=Lotus,c=US in

the alternate DN list

altSecurityIdentity
dn: cn=Jeff,o=IBM,c=US
objectclass: ibm-securityIdentities
altSecurityIdentity: KERBEROS:[email protected]

Figure 6-29 Configuring access control

Configuring access control

Because we now have a list of alternate DNs, access control has been changed to operate on
the list of DNs rather than just a single DN. Group gathering is also performed on all of the
DNs in the list. The following examples show how access control can be configured for
Kerberos binds.
1. To set up new ACLs in your directory, use ibm-kn=<principal>@<REALM> for your aclEntry
values, as shown in the following example:
dn: cn=Scott,o=IBM,c=US aclEntry: access-id:[email protected]:normal:r
If [email protected] performed a Kerberos bind to the server, this user is mapped to
[email protected] and gets read access to normal data in the Scott entry.
2. Use existing ACLs (Method 1) for Kerberos identities that are defined to IBM KDCs or
case-sensitive KDCs.
a. Set up and add the realm entry in the database as shown in the following example:
dn: krbRealmName-V2=IBM.COM,o=IBM,c=US
objectclass: krbRealm
krbRealmName-V2: IBM.COM
krbPrincSubtree: o=IBM,c=US
This example states that if a bound Kerberos identity has a realm of IBM.COM, then
identity mapping is performed in the o=IBM,c=US subtree.

330 ABCs of z/OS System Programming Volume 6

 b. Add the krbPrincipalName attribute to your entries as shown in the following example:
dn: cn=Jeff,o=IBM,c=US
objectclass: extensibleObject
krbPrincipalName: [email protected]
In this example, the realm object for [email protected] is found and the o=IBM,c=US
subtree is searched for [email protected]. Because there is no
krbAliasedObjectName attribute in the Jeff entry, only the DN cn=Jeff,o=IBM,c=US is
added to the DN list along with the default mapping of [email protected].
Therefore, if cn=Jeff,o=IBM,c=US was already defined in another entry’s aclEntry, then
[email protected] still has that access to the entry as shown in the following example:
dn: cn=Ken,o=IBM,c=US
aclEntry: access-id:cn=Jeff,o=IBM,c=US:normal:w
In this example, [email protected] still maintains access to the cn=Ken,o=IBM,c=US entry
since TDBM mapping was performed.
c. The krbAliasedObjectName attribute can also be used for identity mapping as shown in
the following example:
dn: cn=Jeff,o=IBM,c=US
objectclass: extensibleObject
objectClass: krbAlias
krbPrincipalName: [email protected]
krbAliasedObjectName: cn=Tim,o=IBM,c=US
In this example, the realm object for [email protected] is found and the o=IBM,c=US
subtree is searched for [email protected]. The search results in
cn=Jeff,o=IBM,c=US being added to the DN list. Because there is a
krbAliasedObjectName attribute in the Jeff entry, we need to look at the Tim entry
before we add cn=Tim,o=IBM,c=US to the DN list. To use Tim’s DN for access control,
the user must authorize Jeff to do so. Tim’s entry must look similar to the following:
dn: cn=Tim,o=IBM,c=US
objectclass: krbAlias
krbHintAliases: cn=Jeff,o=IBM,c=US
Because Tim listed Jeff as a krbHintAliases, the value of krbAliasedObjectName
cn=Tim,o=IBM,c=US can be added to the DN list. If the Tim entry did not contain the
krbHintAliases with Jeff as its value, then Tim’s DN is not added to the DN list.
Therefore, if cn=Tim,o=IBM,c=US was already defined in another entry’s aclEntry then
[email protected] still has that access to the entry. For example:
dn: cn=Kim,o=IBM,c=US
aclEntry: access-id:cn=Tim,o=IBM,c=US:normal:w
In this example, [email protected] maintains write access to the Kim entry because TDBM
mapping was performed and Jeff was aliased to Tim.
3. Use existing ACLs (Method 2). Use this method for case-insensitive KDCs. Set up your
TDBM entries with the altSecurityIdentities attribute.
Example:
dn: cn=Jeff,o=IBM,c=US
objectclass: ibm-securityIdentities
altSecurityIdentity: KERBEROS:[email protected]
Now if [email protected] performs a Kerberos bind, he is mapped to [email protected] as
well as cn=Jeff,o=IBM,c=US.

Chapter 6. LDAP 331

 4. Therefore, if cn=Jeff,o=IBM,c=US is already defined in another entry’s aclEntry, then
[email protected] still has that access to the entry.
For example:
dn: cn=Ken,o=IBM,c=US
aclEntry: access-id:cn=Jeff,o=IBM,c=US:normal:w
In this example, [email protected] still maintains write access to the Ken entry because TDBM
mapping was performed.

332 ABCs of z/OS System Programming Volume 6

6.30 How to set up a Kerberos directory

[email protected] GSSAPI Bind Front End

LDBM TDBM SDBM

o=IBM,c=US o=Lotus,c=US sysplex=plex1

file DB2
DB2 RACF
RACF
file

dn:cn=Jeff,o=Lotus,c=US
dn: cn=Scott,o=IBM,c=US objectClass: krbAlias
aclEntry: objectClass: extensibleObject
[email protected]:normal:rw krbPrincipalName:[email protected]
krbAliasedObjectName:cn=Tim,
o=Lotus,c=US dn:racfId=JEFF,profiletype=user,
sysplex=plex1
KERBNAME:[email protected]
dn: krbRealmName-V2=IBM.COM,
o=Lotus,c=US
dn:cn=Ken,o=IBM,c=US objectClass: krbRealm-V2
aclEntry:cn=Jeff,o=IBM, krbRealmName-V2: IBM.COM
c=us:normal:rw krbPrincSubtree: o=Lotus,c=US

dn: cn=Tim,o=Lotus,c=US
dn:cn=Jeff,o=IBM,c=US objectClass: krbAlias
objectClass:ibm-securityIdentities krbHintAliases:
altSecurityIdentities = cn=Jeff,o=Lotus,c=US
KERBEROS:[email protected]

dn: cn=Shayne,o=Lotus,c=US
aclEntry: cn=Tim,o=Lotus,c=US:normal:w
aclEntry:racfId=JEFF,profiletype=user,
sysplex=plex1:normal:r

Figure 6-30 How to set up a Kerberos directory

How to set up a Kerberos directory

Assume that Kerberos support has been enabled for this server, all back ends have set
krbIdentityMap to on, and the JEFF user ID has performed a kinit to acquire a Kerberos
ticket before issuing the GSS API Kerberos bind.

The user Jeff with a Kerberos identity of [email protected] is performing a Kerberos GSS API
bind to an LDAP server that is configured with an LDBM, a TDBM, and a SDBM back end.

During the bind process, the Kerberos identity [email protected] by default is mapped to
[email protected], and this value is added to the list of DNs that is used for access
control.

After default mapping is performed, each of the back ends attempt to perform identity
mapping:
1. The LDBM back end first looks for the Kerberos realm object with a
krbRealmName-V2=IBM.COM and does not find one. Then, the back end attempts to find the
entry that contains altSecurityIdentities=KERBEROS:[email protected]. The entry with the
DN cn=Jeff,o=IBM,c=US matches this criteria, and the DN is added to the alternate DN
list.
2. Next, the server moves to the TDBM back end and tries to find the Kerberos realm object
with a krbRealmName-V2=IBM.COM. This time, the realm object is found so all of the
krbPrincSubtree values of the realm object are collected. Then, the server searches each
of these subtrees (in this example, only the o=Lotus,c=US subtree) for entries that contain

Chapter 6. LDAP 333

 [email protected]. In this back end, the entry cn=Jeff,o=Lotus,c=US is
found and is added to the DN list.
Next, the Jeff entry is checked for the krbAliasedObjectName attribute. There is a
krbAliasedObjectName specified, so authorization of the alias needs to be performed. The
alias is cn=Tim,o=Lotus,c=US so the Tim entry must be checked for the attribute
krbHintAliases with a value of cn=Jeff,o=Lotus,c=US. This value does exist so the DN
cn=Tim,o=Lotus,c=US is added to the access control DN list.

Note: If the value cn=Jeff,o=Lotus,c=US did not exist in Tim’s krbHintAliases, then
Tim did not want you to alias him. So, the DN cn=Tim,o=Lotus,c=US is not added to the
DN list.

3. Finally, the server gets to the SDBM back end and invokes a RACF API that attempts to
map the Kerberos identity [email protected] to its associated RACF ID. In this example, the
API returns the Jeff user ID, and the DN racfid=JEFF,profiletype=user,sysplex=plex1
is constructed and added to the list of access control DNs.

At this point, the bind has completed and the list of DNs that is used for access control is as
follows:
[email protected]
cn=Jeff,o=IBM,c=Us
cn=Jeff,o=Lotus,c=Us
cn=Tim,o=Lotus,c=US
racfid=JEFF,profiletype=user,sysplex=plex1

Group gathering can now be performed on the entire list of DNs.

Now that [email protected] is bound to the server and the list of alternate DNs has been
generated, Jeff now has authority to perform other operations as follows:
 Because [email protected] was mapped to [email protected], Jeff has read and write
permission to normal data in the cn=Scott,o=IBM,c=US entry.
 The Kerberos identity [email protected] also has read and write permission to the normal data
in the cn=Ken,o=IBM,c=US entry because his identity is also mapped to
cn=Jeff,o=IBM,c=US.
 Modify operations are permitted on the cn=Shayne,o=IBM,c=US entry because
[email protected] is also mapped to cn=Tim,o=Lotus,c=US and Tim has write access to Shayne.
 Read access is also permitted on the cn=Shayne,o=IBM,c=US entry because [email protected]
is mapped to the SDBM DN racfid=JEFF,profiletype=user,sysplex=plex1 who has read
permission to the cn=Shayne,o=IBM,c=US entry.

This example shows that access control is based on the combination of all the mapped DN’s
access control permissions.

334 ABCs of z/OS System Programming Volume 6

6.31 Access control lists

ACLs are a means of protecting our information from

unauthorized access.
ACLs are a means of providing different users, a
different abstraction of the data contained in the
repository, based on their roles or need to know.
Classification of ACLs:
Non-filtered ACLs
Filtered ACLs

Figure 6-31 Access control lists

Access control lists

Access control of information in the LDAP server is specified by setting up access control lists
(ACLs). LDBM, TDBM, and GDBM ACLs provide a means to protect information that is stored
in an LDAP directory. Administrators use ACLs to restrict access to different portions of the
directory, or specific directory entries. LDAP directory entries are related to each other by a
hierarchical tree structure. Each directory entry (or object), contains the entry’s distinguished
name, a set of attributes, and their corresponding values. When using the LDBM, TDBM, or
GDBM back end, ACLs are created and managed using the ldap_add and ldap_modify APIs.
ACLs can also be entered using the ldif2ds and ds2ldif utilities (TDBM load and unload,
and LDBM unload only).

ACLs are represented by a set of attributes that appear to be a part of the entry. The
attributes that are associated with access control, such as entryOwner, ownerPropagate,
aclEntry, and aclPropagate, are unusual in that they are associated logically with each entry
but can have values that depend upon other entries that are higher in the directory hierarchy.
Depending upon how they are established, these attribute values can be explicit to an entry or
can be inherited from an ancestor entry.

Use of LDAP’s SDBM back end allows a user to be authenticated to the directory namespace
using the RACF ID and password. The RACF identity becomes associated with the user’s
RACF-style distinguished name that was used on the LDAP bind operation. It is then possible
to set up ACLs for entries managed by the LDBM, TDBM, or GDBM back end using

Chapter 6. LDAP 335

 RACF-style user and group DNs. This controls access to LDBM, TDBM, or GDBM database
directory entries using the RACF user or group identities.

ACL model
Let us begin with looking at the ACL model. The ACL model is based on two sets of attributes:
 The entryOwner information
 The Access Control Information (ACI)

In conformance with the LDAP model, the ACI and the entryOwner information both are
represented as attribute-value pairs. You use the LDIF syntax to administer these values.

entryOwner information
The entry owners have complete permissions to perform any operation on the object
regardless of the aclEntry. Additionally, the entry owners are the only ones who are permitted
to administer the aclEntries for that object. entryOwner is an access control subject, it can be
defined as individuals, groups or roles. The attributes that define the entry ownership are as
follows:
 entryOwner: Defines an entry owner
 ownerPropagate: Specifies whether the owner set is propagated to the children.

Note: The directory administrator and administration group members are the entry owners
for all objects in the directory by default, and this entry ownership cannot be removed from
any object.

Access control information

The ACI specifies a subject’s (user’s) permission to perform a given operation against a LDAP
object. Do not confuse this with ACL. ACL is basically a cumulative set of the entry owners
and the ACI.

ACI is further split, depending upon the way intended to specify the ACLs. We can specify the
ACLs, whereby we specify a set of rights to the user cn=user1,o=IBM,c=US over the current
object. The descendants also might be impacted depending upon the setting of the
aclPropagate attribute. Such ACLs are known as non-filtered ACLs.

Alternatively, you can also specify the set of rights to the user cn=user1,o=IBM,c=US over a set
of objects conforming to the filter cn=a*, which is a more generalized way of setting ACLs.
Such ACLs are called filtered ACLs. It is as easy as that. Below is the classification in more
detail.

Non-filtered ACLs
This type of ACL applies explicitly to the directory entry that contains them but can be
propagated to none or all of its descendant entries. The default behavior of the non-filtered
ACL is to propagate. The attributes that define non-filtered ACLs are:
 aclEntry: Defines a permission set
aclentry=access-id:CN=USER1,O=IBM,C=US:normal:rsc:normal:deny:w
 aclPropagate: Specifies whether the permission set is propagated to the descendant
entries
aclpropagate=TRUE

336 ABCs of z/OS System Programming Volume 6

Filtered ACLs
Filter based ACLs employ a search, using a specified object filter, such as cn=user* to select
the directory entries to which they apply. The directory entry that contains the filter ACL
serves as the base of the search. The scope of the search is subtree, which includes the
entry that contains the filter, as well as, zero, one, or more of its descendant entries.

Filter-based ACLs do not propagate in the same way that non-filter-based ACLs currently do.
By nature, they inherently propagate to any comparison matched objects in the associated
subtree. For this reason, the aclPropagate attribute, which is used to stop propagation of
non-filter ACLs, does not apply to the new filter-based ACLs.

Filter based ACLs are maintained using the following attributes:

 ibm-filterAclEntry: It is the same form as the aclEntry attribute but has an additional
component called object filter.
 ibm-filterAclInherit: When set to False, it terminates ACL accumulation. Its default value
is True.

Note: The key thing to remember in the case of filtered ACLs is that the filter that you
specify is for the objects that are impacted and not the subject. This filter is often misread
as the set of subjects, rather than objects.

Initializing ACLs with TDBM

The TDBM back end adds an ACL to the suffix entry if no aclEntry value is specified during
the add of this entry (whether the add was done using ldapadd or ldif2tdbm). This improves
performance of future ACL modifications made to an ACL placed on the suffix entry. The ACL
that is used is:
aclEntry: cn=anybody:normal:rsc:system:rsc
aclPropagate: TRUE

Similarly, if no entry owner is specified when the suffix entry is created, entryOwner is added
to the entry with a value set to the administrator DN, along with ownerPropagate TRUE.

Default ACLs with TDBM

Every entry must have an ACL. If there is no ACL explicitly specified in the entry and if no
parent entry is propagating its ACL, then a default ACL is assigned to the entry. The default
ACL is treated differently than a normal aclEntry value. The default value cannot be deleted.
If an aclEntry value is later added to the entry, explicitly or by inheritance, the entire default
aclEntry value is replaced. The LDAP server sets the value of the aclSource attribute to
default when the entry is using the default ACL. The default ACL is:
aclEntry:access-id:CN=ADMIN:normal:rwsc:sensitive:rwsc:critical:rwsc:restricted
:rwsc:system: rwsc
aclEntry: group:CN=ANYBODY:normal:rsc:system:rsc
aclEntry: group:CN=AUTHENTICATED:normal:rsc:system:rsc

Similarly, every entry must have an entry owner. If none is specified or inherited, a default
entryOwner value set to the administrator DN is assigned to the entry. The default value
cannot be deleted. If an entryOwner value is later added to the entry, explicitly or by
inheritance, the entire default entryOwner value is replaced. The LDAP server sets the value
of the ownerSource attribute to default when the entry is using the default owner.

Chapter 6. LDAP 337

 Initializing ACLs with GDBM
When the LDAP sever is started with GDBM configured for the first time, the LDAP server
creates the change log suffix entry, cn=changelog. The suffix entry is created with an
aclEntry and entryOwner value that allows access only to the LDAP administrator and
propagates the aclEntry and entryOwner values. The aclEntry and entryOwner values in the
suffix can be modified, but these attributes cannot be entirely removed from the suffix entry
and they cannot be changed to be non-propagating. In other words, the change log suffix
entry always contains propagating aclEntry and entryOwner values. If desired, different ACL
values can be placed on specific change log entries to override the inherited values from the
change log suffix entry.

338 ABCs of z/OS System Programming Volume 6

6.32 Access evaluation

Rules of ACL evaluation:

The specificity rules
Access-id is more specific than group or role. Groups
and roles are on the same level.
Within the same dnType level, individual attribute level
permissions are more specific than attribute class level
permissions.
Within the same attribute or attribute class level, deny
is more specific than grant.
The combinatory rules
Permissions granted to subjects of equal specificity are
combined.

Figure 6-32 Access evaluation

Access evaluation
Access for a particular operation is granted or denied based on the subject’s bind DN for that
operation on the target object. Processing stops as soon as access can be determined.

The checks for access are done by first determining the entry ownership and then evaluating
the object’s Access Control Information (ACI) values.

Filter-based ACLs accumulate from the lowest containing entry, upward along the ancestor
entry chain, to the highest containing entry in the DIT. The effective access is calculated as
the union of the access rights granted, or denied, by the constituent ancestor entries. The
existing set of specificity and combinatory rules are used to evaluate effective access for filter
based ACLs.

Filter-based and non-filter-based attributes are mutually exclusive within a single containing
directory entry. Placing both types of attributes into the same entry is not allowed, and is a
constraint violation. Operations that are associated with the creation of, or updates to, a
directory entry fail if this condition is detected.

When calculating effective access, the first ACL type to be detected in the ancestor chain of
the target object entry sets the mode of calculation. In filter-based mode, non-filter-based
ACLs are ignored in effective access calculation. Likewise, in non-filter-based mode,
filter-based ACLs are ignored in effective access calculation.

Chapter 6. LDAP 339

 To limit the accumulation of filter-based ACLs in the calculation of effective access, an
ibm-filterAclInherit attribute set to a value of FALSE can be placed in any entry between
the highest and lowest occurrence of ibm-filterAclEntry in a given subtree. This causes the
subset of ibm-filterAclEntry attributes above it in the target object’s ancestor chain to be
ignored. The resulting access resolves to the default filter ACL value.

By default, the directory administrator, administration group members, and the master server
(or peer server for replication, that is, ibm-slapdMasterDN) get full access rights to all objects
in the directory except write access to system attributes. Other entry owners get full access
rights to the objects under their ownership except write access to system attributes. By
default all users have read access rights to normal, system, and restricted attributes. If the
requesting subject has entry ownership, access is determined by the above default settings
and access processing stops.

If the requesting subject is not an entryOwner, then the ACI values for the object entries are
checked. The access rights as defined in the ACLs for the target object are calculated by the
specificity and combinatory rules.
Specificity rule
The most specific aclEntry definitions are ones that are used in the evaluation of permissions
that are granted or denied to a user. The levels of specificity are:
 The access-id is more specific than group or role. Groups and roles are on the same
level.
 Within the same dnType level, individual attribute level permissions are more specific than
attribute class level permissions.
 Within the same attribute or attribute class level, deny is more specific than grant.

For example, if a defined ACI entry contains an access-id subject DN that matches the bind
DN, then the permissions are first evaluated based on that aclEntry. Under the same subject
DN, if matching attribute level permissions are defined, they supersede any permissions
defined under the attribute classes. Under the same attribute or attribute class level definition,
if conflicting permissions are present, denied permissions override granted permissions.

Combinatory rule
Permissions granted to subjects of equal specificity are combined. If the access cannot be
determined within the same specificity level, the access definitions of lesser specific level are
used. If the access is not determined after all defined ACIs are applied, the access is denied.

For example, consider the following two cases of ACIs defined on cn=user1,o=IBM,c=US:
 Case 1:
access-id: cn=this: at.attribute1:grant:rws
access-id: cn=user1,o=IBM,c=US:at.attribute1:grant:rs:at.attribute1:deny:w
In this example, the (w)rite permission on attribute1 is denied to the user
cn=user1,o=IBM,c=US because access cannot be explicitly determined.
 Case 2:
(cn=user1,o=IBM,c=US belongs to group cn=group1)
access-id: cn=this: at.attribute1:grant:rws
access-id: cn=user1,o=IBM,c=US:at.attribute1:grant:rs:at.attribute1:deny:w
group:cn=group1:at.attribute1:grant:w
In this case, after failing to determine access at the specificity level of access-id, the
access definitions of lesser specific levels (group) is determined. Because the group has
write permissions on attribute1, write permission will be granted to cn=user1,o=IBM,c=US.

340 ABCs of z/OS System Programming Volume 6

6.33 Managing ACLs

Example

aclEntry: cn=tim,o=tworld:normal:rwsc:
sensitive:deny:rwsc:at.userpassword:w

give Tim read, write, search, and compare on normal attributes,

deny all access to sensitive attributes, and grant write access only
to the userpassword attribute

Figure 6-33 Managing ACLS

Adding ACIs and entry owners

This example shows how to add an entryOwner(cn=owner,o=IBM,c=US) for a given entry
(cn=person1,o=IBM,c=US). Create an LDIF file (acl.ldif) with the following contents:
dn: cn=person1,o=IBM,c=US
objectclass: person
cn: person1
sn: person1
entryowner: access-id:cn=owner,o=IBM,c=US
ownerPropagate: True

Then, add the this LDIF file using the following syntax:
# ldapadd -D <admin dn> -w <admin password> -f acl.ldif

In a similar manner, you can add a group or role as an entry owner. The example is for an
(access-id) as the entry owner. The other examples that we show in this section follow a
similar method for the additions.

The next example shows how an access ID cn=Person 1, o=IBM,c=US is given permissions
to read, search, and compare the attribute attribute1. The permissions apply to any node in
the entire subtree that is at or below the node containing this ACI, that matches the
(objectclass=groupOfNames) comparison filter. The accumulation of matching
ibm-filterAclEntry attributes in any ancestor nodes has been terminated at this entry by

Chapter 6. LDAP 341

 using our ceiling attribute. That attribute is the ibm-filterAclInherit attribute. It is been set
to FALSE.
dn: cn=person1,o=IBM,c=US
objectclass: person
cn: person1
sn: person1
ibm-filterAclEntry:
access-id:cn=Person1,o=IBM,c=US:(objectclass=groupOfNames):at.attribute1:grant:
rsc
ibm-filterAclInherit: false

The next example shows how a role cn=System Admins,o=IBM,c=US is given permissions to
add objects below the node o=IBM,c=US, and read, search, and compare attribute attribute2
and the (critical) attribute class. The permission applies only to the node containing this
ACI. This is achieved by setting the aclPropagate attribute to FALSE.
dn: o=IBM,c=US
objectlass: organization
o: ibm
aclEntry: role:cn=System
Admins,o=IBM:object:grant:a:at.attribute2:grant:rsc:critical:grant:rsc
aclPropagate: false

Modifying ACI and entryOwner values

Similar to other attributes, you can modify the ACL attributes (except the system attributes)
using ldapmodify using the following general syntax:
dn: some entry
changetype: modify
<action>: <acl-attribute>
<acl-attribute>: <value>

Where:
 action is one of the following values:
– replace: If the attribute value does not exist, create the value. If the attribute value
exists, replace the value.
– add: If the ACI or entryOwner does not exist, the ACI or entryOwner with the specific
values is created. If the ACI or entryOwner exists, then add the specified values to the
given ACI or entryOwner.
– delete: Deletes an ACL entry with a given value.
 acl-attribute is one of entryOwner, ownerPropagate, aclEntry, aclPropagate,
ibm-filterAclEntry, or ibm-filterAclInherit.
 value is the value of the given attribute.

For example, consider any entry cn=person1,o=IBM,c=US with the following ACL definition:
aclentry=access-id:CN=ABC:object:deny:d:object:a
aclentry=access-id:CN=P1,O=IBM,C=US:normal:rwsc:object:a

To remove the ACL entry cn=ABC, the syntax of ldapmodify is as follows:

ldapmodify -D <admindn> -w <adminpw>
dn: ou=person1,o=IBM,c=US
changetype: modify
delete: aclentry

342 ABCs of z/OS System Programming Volume 6

 aclentry: access-id:CN=ABC:object:deny:d:object:a

Note: You can put the four lines after the line of ldapmodify in this example in an LDIF file
and pass the file to ldapmodify using the -f option. Remember that ldapmodify and
ldapadd ultimately function as the same utility.

After the command in the example above, only the second aclEntry remains as follows:
aclentry=access-id:CN=P1,O=IBM,C=US:normal:rwsc:object:a

In this ldapmodify operation, the value of ACL entry to be removed is given as:
ldapmodify -D <admindn> -w <adminpw>
dn: ou=person1,o=IBM,c=US
changetype: modify
delete: aclentry
aclentry: access-id:CN=ABC:object:deny:d

Note: We have not given the object add (object:a) permission in the aclEntry value.

In such a scenario, both the ACL entries remain, but the deny permissions on object delete
(object:deny:d) is removed from the first ACL entry. The value of the delete entry in the ACL
entry is changed from deny to unspecified.

Searching ACI and entryOwner values

Suppose that we have an entry ou=payroll,o=IBM,c=US, and we want to see all the
information that pertains to ACLs for that entry. We use the following commands to
accomplish this task:
E:\>ldapsearch -D <admin dn> -w <admin pw> -b ou=payroll,o=IBM,c=US
objectclass=* aclEntry aclPropagate entryOwner ibm-filterAclEntry
ibm-filterAclInherit ownerPropagate

ou=payroll,o=IBM,c=US
ownerPropagate=TRUE
aclPropagate=FALSE
entryOwner=access-id:CN=ROOT
aclEntry=access-id:CN=USER1,O=IBM,C=US:system:deny:rsc:critical:deny:rwsc:sensi
tive:deny:rwsc:normal:rwsc:restricted:deny:rwsc

cn=accountant,ou=payroll,o=IBM,c=US
ownerPropagate=TRUE
aclPropagate=TRUE
entryOwner=access-id:CN=ROOT
aclEntry=access-id:CN=USER1,O=IBM,C=US:object:ad:normal:r

In this example, two entries are returned with the ACL showing that these are non-filtered
ACLs.

We run the same search against an entry with filtered ACLs as follows:
E:\>ldapsearch -D cn=root -w root -b ou=hr,o=IBM,c=US objectclass=* aclEntry
aclPropagate entryOwner ibm-filterAclEntry ibm-filterAclInherit ownerPropagate
ou=hr,o=IBM,c=US
ownerPropagate=TRUE
ibm-filterAclInherit=TRUE
entryOwner=access-id:CN=ROOT

Chapter 6. LDAP 343

 ibm-filterAclEntry=access-id:CN=USER1,O=IBM,C=US:(uid=*):object:deny:ad:normal:
rwsc

344 ABCs of z/OS System Programming Volume 6

6.34 Running the LDAP server in z/OS

z/OS
IODF
IODF Only in
schema
HCD IIS LDAP
RMF RMF
RMF DDS schema
LDAP client TCP/IP slapd SDBM RACF
LDAP client
stack daemon RACF schema
LDAP V3
Basic auth Only in
LDBM ACL
SSL/TLS HFS zFS ITDS
schema
Kerberos
CRAM-MD5 GDBM
config
Digest-MD5
TDBM ACL
LDAP DB2 schema
client EXOP
USS

OMVS / TSO Applications

ldapsearch
ldapmodify
ldapdelete
ldapmodrdn
ldapcompare

Figure 6-34 Running the LDAP server in z/OS

Setting up the PDSE for the LDAP server DLLs

The LDAP server searches for and loads a number of DLLs during its startup processing. All
DLLs for the LDAP server are shipped in PDSE format only. For these DLLs to be located by
the LDAP server at runtime, the PDS that contains these DLLs (SYS1.SIEALNKE) must
either be in the LINKLIST (the default installation), referenced in a STEPLIB DD card if the
LDAP server is started from JCL, or listed in the STEPLIB environment variable if the LDAP
server is started from the z/OS UNIX System Services command prompt. You can use any of
these methods, and the best method depends upon the way that you will most often be
running the LDAP server. If you put SYS1.SIEALNKE in LINKLIST, STEPLIB is not
necessary.

The LDAP server also depends on the SCEERUN and SCEERUN2 data sets. Add these to
your LINKLIST or, if that is not possible, add it to STEPLIB.

Setting up and running the LDAP server as a started task

To run the LDAP server as a started task, you must define the started task for the LDAP
server and then you can run the LDAP server using JCL.

Defining the started task for the LDAP server

After you create the LDAPSRV user ID, you must define the LDAPSRV started task. The
examples and the sample startup procedure use the name LDAPSRV for this task, but you
can use any name for it.

Chapter 6. LDAP 345

 To define the started task for the user ID you just created, use the following RACF commands.
RDEFINE STARTED DSSRV.** STDATA(USER(LDAPSRV))
SETROPTS RACLIST(STARTED) REFRESH

Running the LDAP server using the sample JCL

The JCL that is needed to run the LDAP server as a started task is provided with the product
as a procedure. This JCL can be found in GLDHLQ.SGLDSAMP on the system where the
LDAP server is installed. If you have a ServerPac installation, GLDHLQ will be GLD. This JCL
procedure can be started in the System Display and Search Facility (SDSF) or from the
operator’s console, after the sample JCL has been placed into the installation-specific library
for procedures. This JCL must be tailored before it can be run.

To start the LDAP server in SDSF, enter:

/s dssrv

To start the LDAP server from the operator’s console, enter:

s dssrv

Running the LDAP server using data sets

The LDAP server, when run as a started task, accepts several of its files as data sets. Data
set versions of the configuration files and envvars file are not shipped with the LDAP server,
but can be created using the OGET command to copy the HFS versions of the files into data
sets.

The default data set characteristics for record format and record length (V 255) which OGET
will use when creating a new data set are not acceptable for JCL when submitting for batch
processing. In order to avoid this, allocate the MYUSER.DSNTIJCL sequential data set to be
fixed block 80 prior to performing the OGET operation.

A data set version of the DSNAOINI file needed for the TDBM back end can be created by
copying and editing the default file provided by DB2. The DSNAOINI file can be specified
either in the configuration file or in a DSNAOINI DD statement, or a DSNAOINI environment
variable can be used. The DD statement takes precedence.

Note: Be sure to turn off the use of sequence numbers when editing this data set.

When the data set versions of these files are available, they can be specified in the LDAPSRV
procedure. The configuration file can be specified using the CONFIG DD statement, the
envvars file can be specified using the ENVVAR DD statement, and the DSNAOINI file can be
specified using the DSNAOINI DD statement.

Note: Using the LDAP configuration utility (ldapcnf or dsconfig) to configure your server
creates all the necessary files in a partitioned data set.

Verifying the LDAP server

Note: You can use any LDAP client to verify the LDAP server.

The following examples show how to verify the LDAP server using the ldapsearch tool:
 Verifying LDBM and TDBM

346 ABCs of z/OS System Programming Volume 6

 In this example, substitute the suffix value from your configuration file for the -b parameter.
You can run the command multiple times to verify that each suffix is defined in the
configuration file.
ldapsearch -h 127.0.0.1 -s base -b "o=Your Company" "objectclass=*"
The LDAP search returns the message No such object if the suffix entries are not loaded
into the directory.
 Verifying SDBM
For SDBM, you must bind with a valid RACF-style DN to perform the search. Substitute a
RACF ID of your choice in the racfid portion of the DN on the -D and the -b parameters in
this example. Also, substitute your SDBM suffix in the DN on the -D and -b parameters.
The RACF password for the user ID used in the -D parameter must be specified in the -w
parameter.
ldapsearch -h 127.0.0.1 -D racfid=IBMUSER,profiletype=user,cn=myRacf
-w password_for_IBMUSER -b racfid=IBMUSER,profiletype=user,cn=myRacf
"objectclass=*"
 Verifying GDBM
For GDBM, you must bind with the LDAP administrator DN or another DN authorized to
search the change log as follows:
ldapsearch -h 127.0.0.1 -D bindDn -w bindPw -s base -b cn=changelog
"objectclass=*"

The previous ldapsearch examples assume a default port of 389. If your port is not 389, use
the -p parameter to specify the correct port.

Be sure to substitute the correct TCP/IP host name or TCP/IP address for the 127.0.0.1 after
the -h parameter. The -b parameter specifies the starting point for the search. The use of the
quotation marks around the filter prevents the asterisk (*) from being interpreted by the shell.

Note that you can verify the LDAP server from TSO as well by substituting LDAPSRCH for
ldapsearch.

Chapter 6. LDAP 347

6.35 Referrals and replication

Example using referrals and replication

LDAP Server

o=ibm, c=us

LDAP Server LDAP Server

(master) (slave)
replication

ou=pok, ou=end, ou=pok, ou=end,

o=ibm, c=us o=ibm, c=us o=ibm, c=us o=ibm, c=us

Figure 6-35 Referrals and replication

Replication
After the z/OS LDAP server is installed and configured, users can access the directory, add
objects, delete objects, or perform search operations to retrieve particular sets of information.

Replication is a process that keeps multiple databases in synchronization. Through

replication, a change made to one database is propagated to one or more additional
databases. In effect, a change to one database shows up on multiple different databases.

There are several benefits realized through replication. The single greatest benefit is
providing a means of faster searches. Instead of having all search requests directed at a
single server, the search requests can be spread among several different servers. This
improves the response time for the request completion.

Additionally, the replica provides a backup to the replicating server. Even if the replicating
server crashes, or is unreadable, the replica still fulfills search requests and provides access
to the data.

348 ABCs of z/OS System Programming Volume 6

There are two types of replication:
 In peer-to-peer replication, each LDAP peer server is a read-write server. Updates
processed on one peer server are replicated to all the other peer servers. Peer servers are
read-write to all users.
 In read-only replication, a single read-write LDAP server (the master) replicates the
updates it processes to a set of read-only replica servers.
– Master: All changes to the database are made to the master server. The master server
is then responsible for propagating the changes to all other databases. It is important to
note that while there can be multiple databases representing the same information,
only one of those databases can be the master.
– Read-only replica: Each of the additional servers which contain a database replica.
These replica databases are identical to the master database. These servers are
read-only to all users and will only accept updates from their master server.

Note: The z/OS support for peer-to-peer replication is provided for failover support
purposes. There is no support for resolving conflicting simultaneous updates on multiple
peer servers, which can cause a failure of replication. As a result, you need to target
updates to one peer server at a time.

A replication network can contain both peer replica servers and read-only replica servers. In
this case, each peer server must act as a master to each read-only replica (in addition to
being a peer to all the peer servers), so that updates that occur on any peer server are
replicated to all the other peer and read-only replicas in the network.

Replication is only supported when the servers involved are running in single-server mode.
Although replication is not supported when operating multiple concurrent server instances
against the same database (multi-server operating mode), similar benefits are afforded when
operating in this mode.

Replicating server
For the replication process to occur, the following tasks must happen:
 The replicating server (master or peer) must be aware of each replica that is to receive the
change information.
 Each read-only replica must be aware of the replicating server for the database that it
serves.

The replicating server becomes aware of the existence of the replica servers when objects
(entries) of type replicaObject are added to the directory. Each of these objects represents a
particular replica server. The attribute/value pairs within the replica object provide the
information the replicating server needs in order to find the replica server and send any
updates to that server.

Note: The replicaObject object class is provided in the system schema file
schema.user.ldif.

Adding replica objects in TDBM

In TDBM, replica objects can be placed anywhere within the directory tree. This also implies
that the suffix cn=localhost can be removed from the LDAP server configuration file. Placing
replica objects in the directory tree then requires that any parent entries of the replicaObject
entry is added to the directory prior to adding the replicaObject entry. These entries must be
added to both the replicating server and replica server before addition of the replicaObject.

Chapter 6. LDAP 349

 This is needed on the replica server because these entries are being added at the replicating
server without replication being active. If a replica object is not placed as a leaf node in the
directory tree, the only entries allowed below the replica object are other replica objects. The
LDAP server will allow non-replica entries to be placed below replica entries; however, these
entries will not be replicated to the replica servers. The following example shows a replica
object definition using LDIF format:
dn: cn=myReplica,o=YourCompany
objectclass: replicaObject
cn: myReplica
replicaHost: myMachine.ibm.com
replicaBindDn: cn=Master
replicaCredentials: secret
replicaPort: 400
replicaUseSSL: FALSE
description: "Replica machine in the fourth floor lab"

Replica server
Initialization, or population, of a replica database requires several steps.

Special Note: If the replicating server is configured with TDBM, changes to the schema
entry on the replicating server are not replicated. The schema on the replica must be
modified by a user bound as the masterServerDN or peerServerDN. A separate update of
the replica schema is required each time the schema is updated on the replicating server.

If you are modifying the schema on a TDBM read-only replica and are not bound as the
masterServerDN, the masterServer configuration option causes the modification to be
redirected to the replicating server, which causes the schema on the replica and replicating
servers to be out of synchronization. No error message occurs.

To populate a replica, follow these steps:

1. Stop the LDAP replicating server.
2. Unload the replicating server’s directory contents if there are any entries. For TDBM, use
the tdbm2ldif utility.
3. Make sure the schema for the replica server is the same as the schema for the replicating
server. If the replica and replicating server are both z/OS servers configured with TDBM,
the schema can be unloaded from the replicating server using tdbm2ldif and reloaded
into the replica using either the ldif2tdbm -s option or ldapmodify with the replica server
started.
4. Run a load utility with a single added directory entry which defines a replicaObject entry
into the replicating server’s directory contents. For TDBM, use either the ldif2tdbm utility
or ldapadd with the replicating server running.

Note: To load the replicaObject entry, you must also load any parent entries in the
directory hierarchy in hierarchy order.

5. If the replicating server does not contain any entries, no further action must be taken to
ensure that the replica and replicating server are in synchronization and the replicating
server can now be restarted; otherwise, continue to the next step.
6. Transport the LDIF file created in step 2 to the replica server’s location.
7. Run a load utility on the replica server using the LDIF file from step 6. For TDBM, stop the
replica server if it is running and use ldif2tdbm.

350 ABCs of z/OS System Programming Volume 6

8. Configure the replica.
9. Start the replica server. If this is a peer server, ensure that it does not contain a replica
object that defines this server as a replica of itself.
10.Start the replicating server.

Configuring the replica

The key to a successful replica configuration rests in ensuring that the values in the
replicaObject on the replicating server (master or peer) accurately represent the relevant
values on the replica server (read-only or peer). Configuring the replica involves specifying
appropriate configuration file option values to identify:
 The IP address and port on which the replica server should listen for communication from
the replicating server.
 The type of connection expected by the replicating server when it communicates to the
replica server, either over a non-secure or secure connection.
 The DN and password used by the replicating server.

Note: The ldif2tdbm utility does not replicate changes when adding entries to the
replicating server. So, if you are using ldif2tdbm to add entries to a replicating server you
must also use it to add entries to each replica, with no intervening updates on the
replicating server before the replica is loaded.

Referrals
Referrals provide a way for servers to refer clients to additional directory servers. With
referrals you can:
 Distribute namespace information among multiple servers
 Provide knowledge of where data resides within a set of interrelated servers
 Route client requests to the appropriate server

Following are some of the advantages of using referrals:

 Distribute processing overhead, providing primitive load balancing
 Distribute administration of data along organizational boundaries
 Provide potential for widespread interconnection, beyond an organization’s own
boundaries.

In z/OS LDAP, referral entries are only supported in the TDBM (DB2-based) back end. The
default referral can be used with any type of back end.

Using the referral object class and the ref attribute

The referral object class and the ref attribute are used to facilitate distributed name resolution
or to search across multiple servers. The ref attribute appears in an entry named in the
referencing server. The value of the ref attribute points to the corresponding entry maintained
in the referenced server. While the distinguished name (DN) in a value of the ref attribute is
typically that of an entry in a naming context below the naming context held by the referencing
server, it is permitted to be the distinguished name of any entry. A multi-valued ref attribute
can be used to indicate different locations for the same resource. If the ref attribute is
multi-valued, all the DNs in the values of the ref attribute should have the same value.

Chapter 6. LDAP 351

 The recommended setup of referrals is to structure the servers into a hierarchy based on the
subtrees they manage. Then, provide “forward” referrals from servers that hold higher
information and set the default referral to point back to its parent server.

Associating servers with referrals

To associate servers through referrals:
 Use referral objects to point to other servers for subordinate references.
 Define the default referral to point somewhere else, typically to the parent server.

Pointing to other servers

You can use referral objects to point to the other servers for subordinate references (that is,
portions of the namespace below this server that the server does not service directly).
Referral objects, similar to other objects, go in the TDBM back end. Table 6-2 lists referral
objects.

Table 6-2 Referral objects

Objects Specification

dn Specifies the distinguished name. It is the portion of the namespace served by the
referenced server.

objectclass Specifies referral. For entries in TDBM, also include the object class
extensibleObject.

ref Specifies the LDAP URL of the server. This URL should consist of the ldap:// or
ldaps:// identifier, the hostname:port, and a DN. The DN requires a slash (/) before
it to delimit it from the hostname:port, and should match the DN of the referral
object. The ref attribute can be multi-valued, with each value specifying the LDAP
URL of a different server. When multiple values are used, each LDAP URL should
contain the same DN, and each server should hold equivalent information for the
portion of the namespace represented by the DN.

Example 6-5 shows a sample definition of a referral object.

Example 6-5 Sample referral object

dn: o=IBM,c=US
objectclass: referral
objectclass: extensibleObject
ref: ldap://Host1:389/o=IBM,c=US
ref: ldap://Host2:389/o=IBM,c=US
ref: ldap://Host3:1389/o=IBM,c=US

The server can have any number of referral objects within its database. However, the objects
must essentially be descendents of its suffix.

Defining the default referral

Define the default referral to point to another server which services other portions of the
namespace unknown to the referencing server. The default referral can be used to point to:
 The immediate parent of this server (in a hierarchy)
 A “more knowledgeable” server, such as the uppermost server in the hierarchy
 A “more knowledgeable” server which possibly serves a disjoint portion of the namespace

352 ABCs of z/OS System Programming Volume 6

The default referral goes in the configuration file and not the back end. The default referral is
described in the configuration file with the referral keyword and an LDAP URL. Multiple default
referrals can be specified. However, each one specified is considered equivalent; that is, each
server referenced by a default referral should present the same view of the namespace to its
clients.

The default referral LDAP URL does not include the DN portion. It needs just the ldap://
identifier and the hostname:port. For example:
referral ldap://host3.ibm.com:999

SSL/TLS note: A non-secure client referral to a secure port is not supported. Also, a
secure client referral to a non-secure port is not supported.

Chapter 6. LDAP 353

6.36 LDAP change logging

LDBM

Update TDBM

SDBM User, Group, RACF DB

Connections

Change log
entries added

GDBM
Changelog

LDAP Server
Figure 6-36 LDAP change logging

LDAP change logging

The change log is a set of entries in the directory that contain information about changes to
objects. Depending on configuration options, information about a change to a TDBM or LDBM
entry, to the LDAP server schema entry (cn=schema), or to an object controlled by an
application (for example, a RACF user, group, or user-group connection profile) can be saved
in a change log entry.

You can use an LDAP search operation to retrieve change log entries to obtain information
about what changes have taken place. Each LDAP server contains one change log. The
change log entries are created in the same order as the changes are made and each change
log entry is identified by a change number value, beginning with 1, that is incremented each
time a change number is assigned to a change log entry. Therefore, the change number of a
new change log entry is always greater than all the change numbers in the existing change
log entries.

The change log is implemented in the GDBM back end. The change log uses a hard-coded
suffix, cn=changelog. This suffix is a semi-reserved name. When the GDBM back end is
configured, the change log root (cn=changelog) must not overlap any suffix in any TDBM,
SDBM, or LDBM back end, and the change log suffix cannot be the source or target of a
rename operation. If GDBM is not configured, the user can use cn=changelog as a normal
suffix in a TDBM, SDBM, or LDBM back end. However, we do not recommend this method
because you will have to rename that suffix to avoid an overlap if GDBM is configured in the

354 ABCs of z/OS System Programming Volume 6

future. Change logging is enabled by configuring GDBM in the LDAP server configuration file.
Change log processing is controlled by configuration options in the GDBM back end.

The changeLoggingParticipant configuration option can be used to specify if an LDBM or

TDBM back end wants change log entries to be created for changes to entries in the LDBM or
TDBM back end. Similarly, the configuration option can be specified in the GDBM back end to
determine if a change log entry should be created for a change to the LDAP server schema. If
the option is not specified for a TDBM, LDBM, or GDBM back end, the default is to create
change log entries for changes to that TDBM or LDBM back end or to the LDAP server
schema. If the GDBM back end is configured and the cn=changelog root entry does not exist
in the GDBM back end when the server is started, the LDAP server generates the root entry.
The root entry is created with an ACL that allows only the administrator to access the change
log. The ACL is propagated to the change log entries. The user needs to use an LDAP modify
operation to change this ACL to an appropriate ACL for his usage of the change log.

Configuring the GDBM back end

You can use the LDAP configuration utility, dsconfig, to configure GDBM.

The GDBM back end is configured in one of two ways: DB2-based (such as TDBM) or
file-based (such as LDBM). In either configuration:
1. There can be at most one GDBM back end in the configuration file.
2. The suffix option cannot be specified in the GDBM back end.
3. If the changeLoggingParticipant option is specified, it controls whether a change log entry
is created for a change to the LDAP server schema. Change log entries are never created
for any changes to GDBM entries, including the suffix entry.

Configuring a DB2-based GDBM back end

When using DB2 to store its entries, the GDBM database is identical to a TDBM database
and is created in the same way using the same SPUFI script. A DB2-based GDBM back end
cannot share a database with a TDBM back end. Similar to TDBM, a DB2-based GDBM back
end cannot run in 64-bit mode.

Configuring a file-based GDBM back end

When using files to store its entries, the GDBM database is identical to an LDBM database
and is created in the same way. Similar to LDBM, a file-based GDBM back end can run in
64-bit mode.

Additional required configuration

Additional configuration is required for RACF to be able to log changes to a RACF user,
group, or connection:
 The SDBM back end must be configured. The SDBM suffix is needed to create a DN for
the change log entry for a modification to a RACF user, group, or connection. SDBM is
also needed to retrieve the RACF user’s new password or other changed fields.
 Program Callable support must be enabled in the LDAP server containing the change log.
To do this, add the following option to either the global section of the configuration file or
use the following command used to start the LDAP server:
listen ldap://:pc

Chapter 6. LDAP 355

356 ABCs of z/OS System Programming Volume 6
 7

Chapter 7. EIM
This chapter examines the Enterprise Identity Mapping (EIM) concept and its implementation
on z/OS.

© Copyright IBM Corp. 2008. All rights reserved. 357

7.1 Overview of EIM

Windows 2000/NT
NetServer

iSeries
WebSphere NDS

LINUX

John Smith's users: For example, back-end

access is done using a
u:John Smith p:mydog6 single OS user, unaware
u:JSimth p:SE50852 of the end user's
u:John p:just4u authority.
u:Smith1 p:jonny
u:JoSm05 p:eyKd64dv
etc.. intranet
User
AIX RACF z/OS

Figure 7-1 Overview of EIM

Overview of EIM
Today’s network environments are made up of a complex group of systems and applications,
resulting in the need to manage multiple user registries. Dealing with multiple user registries
quickly grows into a large administrative problem that affects users, administrators, and
application developers. Consequently, many companies are struggling to securely manage
authentication and authorization for systems and applications. Enterprise Identity Mapping
(EIM) is an IBM eServer infrastructure technology that allows administrators and application
developers to address this problem more easily and inexpensively than previously possible.

EIM offers a new approach to enable inexpensive solutions to easily manage multiple user
registries and user identities in an enterprise. EIM is an architecture for describing the
relationships between individuals or entities (such as file servers and print servers) in the
enterprise and the many identities that represent them within an enterprise. In addition, EIM
provides a set of APIs that allow applications to ask questions about these relationships.

For example, given a person’s user identity in one user registry, you can determine which user
identity in another user registry represents that same person. If the user has authenticated
with one user identity and you can map that user identity to the appropriate identity in another
user registry, the user does not need to provide credentials for authentication again. You know
who the user is and only need to know which user identity represents that user in another
user registry. Therefore, EIM provides a generalized identity mapping function for the
enterprise.

358 ABCs of z/OS System Programming Volume 6

EIM allows one-to-many mappings (in other words, a single user with more than one user
identity in a single user registry). However, the administrator does not need to have specific
individual mappings for all user identities in a user registry. EIM also allows many-to-one
mappings (in other words, multiple users mapped to a single user identity in a single user
registry).

The ability to map between a user’s identities in different user registries provides many
benefits. Primarily, it means that applications may have the flexibility of using one user
registry for authentication while using an entirely different user registry for authorization. For
example, an administrator could map an SAP® identity (or better yet, SAP could do the
mapping itself) to access SAP resources.

The use of identity mapping requires that administrators do the following:

1. Create EIM identifiers that represent people or entities in their enterprise.
2. Create EIM registry definitions that describe the existing user registries in their enterprise.
3. Define the relationship between the user identities in those registries to the EIM identifiers
that they created.
4. Create policy associations.

No code changes are required to existing user registries. The administrator does not need to
have mappings for all identities in a user registry. EIM allows one-to-many mappings (in other
words, a single user with more than one user identity in a single user registry). EIM also
allows many-to-one mappings (in other words, multiple users sharing a single user identity in
a single user registry, which although supported is not advised). An administrator can
represent any user registry of any type in EIM.

EIM is an open architecture that administrators may use to represent identity mapping
relationships for any registry. It does not require copying existing data to a new repository and
trying to keep both copies synchronized. The only new data that EIM introduces is the
relationship information. Administrators manage this data in an LDAP directory, which
provides the flexibility of managing the data in one place and having replicas wherever the
information is used. Ultimately, EIM gives enterprises and application developers the flexibility
to easily work in a wider range of environments with less cost than would be possible without
this support.

Chapter 7. EIM 359

7.2 EIM concepts

Figure 7-2 EIM concepts

EIM concepts
A conceptual understanding of how EIM works is necessary to fully understand how you can
use EIM in your enterprise. Although the configuration and implementation of EIM APIs can
differ among server platforms, EIM concepts are common across IBM eserver servers.

Figure 7-2 provides an EIM implementation example in an enterprise. Three servers act as
EIM clients and contain EIM-enabled applications that request EIM data using lookup
operations. The domain controller stores information about the EIM domain, which includes
an EIM identifier, associations between these EIM identifiers and user identities, and EIM
registry definitions.

EIM domain controller

The EIM domain controller is a Lightweight Directory Access Protocol (LDAP) server that is
configured to manage at least one EIM domain. An EIM domain is an LDAP directory that
consists of all the EIM identifiers, EIM associations, and user registries that are defined in that
domain. Systems (EIM clients) participate in the EIM domain by using the domain data for
EIM lookup operations. A minimum of one EIM domain controller must exist in the enterprise.

Currently, you can configure a number of IBM platforms to act as an EIM domain controller.
Any system that supports the EIM APIs can participate as a client in the domain. These client
systems use EIM APIs to contact an EIM domain controller to perform EIM lookup operations.

The location of the EIM client determines whether the EIM domain controller is a local or
remote system. The domain controller is local if the EIM client is running on the same system

360 ABCs of z/OS System Programming Volume 6

as the domain controller. The domain controller is remote if the EIM client is running on a
separate system from the domain controller.

EIM domain
An EIM domain is a directory within an LDAP server that contains EIM data for an enterprise.
An EIM domain is the collection of all the EIM identifiers, EIM associations, and user
registries that are defined in that domain. Systems (EIM clients) participate in the domain by
using the domain data for EIM lookup operations.

An EIM domain is different from a user registry. A user registry defines a set of user identities
known to and trusted by a particular instance of an operating system or application. A user
registry also contains the information needed to authenticate the user of the identity.
Additionally, a user registry often contains other attributes such as user preferences, system
privileges, or personal information for that identity.

In contrast, an EIM domain refers to user identities that are defined in user registries. An EIM
domain contains information about the relationship between identities in various user
registries (user name, registry type, and registry instance) and the actual people or entities
that these identities represent. Because EIM tracks relationship information only, there is
nothing to synchronize between user registries and EIM.

The right side of Figure 7-2 on page 360, shows the data that is stored within an EIM domain.
This data includes EIM identifiers, EIM registry definitions, and EIM associations. EIM data
defines the relationship between user identities and the people or entities that these identities
represent in an enterprise.

EIM data includes:

 EIM identifier: Each EIM identifier that you create represents a person or entity (such as a
print server or a file server) within an enterprise.
 EIM registry definition: Each EIM registry definition that you create represents an actual
user registry (and the user identity information it contains) that exists on a system within
the enterprise. After you define a specific user registry in EIM, that user registry can
participate in the EIM domain. You can create two types of registry definitions, one type
refers to system user registries and the other type refers to application user registries.
 EIM association: Each EIM association that you create represents the relationship
between an EIM identifier and an associated identity within an enterprise. You must define
associations so that EIM clients can use EIM APIs to perform successful EIM lookup
operations. These EIM lookup operations search an EIM domain for defined associations
between EIM identifiers and user identities in recognized user registries. Associations
provide the information that ties an EIM identifier to a specific user identity in a specific
user registry.
You can create two different types of associations:
– Identifier associations: Identifier associations allow you to define a one-to-one
relationship between user identities through an EIM identifier defined for an individual.
Each EIM identifier association that you create represents a single, specific
relationship between an EIM identifier and an associated user identity within an
enterprise.
Identifier associations provide the information that ties an EIM identifier to a specific
user identity in a specific user registry and allow you to create one-to-one identity
mapping for a user. Identity associations are especially useful when individuals have
user identities with special authorities and other privileges that you want to specifically
control by creating one-to-one mappings between their user identities.

Chapter 7. EIM 361

 – Policy associations: Policy associations allow you to define a relationship between a
group of user identities in one or more user registries and an individual user identity in
another user registry. Each EIM policy association that you create results in a
many-to-one mapping between the source group of user identities in one user registry
and a single target user identity. Typically, you create policy associations to map a
group of users who all require the same level of authorization to a single user identity
with that level of authorization.

After you create your EIM identifiers, registry definitions, and associations, you can begin
using EIM to more easily organize and work with user identities within your enterprise.

EIM identifier
An EIM identifier represents a person or entity in an enterprise. A typical network consists of
various hardware platforms and applications and their associated user registries. Most
platforms and many applications use platform-specific or application-specific user registries.
These user registries contain all of the user identification information for users who work with
those servers or applications.

When you create an EIM identifier and associate it with the various user identities for a
person or entity, it becomes easier to build heterogeneous, multiple-tier applications (for
example, a single sign-on environment). When you create an EIM identifier and associations,
it also becomes easier to build and use tools that simplify the administration involved with
managing every user identity that a person or entity has within the enterprise.

EIM registry definition

An EIM registry definition represents an actual user registry that exists on a system within the
enterprise. A user registry operates such as a directory and contains a list of valid user
identities for a particular system or application. A basic user registry contains user identities
and their passwords. One example of a user registry is the z/OS Security Server RACF
registry. User registries can contain other information as well. For example, an LDAP directory
contains bind distinguished names, passwords, and access controls to data that is stored in
LDAP. Other examples of common user registries are a Kerberos key distribution center
(KDC) and the OS/400® user profiles registry.

You can also define user registries that exist within other user registries. Some applications
use a subset of user identities within a single instance of a user registry. For example, the
z/OS Security Server RACF registry can contain specific user registries that are a subset of
users within the overall RACF user registry. To model this behavior, EIM allows administrators
to create two kinds of EIM registry definitions:
 System registry definitions
 Application registry definitions

EIM registry definitions provide information regarding those user registries in an enterprise.
The administrator defines these registries to EIM by providing the following information:
 A unique, arbitrary EIM registry name
 The type of user registry

Each registry definition represents a specific instance of a user registry. Consequently, you
need to choose an EIM registry definition name that helps you to identify the particular
instance of the user registry. For example, you could choose the TCP/IP host name for a
system user registry, or the host name combined with the name of the application for an
application user registry. You can use any combination of alphanumeric characters, mixed
case, and spaces to create unique EIM registry definition names.

362 ABCs of z/OS System Programming Volume 6

There are a number of predefined user registry types that EIM provides to cover most
operating system user registries, including:
 AIX®
 Domino - long name
 Domino - short name
 Kerberos
 Kerberos - case sensitive
 LDAP
 Linux
 Policy director
 Novell® Directory Server
 OS/400
 Tivoli Access Manager
 RACF
 Windows - local
 Windows domain (Kerberos)
 X.509

Note: Although the predefined registry definition types cover most operating system user
registries, you may need to create a registry definition for which EIM does not include a
predefined registry type. You have two options in this situation. You can either use an
existing registry definition which matches the characteristics of your user registry or you
can define a private user registry type.

For example in Figure 7-3 on page 364, the administrator followed the process required
and defined the type of registry as WebSphere® Third-Party Authentication (LTPA) for the
System_A_WAS application registry definition.

In Figure 7-3 on page 364, the administrator creates EIM registry definitions for user
registries representing System A, System B, and System C and a Windows Active Directory®
that contains users’ Kerberos principals with which users log into their desk top workstations.
In addition, the administrator created an application registry definition for WebSphere
Lightweight Third-Party Authentication (LTPA), which runs on System A.

The registry definition name that the administrator uses helps to identify the specific
occurrence of the type of user registry. For example, an IP address or host name is often
sufficient for many types of user registries. In this example, the administrator identifies the
specific user registry instance by using System_A_WAS as the registry definition name to
identify this specific instance of the WebSphere LTPA application. In addition to the name, the
administrator also provides the type of registry as System_A.

Chapter 7. EIM 363

 Figure 7-3 EIM registry definitions

You can also define user registries that exist within other user registries. For example, the
z/OS Security Server RACF registry can contain specific user registries that are a subset of
users within the overall RACF user registry.

EIM associations
An EIM association is an entry that you create in an EIM domain to define a relationship
between user identities in different user registries. The type of association that you create
determines whether the defined relationship is direct or indirect. You can create one of two
types of associations in EIM: identifier associations and policy associations. You can use
policy associations instead of, or in combination with, identifier associations. How you use
associations depends on your overall EIM implementation plan.

EIM lookup operation

An application or an operating system uses an EIM API to perform a lookup operation so that
the application or operating system can map from one user identity in one registry to another
user identity in another registry. An EIM lookup operation is a process through which an
application or operating system finds an unknown associated user identity in a specific target
registry by supplying some known and trusted information. Applications that use EIM APIs
can perform these EIM lookup operations on information only if that information is stored in
the EIM domain. An application can perform one of two types of EIM lookup operations based
on the type of information the application supplies as the source of the EIM lookup operation:
a user identity or an EIM identifier.

When applications or operating systems use the eimGetTargetFromSource API to obtain a

target user identity for a given target registry, they must supply a user identity as the source of
the lookup operation. To be used as the source in a EIM lookup operation, a user identity
must have either an identifier source association defined for it or be covered by a policy
association.

364 ABCs of z/OS System Programming Volume 6

When an application or operating system uses this API, the application or operating system
must supply these pieces of information:
 A user identity as the source or starting point of the operation.
 The EIM registry definition name for the source user identity.
 The EIM registry definition name that is the target of the EIM lookup operation. This
registry definition describes the user registry that contains the user identity that the
application is seeking.

When applications or operating systems use the eimGetTargetFromIdentifier API to obtain

a user identity for a given target registry, they must supply an EIM identifier as the source of
the EIM lookup operation. When an application uses this API, the application must supply the
following pieces of information:
 A user identity as the source, or starting point of the operation.
 The EIM registry definition name that is the target of the EIM lookup operation. This
registry definition describes the user registry that contains the user identity that the
application is seeking.

For a user identity to be returned as the target of either type of EIM lookup operation, the user
identity must have a target association defined for it. This target association can be in the
form of an identifier association or a policy association.

The supplied information is passed to EIM and the lookup operation searches for and returns
any target user identities, by searching EIM data in the following order:
1. Identifier target association for an EIM identifier. The EIM identifier is identified in one of
two ways: It is supplied by the eimGetTargetFromIdentifier API. Alternatively, the EIM
identifier is determined from information supplied by the eimGetTargetFromSource API.
2. Certificate filter policy association.
3. Default registry policy association.
4. Default domain policy association.

Chapter 7. EIM 365

 Figure 7-4 EIM lookup operation

The lookup operation, illustrated in Figure 7-4, searches flows in this manner:
1. The lookup operation checks whether mapping lookups are enabled. The lookup operation
determines whether mapping lookups are enabled for the specified source registry, the
specified target registry, or both specified registries. If mapping lookups are not enabled
for one or both of the registries, then the lookup operation ends without returning a target
user identity
2. The lookup operation checks whether there are identifier associations that match the
lookup criteria. If an EIM identifier was provided, the lookup operation uses the specified
EIM identifier name. Otherwise, the lookup operation checks whether there is a specific
identifier source association that matches the supplied source user identity and source
registry. If there is one, the lookup operation uses it to determine the appropriate EIM
identifier name. The lookup operation then uses the EIM identifier name to search for an
identifier target association for the EIM identifier that matches the specified target EIM
registry definition name. If there is an identifier target association that matches, the lookup
operation returns the target user identity defined in the target association
3. The lookup operation checks whether the use of policy associations are enabled. The
lookup operation checks whether the domain is enabled to allow mapping lookups using
policy associations. The lookup operation also checks whether the target registry is
enabled to use policy associations. If the domain is not enabled for policy associations or

366 ABCs of z/OS System Programming Volume 6

 the registry is not enabled for policy associations, then the lookup operation ends without
returning a target user identity.
4. The lookup operation checks for certificate filter policy associations. The lookup operation
checks whether the source registry is an X.509 registry type. If it is an X.509 registry type,
the lookup operation checks whether there is a certificate filter policy association that
matches the source and target registry definition names. The lookup operation checks
whether there are certificates in the source X.509 registry that satisfy the criteria specified
in the certificate filter policy association. If there is a matching policy association and there
are certificates that satisfy the certificate filter criteria, the lookup operation returns the
appropriate target user identity for that policy association.
5. The lookup operation checks for default registry policy associations. The lookup operation
checks whether there is a default registry policy association that matches the source and
target registry definition names. If there is a matching policy association, the lookup
operation returns the appropriate target user identity for that policy association.
6. The lookup operation checks for default domain policy associations. The lookup operation
checks whether there is a default domain policy association defined for the target registry
definition. If there is a matching policy association, the lookup operation returns the
associated target user identity for that policy association.
7. The lookup operation is unable to return any results.

When an application supplies a user identity as the source, the application also must supply
the EIM registry definition name for the source user identity and the EIM registry definition
name that is the target of the EIM lookup operation. To be used as the source in a EIM lookup
operation, a user identity must have a source association defined for it.

When an application supplies an EIM identifier as the source of the EIM lookup operation, the
application must also supply the EIM registry definition name that is the target of the EIM
lookup operation. For a user identity to be returned as the target of either type of EIM lookup
operation, the user identity must have a target association defined for it.

The supplied information is passed to the EIM domain controller where all EIM information is
stored and the EIM lookup operation searches for the source association that matches the
supplied information. Based on the EIM identifier (supplied to the API or determined from the
source association information), the EIM lookup operation then searches for a target
association for that identifier that matches the target EIM registry definition name.

Chapter 7. EIM 367

 In Figure 7-5 on page 368, the user identity johnday authenticates to the WebSphere
Application Server using lightweight third-party authentication (LPTA) on System A.

Figure 7-5 EIM lookup

The WebSphere Application Server on System A calls a native program on System B to

access data on System B. The native program uses an EIM API to perform an EIM lookup
operation based on the user identity on System A as the source of the operation. The
application supplies the following information to perform the operation:
 johnday as the source user identity
 System_A_WAS as the source EIM registry definition name
 System_B as the target EIM registry definition name

This source information is passed to the EIM domain controller and the EIM lookup operation
finds a source association that matches the information. Using the EIM identifier name, the
EIM lookup operation searches for a target association for the johnday identifier that matches
the target EIM registry definition name for System_B. When the matching target association
is found, the EIM lookup operation returns the jsd1 user identity to the application.

Mapping policy support and enablement

EIM mapping policy support allows you to use policy associations as well as specific identifier
associations in an EIM domain. You can use policy associations instead of, or in combination
with, identifier associations.

EIM mapping policy support provides a means of enabling and disabling the use of policy
associations for the entire domain, as well as for each specific target user registry. EIM also
allows you to set whether a specific registry can participate in mapping lookup operations in

368 ABCs of z/OS System Programming Volume 6

general. Consequently, you can use mapping policy support to more precisely control how
mapping lookup operations return results.

The default setting for an EIM domain is that mapping lookups that use policy associations
are disabled for the domain. When the use of policy associations is disabled for the domain,
all mapping lookup operations for the domain return results only by using specific, identifier
associations between user identities and EIM identifiers.

The default setting for each individual registry is that mapping lookup participation is enabled
and the use of policy associations is disabled. When you enable the use of policy
associations for an individual target registry, you must also ensure that this setting is enabled
for the domain.

You can configure mapping lookup participation and the use of policy associations for each
registry in one of the following ways:
 Mapping lookup operations cannot be used for the specified registry at all. In other words,
an application that performs a mapping lookup operation involving that registry will fail to
return results.
 Mapping lookup operations can use specific identifier associations between user identities
and EIM identifiers only. Mapping lookups are enabled for the registry, but the use of policy
associations is disabled for the registry.
 Mapping lookup operations can use specific identifier associations when they exist and
policy associations when specific identifier associations do not exist (all settings are
enabled).

EIM access control

An EIM user is a user who possesses EIM access control based on their membership in a
predefined LDAP user group for a specific domain. Specifying EIM access control for a user
adds that user to a specific LDAP user group for a particular domain. Each LDAP group has
authority to perform specific EIM administrative tasks for that domain. Which and what type of
administrative tasks, including lookup operations, an EIM user can perform is determined by
the access control group to which the EIM user belongs.

EIM access controls allow a user to perform specific administrative tasks or EIM lookup
operations. Only users with EIM administrator access are allowed to grant or revoke
authorities for other users. EIM access controls are granted only to user identities that are
known to the EIM domain controller.

The following sections provide brief descriptions of the functions that each EIM access control
group can perform.

LDAP administrator
This access control allows the user to configure a new EIM domain. A user with this access
control can perform the following functions:
 Create a domain v Delete a domain
 Create and remove EIM identifiers
 Create and remove EIM registry definitions
 Create and remove source, target, and administrative associations
 Perform EIM lookup operations
 Retrieve associations, EIM identifiers, and EIM registry definitions
 Add, remove, and list EIM authority information

Chapter 7. EIM 369

 EIM administrator
This access control allows the user to manage all of the EIM data within this EIM domain. A
user with this access control can perform the following functions:
 Delete a domain
 Create and remove EIM identifiers
 Create and remove EIM registry definitions
 Create and remove source, target, and administrative associations
 Perform EIM lookup operations
 Retrieve associations, EIM identifiers, and EIM registry definitions
 Add, remove, and list EIM authority information

EIM identifiers administrator

This access control allows the user to add and change EIM identifiers and manage source
and administrative associations. A user with this access control can perform the following
functions:
 Create an EIM identifier
 Add and remove source associations
 Add and remove administrative associations
 Perform EIM lookup operations
 Retrieve associations, EIM identifiers, and EIM registry definitions

EIM mapping lookup

This access control allows the user to conduct EIM lookup operations. A user with this access
control can perform the following functions:
 Perform EIM lookup operations
 Retrieve associations, EIM identifiers, and EIM registry definitions

EIM registries administrator

This access control allows the user to manage all EIM registry definitions. A user with this
access control can perform the following functions:
 Add and remove target associations
 Perform EIM lookup operations
 Retrieve associations, EIM identifiers, and EIM registry definitions

EIM registry X administrator

This access control allows the user to manage a specific EIM registry definition. Membership
in this access control group also allows the user to add and remove target associations only
for a specified user registry definition. To take full advantage of mapping lookup operations
and policy associations, a user with this access control should also have EIM mapping
operations access control. This access control allows a user to:
 Create, remove, and list target associations for the specified EIM registry definitions only
 Add and remove default domain policy associations
 Add and remove policy associations for the specified registry definitions only
 Add certificate filters for the specified registry definitions only
 Enable and disable mapping lookups for the specified registry definitions only

370 ABCs of z/OS System Programming Volume 6

 Add and remove policy associations only for the specified registries
 Retrieve EIM identifiers
 Retrieve identifier associations and certificate filters for the specified registry definitions
only
 Add and remove target associations for the specific EIM registry definition
 Perform EIM lookup operations
 Retrieve EIM registry definition information for the specified registry definitions only

Chapter 7. EIM 371

7.3 Setting up EIM in z/OS

Figure 7-6 Setting up EIM on z/OS

Steps for installing and configuring the EIM domain controller on z/OS

Note: For the z/OS Integrated Security Services LDAP server, the following requirements
must be met:
 APAR OW55078 (PTF UW92346) must be applied.
 LDAP must be configured to use the TDBM back end.
 The SDBM (RACF) back end is optional.

1. Install and configure LDAP.

Note:
a. The z/OS Integrated Security Services LDAP server must be configured to accept the
different types of bind requests.
b. Start the z/OS LDAP server.
c. Load the schema definitions.

372 ABCs of z/OS System Programming Volume 6

 Attention:
 An EIM domain must be updated using the EIM APIs or administrative
applications that use the EIM APIs. We do not recommend using the LDAP
utilities and LDAP client APIs to update information in an EIM domain.
 Do not alter the EIM schema definitions unless directed to do so by your IBM
service representative during problem diagnosing.

Restriction: z/OS LDAP by default has a 511 character limit on the length of a
distinguished name for an entry. If this default length is exceeded, message ITY0023
(indicating an unexpected LDAP error) is issued, indicating that DB2 needs to be
reconfigured to support longer distinguished names. This error might show up when
working with long identifier, registry, domain names or suffixes.

2. Consider the options you have for setting up an EIM domain that includes z/OS:
a. Use LDAP on z/OS as the domain controller. (z/OS and non-z/OS applications could
access the data.) The LDAP server on z/OS must be configured with the TDBM back
end. If you plan to use RACF user IDs and passwords for the bind credentials,
configure the server with the SDBM and the TDBM back ends.
b. Set up the z/OS LDAP server in multi-server mode. This configuration has multiple
LDAP servers sharing the same TDBM back-end store, which is useful if you want to
balance the work load between your LDAP servers.
c. The z/OS EIM application can access a domain controller that resides on another
platform.

Chapter 7. EIM 373

7.4 Installing and configuring EIM on z/OS

Figure 7-7 Installing and configuring EIM on z/OS

Installation considerations for applications

EIM applications on z/OS must be APF-authorized. Requiring APF authorization prevents
inadvertent or malicious use of EIM APIs to change information in an EIM domain or to extract
unauthorized information.

Installing and configuring EIM on z/OS

Your z/OS system programmer uses SMP/E to install EIM into an HFS directory. By default,
EIM is installed in the /usr/lpp/eim directory, but your system programmer can determine
whether to change the default for these directories.

Figure 7-7 lists important directories for EIM installation. Your system programmer should
review the right-most column of this table, crossing out any defaults that have changed and
recording the correct directory names.

374 ABCs of z/OS System Programming Volume 6

 Tip: An EIM administrator who uses the eimadmin utility might desire that the directory for
the eimadmin utility be placed in the PATH environment variable. This enables the ability to
run the utility without having to specify the path when issuing the command (or changing to
the /usr/lpp/eim/bin directory prior to issuing the command). The PATH environment
variable can be modified to include the EIM programs directory by issuing the following
command from a shell prompt:
export PATH=$PATH:/usr/lpp/eim/bin

This adds the EIM programs directory to the end of the list of directories to search for
programs. Add the export command to a user’s .profile file so that each time the user
enters a shell, the PATH is updated.

Steps for using the eimadmin utility to manage an EIM domain

Perform the steps listed in this section to create and manage an EIM domain using the
eimadmin utility.

Before you begin:

 The eimadmin utility examples can be entered from the z/OS UNIX System Services shell
by an EIM administrator.
 For improved readability each command option is shown on a separate line.
 In most cases you specify multiple options on a single line, separating them with one or
more spaces.
 If necessary, you can use the backslash (\) continuation character to break the command
into multiple lines.
 The access authority required for successful completion depends on the particular
eimadmin operation you specify, and is determined by the bind credential you specify for
LDAP authentication. The distinguished name that LDAP associates with the credential
should be a member of one or more EIM access groups, which define access authority to
EIM data.

To create the domain:

1. Create an EIM domain by entering a command such as the following from the z/OS shell:
eimadmin -aD -d domainDN -n description -h ldapHost -b bindDN -w
bindPassword
The bindDN must be the distinguished name for the LDAP administrator. (The description
is optional.)
The following command creates the EIM domain My Domain:
eimadmin
-aD
-d ’ibm-eimDomainName=My Domain,o=IBM,c=US’
-n ’An EIM Domain’
-h ldap://some.ldap.host
-b ’cn=ldap administrator’
-w secret

Note: This assumes that the o=IBM,c=US objects are defined in the LDAP Directory.

Chapter 7. EIM 375

 2. Give an administrator EIM administrator authority to the domain by entering a command
such as the following command from the z/OS shell:
eimadmin
-aC
-d domainDN
-c ADMIN
-q accessUser
-f accessUserType
-h ldapHost
-b bindDN
-w bindPassword
The parameter following -c is the accessType parameter. In this situation, the value must
be ADMIN. The bindDN must be the distinguished name for the LDAP administrator.

Tip: If you plan on dividing the administration responsibilities, repeat this command for
the other administrative users.

The following command can be issued by the LDAP administrator to give EIM
administrator, cn=eim administrator,ou=dept20,o=IBM,c=US, authority to administer the
EIM domain:
eimadmin
-aC
-d ’ibm-eimDomainName=My Domain,o=IBM,c=US’
-c ADMIN
-q ’cn=eim administrator,ou=dept20,o=IBM,c=US’
-f DN
-h ldap://some.ldap.host
-b ’cn=ldap administrator’
-w secret

Note: This assumes that the cn=eim administrator,ou=dept20,o=IBM,c=US is defined

in the LDAP Directory.

3. Add registries to the EIM domain by entering a command such as the following command
from the z/OS shell:
eimadmin
-aR
-d domainDN
-r registryName
-y registryType
-n description
-h ldapHost
-b bindDN
-w bindPassword

Note: The -y parameter specifies registry type.

376 ABCs of z/OS System Programming Volume 6

 The following command adds a RACF registry to the EIM domain named My Domain:
eimadmin
-aR
-d ’ibm-eimDomainName=My Domain,o=IBM,c=US’
-r ’RACF Pok1’
-y RACF
-n ’the RACF Registry on Pok System 1’
-h ldap://some.ldap.host
-b ’cn=eim administrator,ou=dept20,o=IBM,c=US’
-w secret
The following command adds an OS/400 registry to the EIM domain named My Domain:
eimadmin
-aR
-d ’ibm-eimDomainName=My Domain,o=IBM,c=US’
-r ’OS400 RCH1’
-y OS400
-n ’the OS400 Registry on Rochester System 1’
-h ldap://some.ldap.host
-b ’cn=eim administrator,ou=dept20,o=IBM,c=US’
-w secret
4. Add enterprise identifiers to the domain by entering a command such as the following from
the z/OS shell:
eimadmin
-aI
-d domainDN
-i identifier
-n description
-h ldapHost
-b bindDN
-w bindPassword
You can add identifiers at any time after creating the domain.
The preceding command adds a single identifier to the domain. Alternately, you can add
multiple identifiers by specifying a file name as standard input to the eimadmin utility.
Specifying a file name indicates using the file of identifiers as input for batch processing of
multiple identifiers.
Repeat this step as needed.
The bindDN must have EIM administrator authority or EIM Identifier administrator authority.
The following command can be issued by the EIM administrator add to an EIM identifier to
the domain My Domain:
eimadmin
-aI
-d ’ibm-eimDomainName=My Domain,o=IBM,c=US’
-i ’John Adam Day’
-h ldap://some.ldap.host
-b ’cn=eim administrator,ou=dept20,o=IBM,c=US’
-w secret

Chapter 7. EIM 377

 5. Create associations between registry user IDs and identifiers by entering commands from
the z/OS shell (One or more of the association types, -t source, -t target, -t admin are
required on the command.):
eimadmin
-aA
-d domainDN
-r registryName
-u userid
-i identifier
-t admin
-t source
-t target
-h ldapHost
-b bindDN
-w bindPassword
The following command creates associations between the user ID JD in the RACF Pok1
registry:
eimadmin
-aA
-d ’ibm-eimDomainName=My Domain,o=IBM,c=US’
-r ’RACF Pok1’
-u JD
-i ’John Day’
-t source
-t target
-h ldap://some.ldap.host
-b ’cn=eim administrator,ou=dept20,o=IBM,c=US’
-w secret
After you enter these commands, you can use the domain for lookup operations. For the
preceding examples, the only user mappings available are mappings from JD to JOHNDAY
and from JOHNDAY to JD.

Note: You can create associations only after registries and identifiers are in place.

The command creates only two associations. Conversely, you can create multiple
associations by specifying a file name as standard input to the eimadmin command.
Specifying a file name indicates using a file of associations as input for batch
processing of multiple associations.

Repeat this step as needed.

6. Give users lookup access to the EIM domain. Use the following command:
eimadmin
-aC
-d domainDN
-c MAPPING
-q accessUser
-f DN
-h ldapHost
-b bindDN
-w bindPassword

378 ABCs of z/OS System Programming Volume 6

The eimadmin utility allows you to grant access one user at a time or a list of users can be
provided in a file using the following command:
eimadmin
-aC
-d domainDN
-c MAPPING
-h ldapHost
-b bindDN
-w bindPassword <input-fileName
The file must contain a label line following by at least one user name. For example, a bind
distinguished name, and the type of the user name as follows:
CU ;CS ; cn=John Day,c=US DN
The EIM administrator can issue the following command to give the user John Day
mapping (lookup) authority to the domain My Domain:
eimadmin
-aC
-d ’ibm-eimDomainName=My Domain,o=IBM,c=US’
-c MAPPING
-q ’cn=John Day,c=US’ -h ldap://some.ldap.host
-b ’cn=eim administrator,ou=dept20,o=IBM,c=US’
-w secret

Chapter 7. EIM 379

7.5 Domain authentication methods

z/OS EIM supports the following authentication methods

recognized by LDAP:
Simple (with or without CRAM-MD5 password protection)
Digital certificate
Kerberos

Figure 7-8 Domain authentication methods

Domain authentication methods

Authentication occurs when an EIM application connects (binds) to the EIM domain controller.
z/OS EIM supports the following three authentication methods recognized by LDAP:
 Simple (with or without CRAM-MD5 password protection)
 Digital certificate
 Kerberos

Your LDAP server configuration and security requirements determine which method you
choose. The examples in this section illustrate how you can use these methods with the
eimadmin utility.

This information explains how the bind credentials specified correspond to the distinguished
name that LDAP uses for access checking. Your access to EIM data is determined by the
authority groups of which the distinguished name is a member. The exception is the
distinguished name for the LDAP administrator that has unrestricted access.

380 ABCs of z/OS System Programming Volume 6

Using simple binds
A distinguished name and password are sufficient credentials for a SIMPLE eimadmin connect
type, as follows:
eimadmin
-lD
-d ’ibm-eimDomainName=MyDomain,o=IBM,c=US’
-h ldap://some.ldap.host
-S SIMPLE
-b ’cn=eimadministrator,ou=dept20,o=IBM,c=US’
-w secret

Note: Unless an SSL session has been established, the password is sent over the network
in plain text, making this method the least secure. The distinguished name that you specify
is the one LDAP uses for access checking.

Using CRAM-MD5 password protection

You can use CRAM-MD5 for simple authentication without sending the bind password over
the network in plain text, provided both client and server support the method. In the utility
command, specify the connect type CRAM-MD5 to indicate simple authentication with
password protection, as follows:
eimadmin
-lD
-d ’ibm-eimDomainName=MyDomain,o=IBM,c=US’
-h ldap://some.ldap.host
-S CRAM-MD5
-b ’cn=eimadministrator,ou=dept20,o=IBM,c=US’
-w secret

Using digital certificates

To bind using a digital certificate, specify the EXTERNAL connect type on the eimadmin
command. Ensure that the host name identifies a secure host:port value prefixed with
ldaps://, as follows:
eimadmin
-lD
-d ’ibm-eimDomainName=MyDomain,o=IBM,c=US’
-h ldaps://secure.ldap.host
-S EXTERNAL
-K client.kdb
-P clientpw
-N eimadmincert

Note: LDAP uses the client certificate’s subject distinguished name for access checking.

Use the following rules:

 You must also specify the name of either a key database file or RACF key ring that
contains your client certificate.
 You must specify the label for that certificate if it is not the defined default. If you specify a
key database file but not its password, the utility prompts you for it.

Chapter 7. EIM 381

 Using Kerberos
To bind using a Kerberos identity, specify connect type GSSAPI on the eimadmin command.
No other credential information is required, but the default Kerberos credential must be
established through a service such as kinit prior to entering the command, as follows:
kinit [email protected]
eimadmin
-lD
-d ’ibm-eimDomainName=MyDomain,o=IBM,c=US’
-h ldap://some.ldap.host
-S GSSAPI

For access checking, LDAP considers a distinguished name formed by prefixing the Kerberos
principal name with ibm-kgn= or distinguished names located through special mapping or
searches.

Using Secure Sockets Layer

You can establish a Secure Sockets Layer (SSL) connection along with any of the supported
authentication types if your domain controller is configured as a secure host enabled for
server authentication.

A secure host is required for EXTERNAL connect.

The strength of SSL is that data transferred over the connection is encrypted, including the
password for a SIMPLE bind. The eimadmin utility recognizes the need for an SSL connection
when you specify an LDAP host name prefixed with ldaps://. It then requires that you specify
a RACF key ring, or a key database file and its password.

382 ABCs of z/OS System Programming Volume 6

7.6 EIM additional administration tasks

EIM additional administration tasks:

Managing registries
Adding a system and application registry
Removing a registry
Assigning an alias
Assigning an alias
Removing an alias
Assigning an alias to a different registry
Adding a new user
Adding an identifier
Adding associations
Removing a user
Removing associations
Removing an identifier
Changing access authority
Adding access
Removing access
Figure 7-9 EIM additional administration tasks

Managing registries
A domain typically contains multiple registries. User identities for a particular system are
associated with a system registry, while a subset of identities might be associated with an
application registry.

Adding a system and application registry

Create a system registry by entering the following command:
eimadmin
-aR
-r ’RACF Pok1’
-y racf
-d ’ibm-eimDomainName=MyDomain,o=IBM,c=US’
-h ldap://some.ldap.host
-b ’cn=eimadministrator,ou=dept20,o=IBM,c=US’
-w secret

Chapter 7. EIM 383

 Enter the following command to define an application registry that is dependent on a
previously defined system registry:
eimadmin
-aR
-r ’App1’
-y racf
-g ’RACF Pok1’
-d ’ibm-eimDomainName=MyDomain,o=IBM,c=US’
-h ldap://some.ldap.host
-b ’cn=eimadministrator,ou=dept20,o=IBM,c=US’
-w secret

Note: After you define an application registry, you can refer to it by name in EIM APIs and
eimadmin commands without having to identify it as an application-type registry.

Listing a registry
You can list any registry using a command similar to the following:
eimadmin
-lR
-r ’App1’
-d ’ibm-eimDomainName=MyDomain,o=IBM,c=US’
-h ldap://some.ldap.host
-b ’cn=eimadministrator,ou=dept20,o=IBM,c=US’
-w secret

Removing a registry
To remove a registry, issue the following command:
eimadmin
-pR
-r ’App1’
-d ’ibm-eimDomainName=MyDomain,o=IBM,c=US’
-h ldap://some.ldap.host
-b ’cn=eimadministrator,ou=dept20,o=IBM,c=US’
-w secret

All associations linked to the registry are deleted automatically.

Attention: EIM refuses to remove a system registry if any application registries depend on
it.

You can find the dependents that you must remove by searching for all occurrences of the
system registry name in the output from the following command, which lists all registries:
eimadmin
-lR
-r ’*’
-d ’ibm-eimDomainName=MyDomain,o=IBM,c=US’
-h ldap://some.ldap.host
-b ’cn=eimadministrator,ou=dept20,o=IBM,c=US’
-w secret

384 ABCs of z/OS System Programming Volume 6

With caution, you can use the -s rmdeps option of eimadmin to remove dependent application
registries automatically when removing the system registry, as follows:
eimadmin
-s rmdeps
-pR
-r ’RACF Pok1’
-d ’ibm-eimDomainName=MyDomain,o=IBM,c=US’
-h ldap://some.ldap.host
-b ’cn=eimadministrator,ou=dept20,o=IBM,c=US’
-w secret
Working with registry aliases
You can define alias names to facilitate registry administration. By establishing aliases that
applications use to look up actual registry names, you can make nondisruptive registry
changes by managing alias assignments.

Rule: When defining or referencing a registry alias, you must specify an associated
registry type.

Assigning an alias
Enter the following command to assign an alias name to an existing registry:
eimadmin
-mR
-r ’RACF Test Pok1’
-x ’z/OS’
-z ’RACF’
-d ’ibm-eimDomainName=MyDomain,o=IBM,c=US’
-h ldap://some.ldap.host
-b ’cn=eimadministrator,ou=dept20,o=IBM,c=US’
-w secret

This example defines the alias z/OS (of type RACF) for registry RACF Test Pok1.
Listing an alias
You can list the registry and its aliases using the following command:
eimadmin
-lR
-r ’RACF Test Pok1’
-d ’ibm-eimDomainName=MyDomain,o=IBM,c=US’
-h ldap://some.ldap.host
-b ’cn=eimadministrator,ou=dept20,o=IBM,c=US’
-w secret
Removing an alias
You can delete an alias for a registry using the following command:
eimadmin
-eR
-r ’RACF Test Pok1’
-x ’z/OS’
-z ’RACF’
-d ’ibm-eimDomainName=MyDomain,o=IBM,c=US’
-h ldap://some.ldap.host
-b ’cn=eimadministrator,ou=dept20,o=IBM,c=US’
-w secret

This example removes the alias z/OS (of type RACF) for registry RACF Test Pok1.

Chapter 7. EIM 385

 Assigning an alias name to a different registry
To assign an alias name to a different registry, add the alias name and type to the registry
attributes as shown in the example for adding an alias name to a registry above. Multiple
registries can have the same registry alias values. However, if you want the alias to map to a
single registry, you must remove that alias from registries in which is was previously defined.

Enter the following two commands to reassign alias z/OS from registry RACF Test Pok1 to
registry RACF Pok1:
eimadmin
-mR
-r ’RACF Pok1’
-x ’z/OS’
-z ’RACF’
-d ’ibm-eimDomainName=MyDomain,o=IBM,c=US’
-h ldap://some.ldap.host
-b ’cn=eimadministrator,ou=dept20,o=IBM,c=US’
-w secret

eimadmin
-eR
-r ’RACF Test Pok1’
-x ’z/OS’
-z ’RACF’
-d ’ibm-eimDomainName=MyDomain,o=IBM,c=US’
-h ldap://some.ldap.host
-b ’cn=eimadministrator,ou=dept20,o=IBM,c=US’
-w secret

Adding a new user

You can create an new EIM identifier to represent a new person entering your enterprise. As
the person is given access to each system or application through its user registry, you can
define an EIM association between the EIM identifier and the corresponding registry defined
in EIM.

Adding an identifier
When you create a new EIM identifier, it is assigned a name that is unique within the domain.

The eimadmin utility requires that you specify a unique name (unlike the eimAddIdentifier
API option that generates a unique name for you).

You can assign an alternate name, or alias, to multiple identifiers. This non-unique name can
be used to further describe the represented individual or to serve as an alternate identifier for
lookup operations.

Enter the following command to add a new identifier John S. Day with two aliases:
eimadmin
-aI
-i ’John S. Day’
-j ’654321’
-j ’Contractor’
-d ’ibm-eimDomainName=MyDomain,o=IBM,c=US’
-h ldap://some.ldap.host
-b ’cn=eimadministrator,ou=dept20,o=IBM,c=US’
-w secret

386 ABCs of z/OS System Programming Volume 6

You can list the new identifier using the unique name.

The utility returns one entry only, as follows:

eimadmin
-lI
-i ’John S. Day’
-d ’ibm-eimDomainName=MyDomain,o=IBM,c=US’
-h ldap://some.ldap.host
-b ’cn=eimadministrator,ou=dept20,o=IBM,c=US’
-w secret

You can also list the new identifier using an alias name.

The utility returns all entries having Contractor defined as an alternate name, as follows:
eimadmin
-lI
-j ’Contractor’
-d ’ibm-eimDomainName=MyDomain,o=IBM,c=US’
-h ldap://some.ldap.host
-b ’cn=eimadministrator,ou=dept20,o=IBM,c=US’
-w secret

Adding associations
You can register the system and application user IDs assigned to the individual by defining
EIM associations between the identifier and the corresponding registries.

Enter the following command to create source and target associations for user ID JD in
registry RACF Pok1:
eimadmin
-aA
-i ’John S. Day’
-r ’RACF Pok1’
-u ’JD’
-t source
-t target
-d ’ibm-eimDomainName=MyDomain,o=IBM,c=US’
-h ldap://some.ldap.host
-b ’cn=eimadministrator,ou=dept20,o=IBM,c=US’
-w secret

Listing associations
Enter the following command to list all associations for John S. Day:
eimadmin
-lA
-i ’John S. Day’
-d ’ibm-eimDomainName=MyDomain,o=IBM,c=US’
-h ldap://some.ldap.host
-b ’cn=eimadministrator,ou=dept20,o=IBM,c=US’
-w secret

Chapter 7. EIM 387

 Removing a user
To completely erase a person’s identity from your EIM domain, remove the identifier.

If you only need to reflect the deletion of a user ID from a registry, simply remove the
corresponding EIM associations.

Removing associations
Enter the following command to remove the source and target associations for user ID JD in
registry RACF Pok1:
eimadmin
-pA
-i ’John S. Day’
-r ’RACF Pok1’
-u ’JD’
-t source
-t target
-d ’ibm-eimDomainName=MyDomain,o=IBM,c=US’
-h ldap://some.ldap.host
-b ’cn=eimadministrator,ou=dept20,o=IBM,c=US’
-w secret

Removing an identifier
Enter the following command to remove an identifier and its associations, including identifier
aliases:
eimadmin
-pI
-i ’John S. Day’
-d ’ibm-eimDomainName=MyDomain,o=IBM,c=US’
-h ldap://some.ldap.host
-b ’cn=eimadministrator,ou=dept20,o=IBM,c=US’
-w secret

Changing access authority

A user is permitted to perform EIM administrative or lookup operations based on the authority
groups containing the user’s LDAP DN. The user’s DN is determined by the credentials
authenticated when connecting to LDAP.

Suppose that a user has registry administrator authority over a specific registry, and your task
is to switch the user’s authority to a different registry. You can accomplish this task in two
steps:
1. Add the user to the new registry administrator group.
2. Remove the user from the prior group.

Adding access authorities

Enter the following command to add user DN cn=Reggie King,ou=dept20,o=IBM,c=US to the
registry administration group for RACF Pok1:
eimadmin
-aC
-q ’cn=Reggie King,ou=dept20,o=IBM,c=US’
-f DN
-c registry
-r ’RACF Pok1’

388 ABCs of z/OS System Programming Volume 6

 -d ’ibm-eimDomainName=MyDomain,o=IBM,c=US’
-h ldap://some.ldap.host
-b ’cn=eimadministrator,ou=dept20,o=IBM,c=US’
-w secret

Listing access authorities

Enter the following command to list all EIM access authorities for the user:
eimadmin
-lC
-q ’cn=Reggie King,ou=dept20,o=IBM,c=US’
-f DN
-d ’ibm-eimDomainName=MyDomain,o=IBM,c=US’
-h ldap://some.ldap.host
-b ’cn=eimadministrator,ou=dept20,o=IBM,c=US’
-w secret

Removing access authorities

Enter the following command to remove the user from the prior registry administration group
for RACF Test Pok1:
eimadmin
-pC
-q ’cn=Reggie King,ou=dept20,o=IBM,c=US’
-f DN
-c registry
-r ’RACF Test Pok1’
-d ’ibm-eimDomainName=MyDomain,o=IBM,c=US’
-h ldap://some.ldap.host
-b ’cn=eimadministrator,ou=dept20,o=IBM,c=US’
-w secret

Chapter 7. EIM 389

7.7 RACF support for EIM

Security administrator has ability to

Define default EIM domain by system or by server
Define default LDAP bind information for the EIM domain
Enhanced commands and profiles
ADDUSER, ALTUSER, LISTUSER
RDEFINE, RALTER, LISTUSER
IRR.PROXY.DEFAULTS FACILITY class profile
IRR.EIM.DEFAULTS LDAPBIND class profile
Other updates
r_admin callable service
Database unload
SMF records, SMF unload
Templates

Figure 7-10 RACF support for EIM

Using RACF for EIM domain access

The RACF administrator can use RACF commands to do the following:
 Add an EIM domain name and bind information for system-wide use
 Add an EIM domain name and bind information for use by a server
 Add an EIM domain name and bind information for use by an administrative user
 Assign a name to the local RACF registry for use by a lookup application

Tip: Issuing these commands is optional. However, setting up your system this way can
eliminate the need for individual applications to handle EIM domain and bind information.

The default domain and bind information can be specified in one of three places:
1. The user ID the application runs under has the name of an LDAPBIND class profile in its
USER profile
2. The IRR.EIM.DEFAULTS profile in the LDAPBIND class
3. The IRR.PROXY.DEFAULTS profile in the FACILITY class

390 ABCs of z/OS System Programming Volume 6

These RACF profiles can be set up in such a way as to control the access the application has
to the EIM domain:
 New connections with an EIM domain can be enabled or disabled by using keywords on
the RDEFINE or RALTER commands.
 Bind credentials can be specific to the server or administrator who uses them.

The EIM APIs try to retrieve the information from a profile if the application does not explicitly
supply the information to the EIM APIs using parameters. Applications or other services that
use EIM can instruct their callers to define a profile in the LDAPBIND class profile.

Chapter 7. EIM 391

7.8 Storing LDAP binding information in a profile

Figure 7-11 Storing LDAP bind information in a profile

Before you begin, use the decision table of Figure 7-11 to determine which profile to use.

Adding EIM domain and bind information for servers or administrative

users
To create a profile for LDAP binding information:
1. If you are creating a profile in the LDAPBIND class, define the domain in the LDAPBIND
class. Enter the following command:
RDEFINE LDAPBIND racfProfileName EIM(DOMAINDN(domainDN))
PROXY(LDAPHOST(ldapHost) + BINDDN(bindDN) BINDPW(bindPasswd))
2. To update the user profile:
ADDUSER ASERVER EIM(LDAPPROF(racfProfileName))

Adding a system default using the IRR.EIM.DEFAULTS profile

If you are using the IRR.PROXY.DEFAULTS profile in the FACILITY class, enter:
RDEFINE LDAPBIND IRR.EIM.DEFAULTS PROXY(LDAPHOST(ldapHost) BINDDN(bindDN) +
BINDPW(bindPasswd)) EIM(DOMAINDN(domainDN))

Adding a system default using the IRR.PROXY.DEFAULTS profile

If no LDAPBIND class profile is associated with the caller’s user profile, the EIM services look
for the EIM domain’s LDAP URL and binding information in the IRR.EIM.DEFAULTS profile in

392 ABCs of z/OS System Programming Volume 6

the LDAPBIND class followed by the IRR.PROXY.DEFAULTS profile in the FACILITY class.
For example, the following command sets up the binding information in the
IRR.PROXY.DEFAULTS profile in the FACILITY class:
RDEFINE FACILITY IRR.PROXY.DEFAULTS PROXY(LDAPHOST(LDAP://SOME.BIG.HOST:389) +
BINDDN(’cn=Joes Admin,o=IBM,c=US’) BINDPW(secret)) +
EIM(DOMAINDN(’ibm-eimDomainName=Joes Domain,o=IBM,c=US’))

In this case, the domain’s LDAP URL is:

LDAP://SOME.BIG.HOST:389/ibm-eimDomainName=Joes Domain,o=IBM,c=US

Chapter 7. EIM 393

7.9 Setting up a registry name for your local RACF registry

Figure 7-12 Setting up a registry name for your local RACF registry

Many of the EIM APIs require the name of a registry. For example, if you are adding a registry
to an EIM domain, you should know the name of the new registry. However, you can use the
lookup APIs (such as eimGetTargetFromSource, eimGetIdentifierFromSource, and
eimGetAssociatedIdentifiers) to convert:
1. A user ID to its equivalent RACF user ID
2. A local RACF user ID to an enterprise identifier

For such applications, you can eliminate the requirement for providing the RACF registry
name or its alias on the local system. You do this by giving a name to the local RACF registry.

Steps for setting up lookups that do not need a registry name

Before you begin, you need to know the registry name.

To set up EIM so that you do not need a registry name on every lookup follow the instructions
in this section. To define the local registry, enter the following RACF command in which
registryName is the name of the local registry:
RDEFINE FACILITY IRR.PROXY.DEFAULTS EIM(LOCALREGISTRY(registryName))

Note: EIM does not look for the registry name in an LDAPBIND class profile.

394 ABCs of z/OS System Programming Volume 6

You can also configure the system with a kerberos registry name and an X.509 registry name.
Issue the following commands to define default kerberos and X.509 registries for the
configured EIM domain:
RALTER FACILITY IRR.PROXY.DEFAULTS EIM(KERBREGISTRY(registry name) +
X509REGISTRY(registry name))

This access can be removed with the following command:

RALTER FACILITY IRR.PROXY.DEFAULTS EIM(NOKERBREGISTRY NOX509REGISTRY)

Note: You need to define these registry names in the configured EIM domain.

Disabling use of an EIM domain

You might need to temporarily disable use of a RACF profile with a configured EIM domain or
a system-wide default EIM domain. You might want to do this if the EIM information in a
domain has been compromised or a security administrator wants to stop the system or server
from establishing new connections with the EIM domain. You can use RACF commands to
disable a domain without deleting EIM information from the RACF profiles. When an EIM
domain is disabled through a RACF profile, existing connections to the domain complete their
work. However, if an EIM service is trying to establish a connection with such a domain, the
EIM service does not continue to look for an enabled domain.

If you want to disable a server (rather than a system) from using a configured EIM domain,
enter the following command:
RALTER LDAPBIND ldapbind_profile EIM(OPTIONS(DISABLE))

This command applies only to a server that has an ldapbind class profile specified for its user
ID.

Tip: To disable a system-wide default EIM domain (rather than a server) that default
profiles use, enter one of the following commands:
RALTER FACILITY IRR.PROXY.DEFAULTS EIM(OPTIONS(DISABLE))
RALTER LDAPBIND IRR.EIM.DEFAULTS EIM(OPTIONS(DISABLE))

Using output from the RACF database unload utility and eimadmin
to prime your EIM domain with information
You can start to put EIM information (identifiers, RACF user IDs, and associations) into your
EIM domain by using output from DBUNLOAD and eimadmin.

For large installations, priming the EIM domain with identifiers and associations can involve a
lot of work. To make the task of getting started with EIM easier, the eimadmin utility accepts
as input a file containing a list of identifiers and associations.

The section explores the steps for setting up an EIM domain based on user information
contained in a RACF database. The initial assumptions are that the EIM domain, World Wide
Domain, has been created and a SAF system registry, SAF user IDs, is defined in the
domain. The LDAP host name for the domain is ldap://some.big.host. The EIM
administrator uses the bind distinguished name of cn=EIM Admin,o=My Company,c=US and the
password is secret. The EIM administrator bind distinguished name has been given EIM
administrator authority and can perform all of the steps that we list here.

Chapter 7. EIM 395

 A user with other types of EIM authority, such as the following types of authority, can perform
a subset of the following steps:
 EIM identifier administrator authority only works with identifiers and source and target
associations.
 EIM registries administrator authority only works with target associations.
 EIM registry-specific administrator authority for the SAF registry only works with target
associations in the SAF registry.

To set up an EIM domain based on user information contained in a RACF database:

1. Request from your RACF security administrator a file containing a copy of the user profiles
in the RACF database. The RACF security administrator can:
a. Run the database unload utility (IRRDBU00) to create the sequential file
b. Run the file through a sort program, such as DFSORT™ or DFSORT ICETOOL to
extract just the user profiles and desired fields. The User Basic Data Record (0200)
contains the user ID and the programmer name. In this example, the programmer
name is used for the EIM identifier.
The DFSORT ICETOOL Report format has a 1 to 4 character name (for example, EIM). It
contains the ICETOOL statements that control report format and record summary
information, such as SORT, COPY, DISPLAY, and OCCURS statements. Example 7-1
shows a report format that can be used to extract RACF user IDs and the programmer
names that are associated with the user IDs.

Example 7-1 A sample report format

**********************************************************************
* Name: EIM
*
*
* Find all user IDs in the RACF database and their name
**********************************************************************
COPY FROM(DBUDATA) TO(TEMP0001) USING(RACF)
OCCURS FROM(TEMP0001) LIST(PRINT) -
TITLE(’user IDs and Names’) -
ON(10,8,CH) HEADER(’USER ID’) -
ON(79,20,CH) HEADER(’Name’)

The record selection criteria is as follows:

– The name of the member containing the record selection criteria is the report member
name followed by CNTL (such as EIMCNTL).
– Record selection is performed using DFSORT control statements, such as SORT and
INCLUDE.
– The SORT command is used to select and sort records.
– The INCLUDE command is used to specify conditions required for records to appear in
the report.
2. When you receive the report from the security administrator, move it to a file in the HFS.
3. Add a eimadmin utility ?label line? to the file containing user profiles. You can use any
one of the editors available from the OMVS shell (such as OEDIT).

396 ABCs of z/OS System Programming Volume 6

4. Add identifiers and list the results using the eimadmin shell command:
eimadmin
-aI
-d "ibm-eimDomainName=World Wide Domain,o=My Company,c=US"
-h ldap://some.big.host
-b "cn=EIM Admin,o=My Company,c=US"
-w secret <racfUsers.txt
5. To list the identifiers that you added, issue the following command:
eimadmin
-lI
-d "ibm-eimDomainName=World Wide Domain,o=My Company,c=US"
-h ldap://some.big.host
-b "cn=EIM Admin,o=My Company,c=US"
-w secret <racfUsers.txt
6. Create source and target associations between the identifiers and the user IDs in RACF.
Because the file racfUsers.txt contains a label line that identifies user IDs as well as
unique identifier names, it can be used to create associations:
eimadmin
-aA
-t source
-t target
-r"SAF user IDs"
-d "ibm-eimDomainName=World Wide Domain,o=My Company,c=US"
-h ldap://some.big.host
-b "cn=EIM Admin,o=My Company,c=US" -w secret <racfUsers.txt
7. To list the associations that you added, issue the following command:
eimadmin
-lA
-d "ibm-eimDomainName=World Wide Domain,o=My Company,c=US"
-h ldap://some.big.host
-b "cn=EIM Admin,o=My Company,c=US"
-w secret <racfUsers.txt
8. The following eimadmin commands can be used to give EIM Mapping Operations authority
to each of the users (identified in the file racfUsersDNs.txt):
eimadmin
-aC
-c MAPPING
-d "ibm-eimDomainName=World Wide Domain,o=My Company,c=US"
-f DN
-h ldap://some.big.host
-b "cn=EIM Admin,o=My Company,c=US"
-w secret <racfUsersDNs.txt

Chapter 7. EIM 397

 9. To list the accesses that have been granted, issue the following command:
eimadmin
-lC
-c MAPPING
-d "ibm-eimDomainName=World Wide Domain,o=My Company,c=US"
-h ldap://some.big.host
-b "cn=EIM Admin,o=My Company,c=US"
-w secret <racfUsersDNs.txt

Tip: At a minimum, a user who is looking for a mapping in the EIM domain needs to have
EIM mapping operations authority. In most cases, the application has one set of
credentials for connect to an EIM domain, and those credentials are shared by all users.
However, if individual access is needed, then a bind distinguished name needs to be
defined for each of the users and given EIM mapping operations authority.

398 ABCs of z/OS System Programming Volume 6

Related publications

We consider the publications that we list in this section particularly suitable for a more
detailed discussion of the topics that we cover in this book.

IBM Redbooks publications

For information about ordering these publications, see “How to get IBM Redbooks
publications” on page 401. Note that some of the documents referenced here might be
available in softcopy only.

The other volumes in this series include:

 ABCs of z/OS System Programming Volume 1, SG24-6981
Introduction to z/OS and storage concepts, TSO/E, ISPF, JCL, SDSF, and z/OS delivery
and installation
 ABCs of z/OS System Programming Volume 2, SG24-6982
Implementing z/OS and daily maintenance, defining subsystems, JES2 and JES3, LPA,
LNKLST, authorized libraries, Language Environment, and SMP/E
 ABCs of z/OS System Programming Volume 3, SG24-6983
Introduction to DFSMS, data set basics, storage management hardware and software,
VSAM, System-managed storage, catalogs, and DFSMStvs
 ABCs of System Programming Volume 4, SG24-5654
Communication Server, TCP/IP, and VTAM
This volume is not yet published.
 ABCs of z/OS System Programming Volume 5, SG24-6985
Base and Parallel Sysplex, System Logger, Resource Recovery Services (RRS), global
resource serialization (GRS), z/OS system operations, automatic restart management
(ARM), and Geographically dispersed Parallel Sysplex (GPDS)
 ABCs of z/OS System Programming Volume 7, SG24-6987
Printing in a z/OS environment, Infoprint Server and Infoprint Central
 ABCs of z/OS System Programming Volume 8, SG24-6988
An introduction to z/OS problem diagnosis
 ABCs of z/OS System Programming Volume 9, SG24-6989
z/OS UNIX System Services
 ABCs of z/OS System Programming Volume 10, SG24-6990
Introduction to z/Architecture, System z processor design, System z connectivity, LPAR
concepts, HCD, and HMC
 ABCs of z/OS System Programming Volume 11, SG24-6327
Capacity planning, performance management, WLM, RMF, and SMF

© Copyright IBM Corp. 2008. All rights reserved. 399

 Other publications of interest include:
 System z Cryptographic Services and z/OS PKI Services, SG24-7470
 z9-109 Crypto and TKE V5 Update, SG24-7123
 Implementing PKI Services on z/OS, SG24-6968
 z/OS Version 1 Release 8 RACF Implementation, SG24-7248

Other publications
These publications are also relevant as further information sources:
 z/OS Integrated Security Services Network Authentication Service Administration,
SC24-5926
 z/OS Integrated Security Services Network Authentication Service Programming,
SC24-5927
 z/OS Cryptographic Services PKI Services Guide and Reference, SA22-7693
 z/OS Integrated Security Services LDAP Server Administration and Use, SC24-5923
 z/OS Security Server RACF Auditor's Guide, SA22-7684
 z/OS Security Server RACF Callable Services, SA22-7691
 z/OS Security Server RACF Command Language Reference, SA22-7687
 z/OS Security Server RACF Data Areas, GA22-7680
 z/OS Security Server RACF Diagnosis Guide, GA22-7689
 z/OS Security Server RACF General User's Guide, SA22-7685
 z/OS Security Server RACF Macros and Interfaces, SA22-7682
 z/OS Security Server RACF Messages and Codes, SA22-7686
 z/OS Security Server RACF Security Administrator's Guide, SA22-7683
 z/OS Security Server RACF System Programmer's Guide, SA22-7681
 z/OS Security Server RACROUTE Macro Reference, SA22-7692
 z/OS Integrated Security Services Enterprise Identity Mapping (EIM) Guide and
Reference, SA22-7875
 z/OS OCSF Service Provider Module Developer's Guide and Reference, SC24-5900
 z/OS Open Cryptographic Services Facility (OCSF) Application Programming, SC24-5899
 z/OS Cryptographic Services ICSF Administrator’s Guide, SA22-7521
 z/OS Cryptographic Services ICSF Application Programmer’s Guide, SA22-7522
 z/OS Cryptographic Services ICSF Messages, SA22-7523
 z/OS Cryptographic Services ICSF Overview, SA22-7519
 z/OS Cryptographic Services ICSF System Programmer’s Guide, SA22-7520
 z/OS Cryptographic Services ICSF TKE PCIX Workstation User’s Guide, SA23-2211
 z/OS Cryptographic Services System SSL Programming, SC24-5901

400 ABCs of z/OS System Programming Volume 6

How to get IBM Redbooks publications
You can search for, view, or download Redbooks, Redpapers, Hints and Tips, draft
publications and Additional materials, as well as order hardcopy Redbooks or CD-ROMs, at
this Web site:
ibm.com/redbooks

Related publications 401

402 ABCs of z/OS System Programming Volume 6
ABCs of z/OS System Programming
Volume 6
ABCs of z/OS System Programming
Volume 6
ABCs of z/OS System Programming Volume 6
(0.5” spine)
0.475”<->0.873”
250 <-> 459 pages
ABCs of z/OS System Programming Volume 6
ABCs of z/OS System Programming
Volume 6
ABCs of z/OS System Programming
Volume 6
 Back cover ®

ABCs of z/OS System

Programming
Volume 6 ®

Security on z/OS, The ABCs of z/OS System Programming is an 11-volume collection that
RACF, and LDAP provides an introduction to the z/OS operating system and the hardware INTERNATIONAL
architecture. Whether you are a beginner or an experienced system
programmer, the ABCs collection provides the information that you need to
TECHNICAL
Kerberos and PKI SUPPORT
start your research into z/OS and related subjects. If you want to become more
familiar with z/OS in your current environment or if you are evaluating ORGANIZATION
Cryptography and EIM platforms to consolidate your e-business applications, the ABCs collection can
serve as a powerful technical tool.
 Volume 1: Introduction to z/OS and storage concepts, TSO/E, ISPF, JCL,
SDSF, and z/OS delivery and installation
BUILDING TECHNICAL
 Volume 2: z/OS implementation and daily maintenance, defining
INFORMATION BASED ON
subsystems, JES2 and JES3, LPA, LNKLST, authorized libraries, Language
PRACTICAL EXPERIENCE
Environment, and SMP/E
 Volume 3: Introduction to DFSMS, data set basics, storage management
IBM Redbooks are developed
hardware and software, VSAM, System-managed storage, catalogs, and by the IBM International
DFSMStvs Technical Support
 Volume 4: Communication Server, TCP/IP, and VTAM Organization. Experts from
 Volume 5: Base and Parallel Sysplex, System Logger, RRS, GRS, z/OS IBM, Customers and Partners
system operations, ARM, and GPDS from around the world create
 Volume 6: Introduction to security, RACF, Digital certificates and PKI, timely technical information
Kerberos, cryptography and z990 integrated cryptography, System z based on realistic scenarios.
firewall technologies, LDAP, EIM, and firewall technologies Specific recommendations
 Volume 7: Printing in a z/OS environment, Infoprint Server and Infoprint are provided to help you
Central implement IT solutions more
effectively in your
 Volume 8: An introduction to z/OS problem diagnosis
environment.
 Volume 9: z/OS UNIX System Services
 Volume 10: Introduction to z/Architecture, System z processor design,
System z connectivity, LPAR concepts, HCD, and HMC
 Volume 11: Capacity planning, performance management, WLM, RMF, and For more information:
SMF ibm.com/redbooks

SG24-6986-00 ISBN 0738485349