DMSESM - Identify Program to External Security Manager

Call Format

The format for calling a CSL routine is language dependent. The routine name is the first parameter in DMSCSL’s parameter list:

DMSESM

(input, CHAR, 8) can be passed as a literal or in a variable. DMSESM must be padded with blanks to eight characters.

For more information and examples of the call formats, see Calling VMLIB CSL Routines.

Purpose

Use the DMSESM routine to identify your program to an External Security Manager (ESM). Your program will receive an identifying token for use with other ESM-related CSL routines or the RACROUTE macro.

Parameters

retcode

(output, INT, 4) is a variable for the return code from DMSESM.

CREATE_TOKEN

(input, CHAR, 12) establishes a security environment within the ESM and obtains a token by which that environment may be identified on subsequent ESM-related calls.

DELETE_TOKEN

(input, CHAR, 12) releases the specified security token and deletes the ESM environment the token represents.

length

(input, INT, 4) is a variable for specifying the length of the preceding character parameter (CREATE_TOKEN or DELETE_TOKEN).

ESMrc

(output, INT, 4) is a variable for the return code from the external security manager.

ESMreason

(output, INT, 4) is a variable for the reason code from the external security manager.

token

(input/output, CHAR, 4) is a variable for a security token.

For a CREATE_TOKEN request, if retcode, ESMrc, and ESMreason are zero, DMSESM returns a value in token that may be used on other ESM-related calls such as DMSLINK and DMSPWCHK.

For a DELETE_TOKEN request, you should specify a value in token that was returned by a previous CREATE_TOKEN request.

Usage Notes

1. The ESM environment must be established before a call to DMSESM is made. For RACF/VM, this is done using the RPIUCMS INIT command. Other ESMs may have their own procedures.
2. DMSESM communicates with the external security manager using the RACROUTE REQUEST=VERIFY macro interface. A nonzero ACEE is expected to be returned for all successful CREATE_TOKEN requests. Additional information about this interface can be found in the z/VM: Security Server RACROUTE Macro Reference.
3. TCP/IP for z/VM® provides an RPIDUMY command that can be used in place of RPIUCMS. This command returns a nonzero token, but will respond “defer” if any subsequent RACROUTE macro calls are made.

Return Codes and Reason Codes

The following table lists the DMSESM return codes.

External security manager return and reason codes are specific to the security product being used. For RACF/VM, refer to Usage Note 2. For other security products, consult the product documentation.