User ID Security Exit Support › Logon Request Parameter List

Logon Request Parameter List

On entry to the security exit, Register 1 points to a list of ten full words, as shown in this diagram.

The contents of the parameter list are as follows:

• Word 1

  Is a full word containing the address of function code F'8'.

• Word 2

  Is the address of a subfunction code. This code defines the type of logon request being processed and has values set as follows:

  Subfunction Code	Value
  F'0'	Logon from native terminal
  F'4'	Logon from TSO interface component of EIP
  F'8'	Logon from ROF user
  F'12'	System console logon
  F'16'	System environment logon
  F'20'	Reserved
  F'24'	Reserved
  F'28'	APPC user region logon
  F'32'	Reserved

• Word 3

  Is the address of an 8-character field, blank padded, containing the user ID requesting the logon. If a partial security exit is installed then there is an additional, contiguous 8-character field, blank-padded containing the model user ID specified by the SYSPARMS MODLUSER operand. If no model user has been specified this field is set to blanks.

• Word 4

  Is the address of two full words. These words are as follows:

  • First word—can contain any value to relate a user to a set of control blocks or other information maintained by the exit in relation to that user
  • Second word—the address of the user token (UTOKEN) obtained from the SAF logon call is placed in the second full word

    These values are returned in all subsequent calls to the exit in reference to this user ID session, so that it can be used as a session correlator.

• Word 5

  Varies according to subfunction code.

  Subfunction Code	Value
  F'0'	Word 5 contains the address of an 8-character field, blank-padded, which contains the name of the terminal at which the user wants to logon.
  F'4'	Word 5 contains the address of an 8-character field, blank-padded, which contains the name of the VTAM APPL name used by the TSO interface for this session.
  F'8'	Word 5 is set to zero.
  F'12'	Word 5 contains the address of an 8-character field holding the word CONSOLE, or the generated user ID for multiple console support (OS/VS systems only).
  F'16'	Word 5 contains the address of an 8-character field containing the name of the pseudo-terminal with which the system environment logon is associated.
  F'28'	Word 5 is set to zero.

• Word 6

  Varies according to subfunction code.

  Subfunction Code	Value
  F'0'	Word 6 contains the address of an 8-character field, blank-padded, containing the password entered with the user ID.
  F'4'	Word 6 is set to zero.
  F'8'	Word 6 contains the address of an 8-character field, blank-padded, holding the password entered on a SIGNON command from the remote region. If no password was entered, this word is zero.
  F'12'	Word 6 is set to zero.
  F'16'	Word 6 is set to zero.
  F'28'	Word 6 contains the address of an 8-character field, blank-padded, holding the password specified on the APPC NCL verb that started this region. If no password was entered, this word is zero.
  F'36'	Web user logon.

• Word 7

  Is set to zero.

• Word 8

  Is the address of an 82-character area into which the exit can place any error message text if the logon request is denied. Any text placed in this area is displayed to the user in response to the logon attempt. If an error message is returned in this area it must be formatted as follows:

  • Bytes 00 to 01

    Specifies the hexadecimal length of the message text (excluding these two bytes).

  • Bytes 02 to nn

    Specifies the error message text.

    Limits: 80 characters

    Error message text is converted to upper case.

• Word 9

  Varies according to subfunction code.

  Subfunction Code	Value
  F'0'	Word 9 set to zero.
  F'4'	Word 9 set to zero.
  F'8'	Address of 12-character area holding the INMC link name of the system from which a ROF logon request has been received. This is followed by a 4-character field which is either zero or contains the domain ID of the system from which the SIGNON request originated. Following this is a 1-byte binary field with flag settings as follows: X'01' - A character domain ID is present after the 12-character link name. X'02' - Is set if the system represented by domain ID is different from the system represented by the link name.
  F'12'	Word 9 set to zero.
  F'16'	Word 9 set to zero.
  F'28'	Word 9 set to zero.

• Word 10

  Depends on whether you have a full or partial security system:

  • Full security exit—the logon is accepted and the exit must provide the address of a list of full words in this field, terminated by X'FFFFFFFF'.

    Each word in this list contains the address of a structured field defining an item of information for this user ID. Your region processes all these structured fields to determine the privileges and other information to be associated with the user ID.

  • Partial security exit—set to zero, or the address of a variable length list of full words, ended by a full word of X'FFFFFFFF'.

    Each word in the area points to a single structured field, representing one attribute of the current UAMS definition for the user ID pointed to by word 3 of the parameter list.

    If the requesting user ID is not defined on UAMS, Word 10 is zero.

Return Codes from Logon Call

The exit must return a completion code in Register 15 on return. Completion codes are supported as described below. Specific causes for logon rejection are identified by error message text returned in the area addressed by word 8 of the Logon Call parameter list.

These return codes are the only codes that are accepted in response to a logon call. Any other return code is treated as indicating that the logon is rejected.

• 0

  Indicates that logon is accepted without error.

• 4

  Indicates that logon is accepted but password has expired. Your product region must enforce password renewal before the user has access to any other functions.

• 8

  Indicates that logon is accepted but this is a new user ID. Your product region must enforce password change before allowing the user access to any other functions.

• 12

  Is reserved and cannot be used as a return code.

• 16

  Indicates that logon is rejected. Password is incorrect, but your product region is to allow a retry.

• 20

  Indicates that logon is rejected. Password is incorrect and no retry is to be permitted. A violation message is logged.

• 24

  Indicates that logon is rejected. An error message explaining the cause of rejection is available in the 82-character area addressed by word 8 of the parameter list. The format of this area must be a 2-byte length field set to contain the length of the error message text, followed by up to 80 characters of error message text. If the logon was from a TSO user, the error message is not displayed; the normal product region logon panel is presented for entry of user ID and password and the user is not classified as a TSO interface user.

Note: Return codes 16 and 20 are provided to give compatibility with the standard UAMS functions, which provide a maximum number of password retries before rejecting the logon attempt and logging a violation message.

Return codes 4 and 8 provide compatibility with the UAMS convention of enforcing password change at logon time if the user's password has expired, or for the first logon of a new user ID.

The exit might not be able to determine that a user ID is new, depending upon the information available to it from the external security system in use. If required, the exit can be written to provide two return codes only, 0 or 24, with an appropriate error message if the logon is rejected.

The ability to deny a logon with return code 24 and an error message of the exit's choice allows the installation to extend the security exit's function beyond that of simple password validation. For example, the exit might deny logons after a certain time of day or reject ROF logons from certain remote systems.

System console and system environment logon calls take default attributes if the exit causes the logon to fail.