Signon and Signoff Exit

Signon and Signoff Exit
tpxsm54
The Signon and Signoff exit provides complete flexibility to the authorization and authentication process. It is invoked at a number of points during signon and signoff, as well as being called at Initialization and Termination.
The signon and signoff exit allows the installation to implement one or more of the following:
  • Generic signon
  • Dynamic user definition
  • Dynamic profile definition
  • Multiple authentication mechanisms
  • User-provided authentication
  • System affinity management
Profiles for Dynamic Users
If you do not use a signon and signoff exit, dynamic users are assigned the default profile specified in the System Options Table (SMRT), unless you are using user level or profile level profile selection with your security system. For more information, see Profile Selection for Dynamic Users in the section "Special Features and Customization Tasks."
Program and Link the Exit
You must program the signon and signoff exit as reentrant and link it into the load library with module name TPXUSNSF.
Register Contents
On entry, the registers contain the following:
  • R0 -- Function code
  • R1 -- Appropriate parameter list address
  • R11 -- SMRT address
  • R13 -- 72-byte save area
  • R14 -- Return address
  • R15 -- Entry point address
Function Code, Parameters, and Return Codes
The following table lists functions, parameters, return codes, and comments for the signon and signoff exit. The code for each function is shown in parenthesis to the right of the name of the function.
Function Codes
Parameters
Return Codes
Comments
CA TPX startup (0)
Builds user data areas required for subsequent exit requests.
N/A
0
 Always
This is a general purpose first call exit to permit the user to initialize the security environment. This exit is called from the initialization processes and will be called again if TPXONOFF abnormally terminates as a part of the TPXONOFF re-initialization process (the shutdown exit point is not called in this situation).
Signon data (4)
Inspects and modifies input signon.
See the Parameter List.
0
 Always
Alter Generic to real name or national character changes. The addresses of parameters 2 and 3 are unpredictable. The SMRTUADS field addresses the first UINDEX entry. UIDXNEXT can be used to chain through the in-storage user entries.
Pre-security (8)
Selects the security system.
See the Parameter List.
0
 Continue with signon.
4
 Reject the signon with the message supplied.
16
 Switch to the system named by the affinity parameter.
The UINDEX block that describes this user can be altered either to inhibit the call to the security package or to select a different package than the one coded in the profile or the system options table (SMRT). UIDXSCTY contains either zero (0) to indicate no security, or the value specified in the user's definition. You can assign one of the following values to this byte to select a different security mechanism:
X'80' CA TPX
X'40' RACF
X'20' CA ACF2
X'10' User (Code 12)
X'08' CA Top Secret
X'04' VM Security
X'02' SAF (RACF Security Access Facility if implemented)
X'01' Not applicable
Equates for these values can be found in the SMRT macro expansion as SEC$TPX, SEC$RACF, and so on.
You can also use this call to cause an Affinity switch to another system before the authentication process is started.
Security (12)
This is an alternative security authentication routine.
See the Parameter List.
0
 User ID and Password or password phrase have been accepted.
4
 Reject logon with a message to the user.
8
 Prompt the user to enter a new password or password phrase.
12
 Continue with signon and send the message when signon is complete.
