Using the command authorization service

Command processors that need to find out whether a user is RACF-authorized to issue a command, should use the command authorization service. If you are not sure whether your command processor should use this service, check with your installation security administrator. Use of the command authorization service increases the path length required to process a command.

To use the command authorization service, a command processor issues the CMDAUTH macro. The service provides a return code that indicates the user's authorization status. Under certain conditions, the command authorization service is unable to make a decision. For example, a decision cannot be made if RACF® 1.9 or later is not installed or is inactive. A return code and reason code together indicate why a decision could not be made. IBM® recommends the use of this service by all command processors that must verify the authorization status of a user.

The CMDAUTH macro has a number of keywords that are functionally equivalent to corresponding RACROUTE macro keywords. These keywords have the same characteristics as their corresponding RACF macro keywords. The following discussion identifies these keywords. The CMDAUTH macro is described in z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN. The RACF macros are described in z/OS Security Server RACF Macros and Interfaces.

The CMDAUTH macro has several required keywords. To indicate whether you want the list form or the execute form of the macro, use the MF keyword. You must also supply the resource name of the command being checked and indicate the access authority for which the service is to check. For an explanation of how to create a command resource name, see Command resource names. To provide the resource name, use the ENTITY keyword. To indicate the access authority, use the ATTR keyword. The ENTITY keyword and the ATTR keyword correspond to similar keywords on the REQUEST=AUTH form of the RACROUTE macro.

In addition, the CMDAUTH macro requires one of the following:

The command text that is to be authority checked and the user security token that is to be used for the authority check. The LOGSTR keyword identifies the information that is to be included in the RACF SMF PROCESS records and the UTOKEN keyword identifies the user security token. These keywords correspond to similar keywords on the REQUEST=AUTH form of the RACROUTE macro. If you need to obtain a user security token, see z/OS Security Server RACF Macros and Interfaces for information on how to use the REQUEST=TOKENXTR form of the RACROUTE macro.
A command input buffer (CIB), and an indication that you have provided a CIB. The CNTLBLK keyword identifies the CIB and the CBLKTYPE keyword indicates that you have provided a CIB.

The CMDAUTH macro also has several optional keywords. Each of these keywords correspond to similar keywords on the RACROUTE macro.

The keywords MSGRTN, MSGSUPP, and MSGSP enable you to control the routing of messages related to your request. To indicate whether you want messages returned to your program, use the MSGRTN keyword. The default is to not return messages. To indicate whether you want to suppress messages issued by SAF and RACF, use the MSGSUPP keyword. If you do not want the operator to see the messages, suppress them. The default is to not suppress these messages. If messages are returned to your program, by default the system returns them to subpool 229. If you want the messages returned to a different subpool, use the MSGSP keyword to identify the subpool.
To provide a control point name to RACF, use the REQSTOR keyword. To find out which control point names you can use, see your RACF administrator.
To provide RACF with the name of the calling subsystem, use the SUBSYS keyword. To find out which subsystem names you can use, see your RACF administrator.