DMSPWCHK - Verify Logon Password
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
- The issuing virtual machine must have OPTION DIAG88 specified in the CP directory entry.
- 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.
- 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 passwordApplication dependent LOGON BY privilege The RACROUTE macro is used with these parameters: REQUEST=AUTH
CLASS=SURROGAT
ENTITYX=LOGONBY.targetid
USERID=useridREAD
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. |