You can use this call to provide your own security algorithm. This call is made if the value of the Security system field in the system options table is USER and no override was found in the user's UINDEX record. The call will also be made if the UINDEX record indicates that a value of USER was set by the pre-security exit or was specified in the Security system field in User Maintenance.
Post-security
Determines what action to take if the security mechanism rejects the signon request.
See the Parameter List.
0
Continue with the rejection signaled by the security package or by the function.
4
Continue with the rejection, but display your own message.
8
Ignore the rejection and permit normal signon to continue.
12
Ignore the rejection and permit normal signon to continue and send message when signon is complete.
16
Switch to the system named by the affinity parameter
This call is made only if the security mechanism has not authorized the user to use this product and has not reprompted the user. You can take further action to decide whether or not the user is allowed to continue.
The return codes are arranged in an order that ensures that omitting this exit and substituting a dummy exit with all the return codes set to zero will not affect the normal operation of the security mechanism.
If you use this exit to cause an Affinity switch to another system, make sure that an invalid user ID does not cause a loop, being rejected and switched repeatedly.
Get Profile (20)
Requests a model profile.
See the Parameter List.
0
Use the profile name currently in the standard parameter list to build a profile for the user.
4
Reject the signon with the message supplied.
8
Use the default dynamic user profile in the systems options table.
12
The exit has issued ADDPROF statements to build the user, or user-level or profile-level profile selection is being used, as shown in the sample exit TPXUSNSF.
16
Switch to the system named in the affinity parameter.
This call is made if a user entry has been dynamically built. A UINDEX entry is built for all users that are not known to this product if the Dynamic Users Allowed field in the system options table is set to Y. On exit, if return code 0, 8, or 12 is used, the specified profile must already be defined in profile maintenance. This exit could determine that a switch to another system will take place and avoid unnecessarily building a profile for a dynamically added user.
Alter Profile (24)
Updates the user profile.
See the Parameter List.
0
Continue to switch systems if either the parameter list or UINDEX implies switching.
4
Inhibit any implied switching.
8
Continue with signon and send the message when signon is complete.
12
Reject the signon with the supplied message.
This function is always called and allows you to further tailor a user's profile. UIDXPTR points to the chain of the user's application entries. You can use UENTNEXT to chain through to the next entry. When the call is completed, any implied switch to another CA TPX will take place unless inhibited by a suitable return code. The supplied parameter list will be inspected before the UIDXOWN field to determine the name of the destination system.
Affinity Failure (28)
Recovers from the situation in which the target system is not accepting logons at the time of the switch.
See the Parameter List.
0
Continue as if no switch was requested.
4
Reject the signon with the message supplied.
12
Continue as if no switch was requested but issue a message when signon is complete.
16
Attempt to switch again using the value in the parameter list. If parameter list value is blank, use the value in UINDEX.
20
Go back to just after pre-security point and issue the security system call.
This call is made if a switch request is rejected because the destination CA TPX or Access is unavailable or not accepting logons. You can use this call to determine what action is to be taken. If continue is requested, the signon process will continue as if the switch request was never made.
The processing logic of subsequent exits can cause this exit to be called more than once. The continue request will only apply to the switch attempt that failed. Any subsequent calls must take the appropriate action.
Signoff (32)
Processes signoff requests.
+0
Address of the user ID.
+4
Address of the UINDEX record.
0
Always
This exit point can be used to clean up any user indicators previously set in the signon entry points. Any ENQs issued can be dequeued. All UINDEX and UENTRY control blocks will be deleted unless either the Keep ACB or the Propagate ACB field in user maintenance is set to Y. The control blocks are deleted after the user's last active session has been terminated. If the user signs off and then signs on again before the sessions have been terminated, the control blocks will not be deleted.
Shutdown (36)
Closes down the security facility.
N/A
0
Always
Any files opened by the security facility can be closed prior to termination. This exit is called in all normal and most abnormal termination situations. The exit cannot be called when the software is not notified of a failure such as CP failure or abends. The exit will not be called if the security subtask ONOFF abnormally terminates.
Signon complete (40)
Indicates that signon processing has been completed.
+0
Address of the user ID
+4
Address of the Password or password phrase
+8
Address of the new password or password phrase
+12
Address of the UINDEX record
0
Always
This exit can be used to generate commands internally to be issued to CA TPX through the $COMMAND macro.
Terminal Lock (44)
Allows you to change the lockword to be something other than the user's password.
+0
Address of the user ID
+4
Address of the Password
0
Lockword not changed
4
Lockword changed
Terminal Unlock (48)
Allows you to determine how CA TPX reacts when the user attempts to unlock a locked terminal.
+0
Address of the user ID
+4
Address of the Password
+8
Address of the Password entered by the user
0
No change
4
User exceeded password retries, issue /F
8
User exceeded password retries, issue /K
12
User exceeded password retries, issue /F and inactivate sessions
16
User exceeded password retries, issue /K and inactivate sessions
Terminal Unlock (52)
Allows you to determine how CA TPX reacts when the user attempts to unlock a locked terminal for Password, Password Phrase, and Passcode users.
+0
Address of user ID
+4
Address of Password
+8
Address of Password entered by user.
0
No change
4
User exceeded password retries, issue /F.
8
 User exceeded password retires, issue /K
