IBM_Server_GC28-1920-01

Macros

Contents

Notices . . . . . . . . . . . . . . . . . . . xi. . . .

Trademarks . . . . . . . . . . . . . . . . . . xii. . . .

About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . xiii. . . . . .

Who Should Use This Book. . . . . . . . . . . . . . . . . . . . . . .xiii. . . . . .

How to Use This .Book. . . . . . . . . . . . . . . . . . . . . . . .xiii. . . . . .

Where to Find More Information. . . . . . . . . . . . . . . . . . . . .xiv. . . . . .

Function Not Upgraded. . . . . . . . . . . . . . . . . . . . . . . . 12. . . . . .

. . . . . . . . . . . . . . . . . . . .17 . . . .

??? Copyright IBM Corp. 1994, 1996

Virtual Storage . . . . . . . . . . . . . . . . . 32. . . . .

Customer Additions to the .CDT. . . . . . . . . . . . . . . . . . . .33. . . . . .

SOMobjects for MVS. . . . . . . . . . . . . . . . . . . . . . . . . .42. . . . . . .

SystemView for MVS . . . . . . . . . . . . . . . . . . . . . . . . .43. . . . . . .

vi OS/390 V1R2.0 Security Server (RACF) Planning: Installation and Migration

Figures

10.Changes to PSPI Data Areas. . . . . . . . . . . . . . . . . . . 16. . . . . .

11.Changed Exits for RACF. . . . . . . . . . . . . . . . . . . . . .17. . . . .

12.Changed Macros for RACF. . . . . . . . . . . . . . . . . . . . .17. . . . . .

13.Changed Panels for RACF. . . . . . . . . . . . . . . . . . . . .19. . . . . .

14. Changes to the RACF Publications . Library. . . . . . . . . . . . . 19. . . .

15.Changes to Routines. . . . . . . . . . . . . . . . . . . . . . .19. . . . . .

16.Changes to SYS1.SAMPLIB . . . . . . . . . . . . . . . . . . . . 20. . . . . .

17.Changes to Templates. . . . . . . . . . . . . . . . . . . . . . 21. . . . . .

18.Changes to Utilities. . . . . . . . . . . . . . . . . . . . . . . .22. . . . .

19. Software Requirements for New Function. . . . . . . . . . . . . . 25. . . .

20. JCL to Rename the Workspace Data. . .Sets. . . . . . . . . . . 30. . . .

21.RACF Estimated Storage Usage. . . . . . . . . . . . . . . . . .32. . . . .

22.New Event Codes. . . . . . . . . . . . . . . . . . . . . . . . 45. . . . . .

23.Changes to SMF Records. . . . . . . . . . . . . . . . . . . . .45. . . . . .

24. An RRSF Network Where Two Single System Nodes Share a RACF

Database . . . . . . . . . . . . . . . . . 61. . . .

??? Copyright IBM Corp. 1994, 1996

Notices

equivalent product, program, or service which does not infringe on any intellectual property rights may be used instead of the IBM produc service. Evaluation and verification of operation in conjunction with oth programs, or services, except those expressly designated by IBM, i responsibility.

??? Copyright IBM Corp. 1994, 1996

This book is organized in the following order:

?? Chapter 6, ???Customization Considerations??? on page 35, highlights informat about customizing function to take advantage of new support after release of RACF is installed.

??? Copyright IBM Corp. 1994, 1996

xiii

??Chapter 9, ???Operational Considerations??? on page 49, summarizes changes t operating procedures for the new release of RACF.

??Chapter 10, ???Application Development Considerations??? on page 51, identifie changes in the new release of RACF that might require changes to

installation's existing programs.

xiv OS/390 V1R2.0 Security Server (RACF) Planning: Installation and Migration

RACF Courses

??Introduction to System and Network Security: Considerations, Options, Techniques, GG24-3451

?? Network Security Involving the NetView Family ofGG24Products,-3524

?? System/390 MVS Sysplex Hardware and Software Migration,GC28-1210

?? Secured Single Signon in a Client/Server Environment,GG24-4282

