Authentication Types
5.11. ASIS/AM Interaction—Tasks
5.11.4. Authentication Task
The authentication task is unique in that it can be segmented into a series of distinct steps called actions. Each action request from ASIS to AM advances the
authentication until an impasse condition is reached or until the authentication is complete. Each action request can be carried out by a different processor activity.
When an AM is called with an action related to a single authentication, the parameter identifies a structure referred to as the Authentication Request Context Block (ARCB).
This structure is important and relatively complex, and it is discussed separately from the actions that employ it.
Following is a list of each authentication action:
• returnUID
• initiateAuthentication
• delayComplete
• eventOccurred
• responseReceived
• abortAuthentication
• handleContingency
5.12. ARCB
The ARCB is initialized at the start and persists throughout an authentication. It is located in shared memory and is visible to all ASIS activities. All data relating to an authentication process that is to carry over between successive AM calls must be held in this structure or in shared memory containers that can be located using information (in other words, pointers) held in this structure. This is because the successive calls (usually a minimum of two) is generally performed by different processor activities.
The ARCB structure provides both fixed and modifiable data. An AM must never modify fixed data. An AM may, and in some cases is expected to, alter modifiable data.
The fixed-data area contains a bool variable (terminateAuthentication) for signaling an AM that an authentication is to be terminated. The value of this variable may change asynchronously (for example, as a result of a terminal timeout or communication path failure). The AM should check its value upon entry, and may check it at any time (for example, before exit). The fixed-data area also includes several bufferDescriptor variables (see 5.5). Each bufferDescriptor identifies a container holding a specific kind of authentication information. Whether or not a buffer contains information is a function of the type and current state of the authentication in question.
This structure is defined as ARCB in AM/H. The ARCB is organized into a fixed area (AM may read only) and a modifiable area (AM may read and write) as listed in Table 5–6 and Table 5–7.
In Table 5–6, the following items are not meaningful on the returnUID request action; ASIS supplies them on later calls for the same authentication request (initiateAuthentication action, unless otherwise specified).
• authenticationType
• initializedADA
• sizeADA
• UIA
• ADA
• terminalResponse
• cgypkt
Table 5–6. ARCB Fixed Data
Flag Array Description
int version ARCB version. This is the lowest ARCB version
supported by ASIS, currently 0. Version 1 was introduced in User Authentication 3R1 and version 2 was introduced in User Authentication 3R3.
bool debugMode TRUE if the debug mode (see 5.16) was in effect
when ASIS created this context block.
bool traceMode TRUE if the tracing mode (see 5.16) was in effect when ASIS created this context block.
bool singleMode TRUE if the single-thread mode (see 5.16) was in effect when ASIS created this context block.
enum action_t
requestAction Request action qualifies the callAMi( ) function call to let the AM know what action ASIS is requesting it to take for this authentication. It is from the set {initiateAuthentication, abortAuthentication, returnUID, handleContingency, delayComplete, responseReceived, and eventOccurred}.
int task_t
taskID Unique identifier assigned to this authentication by the Exec and ASIS.
enum xmode_t
executionMode {demand ,TIP, batch, API} .. type of execution according to the Exec. Batch defined for
completeness but currently never given to ASIS or the AM. API reflects the request was received through the User Authentication API AUTH_USER.
The caller of AUTH_USER could be batch, demand, or TIP.
enum category_t
signonCategory {withToken, withoutToken, outputOnlyTIP, withoutTokenAuthAPI}
enum retryContext {initial, retry, retryIgnore} .. respectively mean initial authentication request for this session, repeat of a previous authentication for which the AM had returned authenticationRetry status, repeat of a previous authentication where Exec ignores ASIS/AM results because of hacker frustration.
bool subsequentAuthenticatio
n Set to true by ASIS if there was a previous authentication during the same demand session, and allowMultipleAuthentications (see Table 5–7) was enabled on the last authentication that passed.
char siteID[ ] A 6-character left-justified, space-filled, ASCII site-id from the Exec (RSI only).
int PID PID number (TIP only).
int applicationGroupNumber Application group number (TIP only).
Table 5–6. ARCB Fixed Data
Flag Array Description
char applicationGroupName[ ] A 6-character ASCII symbolic name of the application group (TIP only).
int authenticationType Authentication type (0–63) of this user (from UIA).
Not used for deferredUID.
bool initializedADA Set to false by ASIS if ADA allocated but not yet written. Not used for deferredUID.
size_t sizeADA Current size of this user’s ADA. Not used for
deferredUID.
bool terminateAuthentication Set true asynchronously by ASIS if authentication terminates (for example, session closed).
ATIDescriptor_t ATI Describes the buffer containing ATI.
bufferDescriptor_t UIA Describes the buffer containing UIA. See 5.12.2. Not used for deferredUID.
bufferDescriptor_t ADA Describes the buffer containing ADA. See 5.12.3.
Not used for deferredUID.
responseDescriptor_t solicitResponse Describes the buffer containing response to the ELMS user-id/password solicit ASIS issues for without-token sign-ons. See 5.17.4.
tokenDescriptor_t token Describes the buffer containing the token/ticket for with-token sign-ons. See 5.17.5.
responseDescriptor_t terminalResponse Describes the buffer containing the last terminal input requested by the AM. Supplied on
responseReceived action and then left as residue on any subsequent calls for the same sign-on. A second terminal input acquires a new terminal response buffer whose descriptor replaces the first one, but the first terminal response buffer is not released. See 5.12.4.
bufferDescriptor_t AMInitData Describes the buffer containing a copy of AM initialization data. See 5.12.6.
bufferDescriptor_t AMWorkData Describes the buffer allocated by ASIS for AM to use as scratch space during this authentication. See 5.12.7.
bufferDescriptor_t cgypkt Describes the buffer containing a contingency packet (CGYPKT1). Only supplied with the handleContingency action. See 5.12.8.
Note: Any illegal value the AM returns to ASIS in this modifiable area of the ARCB is reset to its initial value (default) by ASIS, except for Boolean expressions for which any nonzero value is converted to TRUE.
Table 5–7. ARCB Modifiable Data
Flag Array Description
enum reason_t
execErrorType Qualifies authenticationFail or authenticationRetry callReturnStatus, but is ignored with any other status. It indicates whether any console, terminal message, or log entry the Exec may generate should indicate INVALID PASSWORD or INVALID AUTHENTICATION DATA. It is from the set {badPassword = 2, badAuthenticationData = 3} and is initialized to badAuthenticationData when ASIS calls the AM.
Note: If inhibitExecErrorMessage is TRUE (see below), the Exec does not display any message at the user terminal. This item, however, still qualifies any log entry the Exec may write.
bool inhibitExecErrorMessage If TRUE, the Exec does not display its INVALID PASSWORD, INVALID AUTHENTICATION DATA, or INVALID USER-ID messages on the user’s
terminal, regardless of the Security-Admin configuration and status returned from the AM.
This allows the AM complete control over what appears at the terminal if required, but the Exec still writes the appropriate log entry and console message. Defaults to FALSE. The AM may set it TRUE for any callReturnStatus, but it is especially important for authenticationFail or
authenticationRetry because of execErrorType (see above).
char userID[ ] A 12-character, left-justified, space-filled ASCII, user-id returned by AM for the returnUID
requestAction. Not treated as NULL terminated. If using the deferredUID method, this field is left blank on a returnUID and filled in later by the AM on authenticationPass.
bool writeSessionKey Set true by AM if sessionKey is to be saved in SKEY in user profile. Only meaningful if the callReturnStatus from the AM is
authenticationPass. Initialized to false by ASIS.
char sessionKey[ ] A 16-byte binary session key value returned by AM. Not treated as NULL terminated by ASIS or the Exec. Only meaningful if the callReturnStatus from the AM is authenticationPass.
Table 5–7. ARCB Modifiable Data
Flag Array Description
bufferDescriptor_t updatedADA Describes buffer containing new ADA contents AM wants written to user’s record. May be NULL.
May point to same location as ADA. Size component of updatedADA cannot exceed the maximum ADA size (3404 bytes). If it does, it is not written to the security database. If pointer component is not NULL, ASIS updates the ADA in the security database even if the size component is 0. ASIS does not release the buffer if it belongs to the AM. Not used for deferredUID.
bool logADA Set true by AM if ADA update (see updatedADA)
is to be logged. Initialized to false by ASIS. Not used for deferredUID.
int waitInterval Time to wait (milliseconds) when callReturnStatus is waitTime.
enum clearanceOption Used by AM to indicate whether the user should receive a default or specific clearance level, or neither (let the Exec decide). From the set {nullSelection, defaultClearance,
specifiedClearance}. Only meaningful if the callReturnStatus from the AM is
authenticationPass. Initialized to nullSelection by ASIS.
int clearanceLevel Numeric clearance level supplied by AM if clearanceOption is specified Clearance.
bool inhibitAutoRunCard Set to true by AM to inhibit automatic run card generation by the Exec. Equivalent to asterisk on traditional demand user-id/password. Only meaningful if the callReturnStatus from the AM is authenticationPass. Initialized to false by ASIS.
bool allowMultipleAuthentications Set to true by AM to allow multiple sign-ons during this session. Only meaningful for demand and if the callReturnStatus from the AM is authenticationPass. If returned false on a demand authentication that passes, then the session closes when the user @FINs. Initialized to true by ASIS.
int highestARCBVersionASIS The highest ARCB version supported by ASIS, currently 1. It is in the modifiable AR area only so it could be added at the end, making it unnecessary for existing AMs to recompile.
int lowestARCBVersionAM The lowest ARCB version supported by the AM. It is initialized by ASIS to 0. It may be changed by an AM to reflect the lowest ARCB version it wishes to support.
Table 5–7. ARCB Modifiable Data
Flag Array Description
int highestARCBVersionAM The highest ARCB version supported by the AM. It should be set by the AM to the highest version it supports to inform ASIS.
int detailedAuthStatus An integer reflecting the detailed reason for an authentication failure. Used only for detailed status returned by AUTH_USER and for log entries. Must be a value from
apimessage/h. This field is recognized by ASIS only if the AM specifies it supports ARCB version 1 by setting highestARCBVersionAM to 1.
bufferDescriptor_t networkUserid Describes a buffer containing the network user-id if a network user-id was authenticated. The network user-id is in Unicode. This field is recognized by ASIS only if the AM specifies it supports ARCB version 1 by setting
highestARCBVersionAM to 1.
int detailedAuxStatus An integer providing auxiliary detailed status for an authentication failure. Used only for detailed auxiliary status returned to privileged API callers if AUTH_USER packet version 1 or higher is used.
Only present in version 2 or higher ARCBs.
char requestorRunid The run-id of the requestor if this request is from the AUTH_USER() or AUTH_CONTEXT() APIs.
char requestorUserid The user-id of the requestor if this request is from the AUTH_USER() or AUTH_CONTEXT() APIs.
char requestorProgramName The program name of the requestor if this request is from the AUTH_USER() or AUTH_CONTEXT() APIs.
The following structures are associated with the ARCB, linked to it as variable size buffers, and pointed to from the ARCB fixed area. For example, ATIDescriptor_t is a type of buffer descriptor (pointer plus data length) pointing to the ATI.
5.12.1. ATI
This structure is defined as ATIDescriptor_t in AM/H. In Table 5–8, terminalAddress is of the format listed in the Terminal Address segment of the table. This structure is defined as terminalAddress_t in AM/H.
Table 5–8. Additional Terminal Information
Flag Array Description
Additional Terminal Information
unsigned short int version ATI packet version (from SILAS) is currently 1.
enum protocol_t
transportProtocol {DCA = 1, TCPIP = 2, OSI = 3, TELNET =4}
enum outbound_t
outboundOpen {inbound = 0, outbound = 1}
enum valid_t
validation {standardTerminal = 0, autoValidate = 1}
terminalAddress_t siteID Site-id, if any, supplied by SILAS for the terminal.
terminalAddress_t IPAddress Internet Protocol terminal identifier, if any, supplied by SILAS for the terminal.
terminalAddress_t otherID Other type of terminal-id. This allows drivers to provide another form of terminal address besides site-id or IP address.
Note: SILAS supplies site-id and IP address only (IPv4 or IPv6). This field is available for future expansion.
Terminal Address
unsigned short int addrType See the addrType values in Table 5–9.
unsigned short int length Length (in bytes) of the address in contents.
char* contents Pointer to the address contents. For a siteID, the contents are ASCII characters. For an IPAddress, the contents are a series of binary segment numbers (typically x.x.x.x).
Values for addrType were previously defined as listed in Table 5–9.
Table 5–9. AddrType Values
Octal Range Purpose Current Values
Defined
Purpose
0–077777 Kerberos types 02
012 Internet Protocol version 4 Internet Protocol version 6
Octal Range Purpose Current Values
Defined
Purpose
0100000–0177777 Unisys types 0100000 Site-id
0200000–0277777 Site Local types None
For the convenience of AM developers coding in C, the preprocessor labels for terminal address types and ranges are #DEFINEd in the Unisys supplied header files and listed in Table 5–10. AddrType_Internet (02) and addrType_SiteID (0100000) are the two values used in the addrType subfield of IPAddress and siteID.
Table 5–10. Address Types and Ranges
Address Type Address Range
addrType_Kerberos 0
addrType_Internet addrType_Kerberos + 02 addrType_IPv6 addrType_Kerberos + 012
addrType_Unisys 0100000
addrType_SiteID addrType_Unisys + 0 addrType_SiteLocal 0200000
Note: The ATI is not present unless the communications driver supports this feature. SILAS supplies the Additional Terminal Information.
5.12.2. UIA
The most important item in the UIA to the AM is authentication type, so it is extracted by ASIS and placed separately in the ARCB fixed area. Any other UIA data must be extracted by the AM itself. The C header files do not include UIA structures
.
Note: This is a copy of the UIA as it appeared just before ASIS called the AM to request initiateAuthentication. It is not guaranteed to remain current. This area is not used for deferredUID.
5.12.3. ADA
The format of the ADA buffer is determined by the AM. When ASIS calls the AM with the initiateAuthentication function, this is a copy of the ADA as it currently appears in the user’s security database record. This copy of the ADA is guaranteed to remain current only if the AM serializes authentications for this authentication type
(serializeUserID in AICB). The AM can update the ADA, but ASIS writes the update to the security database only if updatedADA (in the ARCB Modifiable Area) is also updated by the AM.
This areas is not used for deferredUID.
If the following conditions exist, a new ADA is created with the supplied data:
• An ADA does not exist at the time of the call
• The AM registered for a nonzero defaultADA size
• A new ADA is passed to ASIS and sets the updatedADA ARCB flag Solicit Response
This is the raw response from the ELMS user-id/password solicitation that ASIS performs on sign-ons without tokens. It is in the same format as a generic terminal response (see 5.11.4).
Note: The AM can be designed to process responses in a non-ASCII character set (for example, Kanji). This is technically possible because characterSetis one of the fields provided in the terminal response buffer; however, there is a risk if ASIS is down when the non-ASCII terminal attempted to sign on or if the AM declined the sign-on. In this case, the response is sent to the Exec for processing and the Exec does not process a user-id/password response properly if it is not ASCII. Non-ASCII terminals are treated as invalid sign-on attempts by the Exec, typically resulting in an “Invalid User-id” error message at the terminal, plus log entry, console message, hacker frustration, and so forth, whenever ASIS is unavailable or the AM declined.