Parameter List
Most of the security function calls are associated with a standard parameter list. The startup and shutdown calls have no parameter list at all, and the value of R1 is unpredictable.
The standard signon parameter list consists of the following:
  • + 0
    Address of 8-byte user ID
  • + 4
    Address of 8-byte password or password phrase
  • + 8
    Address of 8-byte new password, new password phrase or blanks
  • +12
    Address of 8-byte terminal name
  • +16
    Address of 8-byte application name
  • +20
    Address of 8-byte model profile name
  • +24
    Address of 8-byte affinity name
  • +28
    Address of signon 3270 data stream
  • +32
    Length of 3270 data stream
  • +36
    Address of 20-byte user data field
  • +40
    Address of UINDEX record, except for call points 0, 4, and 36
  • +44
    Address of security system control record or 0
  • +48
    Address of the first of four contiguous 80-byte message lines
  • +52
    Address of second 80-byte message line
  • +56
    A token to be used for panel and variable processing
  • +60
    Address of VSAM user record or 0.
General Notes About the Parameter List
The following notes are general information about the parameter list:
  1. This parameter list is delivered for function codes 4 through 28, although not every parameter is delivered for every function.
  2. The profile name will always be blank. If any of the function calls change the value of this field, the change will be remembered and passed to the get profile call point. If the value is not altered at this time, that model will be used to build the user's profile.
  3. The user data field is reserved.
  4. The application name is the name of the primary ACB.
  5. If Security System=User, the user signon and signoff exit can use the security record address as a suitable pointer to its own security record, but the user must delete the security record before the signon process is completed.
  6. There are four contiguous 80-byte message lines. They can all be accessed from the address of the first one. Even though there are return codes at some call points to display messages, they are not necessary. The presence or absence of text in these fields determines whether a message will be displayed.
  7. Use blank spaces, not zeros, to clear the password, password phrase or message line fields.
  8. Passwords and Password Phrases are passed to this exit either encrypted or unencrypted depending on the setting of the field titled "Keep Pswds Encrypted" on the TEN0090 System Options Table Detail Panel.