?? Tutorial: Options for Tuning GG22RACF, -9396

Other books are available, but they are not included in this list information they present has been incorporated into IBM product manua because their technical content is outdated.

About This Book xv

Other Sources of Information

IBM provides customer-accessible discussion areas where RACF may be discussed by customer and IBM participants. Other information is availa the Internet.

Internet Sources

The following resources are available through the Internet:

??RACF home page

You can visit the RACF home page on the World Wide Web using this http://www.s39??.ibm.com/products/racf/racfhp.html

??RACF-L discussion list

Customers and IBM participants may also discuss RACF on the RACF-L discussion list. RACF-L is not operated or sponsored by IBM; it is r

xvi OS/390 V1R2.0 Security Server (RACF) Planning: Installation and Migration

???Installation-written code

???Operational procedures

???Application programs

The content and extent of a migration plan can vary significantly from installation. To successfully migrate to a new release of RACF, you sh installing and stabilizing the new RACF release without activating the n

with the new RACF release gives detailed information about the corre required for installation.

When defining your installation's migration plan, you should consider the

??Migration

??Installation

??Customization

??Administration

??Auditing

??Operation

??Application development

??General users

Chapter 13, ???Scenarios??? on page 61 contains scenarios that might help defining your migration plan.

Migration Planning Considerations

Installation Considerations

Before installing a new release of RACF, you must determine what updat needed for IBM-supplied products, system libraries, and non-IBM product

Be sure you include the following steps when planning your pre-installatio activities:

?? Contact programmers responsible for updating programs.

For more information, see Chapter 5, ???Installation Considerations??? on page 2

Customization Considerations

ensure that RACF runs as before or to accommodate new security contro installation requires.

For more information, see Chapter 6, ???Customization Considerations??? on page

Administration Considerations

For more information, see Chapter 7, ???Administration Considerations??? on page

2 OS/390 V1R2.0 Security Server (RACF) Planning: Installation and Migration

Auditing Considerations

Operational Considerations

The installation of a new product release might introduce changes to characteristics. These changes can be in the form of changed command changed messages, or methods of implementing new functions. This book

Application Development Considerations

Application development programmers must be aware of new functions intro in a new release of RACF. To implement a new function, the application development personnel should read this book and the following books:

??OS/390 Security Server External Security Interface (RACROUTE) Macro Reference,

General User Considerations

RACF general users use a RACF-protected system to:

?? Log on to the system

?? Access resources on the system

??Protect their own resources and any group resources to which the administrative authority

This book provides an overview of the changes that might affect ex procedures for general users. For more information, see Chapter 11, ???G User Considerations??? on page 55.

Chapter 1. Planning for Migration3

The RACF support for OS/390 OpenEdition DCE includes:

???ADDUSER

???ALTUSER

???LISTUSER

the RACF database and to create cross-linking information between the database and the DCE principal registry:

??MVSIMPT

??MVSEXPT

For more information on these utilities,OpenEditionseeDCE Administration .Guide

RACF interoperation with DCE requires the following software:

Chapter 2. Release Overview7

OS/390 OpenEdition

OS/390 Release 2 OpenEdition adds new capabilities for which RACF provid support.

Authorizing and Auditing Server Access to the CCS and WLM

Services

OS/390 Release 2 OpenEdition adds the capability to check whether ser

process to another. A sending process opens a file and passes the op

?? The access rights are passed by the sending process.

?? The access rights are received by the receiving process.

??The access rights are discarded by the receiving process without received.

SOMobjects for MVS

RACF provides support for Version 1 Release 2 of SOMobjects for MVS. A

SystemView for MVS

SystemView for MVS consists of programs that run on the user's workstati programs that run on MVS. SystemView for MVS displaysLaunch windowa that

contains a customized task treetask .treeThisrepresents systems management

programs, or applications, to which the workstation user can get access

8 OS/390 V1R2.0 Security Server (RACF) Planning: Installation and Migration

It is possible to define a multisystem node that contains only one sy configuration might be useful as a migration path.

The RACF support for multisystem RRSF nodes includes:

?? Enhancements to the TARGET command to allow system programmers to configure multisystem RRSF nodes

?? Enhancements to the RESTART command to allow operators to restart connections to systems in multisystem RRSF nodes

??A new naming convention for the workspace data sets used by RACF fo communications

?? A new connection state,definedthe state

Year 2000

RACF dates are 3-byte packed decimal fieldsyydddF.in Thisthe format does

not allow the first two characters of the year to be specified. I acceptable to assume that the date is in the twentieth century, and characters of the '19year'. However,are as the end of the twentieth century

10 OS/390 V1R2.0 Security Server (RACF) Planning: Installation and Migration

?? Class descriptor table (CDT)

??Commands

??Data Areas

??Exits

??Macros

??Messages

??Panels

??Publications Library

??Routines

??SYS1.SAMPLIB

??Templates

??Utilities

Class Descriptor Table (CDT)

Figure 6 lists the new classes provided in the IBM-supplied class des (ICHRRCDX). For each class, a corresponding entry has been added to IBM-supplied router table (ICHRFR0X). The class names (when the classe profiles) are general-use programming interfaces (GUPI) for ICHEINTY a

RACROUTE.

For more information, OS/390see Security Server (RACF) Macros and .Interfaces

New Messages

Changed Messages

The following messages are changed:

RRSF Handshaking Messages:IRRI000I, IRRI001I, IRRI004I, IRRI005I,

IRRI011I, IRRI012I, IRRI013I

18 OS/390 V1R2.0 Security Server (RACF) Planning: Installation and Migration

Panels

Publications Library

Figure 14 lists changes to the OS/390 Security Server (RACF) publication

Routines

Figure 15 lists a new routine for RACF. The interface to this routine general-use programming interface (GUPI).

Chapter 3. Summary of Changes to RACF Components for OS/390 19Release 2

Chapter 4. Planning Considerations

This chapter describes the following high-level planning considerations f customers upgrading to Security Server (RACF) Release 2 from Security (RACF) Release 1:

??Migration strategy

??Migration paths

??Hardware requirements

??Software requirements

??Compatibility

Migration Strategy

?? From RACF releases prior to 1.9

If you are on a RACF release prior to 1.9, you must install RACF 1 restructure your database, and perform appropriate testing of any installation-supplied code that uses ICHEINTY or RACROUTE

contact your IBM representative for assistance.) Then, if you meet

??? RACF Planning: Installation and Migrationfor RACF 2.1,

??? RACF Migration and Planning for RACF 1.9.2, and

??? RACF Migration and Planning for RACF 1.9.

Hardware Requirements

For systems in a multisystem RRSF node, we recommend placing:

RACF cannot ensure that the systems in a multisystem RRSF node share a database. The system programmer must ensure that the RACF database for

Software Requirements

24 OS/390 V1R2.0 Security Server (RACF) Planning: Installation and Migration

Compatibility

This section describes considerations for compatibility between OS/390 Security Server (RACF) and OS/390 Release 1 Security Server (RACF).

Compatibility Considerations for Remote Sharing

Multisystem node support requires a change to the names of the works sets used by the RACF remote sharing facility (RRSF). If your insta

Chapter 4. Planning Considerations25

Chapter 5. Installation Considerations

?? Enabling RACF

?? Considerations for RRSF networks

?? Virtual storage considerations

?? Customer additions to the CDT

?? Templates

Enabling RACF

PRODUCT OWNER('IBM CORP')

NAME('OS/39??')

FEATURENAME('Security Server')

ID(5645-????1)

VERSION(\)

RELEASE(\)

MOD(\)

STATE(ENABLED)

The naming convention for the workspace data sets for remote connections

prefix.local_luname.remote_luname.ds_identity

1. Warn users of this migration. Start this process at a time appropr installation. Pay particular attention to the effects of locking the

return code of 4, but locks the database. Locking the database p

It is important to completely finish step 2 before locking the dat Otherwise, pending update requests already received from remote no result in abends, and could cause the out-of-sync condition that thi attempting to prevent.

