DMSPWCHK - Verify Logon Password

Read syntax diagramSkip visual syntax diagram DMSPWCHK , retcode , userid , password , targetid ,token,logdata,length1,length2

Call Format

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

DMSPWCHK
(input, CHAR, 8) can be passed as a literal or in a variable.

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

Purpose

Use the DMSPWCHK routine to verify that a particular user ID and password are valid and, optionally, to verify that a user is permitted to “LOGON BY” to another user.

DMSPASS is the preferred routine for password verification. Any applications that support long passwords and password phrases must use DMSPASS.

Parameters

retcode
(output, INT, 4) is a variable for the return code from DMSPWCHK.
userid
(input, CHAR, 8) is a variable for specifying the VM user ID to be checked.
password
(input, CHAR, 8) is a variable for specifying the VM password for userid.
targetid
(input, CHAR, 8) is a variable for specifying another user ID. DMSPWCHK will verify that userid has LOGON BY privileges to targetid. If targetid is specified as nulls, this check will not be performed.
token
(input, CHAR, 4) is a variable for specifying a security token. If token is omitted, or the value of the token is zero, then native CP security services will be used to validate the user information. If the value of the token is nonzero, standard external security manager services will be used. If the value of the token is 1 (X'00000001'), then external security services will be used, but the token will not be passed to the security service. If the value of the token is -1 (X'FFFFFFFF'), then RACROUTE will be called without an ACEE.
logdata
(output, CHAR, length1) is a variable that may contain arbitrary readable text passed from the CSL routine to the calling application. This text is used to more fully describe any error conditions.
Note: This text may or may not be used by the calling application.
length1
(input, INT, 4) is a variable for specifying the length of the logdata field. A value of zero indicates that no text is to be returned by DMSPWCHK. The maximum value is 256.
length2
(output, INT, 4) is a variable in which DMSPWCHK specifies the length of the text that it placed in logdata. A value of zero indicates that no text is present.

Usage Notes

  1. The issuing virtual machine must have OPTION DIAG88 specified in the CP directory entry.
  2. For information on “LOGON BY”, see the LOGON command in the z/VM: CP Commands and Utilities Reference or online help and the LOGONBY directory control statement in the z/VM: CP Planning and Administration.
  3. DMSPWCHK communicates with the external security manager using standard interfaces, as shown in the following table:
    Access control External Security Manager Interface Minimum Access Required
    Password verification The following CMS command is used:
    RPIVAL userid password
    Application dependent
    LOGON BY privilege The RACROUTE macro is used with these parameters:
    REQUEST=AUTH
    CLASS=SURROGAT
    ENTITYX=LOGONBY.targetid
    USERID=userid
    READ

Information about RACROUTE can be found in the z/VM: Security Server RACROUTE Macro Reference. Information about the RPIVAL command can be found in RACF Macros and Interfaces.

Return Codes and Reason Codes

The following table lists the DMSPWCHK return codes.

Return Code Description
0 Requested access is allowed.
4 Password is correct but has expired (external security manager only)
8 userid or password is not valid, or userid does not have LOGON BY privileges to targetid.
24 System paging I/O error.
28 No decision could be made (valid with external security manager only). The RPIVAL program could not be run, or the external security manager is inactive.
32 Function not authorized. See Usage Note 1.
36 Function not available.
40 Password has expired (valid with external security manager only).
-1nn Parameter nn is not valid.