USERPASS User Exit (CA VM:Secure Only)

Reference Guide › User Exit Reference › USERPASS User Exit (CA VM:Secure Only)

USERPASS User Exit (CA VM:Secure Only)

Use the USERPASS user exit to determine what action is taken if the maximum number of invalid logon password attempts is issued by the same user ID.

This exit is valid only if the Rules Facility is implemented.

USERPASS userid termaddr [logonid|userid2] pswd date time termtype

Definitions

userid

Specifies the user ID being logged on. Special users should be exempted from action taken in this user exit. This prevents a malicious user from disabling user IDs that are necessary for normal operation of the system. At least one of these special user IDs should have RESET or JOURNAL authorization in the AUTHORIZ CONFIG file.

termaddr

Specifies the terminal address from which the LOGON or LOGONBY command was issued. Exempt switched terminals from action taken in this user exit, because their addresses are not significant.

Note: For more information, see Terminal Addresses.

Possible forms of termaddr are:

termaddr	Meaning
nnnn	Address of a real terminal device, represented by four hexadecimal digits. (Example: 0024)
Lnnnn	Address of a logical device, represented by an L and four hexadecimal digits. (Example: L0123)
nnn.nnn.nnn.nnn	Address of a TN3270 connected terminal, represented by an eight‑character hexadecimal representation of the standard dotted IPv4 address form. (Example: 0A005933 represents the dotted IP address 10.0.89.51)
nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn	Address of an IPv6 TN3270 connected terminal, represented by a standard IPv6 address.
nnnnnnnn	Address of an SNA or VTAM logical unit name. (Example: WEST0016)

logonid

Specifies the temporary ID assigned to a VMDBK at logon time.

userid2

Specifies the user ID that attempted to log on to the userid using LOGONBY.

pswd

Specifies the invalid password supplied at the last logon attempt.

If you are configured for password phrases, then the pswd will be a quoted string if it contains imbedded blanks.

The sample user exit provided illustrates the techniques needed for parsing quoted strings.

date

Specifies the date in mm/dd/yy format when the user reached the maximum number of invalid password attempts as specified on the JOURNAL record in the SECURITY CONFIG file.

time

The time in hh:mm:ss format when the user reached the maximum number of invalid passwords attempts as specified on the JOURNAL record in the SECURITY CONFIG file.

termtype

Specifies the type of terminal from which access was attempted under the LOGONBY Facility, or the LOGON, LOGON BY, DIAL, or from a Diagnose X’A0’ subcode 4 command.

termtype	Means the address passed is:
REAL	A real terminal device
LDEV	A logical device
IPADDR	A TN3270 connected terminal
NETID	The address of an SNA or VTAM logical unit name
DISC	From a disconnected terminal

Return Codes

The following table describes the return codes:

Return Code	Meaning

0	JOURNAL record count for userid is reset to zero
4	Invalid password journal count is maintained. Further attempts to access this userid from this specific terminal are disallowed.
8	JOURNAL record count for userid is reset to zero and a rule is added to the appropriate file; the rule prevents any terminal from logging on to user ID userid unless there are overriding rules that allow logon attempts:
	For this command	This rule is added (NOTIFY option is used internally by CA VM:Secure to indicate that the REJECT rule was added dynamically after an invalid logon attempt threshold was reached)	To file
	LOGON	REJECT * LOGON (NOTIFY	User rules
	LOGONBY	REJECT userid LOGONBY	OVERRIDE SYSRULES
	LOGONBY	REJECT userid LOGONBY (NOTIFY	User rules
	Password validation function	REJECT userid VALIDATE (NOTIFY	User rules

Macros

CA VM:Secure calls the USERPASS user exit when the number of invalid logon password attempts from the same user ID reaches the maximum, defined on the JOURNAL record in the SECURITY CONFIG file.