//\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\//

Figure 20 (Part 1 of 2). JCL to Rename the Workspace Data Sets

30 OS/390 V1R2.0 Security Server (RACF) Planning: Installation and Migration

//RRSFALTR JOB 'JOB TO RENAME WORKSPACE DATA SETS',MSGLEVEL=???1,1 //\

//\ USE A JOBCAT OR STEPCAT WHERE NEEDED TO POINT TO THE CATAL???OG

//\ THAT CONTAINS THE INFORMATION NEEDED FOR YOUR DATA SETS???. //\

//\ THE WORKSPACE DATA SETS THAT BACKUP THE RRSF TRANSACTIO???NS SENT TO

//\ AND RECEIVED FROM OTHER SYSTEMS SHOULD BE CHANGED AS FOL???LOWS:

ALTER - prefix.local-node.remote-node.INMSG -

NEWNAME(prefix.local-lu.remote-lu.INMSG)

ALTER - prefix.local-node.remote-node.INMSG.INDEX -

NEWNAME(prefix.local-lu.remote-lu.INMSG.INDEX)

ALTER - prefix.local-node.remote-node.INMSG.DATA -

NEWNAME(prefix.local-lu.remote-lu.INMSG.DATA)

ALTER - prefix.local-node.remote-node.OUTMSG -

NEWNAME(prefix.local-lu.remote-lu.OUTMSG)

ALTER - prefix.local-node.remote-node.OUTMSG.INDEX -

NEWNAME(prefix.local-lu.remote-lu.OUTMSG.INDEX)

ALTER - prefix.local-node.remote-node.OUTMSG.DATA -

NEWNAME(prefix.local-lu.remote-lu.OUTMSG.DATA)

Figure 20 (Part 2 of 2). JCL to Rename the Workspace Data Sets

Chapter 5. Installation Considerations31

RACF Storage Considerations

This section discusses storage considerations for RACF.

Virtual Storage

Figure 21 estimates RACF virtual storage usage, for planning purposes.

Formula for average_profile_size:

average_profile_size = 51 + average_installation_data + (average_number?? 9)_of+_access_entries (average_number_of_categories?? 2) + (average_number_of_conditional_access?? 17)_entries

32 OS/390 V1R2.0 Security Server (RACF) Planning: Installation and Migration

Formula for average_profile_size:

average_profile_size = 51 + average_installation_data + (average_number?? 9)_of+_access_entries (average_number_of_categories?? 2) + (average_number_of_conditional_access?? 17)_entries

Customer Additions to the CDT

Additional classes can be defined in the CDT during installation, or t customized later. See ???Customer Additions to the CDT??? on page 35 for information on installation-defined CDT classes.

Chapter 5. Installation Considerations33

Chapter 6. Customization Considerations

This chapter identifies customization considerations for RACF.

For additional information,OS/390see Security Server (RACF) System

Programmer's Guide.

Customer Additions to the CDT

??For a duplicate router table entry, RACF issues this message and processing:ICH527I RACF DETECTED AN ERROR IN THE INSTALLATION ROUTER???

TABLE, ENTRY class_name, ERROR CODE 1.

?? For a duplicate CDT entry, RACF issues this message and enters fa

ICH511I RACF DETECTED AN ERROR IN THE INSTALLATION CLASS ???DESCRIPTOR

TABLE, ENTRY class_name, ERROR CODE 7.

If a conflict in class names occurs, you must delete the profiles

Exit Processing

Installation-written exits might be affected by new function introduce Release 2 Security Server (RACF).

RACROUTE REQUEST=DEFINE Preprocessing Exit (ICHRDX01)

Processing of a RETPD value specified via the RACROUTE REQUEST=DEFINE preprocessing exit has changed. Formerly, a RETPD value specified in an ICHRDX01 exit was not recorded in the profile when a generic profile defined, unless RETPD was also specified via command. Now, a RETPD value

36 OS/390 V1R2.0 Security Server (RACF) Planning: Installation and Migration

?? Multithreaded applications

?? Single threaded applications