When a site uses the TEN1003 signon panel (Set by the "Default LOGO" parameter on the TEN0108 System Options Table Detail Panel.) then users can sign on to TPX with either a password or password phrase depending on how the userid has been defined by security.
Password Phrases generally are passed to this exit in the following format:
Bytes
Meaning of the Password Phrase control block field
0
X'FF' - Password Phrase control block ID
1
Length of the Password Phrase. Valid values are X’00’, X'09' - X'64'
2 - 101
Password Phrase where the unused part of the field contains blanks.
The Signon data (4) call to TPXUSNSF can receive a password phrase that is not prefixed by X’FF’ (password phrase control block ID) and a 1 byte lenth field. It occurs when the parameter "Keep Pswds Encrypted" is set to "N". These calls to TPXUSNSF occur before TPX has parsed the password or new password variable. When the 100 byte buffer is passed to the exit then the exit must figure out whether it has received a password or a password phrase.
Parameters Passed for Specific Function Calls
Some parameters are passed in certain function calls but not in others. The following table shows which parameters are passed for each function call:
Function Call
Parameters
Function Code: 4
Function Code: 8
Function Code: 12
Function Code: 16
Function Code: 20
Function Code: 24
Function Code: 28
Sign on data (user ID, password, or password phrase and new password or password phrase)
P
P
P
P
P
P
P
Application Name
P
P
P
P
P
P
P
User data area returned by the invoked security system *
N
N
N
S
S
S
S
Name of the user's model profile
P
P
P
P
P
P
P
ID of the user's terminal
P
P
P
P
P
P
P
UINDEX Address
N
P
P
P
P
P
P
Addresses of the message areas
P
P
P
P
P
P
P
Name of the system to which control is passed (Affinity)
N
P
P
P
P
P
P
Address of the symbol used by a DISPLAY macro
P
P
P
P
P
P
P
Address of the user record image from ADMIN2
N
D
D
D
D
D
D
* RACF and CA Top Secret return ACEE, and CA ACF2 returns LIDREC
Code
Definition
P
Parameter is passed
N
Parameter is not passed
S
Will be zero (0) if SECURE is set to TPX, NONE, or USER. Otherwise, it will have an address.
D
Will be one of the following:
Zero (0) if either the user has no records on ADMIN2, or the following is true: the Dynamic Users Allowed field is set to Y and the Save Dynamic Users field is set to N.
Zero (0) only the first time the user signs on if the Dynamic Users Allowed field is set to Y and the Save Dynamic Users field is set to Y.
Parameters That Can Be Modified
Some parameters can be modified in certain function calls but not in others. The following table shows which parameters can be modified for each function call:
Function Call Parameters
Function Code: 4
Function Code: 8
Function Code: 12
Function Code: 16
Function Code: 20
Function Code: 24
Function Code: 28
Sign on data (user ID, password or password phrase, and new password or password phrase)
Y
N
N
*
*
*
*
Application Name
N
N
N
N
N
N
N
User data area returned by the invoked security system *
*
*
*
N
N
N
N
Name of the user's model profile
Y
Y
Y
Y
Y
*
Y
ID of the user's terminal
N
N
N
N
N
N
N
UINDEX Address
*
P
P
P
P
P
P
Addresses of the message areas
Y
Y
Y
Y
Y
Y
Y
Name of the system to which control is passed (Affinity)
*
Y
Y
Y
Y
Y
Y
Address of the symbol used by a DISPLAY macro
N
N
N
N
N
N
N
Address of the user record image from ADMIN2
N
N
N
N
N
N
N
Code
Definition
Y
Parameter can be modified
N
Parameter cannot be modified
P
Part of the parameter cannot be modified
*
Not applicable
Multitasking
All of the signon and signoff exit calls, except for code 40, are made from the CA TPX security subtask ONOFF, so there are no user multitasking considerations. Users can issue ENQ DEQ or I/O macros without worrying about which task is associated with the request.
Signon Function
The signon process is serialized in such a way that after the signon data call point has been entered, the signon function will not be entered for any other user until the request has been completed (function call 24), rejected (function call 16 return code 0), or a new password or password phrase has been requested (function code 12 return code 8 or the appropriate RACF, CA Top Secret, or CA ACF2 return code).
Abend in ONOFF or the User Exit
In the event of an Abend in ONOFF or the user exit, the subtask is not terminated. All acquired storage remains available, but the task is restarted. If the initialization call is driven a second time, the user must either delete and restart or check the validity of the data.
Session Portability
When a user signs on to a terminal while sessions are active at another terminal, care must be taken, especially in the signoff function call. The session is not transferred until the signon process is complete, and the user is not linked to the new terminal until the signoff process has completed.
During signon, you can detect whether a user has active sessions on another terminal by inspecting the value of UINDEX field UIDXTERM. If UIDXTERM is not 0, it is pointing to the Session Block of the terminal currently associated with this user. The terminal LUNAME is located at offset +6 from this address. The signoff function call will occur sometime after the signon call for the new terminal, but other signon or signoff calls for other terminals or users can occur between the last signon call for the new terminal and the signoff call for the old. To help you correlate these calls, CA TPX reserves a field UIDXUSER in the UINDEX for use by the signon exit.
ADDPROF Macro
This macro is used to build user profiles in memory by copying all of the information from the specified profile to the user definition. Multiple ADDPROF macros can be used to build a single user definition. The user-specific information specified in the first profile is used to build the UINDEX control block. For every subsequent ADDPROF issued, only the session records are added or replaced in the user's definition in memory.
If the return code is a number other than zero (0), the profile was not found. Be sure to code the list so that it takes the appropriate action if this occurs.
  1. This macro should be issued at the Get Profile call point (call point 20) of TPXUSNSF. If the macro is issued at any other call point, the results are unpredictable.
  2. This macro will modify the contents of registers 14, 15, 0, and 1.
Format of the ADDPROF Macro
The format of the ADDPROF macro is:
ADDPROF UINDEX=,NAME=,PARMLST=
where:
  • UINDEX
    Contains the address of the UINDEX record
  • NAME
    Contains the address of the profile name
  • PARMLST
    Contains the address of the parameter list that is passed to TPXUSNSF in register 1
Affinity Processing
At a number of points throughout the signon process, you can request that the signon process be terminated and a switch be made to PASS the terminal to another CA TPX. By default, this decision is made after the alter profile call based on the value found in UIDXOWN. Switch requests made in the TPXUSNSF exit will override the default Affinity setting in the System Options Table (SMRT). The switch requests allow an installation to recognize that a switch will take place and to make the switch event earlier in the signon to avoid unnecessary processing in this system.
After being switched, complete signon processing takes place in the destination system. One reason for providing this flexibility is to allow you to determine heuristically, based on some selection criteria, which system is to support this user. Because this process can set up a never-ending loop of switches, you should include a mechanism to guard against such an occurrence.
The address of the 8-byte C Affinity name is contained in +24 of the parameter list. The user must place the application ID in the specified address. When the call point is entered, this product will have placed blanks in the address.