A multithreadedapplication has multiple sequential flows of control. In th application, more than one unit of work at a time is processed by application.

A single threadedapplication has one sequential flow of control. In this

the security environment of a thread, meaning that the thread can e

Chapter 7. Administration Considerations39

OpenEdition Planning, and inOS/390 OpenEdition Programming: Assembler Callable Services Reference. The C language support for the pthread_security_np() function is discussedOS/390 inR2 C/C++ Run-Time Library Reference.

a thread that processes the client's request. If the server customiz initiated for the client with the client's RACF identity, any resource

The use ofpthreadthesecurity_np service is partially protected through a FACILITY class profile BPX.SERVER.

??Application servers that have UPDATE access to this profile can act surrogate of the2 Thisclientmeans. that only the client's RACF identity and

authorizations are used in resource access decisions processed by

This additional security checking might require additional RACF administra authorize the server to the RACF resource profiles that the server behalf of its clients.

Changes to RACF Authorization Processing

RACF support for OpenEdition DCE introduces new indicators in the ACEE. Th

There are two types of client ACEEs:

?? Unauthenticated client ACEE

with the current task. If the request is successful, the sec performed.

The automatic checking of both the client's identity and the serv performed for RACF resources defined to RACF via profiles and for

??Authenticated client ACEE

When an authenticated client ACEE is used in an access control dec this ACEE is used in the access control decision. Audit records c additional relocate section, indicating that this authorization requ processed using an ACEE which was created on behalf of an unautho application.

An authenticated client ACEE is created when the client of the se application has supplied its RACF password (or RACF PassTicket) to th

Restrictions

??RACROUTE REQUEST=FASTAUTH processing has not been enhanced to automatically check both the server and client RACF identities.

Ideally, application servers on OS/390 do not have to run APF-authori supervisor state or in a system storage protection key. Unauthori application servers on OS/390 are therefore unable to use the RACR REQUEST=LIST instruction to build in-storage profiles for RACF-defined

Chapter 7. Administration Considerations41

decision, application servers that the security administrator does not

identity pair is not propagated to other applications or servers. The administrator must enforce this through administrative procedures by ens applications servers that do not meet notthisauthorizedcriteria areto the profile BPX.SERVER in the RACF FACILITY class. By denying the untrusted servers

Check your installation for programs that use:

?? the SAF R_dceruid callable service

SOMobjects for MVS

within the new RACF CBIND and SOMDOBJS classes. In addition, the securit

42 OS/390 V1R2.0 Security Server (RACF) Planning: Installation and Migration

SystemView for MVS

?? Authorize SystemView for MVS users to access the defined applica SystemView for MVS Launch window.

For information about SystemView for MVS and the Launch window, see

SystemView for MVS Up and Running!.

Chapter 7. Administration Considerations43

??Unauthenticated client

??Authenticated client

??Server

??Unauthenticated client

??Authenticated client

??Server

class automatically receive the new SMF records. These customers might s increase in the number of SMF records that RACF writes during OpenEditio processing.

46 OS/390 V1R2.0 Security Server (RACF) Planning: Installation and Migration

?? Multithreaded applications

?? Single threaded applications

A multithreadedapplication has multiple sequential flows of control. In a multithreaded application, more than one unit of work at a time is p server application.

A single threadedapplication has one sequential flow of control. In a si threaded application, one unit of work is processed at a time by server.

The security administrator has the option of enforcing the use of bo application server's RACF identityand the RACF identity of the client in resourc access control decisions.

created by OS/390 OpenEdition and RACF on behalf of multithreaded unauth

There are two types of client ACEEs:

?? Unauthenticated client ACEE

with the current task. If the request is successful, the secon performed.

The automatic checking of both the client's identity and the server performed for RACF resources defined to RACF via profiles and for

??Authenticated client ACEE

For more information on the convert_id_np (BPX1CID) callableOS/390service, s

OpenEdition Programming: Assembler Callable Services Reference. The C language support for the __convert_id_np() OS/390is discussedR2 C/C++ in

Run-Time Library Reference

This change might require changes to customer code which uses these

?? RACROUTE REQUEST=FASTAUTH

IBM products should not need changes, because their usage of thes compatible with this change.

Programming Interfaces

?? ???Class Descriptor Table (CDT)??? on page 13

?? ???Data Areas??? on page 16

?? ???Exits??? on page 16

Chapter 10. Application Development Considerations53

?? Log on to the system

?? Access resources on the system

??Protect their own resources and any group resources to which the administrative authority

This chapter highlights new support that might affect general user p

OS/390 OpenEdition DCE

already been authenticated by RACF. However, the user must continue

Chapter 12. NJE Considerations

Several APARs shipped on OS/390 Release 2 Security Server (RACF) have implications for NJE.

APAR OW14451

group for jobs and the owning group for SYSOUT in the absence of a NODEID.GROUP%.GROUPID profiles. This service introduces the ability to

SET AUTODIRECT(NOTIFY(FAILURES(MIAMI1.ADMIN))

OUTPUT(FAILURES(MIAMI1.ADMIN)))

All autodirected output and notifications are sent to the main sys multisystem node.

Guide and the RACJCL member of SYS1.SAMPLIB for information on IRRBRW00.)

Note: Rerun the remaining commands after you complete step 5.

prefixSTOP

START subsystem-name,SUB=MSTR

5. Issue TARGET commands from the operator's console for the new multisystem node, MIAMI1:

prefixTARGET NODE(MIAMI1) DORMANT

prefixTARGET NODE(MIAMI1) SYSNAME(SYSTEM1) MAIN OPERATIVE

prefixTARGET NODE(MIAMI1) SYSNAME(SYSTEM2) OPERATIVE PREFIX(...) PROTOCOL(...) WORKSPACE(...)

Add these commands to the RACF parameter library for ORLANDO.

Remember to rerun remaining commands as noted in step 3.

Chapter 13. Scenarios63

prefixTARGET NODE(ORLANDO) OPERATIVE PREFIX(...) PROTOCOL(...) WORKSPACE(...)

Add this command to the RACF parameter library for SYSTEM2.

Note: The TARGET commands for SYSTEM1 and SYSTEM2 are now

64 OS/390 V1R2.0 Security Server (RACF) Planning: Installation and Migration

access to protected resources, logging detectedmayinteractively prompt and read commands from a

SAF . System authorization facility.

security . Seedata security.

of processing unit operations. Synonymsupervisoryfor routine.

Index

ADDUSER command 15 administration

classroom courses xv administration considerations

migration 2

Airline Control System/MVS, support for 11

BLKUPD utility

new return code 22

CBIND class 13

CCS, server access to 8

CDT

see class descriptor table (CDT)

console communications service, server access to 8 coupling facility structure rebuild 11

JCICSJCT class 14, 53

JCL for renaming workspace data sets 30

KCICSJCT class 14, 53

KEYSMSTR class 14

library, RACF publications changes to 19

LSQA

storage requirement 32

Index 75

Communicating Your Comments to IBM

OS/390

Security Server (RACF)

Planning: Installation and Migration

Publication No. GC28-1920-01

??? FAX: (International Access Code)+1+914+432-9405

?? If you prefer to send comments electronically, use this network ID:

Make sure to include the following in your note:

Reader's Comments ??? We'd Like to Hear from You

OS/390

Security Server (RACF)

Planning: Installation and Migration

Publication No. GC28-1920-01

it believes appropriate without incurring any obligation to you. Your comments will be

direct any requests for copies of publications, or for assistance in using your IB

Newsletter number of latest Technical Newsletter (if any) concerning this publication:

How did you use this publication?

Is there anything you especially like or dislike about the organization, presentation manual? Helpful comments include general usefulness of the book; possible additions, dele clarifications; specific errors and omissions.

Page Number:Comment:

Company or Organization

Phone No.

Reader's Comments ??? We'd Like to Hear from You

GC28-1920-01

IBM???

Cut or Fold

Along Line

Fold and Tape

NO POSTAGE

NECESSARY

IF MAILED IN THE

UNITED STATES